@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/issueReporter.js

@@ -25,12 +25,15 @@
  * 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, } from './errorIssues.js';
+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 eight words is
+ * 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',
@@ -40,6 +43,7 @@ export const ISSUE_REPORT_OUTCOMES = [
     'skipped-no-remote',
     'skipped-gh-missing',
     'skipped-unauthenticated',
+    'skipped-unresolved-project',
     'failed',
 ];
 const ISSUE_REPORTED_EVENT_TYPE = 'issue-reported';
@@ -60,8 +64,6 @@ export const ISSUE_REPORT_PAYLOAD_KEYS = [
     'source',
     'task_ref',
 ];
-/** Default project for an event stamped with none — matches events.ts's documented convention. */
-const DEFAULT_PROJECT = 'black-smith';
 function parseSearchResult(stdout) {
     let parsed;
     try {
@@ -94,14 +96,49 @@ 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) {
+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;
@@ -116,8 +153,11 @@ function priorOpenReports(events) {
         if (typeof payload.fingerprint !== 'string' || typeof payload.latest_event_id !== 'string') {
             continue;
         }
+        const project = resolveRecordProject(record, resolveRow);
+        if (project === null)
+            continue;
         out.push({
-            project: record.project ?? DEFAULT_PROJECT,
+            project,
             fingerprint: payload.fingerprint,
             outcome: payload.outcome,
             latest_event_id: payload.latest_event_id,
@@ -155,7 +195,10 @@ async function appendIssueReported(report, record, opts) {
         plan_version: report.plan_version ?? 1,
         causal_parent: report.latest_event_id,
         payload: toPayload(record),
-        project: report.project,
+        // `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);
 }
 /**
@@ -187,12 +230,21 @@ async function decideOutcome(report, isProjectEnabled, register, runner, history
         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(report.project)) {
+    if (!isProjectEnabled(project)) {
         return { ...base, outcome: 'skipped-disabled', reason: 'switch-off' };
     }
     // Step 2: which repository.
-    const repo = resolveProjectRepo(report.project, register);
+    const repo = resolveProjectRepo(project, register);
     if (!('slug' in repo)) {
         return { ...base, outcome: 'skipped-no-remote', reason: repo.reason, detail: repo.detail };
     }
@@ -234,7 +286,11 @@ async function decideOutcome(report, isProjectEnabled, register, runner, history
     }
     const issues = parseSearchResult(searchResult.stdout);
     if (issues === null) {
-        return { ...base, outcome: 'failed', reason: 'search-failed', repo_slug: repoSlug };
+        // 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);
@@ -274,17 +330,26 @@ const DECISION_NOTE = 'create or comment: which of the two would run is decided
  * `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) {
+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);
-    const history = priorOpenReports(events);
+    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' });
@@ -333,13 +398,13 @@ export async function previewOutcomes(events, isProjectEnabled, register, runner
  * 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 = {}) {
+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);
-    const history = priorOpenReports(events);
+    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);

package/factory/orchestrator/dist/judgePreflight.js

@@ -28,7 +28,8 @@
 // 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 { loadProjectProviderOverlay, parseCrosscheckPolicy, } from './crosscheck.js';
+import { readEnv } from './env.js';
 import { CROSSCHECK_POLICY_PATH } from './paths.js';
 import { apiKeyPresent, commandOnPath } from './preconditions.js';
 function inspect(config) {
@@ -49,6 +50,7 @@ function inspect(config) {
         kind: config.kind,
         enabled: config.enabled,
         mode: config.mode,
+        configSource: config.configSource,
     };
     if (config.transport === 'api') {
         const set = apiKeyPresent(config.apiKeyEnv);
@@ -63,6 +65,22 @@ function inspect(config) {
                     : `Disabled in the policy, so ${config.apiKeyEnv} is not read.`,
             };
         }
+        // Substitution keeps the provider's own name, mode and gating power
+        // (operator decision 1a) -- only the transport target and model changed
+        // underneath it, so this reads as the same provider succeeding, not a
+        // new one appearing.
+        if (config.via === 'openrouter') {
+            return {
+                ...base,
+                transport: 'api',
+                precondition: config.apiKeyEnv,
+                status: set ? 'ok' : 'unmet',
+                via: 'openrouter',
+                detail: set
+                    ? `Running via openrouter as ${config.model}: its own precondition is unmet on this box, and ${config.apiKeyEnv} is set.`
+                    : `Running via openrouter as ${config.model}, but ${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.`,
+            };
+        }
         return {
             ...base,
             transport: 'api',
@@ -91,7 +109,7 @@ function inspect(config) {
         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 executable on PATH. Whether it is authenticated is not knowable without spending a call — run "bs 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.`,
     };
 }
@@ -99,11 +117,14 @@ function inspect(config) {
  * 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) {
+export function judgePreflight(policyPath = CROSSCHECK_POLICY_PATH, options = {}) {
     // parseCrosscheckPolicy with `offline: false` rather than
     // loadCrosscheckPolicy: see `offlineSwitch` above.
     const policy = parseCrosscheckPolicy(readFileSync(policyPath, 'utf8'), {
         offline: false,
+        providerOverlay: options.projectDir
+            ? loadProjectProviderOverlay(options.projectDir)
+            : undefined,
     });
     const providers = Object.values(policy.providers)
         .map(inspect)
@@ -146,7 +167,7 @@ export function judgePreflight(policyPath = CROSSCHECK_POLICY_PATH) {
             : `${activeExternal.length} active external provider(s) against min_providers ${minProviders}: nothing can be decided.`;
     return {
         policyPath,
-        offlineSwitch: Boolean(process.env.SMITH_CROSSCHECK_OFFLINE),
+        offlineSwitch: Boolean(readEnv(process.env, 'SMITH_CROSSCHECK_OFFLINE')),
         providers,
         gating: { activeExternal, shadowExternal, minProviders, canDecide, detail },
         problems,

package/factory/orchestrator/dist/judgeRoles.js

@@ -0,0 +1,47 @@
+/**
+ * The epic criterion's six judge roles (task 5 and task 6 objectives both
+ * name this exact set: spec-reviewer, reviewer, verifier, grader,
+ * security-reviewer, auditor) -- the roles whose dispatch declares an
+ * artifact and whose SubagentStop is guarded by judge-stop.sh.
+ *
+ * A leaf module with no local imports of its own, so both `dispatchLint.ts`
+ * (which needs `readJudgeTurns` from `judges.ts`) and `judges.ts` (which
+ * needs this set for `foldJudgeTurns` and `recordJudgeDispatch`) can import
+ * it without forming a cycle between the two. `dispatchLint.ts` re-exports
+ * this set for its existing callers (judgeStopHook.ts, pluginManifest tests)
+ * — one array, never copied.
+ *
+ * Not the same six as dispatch.md's "Fingerprint the worktree around every
+ * judge" list, which swaps `auditor` for `uiux`: that section is about
+ * which judges run inside a task's worktree (auditor runs over a whole
+ * project at HEAD, never per-task, so a worktree fingerprint does not apply
+ * to it; uiux does run per-task). This list is about which roles owe a
+ * declared artifact and a blocked Stop, and `auditor` is one of them.
+ */
+export const JUDGE_ROLES = [
+    'reviewer',
+    'verifier',
+    'grader',
+    'spec-reviewer',
+    'security-reviewer',
+    'auditor',
+];
+/**
+ * `JUDGE_ROLES` plus `uiux`: every role a `smith judge dispatch` / `smith
+ * judge report` pair can open and close a turn for. wave.md's steps 5-7
+ * bracket the uiux visual pass with those same two verbs, same as grader,
+ * reviewer, verifier and security-reviewer (wave.md:242-253) — so
+ * `foldJudgeTurns` and `recordJudgeDispatch` (judges.ts) need uiux in scope
+ * too, or a real uiux dispatch throws `judges.non-judge-role` and its turn
+ * never folds.
+ *
+ * Deliberately NOT folded into `JUDGE_ROLES` itself: that set's meaning
+ * ("owes a declared-artifact line and a blocked Stop") stays exactly the six
+ * roles it always was for `dispatchLint.ts`'s `checkArtifact()` and
+ * `judgeStopHook.ts`'s SubagentStop guard — uiux's artifact is always the
+ * OBJECT `{run_status, structured_output, artifacts}` (bs-uiux.md), never the
+ * array shape those two callers check for, so widening `JUDGE_ROLES` itself
+ * would start demanding a declared-artifact line and a blocked Stop uiux was
+ * never designed to carry.
+ */
+export const JUDGE_TURN_ROLES = [...JUDGE_ROLES, 'uiux'];

package/factory/orchestrator/dist/judgeStopHook.js

@@ -0,0 +1,239 @@
+#!/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 judgeRoles.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
+ * `declaredArtifactLine.ts`, never redefined — in this clone the PreToolUse
+ * guard refuses, before dispatch, any judge dispatch whose prompt lacks an
+ * absolute line (and `dispatch lint` checks it against the ledger), 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.
+ *
+ * The hook reads the subagent's first non-meta user text -- its dispatch
+ * prompt -- from `agent_transcript_path`. Per
+ * https://code.claude.com/docs/en/hooks#subagentstop: "The `transcript_path`
+ * is the main session's transcript, while `agent_transcript_path` is the
+ * subagent's own transcript stored in a nested `subagents/` folder." Later
+ * user-role entries (meta reminders, resumes, compaction notices) are never
+ * the prompt. An older CLI that sends no `agent_transcript_path` falls back
+ * to `transcript_path`: the main session's first prompt, which carries no
+ * Declared line unless that session was itself dispatched as a judge, so the
+ * hook fails open there.
+ *
+ * SubagentStop stdin fields: https://code.claude.com/docs/en/hooks
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync } from 'node:fs';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { pathToFileURL } from 'node:url';
+import { roleOfAgentType } from './agentNames.js';
+import { parseDeclaredArtifactLine } from './declaredArtifactLine.js';
+import { JUDGE_ROLES } from './judgeRoles.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) {
+    // `bs-reviewer`, `blacksmith:bs-reviewer` and (transition) the bare old names
+    // all map to the role; a name that maps to nothing is not a judge.
+    const role = input.agent_type === undefined ? null : roleOfAgentType(input.agent_type);
+    if (role === null || !JUDGE_ROLE_SET.has(role)) {
+        // 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. The PreToolUse guard refuses this before dispatch in this clone, 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. The PreToolUse guard refuses this before dispatch in this clone, 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 text of the first non-meta user-role entry in a Claude Code JSONL
+ * transcript -- in a subagent's own transcript that is its dispatch prompt,
+ * where the "Declared artifact:" line lives; meta reminders, resumes, tool
+ * results and compaction notices all come after it or are skipped. Streams
+ * the file in fixed-size chunks (a transcript can pass 512 MB, where a
+ * whole-file read throws), splitting on `\n` only, and stops reading as soon
+ * as the prompt is found; work is linear in the bytes read because only the
+ * newly read chunk is scanned for line breaks. A torn or unparseable line is
+ * skipped. Returns `null` on any read failure or when no such entry exists.
+ */
+export function extractDispatchPromptText(transcriptPath, chunkSize = 64 * 1024) {
+    let fd;
+    try {
+        fd = openSync(transcriptPath, 'r');
+    }
+    catch {
+        return null;
+    }
+    const consume = (line) => {
+        if (line.trim() === '')
+            return null;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+        if (entry?.isMeta === true)
+            return null;
+        return userTextOf(entry);
+    };
+    try {
+        const buf = Buffer.alloc(chunkSize);
+        const decoder = new StringDecoder('utf8');
+        let carry = [];
+        for (;;) {
+            const n = readSync(fd, buf, 0, chunkSize, null);
+            if (n === 0)
+                break;
+            const chunk = decoder.write(buf.subarray(0, n));
+            let start = 0;
+            for (let nl = chunk.indexOf('\n'); nl !== -1; nl = chunk.indexOf('\n', start)) {
+                carry.push(chunk.slice(start, nl));
+                const found = consume(carry.join(''));
+                if (found !== null)
+                    return found;
+                carry = [];
+                start = nl + 1;
+            }
+            if (start < chunk.length)
+                carry.push(chunk.slice(start));
+        }
+        carry.push(decoder.end());
+        return consume(carry.join(''));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // nothing to do about a failed close
+        }
+    }
+}
+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",
+        };
+    }
+    // Older CLIs send no agent_transcript_path; the fallback then reads the
+    // main session's transcript, whose first prompt carries no declared line
+    // unless that session was itself dispatched as a judge, so the hook
+    // fails open there.
+    const promptPath = typeof input.agent_transcript_path === 'string' && input.agent_transcript_path !== ''
+        ? input.agent_transcript_path
+        : input.transcript_path;
+    const promptText = promptPath ? extractDispatchPromptText(promptPath) : 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();
+}