crush.md

Crush runner reference

Treat examples as possibly outdated; inspect installed help first and prefer observed behavior over this file.

Help surfaces

  • Top-level help: crush --help
  • Non-interactive help: crush run --help
  • Model list help: crush models --help

Record the exact help commands inspected and any differences from this file in runner_capabilities.

Model availability

  • Use crush models only after help confirms the command exists.
  • Preserve exact model IDs, including provider prefixes.
  • Record model family, generation, and variant only when inferable from the exact ID or model-list metadata.
  • Treat user-pinned IDs as candidates, not proof of availability, unless Crush lists or accepts them.

Crush as the Prose VM

Invoke from the repository or worktree being reviewed so Crosscheck sees the right caller CWD.

crush run -m "provider/model" "prose run ~/repos/personal/crosscheck/src -- subject: \"current diff\" preferences: \"...\""

--yolo best-effort enables write and execute operations while disallowing more dangerous commands like package operations, sudo, and curl. It is suitable for safe-ish read/write reviews without proper virtual machines/containment, but report its usage to the user.

crush run --yolo -m "provider/model" "prose run ~/repos/personal/crosscheck/src -- subject: \"git diff main...HEAD\" preferences: \"use crush run --yolo for local testing\""

If help confirms --cwd, use it only when launching from outside the reviewed repo. Otherwise run the command with the reviewed repo as the process working directory.

Crush quirks

The agent in Crush has a shell tool. When the shell tool takes a long time to finish/exit, which always will when creating a runner or Prose VM through it, the tool will fork the process to the background and return control to the agent in Crush. It will include instructions to run job_output to see the output and kill_job to terminate it. job_output lets the agent wait until the process exits and provide all the output at once (generally preferred) or return immediately with the output so far (preferred with processes with that might oversight). This mechanism allows the agent to oversee long-running subprocesses. The Prose VM, reviewers, or validators are expected to take a very long time, many minutes in some cases. When Crush is the Prose VM, it should seldom wait, always sleep in between checks, and vary the sleep time according to how the runner is performing so far. Not checking a subprocess that's been doing just right for many minutes is fine. Killing a subprocess that's obviously doing the wrong the early is fine. When Crush is a runner, it should not be instructed how to use the tools because its system prompts are adequate. It's only orchestration that requires instruction.

Crush as a review runner

  • Use non-interactive crush run.
  • Pass the exact candidate model with -m provider/model after availability is confirmed or user-pinned uncertainty is recorded.
  • Run from the lane or validator workspace copy, not the original reviewed worktree.
  • Capture stdout as the runner report.
  • Plain crush run is read-only and satisfies Crosscheck's current runner eligibility.
  • crush run --yolo is acceptable when escalating without sandboxes.

Keep the orchestration role distinct from the review-runner role: a Crush process acting as the Prose VM runs Crosscheck; a Crush process acting as a runner receives one lane or validator prompt from the Prose VM or another runner.