@0xgeorgemathew/zcode 0.5.1 → 0.6.0

package/README.md

@@ -51,7 +51,7 @@ The Claude Code skill goes to `~/.claude/skills/zcode` and the Codex skill to `$
 
 ## Models and effort
 
-Every command runs on GLM-5.3-Flash at effort `max` unless you pass a flag.
+Every command runs on GLM-5.3-Flash (it sees images) at effort `max` unless you pass a flag. `--model glm-5.3` is an explicit override: GLM-5.3 cannot see images (`zcode doctor` shows `images` / `no images` per model). Plan sessions, units, resume, `run` and `agent` all default to Flash too, and the visual verifier always uses an image-capable model. Subagent profiles copied from your desktop that pin a GLM-5.3 id are rewritten in the session's copy to the session's model.
 
 | setting | flag | values | default |
 |---|---|---|---|
@@ -116,13 +116,12 @@ Flags cover the common fields. For richer handoffs, pass `--task contract.json`,
   "references": ["design/team.png described in design/team.md"],
   "context": ["Copy lives in content/team.json"],
   "owns": ["src/pages/team/**", "content/team.json"],
-  "limits": { "timeoutMs": 1800000, "maxRepairs": 2, "checkTimeoutMs": 300000 },
-  "model": "glm-5.3",
+  "limits": { "timeoutMs": 7200000, "maxRepairs": 2, "checkTimeoutMs": 300000 },
   "effort": "high"
 }
 ```
 
-`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.
+`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, then to `--cwd`; the error names both paths). 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.
 
@@ -130,7 +129,7 @@ A file passed with `--file` and also inlined with `--context @file` reaches the
 
 **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.
+**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`) make zcode, not the implementer, judge the rendered result. After the implementer's turn (and once the checks pass) zcode opens a fresh engine session on the first image-capable model (GLM-5.3-Flash, effort `high`, same workspace and session environment) that did not build the result. It serves the app on `$ZCODE_PORT`, waits for fonts and animations, captures viewport and full-page screenshots into `$ZCODE_OUT/verify/<round>/` at each viewport, looks at them, makes no edits, and answers with a `zcode-visual` block: `[{criterion, viewport, met, seen, note, shot}]`, quoting the text it can read (`seen`). It also always judges one built-in criterion: all text the page means to show is readable after animations finish (not clipped, hidden, transparent, off-screen or overlapped). Those entries are the result's `visual`; the implementer's own claims are kept only as `executorVisual` in the full record. Unmet criteria spend the repair budget like failing checks (the repair turn goes to the implementer with the verifier's `seen`, note and shot paths; then checks and a new verifier round run). A verifier that fails or returns no parsable block is retried once; still nothing gives `met: null`, status `partial` and the issue `visual not verified`. Still unmet after the budget: `partial` with `visual criteria unmet: …`. An implementer on a model that cannot see images is told so and to self-check visibility in the DOM instead. Files the verifier changes outside `.zcode/` are reported as the issue `verifier edited files: …`. Verifier turns count in `usage`. Without `--visual` nothing changes.
 
 ### Status: what a result means
 
@@ -192,7 +191,7 @@ zcode cancel page-1          # stop the turn and any running check; recorded as
   ] }
 ```
 
-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.
+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, then against the plan's cwd), `model`, `effort`, `limits` (`timeoutMs`, `maxRepairs`, `checkTimeoutMs`: the default for every session; a session's own `limits` override per key). Each session has an `id` (its zcode session id), optional `after` (ids), optional `label` (the session label becomes `plan:<name> <label>`) and any task contract keys. In `plan run --preflight`, a session with `after` is told which upstream sessions have not run yet and to assume they deliver their objectives.
 
 ```sh
 zcode plan check plan.json              # validate: exit 2, one line per problem
@@ -213,7 +212,7 @@ A session starts once everything it is `after` has completed; sessions that can
 
 ```sh
 zcode "What is 17*23? Reply with only the number."
-zcode --model glm-5.3 --effort high "Draft a commit message for the staged diff"
+zcode --effort high "Draft a commit message for the staged diff"
 echo "$PROMPT" | zcode
 ```
 
@@ -237,7 +236,7 @@ The final line is the compact **brief** (`zcode.brief/1`), sized for an orchestr
  "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`):
+The brief lists unmet visual criteria only (`visualMet: "M/N"` counts them all), at most 6 `decisions` (`decisionsMore`) and 40 `files` (`filesMore`, concurrent sessions' files excluded). `run` and `agent` briefs also carry `response`, because the text answer is the product there. Only failing checks are listed (`checksPassed: N` counts the passing ones); 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",
@@ -263,7 +262,7 @@ The final line is the compact **brief** (`zcode.brief/1`), sized for an orchestr
 | `{"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 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.
+`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 watch [<id>… | --plan <name>] [--stall-min 8]` is a live view for humans (no model tokens): one line per session, `id  state phase[ n/m]  elapsed  last: <tool> <age> ago  req <n>  sub <running>`, with `STALLED?` appended when a running session has had no engine event for `--stall-min` minutes (default 8). On a TTY it redraws every 2 s; piped, it prints a line when a session changes; it exits 0 when every watched session has finished (no arguments: live sessions and those finished in the last 10 minutes). `status <id>` (human and `--json`) gains `idleMs` and `stalled: true` for running sessions by the same rule, and `wait` / `plan wait` pending lines carry `idleMs` (`stalled: true` when so). Nothing is done automatically. `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 for each of the 15 most recent sessions plus `… N more (zcode status --all)`. `zcode <command> --help` prints only that command's usage (under 2000 bytes); bare `zcode --help` is the full reference. Usage errors are always a single line (`zcode: unknown flag (did you mean …?)` for a mistyped option), never the help text.
 
 &nbsp;
 
@@ -282,12 +281,12 @@ The final line is the compact **brief** (`zcode.brief/1`), sized for an orchestr
 | `--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 |
+| `--visual`, `--viewport`, `--serve` | task | viewports `390x844`, `1440x900` | an independent image-capable verifier screenshots the app 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` | the model's levels: `low`, `high`, `max` |
-| `--timeout-ms` | all turns; wait | run 600000, task 1800000 | the whole invocation incl. checks and repairs |
+| `--timeout-ms` | all turns; wait | run 600000, task 7200000 (2 h) | 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, plus the desktop's `playwright` | MCP servers (inline JSON or `@file`) |

package/bin/zcode.js

@@ -9,8 +9,10 @@ const USAGE = `usage:
   zcode [run] [options] <prompt…>      one-shot turn (prompt via stdin when piped)
   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 status [<id>] [--all] [--json] one session in detail, or the 15 most recent (--all: every session)
   zcode wait <id…> [--any] [--json]    block until sessions finish; print handbacks
+  zcode watch [<id…> | --plan <name>] [--stall-min n]
+                                       live one-line-per-session view (no model tokens); exits when all finish
   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)
@@ -55,16 +57,17 @@ task contract (task only):
                         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
+  --visual <criterion>  repeatable: after the work an independent image-capable
+                        verifier (GLM-5.3-Flash, fresh session) serves the app on
+                        $ZCODE_PORT, screenshots it 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
+  plan.json             {cwd?, decisions?, context?, files?, model?, effort?, limits?,
+                        sessions:[{id, after?:[ids], label?, ...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
@@ -82,7 +85,7 @@ execution:
                         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)
+                        task default 7200000 = 2 h)
   --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
@@ -143,7 +146,7 @@ function parseMcpSpec(value) {
   return parsed;
 }
 
-const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', 'skills', 'result', 'plan', '__plan', '__exec']);
+const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'watch', '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']);
@@ -192,15 +195,18 @@ function parseArgv(argv) {
       quiet: false,
       thinking: undefined,
       stream: false,
+      plan: undefined,
+      stallMin: undefined,
       full: false,
       any: false,
+      all: 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'], ['--serve', 'serve'],
+    ['--check-timeout-ms', 'checkTimeoutMs'], ['--serve', 'serve'], ['--plan', 'plan'], ['--stall-min', 'stallMin'],
   ]);
   const listFlags = new Map([
     ['--mcp', 'mcpSpecs'], ['--skills', 'skillsDirs'], ['--accept', 'accept'], ['--check', 'check'],
@@ -214,7 +220,7 @@ function parseArgv(argv) {
     ['--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]],
+    ['--full', ['full', true]], ['--any', ['any', true]], ['--all', ['all', true]], ['--preflight', ['preflight', true]],
   ]);
   const numeric = (flag, value, { min = 1 } = {}) => {
     const n = Number(value);
@@ -230,6 +236,7 @@ function parseArgv(argv) {
       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 === 'stallMin') out.flags[key] = numeric(arg, value, { min: 0 });
       else if (key === 'maxRepairs') out.flags[key] = numeric(arg, value, { min: 0 });
       else if (key === 'mcpSpecs') out.flags.mcpSpecs.push(parseMcpSpec(value));
       else if (key === 'skillsDirs') {
@@ -247,7 +254,11 @@ function parseArgv(argv) {
       continue;
     }
     if (arg === '--help' || arg === '-h') {
-      process.stdout.write(USAGE + '\n');
+      // Scan the rest of argv for the command: `zcode --help task` works too.
+      let command = out.commandSet ? out.command : null;
+      if (!command) for (const a of argv) if (COMMANDS.has(a) && !a.startsWith('__')) { command = a === 'list' ? 'status' : a; break; }
+      const text = command && require('../lib/help.js').commandHelp(command);
+      process.stdout.write((text || USAGE) + '\n');
       process.exit(0);
     }
     if (arg === '--version') {
@@ -290,6 +301,10 @@ function parseArgv(argv) {
       if (out.given.has(key)) fail(2, `--${flagName(key)} cannot change on resume; it is fixed when the session starts.`);
     }
   }
+  if (out.given.has('all') && cmd !== 'status') fail(2, '--all is only valid with "zcode status".');
+  for (const k of ['plan', 'stallMin']) {
+    if (out.given.has(k) && cmd !== 'watch') fail(2, `--${flagName(k)} is only valid with "zcode watch".`);
+  }
   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>".');
@@ -360,6 +375,7 @@ async function main() {
       return require('../lib/commands/plan.js')(parsed);
     case 'status':
     case 'wait':
+    case 'watch':
     case 'result':
     case 'cancel':
       return require('../lib/commands/sessions.js')(parsed);

package/lib/appserver.js

@@ -365,6 +365,7 @@ async function runTurn(client, session, {
     reasoningText: '',
     toolCallCount: null,
     toolEvents: 0,
+    modelRequests: 0,
     userInput: null,
     durationMs: 0,
   };
@@ -418,6 +419,7 @@ async function runTurn(client, session, {
       } else if (type === 'turn.started') {
         onEvent({ type: 'turn', phase: 'started', turnId: params.turnId });
       } else if (type === 'session.updated' && payload && payload.type === 'model_request_started') {
+        turn.modelRequests++;
         turn.engineProvider = payload.providerId ?? turn.engineProvider;
         turn.engineModel = payload.modelId ?? turn.engineModel;
         turn.engineReasoningLevel = payload.modelCall?.reasoning?.requestedLevel ?? turn.engineReasoningLevel;
@@ -475,6 +477,9 @@ async function runTurn(client, session, {
       if (['timeout', 'cancelled', 'user_input'].includes(failed.kind)) {
         await client.stopSession(session.sessionId);
       }
+      // The partial facts (model requests so far) survive a failed turn.
+      turn.durationMs = Date.now() - started;
+      failed.turn = turn;
       throw failed;
     }
     if (completed.resultType && completed.resultType !== 'success') {

package/lib/brief.js

@@ -3,8 +3,8 @@
 // `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.
+// long text bounded, passing checks and met visual criteria reduced to a count
+// (checksPassed, visualMet), decisions/files capped, 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;
@@ -26,6 +26,32 @@ function briefCheck(c) {
   return out;
 }
 
+const DECISIONS_MAX = 6;
+const FILES_MAX = 40;
+const OPTION_MAX = 300;
+
+function briefDecision(d) {
+  if (d && typeof d === 'object') return { what: clip(d.what, 160), why: clip(d.why, 120) };
+  return clip(d, 160);
+}
+
+function briefVisual(v) {
+  return {
+    criterion: clip(v.criterion, 160),
+    viewport: v.viewport,
+    met: v.met === null ? null : false,
+    seen: v.seen ? clip(v.seen, 200) : undefined,
+    note: clip(v.note, 300),
+    shot: v.shot,
+  };
+}
+
+// Questions stay whole (the decision surface); only option strings are bounded.
+function briefQuestion(q) {
+  if (!q || typeof q !== 'object' || !Array.isArray(q.options)) return q;
+  return { ...q, options: q.options.map((o) => (typeof o === 'string' ? clip(o, OPTION_MAX) : o)) };
+}
+
 const ALWAYS = new Set(['type', 'schema', 'status', 'ok', 'id']);
 
 function buildBrief(result) {
@@ -37,6 +63,16 @@ function buildBrief(result) {
     : null;
   // The failure message usually repeats as an issue; say it once.
   const issues = (result.issues || []).filter((i) => !(error && i === result.error.message));
+  const checks = result.checks || [];
+  const failing = checks.filter((c) => !c.ok);
+  const passed = checks.length - failing.length;
+  const visual = Array.isArray(result.visual) ? result.visual : [];
+  const visualUnmet = visual.filter((v) => !(v && v.met === true));
+  const decisions = Array.isArray(result.decisions) ? result.decisions : [];
+  // Files a concurrent session changed are that session's, not this handback's.
+  const files = ((result.changes && result.changes.files) || [])
+    .filter((f) => !f.concurrentSession)
+    .map((f) => f.path);
   const raw = {
     type: 'result',
     schema: BRIEF_SCHEMA,
@@ -48,15 +84,19 @@ function buildBrief(result) {
     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,
+    files: files.slice(0, FILES_MAX),
+    filesMore: files.length > FILES_MAX ? files.length - FILES_MAX : undefined,
+    checks: failing.map(briefCheck),
+    checksPassed: passed > 0 ? passed : undefined,
+    questions: Array.isArray(result.questions) ? result.questions.map(briefQuestion) : result.questions,
     issues,
     unresolved: result.unresolved,
     scopeViolations: result.scopeViolations,
     touched: result.touched,
-    decisions: result.decisions,
-    visual: result.visual,
+    decisions: decisions.slice(0, DECISIONS_MAX).map(briefDecision),
+    decisionsMore: decisions.length > DECISIONS_MAX ? decisions.length - DECISIONS_MAX : undefined,
+    visual: visualUnmet.map(briefVisual),
+    visualMet: visual.length ? `${visual.length - visualUnmet.length}/${visual.length}` : undefined,
     units: result.units,
     error,
     result: result.files && result.files.result,

package/lib/commands/doctor.js

@@ -8,7 +8,7 @@ const { sha256File, engineVersion } = require('../engine.js');
 const { resolveRuntime, ConfigError } = require('../bootstrap.js');
 const { buildEngineHome, engineEnv, rootDir, liveDir, effectiveMcpServers } = require('../isolation.js');
 const store = require('../store.js');
-const { modelLevels } = require('../models.js');
+const { modelLevels, modelVision } = require('../models.js');
 
 module.exports = async function doctor(parsed) {
   const flags = parsed.flags;
@@ -53,6 +53,7 @@ module.exports = async function doctor(parsed) {
       builtinProviderConfig: builtinConfig,
     },
     models: modelLevels({ builtinConfig }),
+    vision: modelVision({ builtinConfig }),
     isolation: {
       root,
       home: built.home,
@@ -85,7 +86,7 @@ module.exports = async function doctor(parsed) {
         `    sha256 ${report.engine.sha256}`,
         `    version ${version ?? 'unknown'}`,
         `  builtin provider config ${builtinConfig}`,
-        `  models ${Object.entries(report.models).map(([id, l]) => `${id} (effort ${l.join('|')})`).join(', ')}`,
+        `  models ${Object.entries(report.models).map(([id, l]) => `${id} (effort ${l.join('|')}, ${report.vision[id] ? 'images' : 'no images'})`).join(', ')}`,
         `  isolation root ${root} (one engine HOME per session; config mode: ${built.mode})`,
         `  skills inherited ${built.skillsCopied}, mcp servers available with --mcp-inherit ${report.isolation.mcpServersInherited}`,
         `  sessions ${report.sessions.total} (${report.sessions.running} running, ${report.sessions.interrupted} interrupted)`,

package/lib/commands/exec.js

@@ -25,7 +25,7 @@ const { makeReporter, formatResult, useColor } = require('../ui.js');
 const { normalizeModel, normalizeEffort, effortProblem } = require('../models.js');
 
 const BIN = path.join(__dirname, '..', '..', 'bin', 'zcode.js');
-const DEFAULT_TIMEOUT = { run: 600000, agent: 600000, task: 1800000 };
+const DEFAULT_TIMEOUT = { run: 600000, agent: 600000, task: 7200000 };
 
 // Thrown (not exited) so builders can be reused by the plan supervisor; the
 // command entry points below turn it into the one-line exit 2.

package/lib/commands/plan.js

@@ -99,7 +99,7 @@ function brief(name, flags, status) {
   if (status) report.status = status;
   if (flags.json) return print(report, flags);
   // Human mode: the whole timeout/detach summary is one stdout line.
-  out(`plan ${report.name}: ${report.status} (${report.sessions.map((s) => `${s.id} ${s.status}`).join(', ')})`);
+  out(`plan ${report.name}: ${report.status} (${report.sessions.map((s) => `${s.id} ${s.status}${s.stalled ? ` idle ${Math.round(s.idleMs / 60000)}m STALLED?` : ''}`).join(', ')})`);
 }
 
 // Supervises in-process until the plan settles (or the deadline). On a
@@ -215,7 +215,8 @@ async function preflight(parsed, r, name, state) {
     if (Date.now() >= deadline) {
       for (const id of pending) {
         const v = store.viewSession(store.readSession(id));
-        out(flags.json ? JSON.stringify({ type: 'pending', id, state: v.state, phase: v.phase }) : `${id} ${v.state} ${v.phase}`);
+        const idle = store.idleInfo(v);
+        out(flags.json ? JSON.stringify({ type: 'pending', id, state: v.state, phase: v.phase, ...idle }) : `${id} ${v.state} ${v.phase}${idle && idle.stalled ? ' STALLED?' : ''}`);
       }
       process.exit(124);
     }

package/lib/commands/sessions.js

@@ -4,7 +4,7 @@
 // engine or needs the API key, so they are instant and safe to poll.
 const store = require('../store.js');
 const { buildBrief } = require('../brief.js');
-const { formatResult, formatSessionRow, formatSessionView, useColor } = require('../ui.js');
+const { formatResult, formatSessionRow, formatSessionView, phaseText, useColor } = require('../ui.js');
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
@@ -39,27 +39,35 @@ function finalResult(view) {
 }
 
 function statusPayload(view, { events = 10 } = {}) {
-  const payload = { type: 'status', ...view, recent: store.readEvents(view.id, { tail: events }) };
+  const payload = { type: 'status', ...view, ...store.idleInfo(view), recent: store.readEvents(view.id, { tail: events }) };
   if (view.state === 'finished' || view.state === 'interrupted') payload.result = finalResult(view);
   return payload;
 }
 
+const STATUS_RECENT = 15;
+
 async function status(parsed) {
   const { flags, prompts } = parsed;
   if (prompts.length === 0) {
-    const all = store.listSessions().slice(0, 50);
+    const everything = store.listSessions();
     if (flags.json) {
-      process.stdout.write(JSON.stringify({ type: 'sessions', sessions: all.map(summaryOf) }) + '\n');
-    } else if (all.length === 0) {
+      process.stdout.write(JSON.stringify({ type: 'sessions', sessions: everything.slice(0, 50).map(summaryOf) }) + '\n');
+    } else if (everything.length === 0) {
       process.stdout.write('no sessions\n');
     } else {
-      for (const s of all) process.stdout.write(formatSessionRow(s) + '\n');
+      // Most recent first; the rest is one line, `--all` lists everything.
+      const shown = flags.all ? everything : everything.slice(0, STATUS_RECENT);
+      for (const s of shown) process.stdout.write(formatSessionRow(s) + '\n');
+      if (shown.length < everything.length) {
+        process.stdout.write(`… ${everything.length - shown.length} more (zcode status --all)\n`);
+      }
     }
     process.exit(0);
   }
   const id = resolveOrExit(prompts[0], flags.json);
   const view = store.viewSession(store.readSession(id));
   const payload = statusPayload(view);
+  Object.assign(view, store.idleInfo(view));
   if (flags.json) {
     process.stdout.write(JSON.stringify(payload) + '\n');
   } else {
@@ -97,8 +105,9 @@ function formatElapsed(ms) {
 // one line, nothing else.
 function pendingLine(view, json) {
   const elapsedMs = Math.max(0, Date.now() - Date.parse(view.createdAt || view.updatedAt || Date.now()));
-  if (json) return JSON.stringify({ type: 'pending', id: view.id, state: view.state, phase: view.phase, elapsedMs });
-  return `${view.id} ${view.state} ${view.phase} ${formatElapsed(elapsedMs)}`;
+  const idle = store.idleInfo(view);
+  if (json) return JSON.stringify({ type: 'pending', id: view.id, state: view.state, phase: view.phase, elapsedMs, ...idle });
+  return `${view.id} ${view.state} ${view.phase} ${formatElapsed(elapsedMs)}${idle && idle.stalled ? ` idle ${formatElapsed(idle.idleMs)} STALLED?` : ''}`;
 }
 
 // A finished session's handback in the requested form.
@@ -220,7 +229,85 @@ async function cancel(parsed) {
   return report('killed');
 }
 
+// One line per watched session: `id  state phase[ n/m]  elapsed  last: <tool>
+// <age> ago  req <n>  sub <running>` (+ STALLED? when running and silent).
+function watchLine(view, { stallMin, now = Date.now() }) {
+  const done = isDone(view);
+  const state = view.state === 'finished' ? view.status || 'finished' : view.state;
+  const a = view.activity || {};
+  const idle = store.idleInfo(view, { stallMin, now });
+  const end = done ? Date.parse(view.updatedAt) : now;
+  const elapsed = formatElapsed(end - Date.parse(view.createdAt || view.updatedAt));
+  const last = a.lastTool
+    ? `last: ${a.lastTool}${a.lastToolAt ? ` ${formatElapsed(now - Date.parse(a.lastToolAt))} ago` : ''}`
+    : 'last: -';
+  const phase = done ? '' : ` ${phaseText(view)}`;
+  const stalled = idle && idle.stalled ? '  STALLED?' : '';
+  const text = `${view.id}  ${state}${phase}  ${elapsed}  ${last}  req ${a.modelRequests || 0}  sub ${a.subagentsRunning || 0}${stalled}`;
+  // The change signature leaves out the clocks (elapsed, ages).
+  const sig = [view.id, state, phase, a.lastTool, a.modelRequests || 0, a.subagentsRunning || 0, Boolean(stalled)].join('|');
+  return { text, sig, done };
+}
+
+// watch [<id>… | --plan <name>] [--stall-min n]: live view, no Opus tokens.
+// TTY: redraw every 2 s; otherwise print a session's line when it changes.
+// No args: live sessions plus those finished in the last 10 min. Exits when
+// every watched session is finished; Ctrl-C exits 0.
+async function watch(parsed) {
+  const { flags, prompts } = parsed;
+  const stallMin = parsed.given.has('stallMin') ? flags.stallMin : store.STALL_MIN;
+  const poll = Number(process.env.ZCODE_WATCH_POLL_MS) || 2000;
+  const tty = Boolean(process.stdout.isTTY);
+  process.on('SIGINT', () => process.exit(0));
+  let planCtx = null;
+  if (flags.plan) {
+    const plans = require('../plan.js');
+    const state = store.readPlanState(flags.plan);
+    if (!state) {
+      process.stderr.write(`zcode: no plan "${flags.plan}" (zcode plan run <file> starts one).\n`);
+      process.exit(2);
+    }
+    planCtx = { plans, state, r: plans.resolvePlan(state.file, state.cwd) };
+  }
+  const ids = prompts.map((p) => resolveOrExit(p, false));
+  const pick = () => {
+    if (ids.length) return ids.map((id) => store.viewSession(store.readSession(id))).filter(Boolean);
+    if (planCtx) {
+      return planCtx.plans.sessionList(planCtx.r.plan)
+        .map((s) => store.readSession(s.id)).filter(Boolean).map((rec) => store.viewSession(rec));
+    }
+    const cutoff = Date.now() - 10 * 60000;
+    return store.listSessions().filter((v) => !isDone(v) || Date.parse(v.updatedAt) >= cutoff).reverse();
+  };
+  const planDone = () => planCtx.plans.planReport(flags.plan, planCtx.r, store.readPlanState(flags.plan), { briefs: false }).status !== 'running';
+  const seen = new Map();
+  let drawn = 0;
+  for (;;) {
+    const views = pick();
+    if (!views.length && !planCtx) {
+      process.stdout.write('no live sessions\n');
+      process.exit(0);
+    }
+    const lines = views.map((v) => watchLine(v, { stallMin }));
+    if (tty) {
+      process.stdout.write(`${drawn ? `\x1b[${drawn}F\x1b[J` : ''}${lines.map((l) => l.text).join('\n')}${lines.length ? '\n' : ''}`);
+      drawn = lines.length;
+    } else {
+      for (const l of lines) {
+        const id = l.text.split('  ')[0];
+        if (seen.get(id) === l.sig) continue;
+        seen.set(id, l.sig);
+        process.stdout.write(l.text + '\n');
+      }
+    }
+    const finished = planCtx ? planDone() : lines.every((l) => l.done);
+    if (finished && (lines.length || planCtx)) process.exit(0);
+    await sleep(poll);
+  }
+}
+
 module.exports = async function sessions(parsed) {
+  if (parsed.command === 'watch') return watch(parsed);
   if (parsed.command === 'status') return status(parsed);
   if (parsed.command === 'wait') return wait(parsed);
   if (parsed.command === 'result') return result(parsed);