Catcrafts/Crafter.Review
Watch
2
0
Fork
You've already forked Crafter.Review
 0
Code Issues 7 Pull requests Projects Releases 3 Packages Wiki Activity Actions

feat(run): crafter-review run and slots, the driver of the gates

Browse source 
Run: gate 0 (the artifact, the trees, the inventory, the run lock, the
scratch dir, dispositions, reuse state, resume, reads per round, seats,
the board), the stack and migration preflights, the prompts, reuse of
whole and block verdicts, salvage, a gate on the pool, checkpoints, the
dump, the dry-run report and the unit-state store; slots_plan and
app_ready beside it. The CLI parses run's 28 options, types and choices
included.

A full run takes its lifetime lock beside the board before it joins it.
A signal - or the stop file `crafter-review stop` writes, looked at
every 2 s - stops the run once gate 0 is through, and the stop stays in
force for the gates after; before that it ends the process with its
descendants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-10-31 09:16:41 +01:00
commit 0f803d90bd
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
9 changed files with 2639 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

212
implementations/Crafter.Review-Driver.cpp
View file

@ -12,6 +12,9 @@ import :Config;
import :Freeze;
import :PgWire;
import :Totp;
import :Plan;
import :OpenCode;
import :Run;
import std;
namespace fs = std::filesystem;
@ -51,12 +54,25 @@ inventory unit, against a frozen commit range.)";
}
// ---- the option parser these commands use ---------------------------------
enum class Kind {
String,
Int,
Float,
};
struct OptionSpec {
std::string_view name;
// A value follows (`--x V` or `--x=V`); else a store_true flag.
bool takesValue;
std::string_view metavar;
std::string_view help;
// An integer or a float option: the value must parse as
// Dyn::ParseInt / Dyn::ParseFloat takes it.
Kind kind = Kind::String;
std::span<const std::string_view> choices = {};
bool required = false;
// Left out of --help.
bool hidden = false;
};
struct Parsed {
@ -78,7 +94,9 @@ inventory unit, against a frozen commit range.)";
std::string UsageLine(std::string_view prog, std::span<const OptionSpec> specs) {
std::string line = std::format("usage: {} [-h]", prog);
for (const OptionSpec& spec : specs) {
line += spec.takesValue ? std::format(" [{} {}]", spec.name, spec.metavar) : std::format(" [{}]", spec.name);
if (spec.hidden) continue;
const std::string text = spec.takesValue ? std::format("{} {}", spec.name, spec.metavar) : std::string(spec.name);
line += spec.required ? std::format(" {}", text) : std::format(" [{}]", text);
}
return line;
}
@ -86,6 +104,7 @@ inventory unit, against a frozen commit range.)";
std::string Help(std::string_view prog, std::string_view description, std::span<const OptionSpec> specs) {
std::string text = std::format("{}\n\n{}\n\noptions:\n -h, --help show this help message and exit\n", UsageLine(prog, specs), description);
for (const OptionSpec& spec : specs) {
if (spec.hidden) continue;
const std::string left = spec.takesValue ? std::format("{} {}", spec.name, spec.metavar) : std::string(spec.name);
text += left.size() < 20 ? std::format(" {:<20} {}\n", left, spec.help) : std::format(" {}\n {}\n", left, spec.help);
}
@ -142,24 +161,51 @@ inventory unit, against a frozen commit range.)";
parsed.flags.insert(key);
continue;
}
std::string value;
if (equals != std::string_view::npos) {
parsed.values[key] = std::string(arg.substr(equals + 1));
value = std::string(arg.substr(equals + 1));
} else if (i + 1 < args.size() && !(args[i + 1].starts_with('-') && args[i + 1].size() > 1)) {
parsed.values[key] = std::string(args[++i]);
value = std::string(args[++i]);
} else {
parsed.error = std::format("argument {}: expected one argument", spec.name);
return parsed;
}
if (spec.kind == Kind::Int && !Dyn::ParseInt(value)) {
parsed.error = std::format("argument {}: invalid int value: {}", spec.name, Dyn::Repr(value));
return parsed;
}
if (spec.kind == Kind::Float && !Dyn::ParseFloat(value)) {
parsed.error = std::format("argument {}: invalid float value: {}", spec.name, Dyn::Repr(value));
return parsed;
}
if (!spec.choices.empty() && !std::ranges::contains(spec.choices, value)) {
std::vector<std::string> quoted;
for (const std::string_view c : spec.choices) quoted.push_back(Dyn::Repr(c));
parsed.error = std::format("argument {}: invalid choice: {} (choose from {})", spec.name, Dyn::Repr(value), Dyn::Join(quoted, ", "));
return parsed;
}
parsed.values[key] = std::move(value);
}
if (!unrecognized.empty()) parsed.error = std::format("unrecognized arguments: {}", Dyn::Join(unrecognized, " "));
if (!unrecognized.empty()) {
parsed.error = std::format("unrecognized arguments: {}", Dyn::Join(unrecognized, " "));
return parsed;
}
std::vector<std::string> missing;
for (const OptionSpec& spec : specs) {
if (spec.required && !parsed.values.contains(spec.name.substr(2))) missing.emplace_back(spec.name);
}
if (!missing.empty()) parsed.error = std::format("the following arguments are required: {}", Dyn::Join(missing, ", "));
return parsed;
}
// The consumer config, loaded before every command but `config`:
// warnings on stderr, a problem stops it.
std::optional<Json> LoadConfig(const std::optional<std::string>& configPath) {
// warnings on stderr (`run` logs them with its other lines), a problem
// stops it.
std::optional<Json> LoadConfig(const std::optional<std::string>& configPath, bool warn = true) {
Config::Loaded loaded = Config::Load(fs::current_path(), configPath ? fs::path(*configPath) : fs::path());
for (const Json& warning : Dyn::Or(Dyn::Get(loaded.config, "_warnings"), Dyn::EmptyList())) std::println(std::cerr, "config: warning: {}", warning.get<std::string>());
if (warn) {
for (const Json& warning : Dyn::Or(Dyn::Get(loaded.config, "_warnings"), Dyn::EmptyList())) std::println(std::cerr, "config: warning: {}", warning.get<std::string>());
}
if (!loaded.problems.empty()) {
Die(std::format("config: {}", Dyn::Join(loaded.problems, "; ")));
return std::nullopt;
@ -179,6 +225,152 @@ inventory unit, against a frozen commit range.)";
{"--verify", false, "", "push-time check: HEAD, a clean tree and a fresh export still match freeze.json"},
}};
constexpr std::array<std::string_view, 1> Modes = {"commits"};
constexpr std::array<std::string_view, 2> Harnesses = {"claude", "opencode"};
const std::vector<OptionSpec>& RunOptions() {
static const std::string effort = std::format("reasoning effort of every lens process (default {})", Plan::Effort);
static const std::string reads =
std::format("clean reads a code unit of the static code lenses needs before its verdict is reused, one per round (default {})", Plan::Reads);
static const std::string models = [] {
std::vector<std::string> keys;
for (const Plan::ModelTier& m : Plan::Models()) keys.push_back(m.tier);
return std::format("override the lens model table, e.g. fable=claude-fable-5-1 (keys: {})", Dyn::Join(keys, ","));
}();
static const std::string variant = std::format("opencode harness: the model's reasoning variant (default {})", OpenCode::DefaultVariant);
static const std::vector<OptionSpec> specs = {
{"--mode", true, "MODE", "", Kind::String, Modes, false, true},
{"--artifact", true, "ARTIFACT", "the frozen artifact dir (.review-gates/push/<slug>/)", Kind::String, {}, true},
{"--hash", true, "HASH", ""},
{"--dispositions", true, "DISPOSITIONS", ""},
{"--base", true, "BASE", ""},
{"--date", true, "DATE", ""},
{"--trees", true, "TREES", "the checkout the lenses read, at the range HEAD: the repository itself (`.`, default) or the frozen worktree"},
{"--context-paths", true, "CONTEXT_PATHS", "comma-separated paths of material the artifact discusses (captures, evidence) - mechanical pointers, no narrative"},
{"--only", true, "ONLY", "comma-separated lens files (test only)"},
{"--without", true, "WITHOUT", "comma-separated lens files to leave out of this run by owner ruling (logged; the run stays a full run)"},
{"--units", true, "UNITS", "comma-separated unit ids (test only)"},
{"--warm", false, "", "test runs only: let one pass per prompt prefix go first, as a full run does"},
{"--concurrency", true, "CONCURRENCY",
"lens processes in flight at once across all seats (default 128, 2026-10-15; the pool still places each one by seat headroom, launches a pass only when it fits in free "
"memory at its environment's measured cost, and gives a pass with the browser a stack of its own)",
Kind::Int},
{"--effort", true, "EFFORT", effort},
{"--reads", true, "READS", reads, Kind::Int},
{"--no-reuse", false, "", ""},
{"--no-salvage", false, "", "do not reuse finished process outputs of an earlier run on this hash"},
{"--dry-run", false, "", ""},
{"--claude-bin", true, "CLAUDE_BIN", ""},
{"--models", true, "MODELS", models},
{"--scratch", true, "SCRATCH", ""},
{"--seats", true, "SEATS", "the seats the lenses run on: auto (every Anthropic seat in the env file, else local), local, api, oauth, openrouter (never in auto), or a list like api1,1,2,local"},
{"--env-file", true, "ENV_FILE", "dotenv file with CLAUDE_CODE_OAUTH_TOKEN1..6 / ANTHROPIC_API_KEY1..6 (default $SEATS_ENV_FILE, else the repository .env)"},
{"--no-probe", false, "", "skip the one-request probe of every seat at the start"},
{"--api-budget", true, "API_BUDGET", "USD an API-credit seat may spend per cycle (default REVIEW_GATES_API_BUDGET_USD or 200)", Kind::Float},
{"--harness", true, "{claude,opencode}",
"the agent harness of every lens process: claude (default) or opencode (OpenRouter seats only; no lens whose environment needs an MCP server)", Kind::String, Harnesses},
{"--variant", true, "VARIANT", variant},
{"--opencode-bin", true, "OPENCODE_BIN", ""},
};
return specs;
}
std::int32_t RunCommand(std::span<const std::string_view> args, const std::optional<std::string>& configPath) {
constexpr std::string_view Prog = "crafter-review run";
const std::vector<OptionSpec>& specs = RunOptions();
const Parsed parsed = ParseOptions(args, specs);
if (parsed.help) {
std::print("{}", Help(Prog, "one claude process per inventory unit per lens, the gates, the dump (process/prepush.md)", specs));
return 0;
}
if (!parsed.error.empty()) return UsageError(UsageLine(Prog, specs), Prog, parsed.error);
const std::optional<Json> config = LoadConfig(configPath, false);
if (!config) return 3;
Run::Arguments a;
a.config = configPath;
a.mode = parsed.Value("mode").value_or("commits");
a.artifact = parsed.Value("artifact").value_or("");
a.hash = parsed.Value("hash");
a.dispositions = parsed.Value("dispositions");
a.base = parsed.Value("base").value_or("");
a.date = parsed.Value("date").value_or(Platform::TodayIso());
a.trees = parsed.Value("trees");
a.contextPaths = parsed.Value("context-paths").value_or("");
a.only = parsed.Value("only");
a.without = parsed.Value("without");
if (const std::optional<std::string> units = parsed.Value("units"); units && !units->empty()) {
// A trailing comma names no unit.
a.units = std::set<std::string>();
for (const std::string& part : Dyn::Split(*units, ",")) {
if (std::string id = Dyn::Strip(part); !id.empty()) a.units->insert(std::move(id));
}
}
a.warm = parsed.Flag("warm");
if (const std::optional<std::string> n = parsed.Value("concurrency")) a.concurrency = *Dyn::ParseInt(*n);
a.effort = parsed.Value("effort").value_or("");
if (a.effort.empty()) a.effort = std::string(Plan::DefaultEffort());
a.noReuse = parsed.Flag("no-reuse");
a.noSalvage = parsed.Flag("no-salvage");
a.dryRun = parsed.Flag("dry-run");
a.claudeBin = parsed.Value("claude-bin");
a.models = parsed.Value("models").value_or("");
a.scratch = parsed.Value("scratch");
a.seats = parsed.Value("seats");
if (!a.seats) a.seats = Platform::GetEnv("REVIEW_GATES_SEATS");
a.envFile = parsed.Value("env-file");
a.noProbe = parsed.Flag("no-probe");
if (const std::optional<std::string> budget = parsed.Value("api-budget")) a.apiBudget = *Dyn::ParseFloat(*budget);
a.harness = parsed.Value("harness").value_or("claude");
a.variant = parsed.Value("variant");
if (!a.variant || a.variant->empty()) a.variant = a.harness == "opencode" ? std::optional<std::string>(std::string(OpenCode::DefaultVariant)) : std::nullopt;
a.opencodeBin = parsed.Value("opencode-bin");
if (const std::optional<std::string> reads = parsed.Value("reads")) {
const std::int64_t n = *Dyn::ParseInt(*reads);
if (n < 1) return Die("--reads: a number from 1 up");
a.reads = n;
}
for (const std::string& part : Dyn::Split(a.models, ",")) {
const std::string kv = Dyn::Strip(part);
if (kv.empty()) continue;
const std::size_t equals = kv.find('=');
if (equals == std::string::npos) throw Dyn::Error("ValueError", "not enough values to unpack (expected 2, got 1)");
const std::string key = kv.substr(0, equals);
std::vector<Plan::ModelTier>& tiers = Plan::Models();
const auto tier = std::ranges::find_if(tiers, [&](const Plan::ModelTier& m) { return m.tier == key; });
if (tier == tiers.end()) {
std::vector<std::string> known;
for (const Plan::ModelTier& m : tiers) known.push_back(m.tier);
std::println(std::cerr, "--models: unknown key {} (known: {})", Dyn::Repr(key), Dyn::Join(known, ", "));
return 1;
}
tier->id = kv.substr(equals + 1);
}
return Run::Main(std::move(a), *config);
}
constexpr std::array<OptionSpec, 1> SlotsOptions = {{
{"--artifact", true, "ARTIFACT", "a frozen artifact dir: no more slots than its browser passes can use at once"},
}};
std::int32_t SlotsCommand(std::span<const std::string_view> args, const std::optional<std::string>& configPath) {
constexpr std::string_view Prog = "crafter-review slots";
const Parsed parsed = ParseOptions(args, SlotsOptions);
if (parsed.help) {
std::print("{}", Help(Prog, "how many stacks (slots.*) fit in free memory, and the commands that bring up the missing ones", SlotsOptions));
return 0;
}
if (!parsed.error.empty()) return UsageError(UsageLine(Prog, SlotsOptions), Prog, parsed.error);
const std::optional<Json> config = LoadConfig(configPath);
if (!config) return 3;
const std::optional<std::string> artifact = parsed.Value("artifact");
try {
Run::SlotsPlan(*config, fs::current_path(), artifact ? std::optional<fs::path>(*artifact) : std::nullopt);
} catch (const Inventory::InvariantError& e) {
return Die(e.what());
}
return 0;
}
std::int32_t FreezeCommand(std::span<const std::string_view> args, const std::optional<std::string>& configPath) {
constexpr std::string_view Prog = "crafter-review freeze";
const Parsed parsed = ParseOptions(args, FreezeOptions);
@ -215,6 +407,10 @@ inventory unit, against a frozen commit range.)";
// command anyone types.
if (!rest.empty() && rest.front() == Process::SuperviseVerb) return Process::SuperviseMain(rest.subspan(1));
Platform::Init();
// Before any other thread: SIGINT, SIGTERM and SIGHUP go to a thread of
// their own, which stops a run once it is under way and otherwise ends
// the process.
Process::InstallSignalThread(Run::OnSignal);
// The options before the command: --config FILE or --config=FILE, and
// any unique prefix of a long option.
std::optional<std::string> configPath;
@ -259,6 +455,8 @@ inventory unit, against a frozen commit range.)";
return Config::Main(fs::current_path(), configPath ? fs::path(*configPath) : fs::path());
}
if (command == "freeze") return FreezeCommand(after, configPath);
if (command == "run") return RunCommand(after, configPath);
if (command == "slots") return SlotsCommand(after, configPath);
} catch (const Dyn::Error& error) {
// An error no command catches: its message, exit 1.
std::println(std::cerr, "crafter-review: {}: {}", error.Kind(), error.what());

2171
implementations/Crafter.Review-Run.cpp Normal file
View file

File diff suppressed because it is too large Load diff

4
implementations/Crafter.Review-SeatPool.cpp
View file

@ -319,6 +319,10 @@ namespace Crafter::Review::SeatPool {
return data;
}
const fs::path& Ledger::Path() const {
return path;
}
// ---- the seats ---------------------------------------------------------------------
Json NewSeat(const std::string& id, const std::string& kind, const std::string& secret) {
return {