LazyZCode Documentation

English · 简体中文

The complete guide to the discipline layer for ZCode: plan → execute → take evidence → never stop half-done.

Installation

One package installs both halves of LazyZCode: the lazyzcode:zw plugin (skills, hooks, agents) and the lzy CLI (the goal-loop state machine).

Prerequisites

• macOS, Windows, or Linux — LazyZCode detects the ZCode engine layout on all three (macOS app bundle, Linux deb /opt/ZCode, Windows per-user %LOCALAPPDATA%\Programs\ZCode); nothing is guessed.
• ZCode desktop app, installed and logged in. LazyZCode runs inside ZCode; there is no separate login.
• Node.js ≥ 24 — the sqlite storage floor (ADR-0039; enforced by engines >=24 as of 0.6.0 — npm refuses the install outright, it is no longer advisory). Installed via nvm or Homebrew both work: the bundled hook launcher scans both locations when the engine’s hook environment lacks node (Windows resolves via nvm-windows/Program Files; see Hooks & lifecycle). Windows platform validation boundary (0.6.0, tested on Windows 11 aarch64): migration / queue / hooks / doctor all work; state.sqlite WAL is active on the local NTFS volume while a connection is open and converges on close with integrity_check=ok; shared-folder layouts are outside the tested surface.
• git — evidence binding uses git rev-parse HEAD^{tree}, so the project you work in must be a git repository.

Install

npm i -g lazyzcode
lzy install

lzy install does three things: deploys the plugin payload to the engine’s plugin cache, writes LazyZCode’s own registry entry, and enables the plugin through the engine’s official plugins enable command. It never writes your config.json — enabling flows only through the engine’s own CLI (ADR-0001).

Verify it worked

lzy status   # quick check; exit code 0 = no fail-level findings
lzy doctor   # deep local diagnostics (zero telemetry)

Both commands accept --json: a machine-readable contract output (schemaVersion starts at 1 — the version discipline is additive-only: new fields are optional, absent fields are never emitted as null, and consumers must ignore unknown fields; the shape is pinned by a contract test) for scripts and external observers — no text scraping required.

Inside a fresh ZCode session, type zw at the start of a prompt — the orchestration bootstrap should arrive, and the model’s first line should read **ZW** engaged — LIGHT tier (or HEAVY).

Uninstall

lzy uninstall

Removes the deployed cache and the registry entry, preferring the engine’s official plugins uninstall path.

Recommended environment

Overview

LazyZCode installs four things:

1. One plugin (lazyzcode:zw) whose skill text carries the full orchestration protocol — triage, tier selection, planning, execution, and evidence rules.
2. Six hooks wired to the engine’s lifecycle: SessionStart (re-inject loop state), UserPromptSubmit (trigger words), PreToolUse (command-layer H3R gate — dormant prototype), PostToolUse (comment advisory), PostToolUseFailure (same-tool failure tripwire), Stop (bounded continuation).
3. Three read-only agents: lazyzcode:explorer, lazyzcode:plan-reviewer, lazyzcode:qa-executor.
4. One CLI (lzy) implementing the goal loop as a state machine that survives session restarts: register → plan gate → execute → evidence → finish gate.

The mental model: a plan checkbox is a claim; only real-surface evidence is a fact. LazyZCode’s job is to make the agent convert claims into facts — and to pull it back when it tries to stop before that conversion is complete.

Your first goal loop

Open a fresh ZCode session in your project and type:

zw implement a CSV export endpoint with tests

What happens:

1. The UserPromptSubmit hook matches the sentence-initial zw and injects the orchestration bootstrap.
2. The model announces **ZW** engaged — <tier> tier and triages the task (see The zw protocol).
3. It registers a goal with the CLI (lzy loop register …) and writes a plan file into .lazyzcode/plans/.
4. The plan is adopted through the plan gate — HEAVY plans must first pass the lazyzcode:plan-reviewer agent.
5. The model executes step by step, calling lzy step done <ID> as steps complete. F items require --evidence bound to the current tree hash.
6. lzy loop finish runs the final gate: all steps done, all evidence fresh. Only then is the goal complete.

If the model stops while the loop is open, the Stop hook pulls it back — at most 2 continuations per session. To resume after an interruption (including a rate-limit kill), just send zw continue (zw 继续); the loop state in .lazyzcode/ is untouched.

To free the slot after a finished loop, run lzy loop reset.

FAQ

Where does LazyZCode keep its state? In .lazyzcode/ inside your project (loop state, plans, archived evidence). It is deliberately separate from ZCode’s own .zcode/. Add it to your .gitignore if you do not want to commit it.

Does it phone home? No. Zero telemetry. Everything lzy doctor reports is computed locally from your own files and engine logs.

Does it write my config.json? Never. Enabling goes through the engine’s official plugins enable; the installer only deploys files and writes LazyZCode’s own registry.

Why didn’t my zw trigger? Matching is stratified: a bare zw fires only at the start of the prompt. Mid-sentence zw is ignored (that is intentional — “check the zw hooks” is a question, not an invocation). Use the explicit lazyzcode:zw anywhere, or ulw/ultrawork anywhere word-bounded.

Why did lzy loop finish reject my evidence? Evidence is bound to the tree hash of the commit that was current when it was captured. If you changed code after capturing, the evidence is stale by construction — commit, then re-capture with lzy step done <ID> --evidence ….

I hit [1302] rate limit. Is LazyZCode broken? No — that is the GLM plan’s account-level concurrency limit. lzy doctor’s rate-limit line reports your measured pressure and a suggested session budget. See Rate-limit discipline.

My hooks do nothing at all. Your engine was probably launched without node on its PATH (common when ZCode.app starts from the Dock). The bundled run-hook launcher resolves node automatically — nvm/Homebrew on POSIX, nvm-windows/Program Files on Windows; lzy doctor’s hook-node line tells you what it found. Details in docs/diagnostics/2026-09-07-hook-spawn-env.md.

Can I run two goal loops at once? One loop per project directory. A finished loop still occupies the slot until lzy loop reset clears it.

Can I use the CLI without the plugin (or vice versa)? Yes. The CLI works anywhere; the plugin needs the engine. The workflow works best with both — the hooks and skill text drive the discipline that the CLI enforces.

Trigger words

* that example does not engage the loop — it is a mention. Injection is conditional: an invocation engages the protocol; a mere mention is ignored and answered directly (“Mention ≠ invocation”). zwift, azw, and mid-sentence zw never fire.

The zw protocol

The injected skill text (plugin/skills/zw/SKILL.md) defines the contract the model follows:

1. Open with exactly **ZW** engaged — <LIGHT|HEAVY> tier.
2. Triage the tier. LIGHT for small, contained, low-risk work (a 1–2 item plan, one F item). HEAVY for multi-file features, architecture, or anything risky or vague — explore first, plan every step. Escalating LIGHT → HEAVY is always allowed — and persisted: register with --tier heavy or run lzy loop tier heavy before adopting (the HEAVY review gate is enforced by the machine off the persisted tier). Downgrading is never allowed.
3. Register the goal with the CLI.
4. Plan with an N/F checklist (see The plan gate).
5. Execute step by step, committing work and calling lzy step done <ID> with notes — and evidence for F items.
6. Capture evidence on real surfaces (see Evidence discipline).
7. Finish through the CLI gate (see Goal loop commands).

The protocol also carries behavioral red lines (no fake evidence, no silent scope abandonment) and the rate-limit rules below.

Since 0.1.0 the protocol text also annotates enforcement levels — L0 protocol convention, L1 CLI machine gate, L2 trusted host event, L3 external effect — so a reader always knows whether a rule is kept by promise or by machine, and carries a second axis next to tier: risk_class (LOW / MED / HIGH / RESTRICTED, upgrade-only), with HIGH+ barred from unattended lanes and RESTRICTED a hard block. Approvals bind immutable hashes (INV-05): plan adoption binds planHash at L1; a conversational nod stays L0 until the exact-hash human gate lands.

Since 0.1.1 pull-back is claim-gated: only a session that claimed the goal (an invocational trigger like zw 继续) is subject to Stop pull-backs; an empty claim set means nobody is pullable, so bystander sessions are structurally exempt. A session can opt out explicitly with zw standdown — a standdown flag makes the Stop hook release that session read-only until a claiming trigger clears it or the goal is reset. And the host workspace must be a git repository: lzy loop register hard-rejects a non-git host with git init guidance, because evidence binds git trees and a non-git host cannot pass finish (ADR-0019).

Requirement contracts (0.3.0)

By default a goal loop approves an execution plan: the UPS human gate binds your 「批准 <短码>」 to the planHash, and changing the plan mid-flight re-opens the gate. Since 0.3.0 a goal can instead be bound to a **requirement contract** — an immutable markdown file describing what to build (acceptance items with stable ids), where it may write (`scope:`), which delivery endpoint it targets, and which project-recipe version it trusts:

lzy loop register <slug> --title "…" --contract .lazyzcode/contracts/<task>.md

You approve the contract once (「批准 」); afterwards the agent replans inside the boundary without asking again — deleting an acceptance item, stepping outside `scope:`, or a changed `lzy.project.json` are all machine-rejected until you approve a new contract. You can revoke with 「撤回 」: the next gated action refuses, work already done stays honestly recorded. Read the bound contract and its approval ledger with `lzy contract show` / `lzy contract auth` (read-only — approvals and withdrawals exist only as real user messages). Goals registered without a contract keep the classic plan-approval gate.

Controlled execution & receipts (0.3.0 M2)

Check recipes in lzy.project.json can now actually run: lzy verify run <checkId> executes the recipe under the controlled executor (argv array, no shell, timeout kill, env-name whitelist) and records a checksum receipt under .lazyzcode/verify/ (reset-surviving; tamper fails closed). Raw output lands in raw/, kept separate from human summaries. A recipe that declares inputPaths (files or directories) and passes lzy verify qualify — the adversarial qualification that injects a change into every declared input and requires detection plus byte-identical restore — may reuse old receipts via lzy verify reuse --of <runId>; any failed question (non-empty inputs / qualification on record / input snapshot unchanged / manifest & env unchanged) falls back conservatively with named reasons, and reuse only appends an applicability judgment — the base receipt is never rewritten. lzy verify ci queries GitHub check-runs read-only and binds the commit identity: a recorded sha behind the current HEAD is labeled 非现行 (not current), and gh absent/offline reports blocked with recovery hints — never a silent pass.

Bounded queue & cumulative budget (0.3.0 M3)

Multiple authorized items can run continuously across interruptions. lzy queue add registers an approved contract as a queue item (proposed → authorized once the approval is effective → ready when dependencies / project / budget / lease / plan are all satisfied); lzy queue dispatch runs items serially: a dispatch transaction is written in-lock (occupancy registration) → the goal is registered or resumed → drive → finish → per-segment settlement → queue confirmation → slot recycle → next item. After a crash, restarting dispatch reconciles before acting: each unsettled transaction is judged against the current goal (same goal resumes without re-registering; a done goal settles honestly; a missing goal fails the item with a human-pointer), never re-dispatching blindly and never resetting another goal. The cumulative budget (lzy queue budget) binds the contract hash and lives outside the resettable goal: switching tasks, restarts and retries never refresh it, duplicate receipts dedupe by key. Point enforcement uses the approved approximate-limit semantics: usage is queried per segment sessionId; metering absence / unpriced models / unsettled occupancy are never counted as zero — point-limited dispatch stops with an explicit record until a human resumes it via --resume-points; in-flight consumption at SIGKILL is declared as a killed-inflight entry, never flattened to zero.

Limited delivery B/C (0.3.0 M4)

Delivering all the way to the project’s main branch (endpoint B) or a verified live environment (endpoint C) needs its own authorization on top of the requirement contract: lzy delivery request B|C --contract <file> binds a per-endpoint delivery contract and asks for a UPS approval of its hash. The merge action (lzy delivery act B) is machine-gated: dual B∧C authorization (when merging to a branch that triggers a deploy), PR head/base drift re-check, and green required CI on the PR head — then it merges bound to the PR head, reads back the actual merge SHA, and polls CI on that SHA. Pages verification (lzy delivery act C) waits until the Pages build commit matches the merge SHA and checks the live HTTPS content against an expected marker. Every action is preceded by an intent record (target identity, planned argv) in .lazyzcode/delivery/, and lzy delivery readback B|C classifies outcomes after timeouts or disconnects — a done intent is final, so an already-successful action is never re-executed.

Queue x delivery orchestration (0.3.1)

Items can target a delivery endpoint directly: lzy queue add ... --endpoint B --delivery-b <B contract> (endpoint C needs both --delivery-b and --delivery-c; endpoint A takes no delivery contract). After the goal finishes normally, dispatch runs the delivery chain itself: bind contracts, act/read-back B (then C), and only a done read-back marks the item completed (completedEndpoint records the reached endpoint). Delivery approval codes are available at enqueue time: queue add prints each contract’s short code and 「批准 」 is recorded through the same UPS approval channel (the goal does not exist yet before dispatch - the approval attaches to the item); an item missing any declared approval is never ready. For unattended runs the action parameters come from the contract (B: `repo/base/branch/pr-title/pr-body`; C: `repo/expect-marker/content-url` plus multi-page `page:` lines, each checked for 200-and-marker) - a contract missing required keys is rejected at enqueue, not at dispatch time. HEAVY items enter on a pre-enqueue plan-review PASS plus a plan hash (re-checked before dispatch: a changed plan voids the review); high-risk work stays out of the queue (HIGH+ never enters unattended lanes).

Delivery not completed (PR unmerged / build not aligned): the item lands in failed with the recovery route in its blockedReason - repair with lzy delivery readback/act, then lzy queue reconcile acknowledges it as completed without re-running the goal. A dead delivery chain (past the bound or a dead holder process) is settled from the intent ledger by reconcile - never a deadlock; infrastructure aborts (lock contention / corrupt intent ledger) end as a distinct “infrastructure abort” state so the two causes stay tellable apart.

Cross-project verification recipes (pilot notes)

Three field rules from driving other projects to end-to-end acceptance (0.3.0 three-repo pilots): (1) projects whose config layer ignores XDG (e.g. openchamber’s hard-coded os.homedir()/.config/...) need HOME overridden as well for isolated runs, or they will write the user’s real config; (2) pin version lines (e.g. an opencode v2 vs 1.18.x fixture break) - isolated installs in the recipe, never the system’s current version; (3) rebuild before browser evidence on source-tree projects (build:web etc.) - a stale dist yields false red/green.

Migration (0.3.0 M5)

Explicit migration for legacy loop state: lzy migrate preview <root> is a read-only preview (draft contracts with authorization NONE; refuses with an active goal); lzy migrate apply <root> runs backup → staging → validation → atomic switch and stamps the .lazyzcode/state.json version entry (written last = commit point). In-flight goals become drafts in drafts/ (authorization NONE — turning one into a real contract needs a fresh UPS approval; old approvals never escalate); finished goals and legacy evidence are preserved byte-exact. Reruns are idempotent per task identity with a phase journal for crash recovery; lzy migrate status is the read-only face. A live lease/process refuses migration; a corrupt or unknown-version goal.json stops before any write; update/sync never migrate automatically (ADR-0029).

From 0.4.0 the state version stamps 0.4.0; older states stay readable, and apply is phase-journaled end to end — a kill during backup/stage/switch is resumed idempotently by rerunning the same command (backup and act side effects are never replayed).

Policy evaluation (0.4.0 M5)

0.4.0 ships a paired evaluation harness (scripts/evaluation/run-pairs.mjs) that measures a candidate against the published baseline on sealed tasks from real repositories: baseline/candidate arms, three trials per task, a pre-registered interruption+resume leg, and an independent sealed oracle that judges the delivered repo. The 0.4.0 batch report — including the honest quality-gate reading (not met; no evidence of quality benefit) and its threat boundaries — lives at docs/reviews/v040-policy-evaluation.md. Evaluation informs adoption decisions; it is never wired to any automatic gate.

Writing scope declarations that qualify (0.4.0)

lzy review qualify challenges a review-scope declaration against ten axes; these patterns keep a declaration grantable instead of refused:

• Declare artifacts by role, not only by path — a dependency artifact you omit must be genuinely unrelated to the duty, otherwise name it canary-keep.
• Cover new files the duty’s fix would plausibly create (unknown-new axis): declare the pattern (directory or suffix), not one exact filename.
• If a file was renamed or deleted since the base run, say so (rename-delete); silence reads as an undeclared change and blocks reuse.
• Lockfiles and generated check scripts are always classified — declare them explicitly when the duty may touch them (lockfile / check-script axes).
• Environment-sensitive surfaces (config read at run time, TZ/locale-dependent output) belong in the declaration: the reuse leg re-checks the environment fingerprint and refuses on drift it cannot attribute (env axis).
• When in doubt, declare narrowly and let lzy review reuse print the per-reason fallback — a refused path names exactly what was missing.

OS sandbox for independent reviews (available since 0.6.0)

This capability shipped in 0.6.0 and is included in 0.6.1. The guarantee depends on the detected platform and authentication tier described below. When the Seatbelt probe passes and an allowed personal API key is available, lzy review run and recheck use the os-sandbox tier, wrapping the engine and its descendants in macOS Seatbelt. Candidate snapshots and factual inputs are read-only; the isolated HOME and tmp are writable. Path metadata queries remain allowed, so file existence is not hidden. An environment allowlist excludes inherited host secrets, NODE_OPTIONS, DYLD settings and proxies. PERSONAL configuration still requires an explicit provider allowlist; BUILTIN templates are copied into the isolated HOME too. Without both tier prerequisites, including Linux/Windows, OAuth-only setups and no enabled allowed key, reviews use app-layer isolation: isolated HOME and facts-only checks remain, authentication uses envAuth or an OAuth credential copy, and there is no OS confinement. The run record’s isolation {level,backend,auth} and doctor disclose the tier. Unreadable or unrecognized provider configuration still refuses launch.

In the os-sandbox tier, network access goes through a parent-process proxy for endpoints from allowed PERSONAL api.baseUrl values or BUILTIN template defaults. Plain HTTP forwarding checks the exact origin. HTTPS permits only CONNECT to the configured hostname:port; it does not inspect TLS SNI, HTTP Host or paths inside the tunnel. DNS addresses are resolved and pinned when the proxy starts, not resolved again per request in this run. Explicitly allowed local/private API endpoints remain reachable. An unresolved endpoint or unavailable proxy refuses sandbox launch. Other drive/queue defaults are unchanged.

Normal exit, timeout and catchable interruption attempt to reclaim the managed process group and credential copies/tmp. Descendants in independent process groups retain OS restrictions in the sandbox tier, but may survive cleanup; ordinary host shell children can use such groups too. After SIGKILL, use lzy doctor to inspect residues and lzy review cleanup <runId> to remove registered configuration copies and tmp only after their owner is no longer alive. This command does not prove all descendants have stopped. Transcripts and usage databases remain. Allowed API credentials are readable by the reviewer and the allowed endpoint can receive data. This is not a container/VM and does not guarantee prevention of all exfiltration, review correctness or a hard spending cap. See ADR-0038.

Goal loop commands

lzy loop register <slug> --title "…" [--tier heavy]   # planning state; tier defaults to light
lzy loop plan <file> [--review "…"] [--force]
lzy loop start                          # records the base tree hash + prints the measured 并发纪律 advisory
lzy loop subject add <path>             # declare a sibling repo root (executing-only; validated: git repo, no containment)
lzy loop subject remove <path>          # remove a subject (missing-deadlock escape; evidence invalidation semantics apply)
lzy loop subject list                   # list the subject set (empty = host-only)
lzy loop tier heavy                     # tier upgrade, one-way (machine gate is adoption-time)
lzy loop claim [<id>] [--release]        # per-step claim (anonymous, 48h mutex); bare lists claimable steps
lzy step done <ID> [--note "…"] [--evidence "…"] [--evidence-file <file>]…
lzy loop status                         # progress, next step, evidence freshness, tier/subjects/snapshot
lzy loop verify                         # evidence freshness audit (exit 1 = stale/unbound); prints per-tree head/dirty lines
lzy evidence red <Fid> --evidence "…"   # red half on its own surface (waive-red --reason = machine exemption)
lzy dag dependents <id|surface>         # "what depends on X" (central ledger, read-only)
lzy dag stale                           # invalidation preview vs current fingerprint (display-only)
lzy attest comparator --file <json>     # comparator verdicts as attestation (HEAVY finish enforces MATCH)
lzy policy show|explain                 # policy identity & obligation set explainer (0.4.0 M1; v1 goals print "not applicable")
lzy gate explain                        # unified read-only gate: per-obligation verdicts + snapshot hash (blocked exits non-zero)
lzy review run [--duty <id>] [--timeout-ms N] [--ack-metering]   # controlled independent review runner (0.4.0 M2): isolated HOME +
                                        # candidate snapshot, structured verdict on record; 0=pass&valid / 1=blocked·invalid / 2=usage / 3=precondition (no spawn)
lzy review cleanup <runId>             # development: reclaim dead-owner credential copies/tmp; keep transcripts/usage DB
lzy review list                         # enumerate review runs on record (read-only; corrupt family fails closed non-zero)
lzy review recheck [--fingerprint <p8>] # independent recheck run (0.4.0 M3): fresh same-duty session + closure candidates
lzy review qualify <runId> --scope <decl.json>  # scope qualification (0.4.0 M4): declare the duty's scope and run the
                                        # adversarial challenge suite (ten axes); GRANTED (0) / REJECTED-but-recorded (1); zero points (no spawn)
lzy review reuse <runId>                # reuse applicability (0.4.0 M4): classify the current candidate against the base
                                        # snapshot path by path; all-unrelated = applicable (0) / any declared, unknown or
                                        # structural-axis drift = fallback with per-reason lines (1); the base run and
                                        # qualification records stay byte-identical (append-only judgment)
lzy finding list|show|resolve-request|close|diagnose|relink|reopen
                                        # findings ledger (0.4.0 M3/M4): unclosed blocking findings survive
                                        # reset/supersede; closure only via resolve-request → recheck → close;
                                        # reopen = controlled re-entry when the closure basis went stale
                                        # (closed → resolve-requested, append-only events, history preserved)
lzy review show <runId>                 # field-by-field + findings table + raw output pointer (read-only)
lzy loop finish                         # the final gate: all done + fresh evidence + all trees clean (+ HEAVY: MATCH attestation); writes the final attestation and auto-archives
lzy loop export                         # re-export the evidence bundle
lzy loop handoff --snapshot <file>      # register a clean handoff; next Stop releases once
lzy loop cost                           # points report (standing coefficients + promo overlay, read-only)
lzy loop list [--root <dir>]            # read-only sweep of sibling repos' goal loops
lzy loop history                        # goal lineage (evidence ∪ stubs ∪ trailers, read-only)
lzy loop abandon | lzy loop reset       # give up / clear state

• lzy loop plan parses the N/F checklist and rejects undecided (TBD) items. Pass the plan-reviewer verdict with --review "plan-reviewer: PASS …"; a REVISE verdict is refused even with --force, and for HEAVY goals (persisted tier) adoption without a PASS verdict is machine-rejected. Adoption must also pass the human gate (0.1.1, ADR-0018): the first run is rejected with a short code (first 8 hex of the planHash) — relay the exact sentence 「批准 <短码>」 to the user and wait for their reply (the approval record is written only by the UserPromptSubmit hook on a genuine user message; the model running commands or hand-writing files never counts), then re-run adoption. Editing the plan file after approval voids it — the next adoption issues a fresh code. Both tiers are gated. Adoption snapshots the plan into `.lazyzcode/loop/snapshots/.md` and binds `goal.planHash` (review records carry it too — the review binds the reviewed artifact; re-adopting an amended plan requires a fresh review). A `deps: N1,N2` line right after an item declares prerequisites — ids must exist, and self-loops, cycles, or orphan `deps:` lines are rejected (quoting the syntax in prose? end that line with ``).
• lzy loop start freezes the base tree hash; drift is reported against it. It also prints a 并发纪律 line — a subagent parallelism cap computed from your measured 429 data (see rate-limit discipline).
• lzy step done on an F item without --evidence is refused. Re-running with new evidence re-binds it (marked ↻ re-captured). --evidence-file (repeatable, ≤4 per F item) attaches the capture itself — screenshots, response dumps; lzy copies each file into .lazyzcode/evidence/ and binds its sha256 next to the tree hash.
• lzy loop finish archives an evidence bundle to .lazyzcode/evidence/<slug>.report.md (review verdict, step notes, F-item evidence with attachments) — atomically: the report is written before the goal flips to done, so a failed archive leaves the goal executing with a recovery path instead of a done state with no report. The integrity gate additionally requires every {host}∪subjects root clean — dirty, missing, or git-error roots all reject (no bypass flag). lzy loop export re-exports any time.
• lzy loop verify is the audit-only variant of the finish gate (exit 1 when evidence is stale or unbound, or when no goal exists).
• lzy loop claim provides anonymous per-step claiming for same-goal multi-worker runs: 48h mutual exclusion, blocked-step rejection against the plan’s deps: edges, lzy step done auto-releases, --release frees early, and the bare form lists claimable steps (lzy loop status marks [claimed]/[blocked: …]).
• lzy loop handoff --snapshot <file> registers a clean handoff: the next Stop consumes the marker once and releases the session without spending the continue budget (the goal stays executing; state lives on disk). The snapshot must exist, have been modified within 2h, and contain all seven mandatory sections (remaining steps / next action / goal & progress / dirty-tree list / tree hash / risks / resume command — missing or empty sections are rejected; template in zw’s Continuation section). lzy loop reset sweeps a leftover marker (abandon leaves it; reset before re-registering). Each registration and consumption increments anonymous counters in .lazyzcode/loop/metrics.json (registered/consumed, no session identity); they survive reset and surface in lzy status/lzy loop status.
• lzy loop risk <level> records the goal’s risk_class (0.2.0, ADR-0020): low|med|high|restricted, upgrade-only. HIGH/RESTRICTED are barred from unattended lanes (the drive-entry gate enforces; triage self-assessment is still protocol text) — a HIGH+ upgrade mid-flight is the SUSPENDED_RISK signal: wind down and hand back to a human.
• Multi-tree parallelism (each worktree its own slot and goal) is a supported form since 0.2.0: per-tree ledgers are mutually blind (each .lazyzcode/ keeps its own evidence bundles and attestations — survey siblings with lzy loop list --root), while Goal:-trailer commits on unmerged side branches now count in history/salvage/doctor ledger (git log --all).
• lzy loop list is a read-only diagnostic: it scans one level of sibling directories (default anchor: the parent of the current directory, itself included; --root overrides) and prints each repo’s goal slug, status, step progress, claims, staleness and salvage stubs. One unreadable repo never breaks the sweep — it prints a 版本不符 row instead.
• lzy loop abandon gives up while keeping the record; lzy loop reset clears state (including session counters and orphan temp files) so the next loop can start.

The plan gate

Plans are markdown checklists with two item kinds:

- [N1] Implement the export endpoint in src/api/export.ts
- [N2] Add CSV serialization with quoting rules
deps: N1
- [F1] `curl localhost:3000/export` returns 200 and parses as CSV (qa-executor)

• N items (implementation) describe work.
• F items (final verification) name a real surface and the evidence that will be captured on it. A plan without F items does not pass.
• Subjects (optional, multi-tree goals): subjects: <path> header lines — one path per line, header-only (before the first item), relative paths resolve against the host root. Each must exist, be a git repo, and be a sibling (no containment either way with the host). Declared subjects join the evidence fingerprint and the finish gate; any later subject add/remove invalidates all captured F evidence.
• Dependency edges (optional): a bare lowercase deps: line immediately after an item lists case-sensitive N/F ids (deduplicated). Unknown refs, self-loops, cycles, and orphan deps: lines are rejected loudly.
• The plan must be decision-complete: no TBDs, no “decide later”. The gate rejects undecided items at adoption time. (If your plan legitimately needs the literal string, a line-level <!--lzy:allow--> marker exempts it.)
• HEAVY goals (persisted tier) additionally require a plan-reviewer PASS recorded via --review — machine-enforced at adoption: any non-PASS string (including none at all) is rejected and --force cannot bypass it. The reviewer checks decision-completeness, hidden risks, and whether every F item names a capturable surface.

Known unknowns

Decision-complete means no undecided choices — not no unverified premises. A HEAVY plan therefore ends with an explicit known-unknowns section: 1–3 assumptions the plan silently rests on, each with a falsification path (the signal that would prove it wrong, and how to check). Writing “none” is allowed, but must say in one line where you looked.

The section complements the plan gate rather than softening it: it states unverified premises, not postponed decisions — and the gate still scans every line of it, so an actual TBD inside the section is rejected like anywhere else. The plan-reviewer audits it against hidden risks: is every entry falsifiable, and is a “none” credible?

Evidence discipline

• Evidence comes from a real surface: a CLI’s stdout, an HTTP response, a screenshot — not from the model’s own summary, and not merely “tests are green” (a test run is one surface among several).
• Evidence is bound to the composite fingerprint — the sha256 over every {host}∪subjects root’s HEAD tree hash (git rev-parse HEAD^{tree} per root). Commit first, capture after. Uncommitted changes do not count, and any subject root changing — or the subject set itself changing — makes the evidence stale. Legacy evidence (recorded before 0.0.8) compares the single host tree, unchanged.
• Red-green evidence (dual evidence). By default every F-item claim needs two halves: a red capture of the assertion failing on the pre-change state (taken before you edit) and a green capture of it passing after. If no counter-state can be constructed for the surface, say so in a one-line exemption inside the evidence text — an exemption explains, it does not silently skip. Since 0.1.0 a red half may declare its harness (the verification procedure, --harness "<command>"): the hash lands in the ledger and a red/green pair naming different procedures is flagged — and on HEAVY goals refused at finish (INV-08). HEAVY finish also refuses an F item whose anchored green has no red or waiver at all (INV-09): a missing red half cannot be repaired by capturing more green — record the red (even after the fact; the ledger pairs it to the anchored green) or waive it honestly.
• The moment the code changes, old evidence is stale by construction. The finish gate re-checks freshness and rejects stale or unbound evidence.
• Captured material can be archived under .lazyzcode/evidence/.
• The lazyzcode:qa-executor agent exists for this: spawn it to run the capture and report what it actually observed, verbatim.
• Evidence comparison (comparator). Existence and freshness are checked mechanically; whether the evidence actually demonstrates the claim is not — no CLI can read meaning. So HEAVY goals dispatch qa-executor in comparator mode before finish: each F item’s assertion is held against its captured evidence, and a 不匹配 verdict sends you back for a real re-capture (or an honest plan amendment). Proving a slightly different theorem than the one stated is still not proving it.

The continuation budget

ZCode grants each session a shared pool of 3 stop-continuations, which background task notifications also draw from. LazyZCode’s Stop hook spends at most 2 per session, deliberately reserving 1. Counters are isolated per sessionId (a probe that counted globally once hijacked an unrelated session — that constraint is now structural). Any hook error fails open: the loop never traps a session it does not own, and the user’s explicit stop always wins once the budget is spent.

SessionStart re-injects the loop state, so a fresh session continues where the previous one stopped.

Project memory

Planning heavily against a codebase nobody has mapped wastes the plan gate. lazyzcode:init-deep, the plugin’s second skill, builds layered project memory: a root AGENTS.md map plus maps for qualifying subdirectories (build entry points, directories with 40+ files, directories the root already mentions). ZCode reads AGENTS.md natively, so the map rides into every future session — no hook required.

The skill is conservative by contract: it drafts first and writes only after your approval; existing files receive patch suggestions, never overwrites; secrets and machine-local paths stay out. It touches only the AGENTS.md layer — personal lessons go to the host’s native memory at a zw finish.

lzy agents-md lists qualifying directories and coverage gaps; lzy doctor’s agents-md line audits adoption (warn-only: a repo without a root map is skipped, not nagged). HEAVY planning consults the map when one exists.

Unattended

Unattended mode is the same goal loop on a schedule. The engine’s built-in automation wakes a fresh session with zw continue (unattended: …); the wake cadence is off-peak by design — lzy doctor’s schedule line derives an 8-hour window opposite your measured rate-limit concentration hours, then cross-checks it against known platform pricing peaks (GLM / DeepSeek, a static UTC+8 table maintained by hand) and always states the pricing-safe nightly window. The table can go stale — treat the line as measured rate-limit data plus declared pricing, not a guarantee.

The guardrail is structural, not a promise: an unattended session continues the open goal only — it never registers a new goal and never writes or adopts a plan, because the decision-complete gate needs a human. With nothing to continue it exits cleanly, and the wake-up itself is bounded by the continuation budget, fatal-429 handling, serial subagents, and ≥1-hour spacing between runs.

Since 0.2.0 a wake-up also has an in-wake execution channel: lzy loop drive spawns headless engine segments inside one wake and pushes the executing goal segment by segment. Between segments it checks the gates — the run holds a minutes-scale lease (one runtime holder at a time, renewed by heartbeat), each run gets a fresh wall-clock + points budget (the points axis meters this run’s own per-segment session usage — the account-level rolling waterline is a lzy doctor advisory only), and HIGH+ risk goals are machine-rejected before anything spawns. Every segment’s lzy writes carry the run’s fence token, so a taken-over run fails closed on write instead of corrupting loop state. Wind-down is clean and enumerated: done, budget exhausted, segments exhausted, two zero-progress segments (stuck) — plus two wind-down causes that exist only in the dormant H3R prototype’s lane (they never fire with the prototype asleep): the step gate stopping at a high-risk step (h3r), or a high-risk command denied at the tool boundary (PreToolUse) — every non-done wind-down writes the 7-field handoff snapshot itself and registers the marker for the next session. lzy doctor’s drive line reports the channel’s availability on your machine:

lzy loop drive [--wall-ms N] [--max-segments N] [--mode m] [--workers N | --fast]

Workers (0.2.4). lzy loop drive --workers N (or the --fast sugar, N=2) runs N worker chains per wave on sibling worktrees: steps are split by the claim gate, each worker commits inside its own worktree, and the wave ends with a merge back plus a barrier re-anchor of all evidenced F items. A merge conflict winds down cleanly and leaves the branches for a human. Entry requires env-auth and the H3R wake switches to be off; the measured cost is turns ≈2× with small tasks possibly slowing down — read the experiment report (docs/reviews/2026-fast-exp-report.md §1.3) before enabling.

The host automation stays the only scheduled wake face — drive is what runs once awake (and what you can run yourself in an unattended window).

No need to wait for your laptop for the overnight digest: push the results to your own IM bot webhook (zero servers — lzy ships no notification channel of its own). Recipe: unattended notify.

Discipline agents

Three read-only roles ship in the plugin’s agents/ directory and are auto-discovered by the engine. Spawn them via the Agent tool with the role as subagent_type:

All three are read-only: they never edit code, and their value is that their findings come from the repository, not from the main agent’s assumptions.

Hooks & lifecycle

All six commands route through plugin/hooks/run-hook: the engine spawns hooks with its own environment, and a GUI-launched ZCode may have no node on PATH. One manifest line serves both platform families — POSIX shells execute the extensionless run-hook script, while on Windows cmd.exe resolves the same name to the run-hook.cmd twin via PATHEXT. The launcher falls back to nvm (highest version) and Homebrew locations on POSIX (nvm-windows and Program Files on Windows), logs to /tmp/lzy-hook-launcher.log (%TEMP%\lzy-hook-launcher.log on Windows), and exits 0 (fail-open) if everything is missing. lzy doctor’s hook-node check reports the resolved path.

Rate-limit discipline

GLM plans enforce an account-level concurrency limit ([1302] / 429). There is no fixed threshold you can configure around: measured headroom varies by plan tier, time of day, and account state — lzy doctor measures it from your engine logs (last 2 days) and reports deduplicated 429 turns, fatal turns, the longest sustained run, and — when the data is coherent — an empirical concurrency band (“N sessions clean / M sessions collide”). Warn only; it never flips the exit code.

Behavioral rules the zw skill carries:

• One goal loop at a time; parallel main sessions kept few.
• Subagent parallelism is measured, not guessed: lzy loop start prints a 并发纪律 cap from the same data — serial while a hit is recent or the current hour falls in the measured concentration window; ≤2 on a coherent clean band, or when the window has no 429s at all (skill default, independent captures only).
• Risk trumps quota: quota pressure may pick LIGHT at triage; it never lowers a HEAVY risk bar.
• After a fatal 429 (a turn judged dead after the engine’s retries): stop cleanly, wait a few minutes, then zw continue — the loop state survives.
• Transport deaths are a different family: the request never left your machine (ENETDOWN and friends; the engine often mislabels them as non-retryable). Same recovery contract — close cleanly and nothing in .lazyzcode/ is lost; lzy doctor’s transport line keeps a separate tally (never mixed into the quota math).
• Content-moderation kills are a third family: the stream opens fine and the server’s content filter kills it mid-generation (1301 — either the input or the generated text can trip it; the engine often mislabels it as reason=unknown). An in-place retry reproduces deterministically — close cleanly and resume in a NEW session, or rephrase so the model takes a different reasoning path; lzy doctor’s content line keeps a separate tally (never mixed into the quota math).
• Repo-wiki generation shares your pool: the desktop app’s repo-wiki feature runs as a background lane on the same account model quota — while a large repo wiki is generating, avoid stacking dense unattended wake-ups on top of it.

Unattended (host automation): scheduling and the continue-only protocol live in Unattended; the window comes from lzy doctor’s schedule line — your own measured concentration hours cross-checked against declared pricing peaks, not a guess.

CLI reference

Project memory: the lazyzcode:init-deep skill generates a layered AGENTS.md map (root + qualifying subdirectories), drafts first — nothing is written without your approval; lzy doctor patrols coverage on every run.

lzy install                     deploy plugin + registry + official enable
lzy sync [--watch]              re-deploy payload (hot reload; --watch keeps watching)
lzy status                      quick health check (exit 0 = no fail-level findings)
lzy doctor                      deep local diagnostics (zero telemetry)
lzy uninstall                   remove cache + registry entry
lzy loop register <slug> --title <t> [--tier heavy]   create the goal (planning; HEAVY adoption without PASS review is machine-rejected)
lzy loop plan <file> [--review <v>] [--force]   adopt the N/F checklist (snapshots plan + binds planHash)
lzy loop supersede <file> [--review <v>]   forward-only plan change mid-execution (supersedes the attempt, opens attempt+1, gates re-run)
lzy loop start                  planning → executing; records base tree hash + 并发纪律 advisory
lzy loop subject add <path>     declare sibling repo root (executing-only; validated, dedup'd)
lzy loop subject remove <path>  remove a subject (missing-deadlock escape)
lzy loop subject list           list the subject set
lzy loop tier heavy             tier upgrade, one-way (adoption-time machine gate)
lzy loop claim [<id>] [--release]  per-step claim (multi-worker; blocked-step checks; 48h mutex)
lzy loop risk <level>              risk_class upgrade (low|med|high|restricted; one-way; ADR-0020)
lzy loop lease acquire|heartbeat|release|reclaim  run-level lease (minutes-scale mutex; fence token;
                                  reclaim = zombie-lease exit; ADR-0020)
lzy loop budget init|spend|remaining  drive budget (wall-clock + points double cap; ADR-0020)
lzy loop status                 progress, next step, evidence freshness, tier/subjects/snapshot
lzy policy show|explain         policy identity & obligation set explainer (0.4.0 M1; v1 goals print "not applicable")
lzy gate explain                unified read-only gate: per-obligation verdicts + snapshot hash (blocked exits non-zero)
lzy review run|list|show|recheck|qualify|reuse  controlled independent review runner + scope qualification/reuse (0.4.0 M2/M3/M4):
                                run = real review session on isolated HOME + candidate snapshot, verdict on record
                                (0=pass&valid/1=blocked·invalid/2=usage/3=precondition, no spawn);
                                list/show = read-only enumeration & field view; recheck = independent re-verification
                                + close-candidate reconciliation; qualify = declare scope & run the ten-axis
                                adversarial suite; reuse = path-by-path reuse applicability
lzy finding list|show|resolve-request|close|diagnose|relink|reopen
                                findings ledger (0.4.0 M3/M4): unclosed blocking findings block finish and survive
                                reset/supersede/rename; closure only via resolve-request → recheck → close (basis
                                required); two consecutive invalid fixes flip diagnosis-required (diagnose resets);
                                reopen = controlled re-entry when the closure basis went stale (closure-basis-stale)
lzy loop verify                 evidence freshness audit (exit 1 = stale/unbound/no goal); per-tree head/dirty lines
lzy step done <ID> [--note <t>] [--evidence <t>] [--evidence-file <f>]…
lzy loop finish                 final gate: all done + fresh composite fingerprint + all {host}∪subjects trees clean; atomic archive
lzy loop export                 re-export the evidence bundle (<slug>.report.md)
lzy loop cost                   points report (coefficients + promo overlay, read-only)
lzy loop list [--root <dir>]    cross-repo goal-loop sweep (read-only)
lzy loop history                goal lineage (evidence ∪ stubs ∪ trailers, read-only)
lzy loop attempts               attempt lineage (attempt.json ∪ central ledger derivation, read-only)
lzy loop abandon                give up, keep the record
lzy loop reset                  clear loop state (incl. session counters, orphan tmp)
lzy agents-md                   layered AGENTS.md audit (exit 1 = gaps/overcaps)
lzy version                     print version

Flags: --note is capped at 300 chars, --evidence at 4000, --evidence-file is repeatable (≤4 per F item, each ≤20 MB); --force=true and --force are equivalent; --watch=<value> warns (it takes no value).

Diagnostics

lzy status runs the base checks; lzy doctor runs those plus the deeper ones. Exit code: fail findings flip it to 1; warn and skip never do.

State & configuration

LazyZCode has no configuration file. Everything is derived:

Environment: LZY_ZCODE_ENGINE replaces the default engine candidate list (default: /Applications/ZCode.app/Contents/Resources/glm/zcode.cjs). That is the entire configuration surface.

Privacy: zero telemetry; diagnostics are computed locally and printed locally.

Compatibility & limitations

• macOS, Windows, and Linux are supported for engine detection and the full install chain (ADR-0011); the distribution matrix is arm64-live-verified (Windows 11 / Ubuntu ARM VMs), x64 coverage follows the official download matrix by documentation. The CI matrix (node 24 × ubuntu/windows, two legs plus a sqlite-floor job pinned to 24.0.0) stays green on main; three test families are explicitly skipped on win32 (kept until VM verification): SIGTERM kill receipt semantics, gh CLI parsing semantics, and EACCES permission-denial semantics (POSIX permission bits do not apply on win32) — skipped groups are a support boundary, not a verified surface (debt-G recheck 2026-09-25: the CI win32 legs run the rest of the suite green).
• Headless driving of the engine (--prompt) needs the desktop’s injected model credentials; the mechanism is probe-validated, live headless acceptance is deferred.
• One goal loop per project directory, and a finished loop occupies the slot until lzy loop reset. With several sessions in the same directory: a second goal is rejected by register, and a done goal keeps the slot — never reset a goal another session is actively running (that is its executing state; clearing it leaves only a salvage stub). Serial is the default within one tree. To run goals in parallel, give each its own git worktree created outside the host tree (an in-tree worktree dir reads as untracked and blocks the host’s own finish). Multiple sessions on the SAME goal split work per step via lzy loop claim, with one writer committing at a time — any commit invalidates the others’ captured F evidence, and anyone’s uncommitted work blocks everyone’s finish (read lzy loop status for claims and dirt first).
• Trigger matching is deliberately stratified — if you want the loop from mid-sentence, say lazyzcode:zw or ultrawork.
• Upgrading to 0.6.2+ while old writers run: the cross-process usage-ledger lock landed in 0.6.2; writers from earlier releases do not take it, so an in-flight lzy review / harvest append from a pre-0.6.2 process can bypass serialization while you have already upgraded elsewhere. Finish or stop old writers before upgrading. Legacy records without session identities are preserved as-is — reconcile them against the source run archives; ledger history is never rewritten automatically.

Security & trust surface

What LazyZCode runs on your machine, where it installs, and what it deliberately does not defend against:

• Hooks execute local code. Six lifecycle events run this plugin’s local Node scripts (UserPromptSubmit, SessionStart, Stop, PreToolUse, PostToolUse, PostToolUseFailure). Their output is injected context for the model — guidance the model reads, not a sandbox boundary.
• Install footprint is the engine’s official plugin cache. lzy install places the payload there and enabling goes through the engine’s official CLI; LazyZCode never writes your config.json (red line 1).
• Dual distribution chains, user-verifiable. npm: compare the tarball integrity hash with npm view lazyzcode dist.integrity against the shasum printed by the release. Marketplace: the manifest pins a commit sha (pin=sha), so the payload you load is the pinned tree.
• Threat-model boundary (stated plainly): LazyZCode guards against laziness — fake done, silent scope abandonment. It does not defend against a malicious agent: local ledgers, approval records, and continuation counters are readable/writable by any process with your permissions. The enforcement point for integrity claims is the protocol text plus the audit ring, not tamper-proof hardware.

LazyZCode is MIT-licensed. The workflow is inspired by lazycodex (MIT); oh-my-openagent (OmO, SUL-1.0) contributed ideas only. Documentation structure follows the lazycodex docs with credit.