@0xgeorgemathew/zcode 0.4.1 → 0.5.0

package/README.md

@@ -18,8 +18,8 @@ The orchestrator keeps product decisions, design direction, and coordination. zc
 <tr><td><b>Checks run by zcode</b></td><td>zcode runs each <code>--check</code> after the work. A failing check sends its output back to the model for up to 2 repair turns.</td></tr>
 <tr><td><b>Status from evidence</b></td><td><code>completed</code> requires passing checks and no edits outside <code>--owns</code>. The model's own report is kept as a claim.</td></tr>
 <tr><td><b>Sessions</b></td><td>Stable ids, <code>--detach</code>, <code>status</code>, <code>wait</code>, <code>resume</code>, <code>cancel</code>. A session whose process died shows as interrupted and can be resumed.</td></tr>
-<tr><td><b>Parallel work</b></td><td>Two sessions with overlapping <code>--owns</code> in one repo are refused with exit 7.</td></tr>
-<tr><td><b>Output</b></td><td>One <code>zcode.result/1</code> JSON line with <code>--json</code>. No colour codes when stdout is not a terminal.</td></tr>
+<tr><td><b>Parallel work</b></td><td>Two sessions with overlapping <code>--owns</code> in one repo are refused with exit 7. Every session gets its own port, output dir and tmp dir (<code>ZCODE_PORT</code>, <code>ZCODE_OUT</code>, <code>ZCODE_TMP</code>).</td></tr>
+<tr><td><b>Output</b></td><td>With <code>--json</code>, one compact <code>zcode.brief/1</code> result line (<code>--full</code> for the whole <code>zcode.result/1</code> record). Timeouts and usage errors are one line. No colour codes when stdout is not a terminal.</td></tr>
 </table>
 
 &nbsp;
@@ -30,13 +30,22 @@ The orchestrator keeps product decisions, design direction, and coordination. zc
 npm install -g @0xgeorgemathew/zcode
 echo "$ZAI_API_KEY" | zcode login    # stores your Z.AI key with mode 600; zcode never prints it
 zcode doctor                         # checks the engine, isolation and key
+zcode skills install                 # optional: teach Claude Code and Codex to delegate to zcode
 
 zcode task --check "npm test" "Fix the off-by-one in src/paginate.ts"
 ```
 
 The CLI needs node 20 or later. The engine child runs best on node 26. zcode also needs the ZCode engine, which today ships inside the ZCode desktop app; zcode finds it automatically.
 
-Installing the package also installs the Claude Code skill to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`. These skills teach the orchestrator how to delegate to zcode. Set `ZCODE_SKIP_SKILLS=1` to skip this step. Details are in [`skills/`](skills/README.md).
+The package ships skills that teach Claude Code and Codex how to delegate to zcode. Install them with one command:
+
+```sh
+zcode skills install          # both; or: zcode skills install claude | codex
+zcode skills                  # show what is installed and where
+zcode skills uninstall        # remove them
+```
+
+The Claude Code skill goes to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`. The package runs no install scripts. Details are in [`skills/`](skills/README.md).
 
 &nbsp;
 
@@ -47,13 +56,13 @@ Every command runs on GLM-5.3-Flash at effort `max` unless you pass a flag.
 | setting | flag | values | default |
 |---|---|---|---|
 | model | `--model` | `glm-5.3-flash` (aliases `flash`, `5.3-flash`, `53f`), `glm-5.3` (aliases `5.3`, `53`) | `glm-5.3-flash` |
-| effort | `--effort` | `low`, `medium`, `high`, `xhigh`, `max` | `max` |
+| effort | `--effort` | `low`, `high`, `max` (the engine's levels for both models; `zcode doctor` lists them) | `max` |
 
 ```sh
 zcode task "..."                                   # GLM-5.3-Flash, effort max
 zcode task --effort high "..."                     # Flash with less reasoning
 zcode task --model glm-5.3 "..."                   # GLM-5.3, effort max
-zcode task --model glm-5.3 --effort medium "..."   # GLM-5.3, effort medium
+zcode task --model glm-5.3 --effort high "..."     # GLM-5.3, effort high
 ```
 
 A task contract can set `"model"` and `"effort"`. Flags override the contract. A resumed session keeps its original model and effort unless you pass the flags again.
@@ -87,7 +96,7 @@ not verified
   - prose acceptance criteria are confirmed only by the executor's own report
 ```
 
-That block is the format of the summary printed to stdout. The live feed (session header, phases, tools, subagents, check results) goes to stderr. With `--json` you get the same data as one machine-readable result line.
+That block is the format of the summary printed to stdout. The live feed (session header, phases, tools, subagents, check results) goes to stderr. With `--json` you get the compact brief as one machine-readable result line (see Machine interface).
 
 For small work, the objective alone is enough: `zcode task "Fix the typo in the README heading"`.
 
@@ -100,7 +109,7 @@ Flags cover the common fields. For richer handoffs, pass `--task contract.json`,
   "objective": "Implement page 2 (Team) per the design spec",
   "scope": ["Team page route and its components"],
   "constraints": ["No new dependencies", "Keep existing routing untouched"],
-  "design": ["Grid of 3 columns ≥1024px, 1 column below", "Use tokens from src/theme.ts only"],
+  "decisions": ["Grid of 3 columns ≥1024px, 1 column below", "Use tokens from src/theme.ts only"],
   "acceptance": ["Every member card shows name, role, avatar"],
   "checks": ["npm run build", "npm test -- team"],
   "files": ["src/theme.ts", "src/pages/home/index.tsx"],
@@ -113,7 +122,15 @@ Flags cover the common fields. For richer handoffs, pass `--task contract.json`,
 }
 ```
 
-`design` entries are presented to the model as binding decisions it must implement, not revisit. If the model hits a consequential product or design question the contract does not answer, it reports `blocked` with its questions instead of guessing.
+`decisions` (flags `--decision "…"`, repeatable, and `--decisions @file`; `design` is an alias) are presented to the model as binding decisions it must implement, not revisit. `@file` entries inside contract `decisions`/`context` lists are inlined (relative to the contract file). If something user-visible or behavioural is left open, the executor does not guess: when it blocks the work it reports `blocked` with a structured question `{"q", "options": [...], "recommend"}` (plain strings still work); when it does not block, it takes the most conservative choice and lists it in the handback `decisions: [{what, why}]`, which the brief carries so the orchestrator can overrule it.
+
+A file passed with `--file` and also inlined with `--context @file` reaches the executor once (as context); identical context and acceptance entries are deduped.
+
+**Preflight.** `--preflight` runs a read-only turn over the same contract: the executor lists every open question it would otherwise guess and makes no edits; zcode runs no checks. The result is `blocked` with `questions`, or `completed` with summary `no open questions`; any changed file fails it (`preflight_wrote`). The session is recorded as a preflight; `zcode resume <id> "<answers>"` then switches it to execution: the answers plus the full task protocol go to the executor, and checks and visual verification run as usual.
+
+**Units.** `--unit "name: objective [owns a,b]"` (repeatable; contract `units: [{name, objective, owns?}]`) makes the executor dispatch each unit to its own subagent inside this one session, in parallel where independent, then integrate and verify the whole. Unit `owns` must lie within the session's `--owns` and be disjoint from each other (exit 2 otherwise). The handback `units: [{name, status, note}]` is listed under `notVerified` as executor claims; zcode's checks still verify the integrated result.
+
+**Visual verification.** `--visual "criterion"` (repeatable; contract `visual`), `--viewport WxH` (repeatable, default `390x844` and `1440x900`; contract `viewports`) and `--serve "cmd"` (contract `serve`; must honour `$ZCODE_PORT`, default: the executor reads `package.json`) have the executor serve the app on `$ZCODE_PORT`, capture Playwright screenshots into `$ZCODE_OUT/shots` at each viewport, look at them, fix and re-capture, and report `visual: [{criterion, viewport, met, note, shot}]`. zcode runs no pixel check: results are executor judgement (`notVerified`). Unmet criteria spend the repair budget like failing checks (one combined repair turn when both occur); still unmet afterwards, the result is `partial` with the issue `visual criteria unmet: …`. Without `--visual` nothing changes.
 
 ### Status: what a result means
 
@@ -140,6 +157,8 @@ zcode task --detach --id page-2 --owns src/pages/team/ --check "npm run build" "
 zcode status                 # all sessions: id, state/status, kind, updated, label
 zcode status page-1 --json   # one session: state, phase, activity, recent events, result
 zcode wait page-1 page-2     # block until both finish; print each handback
+zcode wait page-1 page-2 --any   # return as soon as the first one finishes
+zcode result page-1          # a finished session's handback, without waiting
 zcode resume page-2 "Use the 2-column variant below 1024px."   # answer / follow up / retry
 zcode cancel page-1          # stop the turn and any running check; recorded as cancelled
 ```
@@ -157,6 +176,34 @@ zcode cancel page-1          # stop the turn and any running check; recorded as
 - After the work, zcode diffs the workspace and reports each changed file. Changes outside the session's ownership are listed in `scopeViolations`, and for task sessions they make the result `partial`. Files that fall in a concurrent session's ownership are attributed to that session, not counted against this one.
 - For overlapping or risky parallel work, give each session its own git worktree via `--cwd`.
 - `ZAI_CODE_MAX_ACTIVE` (default 8) is a soft machine-wide cap. Sessions beyond it wait in `queued`.
+- **Session environment.** Every session's executor and every check run with `ZCODE_SESSION_ID`, `ZCODE_PORT` (a free TCP port from 41000-48999, reserved per session and unique among live sessions, also recorded in the session), `ZCODE_OUT` (`<cwd>/.zcode/out/<id>`, created) and `ZCODE_TMP` (a per-session scratch dir). The task prompt tells the executor to use them for dev and preview servers, build output dirs and test artifacts, so parallel sessions cannot collide on a port or a `dist/`. Files under `.zcode/` never count as changes or scope violations; add `.zcode/` to the `.gitignore` of repos you run zcode in.
+- **`--touch <path|glob>`** (repeatable; contract key `touch`) allows minimal edits outside `--owns` without declaring ownership. Touched files are listed in `touched` and are not scope violations, so one stray line in a shared stylesheet no longer blocks a session. Starting is refused with exit 7 if a running session owns a matching path; a touch reserves nothing, so it never blocks another session's `--owns`.
+
+### Plans: several sessions with dependencies
+
+`zcode plan` runs a set of task sessions as one unit, in dependency order, and returns a single summary.
+
+```json
+{ "decisions": ["@decisions.md"], "context": ["@brief.md"], "effort": "high",
+  "sessions": [
+    { "id": "tokens", "objective": "Design tokens", "owns": ["src/tokens/**"], "checks": ["npm run lint"] },
+    { "id": "home",   "objective": "Home page", "after": ["tokens"], "owns": ["src/home/**"] },
+    { "id": "team",   "objective": "Team page", "after": ["tokens"], "owns": ["src/team/**"] }
+  ] }
+```
+
+Optional top-level keys: `cwd` (relative to the plan file), `decisions`, `context`, `files` (prepended to every session; `@file` entries are read relative to the plan file), `model`, `effort`. Each session has an `id` (its zcode session id), optional `after` (ids) and any task contract keys.
+
+```sh
+zcode plan check plan.json              # validate: exit 2, one line per problem
+zcode plan run plan.json --preflight    # read-only questions per session (<id>.pre); exit 10 if any
+zcode plan run plan.json --detach       # supervise in the background
+zcode plan wait plan   --json --timeout-ms 600000   # one line; exit 124 on timeout
+zcode plan status plan                  # one line per session
+zcode plan resume plan "answers…"       # resume failed/partial/blocked sessions, relaunch skipped ones
+```
+
+A session starts once everything it is `after` has completed; sessions that can run together must own disjoint paths (`plan check` enforces it). A session that ends without completing marks its downstream `skipped` while the others continue. The summary is `{"type":"plan","name","status","sessions":[{"id","status"}],"briefs":[…]}` with a brief for each finished session that did not complete. Exit codes: 0 completed, 10 blocked, 8 partial or failed, 124 timeout. Plan status is derived from the sessions, so it stays accurate even if the supervisor process dies; `plan resume` restarts it. The plan name is the file's basename (`--id` overrides); ids that already exist as sessions are refused, so re-run through `plan resume`.
 
 &nbsp;
 
@@ -180,6 +227,18 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
 
 `--json`: stdout carries NDJSON events, then exactly one final `{"type":"result",…}` line. With `--quiet`, the result line is the only output. For task sessions, text/reasoning deltas are left out of the events unless you pass `--stream`, so an orchestrator reading the output pays only for lifecycle events.
 
+The final line is the compact **brief** (`zcode.brief/1`), sized for an orchestrator that spends tokens on decisions. Keys with empty values are omitted:
+
+```json
+{"type":"result","schema":"zcode.brief/1","status":"failed","ok":false,"id":"page-1","label":"home",
+ "summary":"…(≤600 chars)…","files":["src/pages/home/index.tsx"],
+ "checks":[{"command":"npm run lint","ok":true},{"command":"npm test","ok":false,"exitCode":1,"tail":"…last 1500 chars…"}],
+ "questions":[],"issues":["…"],"unresolved":[],"scopeViolations":[],"error":{"kind":"checks_failed"},
+ "result":"/…/sessions/page-1/result.json"}
+```
+
+`run` and `agent` briefs also carry `response`, because the text answer is the product there. Passing checks are reduced to `{command, ok:true}`; a failing check carries `exitCode`, `timedOut` and the last 1500 characters of its output as `tail`. `result` is the path to the full record: `result.json` on disk is always the full `zcode.result/1` record, and `--full` prints that same record instead of the brief (on `task`/`run`/`agent`/`resume`/`wait`/`result`):
+
 ```json
 {"type":"result","schema":"zcode.result/1","ok":true,"status":"completed","id":"page-1","kind":"task",
  "summary":"…","response":"…executor report…","issues":[],"questions":[],"unresolved":[],"notVerified":[],
@@ -192,7 +251,7 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
  "toolCalls":14,"durationMs":142301,"files":{"session":"…/sessions/page-1","result":"…/result.json","events":"…/events.ndjson"}}
 ```
 
-`model` and `effort` are engine-reported (from the engine's `model_request_started` event), not echoes. `sessionId` is the engine's session id; `id` is the zcode session id you pass to `status`, `wait`, `resume`, and `cancel`. A run that fails still ends with a parseable result line.
+`model` and `effort` are engine-reported (from the engine's `model_request_started` event), not echoes. `sessionId` is the engine's session id; `id` is the zcode session id you pass to `status`, `wait`, `result`, `resume`, and `cancel`. A run that fails still ends with a parseable result line.
 
 | event | meaning |
 |---|---|
@@ -204,7 +263,7 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
 | `{"type":"mcp","name","status"}` · `{"type":"retry",…}` · `{"type":"model_request_started",…}` | MCP settling, start-up retry, engine model evidence |
 | `{"type":"stream","kind":"text_delta\|reasoning_delta","delta"}` | live text (run/agent; task with `--stream`) |
 
-`zcode status <id> --json` returns `{"type":"status", state, status, phase, pid, live, activity, recent:[…], result?}`. `zcode wait --json` prints one result line per session as each finishes.
+`zcode status <id> --json` returns `{"type":"status", state, status, phase, pid, live, activity, recent:[…], result?}`. `zcode wait --json` prints one brief per session as each finishes (`--full`: full records; `--any`: stop at the first). When `--timeout-ms` elapses first it prints exactly one line per session still running, `{"type":"pending","id","state","phase","elapsedMs"}` (human mode: `<id> <state> <phase> 12m`), and exits 124. `zcode result <id> [--json] [--full]` prints a finished session's handback without waiting (exit 7 if it is still running). `zcode status` without an id is one line per session. Usage errors are always a single line (`zcode: unknown flag (did you mean …?)` for a mistyped option), never the help text.
 
 &nbsp;
 
@@ -216,23 +275,30 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
 | `--detach` | run, task, agent, resume | off | background worker; prints the id |
 | `--cwd` | run, task, agent | current dir | the workspace and blast radius |
 | `--owns` | run, task, agent | whole workspace | repeatable path or glob |
+| `--touch` | task | | repeatable; minimal edits outside `--owns`, reported as `touched` |
 | `--allow-overlap` | run, task, agent | off | start despite overlapping ownership |
 | `--task` | task | | JSON contract, markdown brief, or `-` |
-| `--accept`, `--check`, `--file`, `--context` | task | | repeatable; `--context @file` reads a file |
+| `--accept`, `--check`, `--file`, `--context` | task | | repeatable; `--context @file` reads a file (a `--file` also inlined this way is listed once) |
+| `--decision`, `--decisions` | task | | repeatable binding decisions; `--decisions @file` reads a file |
+| `--preflight` | task | off | read-only turn that returns the open questions; `resume <id> "<answers>"` then executes |
+| `--unit` | task | | repeatable `"name: objective [owns a,b]"`; one subagent per unit |
+| `--visual`, `--viewport`, `--serve` | task | viewports `390x844`, `1440x900` | executor screenshots the app with Playwright and judges each criterion |
 | `--max-repairs` | task, resume | `2` | repair turns after failing checks |
 | `--check-timeout-ms` | task, resume | `300000` | per check; checks get `CI=1` when unset |
 | `--model` | all turns | `glm-5.3-flash` | `glm-5.3` plus aliases `5.3`, `53`, `flash`, `5.3-flash`, `53f` |
-| `--effort` | all turns | `max` | `low`, `medium`, `high`, `xhigh`, `max` |
+| `--effort` | all turns | `max` | the model's levels: `low`, `high`, `max` |
 | `--timeout-ms` | all turns; wait | run 600000, task 1800000 | the whole invocation incl. checks and repairs |
 | `--session` | run | | 0.3 compat: continue by zcode id or engine `sess_` id |
 | `--profile` | agent | `general-purpose` | subagent profile |
-| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic | MCP servers (inline JSON or `@file`) |
+| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic, plus the desktop's `playwright` | MCP servers (inline JSON or `@file`) |
+| `--no-browser` | run, task, agent | off | Drop the desktop's `playwright` MCP server |
 | `--skills` / `--no-skills` | run, task, agent | desktop skills | add skills; or run with none |
-| `--json`, `--quiet` | all | | see Machine interface |
+| `--json`, `--full`, `--quiet` | all | | see Machine interface |
+| `--any` | wait | off | return when the first listed session finishes |
 | `--thinking` / `--no-thinking` | turns | run on, task off | mirror reasoning to stderr |
 | `--stream`, `--include-reasoning` | turns | off | deltas in task events; full reasoning in the result |
 
-Only `glm-5.3` and `glm-5.3-flash` are accepted; anything else exits 2 before any spawn. Effort levels `low`, `high`, and `max` have been observed live on Flash. `medium` and `xhigh` may be rejected server-side.
+Only `glm-5.3` and `glm-5.3-flash` are accepted; anything else exits 2 before any spawn. The effort levels each model accepts are read from the engine's builtin provider config (`zcode doctor --json` lists them as `models`; a built-in table is the fallback). An unsupported model and effort pair, whether from `--effort`, the task contract, or a resumed session's stored setting, exits 2 with one line naming the supported values, before any engine is spawned.
 
 ## Exit codes
 

package/bin/zcode.js

@@ -10,10 +10,20 @@ const USAGE = `usage:
   zcode agent [options] <instructions…> turn that MUST dispatch a subagent
   zcode resume <id> [message…]         continue a session (answer, follow-up, retry)
   zcode status [<id>] [--json]         one session in detail, or all sessions
-  zcode wait <id…> [--json]            block until sessions finish; print handbacks
+  zcode wait <id…> [--any] [--json]    block until sessions finish; print handbacks
+  zcode result <id> [--full] [--json]  print a finished session's handback (brief by default)
   zcode cancel <id> [--json]           stop a running session
+  zcode plan check <file>              validate a plan file (ids, after, cycles, owns, effort)
+  zcode plan run <file> [--preflight] [--detach] [--timeout-ms n] [--id name] [--json]
+                                       run a DAG of task sessions (see "plan" below)
+  zcode plan wait|status <name> [--timeout-ms n] [--json]
+                                       one summary line: {type:"plan",name,status,sessions,briefs}
+  zcode plan resume <name> [message…] [--session <id>]
+                                       resume failed/partial/blocked sessions, restart supervision
   zcode login                          read API key from stdin → credentials
   zcode doctor [--json]                engine + isolation + key report
+  zcode skills [install|uninstall] [claude|codex]
+                                       install the orchestrator skills (default: status)
 
 session:
   --id <id>             name the session (letters, digits, . _ -); default zc-<random>.
@@ -30,26 +40,65 @@ task contract (task only):
   --task <file|->       JSON contract or markdown brief (- = stdin)
   --accept <text>       repeatable acceptance criterion
   --check <command>     repeatable shell check zcode runs after the work
-  --file <path>         repeatable relevant file to read first
-  --context <text|@f>   repeatable extra context (design decisions, references)
+  --touch <path|glob>   repeatable: minimal edits allowed outside --owns; reported
+                        as "touched", not a scope violation. Refused (exit 7) if a
+                        running session owns a matching path; reserves nothing
+  --file <path>         repeatable relevant file to read first (a file also given
+                        as --context @file is inlined once, not listed twice)
+  --context <text|@f>   repeatable extra context (references, background)
+  --decision <text>     repeatable binding decision the orchestrator made (the
+                        executor implements it exactly and must not guess others)
+  --decisions <@f|text> binding decisions from a file (same list as --decision)
+  --preflight           read-only turn: the executor lists the open questions it
+                        would otherwise guess (blocked + questions, or completed
+                        "no open questions"); no edits, no checks. Then
+                        zcode resume <id> "<answers>" executes the task
+  --unit "n: goal [owns a,b]"  repeatable: one subagent per unit inside this
+                        session; owns must lie within --owns and be disjoint
+  --visual <criterion>  repeatable: the executor serves the app on $ZCODE_PORT,
+                        screenshots it with Playwright and judges each criterion
+  --viewport <WxH>      repeatable viewport for --visual (default 390x844, 1440x900)
+  --serve <cmd>         command that serves the app for --visual (honours $ZCODE_PORT)
   --max-repairs <n>     repair turns after failing checks (default 2)
   --check-timeout-ms <n> per-check timeout (default 300000)
 
+plan (zcode plan run <plan.json>):
+  plan.json             {cwd?, decisions?, context?, files?, model?, effort?,
+                        sessions:[{id, after?:[ids], ...task contract keys}]}; the
+                        top-level decisions/context/files are prepended to every
+                        session. A session starts when everything it is "after" has
+                        completed; sessions that can run together must own disjoint
+                        paths. A session ending non-completed marks its downstream
+                        "skipped"; the others continue
+  --preflight           plan run: read-only preflight of every session ("<id>.pre"),
+                        prints the questions as one brief per session (exit 10 if any)
+  --detach              plan run/resume: supervise in a background process
+  --id <name>           plan name (default: the file's basename)
+  --session <id>        plan resume: only this session
+
 execution:
   --model <id>          glm-5.3 | glm-5.3-flash (+aliases). default: glm-5.3-flash
-  --effort <level>      low | medium | high | xhigh | max. default: max
+  --effort <level>      low | high | max for both models (zcode doctor lists the
+                        engine's levels per model); an unsupported level exits 2
+                        before any spawn. default: max
   --timeout-ms <n>      whole invocation incl. checks/repairs (default 600000;
                         task default 1800000)
   --profile <name>      subagent profile (agent command; default general-purpose)
   --mcp <json|@f>       add MCP servers (repeatable); hermetic by default
   --mcp-inherit         also inherit the desktop's enabled MCP servers
+  --no-browser          drop the desktop's playwright MCP server (on by default)
   --mcp-list            print the effective MCP server set as JSON and exit
   --skills <dir>        add skills (repeatable): one skill dir or a root of them
   --no-skills           empty skill set
 
 output:
-  --json                NDJSON events on stdout; final line {"type":"result",…}
-  --quiet               no progress: no stderr feed; with --json only the result line
+  --json                NDJSON events on stdout; final line is the compact brief
+                        {"type":"result","schema":"zcode.brief/1",…}
+  --full                with --json (and result/wait): the full record instead
+                        (schema zcode.result/1; result.json on disk is always full)
+  --any                 wait: return as soon as the FIRST id finishes
+  --quiet               no progress: no stderr feed; with --json only the result line;
+                        usage errors are always a single line
   --thinking / --no-thinking   mirror reasoning to stderr (run: on, task: off)
   --stream              task --json: include text/reasoning deltas in the events
   --include-reasoning   full reasoning text in the result
@@ -94,9 +143,10 @@ function parseMcpSpec(value) {
   return parsed;
 }
 
-const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', '__exec']);
-const TASK_ONLY = new Set(['task', 'accept', 'check', 'file', 'context', 'maxRepairs', 'checkTimeoutMs']);
-const START_ONLY = new Set(['id', 'label', 'owns', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
+const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', 'skills', 'result', 'plan', '__plan', '__exec']);
+const TASK_ONLY = new Set(['task', 'accept', 'check', 'file', 'context', 'touch', 'maxRepairs', 'checkTimeoutMs', 'decisions', 'units', 'visual', 'viewports', 'serve', 'preflight']);
+const FULL_COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'wait', 'result', '__exec']);
+const START_ONLY = new Set(['id', 'label', 'owns', 'touch', 'preflight', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'noBrowser', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
 
 function parseArgv(argv) {
   const out = {
@@ -122,11 +172,19 @@ function parseArgv(argv) {
       file: [],
       context: [],
       owns: [],
+      touch: [],
+      decisions: [],
+      units: [],
+      visual: [],
+      viewports: [],
+      serve: undefined,
+      preflight: false,
       allowOverlap: false,
       maxRepairs: undefined,
       checkTimeoutMs: undefined,
       mcpSpecs: [],
       mcpInherit: false,
+      noBrowser: false,
       mcpList: false,
       skillsDirs: [],
       noSkills: false,
@@ -134,24 +192,29 @@ function parseArgv(argv) {
       quiet: false,
       thinking: undefined,
       stream: false,
+      full: false,
+      any: false,
     },
   };
   const valueFlags = new Map([
     ['--model', 'model'], ['--effort', 'effort'], ['--cwd', 'cwd'], ['--profile', 'profile'],
     ['--timeout-ms', 'timeoutMs'], ['-p', 'prompt'], ['--prompt', 'prompt'], ['--session', 'session'],
     ['--id', 'id'], ['--label', 'label'], ['--task', 'task'], ['--max-repairs', 'maxRepairs'],
-    ['--check-timeout-ms', 'checkTimeoutMs'],
+    ['--check-timeout-ms', 'checkTimeoutMs'], ['--serve', 'serve'],
   ]);
   const listFlags = new Map([
     ['--mcp', 'mcpSpecs'], ['--skills', 'skillsDirs'], ['--accept', 'accept'], ['--check', 'check'],
-    ['--file', 'file'], ['--context', 'context'], ['--owns', 'owns'],
+    ['--file', 'file'], ['--context', 'context'], ['--owns', 'owns'], ['--touch', 'touch'],
+    ['--decision', 'decisions'], ['--decisions', 'decisions'], ['--unit', 'units'], ['--visual', 'visual'],
+    ['--viewport', 'viewports'],
   ]);
   const boolFlags = new Map([
     ['--json', ['json', true]], ['--fresh', ['fresh', true]], ['--mcp-inherit', ['mcpInherit', true]],
-    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]],
+    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]], ['--no-browser', ['noBrowser', true]],
     ['--include-reasoning', ['includeReasoning', true]], ['--quiet', ['quiet', true]],
     ['--detach', ['detach', true]], ['--allow-overlap', ['allowOverlap', true]],
     ['--thinking', ['thinking', true]], ['--no-thinking', ['thinking', false]], ['--stream', ['stream', true]],
+    ['--full', ['full', true]], ['--any', ['any', true]], ['--preflight', ['preflight', true]],
   ]);
   const numeric = (flag, value, { min = 1 } = {}) => {
     const n = Number(value);
@@ -164,7 +227,7 @@ function parseArgv(argv) {
     if (valueFlags.has(arg) || listFlags.has(arg)) {
       const key = valueFlags.get(arg) || listFlags.get(arg);
       const value = argv[++i];
-      if (value === undefined) fail(2, `option ${arg} requires a value.\n${USAGE}`);
+      if (value === undefined) fail(2, `option ${arg} requires a value.`);
       out.given.add(key);
       if (key === 'timeoutMs' || key === 'checkTimeoutMs') out.flags[key] = numeric(arg, value);
       else if (key === 'maxRepairs') out.flags[key] = numeric(arg, value, { min: 0 });
@@ -172,8 +235,6 @@ function parseArgv(argv) {
       else if (key === 'skillsDirs') {
         if (!isDirectory(value)) fail(2, `--skills requires an existing directory, got "${value}".`);
         out.flags.skillsDirs.push(value);
-      } else if (key === 'context') {
-        out.flags.context.push(value.startsWith('@') ? readFileOrFail(value.slice(1), '--context') : value);
       } else if (listFlags.has(arg)) out.flags[key].push(value);
       else if (!value.trim()) fail(2, `${arg} requires a non-empty value.`);
       else out.flags[key] = value.trim();
@@ -197,7 +258,10 @@ function parseArgv(argv) {
       out.prompts.push(...argv.slice(i + 1));
       break;
     }
-    if (arg.startsWith('--') && arg.length > 2) fail(2, `unknown option "${arg}".\n${USAGE}`);
+    if (arg.startsWith('--') && arg.length > 2) {
+      const hint = suggestFlag(arg, [...valueFlags.keys(), ...listFlags.keys(), ...boolFlags.keys()]);
+      fail(2, `unknown flag ${arg} (${hint ? `did you mean ${hint}?` : 'see zcode --help'})`);
+    }
     if (out.prompts.length === 0 && out.command === 'run' && !out.commandSet && COMMANDS.has(arg)) {
       out.command = arg === 'list' ? 'status' : arg;
       out.commandSet = true;
@@ -210,17 +274,25 @@ function parseArgv(argv) {
   if (out.flags.prompt !== undefined) out.prompts.unshift(out.flags.prompt);
   if (cmd !== 'task') {
     for (const key of TASK_ONLY) {
+      if (cmd === 'plan' && key === 'preflight') continue;
       if (out.given.has(key) && !(cmd === 'resume' && (key === 'maxRepairs' || key === 'checkTimeoutMs'))) {
         fail(2, `--${flagName(key)} is only valid with "zcode task".`);
       }
     }
   }
+  if (cmd === 'plan' || cmd === '__plan') {
+    for (const key of ['label', 'owns', 'touch', 'allowOverlap', 'model', 'effort', 'profile']) {
+      if (out.given.has(key)) fail(2, `--${flagName(key)} is not valid with "zcode plan"; set it in the plan file.`);
+    }
+  }
   if (cmd === 'resume' || cmd === '__exec') {
     for (const key of START_ONLY) {
       if (out.given.has(key)) fail(2, `--${flagName(key)} cannot change on resume; it is fixed when the session starts.`);
     }
   }
-  if (out.given.has('session') && cmd !== 'run') fail(2, '--session is only valid with "zcode run"; use "zcode resume <id>".');
+  if (out.given.has('any') && cmd !== 'wait') fail(2, '--any is only valid with "zcode wait".');
+  if (out.given.has('full') && !FULL_COMMANDS.has(cmd)) fail(2, `--full is not valid with "zcode ${cmd}".`);
+  if (out.given.has('session') && cmd !== 'run' && cmd !== 'plan') fail(2, '--session is only valid with "zcode run"; use "zcode resume <id>".');
   if (out.given.has('id') && !require('../lib/store.js').validId(out.flags.id)) {
     fail(2, `--id "${out.flags.id}" must be 1-64 chars of letters, digits, ".", "_" or "-", starting with a letter or digit.`);
   }
@@ -235,8 +307,34 @@ function parseArgv(argv) {
   return out;
 }
 
+// Closest known flag by edit distance (<= 2), or null.
+function suggestFlag(arg, known) {
+  const dist = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let prev = row[0];
+      row[0] = i;
+      for (let j = 1; j <= b.length; j++) {
+        const tmp = row[j];
+        row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = tmp;
+      }
+    }
+    return row[b.length];
+  };
+  let best = null;
+  let bestD = Infinity;
+  for (const k of known) {
+    if (!k.startsWith('--')) continue;
+    const d = dist(arg, k);
+    if (d < bestD) { best = k; bestD = d; }
+  }
+  return best && bestD <= 2 ? best : null;
+}
+
 function flagName(key) {
-  return key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`).replace(/^mcp-specs$/, 'mcp').replace(/^skills-dirs$/, 'skills');
+  return key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`).replace(/^mcp-specs$/, 'mcp').replace(/^skills-dirs$/, 'skills')
+    .replace(/^(unit|viewport)s$/, '$1');
 }
 
 function isDirectory(p) {
@@ -257,19 +355,28 @@ async function main() {
     case 'resume':
     case '__exec':
       return require('../lib/commands/exec.js')(parsed);
+    case 'plan':
+    case '__plan':
+      return require('../lib/commands/plan.js')(parsed);
     case 'status':
     case 'wait':
+    case 'result':
     case 'cancel':
       return require('../lib/commands/sessions.js')(parsed);
     case 'login':
       return require('../lib/commands/login.js')(parsed);
     case 'doctor':
       return require('../lib/commands/doctor.js')(parsed);
+    case 'skills':
+      return require('../lib/commands/skills.js')(parsed);
     default:
-      return fail(2, `unknown command "${parsed.command}".\n${USAGE}`);
+      return fail(2, `unknown command "${parsed.command}" (see zcode --help).`);
   }
 }
 
+// Exported before main() runs: the plan supervisor reuses parseArgv.
+module.exports = { parseArgv, USAGE };
+
 if (require.main === module) {
   main().catch((err) => {
     process.stderr.write(`zcode: internal error: ${err && err.stack ? err.stack : err}\n`);
@@ -277,4 +384,3 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseArgv, USAGE };

package/lib/appserver.js

@@ -150,6 +150,17 @@ class AppServerClient {
       if (this.onUserInputRequest) this.onUserInputRequest(frame);
       return;
     }
+    if (method === 'interaction/browserList') {
+      // The desktop app answers with its built-in browser panes; the CLI has
+      // none. An empty list lets the agent fall back to the user's own tools
+      // (Playwright, MCP browsers) instead of failing on a policy error.
+      reply({ browsers: [] });
+      return;
+    }
+    if (method === 'interaction/browserExecute') {
+      replyError(-32000, 'zcode: no built-in browser in the CLI; use Playwright or a browser MCP server');
+      return;
+    }
     // Everything else — incl. interaction/requestOfficialMcpAuthHeaders,
     // proven non-fatal with -32601 — gets method-not-found and the run
     // continues.
@@ -220,8 +231,12 @@ function workspaceKeyFor(workspacePath) {
 // turn always sees the caller's --mcp servers. Inherited servers are
 // best-effort and never block the send.
 async function waitForMcp(client, { workspacePath, required, timeoutMs = 20000, onEvent = () => {} }) {
-  if (!required || required.length === 0) return;
   const ws = { workspace: { workspacePath, workspaceKey: workspaceKeyFor(workspacePath) } };
+  if (!required || required.length === 0) {
+    // Still start inherited servers (the browser server); never block on them.
+    client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 }).catch(() => {});
+    return;
+  }
   try {
     await client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 });
   } catch {

package/lib/bootstrap.js

@@ -55,11 +55,11 @@ function resolveRuntime(env = process.env) {
   };
 }
 
-function makeClient(runtime, { home, cwd }) {
+function makeClient(runtime, { home, cwd, sessionEnv = {} }) {
   return new AppServerClient({
     nodeBin: runtime.nodeBin,
     enginePath: runtime.enginePath,
-    env: engineEnv({ home, builtinProviderConfig: runtime.builtinConfig }),
+    env: engineEnv({ home, builtinProviderConfig: runtime.builtinConfig, sessionEnv }),
     cwd,
     scrub: runtime.scrub,
   });

package/lib/brief.js

@@ -0,0 +1,69 @@
+'use strict';
+// The compact handback: what an orchestrator reads by default (`--json`,
+// `zcode result`, `zcode wait --json`). A projection of the full result
+// record (schema zcode.result/1, still what result.json holds on disk and
+// what `--full` prints): decision-relevant fields only, empty keys omitted,
+// long text bounded, passing checks reduced to {command, ok:true}, and a
+// pointer (`result`) to the full record for anything else.
+const BRIEF_SCHEMA = 'zcode.brief/1';
+const SUMMARY_MAX = 600;
+const ERROR_MAX = 500;
+const TAIL_MAX = 1500;
+
+function clip(text, max) {
+  const s = String(text ?? '');
+  return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+
+const empty = (v) =>
+  v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
+
+function briefCheck(c) {
+  if (c.ok) return { command: c.command, ok: true };
+  const out = { command: c.command, ok: false, exitCode: c.exitCode ?? null };
+  if (c.timedOut) out.timedOut = true;
+  out.tail = String(c.output || '').slice(-TAIL_MAX);
+  return out;
+}
+
+const ALWAYS = new Set(['type', 'schema', 'status', 'ok', 'id']);
+
+function buildBrief(result) {
+  // checks_failed restates the failing `checks` entries below: kind only.
+  const error = result.error
+    ? result.error.kind === 'checks_failed'
+      ? { kind: 'checks_failed' }
+      : { kind: result.error.kind, message: clip(result.error.message, ERROR_MAX) }
+    : null;
+  // The failure message usually repeats as an issue; say it once.
+  const issues = (result.issues || []).filter((i) => !(error && i === result.error.message));
+  const raw = {
+    type: 'result',
+    schema: BRIEF_SCHEMA,
+    status: result.status,
+    ok: Boolean(result.ok),
+    id: result.id,
+    label: result.label,
+    preflight: result.preflight,
+    summary: clip(result.summary, SUMMARY_MAX),
+    // run/agent: the answer is the product. task: the handback is.
+    response: result.kind === 'task' ? undefined : result.response,
+    files: ((result.changes && result.changes.files) || []).map((f) => f.path),
+    checks: (result.checks || []).map(briefCheck),
+    questions: result.questions,
+    issues,
+    unresolved: result.unresolved,
+    scopeViolations: result.scopeViolations,
+    touched: result.touched,
+    decisions: result.decisions,
+    visual: result.visual,
+    units: result.units,
+    error,
+    result: result.files && result.files.result,
+  };
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) if (ALWAYS.has(k) || !empty(v)) out[k] = v;
+  return out;
+}
+
+module.exports = { buildBrief, BRIEF_SCHEMA };

package/lib/checks.js

@@ -22,6 +22,7 @@ function killGroup(child) {
 }
 
 function runCheck(command, { cwd, timeoutMs = 300000, signal, env = process.env } = {}) {
+  env = env || process.env;
   const started = Date.now();
   return new Promise((resolve) => {
     let output = '';
@@ -80,12 +81,12 @@ function runCheck(command, { cwd, timeoutMs = 300000, signal, env = process.env
 
 // Runs every check in order (later checks still run when an earlier one
 // fails, so the handback carries complete evidence); stops on cancel.
-async function runChecks(commands, { cwd, timeoutMs, signal, onEvent = () => {} } = {}) {
+async function runChecks(commands, { cwd, timeoutMs, signal, env, onEvent = () => {} } = {}) {
   const results = [];
   for (const command of commands) {
     if (signal && signal.aborted) break;
     onEvent({ type: 'check', phase: 'started', command });
-    const r = await runCheck(command, { cwd, timeoutMs, signal });
+    const r = await runCheck(command, { cwd, timeoutMs, signal, env });
     results.push(r);
     onEvent({
       type: 'check',