opencode-skills-collection 4.0.45 → 4.0.46

package/bundled-skills/warp-delegate/references/multi-task-queues.md

@@ -0,0 +1,80 @@
+# Multi-task queues
+
+A queue is a list of briefs run through Warp one at a time, each reviewed before the next is
+dispatched. It is the shape to reach for when the user hands you a backlog rather than a single
+task.
+
+## Run them sequentially
+
+Dispatch one brief, review it, land it, then dispatch the next. Parallel runs against the same
+working tree interleave edits into a diff nobody can review — and because `oz agent run` has no
+sandbox, there is nothing to keep two runs out of each other's files.
+
+If tasks are genuinely independent and you want them concurrent, give each its own checkout (a git
+worktree) and its own `--cd`. Otherwise, keep the queue serial.
+
+## Carry constraints forward
+
+Each brief is self-contained, so a constraint discovered in task 2 does not reach task 5 by itself.
+Keep a short running list and paste the relevant lines into every subsequent brief:
+
+- Conventions you had to correct in an earlier review ("use the existing `Result` type, not
+  exceptions").
+- Files that are off-limits for the whole queue.
+- Gates that turned out to be slow, flaky, or need a flag.
+- Decisions already made, so a later task does not relitigate them.
+
+A constraint that had to be corrected twice belongs in the repository's own skill directory
+(`.agents/skills/`, `.warp/skills/`) instead — then pass it with `--skill` and stop re-pasting it.
+
+## One out-dir per task
+
+Give every dispatch its own `--out-dir` so artifacts do not overwrite each other:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief briefs/03-stream-export.txt \
+  --cd /path/to/repo --out-dir /tmp/warp-queue/03 --name "queue-03-stream-export"
+```
+
+`--name` labels the run in Warp's own run list, which makes a queue far easier to follow later.
+Keeping the out-dirs numbered means `result.json`, `events.jsonl`, and `final.txt` for any task stay
+recoverable after the queue has moved on.
+
+## Track progress where the user can see it
+
+Maintain a visible checklist — the orchestrator's task list, or a scratch file — with one line per
+task and its state: pending, dispatched, under review, landed, or abandoned. Record the commit sha
+as each task lands, and the reason whenever one is abandoned.
+
+## When a task fails
+
+Do not roll straight into the next brief. Decide first:
+
+- **Rework** — the diff is close. Continue the conversation with `--conversation <id>` and a delta
+  brief.
+- **Re-scope** — the task was too big or the brief was wrong. Split it and requeue the parts.
+- **Abandon** — it depends on something that is not true yet. Record why and move on.
+
+A failed task that leaves a dirty tree must be cleaned up before the next dispatch. `git status`
+should be clean, or clean except for work you have deliberately kept.
+
+## Stop the queue when
+
+- Two consecutive tasks fail for the same underlying reason — the shared assumption is wrong, and
+  the remaining briefs probably inherit it.
+- A task reveals the plan itself is wrong. Re-plan with the user rather than working the list.
+- The gates start failing for reasons unrelated to the current task; something earlier in the queue
+  broke and the diff is no longer trustworthy.
+
+## Final coherence pass
+
+Ten individually correct diffs can still add up to an incoherent whole. When the queue is done,
+review the aggregate — `git diff <first-commit>~1..HEAD`:
+
+- Duplicated helpers that separate tasks each introduced.
+- Naming that drifted between early and late tasks.
+- Docs, types, or tests that an earlier task's assumption made stale.
+- Dead code left by a later task superseding an earlier one.
+
+Fix these yourself if small. If the cleanup is substantial, it is one more brief — dispatch it with
+the aggregate diff as the current state.

package/bundled-skills/warp-delegate/references/review-and-land.md

@@ -0,0 +1,123 @@
+# Review and land
+
+Warp edits the working tree. **You commit.** That boundary is the point of the skill: the
+implementer produces a diff, and a reviewer who did not write it decides whether it ships.
+
+## Why the review is not optional here
+
+Every delegate skill asks you to verify the implementer's claims. Warp raises the stakes: `oz agent
+run` has no sandbox, no permission mode, and no read-only run, so nothing constrained what the run
+could touch while it worked. The diff is not a courtesy record — it is the only record.
+
+## The checklist
+
+Work through these in order. Stop at the first one that fails and decide whether to rework or
+discard.
+
+1. **Read `result.json` first.** If there is no `result.json`, stop: a usage error exits 2 before
+   Warp is ever dispatched and writes none, so an absent file means the run did not happen — read the
+   relay's stderr, not the tree. Otherwise require `status: "completed"` and `exitCode: 0` before
+   going further. `failed`, `timeout`, `aborted`, and `warp_unavailable` all mean the run did not
+   finish on its own terms, and `timeout` and `aborted` additionally mean the tree may be mid-edit
+   and incoherent. Rework or discard from the baseline rather than reviewing a partial run.
+2. **Start from `touchedFiles`.** It is `git status --porcelain` taken after the run: post-run,
+   git-visible worktree state, not a log of what the agent did. It cannot show an ignored file, an
+   edit the run made and then reverted, or a write outside the repository, and it includes anything
+   already dirty before dispatch. Start there, but do not read it as the complete set. `null` means
+   git could not report — inspect the tree by hand. `[]` on a run that claimed edits is a
+   contradiction worth chasing.
+3. **Re-run the gates yourself.** Do not accept "tests pass" from `finalMessage`. Run the project's
+   actual lint, typecheck, build, and test commands and read the output. Take "actual" from
+   `CONTRIBUTING.md`, the CI config, or `package.json`: a project's gate set often includes a
+   packaging, manifest, or schema validation step that lint and test do not cover, and that is
+   exactly the gate a run can break without any test going red.
+4. **Read the whole diff against the brief.** `git diff` and `git diff --staged` — then open every
+   `??` path in `touchedFiles` directly, including everything inside an untracked directory. Neither
+   diff command shows the contents of an untracked file, so a file Warp created is invisible to both
+   and would otherwise reach your commit unread. Ask of each hunk and each new file: did the brief
+   ask for this? Changes outside the brief's stated scope are the thing to catch.
+5. **Check what should NOT have changed.** Lockfiles, CI config, formatter config, unrelated
+   modules, and anything the brief listed under "leave untouched".
+6. **Grep for dangling references** after any removal or rename — imports, string keys, docs.
+7. **Round-trip migrations.** Apply and roll back before trusting a schema change.
+8. **Run guard skills** if the repository has them installed.
+9. **Confirm nothing was committed.** `git log -1` should still be your last commit. The relay never
+   commits; if a commit exists, the agent made it despite the brief — treat that as a finding.
+
+## Reading `finalMessage` correctly
+
+`finalMessage` is Warp's self-report: a claim, not evidence. Read it for two things only —
+
+- **Decisions it made that the brief did not specify.** These are the parts you most need to surface
+  to the user.
+- **What it says it could not do.** Usually accurate, and it tells you where to look first.
+
+Everything else in it — "all tests pass", "no other files changed" — is a hypothesis your gates and
+your diff read either confirm or refute. If `finalMessage` is empty on a run that exited 0, read
+`events.jsonl` rather than assuming the run did nothing.
+
+## Rework through a conversation
+
+When the diff is close but wrong, continue the same conversation rather than starting cold:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief delta-brief.txt --cd /path/to/repo \
+  --conversation "$(jq -r .conversationId /tmp/warp-run-1/result.json)"
+```
+
+Warp still holds the earlier exchange, so send only the delta — what was wrong, what to change, what
+to leave alone. See [writing-the-brief.md](writing-the-brief.md#delta-briefs).
+
+If `conversationId` is `null`, the stream did not carry one; dispatch a fresh run with a brief that
+restates the corrected requirements.
+
+Discard rather than rework when the diff misunderstood the goal, wanders far outside the brief, or
+would take longer to correct than to redo.
+
+Discard against a known baseline, never with a blanket revert. `git checkout -- .` is the wrong
+reach: it leaves staged and untracked files behind, so the tree stays dirty for the next dispatch,
+and it destroys any uncommitted work of your own that predates the run. Dispatch from a clean tree —
+commit your own changes, or `git stash push --include-untracked` them. A bare `git stash` leaves
+untracked files in place, and those resurface as `??` entries in `touchedFiles`, where the cleanup
+below would delete work the run never made. Confirm `git status --porcelain` prints nothing before
+dispatching, so that everything dirty afterward is Warp's, then drop exactly what the run
+introduced, reading the paths off `touchedFiles`:
+
+```bash
+git restore --staged --worktree -- <tracked paths>   # the ' M' / 'M ' entries
+git clean -f -- <untracked paths>                    # the '??' entries
+```
+
+A `??` entry can name a whole directory rather than each file under it; passing that path removes
+the directory and its contents, since `-d` only governs the no-pathspec case. The exception is a
+nested git repository — if the run scaffolded one, `git clean -f` skips it and `-ff` is required.
+
+If dispatching from a clean tree is not an option, give Warp its own `git worktree` instead: then
+discarding is `git worktree remove --force`, and your work was never in reach. Either way, rewrite
+the brief before dispatching again.
+
+## Landing
+
+Commit once the gates pass and the diff holds. Write the commit message yourself: it should describe
+the change, not the delegation. Do not credit the tool in the message unless the project's own
+convention asks for it.
+
+## Surface, don't absorb
+
+Delegation is something the human opted into, and committing verified, gate-passing work is the
+agreed contract. Two limits stay with you:
+
+- **Surface, don't absorb.** Report Warp's design decisions, its defensible-but-unasked turns, and
+  the non-blocking nitpicks you chose not to fix. Silently smoothing them over hides the
+  implementer's judgment from the person who owns the code.
+- **Stop for scope changes.** If finishing correctly requires going beyond the brief — a dependency
+  bump, a schema change, an interface the brief did not mention — ask rather than expanding the
+  mandate yourself.
+
+Snapshot egress is a decision you make **before** dispatch, not something you report after it. `oz
+agent run` uploads an end-of-run workspace snapshot by default, so reading `snapshotDisabled: false`
+off a finished run tells you only that the upload already happened. If the repository is sensitive,
+pass `--no-snapshot` on the dispatch and confirm `snapshotDisabled: true` in `result.json` before
+going further. Keep reporting the field either way — it is the evidence of which way the run went.
+
+Also surface the `runUrl` when someone will want to inspect the run in Warp.

package/bundled-skills/warp-delegate/references/writing-the-brief.md

@@ -0,0 +1,105 @@
+# Writing the brief
+
+The brief is the whole contract. Warp sees only the text you send plus whatever it can inspect in
+the workspace — no chat history, no shared context, none of the reasoning that led you here.
+
+## How the brief reaches Warp
+
+`oz agent run` requires one of `--prompt`, `--saved-prompt`, `--task-id`, or `--skill`. Its
+`-f/--file` config path does **not** satisfy that requirement, so there is no stdin or file channel
+for the task text: the relay passes the brief as the `--prompt` value on argv.
+
+Two consequences that do not apply to the other skills in this package:
+
+- **The brief is visible in the host process list** (`ps`, Activity Monitor, Task Manager) for as
+  long as the run is live. Keep credentials, tokens, and customer data out of it. Point Warp at a
+  file in the repo or an environment variable instead of inlining a secret.
+- **A very large brief can hit the OS argument limit.** Practical briefs are far below it, but a
+  brief that inlines whole files can trip it. Reference paths rather than pasting file contents —
+  Warp can read the workspace itself.
+
+Because the brief rides argv, the relay never launches `oz` through a shell on any platform.
+
+## Structure
+
+Cover these in order. Skip a heading only when it genuinely does not apply.
+
+1. **Goal** — one sentence on the outcome, not the mechanics.
+2. **Current state** — where the code is now, and the paths that matter. **Name the workspace root
+   as an absolute path**, and prefer absolute paths for the files you call out. `--cwd` is not
+   uniformly honoured: on a verified run against oz 0.2026.05.27, shell commands executed in the
+   pinned workspace (`pwd` returned it), but the agent stated its working directory was `/` and its
+   file-reading tool resolved bare relative paths against `$HOME` — so `src/strings.js` was first
+   read as `/Users/<you>/src/strings.js`. The agent recovered by running `pwd` and retrying, but it
+   burned a turn, and in a home directory that happened to hold a matching path it would have read
+   the wrong file. There is no sandbox to catch that.
+3. **What to change** — the specific edits, in the order they make sense.
+4. **What to leave untouched** — files, patterns, and public interfaces that must not move. Warp has
+   no sandbox, so this is a written boundary, not an enforced one.
+5. **Gates** — the project's *actual* commands. Read them out of `package.json`, `Makefile`, or the
+   CI config; do not invent `npm test` because it is conventional.
+6. **Report contract** — what the final message must state (below).
+7. **Do not commit** — say it explicitly. Committing is the orchestrator's job.
+
+## The report contract
+
+Ask for a final message that states, plainly:
+
+- What changed, file by file.
+- Which gate commands were run, and their exact outcome.
+- Anything the run could not do, and why.
+- Any decision it made that the brief did not specify.
+
+The relay captures that message as `finalMessage` in `result.json` and as `final.txt`. Treat it as a
+claim to verify, never as verification — see [review-and-land.md](review-and-land.md).
+
+## Repository context files
+
+Warp reads skills from `.agents/skills/`, `.warp/skills/`, `.claude/skills/`, and `.codex/skills/`.
+If the repository carries conventions in one of those, name it with the relay's `--skill` flag
+(`name`, `repo:name`, or `org/repo:name`) so it becomes the base prompt and your brief stays the
+task. Anything not in one of those locations — a plain `CONTRIBUTING.md`, for instance — must be
+referenced by path in the brief; do not assume it is loaded.
+
+## One task per brief
+
+A brief that carries two unrelated changes produces a diff you cannot review cleanly and a
+conversation you cannot resume precisely. Split them and queue the parts — see
+[multi-task-queues.md](multi-task-queues.md).
+
+## Delta briefs
+
+When you continue a conversation with `--conversation <id>`, Warp still holds the earlier exchange.
+Send only what changed:
+
+- What you reviewed and what was wrong — be specific about the file and the symptom.
+- What to do about it.
+- What to leave alone from the previous round.
+- The gates to re-run.
+
+Do not re-send the original brief. Restating a satisfied requirement invites Warp to redo work that
+was already correct.
+
+## Worked example
+
+```text
+Goal: make the CSV export stream instead of buffering the whole result set.
+
+Current state: src/export/csv.ts builds one string in memory (see toCsv) and
+returns it from the /export route in src/routes/export.ts.
+
+Change:
+- Rewrite toCsv to return a Readable that yields one row at a time.
+- Update the /export route to pipe that stream to the response.
+- Keep the column order and the quoting behaviour exactly as they are now.
+
+Leave untouched: the public signature of toCsv's caller in src/routes/export.ts
+beyond the pipe change, and every file under src/import/.
+
+Gates: `npm run lint`, `npm run typecheck`, `npm test -- export`.
+
+Report: list each file you changed, quote the exact output of each gate command,
+and state anything you could not finish.
+
+Do not commit. Leave the changes in the working tree.
+```

package/bundled-skills/zcode-delegate/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: zcode-delegate
+description: Delegate coding tasks to the Z.AI ZCode CLI only when the user explicitly
+  requests it, while the orchestrator retains review and landing responsibility.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+compatibility: Requires the `zcode` CLI (Z.AI ZCode) with a configured model provider,
+  Node 18+, and git. ZCode ships its CLI inside the desktop app rather than on PATH
+  or npm — see Prerequisites. The orchestrating agent must be able to run shell commands
+  and read files. Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on
+  Windows).
+metadata:
+  version: 0.5.0
+---
+# ZCode Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `zcode` implementer (`Z.AI ZCode`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
+**implementer** — the Z.AI ZCode CLI — then review what it produced and land it yourself. You write
+the brief and own the judgment; ZCode does the typing; you verify and commit.
+
+Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
+command and read a file. (It is designed for and run on Claude Code; treat other orchestrators as
+designed-for, not yet proven.)
+
+## When NOT to use this
+
+- The task is small enough to just do inline — delegation overhead is not worth it.
+- ZCode is not installed, or its CLI has no model provider configured.
+- You want to write the code yourself, or you only need a review.
+
+## Prerequisites (check once)
+
+1. **ZCode is installed.** The CLI ships **inside the desktop app** — it is not on PATH and not on
+   npm. The relay resolves it in this order: `--zcode-path <file>` or `ZCODE_CLI` first, then PATH,
+   then the installed app bundle. On Linux the app is an AppImage with no fixed install path, so
+   the flag or the environment variable is required there — the relay guesses nothing.
+2. **A model provider is configured for the CLI**, with a key it can actually reach. Being signed
+   into the desktop app is *not* enough — see below.
+3. You are in (or will point `--cd` at) the target git repository.
+
+The relay records the CLI version and how it was resolved into `result.json`, so a surprising
+install is visible after the fact.
+
+## Authenticating the headless CLI
+
+**Signing into the ZCode desktop app does not authenticate the CLI this relay drives.** The CLI
+keeps its own config at `~/.zcode/cli/config.json`, separate from the desktop app's, and nothing
+bridges the two. `zcode login` is the intended path, but where it fails with `OAuth response is
+not valid JSON` the way in is a Z.AI API key.
+
+Two pieces are needed, and they are separate:
+
+1. **The provider block** must exist in `~/.zcode/cli/config.json`. It defines the provider, its
+   endpoint and its models — the environment cannot supply this:
+
+   ```jsonc
+   {
+     "provider": {
+       "zai": {
+         "kind": "anthropic",
+         "options": { "apiKeyRequired": true, "baseURL": "https://api.z.ai/api/anthropic" },
+         "models": { "glm-5.1": { "name": "GLM-5.1" } }
+       }
+     },
+     "model": { "main": "zai/glm-5.1" }
+   }
+   ```
+
+2. **The key** can live either in `provider.zai.options.apiKey` in that file, or in the
+   environment as any one of `ZAI_API_KEY`, `ZCODE_API_KEY`, or `ANTHROPIC_API_KEY`. Prefer the
+   environment — it keeps the secret off disk.
+
+If a run fails with `Model provider is missing an API key: <provider>`, the provider block resolved
+but no key was found: set one of those variables and re-run.
+
+## Autonomy — read this before dispatching
+
+ZCode's own term is **mode**. It has four values; only two are usable headlessly.
+
+| mode | Behaviour |
+| --- | --- |
+| `yolo` | **Writes.** ZCode's own default for `--prompt`, and this relay's write-capable default. |
+| `plan` | **Refuses edits.** What `--read-only` selects. |
+| `build` | **Rejected by this relay.** No permission client exists headlessly, so tools are blocked and the run exits 0 having done nothing. |
+| `edit` | Rejected for the same reason. |
+
+Two limits stated plainly, because ZCode cannot enforce them:
+
+- **`plan` mode refused edits in testing, but the relay does not treat that as a guarantee.** It
+  takes a Git fingerprint before the run and reports a tri-state `readOnlyViolation` afterwards.
+  Confirm `touchedFiles` came back empty rather than assuming no edits.
+- **ZCode has no `--allowed-tools`.** Only the `--disallowed-tools` denylist exists, and it *is*
+  genuinely enforced. An explicit allowlisted tool surface is therefore impossible here — do not
+  assume one.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+ZCode sees **only** what you send — no repo memory, no chat history. Everything the task needs goes
+in the brief: the goal, the current state, what to change, what to leave untouched, the project's
+**actual** gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not
+assume), and a report contract. Tell ZCode it will **not** commit. One task per brief. The relay
+delivers the brief as an attached file, so the command line no longer bounds its length — the
+model's context window still does. Full guidance and a template:
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# read-only (review/diagnosis, no edits):   add --read-only
+# continue a specific session:              add --session <sess_...>  (from result.json; send only the delta brief)
+# continue the latest session for --cd:     add --resume-last
+# withhold tools (denylist):                add --disallowed-tools "Write,Edit,Bash"
+# point at the CLI explicitly:              add --zcode-path /path/to/zcode.cjs
+# hard time limit (watchdog):               add --timeout 2h  (default: off)
+# see all options:                          node .../relay.mjs --help
+```
+
+(`<skill-dir>` is this skill's installed directory — the folder containing this `SKILL.md`.)
+
+The relay writes its artifacts to a temp dir, so the repo under review stays clean. It **never
+commits** — see step 5. Mechanics, flags, and the `result.json` shape:
+[references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The relay blocks until ZCode finishes, so back it with whatever your orchestrator offers:
+
+- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
+- **Plain shell / other agents:** foreground for short tasks, or background it and poll the result
+  file. The run is done when `result.json` exists with a `status`. A pre-run usage error exits 2 and
+  writes **no** result file, so check the exit code too; a CLI that cannot be found exits 127 but
+  *does* write a `result.json` with status `zcode_unavailable`.
+
+Do not trust progress trackers over reality: read the working tree, not a status line.
+
+### 4. Review — do not trust the self-report
+
+- **Re-run the project's gates yourself.** Never take "gates passed" on faith.
+- **Read the diff** against the brief: did ZCode do what was asked, nothing more and nothing less?
+  `touchedFiles` is your starting point.
+- **On a `--read-only` run, check `readOnlyViolation` and confirm `touchedFiles` is empty.**
+- Run the relevant guard skills on the diff if you have them installed.
+
+Full checklist: [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+**The orchestrator commits.** Only after the gates pass and the diff holds:
+
+- Commit the verified work yourself, with a clear message.
+- If it needs changes, send a delta brief with `--session <sessionId>` from the prior `result.json`,
+  and review again.
+
+## Read-only second opinions
+
+The relay doubles as a way to get an adversarial second opinion with no write risk: dispatch
+`--read-only` with a brief listing the agreed points, then each contested point with both positions,
+and ask ZCode to defend or concede each. Because plan mode's guarantee is measured rather than
+enforced here, verify `touchedFiles` came back empty instead of assuming no edits.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have, committing verified, gate-passing work
+is the agreed contract. Two limits: **surface, don't absorb** (report ZCode's design decisions and
+defensible-but-unasked turns rather than silently keeping them) and **stop for scope changes** (if
+correct completion needs going beyond the brief, ask). The full treatment is in
+[references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — how to write a brief ZCode can
+  execute blind: structure, the report contract, embedding the real gate commands.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — `relay.mjs` flags, the
+  `result.json` contract, how the CLI is resolved, backgrounding, and recovery.
+- [references/review-and-land.md](references/review-and-land.md) — the review checklist, the commit
+  boundary, and the exact-session rework cycle.
+- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
+  carrying constraints forward, progress tracking, and the end-of-run coherence check.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `zcode` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.

package/bundled-skills/zcode-delegate/references/dispatch-and-poll.md

@@ -0,0 +1,113 @@
+# Dispatch and poll
+
+The relay wraps the ZCode CLI so your job is "run a command, read a file."
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+cat brief.txt | node "<skill-dir>/scripts/relay.mjs" --cd /path/to/repo
+```
+
+## How the relay finds ZCode
+
+ZCode does not install a `zcode` binary on PATH and does not publish one to npm — the CLI ships
+inside the desktop app. The relay resolves it in this order, first hit wins:
+
+1. `zcode` on **PATH** — if you made a shim or alias, this is used.
+2. **`--zcode-path <file>`**, else the **`ZCODE_CLI`** environment variable.
+3. The installed **app bundle**: `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs` on Windows,
+   `/Applications/ZCode.app/…` (and `~/Applications/…`) on macOS. Linux ships an AppImage with no
+   fixed install path, so there is nothing to auto-discover there — use option 1 or 2.
+
+A resolved `.cjs` bundle is launched under `node`. `result.json` records which route was used in
+`zcodeSource` (`path` / `flag` / `env` / `bundle`), so a surprising install is visible after the run.
+
+If no CLI is found — including when you name one explicitly that does not exist — the relay exits
+**127** and still writes a `result.json` with `status: "zcode_unavailable"`.
+
+## Options
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | Path to the brief. Omitted → read from stdin. |
+| `--cd <dir>` | Working root for ZCode (default: current directory). |
+| `--lane <name>` | Fleet lane from `delegate-setup` config. Explicit flags win over lane dials. |
+| `--mode <mode>` | ZCode's `--mode`. **Only `plan` and `yolo` are accepted** (see below). Default `yolo`. |
+| `--read-only` | Shortcut for `--mode plan` (review/diagnosis, no edits). |
+| `--disallowed-tools <list>` | Comma/space-separated denylist, e.g. `"Write,Edit,Bash"`. Enforced by ZCode. |
+| `--session <id>` | Continue a specific session by `sess_…` id from a prior `result.json`. |
+| `--resume-last` | Continue the latest session **for `--cd`**. Mutually exclusive with `--session`. |
+| `--zcode-path <file>` | Point at the CLI explicitly. |
+| `--timeout <dur>` | Relay-side watchdog (default: off). `30m`, `2h`. ZCode has no timeout flag of its own. |
+| `--out-dir <dir>` | Where to write run artifacts (default: a fresh dir under the system temp dir). |
+| `-h, --help` | Show help. |
+
+### Why `build` and `edit` are rejected
+
+ZCode documents four modes. Headless runs have no permission client, so under `build` or `edit` the
+Write and Bash tools are blocked and the run **exits 0 having changed nothing**, with a report
+explaining that tool permissions were denied. That is a success status for a run that did no work,
+so the relay refuses those modes up front with a usage error (exit 2) rather than letting them look
+like a completed task. Use `--mode yolo` to write, or `--read-only` for plan mode.
+
+## The `result.json` contract
+
+Speaks `delegate-relay.result.v1`.
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `completed` \| `failed` \| `timeout` \| `aborted` \| `zcode_unavailable` |
+| `exitCode` | ZCode's own exit code, or the relay's mapping for a killed run |
+| `signal` | The signal that killed the child, or `null` |
+| `finalMessage` | ZCode's final report (its `response` field) |
+| `sessionId` | The `sess_…` id — pass to `--session` to continue this exact session |
+| `touchedFiles` | Git porcelain paths. `[]` when the tree is clean, `null` when git cannot report. |
+| `mode` | The ZCode mode the run actually used |
+| `readOnlyViolation` | Tri-state. `false` = the tripwire saw no change on a plan run, `true` = it did, `null` = unknown or not applicable |
+| `usage` | ZCode's token accounting (input, output, total, cache reads) |
+| `contextWindow` | From ZCode's `projection` |
+| `zcodeVersion`, `zcodeSource` | Which CLI ran, and how it was found |
+| `briefPath`, `outputPath`, `finalPath` | Run artifacts on disk |
+
+Exit codes: a pre-run usage error (bad args, empty brief, a rejected `--mode`) exits **2** and writes
+**no** result file. A CLI that cannot be found exits **127** and *does* write one. Otherwise the exit
+code mirrors ZCode's, and a run killed by the watchdog reports `timeout`.
+
+An orchestrator that polls for the file must therefore also check the exit code — a non-zero exit
+with no file is a usage error, not a crashed run.
+
+## Backgrounding
+
+- **Claude Code:** run the Bash call with `run_in_background: true`.
+- **bash/zsh (incl. Git Bash/WSL):** `… &`, then poll for `result.json`.
+- **PowerShell:** `Start-Job`. **cmd:** `start /b`.
+
+The run is finished when `result.json` exists with a `status` *and* the process has exited.
+
+## Reading the output
+
+ZCode's `--json` prints a single JSON document at the end rather than a stream of events, and the
+relay parses it tolerantly: the bundled AI SDK sometimes prints a warning banner on stdout ahead of
+the JSON, so leading non-JSON lines are skipped. The raw stdout is preserved at `outputPath` and the
+final report at `finalPath`, so nothing is lost if parsing degrades.
+
+If the document cannot be parsed at all:
+
+- with exit 0, the run is still `completed`, `finalMessage` falls back to the raw stdout, and a
+  `parseWarning` field is set — read `outputPath` yourself.
+- with a non-zero exit, the run is `failed` and `stderrTail` carries the last lines of stderr.
+
+## When a run misbehaves
+
+- **`status: "timeout"`** — the watchdog fired. The whole ZCode process tree was killed. Inspect the
+  working tree before re-dispatching; a killed run can leave partial edits.
+- **`status: "aborted"`** — the relay itself was killed and forwarded the kill. Same advice.
+- **`status: "zcode_unavailable"`** — no CLI found. Check the three resolution routes above.
+- **Exit 1 with `Session not found`** — the `--session` id does not exist. Session ids are
+  `sess_`-prefixed; copy them from a prior `result.json`, not from memory.
+- **`completed` but `touchedFiles` is empty on a write run** — read `finalMessage`. ZCode may have
+  reported that it could not proceed. That is a real outcome, not a relay bug.
+- **`(no final message captured)` on a resumed plan-mode run** — ZCode has been observed returning
+  `"response": ""` while doing substantial work (658 output tokens across 602 events in one measured
+  run). The relay reports what ZCode sent, so an empty report here is the CLI's, not a parse failure:
+  `parseWarning` will be absent and `usage` non-zero. Read `outputPath` and the working tree rather
+  than concluding nothing happened.