@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/integration.js

@@ -0,0 +1,141 @@
+import { SmithError } from './errors.js';
+import { appendEvent } from './events.js';
+import { runGit as git } from './git.js';
+import { run } from './testgate.js';
+import { integrationBranchName, RESERVED_TASK_ID } from './worktree.js';
+/**
+ * D-42/P9-26, second half. Moving the worktrees outside the project root
+ * (worktree.ts) fixes the tool that went red; it does not fix the reason
+ * nobody noticed for six tasks. Every check this factory runs — schema,
+ * tests, lint, review — runs inside a task worktree, so every quality claim
+ * it makes is a claim about a worktree. The assembled integration branch had
+ * never had one command run against it when the epic was declared shippable.
+ * The run that caught D-42 took eleven seconds and happened because a human
+ * typed it.
+ *
+ * This module is that run, as a logged fact: the full check suite, executed
+ * at the project root while the integration branch is checked out, recorded
+ * as an `integration-check` event that epic.ts's verdict gate then requires.
+ *
+ * It REFUSES rather than acts in the two cases where acting would be worse
+ * than stopping — a project that isn't on the integration branch (checking
+ * it out would be a destructive git op on the operator's own clone) and a
+ * dirty working tree (the checks would certify something that is not the
+ * branch). Both are one operator command away from fixed, and both are
+ * silent corruption of the record if guessed at.
+ */
+export class IntegrationCheckError extends SmithError {
+}
+export const INTEGRATION_CHECK_EVENT = 'integration-check';
+function branchHead(projectDir, branch) {
+    try {
+        return git(projectDir, ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The current head of `smith/<epic>/integration`, or null when the epic has
+ * no integration branch (never planned, never dispatched, wrong --epic).
+ * Read here rather than inside epic.ts so the verdict stays git-free and
+ * purely a fold over events — the CLI passes the sha in.
+ */
+export function integrationHeadSha(projectDir, epicId) {
+    return branchHead(projectDir, integrationBranchName(epicId));
+}
+/** Last-wins fold: the most recent recorded check for this epic, or null. */
+export function latestIntegrationCheck(events, epicId) {
+    let latest = null;
+    for (const event of events) {
+        if (event.record.event_type !== INTEGRATION_CHECK_EVENT)
+            continue;
+        const payload = event.record.payload;
+        if (payload.epic_id !== epicId)
+            continue;
+        latest = {
+            epicId,
+            branch: String(payload.branch ?? ''),
+            headSha: String(payload.head_sha ?? ''),
+            pass: payload.pass === true,
+            results: (payload.results ?? []),
+            eventId: event.event_id,
+            ts: event.record.ts,
+        };
+    }
+    return latest;
+}
+/**
+ * Run the check suite at the project root against the epic's assembled
+ * integration branch and record the outcome as an event.
+ *
+ * A FAILING suite is a recorded failure, not a throw — that is the whole
+ * point of the record. A suite that could not honestly be run at all (no
+ * checks, wrong branch, dirty tree, no branch) throws instead, because the
+ * one thing this must never do is write down a pass that nothing earned.
+ */
+export async function runIntegrationCheck(input, ctx, opts = {}) {
+    const { epicId, projectDir } = input;
+    const branch = integrationBranchName(epicId);
+    // testgate.run([]) returns pass: true for an empty list — correct there
+    // (a task claiming no checks has nothing to short-circuit), and a silent
+    // forgery here. "No checks configured" must never read back as "the
+    // assembled branch passed its checks".
+    if (input.checks.length === 0) {
+        throw new IntegrationCheckError('integration.no-checks', `Refusing to certify epic "${epicId}" with an empty check list: an empty suite would record a pass nothing ran for.`, { epicId, branch });
+    }
+    const headSha = branchHead(projectDir, branch);
+    if (headSha === null) {
+        throw new IntegrationCheckError('integration.branch-missing', `Epic "${epicId}" has no integration branch (${branch}) in ${projectDir} — there is nothing assembled to check.`, { epicId, branch, projectDir });
+    }
+    let currentBranch;
+    try {
+        currentBranch = git(projectDir, ['branch', '--show-current']);
+    }
+    catch (cause) {
+        throw new IntegrationCheckError('integration.not-a-repo', `Could not read the current branch in ${projectDir}: ${String(cause)}`, { projectDir });
+    }
+    // The checks run against the working tree, so the working tree has to BE
+    // the integration branch. Checking it out for the operator would be a
+    // destructive git op on their own clone (guardrails.md) — refuse instead.
+    if (currentBranch !== branch) {
+        throw new IntegrationCheckError('integration.wrong-branch', `${projectDir} is on "${currentBranch || '(detached HEAD)'}", not the integration branch "${branch}". Check it out first — this command will not move your working tree for you.`, { epicId, branch, currentBranch, projectDir });
+    }
+    // `--untracked-files=all` explicitly: the mode is configurable, and a
+    // `status.showUntrackedFiles = no` anywhere in git's config chain made an
+    // untracked-only tree read back as clean — which is exactly the tree someone
+    // forgot to commit, certified under a head it does not match (D-178).
+    const dirty = git(projectDir, ['status', '--porcelain', '--untracked-files=all']);
+    if (dirty) {
+        throw new IntegrationCheckError('integration.dirty-tree', `${projectDir} has uncommitted changes; a check run against a dirty tree certifies something that is not ${branch} at ${headSha.slice(0, 8)}.`, { epicId, branch, projectDir, dirtyEntries: dirty.split('\n').length });
+    }
+    const outcome = await run(input.checks, {
+        cwd: projectDir,
+        runAll: input.runAll ?? true,
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+    });
+    const stored = await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: INTEGRATION_CHECK_EVENT,
+        task_id: `${epicId}/${RESERVED_TASK_ID}`,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: {
+            epic_id: epicId,
+            branch,
+            head_sha: headSha,
+            pass: outcome.pass,
+            results: outcome.results,
+        },
+    }, opts);
+    return {
+        epicId,
+        branch,
+        headSha,
+        pass: outcome.pass,
+        results: outcome.results,
+        eventId: stored.event_id,
+        ts: stored.record.ts,
+    };
+}

package/factory/orchestrator/dist/judgePreflight.js

@@ -0,0 +1,155 @@
+// Does the cross-provider quorum have the providers crosscheck.yml says it
+// has? Every other surface answers that question after the fact: a judge run
+// that failed is a `judge-verdict` row with `ok: false`, and `smith stats
+// providers` aggregates those rows into a rate. Both are readable only once
+// the calls have already been spent.
+//
+// Two failures motivated this, and they are different from each other:
+//
+//   1. A provider that is `enabled: true` with its precondition unmet. The
+//      factory's own deepseek judge shipped `enabled: true` on a machine with
+//      no DEEPSEEK_API_KEY, so every quorum trigger — and gate.ts fires one on
+//      every blocking finding, unprompted — spawned a call that could not
+//      leave the machine, caught it, and wrote a failure row. Nothing was
+//      unsafe: the quorum is fail-closed and the finding stayed blocking. It
+//      was pure latency and a log that reads like a provider outage.
+//
+//   2. A promotion that cannot decide anything. `quorum_rule.min_providers`
+//      is 2, and on a gate finding the native provider is excluded as the
+//      finder, so the gating pool is the ACTIVE EXTERNALS alone. Promote one
+//      provider to `mode: active` and every case still comes back
+//      `insufficient-providers` — the operator has taken on the cost of a
+//      gating provider and bought no gating. docs/runbooks/providers.md §4
+//      states this in prose; until this check existed nothing asserted it.
+//
+// Deliberately not a judge call. A preflight that proves a provider answers
+// by asking it a question costs what it is trying to save, and would turn a
+// config check into a network dependency. This asks only what can be known
+// locally: is the key set, is the binary on PATH, and does the arithmetic of
+// the promotions add up.
+import { readFileSync } from 'node:fs';
+import { parseCrosscheckPolicy } from './crosscheck.js';
+import { CROSSCHECK_POLICY_PATH } from './paths.js';
+import { apiKeyPresent, commandOnPath } from './preconditions.js';
+function inspect(config) {
+    if (config.kind === 'native') {
+        return {
+            provider: config.name,
+            kind: 'native',
+            transport: 'native',
+            enabled: config.enabled,
+            mode: 'native',
+            precondition: null,
+            status: 'ok',
+            detail: 'In-process. Nothing to configure and nothing to dial.',
+        };
+    }
+    const base = {
+        provider: config.name,
+        kind: config.kind,
+        enabled: config.enabled,
+        mode: config.mode,
+    };
+    if (config.transport === 'api') {
+        const set = apiKeyPresent(config.apiKeyEnv);
+        if (!config.enabled) {
+            return {
+                ...base,
+                transport: 'api',
+                precondition: config.apiKeyEnv,
+                status: 'not-applicable',
+                detail: config.enabledSource === 'auto'
+                    ? `enabled: auto, and ${config.apiKeyEnv} is unset here, so this box does not use it. Set the key to switch it on; nothing to edit.`
+                    : `Disabled in the policy, so ${config.apiKeyEnv} is not read.`,
+            };
+        }
+        return {
+            ...base,
+            transport: 'api',
+            precondition: config.apiKeyEnv,
+            status: set ? 'ok' : 'unmet',
+            detail: set
+                ? `${config.apiKeyEnv} is set.`
+                : `${config.apiKeyEnv} is unset or empty. Every quorum trigger will spend a call that cannot be sent, and record it as provider.missing-api-key.`,
+        };
+    }
+    const resolvable = commandOnPath(config.command);
+    if (!config.enabled) {
+        return {
+            ...base,
+            transport: 'cli',
+            precondition: config.command,
+            status: 'not-applicable',
+            detail: config.enabledSource === 'auto'
+                ? `enabled: auto, and ${config.command} is not on PATH here, so this box does not use it. Install it to switch it on; nothing to edit.`
+                : `Disabled in the policy, so ${config.command} is never spawned.`,
+        };
+    }
+    return {
+        ...base,
+        transport: 'cli',
+        precondition: config.command,
+        status: resolvable ? 'ok' : 'unmet',
+        detail: resolvable
+            ? `${config.command} is executable on PATH. Whether it is authenticated is not knowable without spending a call — run "smith judge run --provider ${config.name}" to find out.`
+            : `${config.command} is not executable on PATH. Every quorum trigger will spend a call that cannot start.`,
+    };
+}
+/**
+ * Read the policy as written and report what it would cost and buy. Pure
+ * except for `process.env` and PATH lookups; appends nothing and calls nobody.
+ */
+export function judgePreflight(policyPath = CROSSCHECK_POLICY_PATH) {
+    // parseCrosscheckPolicy with `offline: false` rather than
+    // loadCrosscheckPolicy: see `offlineSwitch` above.
+    const policy = parseCrosscheckPolicy(readFileSync(policyPath, 'utf8'), {
+        offline: false,
+    });
+    const providers = Object.values(policy.providers)
+        .map(inspect)
+        .sort((a, b) => a.provider.localeCompare(b.provider));
+    const callable = providers.filter((p) => p.kind !== 'native' && p.enabled && p.status !== 'unmet');
+    const activeExternal = callable.filter((p) => p.mode === 'active').map((p) => p.provider);
+    const shadowExternal = callable.filter((p) => p.mode === 'shadow').map((p) => p.provider);
+    const minProviders = policy.quorumRule.minProviders;
+    const canDecide = activeExternal.length >= minProviders;
+    const problems = [];
+    const notes = [];
+    for (const p of providers) {
+        if (p.status !== 'unmet')
+            continue;
+        problems.push(`Provider "${p.provider}" is enabled but its precondition (${p.precondition}) is unmet. Set it, or set "enabled: false" for this runner.`);
+    }
+    // One promoted provider is the trap worth failing on. Zero is the shipped
+    // default and a deliberate one, so it is reported and not complained about.
+    //
+    // Unless it was chosen: the sentence below has always ended "or accept
+    // that these calls are shadow runs that cost like gating ones", and
+    // `accept_non_gating_actives` is where that acceptance is now written down.
+    // Declared, the same sentence is a note — the cost is unchanged and still
+    // printed, but a command that reports a decision the operator already made
+    // has no business exiting 1 on it, and a scheduled health check cannot
+    // distinguish a permanent 1 from a new one.
+    if (activeExternal.length > 0 && !canDecide) {
+        const arithmetic = `${activeExternal.length} external provider(s) are mode: active but quorum_rule.min_providers is ${minProviders}. On a finding the native provider raised it is excluded as the finder, so the gating pool is the actives alone and every case returns insufficient-providers.`;
+        if (policy.quorumRule.acceptNonGatingActives) {
+            notes.push(`${arithmetic} Accepted via quorum_rule.accept_non_gating_actives: the verdict still reaches the operator on the escalation, and enabling a second provider starts gating with no further edit.`);
+        }
+        else {
+            problems.push(`${arithmetic} Promote a second provider or accept that these calls are shadow runs that cost like gating ones.`);
+        }
+    }
+    const detail = canDecide
+        ? `${activeExternal.length} active external provider(s) against min_providers ${minProviders}: a native finding can be overturned.`
+        : activeExternal.length === 0
+            ? `No external provider is mode: active. Every cross-check is recorded and none can change an outcome — the shipped default.`
+            : `${activeExternal.length} active external provider(s) against min_providers ${minProviders}: nothing can be decided.`;
+    return {
+        policyPath,
+        offlineSwitch: Boolean(process.env.SMITH_CROSSCHECK_OFFLINE),
+        providers,
+        gating: { activeExternal, shadowExternal, minProviders, canDecide, detail },
+        problems,
+        notes,
+    };
+}

package/factory/orchestrator/dist/judges.js

@@ -0,0 +1,310 @@
+import { readFileSync } from 'node:fs';
+import { JUDGE_REPORT_EVENT_TYPE } from './agents-registry.js';
+import { SmithError } from './errors.js';
+import { appendEvent, eventTaskId, readLineageEvents, } from './events.js';
+import { isQualifiedTaskId, taskIdsMatch } from './taskId.js';
+export class JudgeError extends SmithError {
+}
+/**
+ * A dispatched judge must report back, and the report is a file (D-31, D-20 /
+ * P9-11).
+ *
+ * Wave 3 dispatched eight agents and five ended their turn on an announcement
+ * of the next step they were about to take — "Now let's run the
+ * prototype-pollution probes" — signalled `completed` to the layer above, and
+ * wrote nothing. All five finished correctly on one resume, in 1–13 tool
+ * calls, so the work was cheap and the silence was the entire defect. Wave 4
+ * showed the sharper version: a reviewer that returned 36k tokens of fluent,
+ * on-topic, technically accurate prose which was a fragment of its own
+ * planning. An empty return is detectable. A plausible fragment is not.
+ *
+ * So completion here is never "the agent said something". It is "the artifact
+ * exists and parses" — checked by this module, against a path the DISPATCH
+ * declared in advance, so nobody gets to pick the finish line after the fact.
+ *
+ * The two halves are ordinary events, which is what lets anything downstream
+ * notice a gap:
+ *
+ *   - dispatch: a `dispatch_decision` carrying `declared_artifact` and
+ *     `round` on top of the three dimensions taxonomy.yml already requires of
+ *     a dispatch. It is a normal dispatch record — agents-registry.ts folds it
+ *     unchanged — and `declared_artifact` is what marks it as a turn that owes
+ *     a report. A coder's dispatch declares no artifact and is not a judge.
+ *   - report: a `judge-reported` carrying `agent_role`, `round`,
+ *     `artifact_path` and `finding_count`.
+ *
+ * The difference between the two sets is `outstandingJudges()`, and the gate
+ * refuses to score a task while it is non-empty.
+ */
+export const JUDGE_DISPATCH_EVENT_TYPE = 'dispatch_decision';
+/**
+ * Re-exported, not re-declared. The registry owns the terminal-event
+ * vocabulary — this one next to `task-result-recorded` and `error-logged`,
+ * which are the other two ways a turn can end — and a judge report is one of
+ * its three. Two `= 'judge-reported'` literals in two modules is two places to
+ * keep in sync, and the day they disagree the registry stops recognising the
+ * report this file writes.
+ */
+export { JUDGE_REPORT_EVENT_TYPE };
+/**
+ * Every judge dispatched from the operator session runs on the native provider
+ * at its top tier unless the caller says otherwise.
+ *
+ * The concrete model gets no such default (P9-23). Provider and tier are coarse
+ * enough that a wrong default is visibly wrong; a model id is not, and this
+ * verb is exactly how crosscheck.yml's finder_ne_critic pair (reviewer /
+ * verifier) reaches the log. `smith dispatch check` compares those two ids, so
+ * a defaulted one would have it compare two placeholders and report on a
+ * session nobody ran.
+ */
+const DEFAULT_PROVIDER = 'claude';
+const DEFAULT_MODEL_TIER = 'frontier';
+/** `--no-findings`: an operator attesting that a judge ran clean, recorded as an attestation and never as an artifact. */
+const ATTESTED_BY = 'operator';
+/**
+ * The turn a record belongs to, tolerating the two spellings of one task id.
+ *
+ * Both halves of a turn are stamped with whatever the operator typed:
+ * `smith judge dispatch --task` and `smith gate run <task-id>` pass their
+ * argument through verbatim, and neither qualifies it. Keyed on the raw
+ * string, a dispatch recorded as `epic-1/task-1` and a gate run asking for
+ * `task-1` were two different turns, so the fold handed back an empty set —
+ * which `outstandingJudges` cannot tell apart from "every judge reported"
+ * (D-183).
+ *
+ * A bare id that two epics both claim matches more than one turn, and this
+ * returns none of them: closing one epic's judge with the other's report is
+ * the failure this guard exists to prevent, and `buildTaskIdAliases` refuses
+ * exactly the same ambiguity. Leaving both outstanding blocks the gate, and
+ * the operator's remedy is to qualify the id.
+ */
+function findTurn(turns, taskId, role) {
+    const matching = turns.filter((t) => t.role === role && taskIdsMatch(t.taskId, taskId));
+    return matching.length === 1 ? matching[0] : undefined;
+}
+function stringField(payload, field) {
+    const value = payload[field];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function numberField(payload, field) {
+    const value = payload[field];
+    return typeof value === 'number' && Number.isInteger(value) ? value : undefined;
+}
+/**
+ * Fold the dispatch set and the report set into one turn per (task, role).
+ *
+ * Two passes, not one, because the log's order is real: a round-1 report that
+ * lands after a round-2 dispatch must NOT close round 2. Pass one settles
+ * which round each role is on; pass two closes only a report that names that
+ * round. The alternative — a single pass that resets `reported` on each new
+ * dispatch — gets the same answer for a well-ordered log and the wrong one for
+ * a log where a slow judge's report arrives late.
+ *
+ * A role's earlier rounds are superseded rather than kept outstanding: the
+ * same rule agents-registry.ts already applies to a re-dispatched task, and
+ * without it every re-poke would leave a permanent phantom in the outstanding
+ * list.
+ */
+export function foldJudgeTurns(events, taskId) {
+    const turns = [];
+    for (const { record } of events) {
+        if (record.event_type !== JUDGE_DISPATCH_EVENT_TYPE)
+            continue;
+        // Both levels: the dispatch that owes a report may name its task only in
+        // its payload (D-245), and a turn opened under no task is a report nobody
+        // can ever close.
+        const recordTaskId = eventTaskId(record);
+        if (recordTaskId === null)
+            continue;
+        if (taskId !== undefined && !taskIdsMatch(recordTaskId, taskId))
+            continue;
+        const role = stringField(record.payload, 'agent_role');
+        const declaredArtifact = stringField(record.payload, 'declared_artifact');
+        const round = numberField(record.payload, 'round');
+        // No declared artifact, no report owed: this is a coder or a merger, not
+        // a judge. `round` is required alongside it, so a half-formed payload is
+        // ignored rather than folded into a turn nobody can ever close.
+        if (role === undefined || declaredArtifact === undefined || round === undefined)
+            continue;
+        const existing = findTurn(turns, recordTaskId, role);
+        if (existing !== undefined) {
+            if (existing.round > round)
+                continue;
+            // The qualified spelling wins the row it names: it is the one a caller
+            // can hand back to anything that needs the epic.
+            existing.taskId = isQualifiedTaskId(existing.taskId) ? existing.taskId : recordTaskId;
+            existing.round = round;
+            existing.declaredArtifact = declaredArtifact;
+            existing.reported = false;
+            existing.reportedArtifact = null;
+            existing.attested = false;
+            continue;
+        }
+        turns.push({
+            taskId: recordTaskId,
+            role,
+            round,
+            declaredArtifact,
+            reported: false,
+            reportedArtifact: null,
+            attested: false,
+        });
+    }
+    for (const { record } of events) {
+        if (record.event_type !== JUDGE_REPORT_EVENT_TYPE)
+            continue;
+        const recordTaskId = eventTaskId(record);
+        if (recordTaskId === null)
+            continue;
+        if (taskId !== undefined && !taskIdsMatch(recordTaskId, taskId))
+            continue;
+        const role = stringField(record.payload, 'agent_role');
+        if (role === undefined)
+            continue;
+        const turn = findTurn(turns, recordTaskId, role);
+        if (turn === undefined || turn.round !== numberField(record.payload, 'round'))
+            continue;
+        turn.reported = true;
+        turn.reportedArtifact = stringField(record.payload, 'artifact_path') ?? null;
+        turn.attested = record.payload.attested_by !== undefined && record.payload.attested_by !== null;
+    }
+    return [...turns].sort((a, b) => a.role.localeCompare(b.role));
+}
+/** The judges a task is still waiting on — the whole point of recording either half. */
+export function outstandingJudges(turns) {
+    return turns.filter((t) => !t.reported);
+}
+/**
+ * Read the turns for one task out of its session's whole lineage.
+ *
+ * The lineage and not the session, because a judge turn is a promise with two
+ * halves and nothing makes them land in the same operator session. An epic
+ * that outgrows one session is the recommended shape (P9-7), so round 1
+ * dispatches the reviewer and round 2 is where the report — and the gate that
+ * reads this — arrives. Folding one session broke that in both directions:
+ * `recordJudgeReport` refused a real report as `judges.not-dispatched`, and
+ * `outstandingJudges` came back empty, which is the gate scoring a task whose
+ * judge never reported. That is precisely the state P9-11 exists to refuse.
+ *
+ * D-119 swept every deciding fold onto `readLineageEvents` and missed this
+ * one: the sweep found its callers by grep, and this file carried a NUL byte
+ * that made grep skip it in silence (D-155). D-156 is the half that survived.
+ */
+export async function readJudgeTurns(taskId, ctx, opts = {}) {
+    return foldJudgeTurns(await readLineageEvents(ctx.sessionId, opts), taskId);
+}
+async function emit(eventType, payload, taskId, ctx, opts) {
+    return appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: eventType,
+        task_id: taskId,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload,
+    }, opts);
+}
+/**
+ * Record that a judge was dispatched and what file it owes. Emitted by the
+ * dispatcher BEFORE the agent runs — a dispatch recorded afterwards could only
+ * ever describe judges that came back, which is the set that was never the
+ * problem.
+ */
+export async function recordJudgeDispatch(input, ctx, opts = {}) {
+    if (!Number.isInteger(input.round) || input.round < 1) {
+        throw new JudgeError('judges.invalid-round', `Judge rounds are 1-based integers; got ${JSON.stringify(input.round)}.`, { round: input.round, task_id: input.taskId, agent_role: input.role });
+    }
+    if (input.artifactPath.trim() === '') {
+        throw new JudgeError('judges.no-declared-artifact', 'A judge dispatch must declare the artifact it will write — that path is the finish line.', { task_id: input.taskId, agent_role: input.role });
+    }
+    // appendEvent would reject this too, on taxonomy grounds. Caught here anyway,
+    // so the message names the judge that was about to be dispatched instead of
+    // the record type that failed validation.
+    if (typeof input.model !== 'string' || input.model.trim() === '') {
+        throw new JudgeError('judges.no-model', `A judge dispatch must name the model it runs on: "${input.role}" is checked against the finder it followed by model id, not by tier (P9-23).`, { task_id: input.taskId, agent_role: input.role });
+    }
+    return emit(JUDGE_DISPATCH_EVENT_TYPE, {
+        agent_role: input.role,
+        provider: input.provider ?? DEFAULT_PROVIDER,
+        model_tier: input.modelTier ?? DEFAULT_MODEL_TIER,
+        model: input.model,
+        round: input.round,
+        declared_artifact: input.artifactPath,
+    }, input.taskId, ctx, opts);
+}
+/**
+ * Read a judge's artifact and answer how many findings it holds.
+ *
+ * Three distinct failures, three distinct codes, because they are three
+ * different things to do about it: the file is not there (re-poke the agent),
+ * it is there and is prose (the agent narrated instead of reporting), it is
+ * there and parses but is not a findings list (the agent wrote some other
+ * shape — a grader verdict, say, which is P9-14's business and needs its own
+ * schema before anything here can accept it).
+ */
+export function readJudgeArtifact(artifactPath) {
+    let raw;
+    try {
+        raw = readFileSync(artifactPath, 'utf8');
+    }
+    catch (err) {
+        throw new JudgeError('judges.artifact-missing', `Judge artifact "${artifactPath}" is not on disk. A judge whose turn ended without its declared file did not report; re-run it rather than scoring without it.`, { artifact_path: artifactPath, cause: err instanceof Error ? err.message : String(err) });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JudgeError('judges.artifact-unparseable', `Judge artifact "${artifactPath}" is not JSON. Prose in the artifact slot is the wave-4 failure exactly: fluent text that reads like a verdict and is not one.`, { artifact_path: artifactPath, cause: err instanceof Error ? err.message : String(err) });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new JudgeError('judges.artifact-not-a-list', `Judge artifact "${artifactPath}" parsed to ${parsed === null ? 'null' : typeof parsed}, not a findings-evidence array. An empty review is "[]", written out.`, { artifact_path: artifactPath });
+    }
+    return parsed;
+}
+function notDispatchedMessage(input, turn, forRole) {
+    if (forRole.length > 1) {
+        return `Task id "${input.taskId}" names a "${input.role}" turn in ${forRole.length} epics (${forRole.map((t) => t.taskId).join(', ')}). Report against the qualified id — closing one of them here would be a guess.`;
+    }
+    if (turn === undefined) {
+        return `No judge dispatch for role "${input.role}" on ${input.taskId}. Record the dispatch first — a report with no dispatch behind it proves nothing about coverage.`;
+    }
+    return `Role "${input.role}" on ${input.taskId} is on round ${turn.round}, not round ${input.round}.`;
+}
+/**
+ * Close a judge turn. Refuses unless the role was actually dispatched for the
+ * round being reported, so a report cannot invent its own dispatch and make
+ * the two sets agree by growing both.
+ */
+export async function recordJudgeReport(input, ctx, opts = {}) {
+    const turns = await readJudgeTurns(input.taskId, ctx, opts);
+    const forRole = turns.filter((t) => t.role === input.role);
+    // More than one is a bare id that two epics both claim a turn for. Closing
+    // either would be a guess, and `foldJudgeTurns` refuses the same ambiguity,
+    // so the report emitted here would close nothing on the next read anyway.
+    const turn = forRole.length === 1 ? forRole[0] : undefined;
+    if (turn === undefined || (input.round !== undefined && input.round !== turn.round)) {
+        throw new JudgeError('judges.not-dispatched', notDispatchedMessage(input, turn, forRole), {
+            task_id: input.taskId,
+            agent_role: input.role,
+            round: input.round ?? null,
+        });
+    }
+    const artifactPath = input.noFindings ? null : (input.artifactPath ?? turn.declaredArtifact);
+    const findingCount = artifactPath === null ? 0 : readJudgeArtifact(artifactPath).length;
+    await emit(JUDGE_REPORT_EVENT_TYPE, {
+        agent_role: input.role,
+        round: turn.round,
+        artifact_path: artifactPath,
+        finding_count: findingCount,
+        ...(input.noFindings ? { attested_by: ATTESTED_BY } : {}),
+    }, input.taskId, ctx, opts);
+    return {
+        taskId: input.taskId,
+        role: input.role,
+        round: turn.round,
+        artifactPath,
+        findingCount,
+        attested: input.noFindings === true,
+    };
+}