@jinn-network/client 0.1.6 → 0.1.7

package/dist/harnesses/impls/learner/types.d.ts

@@ -121,4 +121,15 @@ export interface LearnerHarnessConfig {
      * Defaults to 'bare'.
      */
     runtimeMode?: 'bare' | 'container' | 'docker-compose';
+    /**
+     * Path to the `codex` executable. Used by `isReady()` when this
+     * `LearnerHarness` is the Codex variant (`name === CODEX_HARNESS`) — it is
+     * passed to `probeCodexDoctor()`. Defaults to 'codex' (from PATH).
+     */
+    codexPath?: string;
+    /**
+     * Timeout (ms) for the `codex --version` probe in the Codex variant's
+     * `isReady()`. Defaults to 30s.
+     */
+    codexDoctorTimeoutMs?: number;
 }

package/dist/harnesses/impls/stub.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Env-gated stub harness for the T2.2 producer/evaluator gate.
+ *
+ * When JINN_HARNESS_STUB_INSTANCE is set, the canned patch at
+ * <fixturesDir>/<instanceMatcher>.patch is returned as a SWE-rebench v2
+ * restoration solution. Never calls an LLM; never accepts tasks whose
+ * spec.instance_id differs from the configured matcher.
+ *
+ * PRODUCTION SAFETY — two-env-var requirement.
+ * This is a *fake* harness: it produces canned, non-genuine work. If it ever
+ * entered a real operator run it would generate fraudulent on-chain activity.
+ * To make accidental activation impossible, the factory requires BOTH:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to
+ *   JINN_TEST_MODE === '1'         — explicit test-mode sentinel
+ * If JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not '1', the
+ * factory THROWS rather than silently registering the stub. A single stray
+ * exported env var in an operator's shell can no longer activate it.
+ *
+ * Activated by environment variables:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to (required to activate)
+ *   JINN_TEST_MODE                 — must equal '1' (defense-in-depth; required to activate)
+ *   JINN_HARNESS_STUB_FIXTURES_DIR — dir containing <instanceMatcher>.patch files
+ *                                    (default: client/test/release/tier-2/fixtures)
+ */
+import type { Harness, HarnessContext, ReadyStatus, Solution } from '../types.js';
+export interface StubHarnessConfig {
+    /** Directory containing <instanceMatcher>.patch files. */
+    fixturesDir: string;
+    /** The instance ID this stub will accept. Tasks with other instance IDs are rejected. */
+    instanceMatcher: string;
+}
+/**
+ * A zero-LLM Harness that returns a canned patch for a specific SWE-rebench v2
+ * instance. Intended exclusively for T2.2 release-gate automation.
+ */
+export declare class StubHarness implements Harness {
+    readonly name = "harness:stub";
+    readonly version = "0.1.0-stub";
+    private readonly fixturesDir;
+    private readonly instanceMatcher;
+    constructor(config: StubHarnessConfig);
+    supports(ctx: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): boolean;
+    isReady(): Promise<ReadyStatus>;
+    run(ctx: HarnessContext): Promise<Solution>;
+}
+/**
+ * Factory that reads JINN_HARNESS_STUB_INSTANCE and JINN_HARNESS_STUB_FIXTURES_DIR
+ * from the environment and returns a configured StubHarness, or null if the env
+ * var is absent (allowing the registry to skip registration silently).
+ *
+ * Defense-in-depth: if JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is
+ * not exactly '1', this THROWS rather than returning a harness — a real
+ * operator run must never silently pick up the fake stub harness.
+ */
+export declare function maybeCreateStubHarnessFromEnv(): StubHarness | null;

package/dist/harnesses/impls/stub.js

@@ -0,0 +1,89 @@
+/**
+ * Env-gated stub harness for the T2.2 producer/evaluator gate.
+ *
+ * When JINN_HARNESS_STUB_INSTANCE is set, the canned patch at
+ * <fixturesDir>/<instanceMatcher>.patch is returned as a SWE-rebench v2
+ * restoration solution. Never calls an LLM; never accepts tasks whose
+ * spec.instance_id differs from the configured matcher.
+ *
+ * PRODUCTION SAFETY — two-env-var requirement.
+ * This is a *fake* harness: it produces canned, non-genuine work. If it ever
+ * entered a real operator run it would generate fraudulent on-chain activity.
+ * To make accidental activation impossible, the factory requires BOTH:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to
+ *   JINN_TEST_MODE === '1'         — explicit test-mode sentinel
+ * If JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not '1', the
+ * factory THROWS rather than silently registering the stub. A single stray
+ * exported env var in an operator's shell can no longer activate it.
+ *
+ * Activated by environment variables:
+ *   JINN_HARNESS_STUB_INSTANCE     — instance ID this stub responds to (required to activate)
+ *   JINN_TEST_MODE                 — must equal '1' (defense-in-depth; required to activate)
+ *   JINN_HARNESS_STUB_FIXTURES_DIR — dir containing <instanceMatcher>.patch files
+ *                                    (default: client/test/release/tier-2/fixtures)
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+/**
+ * A zero-LLM Harness that returns a canned patch for a specific SWE-rebench v2
+ * instance. Intended exclusively for T2.2 release-gate automation.
+ */
+export class StubHarness {
+    name = 'harness:stub';
+    version = '0.1.0-stub';
+    fixturesDir;
+    instanceMatcher;
+    constructor(config) {
+        this.fixturesDir = config.fixturesDir;
+        this.instanceMatcher = config.instanceMatcher;
+    }
+    supports(ctx) {
+        if (ctx.role === 'evaluation')
+            return false;
+        return ctx.solverType === 'swe-rebench-v2.v1';
+    }
+    async isReady() {
+        return { ready: true };
+    }
+    async run(ctx) {
+        const taskInstanceId = ctx.task.spec?.['instance_id'];
+        if (taskInstanceId !== this.instanceMatcher) {
+            throw new Error(`stub harness: task.spec.instance_id=${String(taskInstanceId)} does not match configured instanceMatcher=${this.instanceMatcher}`);
+        }
+        const patchPath = path.join(this.fixturesDir, `${this.instanceMatcher}.patch`);
+        const patch = await fs.readFile(patchPath, 'utf-8');
+        return {
+            venueRef: { name: this.name },
+            gating: {},
+            solutionPayload: {
+                schemaVersion: 'swe-rebench-v2-solution.v1',
+                patch,
+            },
+        };
+    }
+}
+/**
+ * Factory that reads JINN_HARNESS_STUB_INSTANCE and JINN_HARNESS_STUB_FIXTURES_DIR
+ * from the environment and returns a configured StubHarness, or null if the env
+ * var is absent (allowing the registry to skip registration silently).
+ *
+ * Defense-in-depth: if JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is
+ * not exactly '1', this THROWS rather than returning a harness — a real
+ * operator run must never silently pick up the fake stub harness.
+ */
+export function maybeCreateStubHarnessFromEnv() {
+    const instanceMatcher = process.env['JINN_HARNESS_STUB_INSTANCE'];
+    if (!instanceMatcher)
+        return null;
+    if (process.env['JINN_TEST_MODE'] !== '1') {
+        throw new Error('stub harness must never activate in a real operator run: ' +
+            'JINN_HARNESS_STUB_INSTANCE is set but JINN_TEST_MODE is not "1". ' +
+            'The stub harness produces canned, non-genuine work and would generate ' +
+            'fraudulent on-chain activity. Set JINN_TEST_MODE=1 if this is a Tier 2 ' +
+            'test; otherwise unset JINN_HARNESS_STUB_INSTANCE.');
+    }
+    const fixturesDir = process.env['JINN_HARNESS_STUB_FIXTURES_DIR'] ??
+        path.resolve(process.cwd(), 'test', 'release', 'tier-2', 'fixtures');
+    return new StubHarness({ instanceMatcher, fixturesDir });
+}
+//# sourceMappingURL=stub.js.map

package/dist/harnesses/impls/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["../../../src/harnesses/impls/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAUlC;;;GAGG;AACH,MAAM,OAAO,WAAW;IACb,IAAI,GAAG,cAAc,CAAC;IACtB,OAAO,GAAG,YAAY,CAAC;IAEf,WAAW,CAAS;IACpB,eAAe,CAAS;IAEzC,YAAY,MAAyB;QACnC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAChD,CAAC;IAED,QAAQ,CAAC,GAAgE;QACvE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAC5C,OAAO,GAAG,CAAC,UAAU,KAAK,mBAAmB,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,OAAO;QACX,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAmB;QAC3B,MAAM,cAAc,GAAI,GAAG,CAAC,IAAI,CAAC,IAA4C,EAAE,CAAC,aAAa,CAAC,CAAC;QAC/F,IAAI,cAAc,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,CAAC,cAAc,CAAC,8CAA8C,IAAI,CAAC,eAAe,EAAE,CAClI,CAAC;QACJ,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,eAAe,QAAQ,CAAC,CAAC;QAC/E,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACpD,OAAO;YACL,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;YAC7B,MAAM,EAAE,EAAE;YACV,eAAe,EAAE;gBACf,aAAa,EAAE,4BAA4B;gBAC3C,KAAK;aACN;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAClE,IAAI,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,2DAA2D;YACzD,mEAAmE;YACnE,wEAAwE;YACxE,yEAAyE;YACzE,mDAAmD,CACtD,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IACvE,OAAO,IAAI,WAAW,CAAC,EAAE,eAAe,EAAE,WAAW,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/harnesses/impls/swe-rebench-v2-evaluator/eval-runner.d.ts

@@ -37,6 +37,36 @@ export declare class EvalCouldNotGradeError extends Error {
     readonly logExcerpt: string;
     constructor(reason: string, logExcerpt?: string);
 }
+/**
+ * Thrown by `runEval` when the disk cannot be brought above the eval
+ * disk-floor even after a broad prune. A clean abort — the caller stops
+ * gracefully; no instance is graded, nothing is marked. Distinct from
+ * `EvalCouldNotGradeError`: this is operator-environment, retryable, and must
+ * never be turned into a `scorable: false` admission (#476).
+ */
+export declare class InsufficientDiskError extends Error {
+    readonly freeBytes: number;
+    readonly floorBytes: number;
+    constructor(freeBytes: number, floorBytes: number);
+}
+/**
+ * Default free-disk floor required before an eval round: 20 GB. A single
+ * SWE-rebench eval image was observed to peak transiently at ~12.6 GB, so the
+ * floor clears the worst observed instance with real margin. Override with
+ * `JINN_EVAL_DISK_FLOOR_GB` on constrained hosts.
+ */
+export declare const DEFAULT_EVAL_DISK_FLOOR_BYTES = 20000000000;
+/** Resolve the disk floor: explicit option > `JINN_EVAL_DISK_FLOOR_GB` env > default. */
+export declare function resolveDiskFloorBytes(opt: number | undefined): number;
+/**
+ * Default wall-clock limit for one upstream eval.py invocation: 2 hours. Some
+ * linux/amd64 SWE-rebench images can wedge indefinitely under Apple Silicon
+ * emulation after a native crash, so the subprocess gets a hard guardrail.
+ * Override with `JINN_SWE_REBENCH_EVAL_TIMEOUT_MS`; set `0` to disable.
+ */
+export declare const DEFAULT_EVAL_TIMEOUT_MS: number;
+/** Resolve the eval timeout: explicit option > env > default. */
+export declare function resolveEvalTimeoutMs(opt: number | undefined): number;
 export interface PythonEvalRunnerOptions {
     /** Path to the cloned SWE-rebench-V2 repo (cached locally). */
     upstreamRepoDir: string;
@@ -45,66 +75,55 @@ export interface PythonEvalRunnerOptions {
     /** Workers for parallel eval (defaults to 1; we run one task at a time). */
     maxWorkers?: number;
     /**
-     * Max number of distinct eval images to keep in the local Docker cache.
-     * The runner tracks an in-process LRU keyed by image tag; once usage exceeds
-     * this cap, the least-recently-used images are removed via
-     * {@link PythonEvalRunnerOptions.cleanupImage}.
-     *
-     * The leaderboard pool has hundreds of unique instances at ~3 GB/image, so
-     * an unbounded cache fills operator disks in days (jinn-mono-uy6v.11).
+     * Removes a completed round's entire Docker footprint — the round's image,
+     * stopped containers, and build cache — so eval disk usage never
+     * accumulates across instances (#476). Called once per `runEval`, in a
+     * `finally`, even when the eval threw.
      *
-     * Default: `process.env.JINN_EVAL_IMAGE_CACHE_MAX` parsed as an integer, or
-     * `DEFAULT_EVAL_IMAGE_CACHE_MAX` (20) if unset/invalid.
+     * Defaults to {@link defaultPruneRound}. Implementations MUST NOT throw —
+     * `runEval` guards defensively, but cleanup failures should be swallowed
+     * (logged elsewhere if desired) so a flaky `docker` never escapes `runEval`.
      */
-    imageCacheMax?: number;
+    pruneRound?: (image: string) => Promise<void>;
     /**
-     * Removes an image from the local Docker cache (or no-ops if the operator
-     * has chosen not to GC). Called for each eviction from the LRU.
-     *
-     * Defaults to `docker rmi <image>` via the system `docker` binary. Test
-     * suites inject a stub to capture the eviction order without shelling out.
-     *
-     * Implementations MUST NOT throw — failures should be swallowed (logged
-     * elsewhere if desired) so a missing/failed `docker rmi` never escapes
-     * `runEval`. The runner enforces this defensively too.
+     * Resolves the eval image digest while the image is still local, before
+     * per-round pruning removes it. Defaults to `docker image inspect`.
+     */
+    resolveImageDigest?: (image: string) => Promise<string | null>;
+    /**
+     * Required free disk (bytes) before an eval round starts. Explicit value >
+     * `JINN_EVAL_DISK_FLOOR_GB` env > {@link DEFAULT_EVAL_DISK_FLOOR_BYTES}.
      */
-    cleanupImage?: (image: string) => Promise<void>;
+    diskFloorBytes?: number;
+    /** Probe of free disk (bytes). Defaults to a `statfs` on the temp dir. */
+    freeDiskBytes?: () => Promise<number>;
+    /**
+     * Broad reclaim invoked when free disk is below the floor. Defaults to
+     * `docker system prune -f`. MUST NOT throw.
+     */
+    systemPrune?: () => Promise<void>;
+    /**
+     * Wall-clock timeout (ms) for one upstream eval.py invocation. Explicit value
+     * > `JINN_SWE_REBENCH_EVAL_TIMEOUT_MS` env > {@link DEFAULT_EVAL_TIMEOUT_MS}.
+     * Set to 0 to disable.
+     */
+    evalTimeoutMs?: number;
 }
-/**
- * Default cap on the per-instance Docker image cache when no explicit
- * `imageCacheMax` and no `JINN_EVAL_IMAGE_CACHE_MAX` env var are configured.
- *
- * 20 images × ~3 GB/image ≈ 60 GB working set — small enough that even a
- * 256 GB disk has headroom, large enough that the steady-state loop on a
- * frequently-repeating subset of the pool rarely re-pulls.
- */
-export declare const DEFAULT_EVAL_IMAGE_CACHE_MAX = 20;
-export declare function resolveImageCacheMax(opt: number | undefined): number;
 export declare function matchInfraSignature(log: string): string | null;
 export declare class PythonEvalRunner implements EvalRunner {
     private readonly opts;
-    /**
-     * LRU of image tags whose Docker layers may be cached locally. Stored as a
-     * `Set<string>` because `Set` preserves insertion order; we delete-then-add
-     * to refresh recency and `next()` on the keys iterator to find the
-     * least-recently-used entry.
-     */
-    private readonly imageLru;
-    private readonly imageCacheMax;
-    private readonly cleanupImage;
+    private readonly pruneRound;
+    private readonly diskFloorBytes;
+    private readonly freeDiskBytes;
+    private readonly systemPrune;
+    private readonly resolveImageDigest;
+    private readonly evalTimeoutMs;
     constructor(opts: PythonEvalRunnerOptions);
-    runEval(args: Parameters<EvalRunner['runEval']>[0]): ReturnType<EvalRunner['runEval']>;
     /**
-     * Move `image` to the most-recently-used slot of the in-process LRU; if the
-     * set now exceeds {@link imageCacheMax}, evict the oldest entries via
-     * {@link cleanupImage}. Eviction failures are swallowed so a flaky
-     * `docker rmi` cannot escape `runEval`.
-     *
-     * The cap is enforced after the just-used image is inserted: the
-     * just-evaluated image is the *most* recent, so repeat-evals of recently
-     * used instances never re-pull. Only when more than N distinct images have
-     * been used does the oldest get rmi'd.
+     * Ensure enough free disk for an eval round. Below the floor → broad prune →
+     * re-probe; still below → `InsufficientDiskError` (clean abort). (#476)
      */
-    private recordImageUsage;
+    private ensureDiskHeadroom;
+    runEval(args: Parameters<EvalRunner['runEval']>[0]): ReturnType<EvalRunner['runEval']>;
     private runEvalImpl;
 }

package/dist/harnesses/impls/swe-rebench-v2-evaluator/eval-runner.js

@@ -26,9 +26,10 @@
  *     re-raises as `SkippableError` (no signed verdict).
  */
 import { spawn } from 'node:child_process';
-import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { mkdtemp, writeFile, readFile, rm, statfs } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
+import { defaultCommandRunner, resolveImageDigest as resolveSubstrateImageDigest, } from '../../../solver-types/_swe-rebench-v2-substrate.js';
 /**
  * Thrown when the eval could not actually grade the solution. There is no
  * signal about the solver here, only about the operator's environment — the
@@ -46,62 +47,102 @@ export class EvalCouldNotGradeError extends Error {
     }
 }
 /**
- * Default cap on the per-instance Docker image cache when no explicit
- * `imageCacheMax` and no `JINN_EVAL_IMAGE_CACHE_MAX` env var are configured.
- *
- * 20 images × ~3 GB/image ≈ 60 GB working set — small enough that even a
- * 256 GB disk has headroom, large enough that the steady-state loop on a
- * frequently-repeating subset of the pool rarely re-pulls.
+ * Thrown by `runEval` when the disk cannot be brought above the eval
+ * disk-floor even after a broad prune. A clean abort — the caller stops
+ * gracefully; no instance is graded, nothing is marked. Distinct from
+ * `EvalCouldNotGradeError`: this is operator-environment, retryable, and must
+ * never be turned into a `scorable: false` admission (#476).
+ */
+export class InsufficientDiskError extends Error {
+    freeBytes;
+    floorBytes;
+    constructor(freeBytes, floorBytes) {
+        const gb = (n) => (n / 1_000_000_000).toFixed(1);
+        super(`insufficient disk for swe-rebench eval: ${gb(freeBytes)} GB free, ` +
+            `need ≥ ${gb(floorBytes)} GB`);
+        this.name = 'InsufficientDiskError';
+        this.freeBytes = freeBytes;
+        this.floorBytes = floorBytes;
+    }
+}
+/**
+ * Default free-disk floor required before an eval round: 20 GB. A single
+ * SWE-rebench eval image was observed to peak transiently at ~12.6 GB, so the
+ * floor clears the worst observed instance with real margin. Override with
+ * `JINN_EVAL_DISK_FLOOR_GB` on constrained hosts.
  */
-export const DEFAULT_EVAL_IMAGE_CACHE_MAX = 20;
-export function resolveImageCacheMax(opt) {
+export const DEFAULT_EVAL_DISK_FLOOR_BYTES = 20_000_000_000;
+/** Resolve the disk floor: explicit option > `JINN_EVAL_DISK_FLOOR_GB` env > default. */
+export function resolveDiskFloorBytes(opt) {
     if (typeof opt === 'number' && Number.isFinite(opt) && opt > 0)
         return Math.floor(opt);
-    const envRaw = process.env['JINN_EVAL_IMAGE_CACHE_MAX'];
+    const envRaw = process.env['JINN_EVAL_DISK_FLOOR_GB'];
     if (envRaw !== undefined) {
-        // `Number()` returns 0 for `""` / whitespace and NaN for strings with
-        // non-numeric content (e.g. `"garbage"`, `"1e3oops"`) — unlike `parseInt`,
-        // which would silently accept `parseInt("1e3oops") === 1`. Either way we
-        // reject anything that isn't a positive integer.
         const parsed = Number(envRaw);
-        if (Number.isFinite(parsed) && Number.isInteger(parsed) && parsed > 0)
-            return parsed;
-        // Surface the typo so operators discover it before the disk fills,
-        // rather than silently running on the default.
-        console.warn(`[swe-rebench-v2] JINN_EVAL_IMAGE_CACHE_MAX=${JSON.stringify(envRaw)} is not a positive integer — using default ${DEFAULT_EVAL_IMAGE_CACHE_MAX}`);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return Math.floor(parsed * 1_000_000_000);
+        console.warn(`[swe-rebench-v2] JINN_EVAL_DISK_FLOOR_GB=${JSON.stringify(envRaw)} is not a positive ` +
+            `number — using default ${DEFAULT_EVAL_DISK_FLOOR_BYTES / 1_000_000_000} GB`);
     }
-    return DEFAULT_EVAL_IMAGE_CACHE_MAX;
+    return DEFAULT_EVAL_DISK_FLOOR_BYTES;
 }
 /**
- * Production `cleanupImage`: spawn `docker rmi <image>`. Errors are tolerated
- * — a missing/failed `docker rmi` is operationally survivable (the image
- * stays on disk; cache stays bloated for a while; not a correctness failure)
- * — but we warn on non-zero exit and on failed-to-spawn so a persistently-flaky
- * daemon (or a permission slip) becomes visible before disks fill. Silent
- * leaks were the original failure mode `jinn-mono-uy6v.11` exists to fix.
- *
- * We listen on `'exit'` rather than `'close'` and route stdio to `'ignore'`
- * so the resolve path doesn't depend on parent-side stream draining (which
- * can fail to fire `'close'` cleanly when piped without backpressure on the
- * right tick). The image tag + exit code is sufficient signal; operators can
- * grep the docker daemon log for the underlying reason.
+ * Default wall-clock limit for one upstream eval.py invocation: 2 hours. Some
+ * linux/amd64 SWE-rebench images can wedge indefinitely under Apple Silicon
+ * emulation after a native crash, so the subprocess gets a hard guardrail.
+ * Override with `JINN_SWE_REBENCH_EVAL_TIMEOUT_MS`; set `0` to disable.
  */
-function defaultCleanupImage(image) {
-    return new Promise((resolve) => {
-        const child = spawn('docker', ['rmi', image], { stdio: ['ignore', 'ignore', 'ignore'] });
-        child.on('exit', (code, signal) => {
-            if (code !== 0) {
-                const status = code !== null ? `exited ${code}` : `terminated by signal ${signal ?? 'unknown'}`;
-                console.warn(`[swe-rebench-v2] docker rmi ${image} ${status}`);
-            }
-            resolve();
-        });
-        child.on('error', (err) => {
-            console.warn(`[swe-rebench-v2] docker rmi ${image} failed to spawn: ${err.message}`);
-            resolve();
-        });
+export const DEFAULT_EVAL_TIMEOUT_MS = 2 * 60 * 60 * 1000;
+/** Resolve the eval timeout: explicit option > env > default. */
+export function resolveEvalTimeoutMs(opt) {
+    if (typeof opt === 'number' && Number.isFinite(opt) && opt >= 0)
+        return Math.floor(opt);
+    const envRaw = process.env['JINN_SWE_REBENCH_EVAL_TIMEOUT_MS'];
+    if (envRaw !== undefined) {
+        const parsed = Number(envRaw);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return Math.floor(parsed);
+        console.warn(`[swe-rebench-v2] JINN_SWE_REBENCH_EVAL_TIMEOUT_MS=${JSON.stringify(envRaw)} is not a ` +
+            `non-negative number — using default ${DEFAULT_EVAL_TIMEOUT_MS} ms`);
+    }
+    return DEFAULT_EVAL_TIMEOUT_MS;
+}
+/** Production disk probe: free bytes on the filesystem backing the temp dir. */
+async function defaultFreeDiskBytes() {
+    const s = await statfs(tmpdir());
+    return s.bavail * s.bsize;
+}
+/**
+ * Spawn `docker <args>`, resolving regardless of outcome — a failed cleanup
+ * command is logged, never thrown (#476: cleanup must not break the eval loop).
+ */
+function runDocker(args) {
+    return defaultCommandRunner('docker', args)
+        .then((res) => {
+        if (res.exitCode !== 0) {
+            const detail = (res.stderr || res.stdout).trim();
+            console.warn(`[swe-rebench-v2] docker ${args.join(' ')} exited ${res.exitCode}` +
+                `${detail ? `: ${detail.slice(-500)}` : ''}`);
+        }
+    })
+        .catch((err) => {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.warn(`[swe-rebench-v2] docker ${args.join(' ')} failed to spawn: ${reason}`);
     });
 }
+/**
+ * Production `pruneRound`: remove the round's image, then prune stopped
+ * containers and build cache. Each step is best-effort.
+ */
+async function defaultPruneRound(image) {
+    if (image)
+        await runDocker(['rmi', '-f', image]);
+    await runDocker(['container', 'prune', '-f']);
+    await runDocker(['builder', 'prune', '-f']);
+}
+async function defaultResolveImageDigest(imageName) {
+    return resolveSubstrateImageDigest(imageName, defaultCommandRunner);
+}
 /**
  * Container-output signatures that mean the eval aborted before producing a
  * usable result — i.e. the operator's environment is the problem, not the
@@ -120,6 +161,7 @@ const INFRA_SIGNATURES = [
     { rx: /Failed building editable|Failed to build installable wheels/i, reason: 'install_build_failed' },
     { rx: /No virtual environment found/i, reason: 'venv_missing' },
     { rx: /exec format error|the requested image's platform .* does not match/i, reason: 'image_arch_mismatch' },
+    { rx: /Fatal Python error:\s*Illegal instruction|Illegal instruction(?:\s+\(core dumped\))?/i, reason: 'image_arch_mismatch' },
     // 2026-05-14 triage (jinn-mono-fufn) — failure fingerprints from real verdicts:
     { rx: /A virtual environment already exists at \S+\.venv\b/i, reason: 'venv_collision' },
     { rx: /No module named pytest\b/i, reason: 'pytest_missing' },
@@ -178,64 +220,62 @@ function buildTestCommands(args) {
 }
 export class PythonEvalRunner {
     opts;
-    /**
-     * LRU of image tags whose Docker layers may be cached locally. Stored as a
-     * `Set<string>` because `Set` preserves insertion order; we delete-then-add
-     * to refresh recency and `next()` on the keys iterator to find the
-     * least-recently-used entry.
-     */
-    imageLru = new Set();
-    imageCacheMax;
-    cleanupImage;
+    pruneRound;
+    diskFloorBytes;
+    freeDiskBytes;
+    systemPrune;
+    resolveImageDigest;
+    evalTimeoutMs;
     constructor(opts) {
         this.opts = opts;
-        this.imageCacheMax = resolveImageCacheMax(opts.imageCacheMax);
-        this.cleanupImage = opts.cleanupImage ?? defaultCleanupImage;
+        this.pruneRound = opts.pruneRound ?? defaultPruneRound;
+        this.diskFloorBytes = resolveDiskFloorBytes(opts.diskFloorBytes);
+        this.freeDiskBytes = opts.freeDiskBytes ?? defaultFreeDiskBytes;
+        this.systemPrune = opts.systemPrune ?? (() => runDocker(['system', 'prune', '-f']));
+        this.resolveImageDigest = opts.resolveImageDigest ?? defaultResolveImageDigest;
+        this.evalTimeoutMs = resolveEvalTimeoutMs(opts.evalTimeoutMs);
+    }
+    /**
+     * Ensure enough free disk for an eval round. Below the floor → broad prune →
+     * re-probe; still below → `InsufficientDiskError` (clean abort). (#476)
+     */
+    async ensureDiskHeadroom() {
+        const free = await this.freeDiskBytes();
+        if (free >= this.diskFloorBytes)
+            return;
+        console.warn(`[swe-rebench-v2] low disk (${(free / 1e9).toFixed(1)} GB) — running docker system prune`);
+        await this.systemPrune();
+        const afterPrune = await this.freeDiskBytes();
+        if (afterPrune < this.diskFloorBytes) {
+            throw new InsufficientDiskError(afterPrune, this.diskFloorBytes);
+        }
     }
     async runEval(args) {
+        await this.ensureDiskHeadroom();
         try {
-            return await this.runEvalImpl(args);
+            const result = await this.runEvalImpl(args);
+            let imageDigest = null;
+            try {
+                imageDigest = await this.resolveImageDigest(args.image);
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                console.warn(`[swe-rebench-v2] resolveImageDigest failed for ${args.image}: ${reason}`);
+            }
+            return {
+                ...result,
+                ...(imageDigest ? { imageDigest } : {}),
+            };
         }
         finally {
-            // Always record the image and run GC — even when the eval threw. A
-            // pull-and-crash failure (Docker storage IO error, image_arch_mismatch,
-            // patch_corrupt, eval_no_report) still left an image on disk; we must
-            // count it toward the cache cap so the failure path can't leak the LRU.
-            await this.recordImageUsage(args.image);
-        }
-    }
-    /**
-     * Move `image` to the most-recently-used slot of the in-process LRU; if the
-     * set now exceeds {@link imageCacheMax}, evict the oldest entries via
-     * {@link cleanupImage}. Eviction failures are swallowed so a flaky
-     * `docker rmi` cannot escape `runEval`.
-     *
-     * The cap is enforced after the just-used image is inserted: the
-     * just-evaluated image is the *most* recent, so repeat-evals of recently
-     * used instances never re-pull. Only when more than N distinct images have
-     * been used does the oldest get rmi'd.
-     */
-    async recordImageUsage(image) {
-        if (!image)
-            return;
-        // Refresh recency: delete-then-add reinserts at the tail of the set.
-        this.imageLru.delete(image);
-        this.imageLru.add(image);
-        while (this.imageLru.size > this.imageCacheMax) {
-            const oldest = this.imageLru.values().next().value;
-            if (!oldest)
-                break;
-            this.imageLru.delete(oldest);
+            // Prune this round's full Docker footprint — even when the eval threw,
+            // a pull-and-crash still left an image on disk (#476).
             try {
-                await this.cleanupImage(oldest);
+                await this.pruneRound(args.image);
             }
             catch (err) {
-                // Best-effort GC: a failed rmi leaves the image on disk but mustn't
-                // break the loop. Warn so a flaky `docker` (or a permission slip)
-                // becomes visible before disks fill — silent leaks were the whole
-                // problem this bead exists to fix.
                 const reason = err instanceof Error ? err.message : String(err);
-                console.warn(`[swe-rebench-v2] eval-image cleanup failed for ${oldest}: ${reason}`);
+                console.warn(`[swe-rebench-v2] pruneRound failed for ${args.image}: ${reason}`);
             }
         }
     }
@@ -280,6 +320,7 @@ export class PythonEvalRunner {
         const child = spawn(this.opts.pythonBin ?? 'python3', pyArgs, {
             cwd: this.opts.upstreamRepoDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
             // SWE-rebench eval images are published for linux/amd64. Pin the platform
             // so the upstream `docker run` is consistent on amd64 hosts and does not
             // silently crash under arm64 emulation on dev machines.
@@ -289,10 +330,54 @@ export class PythonEvalRunner {
         child.stderr.on('data', (d) => { stderr += d.toString(); });
         let stdout = '';
         child.stdout.on('data', (d) => { stdout += d.toString(); });
+        let timedOut = false;
+        let closed = false;
+        let killTimer;
+        const killChild = (signal) => {
+            const pid = child.pid;
+            if (!pid)
+                return;
+            try {
+                if (process.platform === 'win32') {
+                    child.kill(signal);
+                }
+                else {
+                    process.kill(-pid, signal);
+                }
+            }
+            catch {
+                try {
+                    child.kill(signal);
+                }
+                catch { }
+            }
+        };
+        const timeoutTimer = this.evalTimeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                killChild('SIGTERM');
+                killTimer = setTimeout(() => {
+                    if (!closed)
+                        killChild('SIGKILL');
+                }, 10_000);
+                killTimer.unref?.();
+            }, this.evalTimeoutMs)
+            : undefined;
+        timeoutTimer?.unref?.();
         const exitCode = await new Promise((resolve, reject) => {
             child.on('close', (code) => resolve(code ?? 1));
             child.on('error', reject);
+        }).finally(() => {
+            closed = true;
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            if (killTimer)
+                clearTimeout(killTimer);
         });
+        if (timedOut) {
+            await rm(tmp, { recursive: true, force: true });
+            throw new EvalCouldNotGradeError('eval_timeout', `python eval timed out after ${this.evalTimeoutMs}ms; ${(stderr || stdout).slice(-800)}`);
+        }
         let report;
         try {
             report = JSON.parse(await readFile(reportPath, 'utf8'));