@0xgeorgemathew/zcode 0.3.1 → 0.4.0

package/lib/workspace.js

@@ -0,0 +1,336 @@
+'use strict';
+// Workspace boundaries for concurrent sessions:
+//  - ownership: `--owns` patterns (paths or globs, relative to --cwd) name
+//    what a session may modify; none = the whole workspace.
+//  - leases: a live session registers its ownership under
+//    <root>/leases/<workspace>/; a new session whose ownership overlaps a
+//    live one is refused (exit 7) unless --allow-overlap.
+//  - change tracking: a snapshot before and after the work yields the files
+//    the session changed (git status + content hashes in a git repo, a
+//    bounded mtime walk otherwise) and the ones outside its ownership.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { rootDir } = require('./isolation.js');
+const { pidAlive } = require('./store.js');
+
+class OwnershipError extends Error {}
+
+const toPosix = (p) => p.split(path.sep).join('/');
+
+function gitToplevel(cwd) {
+  try {
+    return execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+// The lease/change-tracking root: the git toplevel when --cwd is inside a
+// repo (so sessions in sibling subdirectories still see each other), else
+// the real --cwd.
+function workspaceRoot(cwd) {
+  const real = fs.realpathSync(cwd);
+  const top = gitToplevel(real);
+  return top ? fs.realpathSync(top) : real;
+}
+
+// Ownership patterns arrive relative to --cwd; store them relative to the
+// workspace root, posix-style, so every session compares like with like.
+function normalizeOwns(patterns, cwd, root) {
+  const realCwd = fs.realpathSync(cwd);
+  return patterns.map((raw) => {
+    const pattern = String(raw).trim();
+    if (!pattern) throw new OwnershipError('--owns pattern must not be empty');
+    const abs = path.isAbsolute(pattern) ? pattern : path.join(realCwd, pattern);
+    const rel = toPosix(path.relative(root, abs));
+    if (rel === '' || rel === '.') return '**';
+    if (rel.startsWith('../') || rel === '..' || path.isAbsolute(rel)) {
+      throw new OwnershipError(`--owns "${pattern}" is outside the workspace ${root}`);
+    }
+    return /[/\\]$/.test(pattern) && !hasWildcard(rel) ? `${rel}/**` : rel;
+  });
+}
+
+function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        i++;
+        if (glob[i + 1] === '/') {
+          i++;
+          re += '(?:.*/)?';
+        } else {
+          re += '.*';
+        }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+const hasWildcard = (p) => /[*?]/.test(p);
+
+// A plain path owns itself and everything beneath it; a glob owns its
+// matches. Empty ownership = the whole workspace.
+function isOwned(relPath, owns) {
+  if (!owns || owns.length === 0) return true;
+  return owns.some((pattern) => {
+    if (!hasWildcard(pattern)) return relPath === pattern || relPath.startsWith(`${pattern}/`);
+    return globToRegExp(pattern).test(relPath);
+  });
+}
+
+// The literal directory part of a pattern (segments before the first
+// wildcard). Overlap is decided conservatively on these prefixes: two
+// patterns overlap when one prefix contains the other.
+function staticSegments(pattern) {
+  const out = [];
+  for (const seg of pattern.split('/')) {
+    if (hasWildcard(seg)) break;
+    out.push(seg);
+  }
+  return out;
+}
+
+function patternsOverlap(a, b) {
+  const sa = staticSegments(a);
+  const sb = staticSegments(b);
+  const n = Math.min(sa.length, sb.length);
+  for (let i = 0; i < n; i++) if (sa[i] !== sb[i]) return false;
+  // Same literal prefix. Two fully literal, distinct paths of equal depth
+  // were already ruled out above; anything else may share files.
+  return true;
+}
+
+function ownsOverlap(a, b) {
+  if (!a || !b || a.length === 0 || b.length === 0) return true;
+  return a.some((pa) => b.some((pb) => patternsOverlap(pa, pb)));
+}
+
+// --- leases -------------------------------------------------------------------
+
+function leaseDir(root, env = process.env) {
+  const key = crypto.createHash('sha256').update(root).digest('hex').slice(0, 16);
+  return path.join(rootDir(env), 'leases', key);
+}
+
+function readLeases(dir) {
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    try {
+      out.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')));
+    } catch {
+      /* half-written or removed concurrently */
+    }
+  }
+  return out;
+}
+
+// Registers this session's lease, then compares against every other live
+// lease. Writing first and reading second means two sessions starting at
+// the same instant both see each other; the later (startedAt, id) backs
+// off, so exactly one proceeds.
+function acquireLease({ id, root, owns, allowOverlap = false, env = process.env }) {
+  const dir = leaseDir(root, env);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const mine = { id, pid: process.pid, root, owns, startedAt: Date.now() };
+  const file = path.join(dir, `${id}.json`);
+  fs.writeFileSync(file, JSON.stringify(mine) + '\n', { mode: 0o600 });
+
+  const others = [];
+  for (const lease of readLeases(dir)) {
+    if (!lease || lease.id === id) continue;
+    if (!pidAlive(lease.pid)) {
+      fs.rmSync(path.join(dir, `${lease.id}.json`), { force: true });
+      continue;
+    }
+    others.push(lease);
+  }
+  const conflicts = others.filter((o) => ownsOverlap(owns, o.owns));
+  const blocking = conflicts.filter(
+    (o) => o.startedAt < mine.startedAt || (o.startedAt === mine.startedAt && o.id < id)
+  );
+  if (blocking.length > 0 && !allowOverlap) {
+    fs.rmSync(file, { force: true });
+    return { ok: false, conflicts: blocking, others };
+  }
+  return { ok: true, conflicts, others, release: () => fs.rmSync(file, { force: true }) };
+}
+
+function liveLeases(root, env = process.env) {
+  return readLeases(leaseDir(root, env)).filter((l) => l && pidAlive(l.pid));
+}
+
+// --- change tracking ----------------------------------------------------------
+
+const WALK_SKIP = new Set(['.git', 'node_modules', '.zcode', '.DS_Store']);
+const WALK_LIMIT = 20000;
+const HASH_LIMIT = 8 * 1024 * 1024;
+
+function fileSignature(abs) {
+  try {
+    const st = fs.statSync(abs);
+    if (!st.isFile()) return `other:${st.mtimeMs}`;
+    if (st.size > HASH_LIMIT) return `big:${st.size}:${st.mtimeMs}`;
+    return crypto.createHash('sha1').update(fs.readFileSync(abs)).digest('hex');
+  } catch {
+    return 'missing';
+  }
+}
+
+// Parses `git status --porcelain=v1 -z`; rename/copy entries carry the
+// source path as an extra NUL field.
+function gitStatus(root) {
+  const raw = execFileSync(
+    'git',
+    ['-C', root, 'status', '--porcelain=v1', '-z', '--untracked-files=all'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000, maxBuffer: 64 * 1024 * 1024 }
+  );
+  const fields = raw.split('\0');
+  const out = new Map();
+  for (let i = 0; i < fields.length; i++) {
+    const f = fields[i];
+    if (f.length < 4) continue;
+    const code = f.slice(0, 2);
+    out.set(f.slice(3), code);
+    if (code[0] === 'R' || code[0] === 'C') i++;
+  }
+  return out;
+}
+
+function gitHead(root) {
+  try {
+    return execFileSync('git', ['-C', root, 'rev-parse', '--verify', '-q', 'HEAD'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Files changed between two commits (the executor committed, stashed or
+// checked out): without this, committed work would vanish from the diff.
+function committedChanges(root, from, to) {
+  try {
+    const raw = execFileSync('git', ['-C', root, 'diff', '--name-status', '-z', '--no-renames', from, to], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 15000, maxBuffer: 64 * 1024 * 1024,
+    });
+    const f = raw.split('\0');
+    const out = [];
+    for (let i = 0; i + 1 < f.length; i += 2) {
+      if (!f[i]) break;
+      const change = f[i][0] === 'A' ? 'added' : f[i][0] === 'D' ? 'deleted' : 'modified';
+      out.push({ path: f[i + 1], change });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function snapshot(root) {
+  if (gitToplevel(root)) {
+    try {
+      const entries = new Map();
+      for (const [rel, code] of gitStatus(root)) {
+        entries.set(rel, { code, sig: fileSignature(path.join(root, rel)) });
+      }
+      return { kind: 'git', root, head: gitHead(root), entries };
+    } catch {
+      /* fall back to the walk */
+    }
+  }
+  const entries = new Map();
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let dirents;
+    try {
+      dirents = fs.readdirSync(path.join(root, rel), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const d of dirents) {
+      if (WALK_SKIP.has(d.name)) continue;
+      const childRel = rel ? `${rel}/${d.name}` : d.name;
+      if (d.isDirectory()) stack.push(childRel);
+      else if (d.isFile()) {
+        if (entries.size >= WALK_LIMIT) return { kind: 'unavailable', entries: null };
+        try {
+          const st = fs.statSync(path.join(root, childRel));
+          entries.set(childRel, { code: 'fs', sig: `${st.size}:${st.mtimeMs}` });
+        } catch {
+          /* vanished mid-walk */
+        }
+      }
+    }
+  }
+  return { kind: 'fs', entries };
+}
+
+// Files whose state differs between two snapshots. In git mode a path
+// absent from `after` but present in `before` went back to clean — it was
+// still changed by someone.
+function diffSnapshots(before, after) {
+  if (!before || !after || !before.entries || !after.entries || before.kind !== after.kind) {
+    return null;
+  }
+  const out = [];
+  const paths = new Set([...before.entries.keys(), ...after.entries.keys()]);
+  for (const rel of [...paths].sort()) {
+    const b = before.entries.get(rel);
+    const a = after.entries.get(rel);
+    if (b && a && b.sig === a.sig && b.code === a.code) continue;
+    let change = 'modified';
+    if (after.kind === 'fs') {
+      if (!b) change = 'added';
+      else if (!a) change = 'deleted';
+    } else if (a) {
+      if (a.code.includes('D') || a.sig === 'missing') change = 'deleted';
+      else if (!b && (a.code === '??' || a.code[0] === 'A')) change = 'added';
+    }
+    out.push({ path: rel, change });
+  }
+  if (after.kind === 'git' && before.head && after.head && before.head !== after.head) {
+    const seen = new Set(out.map((f) => f.path));
+    for (const f of committedChanges(after.root, before.head, after.head)) {
+      if (!seen.has(f.path)) out.push({ ...f, committed: true });
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+  }
+  return out;
+}
+
+module.exports = {
+  OwnershipError,
+  workspaceRoot,
+  normalizeOwns,
+  globToRegExp,
+  isOwned,
+  ownsOverlap,
+  acquireLease,
+  liveLeases,
+  leaseDir,
+  snapshot,
+  diffSnapshots,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@0xgeorgemathew/zcode",
-  "version": "0.3.1",
-  "description": "Headless GLM-5.3 / GLM-5.3-Flash coding CLI for agents: streaming thinking, subagents, MCP servers, skills, session continuity. Wraps the ZCode engine. Zero dependencies.",
+  "version": "0.4.0",
+  "description": "Lean GLM-5.3 execution engine for orchestrator agents: task contracts, independent sessions, zcode-run verification, structured handbacks, subagents, MCP, skills. Wraps the ZCode engine. Zero dependencies.",
   "license": "MIT",
   "private": false,
   "bin": {
@@ -14,12 +14,14 @@
   "files": [
     "bin",
     "lib",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test --test-concurrency=1 \"test/**/*.test.js\"",
-    "prepublishOnly": "npm test",
+    "test": "node --test --test-concurrency=1 \"test/unit/*.test.js\"",
+    "test:live": "node --test --test-concurrency=1 \"test/live/*.test.js\"",
+    "prepublishOnly": "npm test && npm run test:live",
     "accept:flash": "node scripts/accept.js flash",
     "accept:subagent": "node scripts/accept.js subagent",
     "accept:53": "node scripts/accept.js glm53"
@@ -36,6 +38,8 @@
     "mcp",
     "subagent",
     "headless",
-    "ndjson"
+    "ndjson",
+    "orchestrator",
+    "executor"
   ]
 }

package/skills/README.md

@@ -0,0 +1,32 @@
+# Orchestrator skills
+
+These skills teach an orchestrating agent how to delegate work to zcode, run sessions in parallel, and read the handbacks. Both describe the same CLI; they differ only in runtime notes (tool timeouts for Claude Code, sandbox and network escalation for Codex).
+
+| platform | skill in this repo | format |
+|---|---|---|
+| Claude Code | `skills/claude-code/zcode/SKILL.md` | `SKILL.md` with `name` + `description` frontmatter |
+| Codex | `skills/codex/zcode/SKILL.md` + `agents/openai.yaml` | `SKILL.md` with `name` + `description` frontmatter; optional UI metadata in `agents/openai.yaml` |
+
+## Install
+
+Run these from a checkout of this repo, or from the installed package (`$(npm root -g)/@0xgeorgemathew/zcode`), which ships `skills/`.
+
+**Claude Code.** Personal skills, available in every project:
+
+```sh
+mkdir -p ~/.claude/skills
+cp -R skills/claude-code/zcode ~/.claude/skills/zcode
+```
+
+For a single project, copy it to `<project>/.claude/skills/zcode` instead and commit it so the whole team gets it. Claude Code discovers the skill from its description. You can also invoke it directly with `/zcode`.
+
+**Codex.** User skills live in `$CODEX_HOME/skills`, which defaults to `~/.codex/skills`:
+
+```sh
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/codex/zcode "${CODEX_HOME:-$HOME/.codex}/skills/zcode"
+```
+
+Skills are discovered when a session starts, so open a new Codex session if `$zcode` doesn't appear. The skill is selected automatically from its description, or explicitly with `$zcode`.
+
+Both skills assume `zcode` is on `PATH` (`npm install -g @0xgeorgemathew/zcode`) and that `zcode doctor` passes.

package/skills/claude-code/zcode/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: zcode
+description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor) and consume its verified handback. Use when you are orchestrating and want a page, component, fix or other bounded unit implemented and checked by an independent executor session — alone or several in parallel — while you keep product, design and planning decisions.
+---
+
+# Operating zcode as an executor
+
+zcode is a CLI execution engine. You hand it a scoped task; it implements the task in its own session, runs your acceptance checks itself, repairs failures within a budget, and returns a structured handback. You stay the orchestrator. You decide what to build and how it should look, how to split the work, when to run sessions in parallel, and when to review. zcode decides routine implementation details within the scope you give it.
+
+Check it is ready once per machine: `zcode doctor` (exit 3 means no key, so run `zcode login`; exit 4 means the engine is missing).
+
+## When to use it
+
+- Use it for bounded implementation work with a clear outcome: one page, a few components, a bug fix, a refactor of a known area, a test suite for a module.
+- Don't use it for product or design decisions, open-ended exploration, or work you can't describe a finished state for. Decide those yourself first, then delegate the implementation.
+- Size each session so you could review its result in one sitting. Several small sessions beat one huge one, because each returns its own evidence.
+
+## Writing the handoff
+
+Only the objective is required. Add what the executor cannot infer:
+
+| field | flag | give it when |
+|---|---|---|
+| objective | positional text | always: the outcome, not the steps |
+| acceptance | `--accept "…"` | you have criteria beyond "it works" |
+| checks | `--check "cmd"` | always if possible: shell commands zcode runs itself (build, tests, lint, a grep) |
+| owns | `--owns path/or/glob` | other sessions may touch the same repo |
+| files | `--file path` | specific files to read first |
+| context / design | `--context "…"` or `--context @notes.md` | design decisions, copy, references, constraints |
+| everything | `--task contract.json` | larger handoffs (keys: objective, scope, constraints, design, acceptance, checks, files, references, context, owns, limits, model, effort) |
+
+Rules that keep you in charge:
+
+- Put design decisions in `design` (JSON) or `--context`, written as decisions ("Hero uses the dark palette; CTA right-aligned"). The executor is told to implement them exactly and to report `blocked` rather than invent product or design choices.
+- Make checks mechanical and fast. A task with no `--check` can only come back `unverified`.
+- Don't ask zcode to commit, push, or deploy unless you mean it. It won't by default.
+
+## Running sessions
+
+Your Bash tool times out (2 minutes by default, 10 at most), and real tasks usually take longer. Start them detached and wait in bounded slices:
+
+```sh
+zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
+zcode wait <id> --timeout-ms 540000 --json --quiet                  # exit 124 = still running: wait again
+```
+
+You can also run a foreground `zcode task … --json --quiet` with `run_in_background: true` and read its single result line when you're notified. Quick tasks (well under 2 minutes) can run in the foreground directly.
+
+- `zcode status` lists sessions. `zcode status <id> --json` shows the state (`queued|running|finished|interrupted`), phase (`starting|executing|checking|repairing|reporting`), activity, recent events, and the result once finished. Use it only when you need it. You don't have to watch progress, and nothing waits for your approval.
+- `zcode cancel <id>` stops the turn and any running check; the session is recorded as `cancelled`.
+- `zcode resume <id> "<message>"` continues the same session with its context intact. Use it to answer questions, request follow-up changes, or continue after `interrupted`, `failed`, or `partial`. It accepts `--detach`, `--model`, `--effort`, `--timeout-ms`, and `--max-repairs`. The scope (`--cwd`, `--owns`, checks) stays as it was.
+- Pick your own `--id` values (`page-1`, `fix-auth`) so you can retry safely. A start with an existing id is refused (exit 2) instead of running the work twice.
+
+## Parallel sessions
+
+- Each session has its own engine context, so nothing leaks between them.
+- Sessions in the same repo must declare disjoint `--owns`. An overlapping start is refused with exit 7, and the error names the conflicting session. Fix the split, wait, or give the session its own `git worktree` and point `--cwd` at it.
+- After the work, each handback lists changed files. Anything outside the session's ownership appears in `scopeViolations` and makes the result `partial`.
+- You integrate the results. zcode doesn't coordinate sessions with each other.
+
+## Reading the handback
+
+The result (`--json`: one `{"type":"result"}` line) has `status`, `summary`, `changes.files`, `checks` (zcode's own runs, with output tails), `issues`, `questions`, `unresolved`, `notVerified`, `scopeViolations`, `subagents`, and `handback` (the executor's own claims).
+
+| status | exit | what it means | what you do |
+|---|---|---|---|
+| `completed` | 0 | zcode's checks passed, executor reports done, scope respected | review on your own schedule; integrate |
+| `unverified` | 9 | executor says done, but there were no checks (or no usable handback) | verify yourself, or resume with a check added to the message |
+| `partial` | 8 | work remains, a criterion is unmet, or files changed outside scope | read `issues`/`unresolved`/`scopeViolations`; resume or re-scope |
+| `blocked` | 10 | needs you: see `questions` | decide, then `zcode resume <id> "<answer>"` |
+| `failed` | 8 / 5 / 124 | `error.kind`: `checks_failed` (still failing after repairs), turn/engine error, or `timeout` | read `checks[].output` / `error`; resume with guidance or re-scope |
+| `cancelled` | 130 | stopped | resume if wanted |
+
+Trust `status`, `checks`, and `changes`. They come from what zcode observed. Treat `handback` and `summary` as the executor's report. A subagent's `success` only means it returned. zcode already verified the integrated result through your checks, so you don't need to review per subagent or per step.
+
+## Example: small task
+
+```sh
+zcode task --id fix-typo --cwd ~/site --owns README.md \
+  --check "grep -q '^# Acme Docs' README.md" \
+  "Fix the misspelled top-level heading in README.md (should read 'Acme Docs')" --json --quiet
+```
+
+Exit 0 means it's done. The result line shows the single changed file and the passing check.
+
+## Example: Page 1 and Page 2 in parallel
+
+You've already decided the design. Each page gets its own session, its own scope, and its own checks:
+
+```sh
+zcode task --detach --id page-1 --cwd ~/site --label "Home page" \
+  --owns src/pages/home/ --file src/theme.ts \
+  --context @specs/home.md \
+  --accept "Hero, three feature cards, footer CTA as specified" \
+  --check "npm run build" --check "npm test -- home" \
+  "Implement the Home page exactly as specified in the context"
+
+zcode task --detach --id page-2 --cwd ~/site --label "Pricing page" \
+  --owns src/pages/pricing/ --file src/theme.ts \
+  --context @specs/pricing.md \
+  --accept "Three plan cards, middle one highlighted; monthly/yearly toggle" \
+  --check "npm run build" --check "npm test -- pricing" \
+  "Implement the Pricing page exactly as specified in the context"
+
+zcode wait page-1 page-2 --timeout-ms 540000 --json --quiet   # repeat while exit is 124
+```
+
+If `page-2` comes back `blocked` with "Should yearly prices show the discount badge?", decide and run `zcode resume page-2 "Yes, show the 'Save 20%' badge on yearly." --detach`, then wait again. To run the pages one after another instead, start `page-2` after `page-1`'s handback. The shared `src/theme.ts` is passed with `--file` (read), not owned, so a change to it by either session would come back as a scope violation. If a page truly needs a shared change, make it yourself or give that file to exactly one session's `--owns`.
+
+## Exit codes
+
+0 completed · 2 usage (bad flag, contract, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.

package/skills/codex/zcode/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: zcode
+description: Delegate scoped implementation work to the zcode CLI (GLM-5.3 executor) and consume its verified handback. Use when you are orchestrating and want a page, component, fix or other bounded unit implemented and checked by an independent executor session — alone or several in parallel — while you keep product, design and planning decisions.
+---
+
+# Operating zcode as an executor
+
+zcode is a CLI execution engine. You hand it a scoped task; it implements the task in its own session, runs your acceptance checks itself, repairs failures within a budget, and returns a structured handback. You stay the orchestrator. You decide what to build and how it should look, how to split the work, when to run sessions in parallel, and when to review. zcode decides routine implementation details within the scope you give it.
+
+Check it is ready once per machine: `zcode doctor` (exit 3 means no key, so run `zcode login`; exit 4 means the engine is missing).
+
+## When to use it
+
+- Use it for bounded implementation work with a clear outcome: one page, a few components, a bug fix, a refactor of a known area, a test suite for a module.
+- Don't use it for product or design decisions, open-ended exploration, or work you can't describe a finished state for. Decide those yourself first, then delegate the implementation.
+- Size each session so you could review its result in one sitting. Several small sessions beat one huge one, because each returns its own evidence.
+
+## Writing the handoff
+
+Only the objective is required. Add what the executor cannot infer:
+
+| field | flag | give it when |
+|---|---|---|
+| objective | positional text | always: the outcome, not the steps |
+| acceptance | `--accept "…"` | you have criteria beyond "it works" |
+| checks | `--check "cmd"` | always if possible: shell commands zcode runs itself (build, tests, lint, a grep) |
+| owns | `--owns path/or/glob` | other sessions may touch the same repo |
+| files | `--file path` | specific files to read first |
+| context / design | `--context "…"` or `--context @notes.md` | design decisions, copy, references, constraints |
+| everything | `--task contract.json` | larger handoffs (keys: objective, scope, constraints, design, acceptance, checks, files, references, context, owns, limits, model, effort) |
+
+Rules that keep you in charge:
+
+- Put design decisions in `design` (JSON) or `--context`, written as decisions ("Hero uses the dark palette; CTA right-aligned"). The executor is told to implement them exactly and to report `blocked` rather than invent product or design choices.
+- Make checks mechanical and fast. A task with no `--check` can only come back `unverified`.
+- Don't ask zcode to commit, push, or deploy unless you mean it. It won't by default.
+
+## Running sessions
+
+zcode needs network access (the GLM API) and write access to `~/.zcode-cli` and the target repo. In a sandboxed Codex session, those commands may fail with sandbox or network errors. If they do, re-run the same command with escalated permissions instead of changing the command.
+
+Real tasks usually outlast a single shell call's timeout. Start them detached and wait in bounded slices:
+
+```sh
+zcode task --detach --id <id> --cwd <repo> [flags] "<objective>"   # prints the id, returns at once
+zcode wait <id> --timeout-ms 540000 --json --quiet                  # exit 124 = still running: wait again
+```
+
+Quick tasks can run in the foreground: `zcode task … --json --quiet` prints exactly one result line.
+
+- `zcode status` lists sessions. `zcode status <id> --json` shows the state (`queued|running|finished|interrupted`), phase (`starting|executing|checking|repairing|reporting`), activity, recent events, and the result once finished. Use it only when you need it. You don't have to watch progress, and nothing waits for your approval.
+- `zcode cancel <id>` stops the turn and any running check; the session is recorded as `cancelled`.
+- `zcode resume <id> "<message>"` continues the same session with its context intact. Use it to answer questions, request follow-up changes, or continue after `interrupted`, `failed`, or `partial`. It accepts `--detach`, `--model`, `--effort`, `--timeout-ms`, and `--max-repairs`. The scope (`--cwd`, `--owns`, checks) stays as it was.
+- Pick your own `--id` values (`page-1`, `fix-auth`) so you can retry safely. A start with an existing id is refused (exit 2) instead of running the work twice.
+
+## Parallel sessions
+
+- Each session has its own engine context, so nothing leaks between them.
+- Sessions in the same repo must declare disjoint `--owns`. An overlapping start is refused with exit 7, and the error names the conflicting session. Fix the split, wait, or give the session its own `git worktree` and point `--cwd` at it.
+- After the work, each handback lists changed files. Anything outside the session's ownership appears in `scopeViolations` and makes the result `partial`.
+- You integrate the results. zcode doesn't coordinate sessions with each other.
+
+## Reading the handback
+
+The result (`--json`: one `{"type":"result"}` line) has `status`, `summary`, `changes.files`, `checks` (zcode's own runs, with output tails), `issues`, `questions`, `unresolved`, `notVerified`, `scopeViolations`, `subagents`, and `handback` (the executor's own claims).
+
+| status | exit | what it means | what you do |
+|---|---|---|---|
+| `completed` | 0 | zcode's checks passed, executor reports done, scope respected | review on your own schedule; integrate |
+| `unverified` | 9 | executor says done, but there were no checks (or no usable handback) | verify yourself, or resume with a check added to the message |
+| `partial` | 8 | work remains, a criterion is unmet, or files changed outside scope | read `issues`/`unresolved`/`scopeViolations`; resume or re-scope |
+| `blocked` | 10 | needs you: see `questions` | decide, then `zcode resume <id> "<answer>"` |
+| `failed` | 8 / 5 / 124 | `error.kind`: `checks_failed` (still failing after repairs), turn/engine error, or `timeout` | read `checks[].output` / `error`; resume with guidance or re-scope |
+| `cancelled` | 130 | stopped | resume if wanted |
+
+Trust `status`, `checks`, and `changes`. They come from what zcode observed. Treat `handback` and `summary` as the executor's report. A subagent's `success` only means it returned. zcode already verified the integrated result through your checks, so you don't need to review per subagent or per step.
+
+## Example: small task
+
+```sh
+zcode task --id fix-typo --cwd ~/site --owns README.md \
+  --check "grep -q '^# Acme Docs' README.md" \
+  "Fix the misspelled top-level heading in README.md (should read 'Acme Docs')" --json --quiet
+```
+
+Exit 0 means it's done. The result line shows the single changed file and the passing check.
+
+## Example: Page 1 and Page 2 in parallel
+
+You've already decided the design. Each page gets its own session, its own scope, and its own checks:
+
+```sh
+zcode task --detach --id page-1 --cwd ~/site --label "Home page" \
+  --owns src/pages/home/ --file src/theme.ts \
+  --context @specs/home.md \
+  --accept "Hero, three feature cards, footer CTA as specified" \
+  --check "npm run build" --check "npm test -- home" \
+  "Implement the Home page exactly as specified in the context"
+
+zcode task --detach --id page-2 --cwd ~/site --label "Pricing page" \
+  --owns src/pages/pricing/ --file src/theme.ts \
+  --context @specs/pricing.md \
+  --accept "Three plan cards, middle one highlighted; monthly/yearly toggle" \
+  --check "npm run build" --check "npm test -- pricing" \
+  "Implement the Pricing page exactly as specified in the context"
+
+zcode wait page-1 page-2 --timeout-ms 540000 --json --quiet   # repeat while exit is 124
+```
+
+If `page-2` comes back `blocked` with "Should yearly prices show the discount badge?", decide and run `zcode resume page-2 "Yes, show the 'Save 20%' badge on yearly." --detach`, then wait again. To run the pages one after another instead, start `page-2` after `page-1`'s handback. The shared `src/theme.ts` is passed with `--file` (read), not owned, so a change to it by either session would come back as a scope violation. If a page truly needs a shared change, make it yourself or give that file to exactly one session's `--owns`.
+
+## Exit codes
+
+0 completed · 2 usage (bad flag, contract, or duplicate id) · 3 no key · 4 no engine · 5 failed · 6 `agent` had no subagent · 7 workspace conflict / session busy · 8 partial or checks failing · 9 unverified · 10 blocked · 124 timeout (for `wait`: still running) · 130 cancelled.

package/skills/codex/zcode/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "zcode executor"
+  short_description: "Delegate scoped, verified work to zcode"
+  default_prompt: "Use $zcode to implement this scoped change in a verified zcode session and report its handback."