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
@@ -8,7 +8,7 @@
8
8
  // a renderer that reached for `new Date()` would make that a lie).
9
9
 
10
10
  import { listPaths } from "#git/refs";
11
- import type { ResolvedModelRoute, ResolvedStepRoute } from "#model/routing";
11
+ import type { ResolvedRoutePlan, ResolvedStepRoute } from "#model/routing";
12
12
  import type { PostMinSeverity } from "#pr/post-floor";
13
13
  import {
14
14
  type CiMode,
@@ -1864,40 +1864,40 @@ function round2(value: number): number {
1864
1864
  return Math.round(value * 100) / 100;
1865
1865
  }
1866
1866
 
1867
- export function formatModelRoute(
1868
- route: ResolvedModelRoute,
1869
- logicalIdentity?: string,
1870
- ): string {
1871
- const variant = route.modelVariant ? `#${route.modelVariant}` : "";
1872
- const modelName = route.modelSnapshot || route.modelFamily;
1873
- const target = `${route.provider}/${modelName}${variant}`;
1874
- const gateway = route.gateway ?? "direct";
1875
- const dims = `[${gateway}, ${route.backend}]`;
1876
- if (logicalIdentity && logicalIdentity !== target) {
1877
- return `${logicalIdentity} -> ${target} ${dims}`;
1878
- }
1879
- return `${target} ${dims}`;
1880
- }
1881
-
1882
- export function formatStepRoute(
1883
- step: ResolvedStepRoute,
1884
- rawLogical?: string,
1885
- ): string {
1886
- return formatModelRoute(step.route, rawLogical ?? step.logicalIdentity);
1867
+ // A step's route as the plan card shows it: the model name it resolved to,
1868
+ // which already says its backend (`claude:sonnet-latest`,
1869
+ // `opencode:openai/gpt-5`), and its `models` entry's effort when it sets one,
1870
+ // in the config row's form (`claude:opus-latest (effort max)`, S7). It
1871
+ // replaced `alias -> provider/model [gateway, backend]`, whose gateway no
1872
+ // longer exists.
1873
+ export function formatStepRoute(step: ResolvedStepRoute): string {
1874
+ return step.effort === undefined
1875
+ ? step.logicalIdentity
1876
+ : `${step.logicalIdentity} (effort ${step.effort})`;
1887
1877
  }
1888
1878
 
1889
1879
  // The envelope needs ONE model string. With no --model override each agent
1890
- // carries its own frontmatter model, so report what actually ran rather than
1891
- // inventing a single value: identical models collapse to one name, a mixed
1892
- // set is recorded as a mix instead of as a lie.
1880
+ // carries its own model, so report what actually ran rather than inventing a
1881
+ // single value: identical models collapse to one name, a mixed set is
1882
+ // recorded as a mix instead of as a lie. With a route plan, "what ran" is the
1883
+ // plan's model for the hunters and the refuter (`models` moves them off their
1884
+ // frontmatter); a zero-config plan names the same aliases the frontmatter does.
1893
1885
  export function envelopeModel(
1894
1886
  options: { model?: string },
1895
1887
  agentFiles: Map<string, { model?: string }>,
1888
+ routePlan?: ResolvedRoutePlan,
1896
1889
  ): string {
1897
1890
  if (options.model) return options.model;
1898
1891
  const models = new Set<string>();
1899
- for (const agent of agentFiles.values()) {
1900
- if (agent.model) models.add(agent.model);
1892
+ const agentSteps = (routePlan?.steps ?? []).filter(
1893
+ (step) => step.role === "hunter" || step.role === "refuter",
1894
+ );
1895
+ if (agentSteps.length > 0) {
1896
+ for (const step of agentSteps) models.add(step.route.modelSnapshot);
1897
+ } else {
1898
+ for (const agent of agentFiles.values()) {
1899
+ if (agent.model) models.add(agent.model);
1900
+ }
1901
1901
  }
1902
1902
  if (models.size === 0) return "unspecified";
1903
1903
  return [...models].sort().join("+");
@@ -24,6 +24,7 @@ import {
24
24
  } from "#git/git";
25
25
  import { engineIdentity } from "#git/identity";
26
26
  import { countFreeRouteSteps } from "#model/free-discovery";
27
+ import { planRoutes } from "#model/routing";
27
28
  import { reviewPr } from "#pr/review-pr";
28
29
  import type { Telemetry } from "#review/findings";
29
30
  import { type PipelineResult, runPipeline } from "#review/pipeline";
@@ -80,6 +81,7 @@ import { prheroLayout } from "../home-preflight";
80
81
  import { readLocalIgnoreRules } from "../ignore-read";
81
82
  import type { ProductionRuntime } from "../production-runtime";
82
83
  import { resolveRunnerAuthority } from "../runner-authority";
84
+ import { resolveRunClaudeCredential } from "../security/claude-credential";
83
85
 
84
86
  export async function review(options: CliOptions): Promise<number> {
85
87
  // PR mode is a different front half (gh-resolved range, detached worktree)
@@ -105,6 +107,12 @@ export async function review(options: CliOptions): Promise<number> {
105
107
  options,
106
108
  });
107
109
  options = { ...options, scout, post };
110
+ // S5: the Claude credential this run uses, chosen once, here, from
111
+ // `credentials.claude` and what is set. Every runner, binding and child below
112
+ // reads its env, which holds that one credential and no other.
113
+ const claudeRun = resolveRunClaudeCredential({
114
+ credentials: config.credentials,
115
+ });
108
116
 
109
117
  // 3 — the base ref, then the canonical refs and the range.
110
118
  const baseRef = await resolveBase(repoRoot, options, config);
@@ -242,14 +250,15 @@ export async function review(options: CliOptions): Promise<number> {
242
250
  true,
243
251
  );
244
252
  const productionRoute = await resolvePipelineRoute({
245
- routingConfigured: config.routing !== undefined,
253
+ modelsConfigured: config.models !== undefined,
246
254
  workspaceRoot: repoRoot,
247
255
  spec,
248
256
  options,
249
257
  agentFiles,
250
- routingConfig: config.routing,
258
+ models: config.models,
251
259
  summary,
252
260
  materialityEnabled: resolveMaterialityGate(config),
261
+ claudeRun: options.dryRun ? undefined : claudeRun,
253
262
  });
254
263
  const routePlan = productionRoute?.routePlan;
255
264
  const productionAdmission = productionRoute?.productionAdmission;
@@ -259,8 +268,12 @@ export async function review(options: CliOptions): Promise<number> {
259
268
  routePlan === undefined || productionAdmission === undefined
260
269
  ? undefined
261
270
  : await countFreeRouteSteps({
262
- steps: routePlan.steps,
271
+ steps: planRoutes(routePlan),
263
272
  probe: productionAdmission.freeModelProbe,
273
+ // The CRYSK_OPENCODE_* names admission bound each route's kind with,
274
+ // so the card counts free exactly the routes admission probed (U3).
275
+ openCodeSecretNames:
276
+ productionAdmission.authorityOptions.openCodeSecretNames,
264
277
  });
265
278
  // Named rather than inlined into renderPlan: the same context is what the
266
279
  // confirm menu's "Show details" renders, and building it twice would risk
@@ -311,6 +324,10 @@ export async function review(options: CliOptions): Promise<number> {
311
324
  // claude-code ProviderCapabilityReport path byte-compatible.
312
325
  const runnerAuthority = await resolveRunnerAuthority({
313
326
  workspaceRoot: repoRoot,
327
+ env: claudeRun.env,
328
+ ...(claudeRun.kind === undefined
329
+ ? {}
330
+ : { claudeCredential: claudeRun.kind }),
314
331
  });
315
332
  await enforceCapabilityGate({
316
333
  routePlan,
@@ -2,19 +2,22 @@
2
2
  // enforce executable and provider capability gates, and admit production
3
3
  // routes across Claude and OpenCode runners before confirming or spending tokens.
4
4
 
5
+ import type { ModelsConfig } from "#model/model-name";
5
6
  import {
6
7
  capabilityGateDecision,
7
8
  produceClaudeCapabilityReport,
8
9
  } from "#model/provider-capabilities";
9
10
  import {
10
11
  buildResolvedRoutePlan,
12
+ InvalidModelError,
13
+ planRoutes,
11
14
  type ResolvedRoutePlan,
12
- type RoutingConfig,
13
15
  } from "#model/routing";
14
16
  import { resolveEngineAssets } from "../assets";
15
17
  import { CliError } from "../errors";
16
18
  import type { RunnerBackend } from "../execution/contracts";
17
19
  import {
20
+ type OpenCodeCredentialRefusal,
18
21
  type ProductionAdmissionContext,
19
22
  prepareProductionAdmissionContext,
20
23
  probeBindingsReadiness,
@@ -24,6 +27,12 @@ import type {
24
27
  RunnerAuthorityOptions,
25
28
  RunnerAuthorityResolution,
26
29
  } from "../runner-authority";
30
+ import {
31
+ ClaudeCredentialRefusalError,
32
+ CredentialRefusalError,
33
+ claudeCredentialRefusal,
34
+ type RunClaudeCredential,
35
+ } from "../security/claude-credential";
27
36
  import {
28
37
  admitRoutePlan,
29
38
  createDefaultTransportRegistry,
@@ -111,7 +120,7 @@ export async function buildCliRoutePlan(params: {
111
120
  spec: ReviewSpec;
112
121
  options: CliOptions;
113
122
  agentFiles: Map<string, ParsedAgent>;
114
- routingConfig?: RoutingConfig;
123
+ models?: ModelsConfig;
115
124
  summary: SummarySettings;
116
125
  summarizerEnabled?: boolean;
117
126
  scoutEnabled?: boolean;
@@ -163,7 +172,7 @@ export async function buildCliRoutePlan(params: {
163
172
  return buildResolvedRoutePlan({
164
173
  agents: params.spec.agents,
165
174
  cliModel: params.options.model,
166
- routingConfig: params.routingConfig,
175
+ models: params.models,
167
176
  frontmatterModel: (agentKey) => params.agentFiles.get(agentKey)?.model,
168
177
  ...(summarizerEnabled
169
178
  ? {
@@ -196,11 +205,19 @@ export async function buildCliRoutePlan(params: {
196
205
  });
197
206
  }
198
207
 
199
- // Pre-confirm route resolution: legacy runs without operator routing may omit
200
- // route provenance when the plan cannot be built, but admission failures must
208
+ // Whether a plan that failed to build may fall back to the legacy no-plan
209
+ // path (a prompt or `--model` naming a raw Claude id the CLI resolves itself).
210
+ // Never when `models` is set, and never for a model written in the new form:
211
+ // both are the operator's words, and the error is how to fix them.
212
+ function planErrorIsFatal(error: unknown, modelsConfigured: boolean): boolean {
213
+ return modelsConfigured || error instanceof InvalidModelError;
214
+ }
215
+
216
+ // Pre-confirm route resolution: legacy runs without `models` may omit route
217
+ // provenance when the plan cannot be built, but admission failures must
201
218
  // always surface before confirm — never be swallowed into routePlan = undefined.
202
219
  export async function resolveRoutePlanAtConfirm(input: {
203
- routingConfigured: boolean;
220
+ modelsConfigured: boolean;
204
221
  buildRoutePlan: () => Promise<ResolvedRoutePlan>;
205
222
  registry?: TransportRegistry;
206
223
  }): Promise<ResolvedRoutePlan | undefined> {
@@ -210,13 +227,28 @@ export async function resolveRoutePlanAtConfirm(input: {
210
227
  try {
211
228
  routePlan = await input.buildRoutePlan();
212
229
  } catch (error) {
213
- if (input.routingConfigured) throw error;
230
+ if (planErrorIsFatal(error, input.modelsConfigured)) throw error;
214
231
  return undefined;
215
232
  }
216
233
  await admitRoutePlan(routePlan, registry);
217
234
  return routePlan;
218
235
  }
219
236
 
237
+ // The OpenCode refusal: a route the plan runs has no credential record in the run's
238
+ // OpenCode auth file (openCodeCredentialRefusal, production-runtime.ts). It is the
239
+ // failure the route's first step would hit (CRYSK-CRED-UNUSABLE), raised before any
240
+ // spend.
241
+ export class OpenCodeCredentialRefusalError extends CredentialRefusalError {
242
+ constructor(refusal: OpenCodeCredentialRefusal) {
243
+ super(
244
+ refusal.message,
245
+ { kind: "credential", failureClass: refusal.failureClass },
246
+ refusal.params,
247
+ `no credential record for OpenCode provider ${refusal.params.provider}; refused before any provider spend`,
248
+ );
249
+ }
250
+ }
251
+
220
252
  export interface ProductionRoutePlanResult {
221
253
  readonly routePlan: ResolvedRoutePlan;
222
254
  readonly productionAdmission: ProductionAdmissionContext;
@@ -225,29 +257,59 @@ export interface ProductionRoutePlanResult {
225
257
  // Production admission: discover per-backend executable authority, derive
226
258
  // D1-11 evidence from exact-binding probes, and admit with one shared registry.
227
259
  export async function resolveProductionRoutePlanAtConfirm(input: {
228
- routingConfigured: boolean;
260
+ modelsConfigured: boolean;
229
261
  workspaceRoot: string;
230
262
  buildRoutePlan: () => Promise<ResolvedRoutePlan>;
231
263
  authorityDeps?: ResolveRunnerAuthorityDeps;
232
264
  loadSdk?: () => Promise<OpenCodeSdkLike>;
233
265
  env?: RunnerAuthorityOptions["env"];
266
+ // S5: the Claude credential chosen at run start. Its env replaces `env` (it is the
267
+ // process environment with one Claude credential left), and a plan that needs
268
+ // Claude with no listed credential present is refused here, before admission.
269
+ claudeRun?: RunClaudeCredential;
270
+ // False on a dry run, which authenticates nothing: no OpenCode route is refused
271
+ // for a missing record (the Claude check is skipped by passing no claudeRun).
272
+ checkCredentials?: boolean;
234
273
  }): Promise<ProductionRoutePlanResult | undefined> {
274
+ const refuse = (planHasClaudeRoute: boolean): void => {
275
+ if (input.claudeRun === undefined) return;
276
+ const refusal = claudeCredentialRefusal(
277
+ input.claudeRun.selection,
278
+ planHasClaudeRoute,
279
+ );
280
+ if (refusal !== undefined) throw new ClaudeCredentialRefusalError(refusal);
281
+ };
235
282
  let routePlan: ResolvedRoutePlan;
236
283
  try {
237
284
  routePlan = await input.buildRoutePlan();
238
285
  } catch (error) {
239
- if (input.routingConfigured) throw error;
286
+ if (planErrorIsFatal(error, input.modelsConfigured)) throw error;
287
+ // The legacy no-plan path runs every step on the Claude CLI.
288
+ refuse(true);
240
289
  return undefined;
241
290
  }
291
+ refuse(
292
+ planRoutes(routePlan).some((step) => step.route.backend === "claude-code"),
293
+ );
242
294
 
295
+ const env = input.claudeRun?.env ?? input.env;
243
296
  const productionAdmission = await prepareProductionAdmissionContext({
244
297
  workspaceRoot: input.workspaceRoot,
245
298
  plan: routePlan,
246
299
  authorityDeps: input.authorityDeps,
247
300
  loadSdk: input.loadSdk,
248
- env: input.env,
301
+ ...(input.checkCredentials === false ? { checkCredentials: false } : {}),
302
+ ...(env === undefined ? {} : { env }),
303
+ ...(input.claudeRun?.kind === undefined
304
+ ? {}
305
+ : { claudeCredential: input.claudeRun.kind }),
249
306
  });
250
307
  if ("error" in productionAdmission) {
308
+ if (productionAdmission.credentialRefusal !== undefined) {
309
+ throw new OpenCodeCredentialRefusalError(
310
+ productionAdmission.credentialRefusal,
311
+ );
312
+ }
251
313
  throw new CliError(
252
314
  `production admission failed: ${productionAdmission.error}`,
253
315
  );
@@ -273,7 +335,13 @@ export async function enforceProviderCapabilityGate(input: {
273
335
  `execution authority unavailable: ${input.runnerAuthority.error}`,
274
336
  );
275
337
  }
276
- const capabilityReport = await produceClaudeCapabilityReport({});
338
+ // S5: the run env (one Claude credential, under the CLI's name), the same object
339
+ // the legacy runner hands its child, so the auth check sees the credential the
340
+ // run chose (a CRYSK_* secret included) and never one it stripped.
341
+ const runEnv = input.runnerAuthority?.runnerOptions?.childEnv;
342
+ const capabilityReport = await produceClaudeCapabilityReport(
343
+ runEnv === undefined ? {} : { env: { ...runEnv } },
344
+ );
277
345
  const capabilityGate = capabilityGateDecision(capabilityReport);
278
346
  if (!capabilityGate.ok) {
279
347
  throw new CliError(
package/src/review/run.ts CHANGED
@@ -21,7 +21,8 @@ import {
21
21
  loadEffectiveConfig,
22
22
  notionalCostInput,
23
23
  } from "#config/config";
24
- import type { ResolvedRoutePlan, RoutingConfig } from "#model/routing";
24
+ import type { ModelsConfig } from "#model/model-name";
25
+ import type { ResolvedRoutePlan } from "#model/routing";
25
26
  import type { CiMode } from "#pr/preflight";
26
27
  import {
27
28
  type FindingsDocument,
@@ -90,6 +91,7 @@ import {
90
91
  type ProductionRuntime,
91
92
  } from "../production-runtime";
92
93
  import type { RunnerAuthorityResolution } from "../runner-authority";
94
+ import type { RunClaudeCredential } from "../security/claude-credential";
93
95
 
94
96
  // The codegraph server, and ONLY the codegraph server. Written per run and
95
97
  // handed to every step together with the runner's --strict-mcp-config: an
@@ -129,12 +131,19 @@ export async function loadRunConfig(params: {
129
131
  home: string;
130
132
  configFlag: string | undefined;
131
133
  options: Pick<CliOptions, "summary" | "model" | "scout" | "post">;
134
+ // Where config warnings go. Defaults to stderr, beside every other
135
+ // `warning:` line a run prints.
136
+ warn?: (line: string) => void;
132
137
  }): Promise<LoadedRunConfig> {
133
138
  const loaded = await loadEffectiveConfig({
134
139
  root: params.root,
135
140
  home: params.home,
136
141
  configFlag: params.configFlag,
137
142
  });
143
+ const warn =
144
+ params.warn ??
145
+ ((line: string) => process.stderr.write(`warning: ${line}\n`));
146
+ for (const line of loaded.warnings) warn(line);
138
147
  const config = loaded.effective;
139
148
  const summary = resolveSummary(params.options, config);
140
149
  const scout = resolveScout(params.options, config);
@@ -360,7 +369,11 @@ export async function writeRunFindings(params: {
360
369
  pr: params.pr,
361
370
  base_sha: params.baseSha,
362
371
  head_sha: params.headSha,
363
- model: envelopeModel(params.options, params.agentFiles),
372
+ model: envelopeModel(
373
+ params.options,
374
+ params.agentFiles,
375
+ params.result.routePlan,
376
+ ),
364
377
  iteration: 0,
365
378
  prompt_set: params.promptSet,
366
379
  engine: params.engine,
@@ -487,27 +500,36 @@ export async function writeMcpConfig(
487
500
  // wraps — `resolveProductionRoute` reads as a near-duplicate of that name at
488
501
  // a glance, which is exactly the confusion a shared wrapper should not add.
489
502
  export async function resolvePipelineRoute(params: {
490
- routingConfigured: boolean;
503
+ modelsConfigured: boolean;
491
504
  workspaceRoot: string;
492
505
  spec: ReviewSpec;
493
506
  options: CliOptions;
494
507
  agentFiles: Map<string, ParsedAgent>;
495
- routingConfig: RoutingConfig | undefined;
508
+ models: ModelsConfig | undefined;
496
509
  summary: SummarySettings;
497
510
  summarizerEnabled?: boolean;
498
511
  scoutEnabled?: boolean;
499
512
  consolidateEnabled?: boolean;
500
513
  materialityEnabled?: boolean;
514
+ // S5: the run's Claude credential, chosen once at run start. Required (undefined
515
+ // spelled out) so tsc keeps every caller handing it over: dropping it would compile
516
+ // and silently admit on the process env. A dry run passes undefined: it
517
+ // authenticates nothing (like the capability gate it skips), so it is never
518
+ // refused for a credential and admits on the process env.
519
+ claudeRun: RunClaudeCredential | undefined;
501
520
  }): Promise<ProductionRoutePlanResult | undefined> {
502
521
  return resolveProductionRoutePlanAtConfirm({
503
- routingConfigured: params.routingConfigured,
522
+ modelsConfigured: params.modelsConfigured,
504
523
  workspaceRoot: params.workspaceRoot,
524
+ ...(params.claudeRun === undefined
525
+ ? { checkCredentials: false }
526
+ : { claudeRun: params.claudeRun }),
505
527
  buildRoutePlan: () =>
506
528
  buildCliRoutePlan({
507
529
  spec: params.spec,
508
530
  options: params.options,
509
531
  agentFiles: params.agentFiles,
510
- routingConfig: params.routingConfig,
532
+ models: params.models,
511
533
  summary: params.summary,
512
534
  summarizerEnabled: params.summarizerEnabled,
513
535
  scoutEnabled: params.scoutEnabled,
@@ -131,7 +131,7 @@ export function validateScoutLeads(candidate: unknown): ScoutLead[] {
131
131
  export const MAX_LEADS = 12; // above this it is a filter of nothing
132
132
  export const MAX_LEADS_PER_PATH = 3; // stops one interesting file absorbing the whole budget
133
133
  export const MAX_WHY_CHARS = 240; // one sentence; a paragraph is a finding in disguise
134
- export const MAX_LEADS_BLOCK_CHARS = 3000; // bounded prompt growth per hunter, x4 hunters
134
+ export const MAX_LEADS_BLOCK_CHARS = 3000; // bounded prompt growth per hunter, times every hunter
135
135
 
136
136
  // The verbatim block shape from §3.8. The header paragraph is the
137
137
  // anti-anchoring guard, and it is what keeps §3.4's "bias" from decaying into
@@ -4,7 +4,7 @@
4
4
  // EXACTLY the wiring the engine used to hard-code (prose Step 4), so a caller
5
5
  // that passes nothing gets byte-identical behavior.
6
6
 
7
- import { parseLogicalIdentity } from "#model/routing";
7
+ import { modelNameFromAlias } from "#model/model-name";
8
8
 
9
9
  const SAFE_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
10
10
 
@@ -149,7 +149,7 @@ export function validateReviewSpec(candidate: unknown): ReviewSpec {
149
149
  if (diversityEnabled && Array.isArray(a.models)) {
150
150
  for (const model of a.models as string[]) {
151
151
  try {
152
- parseLogicalIdentity(model);
152
+ modelNameFromAlias(model);
153
153
  } catch (error) {
154
154
  must(
155
155
  false,
@@ -165,7 +165,7 @@ export function validateReviewSpec(candidate: unknown): ReviewSpec {
165
165
  );
166
166
  if (a.model !== undefined) {
167
167
  try {
168
- parseLogicalIdentity(a.model as string);
168
+ modelNameFromAlias(a.model as string);
169
169
  } catch (error) {
170
170
  must(
171
171
  false,
@@ -18,7 +18,9 @@ import type {
18
18
  TransportFailureCause,
19
19
  } from "../execution/contracts";
20
20
  import type { FailureClass } from "../execution/failure-classification";
21
+ import type { FailureCause } from "../execution/failure-policy";
21
22
  import { StepExecutionHarness } from "../execution/harness";
23
+ import { runWithFallback } from "../execution/model-fallback";
22
24
  import type { SpendReservation } from "../execution/spend-limiter";
23
25
  import type { NormalizedUsage } from "../execution/usage-normalized";
24
26
  import type { CredentialBroker } from "../security/credential-broker";
@@ -61,6 +63,20 @@ export interface StepSpec {
61
63
  backend?: "claude-code" | "opencode";
62
64
  models?: string[];
63
65
  route?: ResolvedModelRoute;
66
+ // The routes tried after `route`, in order, when the provider fails it
67
+ // (S4; the plan's `fallbacks`, the runner side is model-fallback.ts).
68
+ // Absent when the step's role names one model.
69
+ fallbackRoutes?: readonly ResolvedModelRoute[];
70
+ // The effort each of `fallbackRoutes` runs at, in the same order (S7): its
71
+ // `models` entry's effort, else the prompt's frontmatter, else the role's
72
+ // default (the pipeline's stepEffortFields). Absent with no fallbacks. A
73
+ // step built without it runs every fallback at `effort`.
74
+ fallbackEfforts?: readonly Effort[];
75
+ // How many attempts earlier models of this same step already used. The
76
+ // harness numbers this run's attempts after them, so every model's attempt
77
+ // logs, receipts and evidence keep their own files instead of overwriting
78
+ // the first model's. Absent means 0.
79
+ attemptOffset?: number;
64
80
  // Frozen route fingerprint from the admitted plan. Required for routed
65
81
  // production execution via createProductionRuntime.
66
82
  routeKey?: string;
@@ -108,15 +124,54 @@ export interface StepResult {
108
124
  // resolved one (a transport cause, never a harness cause). Absent on success,
109
125
  // and on a failure with no transport cause. The CLI record names it per hunter.
110
126
  failureCause?: TransportFailureCause;
127
+ // The cause the step's final failed attempt ended on, harness causes
128
+ // included: `failureCause` above keeps transport causes only, so a timeout
129
+ // (`watchdog_timeout`) or a bad answer (`format_violation`) was invisible to
130
+ // anything reading the result. The fallback reads this one. Absent on
131
+ // success, on cancellation, and when no cause was resolved. An attempt
132
+ // refused by a fenced spend bucket never reached the provider and has no
133
+ // cause, so after one this is the cause of the attempt before it.
134
+ finalCause?: FailureCause;
135
+ // The final attempt was refused by a fenced spend bucket (an earlier
136
+ // attempt on it left a cost nobody knows), before the transport was called.
137
+ // That attempt is counted in `attempts` but wrote no log or receipt. Read
138
+ // only by the fallback (model-fallback.ts); never recorded.
139
+ spendFenced?: true;
111
140
  // The final failed attempt's one-line explanation (TransportOutcome.failureDetail),
112
141
  // when the transport gave one. Absent on success.
113
142
  failureDetail?: string;
114
143
  // The secret the final failed attempt ran on (TransportOutcome.failureCredential).
115
144
  failureCredential?: FailureCredential;
145
+ // Each model the step tried, in order, when its role listed more than one
146
+ // (S4). The last entry not `skipped` is the model that ran. Absent on a
147
+ // step with one model, which records exactly what it recorded before.
148
+ modelAttempts?: ModelAttempt[];
116
149
  stderrTail: string;
117
150
  resultText: string;
118
151
  }
119
152
 
153
+ // One model of a step's list, as it ended. Usage is kept per model because
154
+ // models can bill differently (a subscription model, then a metered one):
155
+ // the step's total sums them, and only these entries keep each one's billing.
156
+ export interface ModelAttempt {
157
+ route: ResolvedModelRoute;
158
+ // `skipped`: never reached its provider. Either an earlier model on the
159
+ // same credential was refused its login (cause `auth_invalid`), or it was
160
+ // stopped before any request: its spend bucket was fenced, or it failed
161
+ // before its first attempt (no cause).
162
+ status: "ok" | "failed" | "skipped";
163
+ // Attempts that reached the provider: 0 for a skipped model.
164
+ attempts: number;
165
+ // The effort this model was asked to run at (S7; StepSpec.effort or its
166
+ // entry in `fallbackEfforts`), skipped models included. Optional only so a
167
+ // runner that predates it still type-checks; runWithFallback always sets it.
168
+ effort?: Effort;
169
+ // Why it failed, or `auth_invalid` for a model skipped after a refused
170
+ // login. Absent on `ok`, and on a model skipped for any other reason.
171
+ cause?: FailureCause;
172
+ usageV2?: NormalizedUsage;
173
+ }
174
+
120
175
  export interface StepRunner {
121
176
  run(step: StepSpec): Promise<StepResult>;
122
177
  }
@@ -211,8 +266,10 @@ export interface ClaudeCodeRunnerOptions {
211
266
 
212
267
  export class ClaudeCodeRunner implements StepRunner {
213
268
  private readonly harness: StepExecutionHarness;
269
+ private readonly signal?: AbortSignal;
214
270
 
215
271
  constructor(options: ClaudeCodeRunnerOptions = {}) {
272
+ this.signal = options.signal;
216
273
  this.harness = new StepExecutionHarness({
217
274
  workspaceRoot: options.workspaceRoot,
218
275
  executableAllowlist: options.executableAllowlist,
@@ -227,7 +284,19 @@ export class ClaudeCodeRunner implements StepRunner {
227
284
  });
228
285
  }
229
286
 
287
+ // A caller that builds its own plan (runPipeline with `models`, as the lab
288
+ // does) can hand this runner a step with fallbacks (S4). It runs them in
289
+ // order like the production runner does. Every Claude model here runs on
290
+ // the one Claude credential this runner holds; a model on another backend
291
+ // has no transport here, fails before any spawn with no cause, and so ends
292
+ // the step, recorded in its `modelAttempts`.
230
293
  async run(step: StepSpec): Promise<StepResult> {
231
- return this.harness.run(step);
294
+ return runWithFallback({
295
+ step,
296
+ runOn: (single) => this.harness.run(single),
297
+ credentialOf: (route) =>
298
+ route.backend === "claude-code" ? "claude-code" : undefined,
299
+ cancelled: () => this.signal?.aborted === true,
300
+ });
232
301
  }
233
302
  }