codecartographer-pi 0.24.1 → 0.26.0

package/.codecarto/broadside/SKILL.md

@@ -35,6 +35,10 @@ not replace any phase; it tells phases where to look.
    it describes), **discarded** (the claim is wrong about the code, with the
    guard or line that shows it), or **unclear**. Start from the confirmed
    ones; treat a discarded one as answered unless the reasoning is thin.
+   Then make sure the work order was built from it: `status` shows
+   `triage: completed (built from N verdicts)`; if it says `(no verdicts)`,
+   run `collect --regenerate` (`regenerate_post_passes: true`) before
+   reading `triage.md`.
    Measured on this repository, the top twelve findings by severity were two
    real defects and ten that a look at the guard, the caller, or the tsconfig
    dismissed — the pass agreed with a reviewer on all twelve for about a cent
@@ -85,6 +89,7 @@ Broad-Side is an executable-surface feature. On the Pi extension:
 /codecarto-broadside status             # show recorded runs
 /codecarto-broadside models             # compare batch models
 /codecarto-broadside verify --top=10    # read the top findings against the source
+/codecarto-broadside collect --regenerate  # rebuild synthesis and triage from the verdicts
 ```
 
 On the MCP server:
@@ -95,6 +100,7 @@ codecarto_broadside {cwd, action: "collect"}                  # poll, save, synt
 codecarto_broadside {cwd, action: "status"}                   # show recorded runs
 codecarto_broadside {cwd, action: "models"}                   # compare batch models
 codecarto_broadside {cwd, action: "verify", top: 10}          # read the top findings against the source
+codecarto_broadside {cwd, action: "collect", regenerate_post_passes: true}   # rebuild synthesis and triage from the verdicts
 ```
 
 The `models` action lists every `:batch` variant on OpenRouter — pricing per
@@ -139,6 +145,16 @@ cap here, since a sync call's cost is known only when it returns: the pass
 stops before the next finding once the calls so far have reached it and
 reports `partial`. About a cent a finding on the default model.
 
+The post-passes read the verdicts when they exist: a synthesis or triage
+built after a `verify` ranks the confirmed findings first, drops the
+discarded ones, lists the not-a-defect ones apart in `omitted`, and says in
+its summary how many verdicts it was built from; `status` and the collect
+report show `(built from N verdicts)` or `(no verdicts)` on each pass. A run
+collected before it was verified has a work order built from batch
+severities alone — `collect --regenerate` (`regenerate_post_passes: true`)
+resets the settled passes and runs them again with the verdicts, for another
+post-pass pair's cost; a pass still in flight is left to finish.
+
 Two caveats apply to any model you pick. The `models` action lists every id
 OpenRouter advertises a `:batch` variant for, and many of those variants do not
 exist — submitting one returns `does not have a :batch endpoint`, with nothing in
@@ -206,7 +222,10 @@ is about the *presence* of a hardcoded credential at that location; the
 value was never sent. This is a safety net against an accidental upload
 with deliberately low-false-positive patterns, not a secret scanner:
 anything it does not recognise goes as written. `redact_secrets: false` in
-`config.yaml` turns the content pass off (the by-name skip stays).
+`config.yaml` turns the content pass off (the by-name skip stays). The same
+pass runs over every line `verify`'s read-only tools hand the model — a key in
+an ordinary source file is exactly what a finding points a verifier at — and
+the verify report says how many values it redacted.
 
 The `max_cost` guardrail is an **estimate-based pre-flight limit**, distinct
 from OpenRouter's runtime cost tracking: it predicts from file sizes before

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.24.1
+scaffold_version: 0.26.0

package/README.md

@@ -20,7 +20,7 @@
 ```
 
 <p align="center">
-  <img src="docs/demo-dashboard-hero.png" alt="CodeCartographer dashboard — a mid-run pipeline with architecture and defect-scan phases complete, contracts in progress, per-phase token and tool-use telemetry.">
+  <img src="docs/demo-dashboard-hero.png" alt="CodeCartographer's dashboard after running the full deep-audit pipeline on its own repository — 7/7 phases complete, 50M tokens and 618 tool uses across 77 minutes, seven open questions and twelve post-pipeline items routed, no blocking artifact gaps.">
 </p>
 
 ---
@@ -305,7 +305,7 @@ Beyond the slash commands, the Pi extension layers on:
 
 **Per-phase usage tracking.** Each phase run is appended to `.codecarto/workflow/.usage.local.yaml`. `/codecarto-usage` reports cumulative + per-phase token, runtime, tool-use, and compaction totals, including threshold/overflow/manual triggers and successful/failed/aborted outcomes.
 
-**Tool interception.** `bash` is blocked outright; `edit` and `write` are confined to `.codecarto/`, plus the configured, marker-validated CodeCartographer library when one is configured. Same rules apply to phase sub-agents.
+**Tool interception.** `bash` is blocked outright; `edit` and `write` are confined to `.codecarto/`, plus the configured, marker-validated CodeCartographer library when one is configured. Phase sub-agents get the same hook over a narrower root — `.codecarto/` alone, since a phase writes findings and handoffs and never publishes.
 
 ### Slash commands
 
@@ -395,15 +395,16 @@ codecarto_broadside {cwd, action: "submit", lenses: [...]}    # fire the batches
 codecarto_broadside {cwd, action: "status"}                   # what is in flight
 codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
 codecarto_broadside {cwd, action: "verify", top: 10}          # read the top findings against the source
+codecarto_broadside {cwd, action: "collect", regenerate_post_passes: true}   # rebuild the report and work order from the verdicts
 ```
 
-A third action, `verify`, reads the top defect and security findings of a collected run against the real source — one sync-priced call each with read-only tools (`read_file`, `grep`, `list_dir`) confined to the repository — and writes `verified.md` with a verdict per finding: **confirmed** (a reachable failure, with the trigger), **not-a-defect**, **discarded**, or **unclear**. Measured on this repository, the top twelve findings by severity were two real defects and ten claims a look at the guard or the caller dismissed; the pass agreed with a reviewer on all twelve for a cent a finding. Read `verified.md` before `triage.md`.
+A third action, `verify`, reads the top defect and security findings of a collected run against the real source — one sync-priced call each with read-only tools (`read_file`, `grep`, `list_dir`) confined to the repository — and writes `verified.md` with a verdict per finding: **confirmed** (a reachable failure, with the trigger), **not-a-defect**, **discarded**, or **unclear**. Measured on this repository, the top twelve findings by severity were two real defects and ten claims a look at the guard or the caller dismissed; the pass agreed with a reviewer on all twelve for a cent a finding. Read `verified.md` before `triage.md` — and have `triage.md` built from it: the synthesis and triage passes rank on the verdicts when they exist (confirmed first, discarded dropped, not-a-defect listed apart), and `collect` with `regenerate_post_passes: true` (`--regenerate` on Pi) rebuilds both for a run that was collected before it was verified.
 
 Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight (`wait_seconds: 0`, the default, polls once and returns), and two collects on one run — a retried tool call, a second session — never pay for the synthesis, triage, or truncation retry twice: each is claimed in the run's state before it is submitted, and a collect whose client has gone away stops polling and submits nothing further. Submit prices the run from the collected file sizes against the model's live per-token pricing (cached 24h) and refuses when the estimate exceeds `max_cost` — $1.00 unless the config or the call sets another value, `0` for no limit — unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
 
 Repository defaults live in `.codecarto/broadside/config.yaml` (`model`, `api_key`, `default_lenses`, `max_cost`, `pricing` overrides, `lens_models`, `incremental`, `retry_truncated`, `include_synthesis`, `include_triage`, `wait_seconds`); an explicit tool parameter always wins. `lens_models` routes individual lenses to their own batch model — a stronger model changes security and defect findings far more than it changes an architecture map — and each override is priced, capability-checked, and clamped exactly like the default, with the estimate broken out per lens so a mixed-model run cannot be approved without seeing which lens costs what. CodeCartographer ships no stronger default: which model earns its price depends on your repository and budget, so compare candidates with the `models` action and choose — for one run with the `model` and `lens_models` parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or for the repository in `config.yaml`. The `models` listing is advisory: OpenRouter's catalog returns a `:batch` id for some models its Batch API then refuses (`does not have a :batch endpoint`), at no cost, and nothing in the catalog tells them apart — so the listing tags the ids this repository's own submits have seen accepted or refused, and a refused lens says why in the submit report. `codecarto_skill {cwd, name: "broadside"}` returns the reading guide for a completed run, and unlike post-pipeline skills it is not gated on a finished pipeline.
 
-On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N]`, with tab-completion for actions, lens names, and flags and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
+On the Pi extension the same run is `/codecarto-broadside [submit|collect|status|models|verify] [lenses…] [--model=ID] [--lens-model=LENS:ID] [--top=N] [--regenerate]`, with tab-completion for actions, lens names, and flags and live per-lens progress while batches poll. The two surfaces differ in one deliberate place: MCP cannot ask a human, so it refuses a run over `max_cost` until you pass `force`; Pi shows the per-lens breakdown and asks, and your approval *is* the force flag. Neither surface takes an API key as a command argument — a key typed into a slash command lands in the session transcript.
 
 Broad-Side needs runtime code, so firing a run is an executable-surface feature: Pi and MCP have it, the pure drop-in template does not (it carries only the reading guide).
 

package/agent-skill/codecartographer/references/broadside.md

@@ -99,7 +99,11 @@ Results land in `.codecarto/broadside/<run>/`. If `verified.md` is there, read
 it before anything else: `action: "verify"` has read the top defect and
 security findings against the source with read-only tools and given each a
 verdict (confirmed with its trigger, not-a-defect, discarded with the guard
-that shows it, unclear). Then, in this order:
+that shows it, unclear). The post-passes rank on those verdicts when they
+exist; a run collected before it was verified has a work order built from
+batch severities alone (`status` says `(no verdicts)`), and
+`action: "collect", regenerate_post_passes: true` rebuilds both passes from
+the verdicts for another post-pass pair's cost. Then, in this order:
 
 1. `synthesis.md` — executive summary, severity counts, top cross-lens
    findings, per-module risk.

package/dist/core/broadside/client.d.ts

@@ -0,0 +1,56 @@
+import { type BroadsideLensId } from "./constants.ts";
+import { type BatchRequest } from "./types.ts";
+export type FetchLike = (url: string, init: Record<string, unknown>) => Promise<Response>;
+export declare function submitBatch(batchRequests: BatchRequest[], apiKey: string, fetcher?: FetchLike, model?: string): Promise<{
+    batchId: string;
+    status: string;
+    error?: unknown;
+}>;
+export declare function fetchBatch(batchId: string, apiKey: string, fetcher?: FetchLike): Promise<Record<string, unknown>>;
+export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
+    deadlineMs?: number;
+    onStatus?: (status: string, counts: Record<string, unknown>) => void;
+    fetcher?: FetchLike;
+    pollIntervalMs?: number;
+    /**
+     * Stops polling early with the same synthetic `timeout` a spent budget
+     * returns: the batch keeps running server-side and a later collect
+     * claims it. The MCP server aborts when its client disconnects (#322).
+     */
+    signal?: AbortSignal;
+}): Promise<Record<string, unknown>>;
+/**
+ * Poll several batch ids in parallel against one shared deadline. Collect
+ * previously polled one lens at a time, so a slow first lens serialized the
+ * wall clock for lenses that had already finished server-side (#136). The
+ * onStatus callback identifies the lens so progress output stays readable
+ * even while the polls interleave.
+ */
+export declare function pollBatchesConcurrently(entries: Array<{
+    lensId: BroadsideLensId;
+    batchId: string;
+}>, apiKey: string, opts?: {
+    deadlineMs?: number;
+    fetcher?: FetchLike;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    onStatus?: (lensId: string, status: string, counts: Record<string, unknown>) => void;
+}): Promise<Map<string, Record<string, unknown>>>;
+export declare const NO_BATCH_ENDPOINT_RE: RegExp;
+/** The refusal for a full per-account concurrent batch-job quota. */
+export declare const BATCH_QUOTA_RE: RegExp;
+/** One line of a batch's error field, whatever shape the provider gave it. */
+export declare function describeBatchError(error: unknown): string | null;
+/**
+ * A provider refusal plus what to do about it, for the two refusals a batch
+ * run meets in practice and cannot fix by itself (#141):
+ *
+ * - `Model '<id>' does not have a :batch endpoint.` — the catalog advertises a
+ *   `:batch` id that OpenRouter runs no batch endpoint for. Nothing in the
+ *   catalog distinguishes these; the `models` action marks ids this
+ *   repository has seen refused.
+ * - `job-submission-count … in use: 16, quota: 16` — the per-account limit
+ *   on concurrent batch jobs. Broad-Side submits one job per lens, so a few
+ *   runs in flight on the same key fill it; the refusal costs nothing.
+ */
+export declare function explainBatchError(error: unknown): string | null;

package/dist/core/broadside/client.js

@@ -0,0 +1,200 @@
+// The OpenRouter Batch API client: submit, fetch, poll one or many batches to a terminal status.
+//
+// Split out of core/broadside.ts (#339); the barrel there re-exports every
+// name, so `core/index.ts` and the tests see one module as before.
+import { sleep } from "../utils.js";
+import { BROADSIDE_BATCH_URL, BROADSIDE_DEAD_BATCH_STATUSES, BROADSIDE_DEFAULT_POLL_BUDGET_MS, BROADSIDE_MODEL, BROADSIDE_POLL_INTERVAL_MS } from "./constants.js";
+export async function submitBatch(batchRequests, apiKey, fetcher = fetch, model = BROADSIDE_MODEL) {
+    // The OpenRouter batch endpoint stream-parses the body and requires
+    // `endpoint` and `model` to serialize before `requests` — key order matters.
+    const payload = {
+        endpoint: "/v1/chat/completions",
+        model,
+        requests: batchRequests,
+    };
+    const resp = await fetcher(BROADSIDE_BATCH_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const data = (await resp.json());
+    if (resp.status !== 202) {
+        return { batchId: "", status: "rejected", error: data };
+    }
+    return { batchId: String(data.id), status: String(data.status) };
+}
+export async function fetchBatch(batchId, apiKey, fetcher = fetch) {
+    const resp = await fetcher(`${BROADSIDE_BATCH_URL}/${batchId}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: AbortSignal.timeout(30_000),
+    });
+    let data;
+    try {
+        data = (await resp.json());
+    }
+    catch (error) {
+        // A gateway error page is not JSON. It used to throw out of here and
+        // be retried as if the network were down; keep the status instead.
+        data = { error: `non-JSON response (${error instanceof Error ? error.message : String(error)})` };
+    }
+    if (!data || typeof data !== "object")
+        data = { error: "empty response" };
+    // Surface the HTTP status so the poller can bail fast on auth expiry
+    // instead of retrying a dead key for the whole budget.
+    data.http_status = resp.status;
+    return data;
+}
+export async function pollBatchUntilTerminal(batchId, apiKey, opts = {}) {
+    const deadline = Date.now() + (opts.deadlineMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS);
+    const intervalMs = opts.pollIntervalMs ?? BROADSIDE_POLL_INTERVAL_MS;
+    const fetcher = opts.fetcher ?? fetch;
+    // A poll that runs out of budget without one good response is not a slow
+    // batch. The last thing that went wrong rides on the timeout so the report
+    // can tell a dead network or a failing gateway from a batch still running.
+    let lastError = null;
+    let sawBatch = false;
+    const timedOut = () => ({
+        id: batchId,
+        status: "timeout",
+        ...(lastError && !sawBatch && { error: `no successful poll response; last error: ${lastError}` }),
+        ...(lastError && sawBatch && { last_error: lastError }),
+    });
+    for (;;) {
+        if (opts.signal?.aborted)
+            return { ...timedOut(), aborted: true };
+        let batch;
+        try {
+            batch = await fetchBatch(batchId, apiKey, fetcher);
+        }
+        catch (error) {
+            lastError = `fetch failed (${error instanceof Error ? error.message : String(error)})`;
+            if (Date.now() >= deadline)
+                return timedOut();
+            await sleep(intervalMs);
+            continue;
+        }
+        const httpStatus = Number(batch.http_status ?? 200);
+        if (httpStatus === 401 || httpStatus === 403) {
+            return { id: batchId, status: "auth-failed", error: batch.error ?? batch };
+        }
+        if (httpStatus >= 400) {
+            // A gateway or server error: retry within the budget, remembered.
+            const detail = typeof batch.error === "string" ? batch.error : JSON.stringify(batch.error ?? "");
+            lastError = `HTTP ${httpStatus}${detail ? ` (${detail.slice(0, 200)})` : ""}`;
+            if (Date.now() >= deadline)
+                return timedOut();
+            await sleep(intervalMs);
+            continue;
+        }
+        sawBatch = true;
+        const status = String(batch.status ?? "unknown");
+        const counts = (batch.request_counts ?? {});
+        opts.onStatus?.(status, counts);
+        if (status === "completed" || BROADSIDE_DEAD_BATCH_STATUSES.includes(status))
+            return batch;
+        if (Date.now() >= deadline)
+            return timedOut();
+        await sleepUnlessAborted(intervalMs, opts.signal);
+    }
+}
+/** Sleep, but wake at once when the signal fires so an abort is not a poll interval late. */
+function sleepUnlessAborted(ms, signal) {
+    if (!signal)
+        return sleep(ms);
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Poll several batch ids in parallel against one shared deadline. Collect
+ * previously polled one lens at a time, so a slow first lens serialized the
+ * wall clock for lenses that had already finished server-side (#136). The
+ * onStatus callback identifies the lens so progress output stays readable
+ * even while the polls interleave.
+ */
+export async function pollBatchesConcurrently(entries, apiKey, opts = {}) {
+    const results = new Map();
+    const deadlineMs = opts.deadlineMs ?? BROADSIDE_DEFAULT_POLL_BUDGET_MS;
+    await Promise.all(entries.map(async ({ lensId, batchId }) => {
+        const batch = await pollBatchUntilTerminal(batchId, apiKey, {
+            deadlineMs,
+            fetcher: opts.fetcher,
+            pollIntervalMs: opts.pollIntervalMs,
+            signal: opts.signal,
+            onStatus: (status, counts) => opts.onStatus?.(lensId, status, counts),
+        });
+        results.set(batchId, batch);
+    }));
+    return results;
+}
+// ---------- provider errors ----------
+export const NO_BATCH_ENDPOINT_RE = /does not have a :batch endpoint/i;
+/** The refusal for a full per-account concurrent batch-job quota. */
+export const BATCH_QUOTA_RE = /job-submission-count/i;
+/** One line of a batch's error field, whatever shape the provider gave it. */
+export function describeBatchError(error) {
+    if (error === undefined || error === null || error === "")
+        return null;
+    if (typeof error === "string")
+        return error.slice(0, 300);
+    if (typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string" && message)
+            return message.slice(0, 300);
+        // OpenRouter wraps a submit refusal as `{ error: { message } }`.
+        const nested = error.error;
+        if (nested && typeof nested === "object") {
+            const inner = nested.message;
+            if (typeof inner === "string" && inner)
+                return inner.slice(0, 300);
+        }
+        if (typeof nested === "string" && nested)
+            return nested.slice(0, 300);
+        try {
+            return JSON.stringify(error).slice(0, 300);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    return String(error);
+}
+/**
+ * A provider refusal plus what to do about it, for the two refusals a batch
+ * run meets in practice and cannot fix by itself (#141):
+ *
+ * - `Model '<id>' does not have a :batch endpoint.` — the catalog advertises a
+ *   `:batch` id that OpenRouter runs no batch endpoint for. Nothing in the
+ *   catalog distinguishes these; the `models` action marks ids this
+ *   repository has seen refused.
+ * - `job-submission-count … in use: 16, quota: 16` — the per-account limit
+ *   on concurrent batch jobs. Broad-Side submits one job per lens, so a few
+ *   runs in flight on the same key fill it; the refusal costs nothing.
+ */
+export function explainBatchError(error) {
+    const message = describeBatchError(error);
+    if (!message)
+        return null;
+    if (NO_BATCH_ENDPOINT_RE.test(message)) {
+        return `${message} — the catalog lists this id, but OpenRouter runs no batch endpoint for it. Nothing was charged; pick another model (the models action marks ids this repository has seen refused).`;
+    }
+    if (BATCH_QUOTA_RE.test(message)) {
+        return `${message} — OpenRouter's per-account limit on concurrent batch jobs is full. Broad-Side submits one job per lens, so a few runs in flight on this key (in any repository) fill it. Nothing was charged; collect or wait out the runs in flight, then re-submit.`;
+    }
+    return message;
+}

package/dist/core/broadside/collect.d.ts

@@ -0,0 +1,68 @@
+import { type BroadsideCollectResult, type BroadsideStateFile } from "./types.ts";
+import { type FetchLike } from "./client.ts";
+/**
+ * One verdict from a run's `verified.json` (written by the verify pass in
+ * `verify.ts`), reduced to what the post-passes are told.
+ */
+export type PostPassVerdict = {
+    lensId: string;
+    customId: string;
+    severity: string;
+    title: string;
+    location: string;
+    verdict: string;
+    confidence: string;
+    evidence: Array<{
+        file: string;
+        lines: string;
+        note: string;
+    }>;
+    reasoning: string;
+};
+/**
+ * The verdicts a verify pass left in the run directory, or null when none
+ * has run (#338). A file that does not parse is treated as absent: the
+ * post-passes then run from the findings alone, which is what they did
+ * before verdicts existed, and `status` shows the pass carried no verdicts.
+ */
+export declare function loadPostPassVerdicts(runDir: string): Promise<PostPassVerdict[] | null>;
+/**
+ * The verdicts as a section of the post-pass user message: one line per
+ * finding with the verdict, the evidence the verifier cited, and its
+ * reasoning, so the pass can rank on them rather than on the batch model's
+ * own severities (#338).
+ */
+export declare function renderPostPassVerdicts(verdicts: PostPassVerdict[]): string;
+export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?: {
+    waitMs?: number;
+    includeSynthesis?: boolean;
+    includeTriage?: boolean;
+    /** Re-submit truncated slices once with a doubled output cap (#133). */
+    retryTruncated?: boolean;
+    onStatus?: (lensId: string, status: string, counts: Record<string, unknown>) => void;
+    fetcher?: FetchLike;
+    /**
+     * Which run to collect. Absent, the most recent — which used to be the
+     * only choice, so an older run still in flight could not be collected
+     * once a newer submit existed (#268). `status` lists the ids.
+     */
+    runId?: string;
+    /**
+     * Stops polling and submits nothing further once fired; what was
+     * already submitted keeps running server-side for a later collect to
+     * claim. The MCP server fires it when its client disconnects (#322).
+     */
+    signal?: AbortSignal;
+    /** Poll cadence override; tests drive the loop faster than 15 s. */
+    pollIntervalMs?: number;
+    /**
+     * Reset the wanted post-passes of a collected run and run them again
+     * (#338) — after a `verify`, so the executive report and the work order
+     * are built from the verdicts. A pass still in flight is left to finish;
+     * a run whose lens batches are still running is refused.
+     */
+    regeneratePostPasses?: boolean;
+}): Promise<BroadsideCollectResult>;
+export declare function runBroadsideStatus(cwd: string): Promise<{
+    state: BroadsideStateFile;
+}>;