Merge pull request #3 from vitry/fix/plugin-data-root

fix: bootstrap stable plugin data root

Author: vitry

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes follow Semantic Versioning.
 
+## Unreleased
+
+- Fixed installed `$zcode:*` skills failing with `DATA_ROOT_REQUIRED` when Codex does not inject `PLUGIN_DATA` into ordinary skill commands.
+- Added marketplace-qualified plugin-data discovery and a restart-safe `$zcode:setup` bootstrap that configures the data directory as a writable root before persisting state.
+
 ## 0.1.0 - 2026-08-06
 
 - Added eight native `$zcode:*` skills for review, adversarial review, Rescue, Transfer, job inspection, cancellation, and setup.

README.md

@@ -17,7 +17,7 @@ codex plugin marketplace add vitry/zcode-plugin-codex --ref marketplace
 codex plugin add zcode@vitry
 ```
 
-The release workflow builds `.agents/plugins/marketplace.json` plus `plugins/zcode/` with production dependencies on that branch. Restart Codex after installation, then run `$zcode:setup` in the target workspace. Do not copy hooks out of the installed plugin cache.
+The release workflow builds `.agents/plugins/marketplace.json` plus `plugins/zcode/` with production dependencies on that branch. Restart Codex after installation, then run `$zcode:setup` in the target workspace. On the first run, setup may add the marketplace-qualified plugin data directory to Codex's writable roots; if it reports `restart-required`, restart Codex and rerun setup. Do not copy hooks out of the installed plugin cache.
 
 Discovery checks `ZCODE_PATH`, `zcode` on `PATH`, platform locations, and on macOS the bundled `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs`. Setup reports missing, outdated, unauthenticated, or untrusted installations; it does not download ZCode or sign in for you.
 
@@ -47,7 +47,7 @@ codex
 # In the Codex session: $zcode:setup
 ```
 
-Setup persists `${PLUGIN_DATA}/workspaces/<workspace-hash>/config/models.json` with this schema:
+Setup persists `$CODEX_HOME/plugins/data/zcode-<marketplace>/workspaces/<workspace-hash>/config/models.json` (the hook-provided `PLUGIN_DATA` resolves to the same root) with this schema:
 
 ```json
 {"version":1,"defaultModel":"fast","models":{"fast":{"providerId":"provider","modelId":"model","variant":"optional"}}}
@@ -59,7 +59,7 @@ To verify configuration, rerun `$zcode:setup`, then run `$zcode:rescue --fresh -
 
 ## Jobs, Transfer, and review gate
 
-Every run is reserved as a durable, owner-scoped job. Plugin state lives beneath `${PLUGIN_DATA}/workspaces/<workspace-hash>/` with private permissions; prompts, results, session IDs, and logs are never written into the repository. `$zcode:status`, `$zcode:result`, and `$zcode:cancel` work across later turns in the same Codex session, while sibling sessions cannot adopt a job.
+Every run is reserved as a durable, owner-scoped job. Installed plugin state lives beneath `$CODEX_HOME/plugins/data/zcode-<marketplace>/workspaces/<workspace-hash>/` with private permissions; prompts, results, session IDs, and logs are never written into the repository or plugin cache. `$zcode:status`, `$zcode:result`, and `$zcode:cancel` work across later turns in the same Codex session, while sibling sessions cannot adopt a job.
 
 Transfer reads a persisted Codex thread through `codex app-server` and imports only ordered visible user/assistant text. It does not transfer hidden reasoning, tools, permissions, or ZCode job ownership.
 
@@ -72,6 +72,7 @@ The optional Stop review gate runs a bounded foreground read-only review only af
 - Authentication unavailable: authenticate with ZCode itself, then rerun setup.
 - Background work: use `$zcode:status <job-id> --wait`, `$zcode:result <job-id>`, or `$zcode:cancel <job-id>` exactly as reported.
 - Hook trust or restart required: let setup trust only this installed plugin's exact hook hashes, restart Codex, and rerun setup.
+- `plugin-data-root-added`: setup added the stable plugin data root to Codex configuration without writing plugin state; restart Codex and rerun setup.
 
 macOS with ZCode Desktop 3.6.5 and CLI 0.16.1+ is the release qualification target. Run `ZCODE_REAL_E2E=1 ZCODE_REAL_E2E_MODEL='provider/model' npm run test:qualified` on an authenticated machine before marking a release qualified. To include the installed-marketplace-to-real-Codex bridge, also set `ZCODE_CODEX_SKILLS_E2E=1`; this consumes authenticated Codex credits. Missing opt-in, authentication, model, or credits produces a structured `unqualified` skip, never a pass. An unknown execution failure remains a test failure. Linux and Windows are code-supported by fake-protocol CI, but are not real-CLI qualified yet.
 

README.zh-CN.md

@@ -17,7 +17,7 @@ codex plugin marketplace add vitry/zcode-plugin-codex --ref marketplace
 codex plugin add zcode@vitry
 ```
 
-发布 workflow 会在该分支生成 `.agents/plugins/marketplace.json` 和带生产依赖的 `plugins/zcode/`。安装后重启 Codex，再在目标工作区运行 `$zcode:setup`。不要把 hooks 从插件缓存复制到别处。
+发布 workflow 会在该分支生成 `.agents/plugins/marketplace.json` 和带生产依赖的 `plugins/zcode/`。安装后重启 Codex，再在目标工作区运行 `$zcode:setup`。首次运行可能把 marketplace 专属的数据目录加入 Codex writable roots；若返回 `restart-required`，重启 Codex 后再次运行 setup。不要把 hooks 从插件缓存复制到别处。
 
 插件依次检查 `ZCODE_PATH`、`PATH` 中的 `zcode`、平台目录，以及 macOS 内置路径 `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs`。Setup 会报告缺失、版本过低、未认证或 hook 不可信，但不会下载 ZCode，也不会代替用户登录。
 
@@ -47,7 +47,7 @@ codex
 # 进入 Codex session 后执行：$zcode:setup
 ```
 
-Setup 会把以下 schema 写入 `${PLUGIN_DATA}/workspaces/<workspace-hash>/config/models.json`：
+Setup 会把以下 schema 写入 `$CODEX_HOME/plugins/data/zcode-<marketplace>/workspaces/<workspace-hash>/config/models.json`（hook 注入的 `PLUGIN_DATA` 会解析到同一目录）：
 
 ```json
 {"version":1,"defaultModel":"fast","models":{"fast":{"providerId":"provider","modelId":"model","variant":"optional"}}}
@@ -59,7 +59,7 @@ Setup 会把以下 schema 写入 `${PLUGIN_DATA}/workspaces/<workspace-hash>/con
 
 ## 任务、Transfer 与 review gate
 
-每次运行都会先建立持久、带 owner 的 job。状态保存在 `${PLUGIN_DATA}/workspaces/<workspace-hash>/`，使用私有权限；prompt、result、session ID 和日志都不会写进仓库。后续 turn 仍可使用 `$zcode:status`、`$zcode:result`、`$zcode:cancel`，但 sibling Codex session 无法接管任务。
+每次运行都会先建立持久、带 owner 的 job。已安装插件的状态保存在 `$CODEX_HOME/plugins/data/zcode-<marketplace>/workspaces/<workspace-hash>/`，使用私有权限；prompt、result、session ID 和日志都不会写进仓库或插件缓存。后续 turn 仍可使用 `$zcode:status`、`$zcode:result`、`$zcode:cancel`，但 sibling Codex session 无法接管任务。
 
 Transfer 通过 `codex app-server` 读取持久 Codex thread，只导入按顺序排列、用户可见的 user/assistant 文本；不转移隐藏推理、工具状态、permission 或 job ownership。
 
@@ -72,6 +72,7 @@ Transfer 通过 `codex app-server` 读取持久 Codex thread，只导入按顺
 - Authentication 不可用：在 ZCode 自身完成认证，再重新 setup。
 - 后台任务：按输出使用 `$zcode:status <job-id> --wait`、`$zcode:result <job-id>` 或 `$zcode:cancel <job-id>`。
 - Hook trust / restart required：只让 setup 信任当前安装插件的精确 hook hash，重启后再次检查。
+- `plugin-data-root-added`：setup 只把稳定数据目录加入 Codex 配置，尚未写入插件状态；重启 Codex 后再次运行 setup。
 
 macOS + ZCode Desktop 3.6.5 + CLI 0.16.1+ 是发布资格目标。发布前应在已认证机器运行 `ZCODE_REAL_E2E=1 ZCODE_REAL_E2E_MODEL='provider/model' npm run test:qualified`。如需同时验证“已安装 marketplace → 真实 Codex → ZCode”桥接，还要设置 `ZCODE_CODEX_SKILLS_E2E=1`；该测试会消耗已认证 Codex 账户的额度。缺少 opt-in、认证、模型或额度时，测试只会给出结构化的 `unqualified` skip，绝不会算作通过；未知执行错误仍会让测试失败。Linux and Windows are code-supported but are not real-CLI qualified yet；两者当前由 fake-protocol CI 覆盖。
 

docs/superpowers/plans/2026-08-07-plugin-data-root-bootstrap.md

@@ -0,0 +1,100 @@
+# Plugin Data Root Bootstrap Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make installed `$zcode:*` skills resolve and bootstrap a stable writable plugin data directory when `PLUGIN_DATA` is absent.
+
+**Architecture:** Introduce a focused plugin-data path resolver, use it at every companion and hook entry point, and extend setup's existing Codex app-server configuration transaction to preserve and add the required writable root before any state write. Installed cache identity determines the marketplace-qualified namespace; source checkouts use an unqualified development namespace.
+
+**Tech Stack:** Node.js 22.13+ ESM, Codex app-server JSONL configuration API, Node built-in test runner, JSDoc/TypeScript checking, ESLint.
+
+---
+
+### Task 1: Resolve and bootstrap plugin data safely
+
+**Files:**
+- Create: `scripts/lib/plugin-data.mjs`
+- Modify: `scripts/zcode-companion.mjs`
+- Modify: `scripts/lib/codex-config.mjs`
+- Modify: `hooks/session-lifecycle-hook.mjs`
+- Modify: `hooks/user-prompt-hook.mjs`
+- Modify: `hooks/subagent-hook.mjs`
+- Modify: `hooks/stop-review-gate-hook.mjs`
+- Modify: `hooks/session-end-hook.mjs`
+- Modify: `tests/setup.test.mjs`
+- Modify: `tests/integration/marketplace-install.test.mjs`
+- Create or modify: `tests/plugin-data.test.mjs`
+- Modify: `README.md`
+- Modify: `README.zh-CN.md`
+- Modify: `CHANGELOG.md`
+
+- [ ] **Step 1: Write failing resolver tests**
+
+Cover explicit `ZCODE_DATA_ROOT`, validated injected roots, installed cache identity,
+marketplace-qualified fallback, source-checkout fallback, `CODEX_HOME`, symlink-equivalent
+paths, and rejection/ignoring of foreign injected roots.
+
+- [ ] **Step 2: Run the resolver tests and verify RED**
+
+Run: `node --test tests/plugin-data.test.mjs`
+
+Expected: FAIL because the shared resolver does not exist.
+
+- [ ] **Step 3: Implement the minimal shared resolver**
+
+Create `scripts/lib/plugin-data.mjs` with pure path/identity functions and a single
+`resolvePluginDataRoot({ env, pluginRoot })` public entry point. Do not create files in
+the resolver.
+
+- [ ] **Step 4: Run resolver tests and verify GREEN**
+
+Run: `node --test tests/plugin-data.test.mjs`
+
+Expected: PASS.
+
+- [ ] **Step 5: Write failing setup bootstrap tests**
+
+Exercise the real companion setup entry without `PLUGIN_DATA`. Assert that it derives
+the installed root, preserves existing `sandbox_workspace_write.writable_roots`, emits
+one version-checked `config/batchWrite`, returns `restart-required`, performs no plugin
+state write before restart, and honors an already-effective writable root on rerun.
+
+- [ ] **Step 6: Run setup tests and verify RED**
+
+Run: `node --test tests/setup.test.mjs tests/integration/marketplace-install.test.mjs`
+
+Expected: FAIL with the current `DATA_ROOT_REQUIRED` or missing writable-root edit.
+
+- [ ] **Step 7: Integrate resolver and setup bootstrap**
+
+Resolve the data root before companion routing. Reorder setup so Codex configuration is
+read and the writable root is installed before model or gate state is accessed. Preserve
+existing roots and user-layer version checks. Return restart guidance without writing
+state when the sandbox root has just changed or is overridden.
+
+- [ ] **Step 8: Use the resolver in hooks**
+
+Replace direct `process.env.PLUGIN_DATA` assumptions with the shared resolver so hooks
+and skills select the same root while retaining fail-closed hook behavior.
+
+- [ ] **Step 9: Run focused tests and verify GREEN**
+
+Run: `node --test tests/plugin-data.test.mjs tests/setup.test.mjs tests/hooks.test.mjs tests/integration/marketplace-install.test.mjs`
+
+Expected: PASS.
+
+- [ ] **Step 10: Update user-facing documentation**
+
+Document the derived plugin-data location, marketplace qualification, restart-required
+setup behavior, and the fact that state never lives in the repository or plugin cache.
+
+- [ ] **Step 11: Run the complete quality gate**
+
+Run: `npm run check`
+
+Expected: PASS with only the documented credential-gated E2E skips.
+
+- [ ] **Step 12: Self-review and commit**
+
+Run `git diff --check`, inspect the full diff for unrelated changes and secret/path
+leaks, then commit with a focused bug-fix message.

docs/superpowers/specs/2026-08-07-plugin-data-root-bootstrap-design.md

@@ -0,0 +1,58 @@
+# Plugin Data Root Bootstrap Design
+
+## Problem
+
+Installed `$zcode:*` skills run ordinary companion commands without a guaranteed
+`PLUGIN_DATA` environment variable. The companion currently rejects every command,
+including `$zcode:setup`, before setup can configure the environment. Codex documents
+`PLUGIN_DATA` for plugin hook commands, not as a guaranteed environment variable for
+ordinary commands launched from a skill.
+
+## Design
+
+Add one plugin-data resolver shared by skills, setup, and hooks. An explicit
+`ZCODE_DATA_ROOT` remains the test and operator override. Otherwise the resolver uses
+an injected `PLUGIN_DATA` or `CLAUDE_PLUGIN_DATA` only when it matches the active
+installed plugin identity. When no injected value is available, it derives a stable
+marketplace-qualified root from the canonical plugin cache path and `CODEX_HOME`:
+
+```text
+${CODEX_HOME:-~/.codex}/plugins/data/zcode-<marketplace>
+```
+
+A source checkout uses the unqualified development root:
+
+```text
+${CODEX_HOME:-~/.codex}/plugins/data/zcode
+```
+
+Workspace state remains isolated below `workspaces/<sha256-canonical-workspace>`.
+No state is written into the repository or plugin cache.
+
+## Setup bootstrap
+
+`$zcode:setup` must be able to run before the data root is writable. It reads Codex
+configuration first, preserves existing writable roots, and adds the resolved plugin
+data root through `config/batchWrite`. When the effective sandbox configuration changes,
+setup reports `restart-required` and defers state writes and review-gate changes until
+the user restarts Codex and reruns setup.
+
+When the root is already writable, setup continues with the existing ZCode discovery,
+authentication, hook validation/trust, model policy, and review-gate flow.
+
+## Safety
+
+- Canonicalize and validate cache-relative marketplace/plugin/version segments.
+- Reject control characters, traversal, and unexpected plugin identities.
+- Never accept an arbitrary injected `PLUGIN_DATA` path for an installed plugin.
+- Preserve existing writable-root configuration and detect higher-precedence overrides.
+- Keep private directory/file permissions and existing workspace hashing unchanged.
+- Hooks and skills must resolve the same data root.
+
+## Verification
+
+Add regression coverage proving an installed-style setup invocation without
+`PLUGIN_DATA` no longer returns `DATA_ROOT_REQUIRED`, derives the expected
+marketplace-qualified path, requests only the required writable-root edit, requires a
+restart before writing state, and succeeds after restart. Keep explicit data-root tests,
+hook tests, marketplace installation tests, and the full suite green.

hooks/session-end-hook.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // @ts-nocheck
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
 import { createIdentityStore } from '../scripts/lib/identity.mjs';
 import { ownerIdForSession } from '../scripts/lib/job-control.mjs';
+import { resolvePluginDataRoot } from '../scripts/lib/plugin-data.mjs';
 import { releaseManagedZCodeOwner } from '../scripts/lib/zcode-client.mjs';
 import { cleanupSession } from './lib/hook-state.mjs';
 import { readHookInput } from './lib/hook-input.mjs';
 
-try { const input = await readHookInput('SessionEnd'); const dataRoot = process.env.PLUGIN_DATA; if (!dataRoot) throw new Error('PLUGIN_DATA required'); await Promise.allSettled([releaseManagedZCodeOwner({ dataRoot, workspace: input.cwd, ownerId: ownerIdForSession(input.session_id), requestTimeoutMs: 750 }), cleanupSession(dataRoot, input.cwd, input.session_id), createIdentityStore({ dataRoot }).cleanupSession(input.cwd, input.session_id)]); }
+try { const input = await readHookInput('SessionEnd'); const dataRoot = resolvePluginDataRoot({ env: process.env, pluginRoot: resolve(fileURLToPath(new URL('../', import.meta.url))) }); await Promise.allSettled([releaseManagedZCodeOwner({ dataRoot, workspace: input.cwd, ownerId: ownerIdForSession(input.session_id), requestTimeoutMs: 750 }), cleanupSession(dataRoot, input.cwd, input.session_id), createIdentityStore({ dataRoot }).cleanupSession(input.cwd, input.session_id)]); }
 catch (error) { process.stderr.write(`ZCode session cleanup advisory failed: ${error?.code ?? 'HOOK_FAILED'}\n`); process.exitCode = 1; }

hooks/session-lifecycle-hook.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 // @ts-nocheck
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { resolvePluginDataRoot } from '../scripts/lib/plugin-data.mjs';
 import { readHookInput } from './lib/hook-input.mjs';
 import { recordSession } from './lib/hook-state.mjs';
 
-try { const input = await readHookInput('SessionStart'); if (!process.env.PLUGIN_DATA) throw new Error('PLUGIN_DATA required'); await recordSession(process.env.PLUGIN_DATA, input); process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'ZCode companion lifecycle is active for this parent session.' } })); }
+try { const input = await readHookInput('SessionStart'); const dataRoot = resolvePluginDataRoot({ env: process.env, pluginRoot: resolve(fileURLToPath(new URL('../', import.meta.url))) }); await recordSession(dataRoot, input); process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: 'ZCode companion lifecycle is active for this parent session.' } })); }
 catch (error) { process.stderr.write(`ZCode lifecycle hook failed safely: ${error?.code ?? 'HOOK_FAILED'}\n`); process.exitCode = 1; }

hooks/stop-review-gate-hook.mjs

@@ -12,6 +12,7 @@ import { ownerIdForSession } from '../scripts/lib/job-control.mjs';
 import { readJsonFile } from '../scripts/lib/fs.mjs';
 import { createStateStore } from '../scripts/lib/state.mjs';
 import { createIdentityStore } from '../scripts/lib/identity.mjs';
+import { resolvePluginDataRoot } from '../scripts/lib/plugin-data.mjs';
 import { resolveWorkspaceStorage } from '../scripts/lib/workspace.mjs';
 import { fingerprintWorkspace, finishGateRun, isForwarding, isOwnedSession, writeGateRun } from './lib/hook-state.mjs';
 import { readHookInput } from './lib/hook-input.mjs';
@@ -34,7 +35,7 @@ export async function runStopReviewGate(input, options) {
 }
 
 async function main() {
-  try { const input = await readHookInput('Stop'); const dataRoot = process.env.PLUGIN_DATA; if (!dataRoot) throw new Error('PLUGIN_DATA required'); output(await runStopReviewGate(input, { dataRoot, env: process.env })); }
+  try { const input = await readHookInput('Stop'); const dataRoot = resolvePluginDataRoot({ env: process.env, pluginRoot: root }); output(await runStopReviewGate(input, { dataRoot, env: process.env })); }
   catch (error) { output({ decision: 'block', reason: cap(`ZCode review gate failed safely (${error?.code ?? 'HOOK_FAILED'}). Run $zcode:setup, then retry the final check.`) }); }
 }