zcode-supervisor 0.0.1__py3-none-any.whl

zcode_supervisor-0.0.1.dist-info/METADATA

@@ -0,0 +1,928 @@
+Metadata-Version: 2.4
+Name: zcode-supervisor
+Version: 0.0.1
+Summary: Codex-side supervisor tooling for safely delegating bounded coding tasks to ZCode.
+Author: ZCode-supervisor contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AkiGarage/ZCode-supervisor
+Project-URL: Source, https://github.com/AkiGarage/ZCode-supervisor
+Project-URL: Issues, https://github.com/AkiGarage/ZCode-supervisor/issues
+Project-URL: Documentation, https://github.com/AkiGarage/ZCode-supervisor#readme
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+![ZCode Supervisor Toolkit hero](assets/images/zcode-supervisor-toolkit-hero.png)
+
+<p align="center">
+  <strong>Language / 言語</strong><br>
+  <a href="./README.md"><kbd>English</kbd></a>
+  <a href="./README.ja.md"><kbd>日本語で読む</kbd></a>
+</p>
+
+# ZCode-supervisor
+
+![Version](https://img.shields.io/badge/version-v0.0.1-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Node](https://img.shields.io/badge/node-%3E%3D22-339933)
+![Python](https://img.shields.io/badge/python-%3E%3D3.11-3776AB)
+
+Codex-side tooling for using ZCode as a bounded coding worker while Codex stays
+the orchestrator and final auditor.
+
+**日本語版はこちら:** [README.ja.md を開く](./README.ja.md)
+
+This repository is not affiliated with Z.AI or ZCode.
+
+## Quick Start
+
+The current public setup path is `uvx` from this GitHub repo:
+
+```bash
+uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+  zcode-install-repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+```
+
+After the first PyPI release, the shorter package command will be:
+
+```bash
+uvx --from zcode-supervisor zcode-install-repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+```
+
+Then check the routing decision before the first delegated task:
+
+```bash
+zcode-auto-route \
+  --workspace /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO \
+  --objective "setup smoke check"
+```
+
+For development from source, clone this repo and run the underlying Python
+command directly:
+
+```bash
+git clone https://github.com/AkiGarage/ZCode-supervisor.git
+cd ZCode-supervisor
+python3 tools/zcode_supervisor/zcode_supervisor.py install-repo \
+  --repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO \
+  --write-agents
+```
+
+The Homebrew tap is archived for now; clone `AkiGarage/ZCode-supervisor` for
+source work.
+
+Release details and verification commands are in
+[docs/distribution.md](docs/distribution.md).
+
+## Ask Codex To Set It Up
+
+If you want Codex to do the setup for you, copy this whole prompt into Codex.
+GitHub shows a copy button on the code block. Replace
+`/ABSOLUTE/PATH/TO/YOUR/TARGET_REPO` with the absolute path to the repo you want
+ZCode to help edit.
+
+```text
+You are Codex. Please set up ZCode-supervisor for this target repo:
+
+TARGET_REPO=/ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+
+Goal:
+Make this target repo ready for the ZCode-supervisor workflow where Codex keeps
+planning, orchestration, validation, audit, recovery, and final acceptance, and
+ZCode only performs bounded implementation through zcodectl run-packet.
+
+Rules:
+- Be careful and non-destructive.
+- Do not read or print secrets, .env files, credentials, API keys, private keys,
+  or token files.
+- Do not edit application source code in the target repo during setup.
+- If TARGET_REPO is still a placeholder, stop and ask me for the real absolute
+  path.
+- If a required app or tool is missing, stop with the exact missing prerequisite
+  and the next command or official link I should use.
+- Do not push, commit, delete branches, or change production behavior.
+
+Steps:
+1. Confirm TARGET_REPO exists and is a git repository.
+2. Prefer the public GitHub-backed `uvx` path. If `uvx --version` works, set
+   INSTALLER_MODE=uvx and do not clone anything. If `uvx` is missing, show this
+   official install link and continue with the source fallback:
+   https://docs.astral.sh/uv/getting-started/installation/
+3. For source fallback only, find this ZCode-supervisor repo locally. Prefer
+   ~/dev/ZCode-supervisor if it exists. Set SUPERVISOR_REPO to the real absolute
+   path. If it is not present, clone it with:
+   mkdir -p ~/dev
+   git clone https://github.com/AkiGarage/ZCode-supervisor.git ~/dev/ZCode-supervisor
+   If clone fails, stop and report the exact error.
+4. Verify local basics:
+   - node --version must be >= 22
+   - python3 --version must be >= 3.11
+   - git --version must work
+5. Verify ZCode is installed or give me this official install link:
+   https://zcode.z.ai/en/docs/install
+6. Run the target repo installer from Terminal or shell. If INSTALLER_MODE=uvx:
+   uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+     zcode-install-repo "$TARGET_REPO"
+   Otherwise run the source fallback:
+   python3 "$SUPERVISOR_REPO/tools/zcode_supervisor/zcode_supervisor.py" install-repo \
+     --repo "$TARGET_REPO" \
+     --write-agents
+7. Verify these files now exist inside TARGET_REPO:
+   - .codex/zcode-routing.json
+   - .codex/ZCODE_DELEGATION.md
+   - .agents/mcp.json
+   - AGENTS.md
+8. Run a dry route check. If INSTALLER_MODE=uvx:
+   uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+     zcode-auto-route \
+     --workspace "$TARGET_REPO" \
+     --objective "setup smoke check"
+   Otherwise run:
+   python3 "$SUPERVISOR_REPO/tools/zcode_supervisor/zcode_supervisor.py" auto-route \
+     --workspace "$TARGET_REPO" \
+     --objective "setup smoke check"
+9. If possible, run preflight. If INSTALLER_MODE=uvx:
+   uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+     zcodectl cli-preflight
+   uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+     zcodectl vision-preflight --workspace "$TARGET_REPO"
+   Otherwise run:
+   node "$SUPERVISOR_REPO/tools/zcode_control/zcodectl.mjs" cli-preflight
+   node "$SUPERVISOR_REPO/tools/zcode_control/zcodectl.mjs" vision-preflight --workspace "$TARGET_REPO"
+10. Report:
+   - what was written
+   - commands run
+   - pass/fail result for each check
+   - anything I still need to do manually
+   - the exact command I should use for the first real delegated task
+
+Success means the target repo has routing files installed, a dry route check
+works, and I understand any remaining manual prerequisite.
+```
+
+## Setup Guide: Set Up One Target Repo
+
+Use this section when you are starting from zero. The goal is to mark one
+existing repository as a place where Codex can plan and audit while ZCode does
+bounded implementation work.
+
+### 0. Know The Two Repositories
+
+- **This repo:** `ZCode-supervisor`. It contains the supervisor tools.
+- **Target repo:** the repo you want ZCode to help edit. This is the path you
+  pass to `zcode-install-repo`.
+
+`/path/to/target-repo` is a placeholder. Replace it with the absolute path to
+your own target repo, such as:
+
+```bash
+~/work/my-app
+```
+
+You can get the absolute path by opening Terminal, moving into the target repo,
+and running:
+
+```bash
+pwd
+```
+
+### 1. Put This Supervisor Repo On Disk
+
+If you are reading this on GitHub and do not have the repo locally yet, clone
+it first:
+
+```bash
+git clone https://github.com/AkiGarage/ZCode-supervisor.git
+cd ZCode-supervisor
+pwd
+```
+
+The `pwd` output is the absolute path to this supervisor repo. If your clone is
+not at `~/dev/ZCode-supervisor`, replace that path in examples with
+your own supervisor repo path.
+
+### 2. Install The Required Apps And Tools
+
+Install and sign in to ZCode first:
+
+- ZCode install docs: https://zcode.z.ai/en/docs/install
+
+Minimum local tools:
+
+- ZCode desktop app installed and connected to a model provider.
+- Node.js `>=22`.
+- Python `>=3.11`.
+- Git.
+- A POSIX-like shell such as the default macOS Terminal shell.
+- Network access to the configured model provider.
+
+Check the local basics:
+
+```bash
+node --version
+python3 --version
+git --version
+```
+
+### 3. Run The Installer From Terminal
+
+Run this in Terminal. You may run it from any current folder, because the
+target repo is provided as an absolute path:
+
+```bash
+zcode-install-repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+```
+
+Example:
+
+```bash
+zcode-install-repo ~/work/my-app
+```
+
+This command is setup only. Run it once per target repo; it is not a per-task
+command.
+
+If `zcode-install-repo` is not found, run the supervisor command directly from
+this repo:
+
+```bash
+python3 /absolute/path/to/ZCode-supervisor/tools/zcode_supervisor/zcode_supervisor.py install-repo \
+  --repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO \
+  --write-agents
+```
+
+If your supervisor repo lives somewhere else, replace
+`/absolute/path/to/ZCode-supervisor` with the absolute path from `pwd` in step 1.
+
+### Primary Install Path
+
+The current public setup path is `uvx` from this GitHub repo:
+
+```bash
+uvx --from git+https://github.com/AkiGarage/ZCode-supervisor.git \
+  zcode-install-repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+```
+
+After the first PyPI release, the shorter package command will be:
+
+```bash
+uvx --from zcode-supervisor zcode-install-repo /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO
+```
+
+The PyPI package is published through Trusted Publishing, without long-lived
+PyPI tokens. High-assurance users can also download the GitHub Release archive,
+verify `SHA256SUMS`, and run `gh attestation verify` before using it. Homebrew
+is archived for now; see [docs/distribution.md](docs/distribution.md).
+
+### 4. Confirm What Was Written
+
+The installer writes these files inside the target repo:
+
+- `.codex/zcode-routing.json`
+- `.codex/ZCODE_DELEGATION.md`
+- `.agents/mcp.json`
+- `AGENTS.md` pointer text, when `--write-agents` is used
+
+The important rule is simple: Codex keeps planning, orchestration, validation,
+audit, recovery, and final acceptance. ZCode only handles bounded
+implementation through `zcodectl run-packet`.
+
+### 5. Check The Route Before Editing
+
+Use a dry run before implementation work:
+
+```bash
+zcode-auto-route \
+  --workspace /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO \
+  --objective "Fix the failing ledger summary test."
+```
+
+Typical results:
+
+- `needs_codex_planning`: Codex should choose allowed files and validation.
+- `delegate_zcode`: the task is ready to run through ZCode.
+- `codex_direct`: Codex can handle it directly.
+- `ask_user`: pause because the task is high risk.
+
+### 6. Run A Real Delegated Task
+
+After Codex has chosen a tight edit scope and validation command:
+
+```bash
+zcode-auto-route \
+  --workspace /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO \
+  --objective "Fix the failing ledger summary test." \
+  --allowed src/ledger.js \
+  --validation "npm test" \
+  --execute
+```
+
+Use `--allowed` for files ZCode may edit. Use `--validation` for the command
+Codex will trust as the first safety check. Keep both narrow.
+
+### Troubleshooting The First Run
+
+- `command not found: zcode-install-repo`: use the direct `python3 ... install-repo`
+  command shown above, or add this repo's `scripts/` directory to your PATH.
+- `repo does not exist`: replace the placeholder with the exact absolute path
+  from `pwd`.
+- ZCode cannot run prompts: open ZCode once, sign in, configure the provider,
+  then run `node tools/zcode_control/zcodectl.mjs cli-preflight` from this repo.
+- Vision or screenshot tasks fail preflight: run
+  `node tools/zcode_control/zcodectl.mjs vision-preflight --workspace /ABSOLUTE/PATH/TO/YOUR/TARGET_REPO`.
+
+## Repository Snapshot
+
+- **Current version:** `v0.0.1`
+- **Primary use case:** delegate bounded coding tasks to ZCode/GLM while Codex
+  keeps planning, guardrails, validation, and final review.
+- **Main command path:** `node tools/zcode_control/zcodectl.mjs run-packet`
+- **Responsibility split:** isolate workspaces, snapshot before execution, audit
+  changes after execution, and reject unsafe or out-of-scope diffs.
+- **Best for:** low-babysitting AI coding workflows, reproducible tool
+  comparisons, token/quota-aware delegation, and supervised benchmark runs.
+
+## Start Here
+
+- New user? Read [Setup Guide](#setup-guide-set-up-one-target-repo), then
+  [How Codex And ZCode Share Responsibility](#how-codex-and-zcode-share-responsibility).
+- Running ZCode headlessly? Read
+  [Requirements And Control Surfaces](#requirements-and-control-surfaces) and
+  [ZCode Desktop Control](#zcode-desktop-control).
+- Comparing tools or tracking usage? Read
+  [Usage, Token, And Quota Logging](#usage-token-and-quota-logging).
+- Planning future work? See [ROADMAP.md](ROADMAP.md) and
+  [CHANGELOG.md](CHANGELOG.md).
+
+## What This Provides
+
+- `zcode_supervisor`: creates task packets, snapshots workspaces, and audits
+  ZCode changes after execution.
+- `zcodectl`: CLI-first controller for the bundled ZCode headless CLI, with
+  optional Electron CDP helpers for desktop inspection.
+- Workspace-local ZCode templates for `AGENTS.md`, quality gates, parallel
+  work, and Skill-friendly operating playbooks.
+- Small benchmark fixtures and tests for the supervisor/audit workflow.
+- A GLM-5.2/ZCode operating playbook for long-horizon coding, root-cause
+  analysis, production-grade standards checks, and token-efficient delegation.
+- Optional repo-local Codex usage hook shim that records session starts/stops
+  through `codex-usage-ledger` when configured, with local pending JSONL
+  fallback when the central ledger is unavailable.
+
+## Version
+
+Current release: `v0.0.1`
+
+Distribution and release preparation: [docs/distribution.md](docs/distribution.md)
+
+## How Codex And ZCode Share Responsibility
+
+This project is built around a simple responsibility split:
+
+- Codex decides the plan, allowed files, validation command, audit result, and
+  final acceptance.
+- ZCode does only the bounded implementation work Codex explicitly delegates.
+
+The intended workflow is:
+
+1. Codex creates a compact task packet.
+2. Codex snapshots the workspace.
+3. ZCode works inside an isolated workspace or worktree.
+4. Codex runs the supervisor audit.
+5. Codex independently reviews and accepts or rejects the result.
+
+`Full access` should only be used in disposable workspaces or isolated
+worktrees. Packet creation blocks regular-workspace `Full access` by default
+and rejects obviously destructive validation commands. The supervisor audit
+rejects forbidden edits, changes outside the allowed file set, optional changed
+file count overages, validation failures, workspace mismatches, and secret-like
+content in changed files.
+
+## Command Reference After Setup
+
+The examples in this section use shorter placeholder paths. Replace every
+`/path/to/target-repo` or `/path/to/repo` with the absolute path to your real
+target repo, just like in the Setup Guide above.
+
+Install repo-local routing hints in a target repository:
+
+```bash
+zcode-install-repo /path/to/target-repo
+```
+
+Run this once per target repo. It is setup, not a per-task command.
+
+This writes `.codex/zcode-routing.json`, `.codex/ZCODE_DELEGATION.md`, and
+`.agents/mcp.json` in the target repo. It also adds a small `AGENTS.md` pointer
+so Codex knows the default split: Codex plans, orchestrates, audits, validates,
+and final-accepts; ZCode handles only bounded implementation through
+`zcodectl run-packet`. The MCP file enables the recommended `zai-mcp-server`
+stdio entry for vision packets without writing API keys into the repository.
+Re-run with `--force` only when you intentionally want to refresh generated
+files or replace an existing `zai-mcp-server` entry.
+
+If the PATH wrapper is unavailable, use the underlying command:
+
+```bash
+python3 /path/to/ZCode-supervisor/tools/zcode_supervisor/zcode_supervisor.py install-repo \
+  --repo /path/to/target-repo \
+  --write-agents
+```
+
+## Auto Routing
+
+Installed repos default to `routing_mode: auto`. Future Codex sessions should
+run the route check before implementation edits:
+
+```bash
+zcode-auto-route \
+  --workspace /path/to/target-repo \
+  --objective "Fix the failing ledger summary test."
+```
+
+This check is optional when you already know the task should run through ZCode;
+it is mainly a dry-run for inspecting the route decision. You do not need to run
+all three setup/check/execute commands for every task:
+
+- First-time setup: run `zcode-install-repo /path/to/target-repo` once.
+- Route inspection: run `zcode-auto-route --workspace ... --objective ...`
+  when you want to see the JSON decision.
+- Real delegated implementation: run `zcode-auto-route ... --allowed ...
+  --validation ... --execute` after Codex has selected the file scope and
+  validation command.
+
+If the user explicitly says "use ZCode", "have ZCode do it", or similar, Codex should
+treat that as an instruction to use this ZCode-supervisor flow for bounded
+implementation work. Codex still owns planning, orchestration, validation,
+audit, recovery, and final acceptance.
+
+The router returns JSON so Codex can proceed without asking for routine
+decisions:
+
+- `delegate_zcode`: create a packet and run ZCode.
+- `needs_codex_planning`: Codex must choose a tight allowed-file set and
+  validation command, then rerun with `--execute`.
+- `codex_direct`: Codex may handle the task directly because it is read-only,
+  trivial, missing routing config, or explicitly marked `no-zcode`.
+- `ask_user`: pause for a short plan because the task matches a high-risk
+  category such as destructive changes, migrations, credentials, production, or
+  money-sensitive work.
+
+For normal implementation after Codex has selected allowed files and validation:
+
+```bash
+zcode-auto-route \
+  --workspace /path/to/target-repo \
+  --objective "Fix the failing ledger summary test." \
+  --allowed src/ledger.js \
+  --validation "npm test" \
+  --execute
+```
+
+`--execute` creates the packet, calls `zcodectl run-packet`, writes run results
+under `.codex/zcode/runs/`, and keeps Codex responsible for final acceptance.
+This is intentionally a smart default rather than a hard lock: high-risk,
+read-only, trivial, and `no-zcode` tasks do not get forced through ZCode.
+
+Create a task packet:
+
+```bash
+python3 tools/zcode_supervisor/zcode_supervisor.py packet \
+  --workspace benchmarks/zcode-goal-mode \
+  --objective "Fix summarizeLedger so npm test passes." \
+  --allowed src/ledger.js \
+  --forbidden test/ledger.test.js \
+  --validation "npm test" \
+  --effort max \
+  --task-class root-cause \
+  --risk-budget low \
+  --max-changed-files 1 \
+  --goal \
+  --out .local/packets/ledger.json \
+  --prompt-out .local/packets/ledger.prompt.txt
+```
+
+Snapshot the workspace:
+
+```bash
+python3 tools/zcode_supervisor/zcode_supervisor.py snapshot \
+  --workspace benchmarks/zcode-goal-mode \
+  --out .local/snapshots/ledger.before.json
+```
+
+After ZCode runs, audit the result:
+
+```bash
+python3 tools/zcode_supervisor/zcode_supervisor.py audit \
+  --workspace benchmarks/zcode-goal-mode \
+  --snapshot .local/snapshots/ledger.before.json \
+  --packet .local/packets/ledger.json
+```
+
+## Requirements And Control Surfaces
+
+This toolkit does not require Codex Computer Use. The preferred automation path
+is the ZCode headless CLI bundled inside the ZCode desktop app:
+
+```text
+Codex or a normal terminal
+  -> node tools/zcode_control/zcodectl.mjs
+  -> ZCode bundled CLI
+  -> ZCode / GLM task execution
+```
+
+Control surface priority:
+
+1. **ZCode bundled headless CLI, recommended and required for headless
+   delegation.** `cli-prompt` and `run-packet` use this path. It is the path
+   validated by this project on macOS with ZCode 3.1.2.
+2. **`cua-driver` plus Electron CDP, optional.** `cua-driver` is an MIT-licensed
+   background computer-use driver from the Cua project:
+   https://cua.ai/docs/cua-driver/guide/getting-started/introduction
+   When available, GUI helpers can use this kind of desktop-control surface to
+   inspect visible text, take screenshots, click buttons, and read visible
+   Usage Stats without making it the primary delegation path. Thanks to the Cua
+   authors for the computer-use driver work; this project uses that capability
+   only as an optional diagnostic/control surface.
+3. **Codex Computer Use, optional fallback only.** It can operate the GUI when
+   available, but this repository does not depend on it and does not require it
+   for the primary workflow.
+
+Minimum local tooling:
+
+- ZCode desktop app installed and connected to a model provider.
+- Node.js `>=22`.
+- Python `>=3.11`.
+- Git and a POSIX-like shell for `scripts/check.sh`.
+- Network access to the configured model provider.
+
+The latest official ZCode install docs list these supported platforms:
+
+- macOS on Apple Silicon and Intel.
+- Windows.
+- Linux through the Linux beta group.
+
+See the official ZCode install docs:
+https://zcode.z.ai/en/docs/install
+
+Project support status:
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Tested | ZCode 3.1.2, bundled CLI path `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs`, bundled CLI version `0.14.8`, GUI config path `~/.zcode/v2/config.json`, CLI config path `~/.zcode/cli/config.json`. |
+| Windows | Expected, not verified | ZCode is officially supported and 3.1.2 adds Windows shell selection, but this project still needs Windows-specific CLI path discovery and shell validation. Set `ZCODE_CLI_PATH` if auto-detection does not find the bundled CLI. |
+| Linux | Expected/beta, not verified | ZCode Linux packages are distributed through the official beta group, but this project has not validated Linux CLI paths, desktop launch, or config discovery yet. Set `ZCODE_CLI_PATH`, `--source-config`, and `--cli-config` as needed. |
+
+`bootstrap-cli-config` can copy a local ZCode GUI Coding Plan API key into the
+ZCode CLI config with `0600` permissions and redacted output. On non-macOS
+systems, pass explicit config paths if the defaults do not match the installed
+ZCode layout:
+
+```bash
+node tools/zcode_control/zcodectl.mjs bootstrap-cli-config \
+  --provider zai \
+  --model glm-5.2 \
+  --source-config /path/to/gui/config.json \
+  --cli-config /path/to/cli/config.json
+```
+
+## ZCode Desktop Control
+
+`zcodectl` is intentionally small and experimental. Its primary path is the
+bundled ZCode headless CLI. Its GUI helpers expect ZCode to be available as a
+desktop app and use Electron CDP after launch.
+
+For ZCode 3.1.2 and later, prefer the bundled headless CLI when it is available:
+
+```bash
+node tools/zcode_control/zcodectl.mjs cli-path
+node tools/zcode_control/zcodectl.mjs cli-preflight
+node tools/zcode_control/zcodectl.mjs bootstrap-cli-config \
+  --provider zai \
+  --model glm-5.2
+node tools/zcode_control/zcodectl.mjs cli-doctor
+node tools/zcode_control/zcodectl.mjs run-packet \
+  --packet .local/packets/ledger.json \
+  --mode plan \
+  --max-attempts 2 \
+  --retry-delay-ms 60000 \
+  --usage-snapshot-source auto \
+  --out .local/runs/ledger.zcode.json
+```
+
+`run-packet` sends the supervisor-generated packet prompt to the bundled
+ZCode CLI with the packet workspace as `--cwd`. It avoids GUI/CDP fragility and
+is the preferred Codex control path for headless delegation. If the CLI config
+is not ready, `cli-prompt` and `run-packet` try to bootstrap it from the local
+ZCode desktop GUI config before sending the prompt. Pass `--no-bootstrap` to
+disable that behavior. Use `cli-prompt` for ad-hoc prompts:
+
+`run-packet` treats ZCode provider overload as structured supervisor state. It
+classifies `ProviderBusinessError`, provider code `1305`, temporary overload
+messages, and CLI exit code `143`. Every attempt is audited by the Codex-side
+supervisor after the ZCode turn, so validation does not depend on ZCode's
+internal Bash/tool permission client. The result returns `supervisor_state`:
+
+- `success`: CLI completed normally and supervisor audit plus validation passed.
+- `audit_failed`: CLI completed normally, but supervisor audit or validation
+  failed.
+- `partial_success`: provider error happened after scoped changes, and audit
+  plus validation passed.
+- `retryable_provider_error`: provider error happened with no file changes.
+- `unsafe_partial`: provider error happened with changed files that failed
+  scope, validation, or safety checks.
+
+Safe no-change provider errors retry up to `--max-attempts` with
+`--retry-delay-ms` cooldown. Changed files are never blindly retried; they are
+audited first. The JSON result includes `cli_ok`, `provider_error`,
+`provider_code`, `provider_message`, `provider_id`, `provider_kind`,
+`usage_available`, `attempts`, `retry_count`, `retry_delays_ms`,
+`safe_to_retry_later`, `partial_artifacts_possible`, `audit`, `validation`,
+`validation_ok`, and compact `attempt_results`.
+
+`run-packet` also captures before/after usage snapshots. The default
+`--usage-snapshot-source auto` first calls the Z.AI quota API directly using
+`ZAI_API_KEY`, `launchctl getenv ZAI_API_KEY`, or the local redacted ZCode CLI
+config as the credential source. The API key is never written to result JSON or
+logs. If the direct API snapshot is unavailable, `auto` falls back to the
+CodexBar CLI:
+
+```bash
+codexbar usage --provider zai --format json
+```
+
+CodexBar.app does not need to be running for either path. The snapshot is
+non-fatal: if both direct API and CodexBar CLI capture are missing or
+unavailable, task execution continues and the JSON records the snapshot error.
+When capture succeeds, the JSON includes:
+
+- `usage_snapshots.before` and `usage_snapshots.after`: raw provider snapshots
+  plus normalized quota windows. Direct Z.AI API snapshots use `source:
+  "zai-api"`; CodexBar snapshots use `source: "codexbar"`.
+- `usage_accounting.tokens_*`: consumed token fields normalized from the ZCode
+  CLI JSON `usage` payload for this run.
+- `usage_accounting.quota_percent_*`: before, after, and delta for the primary
+  used-percent quota window. `quota_percent_direction` is `used`.
+- Direct Z.AI `TOKENS_LIMIT.percentage` is treated as the measured used-percent
+  value even when the same window omits finite `usage` and `remaining` token
+  counts. The normalized window records `token_counts_available` separately, so
+  percent deltas remain available without inventing token-count deltas.
+- `usage_accounting.quota_windows`: per-window deltas, including reset-change
+  detection so a quota-window reset is not misreported as negative usage.
+
+Use `--usage-snapshot-source zai-api` to require direct Z.AI API capture,
+`--usage-snapshot-source codexbar` to require CodexBar CLI capture, or
+`--usage-snapshot-source none` to disable snapshot capture. Use
+`--usage-provider zai` to make the provider explicit. `--zai-quota-url` can
+point at a custom Z.AI-compatible quota endpoint for tests. `--codexbar-path`
+or the `CODEXBAR_PATH` environment variable can point at a custom CodexBar CLI
+path.
+
+```bash
+node tools/zcode_control/zcodectl.mjs cli-prompt \
+  --workspace benchmarks/zcode-goal-mode \
+  --mode plan \
+  --text "Review this fixture and report the failing test cause." \
+  --out .local/runs/review.json
+```
+
+`bootstrap-cli-config` reads the local ZCode GUI config, finds an existing
+Coding Plan API key, and writes the CLI-native config at
+`~/.zcode/cli/config.json` with `0600` permissions. Secret values are copied
+locally and are not printed in command output. The default provider is `zai`
+and the default model is `glm-5.2`.
+
+`cli-preflight` checks the CLI binary, model selection, and whether a Coding
+Plan API key is configured. It redacts secret values and reports
+`prompt_ready=true` when headless prompts can run.
+
+## Image And Vision Tasks
+
+GLM-5.2 is treated as text-only in this supervisor. For image understanding,
+use ZCode's built-in image service through the recommended `zai-mcp-server`
+MCP service, then attach workspace-local images through the packet:
+
+```bash
+python3 tools/zcode_supervisor/zcode_supervisor.py packet \
+  --workspace benchmarks/zcode-goal-mode \
+  --objective "Implement the UI state shown in the screenshot." \
+  --allowed src/ledger.js \
+  --validation "npm test" \
+  --vision-image screenshots/state.png \
+  --vision-color-sample primary=screenshots/state.png@240,420 \
+  --out .local/packets/vision.json
+```
+
+`--vision-image` marks image understanding as required and stores the image
+paths in the packet. `run-packet` automatically forwards those paths to the
+ZCode CLI as repeated `--attach` arguments. Before running a required vision
+packet, `run-packet` checks redacted ZCode MCP configuration for the preferred
+image service and stops with `vision_service_unavailable` if it is missing,
+instead of letting the worker guess from filenames or text.
+
+Use `--vision-color-sample name=image.png@x,y` when a task needs pixel-exact
+hex colors. The supervisor reads that PNG pixel locally and injects the exact
+uppercase `#RRGGBB` value into the worker prompt, while ZCode still handles the
+broader image understanding. The sampler is intentionally narrow: workspace
+local, non-secret, non-interlaced 8-bit RGB/RGBA PNG files.
+
+You can check the image-service setup directly:
+
+```bash
+node tools/zcode_control/zcodectl.mjs vision-preflight \
+  --workspace benchmarks/zcode-goal-mode
+```
+
+`zcode-install-repo /path/to/repo` writes `.agents/mcp.json` with the
+recommended stdio server:
+
+```json
+{
+  "mcpServers": {
+    "zai-mcp-server": {
+      "args": ["-y", "@z_ai/mcp-server"],
+      "command": "npx",
+      "enable": true,
+      "type": "stdio"
+    }
+  }
+}
+```
+
+The relevant ZCode docs describe `zai-mcp-server` as the recommended MCP server
+for visual understanding of images, screenshots, and interface context:
+https://zcode.z.ai/en/docs/mcp-services
+
+The npm package that provides the `zai-mcp-server` binary is
+`@z_ai/mcp-server`. It expects `Z_AI_API_KEY`; for required vision packets,
+`run-packet` passes an available key to the ZCode child process from the current
+environment, `ZAI_API_KEY`, or the local ZCode CLI config without printing the
+secret value. Pixel-exact color sampling should still be verified with a
+deterministic image tool when exact hex values matter; generic vision can be
+close but not always exact.
+
+The GUI/CDP helpers remain available for inspecting the desktop app and reading
+visible Settings usage when CDP is exposed:
+
+Example:
+
+```bash
+node tools/zcode_control/zcodectl.mjs launch --port 9223
+node tools/zcode_control/zcodectl.mjs targets --port 9223
+node tools/zcode_control/zcodectl.mjs goal --port 9223 --text-file .local/packets/ledger.prompt.txt
+```
+
+If ZCode is already running without a debug port, use
+`node tools/zcode_control/zcodectl.mjs launch --port 9223 --new-instance` and
+check that the launch output includes `"cdp": {"ok": true, ...}` before running
+`targets`, `usage`, or `goal`.
+
+Do not send secrets through `zcodectl eval` or prompt files.
+
+## Usage, Token, And Quota Logging
+
+For every delegated ZCode task, capture Usage Stats before and after the run,
+then append the result to the evaluation ledger.
+
+The current ZCode Usage Stats docs split usage into App Usage for local session
+records and Coding Plan for remote Z.ai / BigModel quota, GLM-5.2 and
+GLM-5-Turbo model usage, and MCP tool-call usage. Treat quota snapshots as
+time-sensitive evidence and keep the raw snapshot beside the normalized eval
+record.
+
+```bash
+node tools/zcode_control/zcodectl.mjs open-usage --port 9223
+node tools/zcode_control/zcodectl.mjs usage --port 9223 --out .local/usage/ledger.before.json
+
+# Run the ZCode task.
+
+node tools/zcode_control/zcodectl.mjs open-usage --port 9223
+node tools/zcode_control/zcodectl.mjs usage --port 9223 --out .local/usage/ledger.after.json
+
+python3 tools/zcode_eval/zcode_eval.py append-result \
+  --run-id zcode-ledger-001 \
+  --tool zcode \
+  --task-id ledger \
+  --task-name "Ledger fixture" \
+  --status pass \
+  --validation "npm test: pass" \
+  --usage-before .local/usage/ledger.before.json \
+  --usage-after .local/usage/ledger.after.json
+```
+
+`append-result` records `tokens_before`, `tokens_after`, `tokens_used`,
+`quota_percent_before`, `quota_percent_after`, and `quota_percent_used`. By
+default, quota percent is treated as remaining quota, so consumed quota is
+derived as before minus after. If the visible UI is a used-percent counter, pass
+`--quota-percent-direction used`.
+
+When recording a provider-error run, `append-result` also accepts optional
+metadata: `--supervisor-state`, `--provider-error`, `--provider-code`,
+`--provider-message`, `--provider-id`, `--provider-kind`, `--attempts`,
+`--retry-count`, `--retryable-provider-error`,
+`--partial-artifacts-possible`, `--safe-to-retry-later`, and
+`--usage-available` / `--no-usage-available`.
+
+If ZCode does not expose CDP in the current session, you can still record the
+same fields explicitly:
+
+```bash
+python3 tools/zcode_eval/zcode_eval.py append-result \
+  --run-id zcode-ledger-001 \
+  --tool zcode \
+  --task-id ledger \
+  --task-name "Ledger fixture" \
+  --status pass \
+  --tokens-before 1000 \
+  --tokens-after 1450 \
+  --quota-percent-before 88.5 \
+  --quota-percent-after 87.0
+```
+
+Review logs later with:
+
+```bash
+python3 tools/zcode_eval/zcode_eval.py show-log
+python3 tools/zcode_eval/zcode_eval.py summarize
+```
+
+External duel runs can be imported into the same JSONL ledger. The importer
+reads `results.json` plus adjacent `_control/zcode/*/zcode-result.json` files
+when available, so provider overload rows keep `provider_code`, retryability,
+partial-artifact status, usage availability, and quota unavailable reasons:
+
+```bash
+python3 tools/zcode_eval/zcode_eval.py import-duel-results \
+  --source /path/to/ClaudeCodeGLM-supervisor/work/supervisor_duel_eval/runs/20260617-153042/results.json \
+  --path artifacts/evals/zcode-vs-claude.jsonl
+```
+
+## ZCode Release Monitoring
+
+ZCode compatibility is pinned against `config/zcode-release-baseline.json`.
+Check the official changelog manually with:
+
+```bash
+python3 tools/zcode_eval/zcode_release.py check \
+  --baseline config/zcode-release-baseline.json \
+  --include-installed
+```
+
+The GitHub Actions workflow `.github/workflows/zcode-release-monitor.yml` runs
+the same release check on a schedule. When the official ZCode version is newer
+than the baseline, it runs `bash scripts/check.sh` and opens or updates a GitHub
+Issue with the release notes and follow-up checklist.
+
+## Templates
+
+Copy `templates/zcode-codex-system/` into a disposable workspace or worktree to
+give ZCode:
+
+- a bounded worker contract via `AGENTS.md`
+- Skill-friendly playbooks and a quality gate
+- a parallel-work playbook
+- a GLM-5.2 operating profile for choosing task class, effort, and context
+  strategy
+
+Current ZCode docs say user-defined custom subagents are not supported yet.
+Use the built-in read-only Explore subagent for broad code research, and use
+Skills or Commands for reusable worker behavior. The legacy
+`.zcode/cli/agents/` template files are retained only as draft role prompts,
+not as an advertised ZCode runtime feature.
+
+## GLM-5.2 Operating Defaults
+
+- Use `effort=max` for long-horizon implementation, cross-module debugging,
+  architecture mapping, production-grade standards checks, and mobile/debugging
+  loops.
+- Use `effort=high` for cheap probes, narrow reviews, and small repairs where
+  speed matters more than deep search.
+- Treat 1M context as durable architectural memory, not a reason to dump every
+  file into every task.
+- Use `/goal` only with objective acceptance criteria and an exact validation
+  command.
+- Use `--max-changed-files` when the expected diff is small, so broad edits fail
+  the audit automatically.
+- Use `--workspace-kind fixture|worktree|disposable` before `Full Access`;
+  regular workspaces are blocked by default.
+- Keep Codex as final auditor even when ZCode completes the task.
+
+See the GLM-5.2 ZCode Operator Guide:
+[English](docs/glm-5.2-zcode-operator-guide.md) /
+[日本語](docs/glm-5.2-zcode-operator-guide.ja.md).
+
+## Development
+
+Run the full local check:
+
+```bash
+bash scripts/check.sh
+```
+
+The project uses only the Python and Node standard libraries for its core
+checks.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned benchmark work.