codecartographer-pi 0.20.0 → 0.22.0

package/.codecarto/GUIDE.md

@@ -81,7 +81,7 @@ Some files in this workspace are **read-only instructions** and must not be modi
 | Scaffold version stamp (framework-owned) | `workflow/scaffold-version.yaml` | Written at release, copied by init. The framework compares it to its own version to warn about stale scaffolds. Never edit. |
 | Findings (read-write) | `findings/<phase>/<primary-output>.md`, secondary output files | Create and update during phases. |
 | Phase handoff (read-write) | `scratch/handoffs/<phase>.yaml` | Phase executors propose state changes and closeout content here. The framework validates and applies them. |
-| Closeouts (framework-owned) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Completion writes or updates one canonical closeout and one idempotent index entry. |
+| Closeouts (framework-owned) | `closeouts/<date>-<phase-or-module>.md`, `THREAD_LOG.md` | Completion writes or updates one canonical closeout and one idempotent index entry. `<date>` and every other date the framework writes is the UTC calendar day; a date you write yourself (a `**Validated by:**` line, a decision) should be UTC too, or a late-evening session dates its validation a day before its closeout. |
 | Conventions (orchestrator-maintained) | `CONVENTIONS.md` | Cross-cutting patterns promoted to project-wide invariants. Phase executors propose; the orchestrator promotes at the phase boundary — in inline runs, the same chat changing hats. |
 | Decisions (orchestrator-maintained, append-only) | `DECISIONS.md` | Numbered log of decisions that diverge from spec, prompt, or obvious-default. Completion appends each handoff's `decisions` under `## Completion log`; the orchestrator may re-file entries into categories. |
 | Backlog (orchestrator-maintained) | `BACKLOG.md` | Work this project decided to **defer**, with the reasoning, the preconditions for revisiting, and the smallest viable form. Seeded from `templates/backlog-project.md` at init. |

package/.codecarto/broadside/SKILL.md

@@ -108,7 +108,14 @@ architecture map. Each override is priced, capability-checked, and clamped like
 the default, the submit estimate breaks cost out per lens, and `run-meta.json`
 records which lens ran on what. No stronger default is shipped: which model is
 worth the money depends on the repository and the budget, so compare with the
-`models` action and decide.
+`models` action and decide — for one run with the `model` and `lens_models`
+parameters (Pi: `--model=ID`, `--lens-model=LENS:ID`), or here for the
+repository. The `models` listing is advisory: OpenRouter's catalog returns a
+`:batch` id for some models its Batch API refuses (`does not have a :batch
+endpoint`), at no cost, and nothing in the catalog tells them apart. The
+listing tags the ids this repository's own submits have seen accepted or
+refused (`broadside/batch-endpoints.json`), and a refused lens says why in the
+submit report.
 
 Every run knob — `incremental`, `retry_truncated`, `include_synthesis`,
 `include_triage`, `wait_seconds` — also has a repository default under the same
@@ -127,9 +134,13 @@ environment variable, or `api_key` in this directory's `config.yaml`.
 
 Submits are priced before they fire: Broad-Side estimates the run from the
 collected file sizes against the model's live per-token pricing and refuses
-when the estimate exceeds `max_cost` (`config.yaml` or the tool parameter)
-unless `force` is passed. See `config.yaml` for the model, limit, and manual
-pricing-override keys.
+when the estimate exceeds `max_cost` (`config.yaml` or the tool parameter;
+$1.00 when neither sets it, `0` for no limit) unless `force` is passed. See
+`config.yaml` for the model, limit, and manual pricing-override keys. A
+`config.yaml` that exists but cannot be parsed refuses every action except
+`status` rather than running on defaults, and a `state.json` that cannot be
+read refuses everything and is preserved beside itself — a paid run's batch
+ids live there, so nothing writes over it.
 
 What leaves the machine is repository content, so a redaction pass runs
 before upload: files named like credential stores (`.env*`, `*.pem`,

package/.codecarto/broadside/config.yaml

@@ -54,10 +54,18 @@
 #      Nothing in the catalog distinguishes them. Every Anthropic and OpenAI
 #      batch id tried so far is rejected this way; Google and DeepSeek work.
 #      A rejected batch costs nothing, so probe a candidate on one lens before
-#      relying on it.
+#      relying on it: `codecarto_broadside {action: "submit", lenses:
+#      ["architecture"], model: "<id>"}` (Pi: `/codecarto-broadside architecture
+#      --model=<id>`). Submits remember the answer in batch-endpoints.json next
+#      to this file, and the `models` listing tags each id accordingly.
 #   2. A reasoning-capable model spends its output budget thinking, and the
 #      thinking is billed at the full output rate. See `reasoning:` below.
 #
+# The same two keys are submit parameters for one run — `model` and
+# `lens_models` on codecarto_broadside, `--model=ID` and `--lens-model=LENS:ID`
+# on /codecarto-broadside — and a lens set both there and here takes the
+# parameter's.
+#
 # lens_models:
 #   security: deepseek/deepseek-v4-pro-0813:batch
 #   defect: deepseek/deepseek-v4-pro-0813:batch
@@ -89,17 +97,24 @@
 #   max_tokens: 2000   # or set the thinking budget directly
 #   enabled: false     # only where the provider allows it
 
-# Approximate run expense limit in USD (0 = no limit). Before submitting,
-# Broad-Side estimates the run cost from the collected file sizes and the
-# model's per-token pricing — fetched live from OpenRouter's model catalog
-# and cached for 24h. If the estimate exceeds max_cost, submit refuses and
-# prints the per-lens breakdown; pass force: true to override, or set a
-# value here so every run is guarded by default.
+# Approximate run expense limit in USD. The default is 1.00, and it applies
+# whether or not this key is set: the MCP surface cannot ask a human before
+# spending, so a repository is guarded before anyone configures it. Before
+# submitting, Broad-Side estimates the run cost from the collected file
+# sizes and the model's per-token pricing — fetched live from OpenRouter's
+# model catalog and cached for 24h. If the estimate exceeds max_cost, submit
+# refuses and prints the per-lens breakdown; pass force: true (or approve
+# Pi's dialog) to override for one run, raise the value here for a larger
+# repository, or set 0 for no limit at all.
 #
 # This is a pre-flight estimate guardrail, not a runtime stop: OpenRouter
 # bills actual usage, which may differ from the estimate either direction.
 # Actual cost lands in each run's run-meta.json after collect.
 #
+# A config.yaml that exists but cannot be parsed refuses submit, collect,
+# and models rather than falling back to these defaults — a typo here must
+# not silently remove the guard you set.
+#
 # max_cost: 1.00
 
 # Manual pricing overrides in USD per MILLION tokens. Normally Broad-Side
@@ -136,9 +151,10 @@
 # include_triage: true
 
 # Default poll budget in seconds. 0 returns as soon as the batches are
-# submitted or the recorded state is read; a positive value polls that long
-# before returning with whatever is done. Batch jobs routinely take tens of
-# minutes, so a submit-then-collect-later rhythm is normal.
+# submitted, and on collect polls each in-flight batch once and returns with
+# whatever is done; a positive value keeps polling that long. Batch jobs
+# routinely take tens of minutes, so a submit-then-collect-later rhythm is
+# normal.
 #
 # wait_seconds: 0
 

package/.codecarto/findings/contracts/SKILL.md

@@ -20,7 +20,10 @@ Split the analysis by user-facing surface:
 - web UI
 - API or SDK
 - bot or background worker
-- storage or export formats
+- storage or export formats — as user-visible behavior (what is written where, when it changes, what
+  survives a restart). The byte-level catalog of on-disk and wire formats belongs to the protocols
+  phase; name the format here and let protocols own its shape, so the two phases do not each write
+  it.
 
 For each feature, capture a contract with these fields:
 - `feature`

package/.codecarto/findings/defect-scan/SKILL.md

@@ -58,6 +58,16 @@ Assign one severity per finding:
 - `medium`: latent risk, dead code, defense-in-depth gap, or poor error handling.
 - `low`: style issue with correctness implications, stale docs, or minor inconsistency.
 
+Severity is the consequence, not the confidence. A cheap runtime probe — a script that drives the
+code path and shows the wrong result, the lost write, the escaped path — is worth running before
+a `high` or `critical` is assigned on reading alone: it settles the evidence level at
+`observed fact`, it may move the severity either way (a consequence that reading predicted and the
+probe did not reproduce drops; one the probe showed to be worse than read rises), and it gives the
+porting phase something it can cite. Record what the probe did and showed in the finding's
+evidence cell, and keep the probe script under `.codecarto/scratch/probes/` so the porting phase
+can rerun it. A finding whose consequence a probe confirmed keeps the severity that consequence
+earns; it is not promoted for having been confirmed.
+
 ## Action Classification
 
 Tag each finding with a recommended action. Use the set that matches your pipeline:

package/.codecarto/findings/defect-scan-mechanical/SKILL.md

@@ -13,6 +13,12 @@ The source code to analyze is in the parent directory (`../` relative to `.codec
 
 **Required:**
 - `findings/architecture/architecture-map.md` — for the layer map and public surfaces.
+- The repository's own build and packaging surface, which pass 6 is about and which the source
+  files never mention: the package manifest (`package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, …) with its `files`/include list, the compiler or bundler config (`tsconfig.json`
+  and kin), the CI and release workflows (`.github/workflows/*`), and the ignore files. Three of
+  the high findings in one self-audit came from these files alone; a scan that reads only source
+  cannot see what ships or what runs in CI.
 
 You do **not** need contracts or protocols for this phase. If those exist already, skim them as bonus context, but do not block on them — the mechanical pass is by design context-light.
 

package/.codecarto/findings/defect-scan-semantic/SKILL.md

@@ -17,6 +17,13 @@ The source code to analyze is in the parent directory (`../` relative to `.codec
 - `findings/protocols/protocols-and-state.md` — passes 3 and 5 need this for state machine and event-ordering analysis.
 - `findings/defect-scan-mechanical/mechanical-defects.md` — read so you do not re-flag what the mechanical phase already covered.
 
+**Read when a finding turns on it:** the source of a dependency the code trusts (under
+`node_modules/`, the vendored tree, or the SDK's published source), at the pinned version. The
+evidence rules allow "that system's own source" to settle an `external-behavior claim` about it,
+and passes 4 and 5 keep meeting claims of that shape — what a lock does on release, what a
+session runtime frees on dispose. Reading the pinned source is cheaper than a runtime probe and
+turns the claim into an `observed fact`; say which file and version you read.
+
 If any prerequisite is missing, stop and surface the gap. The semantic pass is the *paid-for* benefit of running the mechanical phase early; do not regress it by running the semantic pass blind.
 
 ## Pass Execution Order
@@ -39,7 +46,7 @@ Use the contracts and protocols outputs to decide emphasis:
 
 ## Evidence, Severity, and Action Classification
 
-Use the scheme from `findings/defect-scan/SKILL.md`. The severity and action sets are the same as the legacy defect-scan phase.
+Use the scheme from `findings/defect-scan/SKILL.md`. The severity and action sets are the same as the legacy defect-scan phase, including its rule for probe-confirmed findings: a cheap runtime probe before a `high` or `critical` settles the evidence level and may move the severity either way; it never promotes a finding for having been confirmed.
 
 When citing a contract or protocol violation, include the contract ID or state-machine reference from the upstream finding so the porting phase can trace the chain.
 

package/.codecarto/findings/porting/SKILL.md

@@ -39,6 +39,10 @@ Sort features by porting importance:
 - `incidental`: source-specific ergonomics or implementation accidents.
 
 If the defect report is available, integrate defect findings into the porting bundle:
+- Read each scan's `§Runtime probes` section (and the probe scripts it points at under
+  `scratch/probes/`) before the findings tables: a probe-confirmed finding is the strongest
+  evidence the scans produce, its severity is settled, and the bundle's dispositions should lean
+  on it first.
 - Reference relevant defects in the feature contract table.
 - Tag each referenced defect with a porting recommendation: `fix before porting` (the defect would carry into a new implementation), `port differently` (the new implementation should handle this case differently by design), `leave behind` (the defect is specific to the source implementation and won't survive porting), or `verify at runtime` (the diagnosis is an `external-behavior claim` or `open question` — carry it as a spike for the spec, and do not design around an unverified diagnosis). Preserve `verify at runtime` as written: flattening it into one of the settled three is how a hedge stops traveling.
 - Consolidate defect-related portability hazards alongside hazards from other phases.

package/.codecarto/findings/protocols/SKILL.md

@@ -37,6 +37,10 @@ Convert control flow into a state machine:
 - Record guards and side effects.
 - Separate synchronous barriers from observational events.
 
+This phase owns the storage-format catalog: every on-disk and wire format the system reads or
+writes, with its shape, version markers, and reader/writer pairs. The contracts phase names the
+formats it saw as user-visible behavior; catalog them here once rather than asking contracts to.
+
 Capture persistence semantics explicitly:
 - append-only vs mutable
 - branching vs linear history

package/.codecarto/templates/mechanical-defects.md

@@ -95,6 +95,21 @@
 
 ---
 
+## Runtime probes
+
+<!-- Optional, but the strongest evidence this report can carry. One row per probe you ran to
+     confirm or refute a finding before assigning its severity: a short script that drives the
+     code path and shows the wrong result, the lost write, the escaped path. Keep the scripts
+     under scratch/probes/ so the porting phase can rerun them, and put the finding's row number
+     in the Finding column so the two can be read together. A probe that did NOT reproduce the
+     read prediction is worth a row too — it is what lowers a severity honestly. -->
+
+| Probe | Finding | What it did | What it showed | Script |
+|---|---|---|---|---|
+| | | | | |
+
+---
+
 ## Open Questions
 
 <!-- Every finding whose Evidence Level is open question or external-behavior claim gets a row

package/.codecarto/templates/reimplementation-spec.md

@@ -121,9 +121,11 @@
 ## Carry-Forward
 
 <!-- Reimplementation-spec is the terminal phase in most pipelines, so most items belong in Known Unknowns
-     above. Use this section only when post-pipeline work (spikes, deltas, amendments) is the right place
-     to close an item. Each entry: { id, kind: defer-to-phase, target_phase, description, deferred_reason }.
-     Allowed target_phase values for post-pipeline: "spike", "delta", "amendment". -->
+     above. A carry_forward entry needs a target_phase that is a LATER phase of the active pipeline —
+     completion refuses anything else — so in a pipeline where this phase is last, this table stays empty.
+     Work for after the pipeline (spikes, deltas, amendments, maintainer rulings, opinionated reruns) goes
+     in the handoff's post_pipeline list instead: { id, kind: spike | delta | amendment, description }.
+     An amendment retires those entries once the pipeline is complete. -->
 
 | ID | Target Phase | Description | Deferred Reason |
 |---|---|---|---|

package/.codecarto/templates/reverse-engineering-bundle.md

@@ -81,7 +81,16 @@
 
   This section is the porting-oriented view of defects — it should answer
   "which defects must the reimplementation design around, and how?" not
-  re-list every finding. Keep it under one screen.
+  re-list every finding.
+
+  Two pressures meet here and one wins: the spec phase needs a disposition
+  (fix before porting / port differently / leave behind / verify at runtime)
+  for every defect it must design around, and a reader needs a table short
+  enough to hold in mind. Completeness wins. Give every high and medium
+  finding its own row; group lows by shared root cause into one row each,
+  naming the source rows, so that nothing is dropped and the table still
+  reads. A scan of 78 findings came out as 11 highs, 28 mediums, and 7 low
+  groups this way — long, but every disposition the spec needed was there.
 -->
 
 | Defect ID | Source Report | One-line Description | Severity | Disposition | Required design consequence |

package/.codecarto/templates/semantic-defects.md

@@ -104,6 +104,21 @@
 
 ---
 
+## Runtime probes
+
+<!-- Optional, but the strongest evidence this report can carry. One row per probe you ran to
+     confirm or refute a finding before assigning its severity: a short script that drives the
+     code path and shows the wrong result, the lost write, the escaped path. Keep the scripts
+     under scratch/probes/ so the porting phase can rerun them, and put the finding's row number
+     in the Finding column so the two can be read together. A probe that did NOT reproduce the
+     read prediction is worth a row too — it is what lowers a severity honestly. -->
+
+| Probe | Finding | What it did | What it showed | Script |
+|---|---|---|---|---|
+| | | | | |
+
+---
+
 ## Open Questions
 
 <!-- Every finding whose Evidence Level is open question or external-behavior claim gets a row

package/.codecarto/workflow/VALIDATE.md

@@ -31,7 +31,7 @@ Append this to the end of every primary output file:
 | 1 | [criterion text from pipeline.yaml] | PASS / PARTIAL / FAIL | [section reference or note] |
 | 2 | ... | ... | ... |
 
-**Validated by:** [session identifier or date]
+**Validated by:** [session identifier or date — YYYY-MM-DD in UTC, the clock every framework-written date uses]
 **Overall:** PASS / PASS WITH GAPS / FAIL
 ```
 

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.20.0
+scaffold_version: 0.22.0

package/README.md

@@ -271,11 +271,11 @@ Every state change re-renders `.codecarto/dashboard.html` — a self-contained s
 - Pipeline progress strip with per-phase status badges
 - Per-phase cards with output links, open questions, carry-forward routing, owner notes, last-run usage
 - Aggregate token and compaction telemetry + per-phase breakdown
-- Activity timeline with session-file links
+- Activity timeline of phase runs (tokens, duration, compactions)
 - Open questions roll-up grouped by source phase
 - Closeouts list (reverse-chronological) with relative-path links
 
-No JavaScript. No external assets. Light/dark via `prefers-color-scheme`. Works opened directly from `file://`.
+No external assets of any kind — nothing linked, nothing fetched. The file inlines two `<script>` blocks of its own (a JSON data island and the search/filter code), so it works opened directly from `file://`. Light/dark via `prefers-color-scheme`.
 
 **Opt-in narrative summary.** `/codecarto-dashboard --narrate` runs the orchestrator's model as a one-shot session that writes a 200–400 word executive summary citing specific findings from recent closeouts. Cached to `.codecarto/.dashboard-narration.local.md` and preserved across deterministic re-renders with a "(N runs since)" staleness note.
 
@@ -396,11 +396,11 @@ codecarto_broadside {cwd, action: "status"}                   # what is in fligh
 codecarto_broadside {cwd, action: "collect"}                  # poll, save, synthesize, triage
 ```
 
-Submit and collect are separate because batch jobs routinely take tens of minutes; collect is resumable and picks up whatever is still in flight. 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` unless `force: true` is passed — a pre-flight estimate, not a runtime stop. Actual spend lands in each run's `run-meta.json`.
+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). 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. `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.
+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] [lenses…]`, with tab-completion for actions and lens names 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] [lenses…] [--model=ID] [--lens-model=LENS:ID]`, 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

@@ -82,6 +82,16 @@ Two more economies worth knowing:
   conventions is usually a better trade than raising the model for everything.
   Overrides are priced and capability-checked individually, and the estimate
   breaks cost out per lens.
+- `model` and `lens_models` are also submit parameters (Pi: `--model=ID`,
+  `--lens-model=LENS:ID`), for one run without editing the file. Choose from
+  `action: "models"`, and read that listing as advisory: OpenRouter's catalog
+  returns a `:batch` id for some models its Batch API then refuses (`does not
+  have a :batch endpoint`) — free, reported on the lens with the reason, and
+  remembered, so the listing tags ids this repository has seen accepted or
+  refused. Probe an untried model on one lens before a six-lens run. A
+  `job-submission-count` refusal is the account's concurrent-job quota (one
+  job per lens fills it fast across runs); collect or wait out what is in
+  flight, then re-submit.
 
 ## Reading a run
 

package/dist/core/amendment.js

@@ -7,7 +7,7 @@
 // "record for a later explicit amendment" that nothing can perform.
 import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { getNextEligiblePhase } from "./pipeline.js";
+import { describeStuckPipeline, resolvePipelineOutcome } from "./pipeline.js";
 import { buildTerminalNextActions, ensureArray, normalizeStatus } from "./status.js";
 import { dateOnly, newlineIfUnterminated, pathExists } from "./utils.js";
 import { getWorkspaceState, updateStatusAtomically } from "./workspace.js";
@@ -101,11 +101,16 @@ export async function applyAmendment(cwd, name) {
     if (!initialState)
         throw new Error("CodeCartographer workspace not found. Run /codecarto-init first.");
     const amendment = await loadAmendmentFile(name, initialState.workspaceDir);
-    const nextPhase = getNextEligiblePhase(initialState);
-    if (nextPhase) {
-        throw new Error(`Cannot amend: the pipeline is not complete (next phase: ${nextPhase.id}). `
+    const outcome = resolvePipelineOutcome(initialState);
+    if (outcome.kind === "eligible") {
+        throw new Error(`Cannot amend: the pipeline is not complete (next phase: ${outcome.phase.id}). `
             + `Resolve open questions and routed items through that phase's handoff (open_question_closures / carry_forward_closures) instead.`);
     }
+    if (outcome.kind === "stuck") {
+        // Amendments are the post-pipeline channel; a pipeline that cannot
+        // finish is not there yet (#228).
+        throw new Error(`Cannot amend: the pipeline is not complete. ${describeStuckPipeline(outcome.blocked)}`);
+    }
     const timestamp = new Date().toISOString();
     const applied = { openQuestionsClosed: [], postPipelineClosed: [], unknownIds: [] };
     let closeoutNotice = "";

package/dist/core/broadside.d.ts

@@ -11,11 +11,28 @@ export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
 export declare const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
 export declare const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
 export declare const BROADSIDE_CATALOG_CACHE_FILE = "model-catalog.json";
+/**
+ * What this repository's own submits learned about batch endpoints: which
+ * `:batch` ids OpenRouter accepted a job for and which it refused with
+ * "does not have a :batch endpoint". The catalog cannot tell the two apart
+ * (#141), so the `models` action annotates its rows from this file.
+ */
+export declare const BROADSIDE_ENDPOINTS_FILE = "batch-endpoints.json";
 export declare const BROADSIDE_CATALOG_CACHE_TTL_MS: number;
 export declare const BROADSIDE_LENS_IDS: readonly ["architecture", "api", "security", "defect", "conventions", "porting"];
 export type BroadsideLensId = (typeof BROADSIDE_LENS_IDS)[number];
 export declare const BROADSIDE_POLL_INTERVAL_MS = 15000;
 export declare const BROADSIDE_DEFAULT_POLL_BUDGET_MS: number;
+/**
+ * The run expense limit in USD a repository gets before it configures one.
+ * Pi asks a human before submitting over the estimate; the MCP surface cannot,
+ * and shipped with no limit at all, so a host calling submit with the stock
+ * config spent whatever the estimate came to (#231). One dollar covers a
+ * six-lens run of a repository this size with room to spare; a larger one
+ * raises `max_cost` in config.yaml, passes `max_cost` on the call, or sets it
+ * to 0 for no limit.
+ */
+export declare const BROADSIDE_DEFAULT_MAX_COST = 1;
 export type ModelPricing = {
     /** USD per million input tokens. */
     inputPerM: number;
@@ -324,6 +341,27 @@ export declare class BroadsideAuthError extends Error {
     readonly detail: string;
     constructor(httpStatus: number, detail: string);
 }
+/**
+ * `broadside/config.yaml` exists but cannot be used. A file that failed to
+ * parse used to be treated exactly like an absent one — defaults, including
+ * no spend cap and no lens routing, with no message — so a typo removed the
+ * user's own guard (#232). Only an absent file yields defaults now.
+ */
+export declare class BroadsideConfigError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+/**
+ * `broadside/state.json` exists but cannot be read. It used to be read as
+ * empty and the next checkpoint wrote that empty state over it, losing the
+ * batch ids of every in-flight, already-paid run (#233). The corrupt file is
+ * preserved beside itself and nothing writes over it until someone looks.
+ */
+export declare class BroadsideStateError extends Error {
+    readonly path: string;
+    readonly backupPath: string;
+    constructor(path: string, backupPath: string, detail: string);
+}
 /** Thrown when a confirm hook declines a run. Nothing was submitted. */
 export declare class BroadsideCancelledError extends Error {
     constructor(message?: string);
@@ -504,6 +542,30 @@ export declare function updateBroadsideStateAtomically(broadsideDir: string, mut
  */
 export declare function persistBroadsideRun(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
 export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
+/** The shipped defaults: what an absent config.yaml means. */
+export declare function defaultBroadsideConfig(): BroadsideConfig;
+/** The catalog cache schema this build writes; a file from another is not read. */
+export declare const BROADSIDE_CATALOG_CACHE_SCHEMA = 3;
+/** One model's most recent submit outcome, as remembered in {@link BROADSIDE_ENDPOINTS_FILE}. */
+export type BatchEndpointRecord = {
+    status: "accepted" | "rejected";
+    /** ISO timestamp of the submit that produced this record. */
+    at: string;
+    /** The provider's refusal, for a rejected endpoint. */
+    error?: string;
+};
+export declare function readBatchEndpoints(broadsideDir: string): Promise<Record<string, BatchEndpointRecord>>;
+/**
+ * Remember what a submit learned about each model it posted to. An accepted
+ * job proves the endpoint exists; a "does not have a :batch endpoint"
+ * refusal proves it does not. Any other rejection (quota, malformed request,
+ * auth) says nothing about the endpoint and leaves the record alone.
+ */
+export declare function recordBatchEndpoints(broadsideDir: string, outcomes: Array<{
+    model: string;
+    batchId: string;
+    error?: unknown;
+}>): Promise<void>;
 export declare function builtInCatalogEntry(model: string): CatalogEntry | null;
 export declare function builtInPricing(model: string): ModelPricing | null;
 export declare function resolveCatalogEntry(broadsideDir: string, config: BroadsideConfig, model: string, apiKey: string, fetcher?: FetchLike): Promise<BroadsideCatalogResult>;
@@ -517,6 +579,8 @@ export declare function listBatchModels(broadsideDir: string, config: BroadsideC
     source: string;
     benchmarks: CodingBenchmarks | null;
     defaultModel: string;
+    /** This repository's remembered submit outcomes per model, from {@link BROADSIDE_ENDPOINTS_FILE}. */
+    endpoints: Record<string, BatchEndpointRecord>;
 }>;
 export type FetchLike = (url: string, init: Record<string, unknown>) => Promise<Response>;
 export declare function submitBatch(batchRequests: BatchRequest[], apiKey: string, fetcher?: FetchLike, model?: string): Promise<{
@@ -533,6 +597,14 @@ export declare function fetchBatch(batchId: string, apiKey: string, fetcher?: Fe
  * charged, so callers must come back for it rather than retire it.
  */
 export declare const BROADSIDE_DEAD_BATCH_STATUSES: string[];
+/**
+ * Batch entry statuses collect never polls again: the dead ones above, plus
+ * `completed`, plus the two a submit assigns without a batch (`skipped`: no
+ * matching files; `rejected`: the provider refused it). The 0.19.1 changelog
+ * called the dead set "a named constant rather than two hand-maintained
+ * lists"; this set was still three literal copies (self-audit sem 5.8).
+ */
+export declare const BROADSIDE_TERMINAL_ENTRY_STATUSES: string[];
 export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
     deadlineMs?: number;
     onStatus?: (status: string, counts: Record<string, unknown>) => void;
@@ -559,6 +631,12 @@ export declare function runBroadsideSubmit(cwd: string, apiKey: string, opts?: {
     lenses?: BroadsideLensId[];
     fetcher?: FetchLike;
     model?: string;
+    /**
+     * Per-lens model overrides for this run, layered over config.yaml's
+     * `lens_models`: a lens named here runs on this model, a lens named only
+     * in the file runs on the file's, and the rest run on `model` (#141).
+     */
+    lensModels?: Partial<Record<BroadsideLensId, string>>;
     /** Approximate run expense limit in USD; 0 means no limit. */
     maxCost?: number;
     /** Submit even when the estimate exceeds maxCost. */
@@ -615,6 +693,12 @@ export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?:
     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;
 }): Promise<BroadsideCollectResult>;
 export declare function runBroadsideStatus(cwd: string): Promise<{
     state: BroadsideStateFile;
@@ -624,7 +708,21 @@ export declare function estimateSubmitText(result: BroadsideSubmitResult, lenses
 export declare function modelsText(entries: CatalogEntry[], opts: {
     benchmarks: CodingBenchmarks | null;
     defaultModel: string;
+    endpoints?: Record<string, BatchEndpointRecord>;
 }): string;
+/**
+ * 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;
 export declare function collectResultText(result: BroadsideCollectResult): string;
 export declare function statusText(state: BroadsideStateFile): string;
 export {};