1# Crush runner reference
 2
 3Treat examples as possibly outdated; inspect installed help first and prefer
 4observed behavior over this file.
 5
 6## Help surfaces
 7
 8- Top-level help: `crush --help`
 9- Non-interactive help: `crush run --help`
10- Model list help: `crush models --help`
11
12Record the exact help commands inspected and any differences from this file in
13`runner_capabilities`.
14
15## Model availability
16
17- Use `crush models` only after help confirms the command exists.
18- Preserve exact model IDs, including provider prefixes.
19- Record model family, generation, and variant only when inferable from the
20  exact ID or model-list metadata.
21- Treat user-pinned IDs as candidates, not proof of availability, unless Crush
22  lists or accepts them.
23
24## Crush as the Prose VM
25
26Invoke from the repository or worktree being reviewed so Crosscheck sees the
27right caller CWD.
28
29<!-- rumdl-disable MD013 -->
30
31```bash
32crush run -m "provider/model" "prose run ~/repos/personal/crosscheck/src -- subject: \"current diff\" preferences: \"...\""
33```
34
35<!-- rumdl-enable MD013 -->
36
37`--yolo` best-effort enables write and execute operations while disallowing more
38dangerous commands like package operations, sudo, and curl. It is suitable for
39safe-ish read/write reviews without proper virtual machines/containment, but
40report its usage to the user.
41
42<!-- rumdl-disable MD013 -->
43
44```bash
45crush run --yolo -m "provider/model" "prose run ~/repos/personal/crosscheck/src -- subject: \"git diff main...HEAD\" preferences: \"use crush run --yolo for local testing\""
46```
47
48<!-- rumdl-enable MD013 -->
49
50If help confirms `--cwd`, use it only when launching from outside the reviewed
51repo. Otherwise run the command with the reviewed repo as the process working
52directory.
53
54## Crush quirks
55
56The agent in Crush has a shell tool. When the shell tool takes a long time to
57finish/exit, which _always_ will when creating a runner or Prose VM through it,
58the tool will fork the process to the background and return control to the agent
59in Crush. It will include instructions to run `job_output` to see the output and
60`kill_job` to terminate it. `job_output` lets the agent `wait` until the process
61exits and provide all the output at once (generally preferred) or return
62immediately with the output so far (preferred with processes with that might
63oversight). This mechanism allows the agent to oversee long-running
64subprocesses. The Prose VM, reviewers, or validators are expected to take a
65_very_ long time, many minutes in some cases. When Crush is the Prose VM, it
66should seldom wait, always sleep in between checks, and vary the sleep time
67according to how the runner is performing so far. Not checking a subprocess
68that's been doing just right for many minutes is fine. Killing a subprocess
69that's obviously doing the wrong the early is fine. When Crush is a runner, it
70should not be instructed how to use the tools because its system prompts are
71adequate. It's only orchestration that requires instruction.
72
73## Crush as a review runner
74
75- Use non-interactive `crush run`.
76- Pass the exact candidate model with `-m provider/model` after availability is
77  confirmed or user-pinned uncertainty is recorded.
78- Run from the lane or validator workspace copy, not the original reviewed
79  worktree.
80- Capture stdout as the runner report.
81- Plain `crush run` is read-only and satisfies Crosscheck's current runner
82  eligibility.
83- `crush run --yolo` is acceptable when escalating without sandboxes.
84
85Keep the orchestration role distinct from the review-runner role: a Crush
86process acting as the Prose VM runs Crosscheck; a Crush process acting as a
87runner receives one lane or validator prompt from the Prose VM or another
88runner.