crysk 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/README.md +26 -17
  2. package/config/models/anthropic.json +1 -1
  3. package/dist/SKILL-k4k0zn1w.md +143 -0
  4. package/dist/SKILL-vhb4c3vv.md +553 -0
  5. package/dist/SKILL-xpf6kmdw.md +74 -0
  6. package/dist/ci-admission-0ken6ehx.md +128 -0
  7. package/dist/cli.js +3056 -1623
  8. package/dist/index.js +1744 -938
  9. package/dist/opencode-ci-ac5zksdn.md +106 -0
  10. package/dist/workflow-4pkyck01.yml +160 -0
  11. package/package.json +1 -1
  12. package/prompts/default/PROVENANCE.md +1 -0
  13. package/skills/crysk/SKILL.md +16 -16
  14. package/skills/crysk-ci-setup/SKILL.md +41 -38
  15. package/skills/crysk-ci-setup/assets/workflow.yml +31 -22
  16. package/skills/crysk-ci-setup/references/ci-admission.md +1 -1
  17. package/skills/crysk-ci-setup/references/opencode-ci.md +53 -88
  18. package/skills/crysk-loop/SKILL.md +1 -1
  19. package/src/asset-manifest.ts +0 -4
  20. package/src/assets.ts +1 -1
  21. package/src/ci/admission-ledger.ts +4 -0
  22. package/src/ci/classify-error.ts +21 -24
  23. package/src/ci/cli-record.ts +53 -1
  24. package/src/ci/crysk-secrets.ts +409 -0
  25. package/src/ci/gates.ts +22 -36
  26. package/src/ci/outcome.ts +421 -330
  27. package/src/ci/platform-config.ts +2 -2
  28. package/src/ci/platform-report.ts +274 -41
  29. package/src/ci/platform-trace.ts +551 -0
  30. package/src/ci/platform.ts +28 -12
  31. package/src/ci/publish.ts +19 -6
  32. package/src/ci/review-levels.ts +8 -7
  33. package/src/ci/run.ts +88 -0
  34. package/src/ci/setup.ts +453 -118
  35. package/src/ci/trace-bundle.ts +1282 -0
  36. package/src/ci/trace-transcripts.ts +415 -0
  37. package/src/ci/trigger.ts +176 -33
  38. package/src/cli.ts +11 -3
  39. package/src/commands/ci-setup-questions.ts +3 -3
  40. package/src/commands/ci-setup.ts +152 -6
  41. package/src/commands/config.ts +3 -0
  42. package/src/commands/doctor.ts +15 -6
  43. package/src/config/config.ts +16 -3
  44. package/src/diversity/clustering.ts +0 -1
  45. package/src/diversity/identity.ts +4 -5
  46. package/src/diversity/pipeline-integration.ts +1 -9
  47. package/src/doctor.ts +3 -3
  48. package/src/execution/attempt-evidence.ts +10 -5
  49. package/src/execution/claude-session-trace.ts +480 -0
  50. package/src/execution/contracts.ts +21 -4
  51. package/src/execution/harness.ts +105 -8
  52. package/src/execution/model-fallback.ts +239 -0
  53. package/src/execution/usage-normalized.ts +6 -4
  54. package/src/home-preflight.ts +1 -1
  55. package/src/index.ts +1 -1
  56. package/src/model/catalog.ts +13 -37
  57. package/src/model/free-discovery.ts +117 -8
  58. package/src/model/model-name.ts +404 -0
  59. package/src/model/provider-capabilities.ts +22 -7
  60. package/src/model/routing.ts +346 -467
  61. package/src/pr/admission.ts +18 -0
  62. package/src/pr/plan.ts +20 -4
  63. package/src/pr/preflight.ts +1 -1
  64. package/src/pr/publish-outcome.ts +1 -1
  65. package/src/pr/review-pr.ts +15 -1
  66. package/src/pr/target.ts +12 -3
  67. package/src/production-runtime.ts +760 -331
  68. package/src/review/pipeline.ts +277 -101
  69. package/src/review/preflight.ts +201 -294
  70. package/src/review/report.ts +26 -26
  71. package/src/review/review.ts +20 -3
  72. package/src/review/route-preflight.ts +79 -11
  73. package/src/review/run.ts +28 -6
  74. package/src/review/scout.ts +1 -1
  75. package/src/review/spec.ts +3 -3
  76. package/src/review/step-runner.ts +70 -1
  77. package/src/runner-authority.ts +127 -9
  78. package/src/security/binding-policy.ts +1 -2
  79. package/src/security/claude-credential.ts +355 -0
  80. package/src/security/credential-broker.ts +56 -40
  81. package/src/security/evidence-redaction.ts +179 -4
  82. package/src/security/opencode-secret-manifest.ts +114 -0
  83. package/src/security/redact.ts +45 -0
  84. package/src/system-tools.ts +48 -21
  85. package/src/transport-registry.ts +12 -2
  86. package/src/transports/claude-code-cli.ts +21 -2
  87. package/src/transports/opencode-sdk.ts +11 -9
  88. package/src/transports/opencode-server.ts +7 -10
  89. package/src/ui/config-edit.ts +9 -20
  90. package/src/ui/config.ts +32 -27
  91. package/src/ui/plan.ts +76 -47
  92. package/src/updater.ts +10 -7
  93. package/prompts/default/deep-review-lifecycle.md +0 -362
@@ -1,71 +1,51 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import type { ResolvedModelRoute, RunnerBackend } from "../execution/contracts";
3
- import { redactDiagnostic } from "../security/redact";
4
3
  import {
5
- isModelAlias,
6
- lookupAlias,
7
- type ModelAlias,
8
- reverseAliasForCanonical,
9
- } from "./catalog";
4
+ hunterRole,
5
+ isModelRole,
6
+ type ModelListEntry,
7
+ type ModelName,
8
+ ModelNameError,
9
+ type ModelsConfig,
10
+ modelEntry,
11
+ modelNameFromAlias,
12
+ parseModelName,
13
+ } from "./model-name";
10
14
 
11
- export type ModelGateway = "configured" | "direct" | "openrouter";
12
15
  export type { ResolvedModelRoute, RunnerBackend };
13
16
 
14
- export interface RouteMapping {
15
- readonly logical?: string;
16
- readonly backend: RunnerBackend;
17
- readonly provider: string;
18
- readonly gateway?: ModelGateway;
19
- readonly modelFamily?: string;
20
- readonly modelSnapshot?: string;
21
- readonly modelVariant?: string;
22
- readonly disabled?: boolean;
23
- readonly allowSpend?: boolean;
24
- }
25
-
26
- export interface RoutingConfig {
27
- readonly default?: RouteMapping;
28
- readonly mappings?: readonly RouteMapping[] | Record<string, RouteMapping>;
29
- readonly disabled?: boolean;
30
- }
31
-
32
- function mappingNeedsOpenCodeSdk(mapping: RouteMapping | undefined): boolean {
33
- if (mapping === undefined) return false;
34
- return (
35
- mapping.backend === "opencode" &&
36
- mapping.disabled !== true &&
37
- mapping.allowSpend !== false
38
- );
39
- }
40
-
41
- // Spend that would actually open an OpenCode transport. A disabled route,
42
- // a mapping that refuses spend, or no routing at all does not.
43
- export function routingNeedsOpenCodeSdk(
44
- routing: RoutingConfig | undefined,
45
- ): boolean {
46
- if (routing === undefined || routing.disabled === true) return false;
47
- if (mappingNeedsOpenCodeSdk(routing.default)) return true;
48
- const mappings = routing.mappings;
49
- if (mappings === undefined) return false;
50
- const entries = Array.isArray(mappings) ? mappings : Object.values(mappings);
51
- return entries.some((entry) => mappingNeedsOpenCodeSdk(entry));
52
- }
53
-
54
- export interface ParsedLogicalIdentity {
55
- readonly raw: string;
56
- readonly canonical: string;
57
- readonly provider: string;
58
- readonly model: string;
59
- readonly variant?: string;
60
- readonly alias?: ModelAlias;
61
- }
17
+ // The route plan: which model each step runs, decided once before anything
18
+ // spends (odd/tasks/role-model-routing.md S1).
19
+ //
20
+ // WHY roles and not aliases: the old routing keyed every assignment by a
21
+ // Claude alias, so "the step" and "the model" were one word. Every hunter on
22
+ // `sonnet` had to run the same model, and pointing `sonnet` at OpenCode moved
23
+ // every step that happened to use it. A step now has a ROLE (`hunter.logic`,
24
+ // `refuter`, `summary`, ...), the operator's `models` maps roles to models, and
25
+ // a model name says which backend runs it (model-name.ts).
62
26
 
63
27
  export interface ResolvedStepRoute {
64
28
  readonly stepKey: string;
65
29
  readonly role: string;
30
+ // The model name the step resolved to, as written (`claude:sonnet-latest`,
31
+ // `opencode:openai/gpt-5`). Prompt aliases appear in their converted form.
32
+ // An entry's effort is not part of it: for OpenCode it is the route's
33
+ // modelVariant, so the fingerprint still tells two efforts apart.
66
34
  readonly logicalIdentity: string;
67
35
  readonly route: ResolvedModelRoute;
68
36
  readonly routeFingerprint: string;
37
+ // The `models` entry's effort as written (S7), on either backend. Absent
38
+ // when the entry sets none, and always for `--model`, a spec model or a
39
+ // prompt alias (D4), so a plan without efforts is the plan it always was.
40
+ // The pipeline reads it for a Claude step's `--effort` (stepEffortFields);
41
+ // an OpenCode effort is also the route's modelVariant. Never part of the
42
+ // route's fingerprint (for Claude it is a launch flag, not a binding), but
43
+ // part of the plan's (createResolvedRoutePlan).
44
+ readonly effort?: string;
45
+ // The models tried after this one, in the order the role lists them (S4).
46
+ // Each is a route of this same step. Absent when the role names one model,
47
+ // so a plan without lists is the plan it always was, byte for byte.
48
+ readonly fallbacks?: readonly ResolvedStepRoute[];
69
49
  }
70
50
 
71
51
  export interface ResolvedRoutePlan {
@@ -75,337 +55,89 @@ export interface ResolvedRoutePlan {
75
55
  }
76
56
 
77
57
  export class ModelRoutingError extends Error {}
78
- export class UnmappedRouteError extends ModelRoutingError {}
79
- export class AmbiguousMappingError extends ModelRoutingError {}
80
- export class UnauthorizedRouteError extends ModelRoutingError {}
81
-
82
- export type { ModelAlias } from "./catalog";
83
- export {
84
- aliasCanonical,
85
- isModelAlias,
86
- lookupAlias,
87
- MODEL_CATALOG,
88
- } from "./catalog";
89
-
90
- const SLASH_GRAMMAR_REGEX =
91
- /^([a-zA-Z0-9_-]+)\/([a-zA-Z0-9._-]+)(?:#([a-zA-Z0-9._-]+))?$/;
92
-
93
- export function parseLogicalIdentity(raw: string): ParsedLogicalIdentity {
94
- if (typeof raw !== "string") {
95
- throw new ModelRoutingError("Model identity must be a string");
96
- }
97
- const trimmed = raw.trim();
98
- if (trimmed.length === 0) {
99
- throw new ModelRoutingError("Model identity cannot be empty");
100
- }
101
58
 
102
- if (isModelAlias(trimmed)) {
103
- const aliasInfo = lookupAlias(trimmed);
104
- return {
105
- raw: trimmed,
106
- canonical: aliasInfo.canonical,
107
- provider: aliasInfo.provider,
108
- // #175: the alias IS the model segment now. `parsed.model` feeds both
109
- // `modelFamily` and `modelSnapshot` on the default alias route below,
110
- // so this is the single line that decides what our provenance claims
111
- // an alias run used — and after #175 it claims the name that was
112
- // actually sent to the CLI, not a version we never verified.
113
- model: aliasInfo.alias,
114
- alias: trimmed,
115
- };
116
- }
59
+ // A model written in the new form (`claude:...`, `opencode:...`) or in `models`
60
+ // that does not resolve. Always surfaced, never swallowed into the legacy
61
+ // no-plan path: its message is the fix (`write "claude:sonnet-latest"`), and a
62
+ // run without a plan would send the bad name to a provider as is.
63
+ export class InvalidModelError extends ModelRoutingError {}
117
64
 
118
- const match = trimmed.match(SLASH_GRAMMAR_REGEX);
119
- if (match) {
120
- const [, provider, model, variant] = match;
121
- const canonical = `${provider}/${model}${variant ? `#${variant}` : ""}`;
122
- return {
123
- raw: trimmed,
124
- canonical,
125
- provider,
126
- model,
127
- ...(variant !== undefined ? { variant } : {}),
128
- };
129
- }
65
+ const NEW_FORM_PREFIXES = ["claude:", "opencode:"];
130
66
 
131
- const safeRaw = redactDiagnostic(raw);
132
- throw new ModelRoutingError(
133
- `Unknown model identity "${safeRaw}": bare model names must be an alias (sonnet|opus|haiku) or use slash grammar provider/model(#variant)`,
134
- );
135
- }
67
+ // Where a step's model came from, for the error a bad one raises.
68
+ type ModelSource = "--model" | "spec" | "models" | "prompt";
136
69
 
137
- // #175 follow-up, 2026-09-02. THE ONE PLACE a route's `modelSnapshot` may fall
138
- // back to the parsed identity. It exists as a function because the fallback had
139
- // THREE copies — array mappings, record mappings, default mapping — and a guard
140
- // added to one of them is the "two copies drift" failure this repo keeps paying
141
- // for.
142
- //
143
- // WHAT IT REFUSES, and why refusing is the only honest option: #175 made a bare
144
- // alias parse to the alias WORD (`parsed.model === "sonnet"`), where it used to
145
- // parse to a version pinned in our own catalogue. That pin was the lie #175
146
- // deleted — only the Claude CLI knows what `sonnet` currently means. But the
147
- // fallback then started handing the bare word to consumers that resolve
148
- // nothing: `transport-registry.ts` forwards `modelSnapshot` verbatim as the
149
- // OpenCode SDK's `modelID`, so a `{"sonnet": {"backend": "opencode"}}` config
150
- // went from sending a real model id to sending the word "sonnet" to a live API.
151
- //
152
- // #176 follow-up, 2026-09-02. THE AXIS IS THE GATEWAY, NOT THE BACKEND. This
153
- // guard's first version refused on `mapping.backend !== "claude-code"`, and
154
- // that door had a hole the size of the defect it closed: `claude-code` only
155
- // resolves the alias itself when the route's gateway is `direct`.
156
- // `spawnModelForClaudeCli` is explicit about it — on any other gateway it
157
- // returns `route.modelSnapshot` verbatim as `--model`, without ever consulting
158
- // the alias table. So `{"sonnet": {"backend": "claude-code", "provider":
159
- // "anthropic"}}` sent `--model sonnet` to a CLI pointed at a gateway that never
160
- // heard of pr-hero's aliases. The predicate below therefore asks the only
161
- // question that matters — DOES THE CONSUMER RESOLVE THIS WORD? — which is true
162
- // in exactly one combination: `claude-code` AND `direct`.
163
- //
164
- // AND MIND THE TWO DIVERGENT GATEWAY DEFAULTS, because the divergence IS what
165
- // let the hole open. Route resolution defaults an absent `gateway` to
166
- // `"configured"` (the three `?? "configured"` call sites below);
167
- // `spawnModelForClaudeCli` defaults an absent one to `"direct"` (and so does
168
- // `report.ts`'s renderer). Those are not the same rule, and only the first one
169
- // is correct here: this guard runs while the route is being BUILT, so it must
170
- // use the value the route is about to assert, not the value a later reader
171
- // would infer from a route that omitted it. Hence `gateway` is passed IN, read
172
- // off the same `?? "configured"` expression that populates the route's own
173
- // field — a fourth independent copy of that default inside this helper is
174
- // exactly the drift this helper exists to prevent.
175
- //
176
- // HOW MUCH the old fallback actually got right, measured on `dev` rather than
177
- // assumed, because it bounds what this guard is restoring: the snapshot came
178
- // from the CATALOGUE, never from the mapping's `provider`. So `sonnet` ->
179
- // opencode/`anthropic` did resolve to `claude-sonnet-5`, and that is the config
180
- // this fix stops breaking — but `sonnet` -> opencode/`openai` sent
181
- // `claude-sonnet-5` to OpenAI, nonsense before #175 and nonsense after. The
182
- // guard refuses BOTH, which is why it is a guard and not a restored pin: we
183
- // cannot know the version, and we must not fabricate one, so the route is
184
- // refused and the operator is told the one thing that fixes it.
185
- //
186
- // THE PREDICATE IS THE ALIAS IDENTITY, not the model segment. `reverseAlias` is
187
- // set for the bare word AND for its canonical `provider/alias` form — the key
188
- // shape this repo's own configs use via `aliasCanonical()`, so a guard on the
189
- // bare word alone would be bypassed by the recommended key. It is unset for
190
- // slash grammar, where the segment is the operator's own words and forwarding
191
- // them verbatim is correct. `anthropic/sonnet#high` is not the registered
192
- // canonical and so passes through: that hole predates #175 (the same
193
- // `?? parsed.model` produced `"sonnet"` for it on `dev` too) and is not this
194
- // regression.
195
- //
196
- // WHY `modelFamily` KEEPS ITS `?? parsed.model` FALLBACK and is deliberately
197
- // NOT guarded here — stated so the next reader does not "complete" the fix:
198
- // (1) it never reaches a provider — the wire identity is `modelSnapshot`, read
199
- // by `transport-registry.ts` for OpenCode's `modelID`, by
200
- // `spawnModelForClaudeCli` for `--model`, and by pricing admission in
201
- // `production-runtime.ts`; (2) `"sonnet"` is a truthful FAMILY label, not a
202
- // fabricated version, so unlike the snapshot it asserts nothing false; and
203
- // (3) this guard already refuses the whole route in the only case where an
204
- // alias-derived family could reach a consumer that does not resolve aliases
205
- // with no snapshot. Guarding it too would force operators to supply both fields
206
- // and buy no safety.
207
- function routeModelSnapshot(
208
- mapping: RouteMapping,
209
- parsed: ParsedLogicalIdentity,
210
- reverseAlias: ModelAlias | undefined,
211
- gateway: ModelGateway,
212
- mappingLabel: string,
213
- ): string {
214
- if (mapping.modelSnapshot !== undefined) {
215
- return mapping.modelSnapshot;
216
- }
217
- // The one combination whose consumer resolves the bare word itself, so the
218
- // alias IS the honest snapshot: the Claude CLI, reached directly.
219
- const consumerResolvesAlias =
220
- mapping.backend === "claude-code" && gateway === "direct";
221
- if (reverseAlias !== undefined && !consumerResolvesAlias) {
222
- // `UnmappedRouteError` and not a new class: a mapping was found, but it
223
- // leaves the alias unmapped to any provider model id, which is what this
224
- // error already names. Nothing in src/ catches these classes, so the
225
- // choice is about meaning, and a fifth class would have no consumer.
226
- throw new UnmappedRouteError(
227
- redactDiagnostic(
228
- `Model alias "${reverseAlias}" is routed to backend "${mapping.backend}" over the "${gateway}" gateway by the ${mappingLabel}, which supplies no "modelSnapshot". Only the Claude CLI reached over the "direct" gateway resolves a bare alias; every other gateway forwards the model identity verbatim to an endpoint that never registered Crysk's aliases, so this route has no provider model id to send. Add an explicit "modelSnapshot" naming the provider's model id to that ${mappingLabel}, or set its "gateway" to "direct" if the Claude CLI really is resolving this alias.`,
229
- ),
230
- );
70
+ function toModelName(
71
+ value: string,
72
+ source: ModelSource,
73
+ stepKey: string,
74
+ ): ModelName {
75
+ try {
76
+ return source === "models"
77
+ ? parseModelName(value)
78
+ : modelNameFromAlias(value);
79
+ } catch (error) {
80
+ if (!(error instanceof ModelNameError)) throw error;
81
+ const where =
82
+ source === "--model"
83
+ ? "--model"
84
+ : source === "models"
85
+ ? `models for ${stepKey}`
86
+ : `the ${source} model of ${stepKey}`;
87
+ const message = `${where}: ${error.message}`;
88
+ if (
89
+ source === "models" ||
90
+ NEW_FORM_PREFIXES.some((prefix) => value.trim().startsWith(prefix))
91
+ ) {
92
+ throw new InvalidModelError(message);
93
+ }
94
+ throw new ModelRoutingError(message);
231
95
  }
232
- return parsed.model;
233
96
  }
234
97
 
235
- export function resolveModelRoute(
236
- logicalInput: string,
237
- config?: RoutingConfig,
98
+ // THE route of a model name. For a `-latest` name the model is the CLI alias
99
+ // (`sonnet`), which the Claude Code CLI resolves to the newest version itself;
100
+ // for a pinned name it is the full id; for OpenCode it is the provider's model
101
+ // id. `modelFamily` keeps the alias where there is one, so a zero-config run
102
+ // records exactly what it recorded before.
103
+ //
104
+ // An OpenCode entry's effort becomes the route's variant (S7: "OpenCode:
105
+ // `effort` becomes the model `variant`"), the field the removed `#variant`
106
+ // suffix used to fill, so binding, transport cache and fingerprint keep
107
+ // telling variants apart as they did. No effort, no variant (D1). A Claude
108
+ // entry's effort is not part of the route: it is a launch flag, not a binding,
109
+ // and rides the plan step instead (ResolvedStepRoute.effort).
110
+ export function routeForModel(
111
+ name: ModelName,
112
+ effort?: string,
238
113
  ): ResolvedModelRoute {
239
- const parsed = parseLogicalIdentity(logicalInput);
240
- const reverseAlias = reverseAliasForCanonical(parsed.canonical);
241
-
242
- if (config !== undefined) {
243
- if (config.disabled === true) {
244
- throw new UnauthorizedRouteError(
245
- redactDiagnostic(
246
- `Spend is disabled for model route "${parsed.canonical}"`,
247
- ),
248
- );
249
- }
250
-
251
- if (config.mappings !== undefined) {
252
- if (Array.isArray(config.mappings)) {
253
- const matches = config.mappings.filter((entry) => {
254
- if (!entry || typeof entry !== "object") return false;
255
- if (entry.logical === parsed.canonical) return true;
256
- if (entry.logical === parsed.raw) return true;
257
- if (parsed.alias && entry.logical === parsed.alias) return true;
258
- if (reverseAlias && entry.logical === reverseAlias) return true;
259
- return false;
260
- });
261
-
262
- if (matches.length > 1) {
263
- throw new AmbiguousMappingError(
264
- redactDiagnostic(
265
- `Ambiguous model routing: found ${matches.length} duplicate mappings for "${parsed.canonical}"`,
266
- ),
267
- );
268
- }
269
-
270
- if (matches.length === 1) {
271
- const m = matches[0];
272
- if (m.disabled === true || m.allowSpend === false) {
273
- throw new UnauthorizedRouteError(
274
- redactDiagnostic(
275
- `Spend is disabled for model route "${parsed.canonical}"`,
276
- ),
277
- );
278
- }
279
- // One `?? "configured"` per branch, shared by the route field and the
280
- // guard, so the value the guard judges is the value the route claims.
281
- const gateway = m.gateway ?? "configured";
282
- return {
283
- backend: m.backend,
284
- provider: m.provider,
285
- gateway,
286
- modelFamily: m.modelFamily ?? parsed.model,
287
- modelSnapshot: routeModelSnapshot(
288
- m,
289
- parsed,
290
- reverseAlias,
291
- gateway,
292
- "routing mapping",
293
- ),
294
- ...(m.modelVariant !== undefined || parsed.variant !== undefined
295
- ? { modelVariant: m.modelVariant ?? parsed.variant }
296
- : {}),
297
- };
298
- }
299
- } else if (
300
- typeof config.mappings === "object" &&
301
- config.mappings !== null
302
- ) {
303
- const record = config.mappings as Record<string, RouteMapping>;
304
- const candidateKeys = Array.from(
305
- new Set(
306
- [parsed.canonical, parsed.alias, reverseAlias, parsed.raw].filter(
307
- (key): key is string => key !== undefined,
308
- ),
309
- ),
310
- );
311
- const matchedKeys = candidateKeys.filter((key) => key in record);
312
-
313
- if (matchedKeys.length > 1) {
314
- throw new AmbiguousMappingError(
315
- redactDiagnostic(
316
- `Ambiguous model routing: found ${matchedKeys.length} duplicate mappings for "${parsed.canonical}" in record mappings`,
317
- ),
318
- );
319
- }
320
-
321
- const m = matchedKeys.length > 0 ? record[matchedKeys[0]] : undefined;
322
-
323
- if (m !== undefined) {
324
- if (m.disabled === true || m.allowSpend === false) {
325
- throw new UnauthorizedRouteError(
326
- redactDiagnostic(
327
- `Spend is disabled for model route "${parsed.canonical}"`,
328
- ),
329
- );
330
- }
331
- // Same shared `?? "configured"` as the array branch: the guard and
332
- // the recorded route must never read two different gateways.
333
- const gateway = m.gateway ?? "configured";
334
- return {
335
- backend: m.backend,
336
- provider: m.provider,
337
- gateway,
338
- modelFamily: m.modelFamily ?? parsed.model,
339
- modelSnapshot: routeModelSnapshot(
340
- m,
341
- parsed,
342
- reverseAlias,
343
- gateway,
344
- "routing mapping",
345
- ),
346
- ...(m.modelVariant !== undefined || parsed.variant !== undefined
347
- ? { modelVariant: m.modelVariant ?? parsed.variant }
348
- : {}),
349
- };
350
- }
351
- }
352
- }
353
-
354
- if (config.default !== undefined) {
355
- const def = config.default;
356
- if (def.disabled === true || def.allowSpend === false) {
357
- throw new UnauthorizedRouteError(
358
- redactDiagnostic("Spend is disabled for default model route"),
359
- );
360
- }
361
- // Third and last copy of the same shared default, for the same reason.
362
- const gateway = def.gateway ?? "configured";
363
- return {
364
- backend: def.backend,
365
- provider: def.provider,
366
- gateway,
367
- modelFamily: def.modelFamily ?? parsed.model,
368
- modelSnapshot: routeModelSnapshot(
369
- def,
370
- parsed,
371
- reverseAlias,
372
- gateway,
373
- "default routing mapping",
374
- ),
375
- ...(def.modelVariant !== undefined || parsed.variant !== undefined
376
- ? { modelVariant: def.modelVariant ?? parsed.variant }
377
- : {}),
378
- };
379
- }
380
- }
381
-
382
- if (parsed.alias !== undefined) {
383
- return {
384
- backend: "claude-code",
385
- provider: "anthropic",
386
- gateway: "direct",
387
- modelFamily: parsed.model,
388
- modelSnapshot: parsed.model,
389
- ...(parsed.variant !== undefined ? { modelVariant: parsed.variant } : {}),
390
- };
391
- }
114
+ return {
115
+ backend: name.backend,
116
+ provider: name.provider,
117
+ modelFamily: name.alias ?? name.model,
118
+ modelSnapshot: name.model,
119
+ ...(effort !== undefined && name.backend === "opencode"
120
+ ? { modelVariant: effort }
121
+ : {}),
122
+ };
123
+ }
392
124
 
393
- throw new UnmappedRouteError(
394
- redactDiagnostic(
395
- `No route mapping found for logical model "${parsed.canonical}"`,
396
- ),
397
- );
125
+ // What the Claude Code CLI receives as `--model`: the route's model. The alias
126
+ // for a `-latest` name, the id for a pinned one. It used to be the step's own
127
+ // prompt alias on a `direct` gateway, so a model configured for a role never
128
+ // reached the CLI; the gateway is gone and the route is the one answer.
129
+ export function claudeCliModel(route: ResolvedModelRoute): string {
130
+ return route.modelSnapshot;
398
131
  }
399
132
 
400
133
  export function computeRouteFingerprint(
401
- canonicalLogical: string,
134
+ logicalIdentity: string,
402
135
  route: ResolvedModelRoute,
403
136
  ): string {
404
137
  const payload = JSON.stringify({
405
- logical: canonicalLogical,
138
+ logical: logicalIdentity,
406
139
  backend: route.backend,
407
140
  provider: route.provider,
408
- gateway: route.gateway ?? "",
409
141
  modelFamily: route.modelFamily,
410
142
  modelSnapshot: route.modelSnapshot,
411
143
  modelVariant: route.modelVariant ?? "",
@@ -431,56 +163,162 @@ export function freezeRoutePlan(plan: ResolvedRoutePlan): ResolvedRoutePlan {
431
163
  return deepFreeze(plan);
432
164
  }
433
165
 
434
- export function resolveLogicalModel(
435
- cliModel?: string,
436
- specModel?: string,
437
- frontmatterModel?: string,
438
- stepName?: string,
439
- ): string {
440
- const model = cliModel ?? specModel ?? frontmatterModel;
441
- if (!model || (typeof model === "string" && model.trim().length === 0)) {
442
- throw new ModelRoutingError(
443
- `agent ${stepName ?? "step"} has no model and no override given`,
444
- );
445
- }
446
- return model.trim();
447
- }
448
-
449
166
  export interface ResolveStepRouteInput {
450
167
  readonly stepKey: string;
451
168
  readonly role: string;
169
+ // The `models` key this step reads (`hunter.logic`, `refuter`, `summary`,
170
+ // `scout`, `consolidate`). Absent: only `models.default` is consulted.
171
+ readonly modelRole?: string;
452
172
  readonly cliModel?: string;
453
173
  readonly specModel?: string;
454
174
  readonly frontmatterModel?: string;
455
- readonly routingConfig?: RoutingConfig;
175
+ readonly models?: ModelsConfig;
176
+ }
177
+
178
+ // The precedence (L5, L6 item 5):
179
+ // 1. `--model` (cliModel), the operator's override for one run;
180
+ // 2. the review spec's own model for the agent (AgentSpec.model: the lab's
181
+ // spec and the diversity legs, whose whole point is to differ);
182
+ // 3. `models[role]`;
183
+ // 4. `models.default`;
184
+ // 5. the prompt's own alias, converted to `claude:<alias>-latest`.
185
+ // 1, 2 and 5 are internal or legacy inputs and keep accepting bare aliases.
186
+ //
187
+ // Only `models` holds a list. Its first model is the step's route and the rest
188
+ // are its fallbacks, tried in order when the provider fails the one before
189
+ // (S4; the runner side is model-fallback.ts). Every other source names one
190
+ // model, so it has no fallbacks. Only a `models` entry carries an effort (S7,
191
+ // D4: `--model`, the CI input and a spec's model take a model only).
192
+ interface StepModel {
193
+ readonly name: ModelName;
194
+ readonly effort?: string;
195
+ }
196
+
197
+ function stepModelOf(entry: ModelListEntry, stepKey: string): StepModel {
198
+ const { name, effort } = modelEntry(entry);
199
+ const parsed = toModelName(name, "models", stepKey);
200
+ return effort === undefined ? { name: parsed } : { name: parsed, effort };
201
+ }
202
+
203
+ function resolveStepChoices(
204
+ input: ResolveStepRouteInput,
205
+ ): [StepModel, ...StepModel[]] {
206
+ if (input.cliModel !== undefined) {
207
+ return [{ name: toModelName(input.cliModel, "--model", input.stepKey) }];
208
+ }
209
+ if (input.specModel !== undefined) {
210
+ return [{ name: toModelName(input.specModel, "spec", input.stepKey) }];
211
+ }
212
+ const configured =
213
+ (input.modelRole === undefined
214
+ ? undefined
215
+ : input.models?.[input.modelRole]) ?? input.models?.default;
216
+ if (configured !== undefined && configured.length > 0) {
217
+ const [first, ...rest] = configured;
218
+ return [
219
+ stepModelOf(first, input.stepKey),
220
+ ...rest.map((entry) => stepModelOf(entry, input.stepKey)),
221
+ ];
222
+ }
223
+ if (
224
+ input.frontmatterModel !== undefined &&
225
+ input.frontmatterModel.trim().length > 0
226
+ ) {
227
+ return [
228
+ { name: toModelName(input.frontmatterModel, "prompt", input.stepKey) },
229
+ ];
230
+ }
231
+ throw new ModelRoutingError(
232
+ `agent ${input.stepKey} has no model and no override given`,
233
+ );
234
+ }
235
+
236
+ export function resolveStepModels(
237
+ input: ResolveStepRouteInput,
238
+ ): [ModelName, ...ModelName[]] {
239
+ const [first, ...rest] = resolveStepChoices(input);
240
+ return [first.name, ...rest.map((choice) => choice.name)];
241
+ }
242
+
243
+ export function resolveStepModel(input: ResolveStepRouteInput): ModelName {
244
+ return resolveStepModels(input)[0];
456
245
  }
457
246
 
458
247
  export function resolveStepRoute(
459
248
  input: ResolveStepRouteInput,
460
249
  ): ResolvedStepRoute {
461
- const logical = resolveLogicalModel(
462
- input.cliModel,
463
- input.specModel,
464
- input.frontmatterModel,
465
- input.stepKey,
466
- );
467
- const parsed = parseLogicalIdentity(logical);
468
- const route = resolveModelRoute(logical, input.routingConfig);
469
- const routeFingerprint = computeRouteFingerprint(parsed.canonical, route);
250
+ const [first, ...rest] = resolveStepChoices(input);
251
+ const route = stepRouteFor(input.stepKey, input.role, first);
252
+ if (rest.length === 0) return route;
253
+ return {
254
+ ...route,
255
+ fallbacks: rest.map((choice) =>
256
+ stepRouteFor(input.stepKey, input.role, choice),
257
+ ),
258
+ };
259
+ }
260
+
261
+ // One `models` entry as a step of its own, with no role precedence: what
262
+ // `crysk doctor` probes for each model a config names.
263
+ export function resolveModelEntryRoute(
264
+ stepKey: string,
265
+ role: string,
266
+ entry: ModelListEntry,
267
+ ): ResolvedStepRoute {
268
+ return stepRouteFor(stepKey, role, stepModelOf(entry, stepKey));
269
+ }
270
+
271
+ // Every route a plan may execute: each step's model, then each step's
272
+ // fallbacks. Whatever binds, admits or picks a credential for a plan reads
273
+ // this, never `plan.steps` alone, so a fallback that cannot run fails before
274
+ // the run spends anything (S4) instead of when its turn comes.
275
+ export function planRoutes(
276
+ plan: ResolvedRoutePlan,
277
+ ): readonly ResolvedStepRoute[] {
278
+ const fallbacks = plan.steps.flatMap((step) => step.fallbacks ?? []);
279
+ return fallbacks.length === 0 ? plan.steps : [...plan.steps, ...fallbacks];
280
+ }
281
+
282
+ function stepRouteFor(
283
+ stepKey: string,
284
+ role: string,
285
+ { name, effort }: StepModel,
286
+ ): ResolvedStepRoute {
287
+ const route = routeForModel(name, effort);
470
288
  return {
471
- stepKey: input.stepKey,
472
- role: input.role,
473
- logicalIdentity: parsed.canonical,
289
+ stepKey,
290
+ role,
291
+ logicalIdentity: name.raw,
474
292
  route,
475
- routeFingerprint,
293
+ routeFingerprint: computeRouteFingerprint(name.raw, route),
294
+ ...(effort === undefined ? {} : { effort }),
476
295
  };
477
296
  }
478
297
 
298
+ // An internal model string (a bare alias or a full name) as a route, with no
299
+ // role and no `models`: what a caller outside the plan needs to know which
300
+ // backend a model runs on.
301
+ export function resolveModelRoute(model: string): ResolvedModelRoute {
302
+ return routeForModel(toModelName(model, "spec", "route"));
303
+ }
304
+
479
305
  export function createResolvedRoutePlan(
480
306
  steps: readonly ResolvedStepRoute[],
481
307
  ): ResolvedRoutePlan {
308
+ // A step's fallbacks join its entry only when it has some, and an entry's
309
+ // effort only when it sets one, so a plan with no lists and no efforts keeps
310
+ // the fingerprint it always had. The effort is part of the plan, not of the
311
+ // route: two runs that differ only in effort are different plans, while the
312
+ // same model at two efforts still shares its binding (Juanma, L38).
313
+ const withEffort = (s: ResolvedStepRoute) =>
314
+ `${s.routeFingerprint}${s.effort === undefined ? "" : `@${s.effort}`}`;
482
315
  const sortedFingerprints = steps
483
- .map((s) => `${s.stepKey}:${s.routeFingerprint}`)
316
+ .map(
317
+ (s) =>
318
+ `${s.stepKey}:${withEffort(s)}${(s.fallbacks ?? [])
319
+ .map((f) => `>${withEffort(f)}`)
320
+ .join("")}`,
321
+ )
484
322
  .sort()
485
323
  .join(";");
486
324
  const planFingerprint = createHash("sha256")
@@ -501,10 +339,52 @@ export function agentStepKey(agent: { key: string; role: string }): string {
501
339
  return agent.key;
502
340
  }
503
341
 
342
+ interface RouteAgent {
343
+ readonly key: string;
344
+ readonly role: string;
345
+ readonly model?: string;
346
+ readonly specialty?: string;
347
+ }
348
+
349
+ // The `models` key an agent reads. A hunter reads `hunter.<specialty>`, so a
350
+ // diversity leg (`reliability--<leg>`) reads its base hunter's role. The
351
+ // refuter role also covers the verifier and the adjudicator: they run under
352
+ // the refuter agent's step key and so share its route.
353
+ function agentModelRole(agent: RouteAgent): string | undefined {
354
+ if (agent.role === "hunter") return hunterRole(agent.specialty ?? agent.key);
355
+ if (agent.role === "refuter") return "refuter";
356
+ return undefined;
357
+ }
358
+
359
+ // `hunter.<key>` is open at parse time (the spec is not loaded yet), so it is
360
+ // checked here, against EVERY hunter the spec declares, not only the ones that
361
+ // fire: parity is conditional, and its role must not read as a typo on the
362
+ // runs where it stays quiet.
363
+ function assertHunterRolesExist(
364
+ models: ModelsConfig | undefined,
365
+ agents: readonly RouteAgent[],
366
+ ): void {
367
+ if (models === undefined) return;
368
+ const hunters = [
369
+ ...new Set(
370
+ agents
371
+ .filter((agent) => agent.role === "hunter")
372
+ .map((agent) => agent.specialty ?? agent.key),
373
+ ),
374
+ ];
375
+ for (const role of Object.keys(models)) {
376
+ if (!role.startsWith("hunter.") || !isModelRole(role)) continue;
377
+ if (hunters.includes(role.slice("hunter.".length))) continue;
378
+ throw new InvalidModelError(
379
+ `models.${role} names no hunter in this review: its hunters are ${hunters.join(", ")}`,
380
+ );
381
+ }
382
+ }
383
+
504
384
  export interface BuildRoutePlanInput {
505
- readonly agents: readonly { key: string; role: string; model?: string }[];
385
+ readonly agents: readonly RouteAgent[];
506
386
  readonly cliModel?: string;
507
- readonly routingConfig?: RoutingConfig;
387
+ readonly models?: ModelsConfig;
508
388
  readonly frontmatterModel?: (agentKey: string) => string | undefined;
509
389
  readonly summarizer?: { model?: string; frontmatterModel?: string };
510
390
  readonly scout?: {
@@ -530,65 +410,72 @@ export const MATERIALITY_STEP_KEY = "materiality";
530
410
  // (same bundled prompt, same bar; both passed, lab bench/METRICS.md
531
411
  // 2026-11-01); sonnet was chosen because it costs half for a difference within
532
412
  // one run's noise. A judge on any other model or transport is a different,
533
- // unmeasured judge. So the model
534
- // is pinned (never `--model`, never the routing default model) and the route is
535
- // returned only when it lands on the claude-code backend.
413
+ // unmeasured judge. So `models.judge` may pick between those two only, and
414
+ // neither `--model` nor `models.default` ever moves it (L6 item 5).
415
+ // MATERIALITY_JUDGE_MODEL is the alias a run with no route plan sends.
536
416
  export const MATERIALITY_JUDGE_MODEL = "sonnet";
417
+ export const MEASURED_JUDGE_MODELS: readonly string[] = [
418
+ "claude:sonnet-latest",
419
+ "claude:opus-latest",
420
+ ];
421
+
422
+ // The judge's model, and what `models.judge` listed that it cannot use. With no
423
+ // `models.judge`, the measured default.
424
+ export function judgeModelChoice(models: ModelsConfig | undefined): {
425
+ model?: string;
426
+ dropped: string[];
427
+ } {
428
+ // Names only: models.judge takes no effort (D3), so an entry is its name.
429
+ const listed = (
430
+ models?.judge ?? [`claude:${MATERIALITY_JUDGE_MODEL}-latest`]
431
+ ).map((entry) => modelEntry(entry).name);
432
+ const usable = listed.filter((name) => MEASURED_JUDGE_MODELS.includes(name));
433
+ return {
434
+ ...(usable.length === 0 ? {} : { model: usable[0] }),
435
+ dropped: listed.filter((name) => !MEASURED_JUDGE_MODELS.includes(name)),
436
+ };
437
+ }
537
438
 
538
- // The judge's route, or undefined when it would not run the measured judge:
539
- // the routing config sends sonnet to another backend, or cannot resolve it at
540
- // all (a disabled route, an unmapped snapshot). Never throws: the gate is
541
- // optional and fails open toward blocking, so a route it cannot use must make
542
- // the stage stand down, never kill the run. Omitting a non-claude route from
543
- // the plan also keeps route admission from gating the run on a step that will
544
- // never spawn.
439
+ // The judge's route, or undefined when no measured model is left: the gate is
440
+ // optional and fails open toward blocking, so a judge it cannot run must make
441
+ // the stage stand down, never kill the run. Omitting it from the plan also
442
+ // keeps route admission from gating the run on a step that will never spawn.
545
443
  export function resolveMaterialityJudgeRoute(
546
- routingConfig: RoutingConfig | undefined,
444
+ models: ModelsConfig | undefined,
547
445
  ): ResolvedStepRoute | undefined {
548
- let step: ResolvedStepRoute;
549
- try {
550
- step = resolveStepRoute({
551
- stepKey: MATERIALITY_STEP_KEY,
552
- role: "other",
553
- specModel: MATERIALITY_JUDGE_MODEL,
554
- routingConfig,
555
- });
556
- } catch {
557
- return undefined;
558
- }
559
- return isMeasuredJudgeRoute(step.route) ? step : undefined;
446
+ const { model } = judgeModelChoice(models);
447
+ if (model === undefined) return undefined;
448
+ return stepRouteFor(MATERIALITY_STEP_KEY, "other", {
449
+ name: parseModelName(model),
450
+ });
560
451
  }
561
452
 
562
- // The route the judge was measured on: the Claude Code CLI talking straight to
563
- // Anthropic. Through any other gateway, spawnModelForClaudeCli passes the
564
- // mapping's modelSnapshot verbatim as --model, so a claude-code route over
565
- // openrouter or a configured gateway can run an arbitrary model — a different,
566
- // unmeasured judge that the pinned prompt hash cannot detect.
567
- export function isMeasuredJudgeRoute(route: {
568
- backend: string;
569
- provider: string;
570
- gateway?: string;
571
- }): boolean {
453
+ // The route the judge was measured on: sonnet or opus, through the Claude Code
454
+ // CLI talking to Anthropic.
455
+ export function isMeasuredJudgeRoute(route: ResolvedModelRoute): boolean {
572
456
  return (
573
457
  route.backend === "claude-code" &&
574
458
  route.provider === "anthropic" &&
575
- (route.gateway === undefined || route.gateway === "direct")
459
+ (route.modelSnapshot === "sonnet" || route.modelSnapshot === "opus")
576
460
  );
577
461
  }
578
462
 
579
463
  export function buildResolvedRoutePlan(
580
464
  input: BuildRoutePlanInput,
581
465
  ): ResolvedRoutePlan {
466
+ assertHunterRolesExist(input.models, input.agents);
582
467
  const stepRoutes: ResolvedStepRoute[] = [];
583
468
  for (const agent of input.agents) {
469
+ const modelRole = agentModelRole(agent);
584
470
  stepRoutes.push(
585
471
  resolveStepRoute({
586
472
  stepKey: agentStepKey(agent),
587
473
  role: agent.role,
474
+ ...(modelRole === undefined ? {} : { modelRole }),
588
475
  cliModel: input.cliModel,
589
476
  specModel: agent.model,
590
477
  frontmatterModel: input.frontmatterModel?.(agent.key),
591
- routingConfig: input.routingConfig,
478
+ models: input.models,
592
479
  }),
593
480
  );
594
481
  }
@@ -597,10 +484,11 @@ export function buildResolvedRoutePlan(
597
484
  resolveStepRoute({
598
485
  stepKey: "summarizer",
599
486
  role: "summarizer",
487
+ modelRole: "summary",
600
488
  cliModel: input.cliModel,
601
489
  specModel: input.summarizer.model,
602
490
  frontmatterModel: input.summarizer.frontmatterModel,
603
- routingConfig: input.routingConfig,
491
+ models: input.models,
604
492
  }),
605
493
  );
606
494
  }
@@ -609,10 +497,12 @@ export function buildResolvedRoutePlan(
609
497
  resolveStepRoute({
610
498
  stepKey: "scout",
611
499
  role: "scout",
612
- cliModel: input.scout.model ?? input.cliModel,
500
+ modelRole: "scout",
501
+ // `--model` outranks `--scout-model`, as the scout step records it.
502
+ cliModel: input.cliModel ?? input.scout.model,
613
503
  frontmatterModel:
614
504
  input.scout.frontmatterModel ?? input.scout.defaultModel,
615
- routingConfig: input.routingConfig,
505
+ models: input.models,
616
506
  }),
617
507
  );
618
508
  }
@@ -621,42 +511,31 @@ export function buildResolvedRoutePlan(
621
511
  resolveStepRoute({
622
512
  stepKey: "consolidate",
623
513
  role: "other",
514
+ modelRole: "consolidate",
624
515
  cliModel: input.consolidate.model ?? input.cliModel,
625
516
  frontmatterModel:
626
517
  input.consolidate.frontmatterModel ?? input.consolidate.defaultModel,
627
- routingConfig: input.routingConfig,
518
+ models: input.models,
628
519
  }),
629
520
  );
630
521
  }
631
522
  if (input.materiality) {
632
- // No `cliModel` on purpose: `--model sonnet` must not move the judge.
633
- const judge = resolveMaterialityJudgeRoute(input.routingConfig);
634
- if (judge !== undefined) stepRoutes.push(judge);
635
- }
636
- return createResolvedRoutePlan(stepRoutes);
637
- }
638
-
639
- export function spawnModelForClaudeCli(
640
- route: ResolvedModelRoute,
641
- executionModel: string,
642
- ): string {
643
- const gateway = route.gateway ?? "direct";
644
- if (gateway !== "direct") {
645
- return route.modelSnapshot;
646
- }
647
- if (isModelAlias(executionModel)) {
648
- return executionModel;
649
- }
650
- try {
651
- const parsed = parseLogicalIdentity(executionModel);
652
- const alias = reverseAliasForCanonical(
653
- `${parsed.provider}/${parsed.model}`,
523
+ // No `cliModel` and no `models.default` on purpose (judgeModelChoice).
524
+ const judge = resolveMaterialityJudgeRoute(input.models);
525
+ // With no `models.judge`, the judge joins only a plan that already runs a
526
+ // Claude step: on a plan with none, the runner may hold no Claude
527
+ // credential, and a judge it cannot bind must stand down rather than fail
528
+ // admission for the whole run. An explicit `models.judge` is the operator
529
+ // saying the judge can run, so it always joins.
530
+ const hasClaudeStep = stepRoutes.some(
531
+ (s) => s.route.backend === "claude-code",
654
532
  );
655
- if (alias !== undefined) {
656
- return alias;
533
+ if (
534
+ judge !== undefined &&
535
+ (input.models?.judge !== undefined || hasClaudeStep)
536
+ ) {
537
+ stepRoutes.push(judge);
657
538
  }
658
- } catch {
659
- // executionModel is not a catalog alias or slash-grammar identity.
660
539
  }
661
- return route.modelSnapshot;
540
+ return createResolvedRoutePlan(stepRoutes);
662
541
  }