@expo/code-review-cli 0.9.1 → 0.10.0

package/build/core/claude-code.js

@@ -11,9 +11,9 @@ const CLAUDE_MAX_TURNS = 60;
 /** Fallback per-pass ceiling when a caller passes no maxWaitMs. */
 const DEFAULT_MAX_WAIT_MS = 8 * 60 * 1000;
 /**
- * A stateless `claude -p` pass emits no incremental tool lines to the caller, so a
- * long pass would look hung. Emit a "still working" heartbeat this often (matching
- * opencode.ts's HEARTBEAT_MS) to keep the progress signal alive.
+ * Emit a "still working" heartbeat after this long with no structured stream
+ * activity (matching opencode.ts's HEARTBEAT_MS), so a thinking stretch still has
+ * a progress signal between tool calls.
  */
 const CLAUDE_HEARTBEAT_MS = 45_000;
 /**
@@ -215,11 +215,13 @@ export function buildClaudeArgs(opts) {
     return [
         "-p",
         "--output-format",
-        "json",
+        "stream-json",
+        "--verbose",
         "--model",
         opts.model,
         "--append-system-prompt",
         opts.system,
+        ...(opts.jsonSchema ? ["--json-schema", JSON.stringify(opts.jsonSchema)] : []),
         ...(enabled.length > 0 ? ["--allowedTools", ...enabled.map(scope)] : []),
         "--disallowedTools",
         ...deniedReadTools,
@@ -232,6 +234,165 @@ export function buildClaudeArgs(opts) {
         String(opts.maxTurns ?? CLAUDE_MAX_TURNS),
     ];
 }
+const CLAUDE_STREAM_MISSING_RESULT = "Claude Code stream ended without a final result event";
+const CLAUDE_RESULT_MISSING_ERROR = "Claude Code returned an error without a message";
+function jsonRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** The final result object from either legacy single JSON or JSONL stream output. */
+function finalClaudeResult(stdout) {
+    try {
+        const parsed = jsonRecord(JSON.parse(stdout));
+        return parsed?.type === "result" ? parsed : null;
+    }
+    catch {
+        let result = null;
+        for (const line of stdout.split(/\r?\n/)) {
+            if (!line.trim()) {
+                continue;
+            }
+            try {
+                const event = jsonRecord(JSON.parse(line));
+                if (event?.type === "result") {
+                    result = event;
+                }
+            }
+            catch {
+                // A malformed/non-JSON line cannot be the structured final result.
+            }
+        }
+        return result;
+    }
+}
+const MAX_ACTIVITY_DETAIL = 180;
+/** Collapse control/newline injection and bound provider/model-originated log text. */
+function safeActivityDetail(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const withoutControls = [...value]
+        .map((char) => {
+        const code = char.charCodeAt(0);
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? " " : char;
+    })
+        .join("");
+    const clean = withoutControls.replace(/\s+/g, " ").trim();
+    if (!clean) {
+        return undefined;
+    }
+    return clean.length > MAX_ACTIVITY_DETAIL ? `${clean.slice(0, MAX_ACTIVITY_DETAIL - 1)}…` : clean;
+}
+/** Render an in-tree tool target without exposing attempted host paths. */
+function activityPath(value, cwd) {
+    const candidate = safeActivityDetail(value);
+    if (!candidate) {
+        return undefined;
+    }
+    const root = path.resolve(cwd);
+    const absolute = path.resolve(root, candidate);
+    if (absolute !== root && !pathInside(absolute, root)) {
+        return undefined;
+    }
+    const relative = path.relative(root, absolute).replace(/\\/g, "/");
+    return relative || ".";
+}
+/**
+ * Convert one Claude stream event into safe progress metadata. Raw assistant text,
+ * tool results, and grep patterns are deliberately never logged: PR/model content is
+ * untrusted and may contain secrets or terminal-control/log-injection payloads.
+ */
+// @ref LLP 0003#claude-code-cli-containment [implements] — stream only bounded lifecycle/tool metadata; raw model text and tool results never become progress logs
+export function claudeActivities(eventValue, cwd) {
+    const event = jsonRecord(eventValue);
+    if (!event) {
+        return [];
+    }
+    if (event.type === "system" && event.subtype === "init") {
+        const model = safeActivityDetail(event.model);
+        return [{ line: model ? `started ${model}` : "started" }];
+    }
+    if (event.type === "result") {
+        if (event.is_error === true) {
+            return [];
+        }
+        const duration = typeof event.duration_ms === "number"
+            ? `${Math.max(0, Math.round(event.duration_ms / 1000))}s`
+            : null;
+        const turns = typeof event.num_turns === "number" ? `${event.num_turns} turn(s)` : null;
+        const detail = [duration, turns].filter(Boolean).join(", ");
+        return [{ line: detail ? `completed (${detail})` : "completed" }];
+    }
+    if (event.type !== "assistant") {
+        return [];
+    }
+    const message = jsonRecord(event.message);
+    const content = Array.isArray(message?.content) ? message.content : [];
+    const activities = [];
+    for (const value of content) {
+        const block = jsonRecord(value);
+        if (block?.type !== "tool_use" || typeof block.name !== "string") {
+            continue;
+        }
+        const input = jsonRecord(block.input) ?? {};
+        const key = typeof block.id === "string" ? block.id : undefined;
+        if (block.name === "Read") {
+            const target = activityPath(input.file_path, cwd);
+            activities.push({ key, line: target ? `Read ${target}` : "Read" });
+        }
+        else if (block.name === "Grep") {
+            const target = activityPath(input.path, cwd);
+            activities.push({ key, line: target ? `Grep ${target}` : "Grep" });
+        }
+        else if (block.name === "Glob") {
+            const target = activityPath(input.path, cwd);
+            activities.push({ key, line: target && target !== "." ? `Glob ${target}` : "Glob" });
+        }
+    }
+    return activities;
+}
+/** Incremental JSONL decoder for Claude's stream-json stdout. */
+export function createClaudeActivityStream(cwd, onActivity) {
+    let buffered = "";
+    const reported = new Set();
+    const consume = (line) => {
+        if (!line.trim()) {
+            return;
+        }
+        try {
+            for (const activity of claudeActivities(JSON.parse(line), cwd)) {
+                if (activity.key && reported.has(activity.key)) {
+                    continue;
+                }
+                if (activity.key) {
+                    reported.add(activity.key);
+                }
+                onActivity(activity.line);
+            }
+        }
+        catch {
+            // Ignore malformed progress events; final result parsing still reports errors.
+        }
+    };
+    return {
+        push(chunk) {
+            buffered += chunk;
+            for (;;) {
+                const newline = buffered.indexOf("\n");
+                if (newline < 0) {
+                    break;
+                }
+                consume(buffered.slice(0, newline).replace(/\r$/, ""));
+                buffered = buffered.slice(newline + 1);
+            }
+        },
+        finish() {
+            consume(buffered);
+            buffered = "";
+        },
+    };
+}
 /**
  * The model that actually answered, out of the result's modelUsage keys. The CLI
  * also bills its own internal helper calls there (a haiku entry appears alongside
@@ -248,22 +409,26 @@ export function pickAnsweringModel(requested, modelOutputTokens) {
     return keys.sort((a, b) => (modelOutputTokens[b] ?? 0) - (modelOutputTokens[a] ?? 0))[0];
 }
 /**
- * Parse the `--output-format json` result object. Keys off `is_error` / a parse
+ * Parse the final result from `--output-format stream-json` JSONL (also accepts the
+ * former single JSON object for compatibility/tests). Keys off `is_error` / a parse
  * failure, NOT `subtype` — `subtype` stays `"success"` on some API errors.
  */
 export function parseClaudeResult(stdout) {
-    let parsed;
-    try {
-        parsed = JSON.parse(stdout);
-    }
-    catch {
+    const parsed = finalClaudeResult(stdout);
+    if (!parsed) {
+        // The stream may contain assistant text and tool results sourced from the
+        // untrusted review tree. Never turn that transcript into an error message or
+        // feed it to provider-error classification.
+        // @ref LLP 0003#claude-code-cli-containment [constrained-by] — raw JSONL transcript content must never reach logs or error classifiers
         return {
             text: "",
             cost: 0,
             tokens: {},
             modelOutputTokens: {},
             isError: true,
-            errorText: stdout.trim(),
+            errorText: CLAUDE_STREAM_MISSING_RESULT,
+            hasStructuredOutput: false,
+            structuredOutputFailure: false,
         };
     }
     const usage = (parsed.usage ?? {});
@@ -281,17 +446,41 @@ export function parseClaudeResult(stdout) {
     for (const [key, value] of Object.entries(modelUsage)) {
         modelOutputTokens[key] = num(value?.outputTokens) ?? 0;
     }
-    const result = typeof parsed.result === "string" ? parsed.result : "";
     const isError = parsed.is_error === true;
+    const hasStructuredOutput = parsed.structured_output !== undefined;
+    // `--json-schema` returns a provider-validated object in `structured_output`.
+    // Serialize it back through the existing local parser so Zod remains the final
+    // trust boundary. Ignore any stale/retracted structured value on an error result;
+    // error classification must use only the CLI's explicit final error message.
+    const structured = isError || parsed.structured_output === undefined
+        ? undefined
+        : JSON.stringify(parsed.structured_output);
+    const result = structured ?? (typeof parsed.result === "string" ? parsed.result : "");
     return {
         text: result,
         cost: num(parsed.total_cost_usd) ?? 0,
         tokens,
         modelOutputTokens,
         isError,
-        errorText: isError ? result || stdout.trim() : "",
+        // Only the final result event's explicit error text is safe to classify and
+        // surface. Falling back to stdout would expose the full JSONL transcript.
+        errorText: isError ? result || CLAUDE_RESULT_MISSING_ERROR : "",
+        hasStructuredOutput,
+        structuredOutputFailure: parsed.subtype === "error_max_structured_output_retries",
     };
 }
+/**
+ * A provider-side schema failure that spent tokens and may be retried once from a
+ * clean process. Carrying the attempt lets the caller retain honest run metrics.
+ */
+class ClaudeStructuredOutputError extends Error {
+    result;
+    constructor(result) {
+        super("Claude Code could not produce output matching the required JSON Schema");
+        this.result = result;
+        this.name = "ClaudeStructuredOutputError";
+    }
+}
 /** Classify a Claude Code failure so the caller can pick backoff vs. hard fail. */
 export function classifyClaudeError(errorText, apiStatus) {
     if (apiStatus === 401 || apiStatus === 403) {
@@ -365,6 +554,34 @@ export function claudeTemperatureNote(config, engineOf) {
             "(for the claude-routed passes)"
         : null;
 }
+/**
+ * Preserve actionable process diagnostics without copying arbitrary stderr into a
+ * public Actions log. A non-empty stream may already contain model/tool content, so
+ * stderr is not even classified in that case. With no stream, recognize only fixed
+ * CLI/setup categories and never interpolate the matched text.
+ */
+// @ref LLP 0003#claude-code-cli-containment [constrained-by] — stderr may reflect untrusted tree content; expose only exit metadata and fixed allowlisted categories
+function claudeExitDiagnostic(result) {
+    const exit = `Claude Code exited with code ${result.code}`;
+    if (result.stdout.trim() !== "") {
+        return exit;
+    }
+    if (/unknown (?:option|argument)|unrecognized option|unexpected argument/i.test(result.stderr)) {
+        return (`${exit}; the CLI rejected its arguments — verify the pinned ` +
+            "@anthropic-ai/claude-code version supports the configured flags");
+    }
+    if (/authentication|oauth|api.?key|unauthorized|\b401\b|\b403\b/i.test(result.stderr)) {
+        return (`${exit}; authentication failed before a result was emitted — check ` +
+            "`claude auth status` and `ecr doctor`");
+    }
+    if (/\bENOENT\b|command not found|no such file or directory/i.test(result.stderr)) {
+        return `${exit}; the Claude Code executable or one of its required files was not found`;
+    }
+    if (/\bEACCES\b/i.test(result.stderr)) {
+        return `${exit}; the Claude Code executable could not be launched due to permissions`;
+    }
+    return exit;
+}
 /**
  * One prompt → text/cost/tokens/model, as a single `claude -p` subprocess (the
  * Claude analogue of OpenCode's promptAgent; no sessions/polling).
@@ -380,12 +597,23 @@ export async function runClaudePrompt(handle, args) {
     // A soft tool-call ceiling doubles as the CLI's per-pass turn bound (the closest
     // stateless analogue of OpenCode's mid-run tool-call cap).
     const maxTurns = args.maxToolCalls != null && args.maxToolCalls > 0 ? args.maxToolCalls : undefined;
-    // A stateless `claude -p` pass streams nothing back, so emit a heartbeat while it
-    // runs or a long pass looks hung (cleared in finally, whatever the outcome).
+    // Stream safe structured activity. The heartbeat fires only after a quiet window,
+    // rather than on a fixed cadence that can land immediately after a tool line.
     const heartbeatStart = Date.now();
+    let lastStreamActivityAt = heartbeatStart;
+    const emitActivity = (line) => {
+        lastStreamActivityAt = Date.now();
+        args.onActivity?.(line);
+    };
+    const activityStream = args.onActivity
+        ? createClaudeActivityStream(process.cwd(), emitActivity)
+        : undefined;
     const heartbeat = args.onActivity
         ? setInterval(() => {
-            args.onActivity?.(`still working… ${Math.round((Date.now() - heartbeatStart) / 1000)}s elapsed`);
+            if (Date.now() - lastStreamActivityAt >= CLAUDE_HEARTBEAT_MS) {
+                args.onActivity?.(`still working… ${Math.round((Date.now() - heartbeatStart) / 1000)}s elapsed ` +
+                    `(no new activity for ${Math.round((Date.now() - lastStreamActivityAt) / 1000)}s)`);
+            }
         }, CLAUDE_HEARTBEAT_MS)
         : undefined;
     heartbeat?.unref?.();
@@ -397,15 +625,18 @@ export async function runClaudePrompt(handle, args) {
             cwd: process.cwd(),
             tools,
             maxTurns,
+            jsonSchema: args.jsonSchema,
         }), {
             input: args.text,
             env: handle.childEnv,
             cwd: process.cwd(),
             timeout: maxWaitMs,
             check: false,
+            onStdout: activityStream?.push,
         });
     }
     finally {
+        activityStream?.finish();
         if (heartbeat) {
             clearInterval(heartbeat);
         }
@@ -418,7 +649,7 @@ export async function runClaudePrompt(handle, args) {
     // A non-timeout signal is a crash (SIGSEGV, OOM SIGKILL, external kill), not a
     // timeout — surface it as a hard error rather than the subdivide/retry path.
     if (result.signal) {
-        throw new Error(`Claude Code was killed by signal ${result.signal}: ${result.stderr.trim() || "(no output)"}`);
+        throw new Error(`Claude Code was killed by signal ${result.signal}`);
     }
     // Truncated output can't be parsed as JSON; report the cause plainly instead of
     // letting it fall through as a generic parse failure.
@@ -426,6 +657,28 @@ export async function runClaudePrompt(handle, args) {
         throw new Error("claude output exceeded the 64MB buffer and was truncated");
     }
     const parsed = parseClaudeResult(result.stdout);
+    const answered = pickAnsweringModel(configuredModel, parsed.modelOutputTokens);
+    const model = answered
+        ? claudeModelMatches(configuredModel, answered)
+            ? configuredModel
+            : `anthropic/${answered}`
+        : configuredModel;
+    const promptResult = {
+        text: parsed.text,
+        cost: parsed.cost,
+        sessionID: "",
+        tokens: parsed.tokens,
+        model,
+    };
+    // A schema-requesting caller must receive the provider-validated object, never a
+    // parseable-looking fallback from `result`. Claude repairs schema mismatches in
+    // session first; its documented exhaustion result gets one clean-process retry in
+    // claudeCodePromptAndParse. A success that omits structured_output is treated the
+    // same way because it did not honor the requested provider contract.
+    if (args.jsonSchema &&
+        (parsed.structuredOutputFailure || (!parsed.isError && !parsed.hasStructuredOutput))) {
+        throw new ClaudeStructuredOutputError(promptResult);
+    }
     if (parsed.isError) {
         const kind = classifyClaudeError(parsed.errorText);
         if (kind === "rate-limit" || kind === "usage-limit") {
@@ -443,29 +696,26 @@ export async function runClaudePrompt(handle, args) {
                 "`claude setup-token`, set CLAUDE_CODE_OAUTH_TOKEN, and check `claude auth status` / " +
                 "`ecr doctor`.");
         }
-        throw new Error(parsed.errorText ||
-            `claude exited with code ${result.code}: ${result.stderr.trim() || result.stdout.trim() || "(no output)"}`);
+        const needsProcessDiagnostic = parsed.errorText === CLAUDE_STREAM_MISSING_RESULT ||
+            parsed.errorText === CLAUDE_RESULT_MISSING_ERROR;
+        throw new Error(needsProcessDiagnostic
+            ? `${parsed.errorText} (${claudeExitDiagnostic(result)})`
+            : parsed.errorText);
     }
-    const answered = pickAnsweringModel(configuredModel, parsed.modelOutputTokens);
-    const model = answered
-        ? claudeModelMatches(configuredModel, answered)
-            ? configuredModel
-            : `anthropic/${answered}`
-        : configuredModel;
-    return { text: parsed.text, cost: parsed.cost, sessionID: "", tokens: parsed.tokens, model };
+    return promptResult;
 }
 /**
- * The claude analogue of opencode.ts's CORRECTIVE. NOT shared: that one says
- * "your previous reply could not be parsed", which is true in OpenCode's
- * same-session follow-up but false here — each `claude -p` invocation is a fresh
- * stateless process with no previous reply to reference.
+ * Last-resort correction for a no-schema caller or disagreement between the
+ * provider's JSON Schema validator and our local parser. Production parsers pass
+ * `--json-schema`, so Claude Code already performs validation-aware repair inside
+ * the original session before this fresh-process fallback is needed.
  */
 const CLAUDE_CORRECTIVE = "\n\nIMPORTANT: reply with ONLY the single JSON object described above — no prose, " +
     "no code fences, no partial output.";
 /**
- * Prompt via the Claude Code CLI and parse the reply, mirroring OpenCode's
- * promptAndParse: transient retry on the first call, then one corrective re-run
- * (a fresh process — the diff is inlined, so re-read is a cache hit).
+ * Prompt via the Claude Code CLI and parse the provider-validated structured
+ * result locally. Transient failures retry first; a remaining local parse failure
+ * gets one fresh-process corrective as defense in depth.
  */
 export async function claudeCodePromptAndParse(handle, args, parse) {
     let cost = 0;
@@ -476,20 +726,42 @@ export async function claudeCodePromptAndParse(handle, args, parse) {
         addTokenUsage(tokens, result.tokens);
         model = result.model ?? model;
     };
-    const first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () => runClaudePrompt(handle, args));
-    record(first);
+    let first;
     try {
-        return { value: parse(first.text), cost, truncated: false, tokens, model };
-    }
-    catch {
-        const retry = await runClaudePrompt(handle, { ...args, text: args.text + CLAUDE_CORRECTIVE });
-        record(retry);
+        first = await withTransientRetry(`Agent "${args.agent}"`, args.onActivity, () => runClaudePrompt(handle, args));
+        record(first);
         try {
-            return { value: parse(retry.text), cost, truncated: false, tokens, model };
+            return { value: parse(first.text), cost, truncated: false, tokens, model };
+        }
+        catch {
+            // Provider validation and local Zod validation disagreed. Retry once from a
+            // clean process rather than accepting an object the trust boundary rejected.
         }
-        catch (finalError) {
-            throw new Error(`Agent "${args.agent}" did not return parseable JSON after retries: ${finalError instanceof Error ? finalError.message : String(finalError)}`);
+    }
+    catch (error) {
+        if (!(error instanceof ClaudeStructuredOutputError)) {
+            throw error;
+        }
+        record(error.result);
+        args.onActivity?.("structured output validation failed — retrying once");
+    }
+    let retry;
+    try {
+        retry = await runClaudePrompt(handle, { ...args, text: args.text + CLAUDE_CORRECTIVE });
+    }
+    catch (error) {
+        if (!(error instanceof ClaudeStructuredOutputError)) {
+            throw error;
         }
+        record(error.result);
+        throw new Error(`Agent "${args.agent}" could not satisfy its required JSON Schema after retries`);
+    }
+    record(retry);
+    try {
+        return { value: parse(retry.text), cost, truncated: false, tokens, model };
+    }
+    catch (finalError) {
+        throw new Error(`Agent "${args.agent}" did not return parseable JSON after retries: ${finalError instanceof Error ? finalError.message : String(finalError)}`);
     }
 }
 /**

package/build/core/config-refs.js

@@ -7,6 +7,7 @@ import { CONFIG_DIRNAME, stripJsonComments, stripTrailingCommas } from "../confi
 import { ROUTING_FILENAME } from "../config/routing.js";
 import { git, pathInside } from "./exec.js";
 import { matchesIgnore } from "./noise.js";
+import { isAmbientRuntimeConfig } from "./scrub.js";
 /**
  * Built by concatenation so this module's own regexes and doc comments are not
  * themselves collected as refs by a scanner (the repo's `ref-check` does the same).
@@ -40,6 +41,7 @@ const CITATION_EXTENSIONS = new Set([
     ".css",
     ".go",
     ".graphql",
+    ".hcl",
     ".h",
     ".hpp",
     ".html",
@@ -63,6 +65,8 @@ const CITATION_EXTENSIONS = new Set([
     ".sh",
     ".sql",
     ".swift",
+    ".tf",
+    ".tfvars",
     ".toml",
     ".ts",
     ".tsx",
@@ -608,10 +612,11 @@ export async function checkConfigRefs(options) {
     // Does an extensionless token name something real? Cached: prompts repeat the same
     // paths, and each miss would otherwise cost a stat per occurrence.
     const resolvable = new Map();
-    /** The root-relative path an extensionless token names, or null if it names nothing. */
+    /** The root-relative path a token names, or null. Scope first: a scoped prompt
+     * citing `alerts/` means its own tree even when the root has one too. */
     const namedPath = async (token, scopeRoot) => {
         for (const candidate of pathishCandidates(token)) {
-            for (const base of [root, scopeRoot]) {
+            for (const base of [scopeRoot, root]) {
                 const absolute = path.resolve(base, candidate);
                 let resolved = resolvable.get(absolute);
                 if (resolved === undefined) {
@@ -630,6 +635,18 @@ export async function checkConfigRefs(options) {
         }
         return null;
     };
+    /** The glob a wildcard token names, rebased onto the scope when that is what
+     * matches, so the suggested `glob:` ref actually resolves. */
+    const namedGlob = (token, scopeRoot) => {
+        const scopeRel = path.relative(root, scopeRoot).split(path.sep).join("/");
+        const candidates = [...(scopeRel && scopeRel !== "." ? [`${scopeRel}/${token}`] : []), token];
+        for (const candidate of candidates) {
+            if (index.files.some((file) => matchesIgnore(file, candidate))) {
+                return candidate;
+            }
+        }
+        return null;
+    };
     for (const dir of dirs) {
         const scopeRoot = path.dirname(dir);
         for (const file of await setupFiles(dir)) {
@@ -658,6 +675,7 @@ export async function checkConfigRefs(options) {
                         line: ref.line,
                         kind: problem.startsWith("cites a line number") ? "line-number-ref" : "broken-ref",
                         problem,
+                        target: ref.target,
                     });
                     continue;
                 }
@@ -674,18 +692,15 @@ export async function checkConfigRefs(options) {
                 }
             }
             for (const { line, token } of findProseCitations(text)) {
-                // Extension or wildcard tail ⇒ a citation on shape alone. Otherwise it only
-                // counts if it names something real: `eas-build-worker/terraform` and
-                // `general-central/{module,production}` are paths, `anthropic/claude-opus-5`
-                // is shaped identically and is not.
-                const named = isCodeCitation(token) ? null : await namedPath(token, scopeRoot);
+                const isWild = token.includes("*");
+                const named = isWild ? namedGlob(token, scopeRoot) : await namedPath(token, scopeRoot);
+                // Shape alone makes a citation; otherwise it must name something real, or
+                // `anthropic/claude-opus-5` would read as a path.
                 if (!isCodeCitation(token) && !named) {
                     continue;
                 }
-                // Coverage must accept the path the token RESOLVED to, not just the token as
-                // written: a prompt says `cert-manager` and the ref that pins it is
-                // `infrastructure/cert-manager/`. Without this, the fix the message suggests
-                // does not silence the citation it was suggested for.
+                // Coverage accepts the resolved path too, else the only ref that silences a
+                // scope-relative citation is an over-broad `glob:**/<basename>`.
                 const forms = [...citationForms(token), ...(named ? coveringForms(named) : [])];
                 if (ignored.has(token) ||
                     forms.some((form) => covered.has(form)) ||
@@ -693,9 +708,12 @@ export async function checkConfigRefs(options) {
                     continue;
                 }
                 const lineCitation = LINE_CITATION_RE.exec(token);
-                // For an extensionless token the suggestion is the path that actually resolved,
-                // which is also how a scope-relative citation learns its root-relative form.
-                const suggestion = named ?? suggestedRef(token);
+                // A wildcard token means the family; anything else gets the precise resolved path.
+                const suggestion = isWild
+                    ? named
+                        ? `${GLOB_PREFIX}${named}`
+                        : suggestedRef(token)
+                    : (named ?? suggestedRef(token));
                 problems.push({
                     file: relative,
                     line,
@@ -703,6 +721,7 @@ export async function checkConfigRefs(options) {
                     problem: lineCitation
                         ? `\`${token}\` pins a line number; cite the file or a \`#symbol\` instead, as \`${REF_MARK} ${suggestedRef(lineCitation[1])}\``
                         : `\`${token}\` cites code without a ref; add \`${REF_MARK} ${suggestion} — why it matters\` (or \`${IGNORE_MARK} ${token}\` if it is not a path)`,
+                    target: token,
                 });
             }
         }
@@ -724,6 +743,12 @@ export async function checkConfigRefs(options) {
         citedPaths: [...citedPaths].sort(),
     };
 }
+/** The file a target names, with any `glob:` prefix, `#anchor` or `:line` stripped. */
+function citedBasename(target) {
+    const withoutPrefix = target.startsWith(GLOB_PREFIX) ? target.slice(GLOB_PREFIX.length) : target;
+    const withoutLine = LINE_CITATION_RE.exec(withoutPrefix)?.[1] ?? withoutPrefix;
+    return path.basename(splitAnchor(withoutLine)[0]);
+}
 /** How many examples a review-side note names before saying "and N more". */
 const NOTE_EXAMPLES = 5;
 function andMore(items) {
@@ -746,7 +771,11 @@ export async function reviewSetupRefNotes(options) {
         return []; // a check that cannot run must never degrade the review
     }
     const notes = [];
-    const broken = report.problems.filter((problem) => problem.kind !== "unannotated-citation");
+    // The read root is scrubbed of ambient runtime config (AGENTS.md, CLAUDE.md, .env…),
+    // so a ref to one is missing by design here, not stale. The template itself cites
+    // AGENTS.md, which would make this note cry wolf on every PR.
+    const broken = report.problems.filter((problem) => problem.kind !== "unannotated-citation" &&
+        !(problem.target && isAmbientRuntimeConfig(citedBasename(problem.target))));
     if (broken.length > 0) {
         notes.push(`The reviewer setup cites code that no longer resolves (${broken.length} ref(s)): ` +
             `${andMore(broken.map((problem) => `${problem.file}:${problem.line}`))}. ` +

package/build/core/coordinator.js

@@ -9,7 +9,7 @@ import { parseCoordinatorOutput } from "./schema.js";
 // cap is a backstop. It runs AFTER all passes, so this adds to the worst-case
 // serial chain — keep it within the CI job timeout (see review.ts / workflows).
 const COORDINATOR_TIMEOUT_MS = 10 * 60 * 1000;
-export async function coordinate(handle, config, metadata, agentFindings, coverageNotes = [], stackManifest) {
+export async function coordinate(handle, config, metadata, agentFindings, coverageNotes = [], stackManifest, onActivity) {
     const system = buildCoordinatorSystem(config);
     const text = buildCoordinatorTask(metadata, agentFindings, coverageNotes, stackManifest);
     const { value, cost, tokens, truncated, model } = await promptAndParse(handle, {
@@ -19,6 +19,7 @@ export async function coordinate(handle, config, metadata, agentFindings, covera
         title: "review-coordinator",
         maxWaitMs: COORDINATOR_TIMEOUT_MS,
         finalizeOnTimeout: true,
+        onActivity,
     }, parseCoordinatorOutput);
     return { output: value, cost, tokens, truncated, model };
 }

package/build/core/exec.js

@@ -161,7 +161,17 @@ function runWithInput(command, args, options, input) {
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         child.stdout.on("data", (chunk) => {
+            const before = stdout.length;
             stdout = cap(stdout, chunk);
+            const admitted = stdout.length - before;
+            if (admitted > 0 && options.onStdout) {
+                try {
+                    options.onStdout(chunk.slice(0, admitted));
+                }
+                catch {
+                    // Observability must never break the command whose output it observes.
+                }
+            }
         });
         child.stderr.on("data", (chunk) => {
             stderr = cap(stderr, chunk);