repo-contract 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.2.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.1.1...repo-contract-v0.2.0) (2026-09-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* defineRepoContract/runRepoContract now require spawn and env on the config (e.g. spawn: child_process.spawn, env: process.env). See ADR 0011 and README's "Supplying spawn/env" section for migration.
+
+### Features
+
+* make process spawning and env access consumer-supplied capabilities ([640a961](https://github.com/MaverickCER/repo-contract/commit/640a961b65fd73511586c3b4f6274284bf5172a9))
+
 ## [0.1.1](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.1.0...repo-contract-v0.1.1) (2026-09-01)
 
 

package/README.md

@@ -92,7 +92,7 @@ npm install --save-dev yaml
 
 ### Runtime support matrix
 
-repo-contract spawns processes and reads `process.env` — it is server/CLI-only by design, not an isomorphic/browser package.
+repo-contract's checks run as spawned processes and read the ambient environment — but repo-contract never imports a process-spawning implementation or reads `process.env` itself (see [Supplying `spawn`/`env`](#supplying-spawnenv) below); it is server/CLI-only by design regardless, not an isomorphic/browser package, since the capability a consumer supplies is itself always a real Node-only spawning mechanism.
 
 | Environment                                | Supported                                                                                                                                                                                                    |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -113,9 +113,14 @@ Define your repository's standards as checks:
 
 ```ts
 // repo-contract.config.ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 
 export default defineRepoContract({
+  // repo-contract never spawns a process or reads process.env itself -- see
+  // "Supplying spawn/env" below for why, and what to pass on Windows.
+  spawn,
+  env: process.env,
   checks: {
     tests: {
       run: "npm test",
@@ -179,6 +184,49 @@ process.exitCode = verdict.passed ? 0 : 1
 
 There is no CLI, no config-file discovery magic, and no hidden state.
 
+### Supplying `spawn`/`env`
+
+`spawn` and `env` are required fields on the config — repo-contract never imports a process-spawning implementation or reads `process.env` internally (see [ADR 0011](specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md)). You supply both, as trusted capabilities repo-contract calls with a resolved command/argv/options — it does not inspect, wrap, or sanitize them.
+
+**macOS/Linux** — plain `node:child_process` is enough:
+
+```ts
+import { spawn } from "node:child_process"
+
+export default defineRepoContract({
+  spawn,
+  env: process.env,
+  checks: {/* ... */},
+})
+```
+
+**Windows** — most npm-installed CLI tools (`eslint`, `prettier`, `tsc`, …) resolve to `.cmd` shims, and plain `node:child_process.spawn` refuses to run those at all without `shell: true` (Node's own CVE-2024-27980 mitigation). Install [`cross-spawn`](https://www.npmjs.com/package/cross-spawn) and pass it instead — it resolves `.cmd`/`.bat` shims and quotes arguments safely for `cmd.exe`, **without** turning on shell metacharacter interpretation:
+
+```ts
+import crossSpawn, { sync as crossSpawnSync } from "cross-spawn"
+
+export default defineRepoContract({
+  spawn: crossSpawn,
+  env: process.env,
+  // Optional: lets a timed-out/aborted/Ctrl+C-killed check's full process
+  // tree (not just its immediate process) get cleaned up on Windows too.
+  killProcessTree: crossSpawnSync,
+  checks: {/* ... */},
+})
+```
+
+**`cross-spawn` does not mean "shell execution."** These are two independent choices:
+
+| `Spawner` choice | `shell` option    | Result                                                                                                                               |
+| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| native `spawn`   | `false` (default) | argv-only, no shell interpretation                                                                                                   |
+| `cross-spawn`    | `false` (default) | Windows `.cmd`/`.bat` resolution + safe `cmd.exe` quoting, still argv-only                                                           |
+| either           | `true`            | shell metacharacters (`&&`, `\|`, …) interpreted — a per-check or global opt-in, see [`shell`](docs/api-report/repo-contract.api.md) |
+
+Passing `cross-spawn` fixes Windows command resolution; it does not by itself enable shell metacharacter interpretation. `check.shell` (or the config-level `shell` default) is the separate, explicit opt-in for that — see `SECURITY.md` before enabling it.
+
+`repo-contract` doesn't ship a ready-made spawner of its own, on purpose (see ADR 0011's Alternatives) — the two snippets above are the whole integration.
+
 ## The model
 
 ```text
@@ -641,10 +689,13 @@ It does **not** encode your repository's definition of quality.
 Import a preset, spread it into your own `checks` record, and override whatever you need — most often `policy`:
 
 ```ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 import { format, typecheck, license } from "repo-contract/presets"
 
 export default defineRepoContract({
+  spawn,
+  env: process.env,
   checks: {
     format,
     typecheck: {
@@ -662,10 +713,13 @@ export default defineRepoContract({
 Some presets are factories because they expose options that change what gets executed:
 
 ```ts
+import { spawn } from "node:child_process"
 import { defineRepoContract } from "repo-contract"
 import { lint, deadCode } from "repo-contract/presets"
 
 export default defineRepoContract({
+  spawn,
+  env: process.env,
   checks: {
     lint: lint({ path: "src" }),
     deadCode: deadCode({

package/dist/.dts/config/validate-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../../../src/config/validate-config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAKnE;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAwC3E;AA6QD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACxD,IAAI,CAoBN"}
+{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../../../src/config/validate-config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAKnE;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAuE3E;AAqSD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACxD,IAAI,CAoBN"}

package/dist/.dts/execution/process-tree.d.ts

@@ -1,3 +1,4 @@
+import type { SyncSpawner } from "../types.js";
 /**
  * Whether a check's process should be spawned with `detached: true`. On
  * POSIX this makes the spawned process the leader of a new process group
@@ -20,11 +21,20 @@ export declare function shouldSpawnDetached(): boolean;
  *
  * On POSIX, sends `signal` to the whole process group via the negative-pid
  * convention (requires the process to have been spawned with
- * `detached: true`, see `shouldSpawnDetached`). On Windows, process groups
+ * `detached: true`, see `shouldSpawnDetached`) -- no process spawning
+ * required, a single syscall via `process.kill`. On Windows, process groups
  * don't work the same way, so this shells out to `taskkill /pid <pid> /t
  * /f` -- the same technique the `tree-kill` package uses internally -- which
  * walks the system process table for descendants of `pid` regardless of how
- * it was spawned.
+ * it was spawned; that requires a synchronous spawn, which -- like every
+ * other process-spawning capability in this package -- is a trusted
+ * capability the caller supplies (`killProcessTree`, threaded from
+ * `RepoContractConfig.killProcessTree`), never imported internally (see
+ * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * When `killProcessTree` is omitted on Windows, this function is a
+ * documented no-op -- the caller (`spawn-check.ts`) falls back to
+ * terminating just the tracked child process handle directly, which needs
+ * no spawn at all.
  *
  * Swallows the expected best-effort-cleanup failures, but not every failure: a
  * process that has already exited (POSIX `ESRCH`, or `taskkill`'s "not found"
@@ -43,6 +53,7 @@ export declare function shouldSpawnDetached(): boolean;
  * more-cooperative alternative to fall back to here the way there is on POSIX.
  * @param pid - the pid of the tree's root process (the process group id on POSIX, since it was spawned detached)
  * @param signal - the POSIX signal to send (on Windows, ignored -- see doc comment above)
+ * @param killProcessTree - the consumer-supplied synchronous spawner used only on Windows; a no-op there when omitted (see doc comment above)
  */
-export declare function killTree(pid: number, signal: NodeJS.Signals): void;
+export declare function killTree(pid: number, signal: NodeJS.Signals, killProcessTree?: SyncSpawner): void;
 //# sourceMappingURL=process-tree.d.ts.map

package/dist/.dts/execution/process-tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../src/execution/process-tree.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CA8ClE"}
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../src/execution/process-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,WAAW,GAAG,IAAI,CAoDjG"}

package/dist/.dts/execution/run-checks.d.ts

@@ -1,4 +1,5 @@
 import type { CheckDefinition, CheckEvidence, CheckSchema, RunRepoContractOptions } from "../types.js";
+import type { ExecutionCapability } from "./spawn-check.js";
 /**
  * One check's id, its original definition, and its raw execution evidence,
  * threaded together as a triple rather than three separately-keyed maps --
@@ -22,8 +23,9 @@ export declare const SELF_TERMINATE_DELAY_MS: number;
  * simply absent from the result, not present with some placeholder value.
  * @param checks - the full set of configured checks, keyed by id
  * @param concurrency - the maximum number of checks to run in parallel at once
+ * @param execution - the run's trusted execution capabilities (`spawn`, `env`, resolved global `shell` default), forwarded to every `spawnCheck` call
  * @param options - run options; `options.checks` restricts execution to those ids (plus their dependencies), `options.signal` cancels the whole run
  * @returns each executed check's id, definition, and raw evidence, one entry per resolved check regardless of whether it actually spawned
  */
-export declare function runChecks(checks: CheckSchema, concurrency: number, options?: RunRepoContractOptions): Promise<readonly CheckExecutionEntry[]>;
+export declare function runChecks(checks: CheckSchema, concurrency: number, execution: ExecutionCapability, options?: RunRepoContractOptions): Promise<readonly CheckExecutionEntry[]>;
 //# sourceMappingURL=run-checks.d.ts.map

package/dist/.dts/execution/run-checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-checks.d.ts","sourceRoot":"","sources":["../../../src/execution/run-checks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,sBAAsB,EACvB,MAAM,aAAa,CAAA;AAOpB;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAYnF,eAAO,MAAM,uBAAuB,QAAgC,CAAA;AAoJpE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAkJzC"}
+{"version":3,"file":"run-checks.d.ts","sourceRoot":"","sources":["../../../src/execution/run-checks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,sBAAsB,EACvB,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAG9E;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAYnF,eAAO,MAAM,uBAAuB,QAAgC,CAAA;AAoJpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,mBAAmB,EAC9B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAkJzC"}

package/dist/.dts/execution/spawn-check.d.ts

@@ -1,4 +1,22 @@
-import type { CheckDefinition, CheckEvidence } from "../types.js";
+import type { CheckDefinition, CheckEvidence, Spawner, SyncSpawner } from "../types.js";
+/**
+ * The trusted execution capabilities a run supplies once (see
+ * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md)
+ * and every spawned check draws from -- `spawn`/`env` verbatim from
+ * `RepoContractConfig`, `shell` already resolved to its effective global
+ * default (`config.shell ?? false`). Internal only: not exported from
+ * `src/types.ts` or `src/index.ts`. Grouped into one object, rather than
+ * threaded as independent parameters through `run-repo-contract.ts` ->
+ * `run-checks.ts` -> `spawn-check.ts`, purely to keep related
+ * execution-capability concerns from drifting into unrelated positional
+ * parameters as more get added later.
+ */
+export interface ExecutionCapability {
+    readonly spawn: Spawner;
+    readonly env: NodeJS.ProcessEnv;
+    readonly shell: boolean;
+    readonly killProcessTree?: SyncSpawner;
+}
 export declare const SIGKILL_GRACE_PERIOD_MS = 2000;
 /** Handle a caller can use to forcibly terminate one in-flight check's process tree, independent of that check's own timeout/abort wiring -- used by run-checks.ts to clean up every active check when the host process itself receives SIGINT/SIGTERM. */
 export interface ActiveCheckHandle {
@@ -24,7 +42,8 @@ export interface ActiveCheckHandle {
  * @param check - the check definition to run (command, timeout, env, cwd, shell, etc.)
  * @param runSignal - the whole run's abort signal, if any; already-aborted before this is called means the check never spawns
  * @param activeHandles - the shared registry this check's kill handle is added to while running, so a host-process SIGINT/SIGTERM can terminate it
+ * @param execution - the run's trusted execution capabilities (`spawn`, `env`, resolved global `shell` default) -- see `ExecutionCapability`
  * @returns a fully-formed `CheckEvidence` reflecting however the process ended; this function itself never rejects
  */
-export declare function spawnCheck(checkId: string, check: CheckDefinition, runSignal: AbortSignal | undefined, activeHandles: Set<ActiveCheckHandle>): Promise<CheckEvidence>;
+export declare function spawnCheck(checkId: string, check: CheckDefinition, runSignal: AbortSignal | undefined, activeHandles: Set<ActiveCheckHandle>, execution: ExecutionCapability): Promise<CheckEvidence>;
 //# sourceMappingURL=spawn-check.d.ts.map

package/dist/.dts/execution/spawn-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-check.d.ts","sourceRoot":"","sources":["../../../src/execution/spawn-check.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAe,MAAM,aAAa,CAAA;AA6B9E,eAAO,MAAM,uBAAuB,OAAO,CAAA;AA6D3C,2PAA2P;AAC3P,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CACnC;AAoHD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,aAAa,EAAE,GAAG,CAAC,iBAAiB,CAAC,GACpC,OAAO,CAAC,aAAa,CAAC,CA6PxB"}
+{"version":3,"file":"spawn-check.d.ts","sourceRoot":"","sources":["../../../src/execution/spawn-check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAe,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAIpG;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAA;CACvC;AA2BD,eAAO,MAAM,uBAAuB,OAAO,CAAA;AA6D3C,2PAA2P;AAC3P,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CACnC;AAyHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,aAAa,EAAE,GAAG,CAAC,iBAAiB,CAAC,EACrC,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAAC,aAAa,CAAC,CA4QxB"}

package/dist/.dts/index.d.ts

@@ -9,5 +9,5 @@
 export { defineRepoContract } from "./config/define-repo-contract.js";
 export { runRepoContract } from "./run-repo-contract.js";
 export { DependencyDeclaredLaterError, InvalidCheckConfigError, InvalidRepoContractConfigError, ParserDependencyMissingError, PolicyReadFailedParseValueError, PolicyReadUnrequestedOutputError, PolicyThrewError, RepoContractError, UnknownCheckIdError, } from "./errors.js";
-export type { CheckDefinition, CheckDefinitionConfig, CheckEvidence, CheckSchema, CheckStatus, Evidence, OutputFormat, ParsedOutput, ParsedOutputFailure, ParsedOutputSuccess, Policy, PolicyContext, PolicyOutcome, PolicyResult, RepoContractConfig, RunRepoContractOptions, ValidatedCheckSchema, Verdict, } from "./types.js";
+export type { CheckDefinition, CheckDefinitionConfig, CheckEvidence, CheckSchema, CheckStatus, Evidence, OutputFormat, ParsedOutput, ParsedOutputFailure, ParsedOutputSuccess, Policy, PolicyContext, PolicyOutcome, PolicyResult, RepoContractConfig, RunRepoContractOptions, Spawner, SyncSpawner, ValidatedCheckSchema, Verdict, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/.dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,OAAO,GACR,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AAEpB,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACP,WAAW,EACX,oBAAoB,EACpB,OAAO,GACR,MAAM,YAAY,CAAA"}

package/dist/.dts/run-repo-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-repo-contract.d.ts","sourceRoot":"","sources":["../../src/run-repo-contract.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACR,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAC/D,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAGrE"}
+{"version":3,"file":"run-repo-contract.d.ts","sourceRoot":"","sources":["../../src/run-repo-contract.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACR,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAC/D,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAGrE"}

package/dist/.dts/types.d.ts

@@ -4,6 +4,7 @@
  * separate concepts (see specs/architecture.md) even though
  * `runRepoContract` returns both together.
  */
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
 /** Output interpretation a check can explicitly request. No format requested means no parsing -- the consumer gets raw stdout/stderr only. */
 export type OutputFormat = "json" | "yaml" | "text";
 /**
@@ -202,9 +203,11 @@ export interface CheckDefinitionConfig {
     readonly run: string | readonly string[];
     /**
      * Opt into real shell execution instead of the safe argv-only default.
-     * When `true`, `run` must be a `string` and is passed to the platform
-     * shell as-is (via cross-spawn's own `shell` option) -- shell metacharacter
-     * rejection does not apply. See SECURITY.md before enabling this.
+     * When `true` (or left unset with `RepoContractConfig.shell: true` as the
+     * run-wide default -- see that field), `run` must be a `string` and is
+     * passed to the platform shell as-is (via the supplied `Spawner`'s own
+     * `shell` option) -- shell metacharacter rejection does not apply. See
+     * SECURITY.md before enabling this.
      */
     readonly shell?: boolean;
     /** Working directory for the spawned process. Defaults to the current process's `cwd`. */
@@ -285,12 +288,76 @@ export type ValidatedCheckSchema<T> = {
         readonly dependsOn?: readonly (Exclude<keyof T, K> & string)[];
     } : never;
 };
+/**
+ * Spawns a child process, given a resolved command, argv, and options --
+ * modeled directly on `node:child_process`'s own `spawn(command, args,
+ * options)` signature so both `node:child_process.spawn` and cross-spawn's
+ * exported `spawn` are valid, drop-in values with no adapter code required
+ * (see specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * repo-contract treats whatever function is supplied as a trusted
+ * capability: it calls it with a resolved command/argv/options and does not
+ * inspect, wrap, or sanitize it -- the security properties of the spawned
+ * process are entirely the supplied function's own.
+ */
+export type Spawner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/**
+ * Synchronously spawns a child process and waits for it to exit -- modeled directly on
+ * `node:child_process`'s own `spawnSync(command, args, options)` signature, the same
+ * drop-in-compatibility approach as `Spawner`. Used only for `RepoContractConfig.killProcessTree`
+ * (Windows process-tree cleanup via `taskkill`, which fundamentally needs to run synchronously from
+ * a signal-handling context that cannot `await` anything else -- see
+ * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * `node:child_process.spawnSync` and cross-spawn's exported `sync` are both valid, drop-in values.
+ */
+export type SyncSpawner = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer | string>;
 /** Top-level configuration passed to `defineRepoContract`/`runRepoContract`. */
 export interface RepoContractConfig<TChecks extends CheckSchema = CheckSchema> {
     /** Every check to run, keyed by check id. */
     readonly checks: TChecks;
     /** Maximum number of checks to execute concurrently. Defaults to `os.availableParallelism()`. Must be a positive integer. */
     readonly concurrency?: number;
+    /**
+     * The trusted capability repo-contract calls to spawn every check's
+     * process -- e.g. `child_process.spawn` (from `"node:child_process"`) or
+     * cross-spawn's exported `spawn`. Required: repo-contract never imports a
+     * process-spawning implementation itself (see ADR 0011 above `Spawner`).
+     * `child_process.spawn` alone does not resolve Windows `.cmd`/`.bat`
+     * shims (most npm-installed CLI tools on Windows) without `shell: true`;
+     * pass cross-spawn instead for that correctness without enabling shell
+     * metacharacter interpretation -- cross-spawn is a spawn implementation
+     * choice, not a `shell: true` equivalent. See `shell` below.
+     */
+    readonly spawn: Spawner;
+    /**
+     * The ambient environment repo-contract treats as inheritable by each
+     * check whose `inheritEnv` is not `false` (the default) -- typically
+     * `process.env`, passed straight through by reference (never copied
+     * internally) so a consumer that mutates `process.env` mid-run still sees
+     * that reflected in later-spawned checks, exactly as if repo-contract had
+     * read `process.env` itself. Required: repo-contract never reads
+     * `process.env` internally (see ADR 0011 above `Spawner`). Typed as
+     * `NodeJS.ProcessEnv` so `env: process.env` needs no casting.
+     */
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * Global default for every check's own `shell` when that check doesn't
+     * set one itself (`check.shell ?? shell ?? false`). Defaults to `false`,
+     * the safe argv-only mode -- unrelated to which `spawn` is supplied; see
+     * `spawn`'s own doc comment for that distinction.
+     */
+    readonly shell?: boolean;
+    /**
+     * The trusted capability repo-contract calls, on Windows only, to forcibly terminate a check's
+     * entire process tree (not just its immediate process) on a timeout, an aborted run, or a
+     * host-process SIGINT/SIGTERM -- e.g. `child_process.spawnSync` (from `"node:child_process"`) or
+     * cross-spawn's exported `sync`. Optional, unlike `spawn`/`env`: when omitted, Windows cleanup
+     * falls back to terminating only the check's own immediate process (not any subprocess it spawned
+     * internally) -- correct for the common case, but a check that spawns its own descendants (e.g.
+     * `npm test` spawning the real test runner) may leave them running. POSIX cleanup never needs
+     * this at all (`process.kill(-pid, signal)` reaches the whole process group directly, no spawning
+     * required) -- see specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md.
+     */
+    readonly killProcessTree?: SyncSpawner;
 }
 /** Optional per-run controls for `runRepoContract`. */
 export interface RunRepoContractOptions {

package/dist/.dts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8IAA8I;AAC9I,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GACrB,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAAA;AAExF,uDAAuD;AACvD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,oIAAoI;AACpI,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAA;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IACtC,6JAA6J;IAC7J,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4JAA4J;IAC5J,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,0JAA0J;IAC1J,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,6XAA6X;IAC7X,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,uGAAuG;IACvG,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACjE,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,aAAa;KAAE,CAAA;CAClE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACtE,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA;CAC/D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW,IAAI,CAC9D,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,KACxB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;AAEzC,8JAA8J;AAC9J,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,0JAA0J;IAC1J,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C,mSAAmS;IACnS,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,2IAA2I;IAC3I,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,qHAAqH;IACrH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;KAAE,CAAA;IACnD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,0JAA0J;AAC1J,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,qBAAqB,GACvD,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG;QACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAA;KAC/D,GACD,KAAK;CACV,CAAA;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IAC3E,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,6HAA6H;IAC7H,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,oOAAoO;IACpO,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,yIAAyI;IACzI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IAChE,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,YAAY;KAAE,CAAA;CACjE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -1,11 +1,7 @@
 'use strict';
 
 var os = require('os');
-var crossSpawn = require('cross-spawn');
 var string_decoder = require('string_decoder');
-var child_process = require('child_process');
-
-function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -26,7 +22,6 @@ function _interopNamespace(e) {
 }
 
 var os__namespace = /*#__PURE__*/_interopNamespace(os);
-var crossSpawn__default = /*#__PURE__*/_interopDefault(crossSpawn);
 
 // src/config/define-repo-contract.ts
 function defineRepoContract(config) {
@@ -236,7 +231,7 @@ function validateRepoContractConfig(config) {
   if (untrusted === null || typeof untrusted !== "object") {
     throw new InvalidRepoContractConfigError("config must be an object.");
   }
-  const { checks, concurrency } = untrusted;
+  const { checks, concurrency, spawn, env, shell, killProcessTree } = untrusted;
   if (checks === null || typeof checks !== "object" || Array.isArray(checks)) {
     throw new InvalidRepoContractConfigError(
       "checks must be an object mapping check id to check definition."
@@ -249,12 +244,35 @@ function validateRepoContractConfig(config) {
       );
     }
   }
+  if (typeof spawn !== "function") {
+    throw new InvalidRepoContractConfigError("spawn must be a function.");
+  }
+  validateConfigEnv(env);
+  if (shell !== void 0 && typeof shell !== "boolean") {
+    throw new InvalidRepoContractConfigError("shell must be a boolean when provided.");
+  }
+  const globalShell = shell === true;
+  if (killProcessTree !== void 0 && typeof killProcessTree !== "function") {
+    throw new InvalidRepoContractConfigError("killProcessTree must be a function when provided.");
+  }
   for (const [checkId, check] of Object.entries(checks)) {
-    validateCheckDefinition(checkId, check);
+    validateCheckDefinition(checkId, check, globalShell);
   }
   validateDependencyGraph(checks);
 }
-function validateCheckDefinition(checkId, check) {
+function validateConfigEnv(env) {
+  if (env === null || typeof env !== "object" || Array.isArray(env)) {
+    throw new InvalidRepoContractConfigError(
+      "env must be an object mapping variable name to value."
+    );
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value !== "string" && value !== void 0) {
+      throw new InvalidRepoContractConfigError(`env["${key}"] must be a string or undefined.`);
+    }
+  }
+}
+function validateCheckDefinition(checkId, check, globalShell) {
   if (/^(?:0|[1-9]\d*)$/.test(checkId)) {
     throw new InvalidCheckConfigError(
       checkId,
@@ -265,7 +283,7 @@ function validateCheckDefinition(checkId, check) {
     throw new InvalidCheckConfigError(checkId, "check definition must be an object.");
   }
   const fields = check;
-  const usesShell = validateShell(checkId, fields.shell);
+  const usesShell = validateShell(checkId, fields.shell, globalShell);
   validateRun(checkId, fields.run, usesShell);
   validateCwd(checkId, fields.cwd);
   validateEnv(checkId, fields.env);
@@ -276,11 +294,11 @@ function validateCheckDefinition(checkId, check) {
   validateIsolated(checkId, fields.isolated);
   validatePolicy(checkId, fields.policy);
 }
-function validateShell(checkId, shell) {
+function validateShell(checkId, shell, globalShell) {
   if (shell !== void 0 && typeof shell !== "boolean") {
     throw new InvalidCheckConfigError(checkId, "shell must be a boolean when provided.");
   }
-  return shell === true;
+  return typeof shell === "boolean" ? shell : globalShell;
 }
 function validateRun(checkId, run, usesShell) {
   if (typeof run !== "string" && !Array.isArray(run)) {
@@ -627,18 +645,23 @@ async function runWithConcurrencyGraph(items, concurrency, dependencyIndexes, wo
     launchNext();
   });
 }
+
+// src/execution/process-tree.ts
 function shouldSpawnDetached() {
   return process.platform !== "win32";
 }
 function isErrnoException(error) {
   return error instanceof Error && "code" in error;
 }
-function killTree(pid, signal) {
+function killTree(pid, signal, killProcessTree) {
   if (!Number.isInteger(pid) || pid <= 0) {
     return;
   }
   if (process.platform === "win32") {
-    const result = child_process.spawnSync("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore" });
+    if (killProcessTree === void 0) return;
+    const result = killProcessTree("taskkill", ["/pid", String(pid), "/t", "/f"], {
+      stdio: "ignore"
+    });
     if (result.error !== void 0) throw result.error;
     return;
   }
@@ -672,7 +695,7 @@ function createBoundedCollector() {
     value: () => value
   };
 }
-function resolveCommand(checkId, check) {
+function resolveCommand(checkId, check, effectiveShell) {
   const run = check.run;
   if (typeof run !== "string") {
     const [command2, ...args2] = run;
@@ -681,7 +704,7 @@ function resolveCommand(checkId, check) {
     }
     return { command: command2, args: args2 };
   }
-  if (check.shell === true) {
+  if (effectiveShell) {
     return { command: run, args: [] };
   }
   const [command, ...args] = tokenizeRunString(run, checkId);
@@ -690,10 +713,10 @@ function resolveCommand(checkId, check) {
   }
   return { command, args };
 }
-function buildEnv(check) {
+function buildEnv(check, ambientEnv) {
   const base = {};
   if (check.inheritEnv !== false) {
-    for (const [key, value] of Object.entries(process.env)) {
+    for (const [key, value] of Object.entries(ambientEnv)) {
       if (value !== void 0) base[key] = value;
     }
   }
@@ -716,13 +739,14 @@ function terminalEvidence(command, args, startedAt, status, exitCode, signal, st
     ...spawnErrorCode !== void 0 ? { spawnErrorCode } : {}
   };
 }
-async function spawnCheck(checkId, check, runSignal, activeHandles) {
+async function spawnCheck(checkId, check, runSignal, activeHandles, execution) {
   const startedAt = /* @__PURE__ */ new Date();
-  const { command, args } = resolveCommand(checkId, check);
+  const effectiveShell = check.shell ?? execution.shell;
+  const { command, args } = resolveCommand(checkId, check, effectiveShell);
   if (runSignal?.aborted === true) {
     return terminalEvidence(command, args, startedAt, "aborted", null, null);
   }
-  const env = buildEnv(check);
+  const env = buildEnv(check, execution.env);
   let terminationReason = null;
   let timeoutHandle;
   const timeoutController = new AbortController();
@@ -737,10 +761,10 @@ async function spawnCheck(checkId, check, runSignal, activeHandles) {
     runSignal !== void 0 ? [runSignal, timeoutController.signal] : [timeoutController.signal]
   );
   return new Promise((resolve) => {
-    const child = crossSpawn__default.default(command, args, {
+    const child = execution.spawn(command, args, {
       cwd: check.cwd,
       env,
-      shell: check.shell === true,
+      shell: effectiveShell,
       detached: shouldSpawnDetached(),
       // Windows-only cosmetic behavior (suppresses a console window flash)
       // with no effect on stdout/stderr/exitCode/signal on any platform, and
@@ -755,7 +779,11 @@ async function spawnCheck(checkId, check, runSignal, activeHandles) {
     let hostTerminated = false;
     const bestEffortKillTree = (pid, signal) => {
       try {
-        killTree(pid, signal);
+        killTree(pid, signal, execution.killProcessTree);
+      } catch {
+      }
+      try {
+        child.kill(signal);
       } catch {
       }
     };
@@ -894,7 +922,7 @@ function resolveCheckDependencies(checks, requestedChecks) {
   for (const checkId of requestedChecks) visit(checkId);
   return Object.entries(checks).filter(([checkId]) => required.has(checkId));
 }
-async function runChecks(checks, concurrency, options) {
+async function runChecks(checks, concurrency, execution, options) {
   const entries = options?.checks ? resolveCheckDependencies(checks, options.checks) : Object.entries(checks);
   const activeHandles = /* @__PURE__ */ new Set();
   const hostAbortController = new AbortController();
@@ -915,7 +943,7 @@ async function runChecks(checks, concurrency, options) {
     )
   );
   const worker = async ([checkId, check]) => {
-    const evidence = await spawnCheck(checkId, check, runSignal, activeHandles);
+    const evidence = await spawnCheck(checkId, check, runSignal, activeHandles, execution);
     return [checkId, check, evidence];
   };
   try {
@@ -1047,7 +1075,13 @@ function runRepoContract(config, options) {
 async function runRepoContractAfterValidation(config, options) {
   const concurrency = config.concurrency ?? os__namespace.availableParallelism();
   const startedAt = /* @__PURE__ */ new Date();
-  const results = await runChecks(config.checks, concurrency, options);
+  const execution = {
+    spawn: config.spawn,
+    killProcessTree: config.killProcessTree,
+    env: config.env,
+    shell: config.shell ?? false
+  };
+  const results = await runChecks(config.checks, concurrency, execution, options);
   const completedAt = /* @__PURE__ */ new Date();
   const { evidence, entries } = await buildEvidence(results, startedAt, completedAt);
   const verdict = await runPolicies(entries, evidence);