opencode-skills-collection 4.0.45 → 4.0.46

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

@@ -0,0 +1,59 @@
+# Multi-task queues
+
+The single-task loop scales to a queue: a removal across layers, a migration across files, or a
+refactor sweep. Sequencing and bookkeeping make it trustworthy.
+
+## Run sequentially, one commit per task
+
+Run tasks **one at a time, in dependency order**, landing each after review and gates before
+dispatching the next:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief task-01.txt --cd /path/to/repo
+```
+
+- Later briefs can rely on earlier work only after it lands.
+- One commit per task keeps history reviewable and each step revertible.
+- A clean tree before each dispatch keeps `touchedFiles` honest.
+
+Use parallel runs only for genuinely independent tasks in separate working trees. Sequential is the
+default because it preserves clean task boundaries.
+
+## Carry decided constraints forward
+
+Fresh Vibe sessions do not remember earlier tasks. If task 2 chooses a helper name, fixture location,
+or interface that task 5 needs, write that fact into task 5's brief.
+
+Use a resumed Vibe session only for rework on the same task. Send a delta brief with `--resume-last`;
+use `--session <id>` only for an id obtained outside the relay because Vibe's stream does not expose
+one. Start unrelated queue items in fresh sessions.
+
+## Keep a progress file
+
+For more than two or three tasks, maintain one progress file beside the work:
+
+- **Status table** — queued / at-implementer / reviewed+committed, with the commit hash.
+- **Per-task review notes** — what landed, what you verified, and gate outcomes.
+- **Needs your eyes** — design decisions, non-blocking nitpicks, and questions for the human.
+- **End-of-run checklist** — the final cross-task verification.
+
+Update it when each task lands, not in one batch at the end.
+
+## Close with a coherence check
+
+After the last task:
+
+- Run the full test/build once more.
+- Search repo-wide for the thing the queue changed.
+- Replay migrations from a clean state and check drift when applicable.
+- Push and open or update the PR only after the final tree is coherent.
+
+## When to stop and ask
+
+Proceed on work that follows from the agreed plan. Stop and surface when:
+
+- A task cannot be completed correctly within its brief.
+- Review calls the plan itself into question.
+- Gates reveal a problem affecting already-landed tasks.
+
+Report the landed state, commit hashes, and open question, then wait.

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

@@ -0,0 +1,87 @@
+# Review and land
+
+Vibe did the typing; you own the judgment. Verify against reality, never the self-report, and read the
+diff as generated code because a green gate cannot catch every failure mode.
+
+## Check tests before trusting gates
+
+If the diff touches existing tests, review those edits first:
+
+- Treat unbriefed test edits as a contract change, not part of the fix.
+- Treat newly skipped, disabled, or commented-out tests as failing until proven otherwise.
+- Treat loosened assertions the same way: contains/truthy replacing exact matches, broadened error
+  types, and widened tolerances all weaken the gate.
+
+## Re-run the gates yourself
+
+`result.json` carries Vibe's claims, not evidence. Re-run the project's actual test, lint, and build
+commands in the working tree and read their output. Passing is necessary, not sufficient.
+
+For changes with a specialized verification shape:
+
+- **Migrations or schema:** round-trip them and check for drift.
+- **Removals or renames:** grep for dangling references.
+- **Stateful behavior:** exercise the behavior, not just compilation.
+
+## Read the diff against the brief
+
+Start with `touchedFiles`, open the diff, and compare it to the brief:
+
+- **Scope creep** — changes the brief excluded.
+- **Scope shortfall** — missed behavior, edges, or cleanup.
+- **Quiet judgment calls** — defensible but unasked decisions that need review.
+
+## The implementer sweep
+
+Check every diff for patterns gates often miss:
+
+- Hardcoded success or fixture data on a real-work path.
+- Catch-all error handling that returns a default instead of propagating or recovering.
+- Imports, dependencies, methods, and signatures not present in the installed version.
+- Unused imports, uncalled helpers, unreachable branches, and scaffolding comments.
+- A second client, error idiom, or logging style beside the repo's existing one.
+- Tests that assert internals instead of behavior, or near-duplicate test bodies.
+- Optional parameters, config flags, and abstractions with no caller.
+- Guards for impossible cases that hide trust-boundary validation.
+
+Send anything blocking back to Vibe as a delta brief, or fix it in the tree, and report either choice
+to the human. Run relevant guard skills if installed.
+
+## The commit boundary
+
+When the gates pass and the diff holds, **the orchestrator commits**, never the implementer. Write a
+clear message describing what landed.
+
+From dispatch until that commit, the uncommitted working tree is the authoritative copy of Vibe's
+work. Never reflexively run `git checkout`, `reset`, `clean`, or switch branches after an interrupted
+run. Inspect `git status`, `git diff`, `git diff --cached` for staged changes, and open every untracked
+file (`??`) directly because no diff shows its contents. After inspection, discarding a bad or
+premise-contaminated change can be correct; the rule is to preserve the evidence until it is reviewed.
+
+## Rework: send the delta
+
+Continue the same session with only the correction:
+
+```bash
+echo "The fix is right, but the test mocks the DB session. Use the real migrated fixture and remove
+the unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo
+```
+
+Vibe's stream does not expose a session id, so use `--resume-last` normally. Use `--session <id>` only
+when the id came from outside the relay. Rework gets the same gate rerun, test review, diff review, and
+implementer sweep.
+
+Default `accept-edits` runs cannot execute most gates headlessly; the orchestrator runs them.
+`--full-access` permits arbitrary shell/tool execution and requires explicit human authorization.
+
+## Surface, do not absorb
+
+The human opted into delegation, so committing verified, gate-passing work is the contract. Keep them
+in the loop when the work changes shape:
+
+- Report design decisions and defensible-but-unrequested turns.
+- Note non-blocking nitpicks you did not block on.
+- Stop and ask if correct completion requires going beyond the brief.
+
+For a queue, keep these notes in the progress file described in
+[multi-task-queues.md](multi-task-queues.md).

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

@@ -0,0 +1,131 @@
+# Writing the brief
+
+A brief is the entire task as Vibe will see it. It runs in a separate session with **no memory of your
+conversation, no access to prior notes, and no shared context** — only the text you send and whatever
+it can inspect in the workspace. If a constraint is not in the brief or discoverable in the repo, it
+does not exist for Vibe.
+
+## Resumed sessions
+
+A resumed run keeps the session context. Send only the delta brief with `--resume-last` or
+`--session <id>`.
+
+## The shape that works
+
+Use a compact, block-structured brief. State the task, what done means, the few constraints that
+matter, and the report Vibe must return.
+
+```xml
+<task>
+One or two sentences: the concrete job and where it lives. Then the specifics — current state, what to
+change, and explicitly what to leave untouched. The leave-untouched list prevents unrelated refactors.
+</task>
+
+<verification_loop>
+These are the real project gates the orchestrator will run after dispatch:
+  <the project's real test command>
+  <the project's real lint/format command>
+  <the project's real build/typecheck command>
+If shell execution was explicitly authorized for this run, run them and fix what they surface.
+Otherwise do not claim they ran; perform the inspections available to you and report the gates as not run.
+</verification_loop>
+
+<action_safety>
+Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
+correctness. Do NOT run git add or git commit — the orchestrator commits after reviewing. Leave the
+work uncommitted in the working tree.
+</action_safety>
+
+<structured_output_contract>
+End with a report in this exact shape:
+  1. What changed and why
+  2. Files touched
+  3. Gate outcomes with counts, or exactly which gates were not run
+  4. Anything you deviated on, left open, or want a decision on
+</structured_output_contract>
+```
+
+Add extra blocks only when the task needs them:
+
+- **Debugging or open-ended fixes** — add `<completeness_contract>` (resolve fully, not just the
+  first plausible cause) and `<missing_context_gating>` (find missing repo facts or state what is
+  unknown).
+- **Research or recommendations** — add `<research_mode>` (separate observed facts, inferences, and
+  open questions).
+
+## Always ask for the report explicitly
+
+The relay uses Vibe's last non-empty assistant message as `finalMessage`. Without a
+closing summary, the edits may exist but the result is hard to review. The
+`<structured_output_contract>` block makes the expected report explicit.
+
+## Discover the real gates
+
+Read the repo's `AGENTS.md`, `CLAUDE.md`, `Makefile`, `package.json`, or equivalent first and copy the
+actual commands into `<verification_loop>`. Default `accept-edits` runs cannot execute most gates
+headlessly, but naming them lets the orchestrator run the same commands after dispatch. Ask Vibe to
+run them only when the human explicitly authorized `--full-access`.
+
+## Honor repo conventions
+
+Restate the load-bearing house rules in the brief. Vibe can inspect the workspace, but the important
+constraints should be directly in front of it.
+
+## One task per brief
+
+Keep each brief bounded. One brief → one Vibe run → one reviewed commit keeps the diff and rollback
+clean. Split mixed implementation, review, documentation, and roadmap requests into separate
+dispatches.
+
+## Premises freeze at dispatch
+
+Vibe starts from the brief's facts and there is no steering channel mid-run. Audit ownership, target
+branch, constraints, and other judgment-bearing premises before dispatch. If one proves wrong while
+the run is live, stop it and inspect the working tree before sending a corrected brief; reconcile any
+partial or premise-contaminated edits rather than discounting them after the fact.
+
+## A worked example
+
+```xml
+<task>
+In the payments service at services/billing/, the refund path double-charges when a refund is retried
+after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency
+key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge
+path, API routes, and data models untouched.
+</task>
+
+<verification_loop>
+The orchestrator will run:
+  pytest tests/billing/ -q
+  ruff check services/billing/
+If shell execution is authorized for this run, run them and fix failures. Otherwise report them as
+not run and confirm only refund.py and its test file changed.
+</verification_loop>
+
+<action_safety>
+Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
+changes in the working tree for review.
+</action_safety>
+
+<structured_output_contract>
+Report: (1) the root cause and fix, (2) files touched, (3) pytest and ruff outcomes with counts or
+that they were not run,
+(4) anything left open or needing a decision.
+</structured_output_contract>
+```
+
+## Argv delivery limits
+
+Vibe's headless mode requires the brief as a command-line argument via `--prompt`. The relay reads a
+file or stdin for convenience, then passes the text with `--prompt=<brief>`. The equals form binds a
+brief that starts with `-` instead of treating it as another flag.
+
+This has two consequences:
+
+- The brief is visible in the host process list (`ps`, `/proc`). Keep secrets out of it on shared
+  machines; reference workspace files or environment variables instead.
+- A brief over 120 KB on POSIX or 12 KB on Windows is rejected before launch because the platforms
+  cap command arguments. Put large context in the workspace and tell Vibe which file to read.
+
+Dispatch with [dispatch-and-poll.md](dispatch-and-poll.md), then review and commit with
+[review-and-land.md](review-and-land.md).

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

@@ -0,0 +1,192 @@
+---
+name: warp-delegate
+description: Delegate coding tasks to the Warp Agent CLI (`oz`) 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 `oz` CLI (Warp Agent CLI) installed and authenticated
+  (`oz login`, or `WARP_API_KEY` for a headless host; Warp AI features need an eligible
+  Warp plan or your own provider key), Node 18+, and git. 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
+---
+# Warp Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `warp` implementer (`Warp Agent CLI`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. Delegate a bounded coding task to a separate **implementer** - the
+Warp Agent CLI - then review what it produced and land it yourself. You write the brief and own the
+judgment; the implementer makes changes in its own conversation; you verify and commit.
+
+The loop needs only a shell command and file access, so any comparable orchestrator can drive it.
+
+## The binary is `oz`, not `warp`
+
+Warp ships two different programs, and only one of them can be delegated to:
+
+- **`oz`** - the Warp Agent CLI. Headless and scriptable; `oz agent run` executes an agent against a
+  local directory. **This is what the relay drives.**
+- **`warp`** - the interactive Warp TUI. It requires a terminal device, has no prompt or print flag
+  (its only options are `--resume`, `--auto-approve`, `--api-key`, and the provider-key commands),
+  and exits with `Device not configured` when stdin is a pipe. It cannot be relayed.
+
+If `oz` is missing but `warp` is installed, you have the TUI, not the CLI.
+
+## When NOT to use this
+
+- The task is small enough to do inline; delegation overhead is not worth it.
+- The `oz` CLI is not installed or authenticated.
+- You need a sandboxed or read-only implementer. `oz agent run` has **no sandbox, no permission
+  mode, and no read-only run** - see [Autonomy and permissions](#autonomy-and-permissions).
+- The work must stay off Warp's servers. `oz agent run` uploads an end-of-run workspace snapshot
+  unless `--no-snapshot` is passed, and conversations live server-side.
+
+## Prerequisites (check once)
+
+1. Install the Warp Agent CLI - see <https://docs.warp.dev/cli/>.
+2. Authenticate: `oz login`, or set `WARP_API_KEY` for CI, a container, or any headless host.
+3. Confirm the account has AI quota. **A working login is not enough** - unlike the other CLIs in
+   this package. `oz whoami` can succeed while every dispatch fails with `In order to use Warp's AI
+   features, subscribe to a Warp plan, or bring your own inference.` Warp records this internally as
+   `QuotaLimit` / "lack of AI quota", so it is a credit condition on the account rather than a
+   CLI-specific entitlement: `oz` runs the same agent harness as the Warp app and draws on the same
+   account, plan, and credits. Check that `oz whoami` names the account holding the plan - if it
+   does not, `oz logout && oz login` fixes it. Otherwise confirm the plan's AI credits are not
+   spent, or store your own provider key -
+   `warp --set-provider-api-key <openai|anthropic|google|grok>`, or `/api-keys` inside the TUI.
+   Bring-your-own-key needs no paid Warp plan.
+4. Confirm `oz --version` succeeds and `oz whoami` prints your user.
+5. Work in, or point `--cd` at, the target git repository.
+
+On macOS the CLI is distributed as a signed Developer ID binary; a first run may be held by
+Gatekeeper until it is approved.
+
+## Choose the model (optional)
+
+Omit `--model` to use Warp's configured default. To pick another, choose an id from `oz model list`
+and pass it verbatim. The relay accepts letters, digits, and `. _ : / -` only, so a value cannot be
+mistaken for another `oz` flag.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Warp sees only the text you send plus what it can inspect in the workspace - no chat history or
+shared context. Include the goal, current state, what to change, what to leave untouched, the
+project's **actual** gates, and a report contract. Tell it not to commit. Keep one task per brief.
+The brief is delivered as the `--prompt` value on argv, so it is visible in the host process list -
+keep secrets out of it and reference workspace files instead. See
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+### 2. Dispatch
+
+Use the bundled relay. It runs `oz agent run --output-format ndjson`, captures the event stream, and
+writes `result.json`. (`<skill-dir>` is the installed folder containing this `SKILL.md`.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# choose a model:                          add --model <id from oz model list>
+# use an agent profile:                    add --profile <id>
+# label the run:                           add --name <label>
+# continue an existing conversation:       add --conversation <id> (delta brief only)
+# base the run on a Warp skill:            add --skill <name|repo:name|org/repo:name>
+# start MCP servers:                       add --mcp <path-or-inline-json>  (repeatable)
+# suppress the workspace snapshot upload:  add --no-snapshot
+# hard time limit (watchdog):              add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
+# see all options:                         node .../relay.mjs --help
+```
+
+The relay pins the workspace with both the child process's cwd and Warp's own `--cwd`. It writes
+artifacts under the system temp dir by default and never commits. See
+[references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The relay blocks until `oz` finishes. Run it with the orchestrator's background-command facility, or
+background it in the shell and poll for `result.json`. A pre-run usage error exits 2 and writes no
+result; a missing `oz` exits 127 and writes `status: "warp_unavailable"`.
+
+Trust process state and the working tree over a progress display. Completion means the process
+exited and `result.json` exists. Warp's report is the `finalMessage` field in `result.json` (also
+printed on stdout between the report markers); the raw event stream is always in `events.jsonl`.
+
+### 4. Review - do not trust the self-report
+
+Treat Warp's final message and gate claims as claims:
+
+- Re-run the project's gates yourself.
+- Read the diff against the brief, starting with `touchedFiles`.
+- Run relevant guard skills if installed.
+- Round-trip migrations and grep for dangling references after removals or renames.
+
+Because there is no read-only mode to fall back on, the diff is the **only** record you get - and it
+records what git can see in the workspace afterward, not everything the run did. Dispatch from a
+clean tree so the two are as close as they can be. See
+[references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The implementer edits the working tree; **the orchestrator commits.** Commit only after the gates
+pass and the diff holds. If rework is needed, send a delta brief with `--conversation <id>` using the
+`conversationId` from `result.json`, then review again.
+
+## Autonomy and permissions
+
+`oz agent run` has **no sandbox, no permission mode, and no read-only mode**. A headless run reads,
+writes, edits, and executes commands with your own user permissions and never prompts. There is
+nothing in the CLI to restrict that surface, so this relay ships no `--read-only` flag - offering one
+would imply an enforcement that does not exist. The controls you actually have are:
+
+1. **Scope by directory.** `--cd` pins the workspace, and the relay passes it to Warp's own `--cwd`.
+   Treat this as *aim*, not a fence: on oz 0.2026.05.27 shell commands did run in the pinned
+   workspace, but the agent's file tool resolved bare relative paths against `$HOME`. Name absolute
+   paths in the brief - see [references/writing-the-brief.md](references/writing-the-brief.md).
+2. **Review the diff.** `touchedFiles` 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 (see item 1), and it
+   carries anything that was already dirty before dispatch. Dispatch from a clean tree so those are
+   the same set, and treat the diff as the best available record, not a complete one.
+3. **Snapshot egress.** `--no-snapshot` forwards Warp's flag so the end-of-run workspace snapshot is
+   not uploaded. Without it, the upload is Warp's default.
+
+`--auto-approve` belongs to the interactive `warp` TUI and has no bearing on `oz agent run`.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have ("run this queue", "proceed"),
+committing verified, gate-passing work is the agreed contract. Two limits remain: **surface, don't
+absorb** (report Warp's design decisions, defensible-but-unasked turns, and non-blocking nitpicks)
+and **stop for scope changes** (if correct completion needs going beyond the brief, ask instead of
+expanding the mandate). See [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) - structure, report contract,
+  real gates, argv delivery, and delta briefs.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) - flags, artifacts,
+  `result.json`, polling, and failure recovery.
+- [references/review-and-land.md](references/review-and-land.md) - review checklist, commit
+  boundary, and rework through Warp conversations.
+- [references/multi-task-queues.md](references/multi-task-queues.md) - sequential queues,
+  constraint carry-forward, progress tracking, and the final coherence pass.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `warp` 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/warp-delegate/references/dispatch-and-poll.md

@@ -0,0 +1,163 @@
+# Dispatch and poll
+
+The relay is the only Warp-specific machinery in this skill. It launches `oz agent run`, captures
+the event stream, and writes one result file the orchestrator can read.
+
+## What the relay runs
+
+```text
+oz agent run --output-format ndjson --cwd <cd> [--model …] [--profile …] [--name …]
+             [--conversation …] [--skill …] [--mcp … …] [--no-snapshot] --prompt <brief>
+```
+
+`--output-format ndjson` makes Warp emit one JSON object per line, so a long run reports progress
+instead of buffering to the end. The workspace is pinned twice: the child process's cwd and Warp's
+own `--cwd`.
+
+## Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | Path to the brief. Omit to read it from stdin. |
+| `--cd <dir>` | Working root (default: current directory). Also passed as Warp's `--cwd`. |
+| `--lane <name>` | Resolve dials from a `delegate-setup` fleet lane. Explicit flags win. |
+| `--model <id>` | Warp model id from `oz model list`. Letters, digits, and `. _ : / -` only. |
+| `--profile <id>` | Warp agent profile. |
+| `--name <label>` | Labels the run in Warp's own run list. |
+| `--conversation <id>` | Continue an existing Warp conversation. Send a delta brief only. |
+| `--skill <spec>` | Warp skill as the base prompt: `name`, `repo:name`, or `org/repo:name`. |
+| `--mcp <spec>` | MCP config path or inline JSON. Repeatable. |
+| `--no-snapshot` | Forward Warp's `--no-snapshot` so no end-of-run workspace snapshot is uploaded. |
+| `--timeout <dur>` | Relay watchdog, h/m/s (default `30m`). Warp has no timeout flag of its own. |
+| `--out-dir <dir>` | Artifact directory (default: a fresh dir under the system temp dir). |
+
+Values for `--model`, `--profile`, and `--conversation` are token-validated. `--skill`, `--mcp`, and
+`--name` accept freer text but must not start with `-`, which `oz` would read as another flag.
+
+## Artifacts
+
+Written to `--out-dir`:
+
+- `brief.txt` — exactly what was sent.
+- `events.jsonl` — the raw ndjson stream, byte for byte. The fallback whenever a parsed field looks
+  wrong.
+- `final.txt` — the assembled report, when one was captured.
+- `stderr.txt` — everything Warp wrote to stderr.
+- `result.json` — the structured result, written atomically via a temp file and rename, so a polling
+  reader never sees a half-written file.
+
+## `result.json`
+
+Schema id `delegate-relay.result.v1`. Synthetic example:
+
+```json
+{
+  "schema": "delegate-relay.result.v1",
+  "tool": "oz",
+  "status": "completed",
+  "exitCode": 0,
+  "signal": null,
+  "ozVersion": "Oz v0.0000.00.00.00.00.stable_01",
+  "workdir": "/path/to/repo",
+  "model": null,
+  "profile": null,
+  "snapshotDisabled": false,
+  "resumed": false,
+  "runId": "00000000-0000-0000-0000-000000000000",
+  "runUrl": "https://oz.warp.dev/runs/00000000-0000-0000-0000-000000000000",
+  "conversationId": null,
+  "finalMessage": "Changed src/export/csv.ts …",
+  "touchedFiles": [" M src/export/csv.ts", "?? src/export/csv.test.ts"],
+  "startedAt": "2026-01-01T00:00:00.000Z",
+  "finishedAt": "2026-01-01T00:04:12.000Z"
+}
+```
+
+Field notes:
+
+- **`status`** — `completed`, `failed`, `timeout`, `aborted`, or `warp_unavailable`.
+- **`touchedFiles`** — `git status --porcelain` lines. `null` when git cannot report (not a
+  repository, git missing); `[]` when the tree is genuinely clean. `[]` and `null` mean different
+  things — do not collapse them.
+- **`runId` / `runUrl`** — from Warp's `run_started` system event. `runUrl` opens the run in Warp.
+- **`conversationId`** — the handle to pass back as `--conversation` for rework. Present only when
+  Warp emitted it on the stream.
+- **`finalMessage`** — Warp's own report. Assembled from the text-bearing events in the stream; see
+  the caveat below.
+- **`stderrTail`** — last 20 stderr lines, included on every non-clean outcome.
+
+### What `finalMessage` actually contains
+
+Confirmed against a live edit run on oz 0.2026.05.27. The stream carries:
+
+| Event | Meaning |
+| --- | --- |
+| `{"type":"system","event_type":"run_started","run_id":…,"run_url":…}` | Run registered. |
+| `{"type":"system","event_type":"conversation_started","conversation_id":…}` | The `--conversation` handle. Re-emitted on a resumed run carrying the *same* id, so `conversationId` stays stable across a rework chain. |
+| `{"type":"agent","text":…}` | Agent output. **This is what `finalMessage` is built from.** |
+| `{"type":"agent_reasoning","text":…}` | Private reasoning. Same shape, deliberately **excluded**. |
+| `{"type":"tool_call"\|"tool_result"\|"tool_error",…}` | Tool traffic. No `text` field. |
+
+Two consequences:
+
+- **`finalMessage` is the whole narration, not just the closing report.** Warp emits no distinct
+  final-message event, so every `agent` chunk is concatenated — including running commentary like
+  "Now let me run both gates." This is why the brief must specify a report contract: `FILES:` /
+  `GATES:` / `NOTES:` at the end gives you a stable anchor to read instead of parsing prose.
+- **`agent_reasoning` must stay excluded.** It carries a `text` field of exactly the same shape, so
+  matching on `text` alone splices the model's reasoning into the report.
+
+Past those two rules the extraction stays tolerant — it also accepts `agent_output`, `content`, and
+a nested `message.content` — so a renamed output event still reports rather than yielding an empty
+`finalMessage`. If one ever does come back empty on a successful run, `events.jsonl` holds the raw
+stream and `collectText` is the one place to correct.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Warp exited 0 and reported no stream error. |
+| `1` | Generic failure, or a stream-reported agent error even when `oz` exited 0. |
+| `2` | Usage error — bad flag, bad `--timeout`, missing or empty brief. **No result file is written.** |
+| `124` | The bounded `oz --version` preflight timed out; Warp was never dispatched. |
+| `127` | `oz` is not on PATH. A result file **is** written, with `status: "warp_unavailable"`. |
+| `128 + n` | The child died on signal *n*; `signal` records which. |
+
+## Polling
+
+The relay blocks until the run ends. Background it and poll for `result.json`:
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo \
+  --out-dir /tmp/warp-run-1 &
+until [ -f /tmp/warp-run-1/result.json ]; do sleep 5; done
+```
+
+Completion means the process exited **and** `result.json` exists. Do not infer completion from
+stdout going quiet — a long tool call looks identical to a finished run.
+
+## Timeouts and aborts
+
+`oz` has no timeout flag, so the watchdog is the relay's. When `--timeout` expires the relay kills
+the whole process group (SIGTERM, then SIGKILL after 10s) and writes `status: "timeout"`.
+
+If the relay itself is killed, it still writes `status: "aborted"`, forwards the kill to `oz`, and
+re-snapshots `touchedFiles` after a 2-second grace window so files flushed during shutdown are
+recorded. On Windows the process tree is felled with `taskkill /t /f`; Windows delivers no catchable
+SIGTERM, so the aborted path cannot be driven there.
+
+**A timed-out or aborted run leaves a partially edited tree.** Inspect `git status` and `git diff`
+before re-dispatching. If the state is incoherent, discard it against the recorded baseline rather
+than stashing — a bare `git stash` leaves behind every file the run created. See
+[review-and-land.md](review-and-land.md#rework-through-a-conversation).
+
+## Failure recovery
+
+| Symptom | What it means | Do |
+| --- | --- | --- |
+| `warp_unavailable`, exit 127 | `oz` is not on PATH | Install the Warp Agent CLI; check `oz --version`. |
+| stderr `subscribe to a Warp plan, or bring your own inference` | Authenticated, but the account has no AI quota. Warp logs it as `QuotaLimit` / "lack of AI quota". `oz` shares the Warp app's account, plan, and credits, so this is a credit condition, not a CLI-only gate | Check `oz whoami` names the account holding the plan - if not, `oz logout && oz login`. Otherwise confirm its AI credits are not spent, or store your own provider key: `warp --set-provider-api-key <openai\|anthropic\|google\|grok>` (or `/api-keys` in the TUI). Bring-your-own-key needs no paid plan. Warp's log is at `~/Library/Logs/oz/warp.log` on macOS. |
+| `Device not configured` | The `warp` TUI was launched, not `oz` | Use `oz`; the TUI cannot be relayed. |
+| exit 2, no result file | Usage error | Read the relay's stderr line; fix the flag. |
+| `status: "timeout"` | The watchdog fired | Raise `--timeout`, or split the brief. |
+| Empty `finalMessage`, exit 0 | Text extraction missed the event shape | Read `events.jsonl`; see the caveat above. |