pilot-workers 0.2.0__py3-none-any.whl

pilot_workers/integrations/claude-host/commands/glm/review.md

@@ -0,0 +1,38 @@
+---
+description: Dispatch GLM to review code (read-only, no fixes); fan out across multiple axes in parallel
+argument-hint: [what to review]
+---
+
+The user wants GLM to review code:
+
+$ARGUMENTS
+
+Do the following:
+
+1. **First fix the review axes -- this is judgment work and it is yours.** Split out 2-4 orthogonal axes from the target under review, for example: correctness and boundary conditions, security (injection/privilege escalation/secret leakage), performance (hot paths/N+1/leaks), consistency (deviations from existing codebase conventions). Write each axis as its own self-contained task file: scope, what specifically to look at under this axis. GLM is a separate OpenCode process and cannot see this conversation. Append the output discipline:
+
+   > 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
+
+   The structure is provided by the `pilot-workers template review` template; just fill in the blanks. When there are many axes, you can mix in kimi (`--provider kimi-k3`) to spread the load across both quotas.
+
+2. **Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow). Each axis is one independent task with one independent background Bash:**
+
+   1. For each axis: `pilot-workers template review > /tmp/glm-review-<axis-name>-<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. Launch multiple background Bash calls (`run_in_background: true`) in the same round, one per axis:
+      ```bash
+      pilot-workers dispatch --provider glm --mode review --workdir "$PWD" --task-file /tmp/glm-review-<axis-name>-<timestamp>.md
+      ```
+   3. Each stream's 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 = that 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). Each axis collects its verdict independently, without interference.
+   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. **Aggregation is your job.** Merge and dedupe findings across axes, sort by severity, and **report to the user directly**. Do not spot-check -- findings carry `file:line`, so the user can verify themselves. You decide the fix plan: do small fixes yourself, and route large batches of mechanical fixes through `/glm:code`.
+
+4. **Report honestly**: how many findings per axis, which ones are real (with `file:line`), and how you plan to fix them.
+
+If the scope of review is unclear (no range at all), ask the user first; do not fire indiscriminately across the whole repo.

pilot_workers/integrations/claude-host/commands/glm/test.md

@@ -0,0 +1,30 @@
+---
+description: Dispatch GLM to run tests and gather failure information (read-only, no fixes)
+argument-hint: [what tests to run]
+---
+
+The user wants GLM to run tests:
+
+$ARGUMENTS
+
+Do the following:
+
+1. **Make clear what to run.** Write the test command, directory, and preconditions as a self-contained task file (GLM is a separate OpenCode process and cannot see this conversation). If nothing is specified, take a quick look at how the project runs its tests, fix the command, then dispatch. General discipline (run, do not fix; reporting format) **does not need to be written** -- dispatch injects `prompts/test.md` automatically; the task only states which command to run and any known pre-existing failures. The structure is provided by the `pilot-workers template test` template; just fill in the blanks.
+
+2. **Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow):**
+
+   1. `pilot-workers template test > /tmp/glm-test-<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 glm --mode test --workdir "$PWD" --task-file /tmp/glm-test-<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; sanity-check it: has counts and raw error text -> trust it; just "all passed" with no counts -> suspicious, read `jsonl_path` to see what command it actually ran, and redispatch if needed; run `git status` to confirm it left no junk changes; `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. **Once you have the failure list, diagnosis and fixes are your job.** Use `file:line` to locate the cause and decide the fix; route large batches of mechanical fixes through `/glm:code`, and do small fixes yourself.
+
+4. **Report honestly**: how many passed/failed, your read on the cause of failure, and how you plan to fix it.
+
+If what to run is unclear, ask the user first; do not guess the command.

pilot_workers/integrations/claude-host/commands/kimi/code.md

@@ -0,0 +1,47 @@
+---
+description: Dispatch a coding task Claude has already planned to Kimi for execution (modifies files directly; dispatch in the background, then harvest by verdict when done)
+argument-hint: [task description]
+---
+
+The user wants to dispatch this coding task to Kimi for execution:
+
+$ARGUMENTS
+
+Do the following:
+
+1. **Planning is your job, not Kimi's.** If the approach is not decided, think it through first; if you need to scope the code first, run `/kimi:explore` -- do not read through it yourself.
+
+2. **Before dispatching, self-check whether it is worth it: is the expected change volume far larger than the task description?**
+   - Worth it: large batches of mechanical changes (renaming dozens of files, scaffolding boilerplate, backfilling tests in bulk), parallel fan-out, your quota near the cap
+   - Not worth it: small tweaks, tasks that need mid-course judgment, self-contained specs about as long as the diff
+   - **One worker call should bundle at most 2-3 related fix points; split larger batches into multiple workers (which can run in parallel).**
+
+   If it is not worth it, just tell the user "this is better done by me" and do it yourself. Do not force a dispatch.
+
+3. **Write the task as a self-contained spec.** Kimi is a separate OpenCode process and cannot see this conversation, so the spec must be self-contained: explicit file paths, completion criteria, and the do-not-touch boundaries. **Pick sub-second verification commands** (grep/diff/typecheck); leave the heavyweight `pnpm test` for the main session to run. General discipline **does not need to be written** -- dispatch injects `prompts/*.md` automatically. Copy any out-of-project material into the project root first, then reference it. The structure is provided by the `pilot-workers template code` template; just fill in the blanks.
+
+4. **Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow):**
+
+   1. `pilot-workers template code > /tmp/kimi-k3-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 kimi-k3 --mode code --workdir "$PWD" --task-file /tmp/kimi-k3-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 kimi-k3 --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.
+
+   For parallel workers, add `--worktree` so each gets an isolated git worktree that will not stomp the others; clean up with `pilot-workers maintain worktrees remove <path>` when done. When you want parallel fan-out without consuming main-session turns, route through the corresponding coder subagent instead (one instance manages one worker). Do not edit a worker's target files while it is running.
+
+5. **Verification is the single verification pass -- do not skip it** (only when verdict == `completed` or `step_capped_partial`):
+   - Run `git diff --stat` against the spec whitelist to catch out-of-bounds changes (exclude dirty changes that pre-existed before the session started)
+   - Spot-check the actual diff with `git diff` to confirm it matches the plan
+   - Run tests/lint
+
+6. **Report honestly**: what changed, what verification found, and what the user should look at themselves.
+
+If the task description is too vague to dispatch, ask the user first; do not force a dispatch.

pilot_workers/integrations/claude-host/commands/kimi/explore.md

@@ -0,0 +1,38 @@
+---
+description: Dispatch Kimi to explore the codebase (read-only); conclusions must carry file:line
+argument-hint: [what to investigate]
+---
+
+The user wants to dispatch this exploration task to Kimi (reading code is the bulk of token spend, so this kind of work is a top candidate for dispatch):
+
+$ARGUMENTS
+
+Do the following:
+
+1. **Write the user's question straight into a task file; do not read the code yourself first.** The whole point of dispatching explore is to save your tokens -- running grep/read yourself first wastes that saving. You only do two things:
+   - Fill in the working directory and scope (if the user did not specify, use `$PWD` and scope to `src/` or the whole project)
+   - Append the output discipline below verbatim to the end of 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"
+
+   The structure is provided by the `pilot-workers template explore` template; just fill in the blanks.
+
+2. **Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow):**
+
+   1. `pilot-workers template explore > /tmp/kimi-k3-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 kimi-k3 --mode explore --workdir "$PWD" --task-file /tmp/kimi-k3-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 -- **bring it straight back to the user**, no spot-checking, no parroting, no rewriting; hand the conclusions on as-is with their `file:line`; `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. If the next step is to change code: planning is your job; the mechanical-execution part of the plan goes through `/kimi:code`.
+
+If the question is too vague (even the user does not know what to investigate), ask one clarifying question first; do not force a dispatch. But the bar for "vague" is that the user themselves does not know what to look into -- not that you think the question is not structured enough. "Figure out how auth works" is enough; do not require them to list specific files first.

pilot_workers/integrations/claude-host/commands/kimi/review.md

@@ -0,0 +1,38 @@
+---
+description: Dispatch Kimi to review code (read-only, no fixes); fan out across multiple axes in parallel
+argument-hint: [what to review]
+---
+
+The user wants Kimi to review code:
+
+$ARGUMENTS
+
+Do the following:
+
+1. **First fix the review axes -- this is judgment work and it is yours.** Split out 2-4 orthogonal axes from the target under review, for example: correctness and boundary conditions, security (injection/privilege escalation/secret leakage), performance (hot paths/N+1/leaks), consistency (deviations from existing codebase conventions). Write each axis as its own self-contained task file: scope, what specifically to look at under this axis. Kimi is a separate OpenCode process and cannot see this conversation. Append the output discipline:
+
+   > 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
+
+   The structure is provided by the `pilot-workers template review` template; just fill in the blanks. When there are many axes, you can mix in glm (`--provider glm`) to spread the load across both quotas.
+
+2. **Dispatch (the protocol is fixed in the pilot-workers CLI; do not invent your own flow). Each axis is one independent task with one independent background Bash:**
+
+   1. For each axis: `pilot-workers template review > /tmp/kimi-k3-review-<axis-name>-<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. Launch multiple background Bash calls (`run_in_background: true`) in the same round, one per axis:
+      ```bash
+      pilot-workers dispatch --provider kimi-k3 --mode review --workdir "$PWD" --task-file /tmp/kimi-k3-review-<axis-name>-<timestamp>.md
+      ```
+   3. Each stream's 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 = that 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). Each axis collects its verdict independently, without interference.
+   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. **Aggregation is your job.** Merge and dedupe findings across axes, sort by severity, and **report to the user directly**. Do not spot-check -- findings carry `file:line`, so the user can verify themselves. You decide the fix plan: do small fixes yourself, and route large batches of mechanical fixes through `/kimi:code`.
+
+4. **Report honestly**: how many findings per axis, which ones are real (with `file:line`), and how you plan to fix them.
+
+If the scope of review is unclear (no range at all), ask the user first; do not fire indiscriminately across the whole repo.

pilot_workers/integrations/claude-host/commands/kimi/test.md

@@ -0,0 +1,32 @@
+---
+description: Dispatch Kimi to run tests and gather failure information (read-only, no fixes; dispatch in the background, then harvest by verdict when done)
+argument-hint: [what tests to run]
+---
+
+The user wants Kimi to run tests:
+
+$ARGUMENTS
+
+Do the following:
+
+1. **First self-check whether it is worth it -- push back on fast suites.** Estimate locally first: if the full suite takes < 1 minute, or the failure output is expected to be short (a few dozen lines) -> just tell the user "I can run this faster myself" and run it yourself. Kimi's value cases are: huge output (hundreds/thousands of lines of failures to sift), repeated reruns to gather data, or your context is near full.
+
+2. **Make clear what to run.** Write the test command, directory, and preconditions as a self-contained task file (Kimi is a separate OpenCode process and cannot see this conversation). If nothing is specified, take a quick look at how the project runs its tests, fix the command, then dispatch. General discipline (run, do not fix; reporting format) **does not need to be written** -- dispatch injects `prompts/test.md` automatically; the task only states which command to run and any known pre-existing failures. The structure is provided by the `pilot-workers template test` 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 test > /tmp/kimi-k3-test-<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 kimi-k3 --mode test --workdir "$PWD" --task-file /tmp/kimi-k3-test-<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; sanity-check it: has counts and raw error text -> trust it; just "all passed" with no counts -> suspicious, read `jsonl_path` to see what command it actually ran; run `git status` to confirm it left no junk changes; `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.
+
+4. **Once you have the failure list, diagnosis and fixes are your job.** Use `file:line` to locate the cause and decide the fix; route large batches of mechanical fixes through `/kimi:code`, and do small fixes yourself.
+
+5. **Report honestly**: how many passed/failed, your read on the cause of failure, and how you plan to fix it.
+
+If what to run is unclear, ask the user first; do not guess the command.

pilot_workers/integrations/codex-host/ds/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: ds
+description: Plan with Codex, then run a bounded task through the fixed DeepSeek OpenCode worker and have Codex verify the result. Invoke explicitly as `$ds [code|explore|test|review|resume] [task]`; examples include `$ds code`, `$ds code fix the login bug`, `$ds review current changes`, and `$ds resume ses_xxx continue the fix`. Use whenever the user asks to delegate coding, investigation, testing, review, or session continuation to DeepSeek.
+---
+
+# DeepSeek Worker
+
+Parse the first word after `$ds` as the mode (`code`/`explore`/`test`/`review`/`resume`); otherwise default to `code` and treat all text as the task. Keep planning, task decomposition, and final verification with Codex; give the worker only settled decisions.
+
+1. `pilot-workers template <mode> > /tmp/ds-<mode>-<slug>-<timestamp>.md`, then fill in the template with the task (unique filename — parallel sessions must not collide). The worker is an independent process and cannot see this conversation; the file must be self-contained. No template for `resume` — pass `--task "<what remains, how to fix>"` instead.
+2. Run in a background shell: `pilot-workers dispatch --provider ds --mode <mode> --workdir <absolute-project-path> --task-file <file>`. For `resume` add `--session <session_id>` and use the workdir from the prior `started` event.
+3. stdout is exactly two JSON lines: first `worker_runner.started` (note run_id and log paths), last `worker_runner.verdict`. Completion signal = the background shell exiting. Never poll by process name; never judge from shared logs. Live log for humans: `$PILOT_WORKERS_HOME (default $CODEX_HOME) /opencode-workers/logs/ds/latest.log`.
+4a. If the background shell exits but stdout has fewer than two lines, check its stderr — early failures (missing credentials, runner not installed) produce no JSON.
+4. Act on `verdict`: `completed` → `final_text` is the worker's report; `step_capped_partial` → partial coverage, report honestly; `empty`/`error` → read `jsonl_path` for the post-mortem before concluding anything. Prefer `resume` over cold re-dispatch when a run fails or falls short; after the same obstacle twice, take over yourself.
+5. After `code`/`resume`: inspect the actual diff against the task scope and run the smallest real verification yourself. Never treat the worker's completion claim as proof. Missing credentials → `pilot-workers credentials ds`.

pilot_workers/integrations/codex-host/ds/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "DeepSeek"
+  short_description: "Collaborate with DeepSeek V4 Pro on design, implementation, investigation, testing, and review"
+  default_prompt: "$ds code"

pilot_workers/integrations/codex-host/glm/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: glm
+description: Plan with Codex, then run a bounded task through the fixed GLM OpenCode worker and have Codex verify the result. Invoke explicitly as `$glm [code|explore|test|review|resume] [task]`; examples include `$glm code`, `$glm code fix the login bug`, `$glm review current changes`, and `$glm resume ses_xxx continue the fix`. Use whenever the user asks to delegate coding, investigation, testing, review, or session continuation to GLM.
+---
+
+# GLM Worker
+
+Parse the first word after `$glm` as the mode (`code`/`explore`/`test`/`review`/`resume`); otherwise default to `code` and treat all text as the task. Keep planning, task decomposition, and final verification with Codex; give the worker only settled decisions.
+
+1. `pilot-workers template <mode> > /tmp/glm-<mode>-<slug>-<timestamp>.md`, then fill in the template with the task (unique filename — parallel sessions must not collide). The worker is an independent process and cannot see this conversation; the file must be self-contained. No template for `resume` — pass `--task "<what remains, how to fix>"` instead.
+2. Run in a background shell: `pilot-workers dispatch --provider glm --mode <mode> --workdir <absolute-project-path> --task-file <file>`. For `resume` add `--session <session_id>` and use the workdir from the prior `started` event.
+3. stdout is exactly two JSON lines: first `worker_runner.started` (note run_id and log paths), last `worker_runner.verdict`. Completion signal = the background shell exiting. Never poll by process name; never judge from shared logs. Live log for humans: `$PILOT_WORKERS_HOME (default $CODEX_HOME) /opencode-workers/logs/glm/latest.log`.
+4a. If the background shell exits but stdout has fewer than two lines, check its stderr — early failures (missing credentials, runner not installed) produce no JSON.
+4. Act on `verdict`: `completed` → `final_text` is the worker's report; `step_capped_partial` → partial coverage, report honestly; `empty`/`error` → read `jsonl_path` for the post-mortem before concluding anything. Prefer `resume` over cold re-dispatch when a run fails or falls short; after the same obstacle twice, take over yourself.
+5. After `code`/`resume`: inspect the actual diff against the task scope and run the smallest real verification yourself. Never treat the worker's completion claim as proof. Missing credentials → `pilot-workers credentials glm`.

pilot_workers/integrations/codex-host/glm/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GLM"
+  short_description: "Run code, investigation, testing, or review on the fixed GLM 5.2"
+  default_prompt: "$glm code"

pilot_workers/integrations/codex-host/kimi/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: kimi
+description: Plan with Codex, then run a bounded task through the fixed Kimi K3 OpenCode worker and have Codex verify the result. Invoke explicitly as `$kimi [code|explore|test|review|resume] [task]`; examples include `$kimi code`, `$kimi code fix the login bug`, `$kimi review current changes`, and `$kimi resume ses_xxx continue the fix`. Use whenever the user asks to delegate coding, investigation, testing, review, or session continuation to Kimi K3.
+---
+
+# Kimi K3 Worker
+
+Parse the first word after `$kimi` as the mode (`code`/`explore`/`test`/`review`/`resume`); otherwise default to `code` and treat all text as the task. Keep planning, task decomposition, and final verification with Codex; give the worker only settled decisions.
+
+1. `pilot-workers template <mode> > /tmp/kimi-<mode>-<slug>-<timestamp>.md`, then fill in the template with the task (unique filename — parallel sessions must not collide). The worker is an independent process and cannot see this conversation; the file must be self-contained. No template for `resume` — pass `--task "<what remains, how to fix>"` instead.
+2. Run in a background shell: `pilot-workers dispatch --provider kimi-k3 --mode <mode> --workdir <absolute-project-path> --task-file <file>`. For `resume` add `--session <session_id>` and use the workdir from the prior `started` event.
+3. stdout is exactly two JSON lines: first `worker_runner.started` (note run_id and log paths), last `worker_runner.verdict`. Completion signal = the background shell exiting. Never poll by process name; never judge from shared logs. Live log for humans: `$PILOT_WORKERS_HOME (default $CODEX_HOME) /opencode-workers/logs/kimi-k3/latest.log`.
+4a. If the background shell exits but stdout has fewer than two lines, check its stderr — early failures (missing credentials, runner not installed) produce no JSON.
+4. Act on `verdict`: `completed` → `final_text` is the worker's report; `step_capped_partial` → partial coverage, report honestly; `empty`/`error` → read `jsonl_path` for the post-mortem before concluding anything. Prefer `resume` over cold re-dispatch when a run fails or falls short; after the same obstacle twice, take over yourself.
+5. After `code`/`resume`: inspect the actual diff against the task scope and run the smallest real verification yourself. Never treat the worker's completion claim as proof. Missing credentials → `pilot-workers credentials kimi-k3`.

pilot_workers/integrations/codex-host/kimi/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Kimi"
+  short_description: "Run code, investigation, testing, or review on the fixed Kimi K3"
+  default_prompt: "$kimi code"

pilot_workers/maintain.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Explicit, auditable lifecycle tools for worker logs and detached worktrees.
+
+Never silent: every deletion is printed. Never destructive by surprise:
+- log cleanup keeps each provider's newest run pair regardless of age;
+- worktree removal refuses when the worktree is dirty or holds commits that
+  are not reachable from any ref of the main repository (unintegrated work).
+There is no force flag on purpose; unintegrated changes are integrated or
+discarded by a human with plain git, not by this script.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import time
+
+from pilot_workers import providers
+
+
+def _run_pairs(logs_dir: Path) -> list[list[Path]]:
+    """Group per-run files (jsonl + stderr + rendered archive) by run id, newest first."""
+    groups: dict[str, list[Path]] = {}
+    for path in logs_dir.iterdir():
+        if not path.is_file():
+            continue
+        name = path.name
+        if name == "latest.log":
+            continue
+        run_id = None
+        if name.endswith(".stderr.log"):
+            run_id = name[: -len(".stderr.log")]
+        elif name.endswith(".jsonl"):
+            run_id = name[: -len(".jsonl")]
+        elif name.startswith("rendered-") and name.endswith(".log"):
+            run_id = name[len("rendered-") : -len(".log")]
+        if run_id is None:
+            continue
+        groups.setdefault(run_id, []).append(path)
+    ordered = sorted(
+        groups.values(),
+        key=lambda paths: max(item.stat().st_mtime for item in paths),
+        reverse=True,
+    )
+    return ordered
+
+
+def cleanup_logs(older_than_days: int, provider_keys: list[str]) -> int:
+    if older_than_days < 1:
+        raise RuntimeError("--older-than-days must be >= 1")
+    cutoff = time.time() - older_than_days * 86400
+    removed = 0
+    for key in provider_keys:
+        logs_dir = providers.logs_root(providers.PROVIDERS[key])
+        if not logs_dir.is_dir():
+            print(f"{key}: no log directory, skipping")
+            continue
+        pairs = _run_pairs(logs_dir)
+        for index, paths in enumerate(pairs):
+            newest_mtime = max(item.stat().st_mtime for item in paths)
+            if index == 0:
+                continue  # always keep the newest run for diagnosis
+            if newest_mtime >= cutoff:
+                continue
+            for path in sorted(paths):
+                print(f"delete {path}")
+                path.unlink()
+                removed += 1
+    print(f"removed {removed} file(s)")
+    return 0
+
+
+def _git(worktree: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(worktree), *args], text=True, capture_output=True, check=False
+    )
+
+
+def worktree_status(path: Path) -> dict:
+    dirty = None
+    unintegrated = None
+    head = None
+    status = _git(path, "status", "--porcelain")
+    if status.returncode == 0:
+        dirty = bool(status.stdout.strip())
+    head_result = _git(path, "rev-parse", "HEAD")
+    if head_result.returncode == 0:
+        head = head_result.stdout.strip()
+    reachable = _git(path, "rev-list", "HEAD", "--not", "--all")
+    if reachable.returncode == 0:
+        unintegrated = bool(reachable.stdout.strip())
+    return {
+        "path": str(path),
+        "head": head,
+        "dirty": dirty,
+        "unintegrated_commits": unintegrated,
+        "age_days": round((time.time() - path.stat().st_mtime) / 86400, 1),
+    }
+
+
+def list_worktrees() -> int:
+    root = providers.worktrees_root()
+    if not root.is_dir():
+        print("[]")
+        return 0
+    entries = [worktree_status(path) for path in sorted(root.iterdir()) if path.is_dir()]
+    print(json.dumps(entries, indent=2))
+    return 0
+
+
+def remove_worktree(target: str) -> int:
+    root = providers.worktrees_root().resolve()
+    path = Path(target).expanduser().resolve()
+    if not path.is_dir():
+        raise RuntimeError(f"worktree does not exist: {path}")
+    if root not in path.parents and path != root:
+        raise RuntimeError(f"refusing to touch a path outside {root}: {path}")
+    info = worktree_status(path)
+    if info["dirty"] is not False:
+        raise RuntimeError(
+            f"refusing removal: worktree is dirty or unreadable ({path}); "
+            "integrate or discard changes with git first"
+        )
+    if info["unintegrated_commits"] is not False:
+        raise RuntimeError(
+            f"refusing removal: worktree holds commits unreachable from any ref ({path}); "
+            "integrate them first"
+        )
+    result = _git(path, "worktree", "remove", str(path))
+    if result.returncode != 0:
+        raise RuntimeError(f"git worktree remove failed: {result.stderr.strip()}")
+    print(f"removed {path}")
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Worker log and worktree lifecycle tools.")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    logs = commands.add_parser("logs", help="Delete old per-run logs (never the newest run).")
+    logs.add_argument("--older-than-days", type=int, required=True)
+    logs.add_argument("--provider", choices=sorted(providers.PROVIDERS), default=None)
+
+    worktrees = commands.add_parser("worktrees", help="List or safely remove detached worktrees.")
+    actions = worktrees.add_subparsers(dest="action", required=True)
+    actions.add_parser("list", help="Show every worker worktree with dirty/integration state.")
+    remove = actions.add_parser("remove", help="Remove one clean, integrated worktree.")
+    remove.add_argument("path")
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        if args.command == "logs":
+            keys = [args.provider] if args.provider else sorted(providers.PROVIDERS)
+            return cleanup_logs(args.older_than_days, keys)
+        if args.action == "list":
+            return list_worktrees()
+        return remove_worktree(args.path)
+    except (OSError, RuntimeError) as exc:
+        print(f"error: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())