Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
30.1 KB
Raw Blame
//! Subagent spawning: the isolated one-level-deep child Agent runner
//! (`execSubagent`/`runSub`), the workflow/judge task wrappers
//! (`workflowTask`/`judgeTask`), the --json GUI event bridge (`guiEmit`), and
//! the ultracode/DGM variant-scoring judge (`variantJudgePrompt`/
//! `scoreVariants`). Split out of main.zig (600-line goal). Sibling-imports
//! tools.zig for `ToolCtx`/`ToolOutput`/`failure`; back-imports main (as
//! `main_mod`) for `Agent` (whose `runTurn`/`systemPrompt` are pub-flipped for
//! this cross-module call), `parseEvalScore`, `utf8Prefix`, `json_mode`,
//! `g_out`/`g_gui_mu` (guiEmit serializes --json stdout), and `g_fleet`.

const std = @import("std");
const Io = std.Io;
const Value = std.json.Value;
const Allocator = std.mem.Allocator;

const main_mod = @import("main.zig");
const agent_mod = @import("agent.zig");
const util = @import("util.zig");
const repl_glue = @import("repl_glue.zig");
const Agent = agent_mod.Agent;
const Provider = @import("provider.zig").Provider;

const tools = @import("tools.zig");
const ToolCtx = tools.ToolCtx;
const ToolOutput = tools.ToolOutput;
const failure = tools.failure;

const telemetry = @import("telemetry.zig");
const scoring = @import("scoring.zig");
const promptFingerprint = scoring.promptFingerprint;
const providerClass = scoring.providerClass;
const signScore = scoring.signScore;
const fleet = @import("fleet.zig");
const learning_privacy = @import("learning_privacy.zig");
const agentTypePrompt = fleet.agentTypePrompt;
const Isolation = fleet.Isolation;
const jobs = @import("jobs.zig"); // #276 P0-1: agentWorktreeCreate/agentWorktreeFinish/isolationFailureText
const ledger = @import("subagent_ledger.zig"); // #753: handles survive an interrupted parent turn
const run_budget = @import("run_budget.zig"); // #276 P0-3: default_max_concurrency, reused as the background-agent cap's default value
const cards = @import("cards.zig");
const trace = @import("trace.zig");
const messages_mod = @import("messages.zig");
const textMessage = messages_mod.textMessage;
const brief_diversity = @import("brief_diversity.zig"); // genomeSha: the distinct-genome tournament gate
const orch_rows = @import("orchestration_rows.zig"); // #290: a scored tournament is not variant-free

/// Spawn a one-level-deep subagent: fresh arena, fresh history, same shared
/// http client and provider. Runs entirely on this pool thread; its own tool
/// calls fan out further via io.async. `run_in_background:true` (#276 P0-3)
/// instead registers the spawn and returns immediately — see
/// spawnSubBackground below.
const spawn_gate = @import("subagent_spawn.zig");

pub fn execSubagent(ctx: ToolCtx, input: Value) !ToolOutput {
    const obj = tools.json_args.object(input) orelse return .{ .text = try ctx.gpa.dupe(u8, "subagent: arguments must be a JSON object with a \"prompt\" string"), .is_error = true };
    const label = tools.json_args.str(obj, "description") orelse "subagent";
    const briefed = @import("subagent_brief.zig").fromInput(ctx.gpa, obj);
    defer @import("subagent_brief.zig").release(ctx.gpa, briefed);
    const prompt = briefed.text;
    if (prompt.len == 0) return .{ .text = try ctx.gpa.dupe(u8, "subagent: missing required \"prompt\" (a self-contained task)"), .is_error = true };
    if (spawn_gate.refuse(ctx.from_sub, label, prompt, g_agent_jobs.active)) |why|
        return .{ .text = try ctx.gpa.dupe(u8, why), .is_error = true };
    const sys_override = fleet.resolveOverride(obj);
    const niche = fleet.resolveNiche(obj);
    const isolation = fleet.resolveIsolation(obj);
    const isolation_fallback = fleet.resolveIsolationFallback(obj);
    // #292: explicit spawn `model`/`tier` > persona frontmatter > the session
    // default (--subagent-model / the #291 ladder), resolved provider-locally.
    const base = childProvider(ctx.provider, ctx.subagent_provider, ctx.subagent_cross_provider);
    // #372: adhoc cell uses the same role vocabulary as a workflow phase.
    const cell: route_policy.Cell = .{ .role = route_policy.roleOf(label, niche) };
    // #380: vision-aware seat + honesty flag (this file is at the cap).
    const ask = vision_ask.seat(ctx, base, obj, cell, label, prompt, sys_override, niche);
    if (ask.pin.effort_outcome == .unsupported_effort) return .{ .text = try ctx.gpa.dupe(u8, "subagent: Off is unsupported by this model; choose a supported effort"), .is_error = true };
    if (ask.blocked) return .{ .text = try vision_ask.blockMessage(ctx.gpa, ask), .is_error = true };
    // ADR 0232: the child sees the user's request and runs at its parent's effort unless pinned.
    const effort = @import("subagent_fork.zig").effort(ctx.parent_effort, ask.pin.effort, ask.pin.provider orelse base);
    var source_arena = std.heap.ArenaAllocator.init(ctx.gpa);
    defer source_arena.deinit();
    var forked = ctx;
    forked.fork_source = @import("subagent_history.zig").fromInput(ctx, input, source_arena.allocator()) catch |err| return failure(ctx.gpa, err);
    forked.parent_task = try @import("subagent_fork.zig").task(ctx.gpa, ctx.parent_messages);
    defer ctx.gpa.free(forked.parent_task);
    const keep = tools.json_args.flag(input, "retained");
    // Interactive roots default to detached workers, but an explicit false
    // asks for a foreground child that completes within this prompt turn.
    const explicit_foreground = switch (obj.get("run_in_background") orelse .null) {
        .bool => |value| !value,
        else => false,
    };
    if ((ctx.interactive_children and !explicit_foreground) or tools.json_args.flag(input, "run_in_background")) {
        var child = forked;
        if (keep) child.retained_worker = try @import("subagent_retained.zig").create(ctx, label);
        errdefer if (keep) child.retained_worker.?.deinit(ctx.gpa, ctx.io);
        return spawnSubBackground(child, label, prompt, sys_override, niche, isolation, isolation_fallback, ask.pin.provider, effort, ask);
    }
    const run = if (keep)
        try @import("subagent_resume.zig").foreground(forked, label, prompt, sys_override, niche, isolation, isolation_fallback, ask.pin.provider, effort)
    else
        try runSub(forked, "subagent", label, prompt, sys_override, niche, isolation, isolation_fallback, ask.pin.provider, effort);
    return vision_ask.flagReport(ctx.gpa, run.output, ask);
}

const subagent_run = @import("subagent_run.zig");
const vision_ask = @import("vision_ask.zig"); // #380 vision-aware seat (wraps #292's subagent_pin) + the report honesty flag
pub const AgentUsage = subagent_run.AgentUsage;
pub const SubRun = subagent_run.SubRun;
pub const runSub = subagent_run.runSub;
const childProvider = subagent_run.childProvider;
const route_phase = @import("route_phase.zig"); // #376 one learned seat per phase
const shapes = @import("shapes.zig");
const route_policy = @import("route_policy.zig"); // #372 (shape, role) policy cells
const route_trace = @import("route_trace.zig"); // #372 per-worker routing trace
const FailKind = subagent_run.FailKind;
const classifyFailure = subagent_run.classifyFailure;

// ── Async, fire-and-forget background subagents (#276 P0-3) ────────────────
// Extends jobs.zig's background-bash-job pattern (Job/g_jobs/spawnJob/
// jobOutput/jobKill — stable incrementing ids, a session-global mutex-guarded
// registry, non-blocking spawn) to subagent spawns: `run_in_background:true`
// on `subagent` returns a stable agent id immediately (spawnSubBackground);
// the child runs on io.concurrent, never io.async — io.async may run inline
// and block the spawning call forever on a long-lived child, same reason
// spawnJob avoids it for bash. Completion is polled non-destructively via the
// `agent_output` tool (agentOutput), mirroring bash_output's id/wait_ms shape
// and 30s wait cap — except a subagent's report is a one-shot value, not a
// stream, so a completed fetch replays the FULL result (design point 4).

/// Concurrency ceiling on background subagents actually RUNNING (i.e. past
/// admission, inside their own runSub call) at once. Deliberately a counter
/// of its own, not a reuse of RunBudget.active/acquireConcurrency: a
/// background job's admission slot would otherwise have to stay held for its
/// entire — possibly minutes-long — lifetime, while its OWN internal turns
/// separately acquire per-model-call permits from that very same pool; once
/// enough jobs queued up, every held outer slot would starve the inner acquires
/// each job needs to ever finish and release it — a deadlock. Same admission
/// SHAPE as RunBudget.acquireConcurrency (spin-wait, no failure on saturation)
/// and the same default value, but an independent resource.
pub const max_concurrent_background_agents: u32 = run_budget.default_max_concurrency;

/// One background subagent spawn: the runSub arguments (gpa-owned copies —
/// the caller's ToolCtx.arena-backed strings do not outlive this tool call's
/// return, the whole point of fire-and-forget) plus its outcome once done.
/// `admitted` is false while queued behind max_concurrent_background_agents;
/// jobs.zig's Job mirrors this shape (id/cmd there ~ id/label+prompt here).
pub const AgentJob = struct {
    id: u32,
    label: []u8,
    prompt: []u8,
    sys_override: ?[]u8 = null,
    niche: []u8,
    isolation: Isolation,
    isolation_fallback: bool,
    /// #292: resolved per-spawn model pin. Needs no gpa copy, unlike
    /// label/prompt: a Provider's strings come from the spec table, the model
    /// catalog and the credential store, never from this tool call's arena.
    pin: ?Provider = null,
    /// #292 follow-up: resolved per-spawn/per-persona effort pin — an enum by
    /// value, no lifetime to manage.
    effort: ?main_mod.ReasoningEffort = null,
    /// #380: the vision decision, rebased onto the gpa-owned prompt, so a
    /// backgrounded report earns the same honesty flag a foreground one does.
    ask: vision_ask.Ask = .{},
    ctx: ToolCtx,
    owned: ?*@import("subagent_owned.zig").Owned = null,
    owner: ?[]const u8 = null,
    notified: bool = false,
    admitted: bool = false,
    done: bool = false,
    feedback: @import("subagent_feedback.zig").Inbox = .{},
    is_error: bool = false,
    result: []u8 = &.{}, // gpa-owned once done
    usage: AgentUsage = .{},
    future: Io.Future(void) = undefined, // pump; awaited only by agentJobsReap
};

pub const AgentJobs = struct {
    mutex: Io.Mutex = .init,
    list: std.ArrayList(*AgentJob) = .empty,
    active: u32 = 0, // admitted and not yet done
    next_id: u32 = 1,

    pub fn find(self: *AgentJobs, id: u32) ?*AgentJob {
        for (self.list.items) |j| if (j.id == id) return j;
        return null;
    }
};

pub var g_agent_jobs: AgentJobs = .{};

/// Pure admission step: pop the oldest not-yet-admitted job and mark it
/// admitted (bumping `active`), or return null when the cap is full or
/// nothing is queued. No Io — callers hold AgentJobs.mutex around it; kept
/// separate so the queue-not-fail contract (design point 6) is unit-testable
/// without a real Io/thread pool.
pub fn admitOneLocked(registry: *AgentJobs) ?*AgentJob {
    if (registry.active >= max_concurrent_background_agents) return null;
    for (registry.list.items) |j| {
        if (!j.admitted) {
            j.admitted = true;
            registry.active += 1;
            return j;
        }
    }
    return null;
}

/// Drain admittable jobs, launching each via io.concurrent. Called right
/// after a spawn (start immediately if there's room) and at the end of
/// every job's pump (drain the next queued one) — a small self-perpetuating
/// worker chain, no separate ticker task needed. Never called with the
/// mutex held.
pub fn admitNext(gpa: Allocator, io: Io) void {
    while (true) {
        g_agent_jobs.mutex.lockUncancelable(io);
        const job = admitOneLocked(&g_agent_jobs);
        g_agent_jobs.mutex.unlock(io);
        const j = job orelse return;
        j.future = io.concurrent(agentJobPump, .{ j, gpa, io }) catch {
            // Pool has no spare concurrency right now — un-admit and stop;
            // the next spawn or completion retries (#276 P0-3 design point
            // 6: queue rather than fail — never surfaced to the model).
            g_agent_jobs.mutex.lockUncancelable(io);
            j.admitted = false;
            g_agent_jobs.active -= 1;
            g_agent_jobs.mutex.unlock(io);
            return;
        };
    }
}

/// The background pump: runs the child to completion off the calling turn,
/// records the structured completion (status/result/usage — never silent,
/// even on failure), then drains the next queued spawn. Mirrors jobPump's
/// shape in jobs.zig.
pub fn agentJobPump(job: *AgentJob, gpa: Allocator, io: Io) void {
    const t0: Io.Timestamp = .now(io, .awake);
    var ctx = job.ctx;
    ctx.subagent_feedback = &job.feedback;
    var run = runSub(ctx, "subagent", job.label, job.prompt, job.sys_override, job.niche, job.isolation, job.isolation_fallback, job.pin, job.effort) catch |err| SubRun{
        .output = @import("subagent_run.zig").startFailure(gpa, err),
        .usage = .{ .duration_ms = @intCast(@max(0, t0.untilNow(io, .awake).toMilliseconds())) },
    };
    const undelivered = job.feedback.close(io);
    if (undelivered > 0) {
        if (std.fmt.allocPrint(gpa, "{s}\n\n[{d} queued feedback message(s) were not delivered before the agent stopped.]", .{ run.output.text, undelivered })) |text| {
            gpa.free(run.output.text);
            run.output.text = text;
        } else |_| {}
        run.output.is_error = true;
    }
    g_agent_jobs.mutex.lockUncancelable(io);
    job.result = vision_ask.flagText(gpa, run.output.text, job.ask); // #380 honesty flag
    job.is_error = run.output.is_error;
    job.usage = run.usage;
    job.done = true;
    const retained_state = job.ctx.retained_worker;
    job.ctx.retained_worker = null; // completed jobs retain reports, not full conversation arenas
    job.ctx.fork_source = null;
    g_agent_jobs.active -= 1;
    g_agent_jobs.mutex.unlock(io);
    if (retained_state) |state| state.deinit(gpa, io);
    if (job.owned) |owned| owned.releaseHistory();
    ledger.finish(gpa, io, job.id, job.is_error, job.result, job.usage);
    admitNext(gpa, io);
}

/// `run_in_background:true` path for `subagent` (execSubagent): register the
/// job and return immediately with its id; the child runs on the pool.
/// Never blocks on a free concurrency slot — a spawn beyond the cap is
/// queued, not failed; admitNext drains it once room frees up.
pub const spawnSubBackground = @import("subagent_spawn_job.zig").spawnSubBackground;

/// Programmatic fire-and-forget spawn for harness-internal reporters (the
/// codedbpro failure → issue filer): no tool-call input to parse, no persona,
/// no pin — the session-default seat in the shared cwd. execSubagent stays
/// the model-facing path; this never surfaces a ToolOutput to anyone.
pub fn spawnBackground(ctx: ToolCtx, label: []const u8, prompt: []const u8) !void {
    _ = try spawnSubBackground(ctx, label, prompt, null, "", .shared_cwd, false, null, null, vision_ask.forPrompt(prompt));
}

/// Pure formatting for agent_output's status line: the "structured
/// completion event" shape (#276 P0-3 design point 3) — running / completed
/// / failed, plus the usage summary, plus the full result once done.
/// Factored out of agentOutput so it's unit-testable without a real Io.
/// pub only so subagent_tests.zig can reach it (this file is at the cap).
pub fn agentStatusText(gpa: Allocator, id: u32, done: bool, is_error: bool, usage: AgentUsage, result: []const u8) ![]u8 {
    if (!done) return std.fmt.allocPrint(gpa, "[agent {d}: running]", .{id});
    return std.fmt.allocPrint(
        gpa,
        "[agent {d}: {s} in {d}ms · {d} tool call(s) · ~{d} context token(s) · {d} cache-read token(s)]\n\n{s}",
        .{ id, if (is_error) "failed" else "completed", usage.duration_ms, usage.tool_calls, usage.context_tokens, usage.cache_read_tokens, result },
    );
}

/// Same wait policy as bash_output (ADR 0010 / #640): 0 = snapshot, any
/// >0 waits for exit (10h). Inlined so this file stays at the line cap.
const agent_wait_cap_ms: u64 = 36_000_000;

/// agent_output: fetch a background subagent's status/result. Non-
/// destructive — a completed fetch always replays the full result (unlike
/// bash_output's cursor, a subagent's report is one-shot, not a stream).
/// wait_ms > 0 blocks until the agent finishes (or Esc), not every 30s.
pub fn agentOutput(gpa: Allocator, io: Io, id: u32, wait_ms: u64) !ToolOutput {
    const deadline: u64 = if (wait_ms == 0) 0 else agent_wait_cap_ms;
    var waited: u64 = 0;
    while (true) {
        g_agent_jobs.mutex.lockUncancelable(io);
        const job = g_agent_jobs.find(id) orelse {
            g_agent_jobs.mutex.unlock(io);
            return ledger.missing(gpa, io, id);
        };
        if (job.done or waited >= deadline) {
            const text = try agentStatusText(gpa, id, job.done, job.is_error, job.usage, job.result);
            const is_err = job.done and job.is_error;
            if (job.done) job.notified = true;
            g_agent_jobs.mutex.unlock(io);
            return .{ .text = text, .is_error = is_err };
        }
        g_agent_jobs.mutex.unlock(io);
        if (Agent.esc_cancel.load(.acquire)) {
            waited = deadline; // render current state on the next pass
            continue;
        }
        io.sleep(.fromMilliseconds(100), .awake) catch {
            waited = deadline;
            continue;
        };
        waited += 100;
    }
}

/// Session end: let every still-running background agent finish naturally —
/// unlike a bash child process (jobs.zig's jobsReap, which flags
/// kill_requested and the pump kills the child within ~200ms), there is no
/// cheap way to abort an in-flight agent turn mid-request, so this mirrors
/// jobsReap's SHAPE (drain the registry, await every pump, free everything
/// before the process exits) but not its KILL semantics — see this feature's
/// commit body for the full rationale. A job still queued (never admitted)
/// at shutdown never started, so it's simply dropped: nothing ran, nothing
/// to lose.
pub fn agentJobsReap(gpa: Allocator, io: Io) void {
    ledger.markRunningInterrupted(io);
    g_agent_jobs.mutex.lockUncancelable(io);
    const list = g_agent_jobs.list.toOwnedSlice(gpa) catch {
        g_agent_jobs.mutex.unlock(io);
        return;
    };
    g_agent_jobs.mutex.unlock(io);
    for (list) |job| {
        if (job.admitted) job.future.await(io);
        job.feedback.deinit(gpa);
        if (job.ctx.retained_worker) |state| state.deinit(gpa, io);
        if (job.owned) |owned| {
            owned.deinit();
            gpa.destroy(owned);
        }
        gpa.free(job.label);
        gpa.free(job.prompt);
        if (job.sys_override) |s| gpa.free(s);
        gpa.free(job.niche);
        gpa.free(job.result);
        gpa.destroy(job);
    }
    gpa.free(list);
}

/// One task inside a workflow phase; never throws, suitable for io.async.
/// `niche` is the task's MAP-Elites cell, threaded through so runSub's
/// fleet:propose — and scoreVariants' submit — tag the variant's genome.
pub fn workflowTask(ctx: ToolCtx, label: []const u8, prompt: []const u8, sys_override: ?[]const u8, niche: []const u8, isolation: Isolation, isolation_fallback: bool, seat: ?Provider) ToolOutput {
    // `seat` is the PHASE's one model (route_phase.forPhase, resolved once and
    // handed to every task alike), never a per-task pin: the variants still
    // share one configuration (#290). The effort axis stays unpinned.
    const run = runWorkflow(ctx, "workflow_task", label, prompt, sys_override, niche, isolation, isolation_fallback, seat) catch |err| return failure(ctx.gpa, err);
    return run.output;
}

/// A second workflow attempt has its own explicit budget kind. It still shares
/// the same invocation-wide atomic ceiling and concurrency limiter.
pub fn workflowRetryTask(ctx: ToolCtx, label: []const u8, prompt: []const u8, sys_override: ?[]const u8, niche: []const u8, isolation: Isolation, isolation_fallback: bool, seat: ?Provider) ToolOutput {
    // The SAME phase seat: a retry that changed model would break uniformity.
    const run = runWorkflow(ctx, "workflow_retry", label, prompt, sys_override, niche, isolation, isolation_fallback, seat) catch |err| return failure(ctx.gpa, err);
    return run.output;
}

pub fn runWorkflow(ctx: ToolCtx, kind: []const u8, label: []const u8, prompt: []const u8, system: ?[]const u8, niche: []const u8, isolation: Isolation, fallback: bool, seat: ?Provider) !SubRun {
    if (ctx.retain_children) return @import("subagent_resume.zig").foregroundKind(ctx, kind, label, prompt, system, niche, isolation, fallback, seat, null);
    return runSub(ctx, kind, label, prompt, system, niche, isolation, fallback, seat, null);
}

/// The --judge LLM-as-judge run (see runEval in main): an isolated subagent
/// scores the work against the rubric and ends with a `score:` line. Mirrors
/// workflowTask — a thin runSub wrapper — so the eval handler can io.async it
/// on a pool thread. Never worktree-isolated: a judge only reads/reasons over
/// text handed to it, never the filesystem, so there's nothing to isolate.
pub fn judgeTask(ctx: ToolCtx, prompt: []const u8) ToolOutput {
    const run = runSub(ctx, "judge_task", "judge", prompt, null, "", .shared_cwd, false, null, null) catch |err| return failure(ctx.gpa, err);
    return run.output;
}

/// Build the judge prompt that scores one workflow variant's output against its
/// task on a 0-100 scale (see scoreVariants). Bounded: the task spec and output
/// tail are truncated so a fat phase can't blow up the judge's context.
/// pub only so subagent_tests.zig can reach it (this file is at the cap).
pub fn variantJudgePrompt(arena: Allocator, title: []const u8, task: []const u8, output: []const u8) ![]const u8 {
    const spec = util.utf8Prefix(task, 1200);
    const work = if (output.len > 2000) output[output.len - 2000 ..] else output;
    return std.fmt.allocPrint(arena,
        \\An agent variant ran the task below as part of the "{s}" phase of a workflow.
        \\Judge how well its OUTPUT accomplishes the TASK, on a 0-100 scale. Be
        \\discriminating: reward correctness, completeness, and usefulness; penalize
        \\hand-waving, non-answers, and ignored requirements. Do not reward length.
        \\
        \\TASK:
        \\{s}
        \\
        \\VARIANT OUTPUT:
        \\{s}
        \\
        \\Inspect any files the work references if you need to, then end your reply
        \\with a single final line `score: <N>` where N is an integer from 0 to 100.
    , .{ title, spec, work });
}

/// Task-array bound shared with workflow.zig's execWorkflow (phase task caps
/// and the fixed-size scratch arrays both use it) — the single source of truth
/// lives here since scoreVariants (below) needs it too.
pub const max_workflow_tasks = 8;

/// #1 — Score this phase's persona variants and submit niche-tagged fitness to
/// the fleet, turning every ultracode tournament into a DGM scoring round. Each
/// surviving variant task is judged 0-100 against its task; the score is signed
/// and submitted under the task's niche so a MAP-Elites cell accrues real fitness
/// and the promote pass can crown a winner. Mirrors runEval's submit but with a
/// NON-EMPTY niche — the gap that previously forced bootstrap seeding.
/// Best-effort and gated: no judge runs unless ≥2 variants competed and the
/// fleet (telemetry) is on, so ordinary fan-outs pay nothing. `seat` (#376) is
/// this phase's shape/title/model — the configuration every variant shared.
pub fn scoreVariants(
    ctx: ToolCtx,
    arena: Allocator,
    seat: route_phase.Seat,
    prompts: [][]const u8,
    raws: [][]const u8,
    overrides: []?[]const u8,
    niches: [][]const u8,
    outputs: []ToolOutput,
) void {
    if (!main_mod.g_fleet) return;
    // #372: the local (shape, role, tier, model) capture below runs with
    // telemetry OFF too, so a private session still accrues policy evidence.
    if (telemetry.g_telem == null and trace.g_traj == null) return;

    // Variant tasks that produced a usable result; a tournament needs ≥2 with
    // DISTINCT genomes. Counting `override != null` counted PRESENCE, and a
    // phase where every worker carries the same resolved system_prompt is one
    // genome run N times — nothing to rank. The study paid for that twice: two
    // single-genome phases each spawned three judges to score a tournament
    // that had exactly one entrant, on a run that then died at the cap.
    var vidx: [max_workflow_tasks]usize = undefined;
    var vn: usize = 0;
    for (overrides, outputs, 0..) |o, out, i| {
        if (o != null and !out.is_error) {
            vidx[vn] = i;
            vn += 1;
        }
    }
    if (vn < 2) return;
    var distinct = false;
    for (1..vn) |k| if (brief_diversity.genomeSha(overrides[vidx[k]].?) != brief_diversity.genomeSha(overrides[vidx[0]].?)) {
        distinct = true;
    };
    if (!distinct) {
        if (ctx.tracer) |tr| tr.note("fleet", "tournament skipped: one genome, no axis to rank");
        return;
    }
    // Any score filed below attributes to the PROMPT, not to the orchestration
    // rung, so this run's orch_outcome row is no longer variant-free (#290).
    orch_rows.notePendingVariants();

    // A tournament must vary exactly ONE axis: variants that did not all run on
    // the same MODEL rank the model as much as the prompt, and filing that under
    // the prompt fingerprint writes model effects into the genome archive (#290).
    // #376 tightened the key from the capability class — which pools distinct
    // models under one label (sol and bare gpt-5.6 are both "frontier") — to
    // the resolved model, catching a rung-only difference too. Bail before a
    // judge: unscoreable round.
    for (1..vn) |k| {
        if (!std.mem.eql(u8, subagent_run.variantStratum(seat.provider, vidx[0]), subagent_run.variantStratum(seat.provider, vidx[k]))) {
            if (ctx.tracer) |tr| tr.note("fleet", "tournament skipped: variants span routing strata");
            return;
        }
    }

    // All fallible work (prompt builds) before any future spawns, so an early
    // return can never abandon a running judge.
    const jprompts = arena.alloc([]const u8, vn) catch return;
    for (jprompts, 0..) |*jp, k| {
        const i = vidx[k];
        jp.* = variantJudgePrompt(arena, seat.title, prompts[i], outputs[i].text) catch return;
    }
    const jfuts = arena.alloc(Io.Future(ToolOutput), vn) catch return;
    for (jfuts, jprompts) |*jf, jp| jf.* = ctx.io.async(judgeTask, .{ ctx, jp });

    const run_id: []const u8 = &scoring.g_run_id;
    // This phase's MAP-Elites slot (#290/#293); "" off-vocabulary. See telemetrySlot.
    const slot = scoring.telemetrySlot(shapes.canonicalSlot(seat.title));
    for (jfuts, 0..) |*jf, k| {
        const i = vidx[k];
        const jout = jf.await(ctx.io);
        defer ctx.gpa.free(jout.text);
        if (jout.is_error) continue;
        const s = repl_glue.parseEvalScore(jout.text) orelse continue;
        if (s <= 0) continue; // skip the total-failure 0 (don't pollute the cell mean), mirroring runEval
        if (s > 100) {
            // Review F8: parseEvalScore does NOT return 0-100 by construction
            // (a stray "score: 9000" line parses as 9000) — guard to [0,100]
            // here, mirroring mainloop /score's explicit rejection. Skip the
            // score AND its paired propose/submit so no s01 > 1 row is ever
            // signed and the submit counter stays in sync with stored scores.
            if (ctx.tracer) |tr| tr.note("fleet", "score skipped: eval score outside [0,100]");
            continue;
        }
        // SCORE SCALE CONTRACT (issue #168 Gap 4): s is guarded to (0,100]
        // above; every score that leaves the client is [0,1], so divide at
        // the emission boundary — s01 is what gets signed and sent.
        const s01 = s / 100.0;
        const pclass = subagent_run.variantProviderClass(seat.provider, i);
        const genome_fp = promptFingerprint(overrides[i].?);
        const esh_fp = promptFingerprint(raws[i]);
        const genome: []const u8 = &genome_fp;
        const esh: []const u8 = &esh_fp;
        // Truncated to 64 chars and sanitized (tab/newline/CR → ' ', review
        // F7) BEFORE signing (fleetEvent's own niche cap, same as mainloop
        // /score and runEval) so signed bytes equal ingested bytes.
        var niche_buf: [64]u8 = undefined;
        const niche = scoring.sanitizeMetaField(&niche_buf, util.utf8Prefix(niches[i], 64));
        const sig = signScore(genome, "", s01, run_id, "", "", esh, niche, pclass);
        const sig_s: []const u8 = if (scoring.g_score_key != null) &sig else "";
        var provbuf: [512]u8 = undefined;
        // Slot (6th) and #376's routing STRATUM (7th) are APPENDED, so a
        // collector indexing 0..4 is unaffected; both stay advisory like the
        // rest of `prov` (signing them needs a collector-first deploy). The
        // stratum is what lets a cross-run comparison of two genomes stay
        // inside one rung instead of averaging over the phase's seat.
        const prov = std.fmt.bufPrint(&provbuf, "{s}\t{s}\t{s}\t{s}\t{s}\t{s}\t{s}", .{ "", "", esh, pclass, niche, slot, subagent_run.variantStratum(seat.provider, i) }) catch "";
        // #372: the policy observation — this cell's (shape, role, tier,
        // model) plus the judged score — filed locally, never on the genome.
        route_trace.captureVariant(seat.provider, seat.shape, seat.title, niche, genome, s01);
        const t = telemetry.g_telem orelse continue;
        // Genome-send (issue #168 Gap 5), mirroring runEval: ride the variant's
        // text over on a propose (deduped by fingerprint server-side) so the
        // scored cell has a servable genome even when runSub never proposed it.
        // Oversized genomes skip the propose (review F6): a truncated genome
        // would fail the server's fingerprint check and be dropped anyway.
        if (niche.len > 0) {
            if (overrides[i].?.len <= telemetry.Telemetry.max_propose_text)
                t.fleetEvent("propose", niche, genome, "", pclass, "", 0, overrides[i].?)
            else if (ctx.tracer) |tr| tr.note("fleet", "propose skipped: genome > 64KB");
        }
        t.scoreEvent(genome, "", s01, run_id, sig_s, prov);
        t.fleetEvent("submit", niche, genome, "", pclass, esh, 0, "");
    }
}