@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/issueReporter.js

@@ -0,0 +1,415 @@
+/**
+ * Compose the three pure pieces into the run's write path: fold the log
+ * (errorIssues.ts), ask the roadmap whether a project's tracker is writable
+ * (the resolved switch, handed in), resolve the repo and classify `gh`
+ * (git.ts/gh.ts), deduplicate against already-open issues, open or comment,
+ * and record what happened as an `issue-reported` event of its own.
+ *
+ * `reportErrors()` is the one entry point a run calls right after it
+ * records an error. It is idempotent by fingerprint: called twice over the
+ * same log plus the events the first call appended, it opens and comments
+ * nothing the second time, because step 4 below reads that history back.
+ *
+ * Dedup asks GitHub, not a local index (functional clause 3). No file
+ * under `state/` tracks which fingerprints are already open. The loser's
+ * cost of that choice: one `gh issue list --search` round trip per
+ * candidate error rather than an O(1) local lookup, and every `commented`
+ * outcome pays a second `gh issue comment` round trip on top. Both are
+ * accepted because a local index would drift the moment an issue is closed
+ * or reopened by a human outside this process, and this module would have
+ * no way to notice.
+ *
+ * This module never re-implements task 2 or task 3: `errorIssues.ts`,
+ * `gh.ts` and `git.ts` are imported, never edited, and never touched here
+ * are `PROJECTS_DIR`, `process.cwd()` or `REPO_ROOT` — the project register
+ * is a required parameter, supplied by the caller (task 5), never read off
+ * the filesystem by this module.
+ */
+import { FINGERPRINT_LINE_PREFIX, foldErrorEvents, renderBody, renderComment, renderTitle, toIssueBodyFields, toIssueCommentFields, withSessionFallback, } from './errorIssues.js';
+import { appendEvent } from './events.js';
+import { buildCommentArgv, buildCreateIssueArgv, buildSearchIssuesArgv, classifyGh, resolveProjectRepo, } from './gh.js';
+/**
+ * The closed, named outcome vocabulary. Exactly one of these nine words is
+ * recorded for every candidate error, always — functional clause 2.
+ * `skipped-unresolved-project` is settled before any of the others can be:
+ * a row this factory cannot identify the project of is never filed against
+ * this factory's own repository by default (the privacy-leak guard).
+ */
+export const ISSUE_REPORT_OUTCOMES = [
+    'opened',
+    'commented',
+    'deduped-open',
+    'skipped-disabled',
+    'skipped-no-remote',
+    'skipped-gh-missing',
+    'skipped-unauthenticated',
+    'skipped-unresolved-project',
+    'failed',
+];
+const ISSUE_REPORTED_EVENT_TYPE = 'issue-reported';
+/**
+ * The `issue-reported` payload allowlist (functional clause 6, nonfunctional
+ * clause 3): named fields only, never a spread of a source event's payload.
+ * Sorted, and this is the literal the test asserts against.
+ */
+export const ISSUE_REPORT_PAYLOAD_KEYS = [
+    'detail',
+    'error_class',
+    'fingerprint',
+    'issue_url',
+    'latest_event_id',
+    'outcome',
+    'reason',
+    'repo_slug',
+    'source',
+    'task_ref',
+];
+function parseSearchResult(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed))
+        return null;
+    const issues = [];
+    for (const item of parsed) {
+        if (typeof item !== 'object' || item === null)
+            return null;
+        const number = item.number;
+        const body = item.body;
+        if (typeof number !== 'number' || typeof body !== 'string')
+            return null;
+        const url = item.url;
+        issues.push({ number, body, url: typeof url === 'string' ? url : undefined });
+    }
+    return issues;
+}
+/** The exact machine-readable fingerprint line, built the same way errorIssues.ts's renderers do. */
+function fingerprintLine(fingerprint) {
+    return `${FINGERPRINT_LINE_PREFIX}${fingerprint}`;
+}
+/** An exact line match, not a substring: functional clause 4. */
+function findExactMatch(issues, fingerprint) {
+    const line = fingerprintLine(fingerprint);
+    return issues.find((issue) => issue.body.split('\n').includes(line)) ?? null;
+}
+/**
+ * The task ref an unstamped row carries, if any -- the envelope's own
+ * `task_id` first, falling back to a hand-appended row's `payload.task_ref`.
+ * Mirrors errorIssues.ts's `candidateTaskRef`, which this module never
+ * imports so as to keep the two folds' internals independent.
+ */
+function candidateTaskRef(record) {
+    if (typeof record.task_id === 'string' && record.task_id.length > 0)
+        return record.task_id;
+    const payload = (record.payload ?? {});
+    return typeof payload.task_ref === 'string' && payload.task_ref.length > 0
+        ? payload.task_ref
+        : undefined;
+}
+/**
+ * A row's project, resolved the same way `errorIssues.ts`'s fold resolves
+ * one: an explicit stamp always wins; absent that, `resolveRow` (the row's
+ * own task ref widened with `withSessionFallback`'s session fallbacks) gets
+ * the answer. `null` when none of them can tell -- this factory's own
+ * project is never guessed. This is what keeps an unstamped row from a
+ * foreign (or unidentifiable) project's session from being folded into this
+ * factory's own prior-report history (and, through `decideOutcome`'s dedup
+ * key, its own repository) merely because nothing stamped it.
+ */
+function resolveRecordProject(record, resolveRow) {
+    if (typeof record.project === 'string')
+        return record.project;
+    return resolveRow(candidateTaskRef(record), record.session_id);
+}
+/**
+ * Every already-appended `issue-reported` record still open, read off the
+ * SNAPSHOT of events this call was handed — never off events this same call
+ * itself appends. That is what lets the five duplicate candidates a single
+ * broken gate produces in one round resolve through GitHub search (one
+ * create, four comments) rather than short-circuiting on each other.
+ *
+ * A record whose project cannot be resolved at all is dropped rather than
+ * pushed: it can never match `priorReportFor`'s `h.project === report.project`
+ * comparison against a null-project report either (Step 0 below settles
+ * those before Step 4 runs), so keeping it around would only cost a lookup.
+ */
+function priorOpenReports(events, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
+    const resolveRow = withSessionFallback(scopeEvents, resolveProject, selfFallback);
+    const out = [];
+    for (const event of events) {
+        const { record } = event;
+        if (record.event_type !== ISSUE_REPORTED_EVENT_TYPE)
+            continue;
+        const payload = record.payload;
+        if (payload.outcome !== 'opened' &&
+            payload.outcome !== 'commented' &&
+            payload.outcome !== 'deduped-open') {
+            continue;
+        }
+        if (typeof payload.fingerprint !== 'string' || typeof payload.latest_event_id !== 'string') {
+            continue;
+        }
+        const project = resolveRecordProject(record, resolveRow);
+        if (project === null)
+            continue;
+        out.push({
+            project,
+            fingerprint: payload.fingerprint,
+            outcome: payload.outcome,
+            latest_event_id: payload.latest_event_id,
+        });
+    }
+    return out;
+}
+function toPayload(record) {
+    const payload = {
+        outcome: record.outcome,
+        fingerprint: record.fingerprint,
+        source: record.source,
+        error_class: record.error_class,
+        task_ref: record.task_ref,
+        latest_event_id: record.latest_event_id,
+    };
+    if (record.repo_slug !== undefined)
+        payload.repo_slug = record.repo_slug;
+    if (record.issue_url !== undefined)
+        payload.issue_url = record.issue_url;
+    if (record.reason !== undefined)
+        payload.reason = record.reason;
+    if (record.detail !== undefined)
+        payload.detail = record.detail;
+    return payload;
+}
+async function appendIssueReported(report, record, opts) {
+    return appendEvent({
+        session_id: report.session_id,
+        actor: 'system',
+        event_type: ISSUE_REPORTED_EVENT_TYPE,
+        task_id: report.task_ref,
+        // Schema minimum is 1; a report folded from an event that carried no
+        // plan version (e.g. a hand-appended error-logged) has none either.
+        plan_version: report.plan_version ?? 1,
+        causal_parent: report.latest_event_id,
+        payload: toPayload(record),
+        // `EventInput.project` is `string | undefined` -- omitted, never
+        // `null`, when a row's project could not be resolved; the writer
+        // never stamps a guess (events.ts's documented convention).
+        ...(report.project !== null ? { project: report.project } : {}),
+    }, opts);
+}
+/**
+ * Step 4's dedup rule, the one copy both the real path and the preview read:
+ * same project, same fingerprint, same latest event, already open.
+ */
+function priorReportFor(history, report) {
+    return history.find((h) => h.project === report.project &&
+        h.fingerprint === report.fingerprint &&
+        h.latest_event_id === report.latest_event_id);
+}
+/**
+ * `register` is required and never defaulted: forwarded `undefined` would
+ * otherwise fail inside `resolveProjectRepo` naming neither the parameter
+ * nor this module. `[]` is a legitimate register and is not rejected.
+ */
+function requireRegister(register, entryPoint) {
+    if (!Array.isArray(register)) {
+        throw new Error(`${entryPoint}: the register parameter is required (readonly ProjectRef[]), got ${String(register)}`);
+    }
+}
+/** Functional clause 2's decision procedure, in order, stopping at the first match. */
+async function decideOutcome(report, isProjectEnabled, register, runner, history) {
+    const base = {
+        fingerprint: report.fingerprint,
+        project: report.project,
+        source: report.source,
+        error_class: report.error_class,
+        task_ref: report.task_ref,
+        latest_event_id: report.latest_event_id,
+    };
+    // Step 0: can this row's project be identified at all. A row still
+    // unresolved after the fold's own session fallbacks is never filed
+    // against this factory's own repository by default (the privacy-leak
+    // guard this whole module exists to close) -- settled before repo
+    // resolution or any `gh` interaction, ahead of every other step.
+    if (report.project === null) {
+        return { ...base, outcome: 'skipped-unresolved-project', reason: 'project-unresolved' };
+    }
+    const project = report.project;
+    // Step 1: the switch.
+    if (!isProjectEnabled(project)) {
+        return { ...base, outcome: 'skipped-disabled', reason: 'switch-off' };
+    }
+    // Step 2: which repository.
+    const repo = resolveProjectRepo(project, register);
+    if (!('slug' in repo)) {
+        return { ...base, outcome: 'skipped-no-remote', reason: repo.reason, detail: repo.detail };
+    }
+    const repoSlug = repo.slug;
+    // Step 3: can `gh` actually be used.
+    const gh = classifyGh(runner);
+    if (gh.outcome === 'missing') {
+        return {
+            ...base,
+            outcome: 'skipped-gh-missing',
+            reason: 'gh-not-on-path',
+            repo_slug: repoSlug,
+        };
+    }
+    if (gh.outcome === 'unauthenticated') {
+        return {
+            ...base,
+            outcome: 'skipped-unauthenticated',
+            reason: 'gh-unauthenticated',
+            repo_slug: repoSlug,
+        };
+    }
+    if (gh.outcome === 'unknown') {
+        return { ...base, outcome: 'failed', reason: 'gh-unknown', repo_slug: repoSlug };
+    }
+    // Step 4: already reported and still open, per the snapshot this call read.
+    if (priorReportFor(history, report)) {
+        return {
+            ...base,
+            outcome: 'deduped-open',
+            reason: 'already-reported',
+            repo_slug: repoSlug,
+        };
+    }
+    // Step 5: search GitHub itself.
+    const searchResult = runner('gh', buildSearchIssuesArgv(repoSlug, report.fingerprint));
+    if (searchResult.status !== 0) {
+        return { ...base, outcome: 'failed', reason: 'search-failed', repo_slug: repoSlug };
+    }
+    const issues = parseSearchResult(searchResult.stdout);
+    if (issues === null) {
+        // gh exited 0 but the output could not be read as an issue list (e.g.
+        // --json was dropped somewhere upstream and gh printed its human table,
+        // or the response was truncated). Distinct from a genuine nonzero exit
+        // above, which is a process failure rather than an unreadable payload.
+        return { ...base, outcome: 'failed', reason: 'search-unparseable', repo_slug: repoSlug };
+    }
+    // Step 6: an exact fingerprint-line match gets a comment.
+    const match = findExactMatch(issues, report.fingerprint);
+    if (match) {
+        const body = renderComment(toIssueCommentFields(report));
+        const commentResult = runner('gh', buildCommentArgv(repoSlug, match.number, body));
+        if (commentResult.status !== 0) {
+            return { ...base, outcome: 'failed', reason: 'comment-failed', repo_slug: repoSlug };
+        }
+        const issueUrl = match.url ?? `https://github.com/${repoSlug}/issues/${String(match.number)}`;
+        return { ...base, outcome: 'commented', repo_slug: repoSlug, issue_url: issueUrl };
+    }
+    // Step 7: no match — open a new issue.
+    const fields = toIssueBodyFields(report);
+    const createResult = runner('gh', buildCreateIssueArgv(repoSlug, renderTitle(fields), renderBody(fields)));
+    if (createResult.status !== 0) {
+        return { ...base, outcome: 'failed', reason: 'create-failed', repo_slug: repoSlug };
+    }
+    return {
+        ...base,
+        outcome: 'opened',
+        repo_slug: repoSlug,
+        issue_url: createResult.stdout.trim(),
+    };
+}
+/** Preview's statement about the one step it has no instrument to measure. */
+const STEP_3_NOT_PERFORMED = 'not-performed';
+const DECISION_NOTE = 'create or comment: which of the two would run is decided by the search ' +
+    'this preview deliberately does not perform';
+/**
+ * The preview-safe half of `decideOutcome`: steps 1, 2 and 4 only, through
+ * the same fold, `priorOpenReports` and `priorReportFor` the real path uses.
+ * Never invokes the runner with command `gh`, never appends an event. For a
+ * gh-reaching candidate it BUILDS the search, create and comment argv, and
+ * prints both create and comment because which one runs is settled by a
+ * search this helper does not perform; the comment argv's issue number is
+ * `0`, a placeholder known only after that search. `runner` is accepted for
+ * signature parity with `reportErrors()`; nothing here reaches it.
+ */
+export async function previewOutcomes(events, isProjectEnabled, register, runner, clock, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
+    requireRegister(register, 'previewOutcomes');
+    void runner;
+    const { reports } = foldErrorEvents(events, clock(), () => true, resolveProject, selfFallback, scopeEvents);
+    const history = priorOpenReports(events, resolveProject, selfFallback, scopeEvents);
+    const out = [];
+    for (const report of reports) {
+        const { fingerprint, project, source, error_class, task_ref, latest_event_id } = report;
+        const base = { fingerprint, project, source, error_class, task_ref, latest_event_id };
+        const step3 = { step_3_gh_availability: STEP_3_NOT_PERFORMED };
+        const settle = (rest) => out.push({ ...base, ...step3, ...rest });
+        // Step 0: can this row's project be identified at all.
+        if (project === null) {
+            settle({
+                settled_at_step: 0,
+                outcome: 'skipped-unresolved-project',
+                reason: 'project-unresolved',
+            });
+            continue;
+        }
+        // Step 1: the switch.
+        if (!isProjectEnabled(project)) {
+            settle({ settled_at_step: 1, outcome: 'skipped-disabled', reason: 'switch-off' });
+            continue;
+        }
+        // Step 2: which repository -- git-only, and the source of the slug.
+        const repo = resolveProjectRepo(project, register);
+        if (!('slug' in repo)) {
+            settle({
+                settled_at_step: 2,
+                outcome: 'skipped-no-remote',
+                reason: repo.reason,
+                detail: repo.detail,
+            });
+            continue;
+        }
+        const repoSlug = repo.slug;
+        // Step 3 is skipped, not guessed. Step 4: the own-log dedup.
+        if (priorReportFor(history, report)) {
+            const reason = 'already-reported';
+            settle({ settled_at_step: 4, outcome: 'deduped-open', reason, repo_slug: repoSlug });
+            continue;
+        }
+        const fields = toIssueBodyFields(report);
+        const issueBody = renderBody(fields);
+        const commentText = renderComment(toIssueCommentFields(report));
+        settle({
+            repo_slug: repoSlug,
+            search_argv: buildSearchIssuesArgv(repoSlug, fingerprint),
+            create_argv: buildCreateIssueArgv(repoSlug, renderTitle(fields), issueBody),
+            comment_argv: buildCommentArgv(repoSlug, 0, commentText),
+            issue_body: issueBody,
+            comment_text: commentText,
+            decision_note: DECISION_NOTE,
+        });
+    }
+    return out;
+}
+/**
+ * Fold `events` into candidate errors, decide and act on each in order, and
+ * record every attempt as an `issue-reported` event. Never throws on a
+ * reporting failure — every path returns an outcome (functional clause 8).
+ *
+ * `isProjectEnabled` is the resolved `error_issues` switch, `register` is
+ * `projects.ts`'s `{name, dir}` list (task 5 supplies it; this module never
+ * calls `factoryProjects()` itself), `runner` is task 3's injected `gh`
+ * command runner, and `clock` supplies `now` for the fold below.
+ */
+export async function reportErrors(events, isProjectEnabled, register, runner, clock, opts = {}, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
+    requireRegister(register, 'reportErrors');
+    // Every project's switch is applied by this module's own step 1, not by
+    // the fold: foldErrorEvents dropping a disabled project's candidates
+    // silently would lose the `skipped-disabled` record clause 2 requires.
+    const { reports } = foldErrorEvents(events, clock(), () => true, resolveProject, selfFallback, scopeEvents);
+    const history = priorOpenReports(events, resolveProject, selfFallback, scopeEvents);
+    const out = [];
+    for (const report of reports) {
+        const record = await decideOutcome(report, isProjectEnabled, register, runner, history);
+        await appendIssueReported(report, record, opts);
+        out.push(record);
+    }
+    return out;
+}

package/factory/orchestrator/dist/judgeStopHook.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * `.claude/hooks/judge-stop.sh` — the SubagentStop decision for a judge-class
+ * agent (reviewer, verifier, grader, spec-reviewer, security-reviewer,
+ * auditor; `JUDGE_ROLES` in dispatchLint.ts is the authoritative set).
+ *
+ * A judge can end its turn without ever writing the artifact its dispatch
+ * declared, and today that gap is found only downstream, when `smith judge
+ * report` answers `judges.artifact-missing` — after the agent is gone. This
+ * hook closes the loop at the one moment it can still act: block the stop
+ * while the declared path does not exist, allow it once it does. A harness
+ * `maxTurns` cap is out of scope; this hook cannot override it.
+ *
+ * The declared-artifact line and its parser come from `dispatchLint.ts`,
+ * never redefined — `dispatch lint` already refuses, before dispatch, any
+ * judge prompt whose line is missing, relative, or mismatched, so this hook
+ * only asks "does the file exist yet", never "is the line well-formed".
+ *
+ * Fail open on anything this hook cannot read: a non-judge `agent_type`, a
+ * prompt with no declared-artifact line, a relative path, unparseable stdin,
+ * an unreadable transcript — blocking on those would trap the agent until
+ * `maxTurns` for an obligation the hook could never state. Every fail-open
+ * path prints a stderr note and is covered upstream by `dispatch lint` or
+ * downstream by `judge report`'s `judges.artifact-missing`.
+ *
+ * Fail closed ONLY on a readable absolute declared path that does not exist.
+ *
+ * SubagentStop stdin fields: https://code.claude.com/docs/en/hooks
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { JUDGE_ROLES, parseDeclaredArtifactLine } from './dispatchLint.js';
+const JUDGE_ROLE_SET = new Set(JUDGE_ROLES);
+/**
+ * The pure decision: given the hook's stdin and the subagent's prompt text
+ * (or `null` when it could not be read at all), decide whether the stop is
+ * allowed. Touches the filesystem only to check whether the declared path
+ * exists -- the one question this hook exists to ask.
+ */
+export function decideJudgeStop(input, promptText) {
+    const agentType = input.agent_type;
+    if (agentType === undefined || !JUDGE_ROLE_SET.has(agentType)) {
+        // Not one of the six judge roles -- a coder's turn carries no declared
+        // artifact at all, so there is nothing for this hook to check.
+        return { decision: 'allow' };
+    }
+    if (promptText === null) {
+        return {
+            decision: 'allow',
+            note: "judge-stop: could not read this agent's prompt (transcript missing or " +
+                "unreadable); allowing the stop. judge report's judges.artifact-missing " +
+                'remains the backstop.',
+        };
+    }
+    const declared = parseDeclaredArtifactLine(promptText);
+    if (declared === null) {
+        return {
+            decision: 'allow',
+            note: 'judge-stop: no "Declared artifact: <path>" line in this prompt; allowing ' +
+                "the stop. dispatch lint refuses this before dispatch, and judge report's " +
+                'judges.artifact-missing catches it downstream.',
+        };
+    }
+    if (!path.isAbsolute(declared)) {
+        return {
+            decision: 'allow',
+            note: `judge-stop: declared artifact "${declared}" is not an absolute path; ` +
+                'allowing the stop. dispatch lint refuses this before dispatch, and judge ' +
+                "report's judges.artifact-missing catches it downstream.",
+        };
+    }
+    if (!existsSync(declared)) {
+        return {
+            decision: 'block',
+            reason: `Declared artifact ${declared} does not exist yet. Write it before ending this turn.`,
+        };
+    }
+    // Existence is this hook's whole question -- an empty or unparseable file
+    // is `judge report`'s to refuse (`judges.artifact-unparseable`, `judges.
+    // artifact-not-a-list`), not this hook's to trap the agent over.
+    return { decision: 'allow' };
+}
+/**
+ * The last user-role message's text in a Claude Code JSONL transcript --
+ * where a dispatch prompt and its "Declared artifact:" line live. Walks
+ * backward from the end, since a subagent's transcript can carry many turns
+ * and the dispatch prompt need not be the only user turn. Returns `null` on
+ * any read or parse failure.
+ */
+export function extractLastUserPromptText(transcriptPath) {
+    let raw;
+    try {
+        raw = readFileSync(transcriptPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined || line.trim() === '')
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const text = userTextOf(entry);
+        if (text !== null)
+            return text;
+    }
+    return null;
+}
+function userTextOf(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return null;
+    const rec = entry;
+    if (rec.type !== 'user')
+        return null;
+    const message = rec.message;
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        const parts = content
+            .filter((block) => typeof block === 'object' && block !== null)
+            .filter((block) => block.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text);
+        if (parts.length > 0)
+            return parts.join('\n');
+    }
+    return null;
+}
+/**
+ * The whole hook, minus process I/O: parse stdin, read the prompt, decide,
+ * and format the two output streams Claude Code and an operator each read.
+ * Exercised directly by tests without spawning a process; `main` below is
+ * the only piece that touches fd 0 and process.exit.
+ */
+export function runJudgeStopHook(rawStdin) {
+    let input;
+    try {
+        input = JSON.parse(rawStdin);
+    }
+    catch {
+        return {
+            stdout: '',
+            stderr: 'judge-stop: could not parse stdin as JSON; allowing the stop. ' +
+                "judge report's judges.artifact-missing remains the backstop.\n",
+        };
+    }
+    const promptText = input.transcript_path
+        ? extractLastUserPromptText(input.transcript_path)
+        : null;
+    const result = decideJudgeStop(input, promptText);
+    if (result.decision === 'block') {
+        return {
+            stdout: `${JSON.stringify({ decision: 'block', reason: result.reason })}\n`,
+            stderr: '',
+        };
+    }
+    return { stdout: '', stderr: result.note ? `${result.note}\n` : '' };
+}
+function main() {
+    const { stdout, stderr } = runJudgeStopHook(readFileSync(0, 'utf8'));
+    if (stdout)
+        process.stdout.write(stdout);
+    if (stderr)
+        process.stderr.write(stderr);
+}
+// Runs only when executed directly (judge-stop.sh execs `node
+// dist/judgeStopHook.js`) -- importing this module for its exports, as the
+// tests do, must never read stdin as a side effect.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main();
+}

package/factory/orchestrator/dist/judges.js

@@ -273,7 +273,7 @@ function graderFindingCount(parsed) {
  *
  * The grader is the one role whose declared shape is not a list: it writes a
  * verdict document, and refusing that document left its turn closable only by
- * a hand-written evidence file (FD-1, csb-audit-1). For `role === 'grader'`
+ * a hand-written evidence file (FD-1). For `role === 'grader'`
  * the grader result document is accepted beside the list, and the count is
  * its non-pass criteria. No other role gets that reading — a reviewer that
  * wrote a verdict wrote the wrong shape.