crysk 0.0.0 → 0.3.1

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 (233) hide show
  1. package/LICENSE +176 -0
  2. package/README.md +611 -3
  3. package/bin/pr-hero.js +166 -0
  4. package/config/models/anthropic.json +5 -0
  5. package/dist/SKILL-7e3725zn.md +496 -0
  6. package/dist/SKILL-7q35wcaz.md +66 -0
  7. package/dist/SKILL-9at22381.md +74 -0
  8. package/dist/SKILL-ex2hxxh3.md +134 -0
  9. package/dist/SKILL-y8rv8msh.md +134 -0
  10. package/dist/SKILL-ygka1bs0.md +515 -0
  11. package/dist/adjudicator-dtg2axnh.md +86 -0
  12. package/dist/admission-config.example-a9vqmmad.json +9 -0
  13. package/dist/ci-admission-camfbx2b.md +122 -0
  14. package/dist/ci-admission-qk9r9taq.md +124 -0
  15. package/dist/cli.js +42501 -0
  16. package/dist/consolidate-ac0mnfyj.md +24 -0
  17. package/dist/deep-review-lifecycle-m698ybjp.md +362 -0
  18. package/dist/deep-review-logic-a6b1gczf.md +156 -0
  19. package/dist/deep-review-parity-0ec904db.md +120 -0
  20. package/dist/deep-review-reliability-qyakbjb9.md +125 -0
  21. package/dist/deep-review-resilience-3tz8y26e.md +118 -0
  22. package/dist/index.js +20190 -0
  23. package/dist/opencode-ci-7b0be64p.md +141 -0
  24. package/dist/review-refuter-j4e9gezy.md +71 -0
  25. package/dist/scout-yvp153q7.md +140 -0
  26. package/dist/summarizer-zca44nxa.md +18 -0
  27. package/dist/workflow-w1g9szna.yml +151 -0
  28. package/package.json +81 -4
  29. package/prompts/consolidate.md +24 -0
  30. package/prompts/default/PROVENANCE.md +18 -0
  31. package/prompts/default/deep-review-lifecycle.md +362 -0
  32. package/prompts/default/deep-review-logic.md +156 -0
  33. package/prompts/default/deep-review-parity.md +120 -0
  34. package/prompts/default/deep-review-reliability.md +125 -0
  35. package/prompts/default/deep-review-resilience.md +118 -0
  36. package/prompts/default/review-refuter.md +71 -0
  37. package/prompts/scout.md +140 -0
  38. package/prompts/summarizer.md +18 -0
  39. package/skills/crysk/SKILL.md +74 -0
  40. package/skills/crysk-ci-setup/SKILL.md +134 -0
  41. package/skills/crysk-ci-setup/assets/admission-config.example.json +9 -0
  42. package/skills/crysk-ci-setup/assets/workflow.yml +151 -0
  43. package/skills/crysk-ci-setup/references/ci-admission.md +124 -0
  44. package/skills/crysk-ci-setup/references/opencode-ci.md +141 -0
  45. package/skills/crysk-loop/SKILL.md +515 -0
  46. package/skills/crysk-loop/adjudicator.md +86 -0
  47. package/skills/crysk-pr/SKILL.md +66 -0
  48. package/src/agent-env.ts +1084 -0
  49. package/src/asset-manifest.ts +83 -0
  50. package/src/assets.d.ts +6 -0
  51. package/src/assets.ts +183 -0
  52. package/src/brand-paths.ts +155 -0
  53. package/src/brand.ts +255 -0
  54. package/src/ci/admission-ledger.ts +350 -0
  55. package/src/ci/classify-error.ts +73 -0
  56. package/src/ci/cli-record.ts +271 -0
  57. package/src/ci/force-comment.ts +39 -0
  58. package/src/ci/gates.ts +945 -0
  59. package/src/ci/outcome.ts +2181 -0
  60. package/src/ci/override.ts +187 -0
  61. package/src/ci/publish.ts +1639 -0
  62. package/src/ci/reporter.ts +626 -0
  63. package/src/ci/review-admission.ts +910 -0
  64. package/src/ci/review-levels.ts +310 -0
  65. package/src/ci/review-policy.ts +18 -0
  66. package/src/ci/review-risk.ts +184 -0
  67. package/src/ci/setup.ts +844 -0
  68. package/src/ci/trigger.ts +1353 -0
  69. package/src/cli.ts +348 -0
  70. package/src/commands/activity.ts +67 -0
  71. package/src/commands/ci-setup-questions.ts +397 -0
  72. package/src/commands/ci-setup.ts +381 -0
  73. package/src/commands/config.ts +99 -0
  74. package/src/commands/doctor.ts +108 -0
  75. package/src/commands/init.ts +139 -0
  76. package/src/commands/mcp.ts +10 -0
  77. package/src/commands/menu.ts +129 -0
  78. package/src/commands/post.ts +302 -0
  79. package/src/commands/skills.ts +83 -0
  80. package/src/commands/status.ts +173 -0
  81. package/src/commands/triage.ts +342 -0
  82. package/src/commands/uninstall.ts +37 -0
  83. package/src/commands/upgrade.ts +214 -0
  84. package/src/commands/usage.ts +98 -0
  85. package/src/compare/compare.ts +28 -0
  86. package/src/compare/floor-test.ts +471 -0
  87. package/src/compare/martian-adapter.ts +80 -0
  88. package/src/config/config.ts +267 -0
  89. package/src/corpus/corpus.ts +1094 -0
  90. package/src/corpus/preflight.ts +1789 -0
  91. package/src/diversity/accounting.ts +90 -0
  92. package/src/diversity/adjudication.ts +145 -0
  93. package/src/diversity/admission.ts +60 -0
  94. package/src/diversity/benchmark.ts +195 -0
  95. package/src/diversity/clustering.ts +285 -0
  96. package/src/diversity/errors.ts +7 -0
  97. package/src/diversity/identity.ts +285 -0
  98. package/src/diversity/index.ts +11 -0
  99. package/src/diversity/pipeline-integration.ts +448 -0
  100. package/src/diversity/projection.ts +57 -0
  101. package/src/diversity/self-contained.ts +68 -0
  102. package/src/diversity/target-validation.ts +179 -0
  103. package/src/doctor-migration.ts +209 -0
  104. package/src/doctor.ts +723 -0
  105. package/src/errors.ts +83 -0
  106. package/src/execution/admission.ts +75 -0
  107. package/src/execution/atomic-write.ts +35 -0
  108. package/src/execution/attempt-evidence.ts +415 -0
  109. package/src/execution/bucket-id.ts +136 -0
  110. package/src/execution/concurrency-limiter.ts +175 -0
  111. package/src/execution/contracts.ts +443 -0
  112. package/src/execution/failure-classification.ts +42 -0
  113. package/src/execution/failure-policy.ts +240 -0
  114. package/src/execution/harness.ts +2548 -0
  115. package/src/execution/settlement.ts +348 -0
  116. package/src/execution/spawned-process.ts +66 -0
  117. package/src/execution/spend-limiter.ts +424 -0
  118. package/src/execution/step-artifacts.ts +55 -0
  119. package/src/execution/usage-normalized.ts +469 -0
  120. package/src/git/git.ts +396 -0
  121. package/src/git/identity.ts +64 -0
  122. package/src/git/refs.ts +140 -0
  123. package/src/home-preflight.ts +443 -0
  124. package/src/home.ts +243 -0
  125. package/src/ignore-file.ts +336 -0
  126. package/src/ignore-read.ts +118 -0
  127. package/src/index.ts +34 -0
  128. package/src/legacy-launchd.ts +29 -0
  129. package/src/mcp/mcp.ts +150 -0
  130. package/src/mcp/preflight.ts +407 -0
  131. package/src/menu-context.ts +192 -0
  132. package/src/model/catalog.ts +251 -0
  133. package/src/model/exec-snapshots.ts +390 -0
  134. package/src/model/free-discovery.ts +302 -0
  135. package/src/model/provider-capabilities.ts +814 -0
  136. package/src/model/routing.ts +600 -0
  137. package/src/pr/admission.ts +984 -0
  138. package/src/pr/answered-findings.ts +169 -0
  139. package/src/pr/ci-admission-gate.ts +743 -0
  140. package/src/pr/ci-publish.ts +76 -0
  141. package/src/pr/discovery.ts +432 -0
  142. package/src/pr/inline.ts +507 -0
  143. package/src/pr/plan.ts +366 -0
  144. package/src/pr/posting.ts +115 -0
  145. package/src/pr/pr-status.ts +845 -0
  146. package/src/pr/pr.ts +3642 -0
  147. package/src/pr/preflight.ts +1031 -0
  148. package/src/pr/publish-outcome.ts +361 -0
  149. package/src/pr/range.ts +119 -0
  150. package/src/pr/reverts-preflight.ts +606 -0
  151. package/src/pr/reverts.ts +377 -0
  152. package/src/pr/review-pr.ts +927 -0
  153. package/src/pr/status.ts +154 -0
  154. package/src/pr/target.ts +388 -0
  155. package/src/pr/teardown.ts +437 -0
  156. package/src/pr/worktree-setup.ts +60 -0
  157. package/src/production-runtime.ts +1877 -0
  158. package/src/progress.ts +487 -0
  159. package/src/rereview/adjudicate.ts +89 -0
  160. package/src/rereview/classify.ts +362 -0
  161. package/src/rereview/identity.ts +211 -0
  162. package/src/rereview/plan.ts +308 -0
  163. package/src/rereview/prepare.ts +1025 -0
  164. package/src/rereview/state.ts +767 -0
  165. package/src/rereview/verify.ts +241 -0
  166. package/src/review/boundary.ts +105 -0
  167. package/src/review/consolidate.ts +246 -0
  168. package/src/review/dedupe.ts +368 -0
  169. package/src/review/drafts.ts +448 -0
  170. package/src/review/findings-conformance.ts +120 -0
  171. package/src/review/findings.ts +714 -0
  172. package/src/review/pipeline.ts +3977 -0
  173. package/src/review/preflight.ts +3575 -0
  174. package/src/review/prompt-set.ts +177 -0
  175. package/src/review/proof-refs.ts +187 -0
  176. package/src/review/report.ts +1821 -0
  177. package/src/review/review.ts +490 -0
  178. package/src/review/root-cause.ts +120 -0
  179. package/src/review/route-preflight.ts +289 -0
  180. package/src/review/run.ts +601 -0
  181. package/src/review/scout.ts +323 -0
  182. package/src/review/size-gate.ts +595 -0
  183. package/src/review/spec.ts +235 -0
  184. package/src/review/step-runner.ts +233 -0
  185. package/src/runner-authority.ts +596 -0
  186. package/src/security/binding-policy.ts +115 -0
  187. package/src/security/credential-broker.ts +773 -0
  188. package/src/security/evidence-redaction.ts +62 -0
  189. package/src/security/execution-authority.ts +27 -0
  190. package/src/security/redact.ts +71 -0
  191. package/src/security/workspace-read-broker.ts +466 -0
  192. package/src/server/client.ts +190 -0
  193. package/src/server/preflight.ts +217 -0
  194. package/src/server/server.ts +327 -0
  195. package/src/signal-handler.ts +50 -0
  196. package/src/store/activity.ts +413 -0
  197. package/src/store/backfill-preflight.ts +49 -0
  198. package/src/store/backfill.ts +141 -0
  199. package/src/store/gc-preflight.ts +206 -0
  200. package/src/store/gc.ts +424 -0
  201. package/src/store/metrics-preflight.ts +229 -0
  202. package/src/store/metrics.ts +236 -0
  203. package/src/store/preflight.ts +748 -0
  204. package/src/store/store.ts +693 -0
  205. package/src/system-tools.ts +355 -0
  206. package/src/transport-registry.ts +1124 -0
  207. package/src/transports/claude-code-cli.ts +1348 -0
  208. package/src/transports/opencode-admission.ts +515 -0
  209. package/src/transports/opencode-client.ts +3328 -0
  210. package/src/transports/opencode-evidence.ts +557 -0
  211. package/src/transports/opencode-mcp.ts +248 -0
  212. package/src/transports/opencode-sdk.ts +2294 -0
  213. package/src/transports/opencode-server.ts +535 -0
  214. package/src/triage/adjudication.ts +113 -0
  215. package/src/triage/reply.ts +125 -0
  216. package/src/triage/triage.ts +255 -0
  217. package/src/ui/activity.ts +173 -0
  218. package/src/ui/config-edit.ts +816 -0
  219. package/src/ui/config.ts +462 -0
  220. package/src/ui/menu.ts +1325 -0
  221. package/src/ui/plan.ts +1039 -0
  222. package/src/ui/primitives.ts +300 -0
  223. package/src/ui/progress.ts +298 -0
  224. package/src/ui/result.ts +552 -0
  225. package/src/ui/review-menu.ts +312 -0
  226. package/src/ui/select.ts +528 -0
  227. package/src/ui/tree.ts +178 -0
  228. package/src/uninstaller.ts +479 -0
  229. package/src/updater.ts +836 -0
  230. package/src/usage.ts +77 -0
  231. package/src/watch/preflight.ts +1389 -0
  232. package/src/watch/watch.ts +1235 -0
  233. package/src/wizard.ts +877 -0
@@ -0,0 +1,235 @@
1
+ // Pipeline-as-data: the review DAG is a validated TS literal, convoy-style —
2
+ // creating, removing, or re-wiring subagents is a config change, never an
3
+ // engine edit. The engine consumes a ReviewSpec; defaultReviewSpec() encodes
4
+ // EXACTLY the wiring the engine used to hard-code (prose Step 4), so a caller
5
+ // that passes nothing gets byte-identical behavior.
6
+
7
+ import { parseLogicalIdentity } from "#model/routing";
8
+
9
+ const SAFE_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
10
+
11
+ // A conditional hunter's trigger. `string[]` is a glob/contains pattern list
12
+ // matched against the diff's changed paths with the same parityTriggered
13
+ // semantics the parity hunter always used. The `"input"` sentinel means "use
14
+ // PipelineInput.parityTriggerPaths" — the trigger PATHS stay lab config
15
+ // (deep-review.config.json), only the WIRING ("parity is conditional") lives
16
+ // in the spec. Chosen over a second optional field because a union keeps
17
+ // "has a trigger" a single presence check.
18
+ export type AgentTrigger = string[] | "input";
19
+
20
+ export interface AgentSpec {
21
+ // Stable id: becomes the per_agent telemetry key and the step-name suffix
22
+ // ("hunter-<key>"; the single refuter step keeps the fixed name "refuter").
23
+ key: string;
24
+ // Semantic specialty stamped into finding.hunter. Defaults to key when
25
+ // omitted — the execution identity and the specialty diverge only when D3
26
+ // fans multiple model legs at the same specialty.
27
+ specialty?: string;
28
+ // Agent .md basename inside agentsDir, e.g. "deep-review-reliability.md".
29
+ file: string;
30
+ role: "hunter" | "refuter";
31
+ // Hunters only. Omitted → the hunter always runs. Present → it runs only
32
+ // when any changed path matches (see AgentTrigger).
33
+ trigger?: AgentTrigger;
34
+ // Per-agent model override. Precedence for every step:
35
+ // input.model (CLI --model) > spec.model > agent frontmatter model.
36
+ model?: string;
37
+ // D3 fan-out: when multiModelDiversity.enabled, each model becomes a leg.
38
+ models?: readonly string[];
39
+ }
40
+
41
+ export interface MultiModelDiversityConfig {
42
+ readonly enabled: true;
43
+ readonly armId: string;
44
+ readonly maxLegs: number;
45
+ readonly cashCapUsd: number;
46
+ }
47
+
48
+ export interface ReviewSpec {
49
+ agents: AgentSpec[];
50
+ multiModelDiversity?: MultiModelDiversityConfig;
51
+ }
52
+
53
+ export function isSafeSlug(value: string): boolean {
54
+ return value.length >= 1 && value.length <= 64 && SAFE_SLUG_RE.test(value);
55
+ }
56
+
57
+ export function resolveSpecialty(agent: AgentSpec): string {
58
+ return agent.specialty ?? agent.key;
59
+ }
60
+
61
+ export class ReviewSpecValidationError extends Error {}
62
+
63
+ function must(condition: boolean, message: string): void {
64
+ if (!condition) throw new ReviewSpecValidationError(message);
65
+ }
66
+
67
+ export function validateReviewSpec(candidate: unknown): ReviewSpec {
68
+ must(
69
+ typeof candidate === "object" && candidate !== null,
70
+ "review spec must be an object",
71
+ );
72
+ const spec = candidate as Record<string, unknown>;
73
+ must(Array.isArray(spec.agents), "spec.agents must be an array");
74
+ const diversityEnabled =
75
+ spec.multiModelDiversity !== undefined &&
76
+ typeof spec.multiModelDiversity === "object" &&
77
+ spec.multiModelDiversity !== null &&
78
+ (spec.multiModelDiversity as Record<string, unknown>).enabled === true;
79
+ if (spec.multiModelDiversity !== undefined) {
80
+ const diversity = spec.multiModelDiversity as Record<string, unknown>;
81
+ must(
82
+ diversity.enabled === true,
83
+ "multiModelDiversity.enabled must be true when present",
84
+ );
85
+ must(
86
+ typeof diversity.armId === "string" &&
87
+ isSafeSlug(diversity.armId as string),
88
+ "multiModelDiversity.armId must be a safe slug",
89
+ );
90
+ must(
91
+ typeof diversity.maxLegs === "number" &&
92
+ Number.isInteger(diversity.maxLegs) &&
93
+ (diversity.maxLegs as number) >= 1,
94
+ "multiModelDiversity.maxLegs must be a positive integer",
95
+ );
96
+ must(
97
+ typeof diversity.cashCapUsd === "number" &&
98
+ Number.isFinite(diversity.cashCapUsd) &&
99
+ (diversity.cashCapUsd as number) > 0,
100
+ "multiModelDiversity.cashCapUsd must be a positive number",
101
+ );
102
+ }
103
+ const agents = spec.agents as unknown[];
104
+ const keys = new Set<string>();
105
+ const hunterSpecialties = new Set<string>();
106
+ let hunterCount = 0;
107
+ let refuterCount = 0;
108
+ agents.forEach((entry, i) => {
109
+ must(
110
+ typeof entry === "object" && entry !== null,
111
+ `agents[${i}] must be an object`,
112
+ );
113
+ const a = entry as Record<string, unknown>;
114
+ must(
115
+ typeof a.key === "string" && a.key.length > 0,
116
+ `agents[${i}].key required`,
117
+ );
118
+ must(
119
+ isSafeSlug(a.key as string),
120
+ `agents[${i}].key "${a.key}" is not a safe slug (^[a-z0-9]+(?:-[a-z0-9]+)*$, 1-64 chars)`,
121
+ );
122
+ must(!keys.has(a.key as string), `agents[${i}].key duplicates "${a.key}"`);
123
+ keys.add(a.key as string);
124
+ must(
125
+ a.specialty === undefined ||
126
+ (typeof a.specialty === "string" && isSafeSlug(a.specialty)),
127
+ `agents[${i}].specialty must be a safe slug when present`,
128
+ );
129
+ must(
130
+ typeof a.file === "string" && a.file.length > 0,
131
+ `agents[${i}].file required`,
132
+ );
133
+ must(
134
+ a.role === "hunter" || a.role === "refuter",
135
+ `agents[${i}].role must be hunter|refuter`,
136
+ );
137
+ must(
138
+ a.models === undefined ||
139
+ (diversityEnabled &&
140
+ Array.isArray(a.models) &&
141
+ (a.models as unknown[]).length >= 1 &&
142
+ (a.models as unknown[]).every(
143
+ (model) => typeof model === "string" && model.length > 0,
144
+ )),
145
+ diversityEnabled
146
+ ? `agents[${i}].models must be a non-empty string array when multiModelDiversity is enabled`
147
+ : `agents[${i}].models is not supported in D2; fan-out is a D3 capability`,
148
+ );
149
+ if (diversityEnabled && Array.isArray(a.models)) {
150
+ for (const model of a.models as string[]) {
151
+ try {
152
+ parseLogicalIdentity(model);
153
+ } catch (error) {
154
+ must(
155
+ false,
156
+ `agents[${i}].models contains invalid model identity "${model}": ${(error as Error).message}`,
157
+ );
158
+ }
159
+ }
160
+ }
161
+ must(
162
+ a.model === undefined ||
163
+ (typeof a.model === "string" && a.model.length > 0),
164
+ `agents[${i}].model must be a non-empty string when present`,
165
+ );
166
+ if (a.model !== undefined) {
167
+ try {
168
+ parseLogicalIdentity(a.model as string);
169
+ } catch (error) {
170
+ must(
171
+ false,
172
+ `agents[${i}].model "${a.model}" is not a valid model identity: ${(error as Error).message}`,
173
+ );
174
+ }
175
+ }
176
+ if (a.role === "hunter") {
177
+ hunterCount++;
178
+ const specialty =
179
+ a.specialty === undefined ? (a.key as string) : (a.specialty as string);
180
+ if (!diversityEnabled || a.models === undefined) {
181
+ must(
182
+ !hunterSpecialties.has(specialty),
183
+ `agents[${i}] specialty "${specialty}" duplicates another hunter's effective specialty`,
184
+ );
185
+ hunterSpecialties.add(specialty);
186
+ }
187
+ must(
188
+ a.trigger === undefined ||
189
+ a.trigger === "input" ||
190
+ (Array.isArray(a.trigger) &&
191
+ (a.trigger as unknown[]).every(
192
+ (p) => typeof p === "string" && p.length > 0,
193
+ )),
194
+ `agents[${i}].trigger must be "input" or a string array`,
195
+ );
196
+ } else {
197
+ refuterCount++;
198
+ must(
199
+ a.specialty === undefined,
200
+ `agents[${i}] is a refuter and cannot carry a specialty`,
201
+ );
202
+ must(
203
+ a.trigger === undefined,
204
+ `agents[${i}] is a refuter and cannot carry a trigger`,
205
+ );
206
+ }
207
+ });
208
+ must(hunterCount >= 1, "spec needs at least one hunter");
209
+ must(refuterCount <= 1, "spec allows at most one refuter");
210
+ return spec as unknown as ReviewSpec;
211
+ }
212
+
213
+ // EXACTLY today's hard-coded wiring (prose Step 4): reliability + resilience
214
+ // unconditional, parity conditional on the lab's parityTriggerPaths (the
215
+ // "input" sentinel), one refuter. runPipeline without an explicit spec uses
216
+ // this, which is what keeps the default engine behavior byte-stable.
217
+ export function defaultReviewSpec(): ReviewSpec {
218
+ return {
219
+ agents: [
220
+ {
221
+ key: "reliability",
222
+ file: "deep-review-reliability.md",
223
+ role: "hunter",
224
+ },
225
+ { key: "resilience", file: "deep-review-resilience.md", role: "hunter" },
226
+ {
227
+ key: "parity",
228
+ file: "deep-review-parity.md",
229
+ role: "hunter",
230
+ trigger: "input",
231
+ },
232
+ { key: "refuter", file: "review-refuter.md", role: "refuter" },
233
+ ],
234
+ };
235
+ }
@@ -0,0 +1,233 @@
1
+ // Step-level headless engine spawn — the v2 descendant of deep-review's
2
+ // runner/session.ts. v1 spawned ONE Claude Code session and let an
3
+ // orchestrator prompt fan out hunters via the Task tool; v2 spawns one
4
+ // session PER STEP (hunter/refuter) and the driver owns the orchestration.
5
+ // Every isolation flag and retry mechanism here encodes a paid-for failure
6
+ // from v1 — port, don't rewrite.
7
+
8
+ import type { Effort } from "#model/catalog";
9
+ import type { CredentialKind } from "#model/provider-capabilities";
10
+ import type { AttemptAdmissionGate } from "../execution/admission";
11
+ import type {
12
+ AuthEvent,
13
+ DenialCode,
14
+ ExecutableAllowlistEntry,
15
+ FailureCredential,
16
+ ResolvedModelRoute,
17
+ StepAdmissionGate,
18
+ TransportFailureCause,
19
+ } from "../execution/contracts";
20
+ import type { FailureClass } from "../execution/failure-classification";
21
+ import { StepExecutionHarness } from "../execution/harness";
22
+ import type { SpendReservation } from "../execution/spend-limiter";
23
+ import type { NormalizedUsage } from "../execution/usage-normalized";
24
+ import type { CredentialBroker } from "../security/credential-broker";
25
+ import type { SessionUsage } from "../usage";
26
+
27
+ export interface StepSpec {
28
+ // "hunter-reliability" | "hunter-resilience" | "hunter-parity" | "refuter"
29
+ name: string;
30
+ // Driver-templated file in the run dir (audit artifact).
31
+ systemPromptPath: string;
32
+ // User message: diff, hop budget, batch path, output contract.
33
+ prompt: string;
34
+ // From agent frontmatter.
35
+ tools: string[];
36
+ // Codegraph-only mcp.json.
37
+ mcpConfigPath: string;
38
+ model: string;
39
+ // How hard the model works (`claude --effort`). Always resolved by the engine
40
+ // (frontmatter, else the per-role default) and never left to the CLI's
41
+ // implicit default, which is `medium` on the 5.5 family (#299).
42
+ effort: Effort;
43
+ cwd: string;
44
+ outPath: string;
45
+ // Per-step watchdog; the default (30 min) lives with the caller.
46
+ timeoutMs: number;
47
+ // Transient-only bound (default 2); the format-retry is additional.
48
+ maxAttempts: number;
49
+ // throw = not delivered (v1's draftDelivered role, applied per step).
50
+ parse(finalText: string): unknown;
51
+ // OBSERVATION ONLY. Called just before a retry is spawned, so a retrying
52
+ // step stops looking merely slow — `attempts` was already counted, but only
53
+ // after the fact in PerAgentUsage, which is a post-mortem, not a signal.
54
+ // Nothing here may change retry behavior: no return value is read, and a
55
+ // throwing callback is swallowed (the same rule review/pipeline.ts's emit() keeps
56
+ // — a cosmetic listener must never kill a paid run).
57
+ onRetry?(info: RetryInfo): void;
58
+ // Stage-2 fields — typed now so specs stay forward-compatible, UNUSED in
59
+ // Stage 1: `backend` selects the runner, `models` fans one spec out to
60
+ // `<step>__<model-slug>` legs sharing a groupId.
61
+ backend?: "claude-code" | "opencode";
62
+ models?: string[];
63
+ route?: ResolvedModelRoute;
64
+ // Frozen route fingerprint from the admitted plan. Required for routed
65
+ // production execution via createProductionRuntime.
66
+ routeKey?: string;
67
+ // Provider credential projection stamped by MultiProviderRunner from the
68
+ // admitted binding. Defaults preserve Claude-only behavior.
69
+ credentialKind?: CredentialKind;
70
+ credentialRef?: string;
71
+ // Optional sha256 pin for mcp.json integrity checks at binding admission.
72
+ mcpConfigSha256?: string;
73
+ }
74
+
75
+ export interface RetryInfo {
76
+ // Step name, e.g. "hunter-reliability" or "refuter-F001".
77
+ step: string;
78
+ // The attempt about to START (1-based).
79
+ attempt: number;
80
+ // The transient budget. Meaningless for `reason: "format"` — that retry has
81
+ // its own cap of exactly one, so a renderer must not print "N of M" there.
82
+ maxAttempts: number;
83
+ reason: RetryFailureClass;
84
+ }
85
+
86
+ export interface StepResult {
87
+ name: string;
88
+ status: "ok" | "failed";
89
+ denialCode?: DenialCode;
90
+ output?: unknown;
91
+ // Legacy flat shape (§8's ONLY consumer boundary: `../deep-review/runner/
92
+ // telemetry.ts` reads `runPipeline()`'s returned `usage` by these field
93
+ // names). Projected from `usageV2` via `projectLegacyUsage`, never hand-built.
94
+ usage: SessionUsage;
95
+ // D1-08 PR2: the normalized disjoint leaves this step's attempts actually
96
+ // reported, summed across attempts. Absent when no attempt ever spawned
97
+ // (a pre-spawn denial, a construction failure) — those cases are genuine
98
+ // zero cost, not "unavailable", and carry no v2 record at all.
99
+ usageV2?: NormalizedUsage;
100
+ // D1-08 PR5b (§9.1): one entry per attempt that reached `runAttempt`'s
101
+ // reserve step, each carrying its own `reservationId` and TERMINAL state
102
+ // — spec: "every attempt MUST carry a reservationId and terminal state in
103
+ // pipeline.json". Absent when no `SpendLedger` was configured on the
104
+ // harness (the ledger-free PR5a shape) or no attempt ever reserved.
105
+ reservations?: SpendReservation[];
106
+ attempts: number;
107
+ // The transport cause of the step's final failed attempt, when the harness
108
+ // resolved one (a transport cause, never a harness cause). Absent on success,
109
+ // and on a failure with no transport cause. The CLI record names it per hunter.
110
+ failureCause?: TransportFailureCause;
111
+ // The final failed attempt's one-line explanation (TransportOutcome.failureDetail),
112
+ // when the transport gave one. Absent on success.
113
+ failureDetail?: string;
114
+ // The secret the final failed attempt ran on (TransportOutcome.failureCredential).
115
+ failureCredential?: FailureCredential;
116
+ stderrTail: string;
117
+ resultText: string;
118
+ }
119
+
120
+ export interface StepRunner {
121
+ run(step: StepSpec): Promise<StepResult>;
122
+ }
123
+
124
+ // Step-artifact paths (attemptLogPath, settlementReceiptPath,
125
+ // attemptEvidencePath), FORMAT_RETRY_REMINDER, and the legacy v1
126
+ // classifyFailure/isTransientSessionFailure/isTerminalSessionFailure
127
+ // classification vocabulary moved to execution/step-artifacts.ts and
128
+ // execution/failure-classification.ts (architecture guard C2): this module
129
+ // depends on execution/harness.ts for StepExecutionHarness, so
130
+ // execution/harness.ts and execution/attempt-evidence.ts and
131
+ // execution/failure-policy.ts importing those helpers FROM here closed a
132
+ // value-import cycle back through harness.ts.
133
+
134
+ export const DEFAULT_STEP_TIMEOUT_MS = 30 * 60 * 1000;
135
+ export const DEFAULT_STEP_MAX_ATTEMPTS = 2;
136
+
137
+ export type RetryFailureClass = Exclude<FailureClass, "terminal">;
138
+
139
+ // The Claude CLI argv a step spawns with, mirroring the flag order of
140
+ // ClaudeCodeCliTransport.execute so the isolation flags can be asserted
141
+ // without a transport. It takes no prompt (#314): the prompt goes to
142
+ // the child on stdin, because one argv string over Linux's MAX_ARG_STRLEN
143
+ // (131072 bytes) fails execve with E2BIG and the prompt embeds the whole
144
+ // patch. `-p` with no positional is what makes the CLI read stdin.
145
+ export function buildStepArgv(step: StepSpec): string[] {
146
+ return [
147
+ "claude",
148
+ "-p",
149
+ "--append-system-prompt-file",
150
+ step.systemPromptPath,
151
+ "--output-format",
152
+ "json",
153
+ "--mcp-config",
154
+ step.mcpConfigPath,
155
+ "--strict-mcp-config",
156
+ "--setting-sources",
157
+ "",
158
+ "--tools",
159
+ step.tools.join(","),
160
+ "--permission-mode",
161
+ "bypassPermissions",
162
+ "--model",
163
+ step.model,
164
+ "--effort",
165
+ step.effort,
166
+ "--exclude-dynamic-system-prompt-sections",
167
+ ];
168
+ }
169
+
170
+ // SpawnedProcess, ACTIVE_CHILD_PROCS, and killAllChildProcesses moved to
171
+ // execution/spawned-process.ts (architecture guard C2): the spawner
172
+ // (transports/claude-code-cli.ts) is reached from execution/harness.ts via
173
+ // transport-registry.ts, and this module depends on execution/harness.ts
174
+ // for StepExecutionHarness — so the spawner importing this registry FROM
175
+ // here closed a value-import cycle back through harness.ts.
176
+
177
+ export interface ClaudeCodeRunnerOptions {
178
+ spawnFn?: typeof Bun.spawn;
179
+ workspaceRoot?: string;
180
+ executableAllowlist?: readonly ExecutableAllowlistEntry[];
181
+ binaryPath?: string;
182
+ admissionGate?: StepAdmissionGate;
183
+ // The max_concurrent_steps cap (run.ts admissionGateFor). The legacy
184
+ // runner is what a review without routing runs on, so the cap must reach
185
+ // it too or the key silently does nothing on the default Claude path.
186
+ attemptAdmissionGate?: AttemptAdmissionGate;
187
+ onAuthEvent?: (event: AuthEvent) => void;
188
+ // §6.1 D1-05 credential projection; forwarded to the harness.
189
+ credentialBroker?: CredentialBroker;
190
+ // #177, 2026-09-02: source for the child-env projection, forwarded to the
191
+ // harness (which has documented it as "injectable so tests never touch the
192
+ // real process environment" since D1-05 — this entry point just never
193
+ // passed it, so through THIS runner the injection point was unreachable and
194
+ // `process.env` was the only source).
195
+ //
196
+ // It stopped being cosmetic when the Claude CLI transport began reading
197
+ // that projected env to decide whether an attempt bills metered: two tests
198
+ // here assert the subscription cost shape, and without this they assert it
199
+ // against whatever credentials the developer's own shell carries. Verified,
200
+ // not assumed — `ANTHROPIC_API_KEY=sk-probe bun test` reddened exactly those
201
+ // two before this landed. That is #174's defect, and it cost this repo two
202
+ // wrong diagnoses in one day.
203
+ childEnv?: Readonly<Record<string, string | undefined>>;
204
+ // §5.3 D1-10b: the pipeline ceiling's cancellation signal. This is the ONLY
205
+ // entry point to the harness's §5.3 sequence (no new attempts, lease fence,
206
+ // abort, bounded grace) — the whole sequence shipped implemented and
207
+ // unreachable because this option was missing here, so nothing in src/ ever
208
+ // handed the harness a signal.
209
+ signal?: AbortSignal;
210
+ }
211
+
212
+ export class ClaudeCodeRunner implements StepRunner {
213
+ private readonly harness: StepExecutionHarness;
214
+
215
+ constructor(options: ClaudeCodeRunnerOptions = {}) {
216
+ this.harness = new StepExecutionHarness({
217
+ workspaceRoot: options.workspaceRoot,
218
+ executableAllowlist: options.executableAllowlist,
219
+ binaryPath: options.binaryPath,
220
+ admissionGate: options.admissionGate,
221
+ attemptAdmissionGate: options.attemptAdmissionGate,
222
+ onAuthEvent: options.onAuthEvent,
223
+ credentialBroker: options.credentialBroker,
224
+ childEnv: options.childEnv,
225
+ spawnFn: options.spawnFn,
226
+ signal: options.signal,
227
+ });
228
+ }
229
+
230
+ async run(step: StepSpec): Promise<StepResult> {
231
+ return this.harness.run(step);
232
+ }
233
+ }