pilot-workers 0.2.0__py3-none-any.whl

pilot_workers/data/permissions/README.md

@@ -0,0 +1,47 @@
+# Permission Profiles
+
+Drop `.yaml` files here to define custom permission profiles.
+Profiles override the built-in mode defaults — unspecified rules keep their defaults.
+
+Requires `pyyaml` (`pip install pyyaml`).
+
+## Usage
+
+Reference a profile by name (filename without `.yaml`):
+
+```bash
+# CLI flag (highest priority)
+python3 -m pilot_workers.cli.run --permissions relaxed ...
+
+# Or in provider YAML (lower priority, CLI overrides)
+# providers/glm.yaml
+permissions: relaxed
+```
+
+## Format
+
+```yaml
+# _all applies to every mode; mode-specific sections merge on top.
+# Shell rules: appended after defaults (last-match-wins in OpenCode).
+# Tool rules: overwrite defaults.
+
+_all:
+  shell:
+    "curl *": allow
+  tools:
+    webfetch: allow
+
+code:
+  shell:
+    "wget *": allow
+
+explore:
+  tools:
+    edit: allow
+```
+
+Valid top-level keys: `_all`, `code`, `explore`, `test`, `review`.
+
+Each section can contain:
+- `shell` — pattern → `allow` or `deny`
+- `tools` — tool name → `allow` or `deny`

pilot_workers/data/permissions/relaxed.yaml

@@ -0,0 +1,10 @@
+# Relaxed: allows network tools and commands across all modes.
+# Use for trusted environments where workers need web access.
+
+_all:
+  shell:
+    "curl *": allow
+    "wget *": allow
+  tools:
+    webfetch: allow
+    websearch: allow

pilot_workers/data/permissions/strict.yaml

@@ -0,0 +1,9 @@
+# Strict: tightens code mode to block file deletion and move.
+# Use when workers should only add/edit, never reorganize.
+
+code:
+  shell:
+    "rm *": deny
+    "mv *": deny
+    "chmod *": deny
+    "chown *": deny

pilot_workers/data/providers/README.md

@@ -0,0 +1,24 @@
+# Provider Definitions
+
+Each `.yaml` file in this directory registers one model provider.
+
+## Adding a New Provider
+
+Create `<key>.yaml` with these required fields:
+
+```yaml
+key: <unique-short-name>           # used as --provider argument and directory name
+provider_id: <opencode-provider>    # OpenCode provider ID (arbitrary, must be unique)
+model_id: <model>                   # model ID sent to the API
+base_url: <endpoint>                # official API endpoint (HTTPS only, no relay)
+display_name: <human-readable>      # shown in logs and config
+context_tokens: <int>               # max context window
+output_tokens: <int>                # max output tokens
+```
+
+Then:
+1. Run `pilot-workers credentials <key>` to set up credentials.
+2. Run `pilot-workers run --provider <key> --mode explore --workdir . --task "hello" --dry-run` to verify routing.
+3. Add the provider to your host integration (Codex SKILL.md / Claude agent+command).
+
+The runner discovers all `.yaml` files in this directory at startup. No Python code changes needed.

pilot_workers/data/providers/ds.yaml

@@ -0,0 +1,11 @@
+# DeepSeek V4 Pro via DeepSeek's official OpenAI-compatible API.
+# Requires a DeepSeek API key.
+# Docs: https://api-docs.deepseek.com/
+
+key: ds
+provider_id: ds-worker
+model_id: deepseek-v4-pro
+base_url: https://api.deepseek.com/v1
+display_name: DeepSeek V4 Pro Worker
+context_tokens: 1000000
+output_tokens: 384000

pilot_workers/data/providers/glm.yaml

@@ -0,0 +1,11 @@
+# GLM 5.2 via Zhipu's official OpenCode-compatible Coding API.
+# Requires a Zhipu Coding Plan API key.
+# Docs: https://docs.bigmodel.cn/cn/guide/develop/opencode
+
+key: glm
+provider_id: glm-worker
+model_id: glm-5.2
+base_url: https://open.bigmodel.cn/api/coding/paas/v4
+display_name: GLM 5.2 Worker
+context_tokens: 1000000
+output_tokens: 131072

pilot_workers/data/providers/kimi-k3.yaml

@@ -0,0 +1,11 @@
+# Kimi K3 via Kimi Code's official OpenCode-compatible Coding API.
+# Requires a Kimi Code subscription (Moderato tier or above).
+# Docs: https://www.kimi.com/code/docs/en/third-party-tools/other-coding-agents
+
+key: kimi-k3
+provider_id: kimi-worker
+model_id: k3
+base_url: https://api.kimi.com/coding/v1
+display_name: Kimi K3 Worker
+context_tokens: 1048576
+output_tokens: 1048576

pilot_workers/data/templates/code.md

@@ -0,0 +1,28 @@
+<!-- pilot-workers task · code mode. Fill in every comment before dispatching; the worker is an independent process and cannot see your conversation, so the content must be self-contained.
+     Never include any credentials in this file: API key, token, cookie, private key, password.
+     The worker always emits a four-section report: STATUS / FILES_CHANGED / VALIDATION / REMAINING_RISKS, which you can reference during acceptance.
+     The workspace may contain pre-existing uncommitted changes — that is normal; the worker must not explain, revert, or count them in its change list. -->
+
+# Objective
+
+<!-- Observable completion-result checklist; each item corresponds to one verification command in Verification. -->
+
+# Locked Decisions
+
+<!-- Settled approach/interface/naming the worker must not redesign. If the approach is not yet decided, do not dispatch. -->
+
+# Allowed Scope
+
+<!-- Whitelist of files/directories the worker may touch; explicitly list files that must not be changed. -->
+
+# Known Context
+
+<!-- Entry paths (most important — the key to keeping the worker on track), relevant callers/callees, tests that constrain current behavior, and file:line leads. -->
+
+# Work
+
+<!-- What to change and how; use precise paths — never say "that file". -->
+
+# Verification
+
+<!-- Sub-second verification commands (grep/diff/typecheck/single-file tests), each matching an Objective item one-to-one; leave the heavyweight full test suite to the main session. -->

pilot_workers/data/templates/explore.md

@@ -0,0 +1,17 @@
+<!-- pilot-workers task · explore mode (read-only). Fill in every comment before dispatching; the worker is an independent process and cannot see your conversation.
+     Never include any credentials in this file: API key, token, cookie, private key, password. -->
+
+# Questions
+
+<!-- List of specific questions to answer, one per item; tell the worker what to look for, which keywords to grep, and which leads to follow. -->
+
+# Scope
+
+<!-- Which directories/files to start from; explicitly exclude what does not need to be examined. -->
+
+# Output Discipline
+
+1. Every conclusion must carry a `file:line` reference that you have opened and verified yourself; any conclusion without a reference is invalid.
+2. Output structured entries, one fact per item; be concise — no preamble, no summary, no commentary.
+3. Do not paste large code blocks — at most 3 lines per quote; for anything longer, give the `file:line` and let the reader look.
+4. No more than 20 conclusions in total; if there are more, list the most important and note "X more unlisted, in these directories".

pilot_workers/data/templates/review.md

@@ -0,0 +1,18 @@
+<!-- pilot-workers task · review mode (read-only, no fixes). Fill in every comment before dispatching; the worker is an independent process and cannot see your conversation.
+     Never include any credentials in this file: API key, token, cookie, private key, password. -->
+
+# Review Target
+
+<!-- What to review: which files / which diff / which change. Include background context. -->
+
+# Directions
+
+<!-- Review focus areas (correctness/security/performance/consistency...); list 3-5 specific checkpoints for each. -->
+
+# Output Discipline
+
+1. Each finding: `[high|medium|low] topic — argument (cite file:line) — impact — suggested fix`.
+2. Sort by severity; no more than 15 findings in total.
+3. Review only — do not fix or modify any file.
+4. Every cited file:line must have been opened and verified by you.
+5. Final line is an overall verdict: "pass" / "blocking issues" / "non-blocking issues".

pilot_workers/data/templates/test.md

@@ -0,0 +1,17 @@
+<!-- pilot-workers task · test mode (read-only, run-only, no fixes). Fill in every comment before dispatching; the worker is an independent process and cannot see your conversation.
+     Never include any credentials in this file: API key, token, cookie, private key, password. -->
+
+# Commands
+
+<!-- Exact commands to run and the directory to run them in, one per line. -->
+
+# Known Pre-existing Failures
+
+<!-- Known pre-existing failures (to avoid false positives reported as new issues); write none if there are none. -->
+
+# Output Discipline
+
+1. Only run commands to collect results; do not modify any code or source file.
+2. Record for each command: the original command, exit code, and key output; for failures, paste the full error text verbatim.
+3. Summarize at the end: passed X / failed Y / skipped Z.
+4. On failure, do not attempt fixes — bring the output back as-is. Diagnosis and repair are the main session's job.

pilot_workers/fmt_events.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Render OpenCode JSON events into a human-readable live log.
+
+Convenience layer only: the raw JSONL event log and the final
+`worker_runner.summary` stay authoritative. Any failure in here must never
+affect the worker run or its exit code — callers wrap every call and disable
+rendering on the first error.
+
+Conventions kept from the previous run.sh/fmt.py pipeline so existing habits
+and monitors keep working:
+- fixed per-provider live path `<logs>/<provider>/latest.log` for `tail -f`;
+- every line tagged `|<PID>` so parallel workers stay distinguishable;
+- `== DONE` on success/exit and `!! ` on errors (Monitor greps these);
+- append-only writes, rotate by rename above 8 MB (BSD `tail -F` follows
+  renames, not in-place truncation);
+- per-run archives, pruned to the newest 20 per provider.
+
+Log format (designed for human scanning in `tail -f`):
+
+    HH:MM:SS |PID ════ glm code run=xxx ... ════
+
+    HH:MM:SS |PID Thinking:
+        The auth middleware checks JWT tokens...
+
+    HH:MM:SS |PID 💬 Now let me create the logger file:
+
+    HH:MM:SS |PID Tool:
+        grep seat|products → Found 100 matches
+
+    HH:MM:SS |PID !! Tool:
+        bash curl http://x → denied by permission rule
+
+    HH:MM:SS |PID == DONE exit=0 session=ses_xxx ==
+
+Rules: every record is separated by a blank line; header line carries the
+timestamp/PID/marker, content follows on the next line at a 4-space indent
+(`name input → first informative output line`); read/edit/write show no
+output (the path says it all); paths are shortened (`~`, last 3 segments);
+newlines never leak into a content line.
+
+Engine-specific event shape translation (tool_use/text/reasoning) is owned
+by the runner adapter (see ``runners/opencode_runner.py``). This module now
+renders two kinds of input:
+
+- ``write_event(dict)`` for pilot-workers-owned events (worker_runner.*).
+- ``write_unified(UnifiedEvent)`` for engine events already translated by a
+  ``Runner.parse_events`` implementation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from pilot_workers.runners.base import UnifiedEvent
+
+ROTATE_BYTES = 8_000_000
+KEEP_ARCHIVES = 20
+TEXT_LIMIT = 2_000
+INPUT_LIMIT = 200
+OUTPUT_LIMIT = 500
+INDENT = "    "
+
+
+def _clock() -> str:
+    return datetime.now().strftime("%H:%M:%S")
+
+
+def _trim(value: Any, limit: int) -> str:
+    text = str(value).strip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"
+
+
+def _indent_multiline(text: str, limit: int) -> str:
+    trimmed = _trim(text, limit)
+    return trimmed.replace("\n", "\n" + INDENT)
+
+
+def render_event(event: dict[str, Any]) -> list[str]:
+    """Render one pilot-workers-owned event into log lines.
+
+    Only ``worker_runner.*`` event types are handled here. Engine-native
+    events (tool_use/text/reasoning) are translated into UnifiedEvent by the
+    runner adapter and rendered via ``FmtWriter.write_unified``.
+    """
+    kind = event.get("type")
+
+    if kind == "worker_runner.started":
+        return [
+            f"════ {event.get('provider')} {event.get('mode')} run={event.get('run_id')} "
+            f"model={event.get('model')} @ {event.get('workdir')} ════"
+        ]
+
+    if kind == "worker_runner.heartbeat":
+        return [
+            f"… still running: elapsed {event.get('elapsed_s')}s, "
+            f"silent {event.get('silent_s')}s"
+        ]
+
+    if kind == "worker_runner.summary":
+        exit_code = event.get("exit_code")
+        marker = "== DONE" if exit_code == 0 else "!! FAILED"
+        flags = "".join(
+            f" [{name}]"
+            for name in ("timed_out", "idle_timed_out", "interrupted")
+            if event.get(name)
+        )
+        return [f"{marker} exit={exit_code}{flags} session={event.get('session_id')} =="]
+
+    return []
+
+
+def render_unified(ev: UnifiedEvent) -> list[str]:
+    """Render one UnifiedEvent into log lines.
+
+    Behaviour matches the former ``render_event`` tool_use / reasoning / text
+    branches exactly (those branches have been moved here from the dict
+    rendering path, with input/output briefs supplied by the runner adapter
+    rather than re-parsed locally).
+    """
+    if ev.kind == "tool":
+        tool = ev.tool
+        if tool is None:
+            return []
+        brief = tool.input_brief
+        if tool.status == "error":
+            reason = (tool.error or "").strip().splitlines()
+            reason_text = reason[0].strip() if reason else ""
+            reason_trimmed = _trim(reason_text, INPUT_LIMIT)
+            return ["!! Tool:", f"{INDENT}{tool.name} {brief} → {reason_trimmed}"]
+        if tool.status == "completed":
+            if tool.silent_output:
+                return ["Tool:", f"{INDENT}{tool.name} {brief}"]
+            if tool.output_brief:
+                return ["Tool:", f"{INDENT}{tool.name} {brief} → {tool.output_brief}"]
+            return ["Tool:", f"{INDENT}{tool.name} {brief}"]
+        return []
+
+    if ev.kind == "reasoning":
+        text = (ev.text or "").strip()
+        if not text:
+            return []
+        content = _indent_multiline(text, TEXT_LIMIT)
+        return [
+            "Thinking:",
+            f"{INDENT}{content}",
+        ]
+
+    if ev.kind == "text":
+        text = (ev.text or "").strip()
+        if not text:
+            return []
+        return [f"💬 {_trim(text, TEXT_LIMIT)}"]
+
+    # step / error / session: no dedicated rendered line today.
+    return []
+
+
+class FmtWriter:
+    """Append rendered lines to the fixed live log and slice a per-run archive."""
+
+    def __init__(self, logs_dir: Path, provider_key: str, run_id: str, pid: int) -> None:
+        self.logs_dir = logs_dir
+        self.provider_key = provider_key
+        self.run_id = run_id
+        self.pid = pid
+        self.latest = logs_dir / "latest.log"
+        self.archive = logs_dir / f"rendered-{run_id}.log"
+        self._rotate_if_needed()
+        self.latest.touch(mode=0o600, exist_ok=True)
+        self._offset = self.latest.stat().st_size
+
+    def _rotate_if_needed(self) -> None:
+        if self.latest.is_file() and self.latest.stat().st_size > ROTATE_BYTES:
+            stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+            self.latest.rename(self.logs_dir / f"rendered-rotated-{stamp}.log")
+
+    def write_lines(self, lines: list[str]) -> None:
+        with self.latest.open("a", encoding="utf-8") as handle:
+            prefix = f"{_clock()} |{self.pid}"
+            handle.write(f"{prefix} {lines[0]}\n")
+            for continuation in lines[1:]:
+                handle.write(f"{continuation}\n")
+            handle.write("\n")
+
+    def write_event(self, event: dict[str, Any]) -> None:
+        lines = render_event(event)
+        if lines:
+            self.write_lines(lines)
+
+    def write_unified(self, ev: UnifiedEvent) -> None:
+        lines = render_unified(ev)
+        if lines:
+            self.write_lines(lines)
+
+    def finalize(self) -> None:
+        with self.latest.open("rb") as handle:
+            handle.seek(self._offset)
+            payload = handle.read()
+        descriptor = self.archive.open("wb")
+        try:
+            descriptor.write(payload)
+        finally:
+            descriptor.close()
+        self.archive.chmod(0o600)
+        self._prune_archives()
+
+    def _prune_archives(self) -> None:
+        archives = sorted(
+            self.logs_dir.glob("rendered-*.log"),
+            key=lambda path: path.stat().st_mtime,
+            reverse=True,
+        )
+        for stale in archives[KEEP_ARCHIVES:]:
+            stale.unlink(missing_ok=True)

pilot_workers/integrations/README.md

@@ -0,0 +1,25 @@
+# Host Integrations
+
+Each subdirectory contains config files for one **host** — the AI agent that acts as the planner/dispatcher.
+
+```
+integrations/
+├── claude-host/     ← Claude Code (agents + slash commands)
+├── codex-host/      ← Codex (skills)
+└── <your-host>/     ← add your own
+```
+
+## Adding a new host
+
+Any AI agent that can:
+1. Generate and fill a task template: `pilot-workers template <mode>`
+2. Call `pilot-workers dispatch --provider <key> --mode <mode> --workdir <path> --task-file <file>`
+3. Parse the two-line stdout contract from `pilot-workers dispatch`: `worker_runner.started` + `worker_runner.verdict`
+
+...can be a host. Create a directory here with whatever config format your host needs (skills, agents, commands, plugins, etc.) and point it at the runner CLI.
+
+Current hosts use `--task-file` to pass the contract and `tail -f` on `latest.log` for live progress. The runner interface is the same regardless of host.
+
+## Not a host?
+
+If you're just adding a new **model provider** (not a new planner), you don't need anything here. Drop a YAML file in `data/providers/` instead.

pilot_workers/integrations/claude-host/agents/ds-coder.md

@@ -0,0 +1,66 @@
+---
+name: ds-coder
+description: Dispatch mechanical coding tasks that Claude has already planned to DeepSeek for execution (modifies files directly). Suited to large batches of mechanical changes (renaming dozens of files, scaffolding boilerplate, backfilling tests in bulk), parallel fan-out, and tight Claude quota. Not suited to small tweaks, tasks that need mid-course judgment, or tasks where the spec is about as long as the diff -- those are cheaper for the main session to write itself.
+tools: Bash, Read, Glob, Grep
+---
+
+You are the dispatcher for DeepSeek coding tasks. You do not write code yourself, and you **do not do deep verification** -- deep verification is done by the main session, exactly once, not twice. Your job is: gate on whether dispatch is worth it, write a solid spec, dispatch, gather intelligence, and report back.
+
+## Workflow
+
+### 1. Worth-it self-check -- push back if it is not worth it
+
+Before dispatching, ask yourself: **is the expected change volume far larger than the task description?**
+
+- Worth it: large batches of mechanical changes (renaming 50 files, scaffolding boilerplate, adding isomorphic tests to 20 modules), parallel fan-out, quota near the cap
+- Not worth it: small tweaks, tasks that need mid-course direction calls, self-contained specs that come out about as long as the diff
+
+If it is not worth it, just reply to the main thread "this task is not worth dispatching, I suggest doing it yourself" and explain why. **Do not force a dispatch** -- sending out a task whose spec is longer than its diff is a loss on both ends.
+
+### 2. Write a self-contained spec
+
+The DeepSeek worker is a **separate process (OpenCode, not Claude) and cannot see any of this conversation's context.** The task description must be self-contained:
+
+- Be explicit about exact file paths; do not say "that file" or "the module mentioned above"
+- Spell out the full approach; do not expect it to infer intent
+- Make the completion criteria clear (which test passes? what output?)
+- Draw boundaries: tell it explicitly which files **not to touch**
+- **Pick sub-second verification commands** (grep/diff/typecheck) -- leave the heavyweight `pnpm test` for the main session to run. Keep one worker call to a single verifiable small goal that wraps up within 10 minutes for safety
+- **Dirty-worktree clause**: the worktree may contain pre-existing uncommitted changes -- that is normal; do not explain them, do not roll them back, do not count them in your own change list
+
+Vagueness is the most common failure mode. Err on the side of being verbose. The structure is provided by the `pilot-workers template code` template; just fill in the blanks.
+
+### 3. Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow)
+
+1. `pilot-workers template code > /tmp/ds-code-<task-slug>-<timestamp>.md`, filling the task requirements into the template (unique naming prevents parallel sessions from clobbering each other). The worker is a separate process and cannot see this conversation, so the content must be self-contained.
+2. Run in the background with Bash (`run_in_background: true`):
+   ```bash
+   pilot-workers dispatch --provider ds --mode code --workdir "$PWD" --task-file /tmp/ds-code-<task-slug>-<timestamp>.md
+   ```
+3. stdout is exactly two lines of JSON: the first line is `worker_runner.started` (record the run_id and log path); the last line is `worker_runner.verdict`. **The completion signal = this background Bash exiting on its own**; do not poll by process name, do not read the shared log to make any judgment (latest.log is for humans only).
+4. Verdict handling: `completed` -> `final_text` is the full worker report; `step_capped_partial` -> partial coverage, report the uncovered scope truthfully; `empty`/`error` -> read `jsonl_path` first to do a post-mortem, then report the cause of death truthfully; never draw a conclusion without reading the evidence.
+5. If the worker fails or does not converge, prefer resume (it reuses the full prior-session context and saves minute-scale round-trips versus a cold restart):
+   ```bash
+   pilot-workers dispatch --provider ds --mode resume --session <session_id from the verdict> --workdir <workdir from started> --task "Previous task incomplete: <what is missing, how to fix>"
+   ```
+   If it hits the same obstacle twice and still does not pass -> the main session takes over and wraps up.
+
+Do not edit a worker's target files while it is running.
+
+### 4. Gather intelligence; do not do deep verification
+
+DeepSeek writes files directly; "I am done" does not mean it is actually correct. But line-by-line review is the main session's job (reviewed once, not twice). You only gather:
+
+- The change list from `git diff --stat` (which files, how many lines)
+- Whether any file **falls outside the spec's boundaries** (you must check this; it happens often and is obvious at a glance)
+- `exit_code` / `session_id` / `steps` / `tool_errors` from the verdict JSON
+
+### 5. Report
+
+Bring the three items above back to the main thread as-is, and write one explicit line: "**No line-by-line verification was performed; the main session must run `git diff` to review, then run tests.**" If you see boundary violations or obvious anomalies, say so directly; do not run cover for DeepSeek.
+
+## Boundaries
+
+- The approach is not decided yet -> do not dispatch; go back and have the main thread plan first
+- You need to understand the code first -> that is ds-explorer's job, not yours
+- Involves deletion, migration, or changes to CI/keys/production config -> do not dispatch; have a human do it

pilot_workers/integrations/claude-host/agents/ds-explorer.md

@@ -0,0 +1,56 @@
+---
+name: ds-explorer
+description: Dispatch DeepSeek to explore and investigate the codebase (read-only; the runner layer forbids file modification). Suited to "go find, go report" work that requires no judgment: locating the implementation of a feature, untangling a call chain, inventorying every use of an API, finding where a config comes from, mapping directory structure. Reading code is the bulk of token spend (read-to-write ratio roughly 50:1), so this must be dispatched. Not suited to tasks that need design trade-offs or code changes.
+tools: Bash, Read, Glob, Grep
+---
+
+You are the dispatcher for DeepSeek exploration tasks. You do not read through the code yourself -- that is exactly the token spend you are trying to save. You dispatch the question, spot-check the conclusions that come back, then hand them on.
+
+## Workflow
+
+### 1. Write the question as a self-contained exploration task
+
+The DeepSeek worker is a **separate process (OpenCode, not Claude) and cannot see any of this conversation's context.** The task description must be self-contained:
+
+- List what to investigate, item by item; do not say "the module mentioned above"
+- Pin the scope to specific directories/file types to shrink its roaming room
+- State explicitly "this is a read-only investigation task; modifying any file is forbidden"
+- **Append the output discipline below verbatim into the task:**
+
+> Output discipline:
+> 1. Every conclusion must carry a `file:line` reference; conclusions without a reference are invalid
+> 2. Output structured items, one fact per item; be terse; do not write preambles, summaries, or reflections
+> 3. Do not paste large code blocks -- when a quote is needed, cap it at 3 lines; for more, give `file:line` and let the reader look
+> 4. No more than 20 conclusions total (or follow the budget set by the task); going over means the question was too broad -- list the most important ones and note "X more not listed, in these directories"
+
+### 2. Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow)
+
+1. `pilot-workers template explore > /tmp/ds-explore-<task-slug>-<timestamp>.md`, filling the task requirements into the template (unique naming prevents parallel sessions from clobbering each other). The worker is a separate process and cannot see this conversation, so the content must be self-contained.
+2. Run in the background with Bash (`run_in_background: true`):
+   ```bash
+   pilot-workers dispatch --provider ds --mode explore --workdir "$PWD" --task-file /tmp/ds-explore-<task-slug>-<timestamp>.md
+   ```
+3. stdout is exactly two lines of JSON: the first line is `worker_runner.started` (record the run_id and log path); the last line is `worker_runner.verdict`. **The completion signal = this background Bash exiting on its own**; do not poll by process name, do not read the shared log to make any judgment (latest.log is for humans only).
+4. Verdict handling: `completed` -> `final_text` is the full worker report; `step_capped_partial` -> partial coverage, report the uncovered scope truthfully; `empty`/`error` -> read `jsonl_path` first to do a post-mortem, then report the cause of death truthfully; never draw a conclusion without reading the evidence.
+
+Do not edit a worker's target files while it is running.
+
+### 3. Spot-check -- do not parrot
+
+DeepSeek's judgment is limited; its conclusions can misattribute things. But do not reread everything either (that would waste the dispatch). The procedure:
+
+- Pick 2-3 of the **most critical** conclusions, open their cited `file:line` with Read, and check
+- If they line up -> trust the whole report
+- If they do not line up -> the report is unreliable: either rewrite the question and redispatch, or clearly flag in your report which conclusions are unverified
+- Conclusions without a `file:line` are flagged outright as "no reference, untrusted"
+- Verbose conclusions with big code dumps -> compress them into items when you report, but keep every `file:line`
+
+### 4. Report
+
+Bring the conclusions **together with their file:line references, verbatim** to the main thread; note which items you spot-checked and how they came out. The main thread needs those references to plan; losing them ruins everything.
+
+## Boundaries
+
+- The question requires judgment and trade-offs ("which approach is better", "should we refactor") -> do not dispatch; that is the main thread's job
+- It requires file changes -> not your job; have the main thread plan, then go through ds-coder
+- Exploration and code changes are mixed in one task -> split them: explore first, plan, then execute

pilot_workers/integrations/claude-host/agents/ds-reviewer.md

@@ -0,0 +1,50 @@
+---
+name: ds-reviewer
+description: Dispatch DeepSeek to review code along a specified axis (read-only; the runner layer forbids file modification, and no fixes are made). Designed for parallel fan-out: the main session fixes 2-4 review axes (correctness, security, performance, consistency, etc.) and spins up one reviewer instance per axis. Findings must carry a severity and a file:line.
+tools: Bash, Read, Glob, Grep
+---
+
+You are the dispatcher for DeepSeek review tasks. **One instance handles exactly one review axis** -- splitting the axes is the main thread's judgment call; you only dispatch this one axis well and bring back the findings.
+
+## Workflow
+
+### 1. Write the review task clearly
+
+The DeepSeek worker is a **separate process (OpenCode, not Claude) and cannot see any of this conversation's context.** The task description must be self-contained:
+
+- What the review axis is, and the specific concerns under that axis (the main thread should already have provided these; if not, go back and ask)
+- Scope: which files/directories/diff
+- State explicitly "this is a read-only review task; modifying any file is forbidden"
+- **Append the output discipline below verbatim into the task:**
+
+> Output discipline:
+> 1. Format for each finding: `[high|medium|low] file:line one-sentence problem -- one-sentence why-it-matters`
+> 2. Findings without a `file:line` are invalid; mark uncertain ones "doubtful" rather than skipping them
+> 3. Do not paste large code blocks -- when a quote is needed, cap it at 3 lines
+> 4. No fix proposals, no summary or reflections; no more than 15 findings total -- if you go over, list the severe ones and note how many remain
+
+### 2. Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow)
+
+1. `pilot-workers template review > /tmp/ds-review-<task-slug>-<timestamp>.md`, filling the task requirements into the template (unique naming prevents parallel sessions from clobbering each other). The worker is a separate process and cannot see this conversation, so the content must be self-contained.
+2. Run in the background with Bash (`run_in_background: true`):
+   ```bash
+   pilot-workers dispatch --provider ds --mode review --workdir "$PWD" --task-file /tmp/ds-review-<task-slug>-<timestamp>.md
+   ```
+3. stdout is exactly two lines of JSON: the first line is `worker_runner.started` (record the run_id and log path); the last line is `worker_runner.verdict`. **The completion signal = this background Bash exiting on its own**; do not poll by process name, do not read the shared log to make any judgment (latest.log is for humans only).
+4. Verdict handling: `completed` -> `final_text` is the full worker report; `step_capped_partial` -> partial coverage, report the uncovered scope truthfully; `empty`/`error` -> read `jsonl_path` first to do a post-mortem, then report the cause of death truthfully; never draw a conclusion without reading the evidence.
+
+Do not edit a worker's target files while it is running.
+
+### 3. Spot-check
+
+Pick 1-2 **high-severity** findings, open the corresponding `file:line` with Read, and check whether they hold. False positives are the most common defect of review tasks -- anything that does not check out gets flagged in your report as "verified as false positive"; do not let it pollute the main thread's judgment.
+
+### 4. Report
+
+Bring the finding list (with severities and `file:line`) back verbatim; note the spot-check results. **Do not expand it with your own fix suggestions** -- verdicts on whether findings are real, and the fix plan, are the main thread's job after aggregating all axes.
+
+## Boundaries
+
+- "Fix it while you're at it" -> no; review mode cannot edit files, fixes go through main-thread planning
+- The axis is too broad ("review the entire repo") -> go back and have the main thread split the axes; one instance, one axis
+- When reviewing a diff, if the baseline is unclear -> clarify which two versions are being compared first