@sema-agent/server 1.323.0 → 2.0.0

package/dist/bench/s1/oracle.d.ts

@@ -1,34 +1,83 @@
+/**
+ * S1 value-verdict harness — the HIDDEN OBJECTIVE ORACLE (the measure, NEVER an LLM). SPEC-S1-value-harness.md §4.
+ *
+ * ONE standalone oracle, shared by ALL three arms; ONLY the profile (arms.ts) differs. The oracle is:
+ *   - OBJECTIVE: it runs `runExecGate` (real exit codes; null-exit never passes; an empty suite never passes —
+ *     `exec-gate.d.ts`). There is NO model/LLM parameter ANYWHERE in this type (objective-oracle discipline,
+ *     design/89 §2.2.1 — the LLM is a GATE inside an arm, never the MEASURE in the numerator).
+ *   - DECORRELATED + ANTI-REWARD-HACK: it grades in a DISTINCT grader env (`ctx.newGraderEnv()`), never the
+ *     worker's own env — the SAME isolation the repair-loop §5.1 identity check enforces.
+ *   - HIDDEN + RESTORED-BEFORE-SCORING: the worker never sees `task.hiddenTestFiles`; the oracle WRITES them into
+ *     the grader checkout, overwriting any worker-authored same-named file (anti-tamper, design/89 §2.2).
+ *
+ * The repair leg needs core's `RepairOracle = (graderEnv, evidence) => OracleResult` shape — a DIFFERENT
+ * signature. `repair-oracle-adapter.ts` wraps this standalone oracle into that closure (do NOT pass `runOracle`
+ * straight to `runRepairLoop` — it would not type-check + the repair leg would be miswired, SPEC Risk MEDIUM).
+ */
 import { type ExecutionEnv, type ExecStep, type ExecStepResult } from "@sema-agent/core";
 import { type OracleVerdicts } from "./row.js";
+/**
+ * The objective verdict — the 4 s1.v1 `OracleVerdicts` booleans PLUS the derived `trulyCorrect` and the raw exec
+ * steps (provenance). `trulyCorrect` is the AND of every objective signal — it is the numerator gate. The 4
+ * boolean field names (hiddenTestsGreen / buildPassed / invariantsOk / delivered) ARE the s1.v1 contract names.
+ */
 export interface OracleVerdict extends OracleVerdicts {
+    /** = delivered && hiddenTestsGreen && buildPassed && invariantsOk. The ONLY thing that counts as value. */
     trulyCorrect: boolean;
     raw: {
         steps: ExecStepResult[];
     };
 }
+/** The slice of a TrapSpec the oracle needs (avoids a circular import on the full tasks.ts shape). */
 export interface OracleTask {
     id: string;
+    /** Hidden test files the oracle restores into the grader checkout BEFORE scoring (worker never sees these). */
     hiddenTestFiles: Array<{
         path: string;
         content: string;
     }>;
+    /** The build step(s) — exit 0 = `buildPass`. Empty ⇒ `buildPass:true` (no build to fail). */
     buildSteps: ExecStep[];
+    /** The hidden-test step(s) — exit 0 = `hiddenTestsPass`. MUST be non-empty (an empty suite never passes). */
     oracleSteps: ExecStep[];
+    /** Optional property-harness invariant step(s) — exit 0 = `invariantsOk`. Empty ⇒ `invariantsOk:true` (N/A). */
     invariantSteps?: ExecStep[];
+    /** Repo dir inside the grader env where the worker's committed tree was cloned/pulled. */
     graderRepoDir: string;
+    /** The base ref to diff against for `delivered` (HEAD must differ AND be in the committed tree). */
     baseRef: string;
+    /** 🔴 tar-worktree path (firm-v1/C4): when the grader receives a tar of the WORKTREE (no .git — to dodge the E2B
+     *  grader-clone heisenbug + Kata virtiofs st_dev limit), `delivered` can't run `git rev-parse` in the grader. The
+     *  worker (where git works) computes HEAD + s1-base shas up front; `delivered` = head≠base from THESE. When set,
+     *  the grader does no git at all. Absent ⇒ the legacy `cd REPO && git rev-parse` path (mock tests). */
     deliveredShas?: {
         head: string;
         base: string;
     };
 }
+/**
+ * A minimal grader-side helper the oracle needs the env to expose to clone/pull the worker's COMMITTED tree IN
+ * and to write hidden tests. The real E2B/Kata env satisfies this via its exec/writeFile; the shape test passes
+ * a deterministic fake. (We DON'T reuse `ExecutionEnv.writeFile` directly only because the file-write path is
+ * env-specific — but we DO require the `ExecutionEnv` itself for `runExecGate`, the actual measure.)
+ */
 export interface GraderTransport {
+    /** Run a setup command in the grader (clone the worker's committed tree, checkout the SHA). Returns exit code. */
     exec: (command: string) => Promise<{
         exitCode: number;
         stdout: string;
         stderr: string;
     }>;
+    /** Write a hidden test file into the grader checkout (overwriting a worker-authored same-named file). */
     writeFile: (path: string, content: string) => Promise<void>;
 }
+/**
+ * Run the hidden objective oracle against the worker's COMMITTED tree, IN a distinct grader env.
+ *
+ * @param graderEnv  the distinct grader execution env (for `runExecGate` — the real measure).
+ * @param transport  the grader's clone/checkout/writeFile seam (restore hidden tests + pull the committed tree in).
+ * @param workerEnv  the worker's env — passed ONLY so we can assert `graderEnv !== workerEnv` (anti-reward-hack).
+ * @param task       the trap's oracle config (hidden tests + build/oracle/invariant steps + repo + base ref).
+ */
 export declare function runOracle(graderEnv: ExecutionEnv, transport: GraderTransport, workerEnv: ExecutionEnv, task: OracleTask): Promise<OracleVerdict>;
 //# sourceMappingURL=oracle.d.ts.map

package/dist/bench/s1/oracle.js

@@ -1,13 +1,45 @@
+/**
+ * S1 value-verdict harness — the HIDDEN OBJECTIVE ORACLE (the measure, NEVER an LLM). SPEC-S1-value-harness.md §4.
+ *
+ * ONE standalone oracle, shared by ALL three arms; ONLY the profile (arms.ts) differs. The oracle is:
+ *   - OBJECTIVE: it runs `runExecGate` (real exit codes; null-exit never passes; an empty suite never passes —
+ *     `exec-gate.d.ts`). There is NO model/LLM parameter ANYWHERE in this type (objective-oracle discipline,
+ *     design/89 §2.2.1 — the LLM is a GATE inside an arm, never the MEASURE in the numerator).
+ *   - DECORRELATED + ANTI-REWARD-HACK: it grades in a DISTINCT grader env (`ctx.newGraderEnv()`), never the
+ *     worker's own env — the SAME isolation the repair-loop §5.1 identity check enforces.
+ *   - HIDDEN + RESTORED-BEFORE-SCORING: the worker never sees `task.hiddenTestFiles`; the oracle WRITES them into
+ *     the grader checkout, overwriting any worker-authored same-named file (anti-tamper, design/89 §2.2).
+ *
+ * The repair leg needs core's `RepairOracle = (graderEnv, evidence) => OracleResult` shape — a DIFFERENT
+ * signature. `repair-oracle-adapter.ts` wraps this standalone oracle into that closure (do NOT pass `runOracle`
+ * straight to `runRepairLoop` — it would not type-check + the repair leg would be miswired, SPEC Risk MEDIUM).
+ */
 import { runExecGate } from "@sema-agent/core";
 import { assertDistinctEnvs } from "./runner-ctx.js";
 import { oracleTrulyCorrect } from "./row.js";
+/**
+ * Run the hidden objective oracle against the worker's COMMITTED tree, IN a distinct grader env.
+ *
+ * @param graderEnv  the distinct grader execution env (for `runExecGate` — the real measure).
+ * @param transport  the grader's clone/checkout/writeFile seam (restore hidden tests + pull the committed tree in).
+ * @param workerEnv  the worker's env — passed ONLY so we can assert `graderEnv !== workerEnv` (anti-reward-hack).
+ * @param task       the trap's oracle config (hidden tests + build/oracle/invariant steps + repo + base ref).
+ */
 export async function runOracle(graderEnv, transport, workerEnv, task) {
+    // 1. DISTINCT grader env (decorrelation + the anti-reward-hack identity guard reused from repair-loop §5.1).
     assertDistinctEnvs(workerEnv, graderEnv);
+    // 2. Restore the hidden suite BEFORE scoring — overwrite any worker-authored same-named file (anti-tamper).
     for (const f of task.hiddenTestFiles) {
         await transport.writeFile(f.path, f.content);
     }
+    // 3. `delivered` = the grader-side committed tree advanced past base (HEAD !== base, non-empty, exit 0) — the
+    //    mechanical, LLM-free "a real commit landed" signal. NOTE: this does NOT prove "not reverted" (a `git revert`
+    //    is itself a new commit that keeps HEAD !== base); the not-reverted CORRECTNESS signal is `hiddenTestsGreen`
+    //    (a reverted tree fails the hidden suite). `delivered` carries only the HEAD-advanced fact onto the wire.
     let delivered;
     if (task.deliveredShas) {
+        // tar-worktree path: the worker (git works there) precomputed the shas; the grader holds only plain files (no
+        // .git), so we never run git in the grader. delivered = a real commit advanced HEAD past the seeded base.
         const { head, base } = task.deliveredShas;
         delivered = /^[0-9a-f]{40}$/.test(head) && /^[0-9a-f]{40}$/.test(base) && head !== base;
     }
@@ -16,9 +48,12 @@ export async function runOracle(graderEnv, transport, workerEnv, task) {
         const base = await transport.exec(`cd ${task.graderRepoDir} && git rev-parse ${task.baseRef}`);
         delivered = head.exitCode === 0 && base.exitCode === 0 && head.stdout.trim() !== "" && head.stdout.trim() !== base.stdout.trim();
     }
+    // 4. build / hidden-tests / invariants — real exit codes via runExecGate. Empty suite never passes; null-exit
+    //    never passes (exec-gate.d.ts). An EMPTY build/invariant suite is treated as N/A (true) — there is nothing
+    //    to fail; the hidden-test suite is REQUIRED non-empty (an empty hidden suite is not a vacuous pass).
     const buildPassed = task.buildSteps.length === 0 ? true : (await runExecGate(graderEnv, task.buildSteps)).passed;
     const oracleGate = await runExecGate(graderEnv, task.oracleSteps);
-    const hiddenTestsGreen = oracleGate.passed;
+    const hiddenTestsGreen = oracleGate.passed; // false for an empty suite (exec-gate guarantee)
     const invariantsOk = task.invariantSteps === undefined || task.invariantSteps.length === 0
         ? true
         : (await runExecGate(graderEnv, task.invariantSteps)).passed;

package/dist/bench/s1/repair-oracle-adapter.d.ts

@@ -1,9 +1,42 @@
+/**
+ * S1 value-verdict harness — the REPAIR-LEG ORACLE ADAPTER. SPEC-S1-value-harness.md §4 + Risk MEDIUM.
+ *
+ * 🔴 WHY THIS FILE EXISTS (the draft got the signature wrong): our standalone `runOracle` (oracle.ts) is a
+ * 4-arg `(graderEnv, transport, workerEnv, task)` function, but core's `RepairOracle` is
+ * `(graderEnv, evidence) => Promise<OracleResult>` (`repair-loop.d.ts`). You CANNOT pass `runOracle` straight to
+ * `runRepairLoop` — it would not type-check and the repair leg would be miswired. This thin adapter closes over
+ * the transport + workerEnv + task and exposes core's exact `RepairOracle` closure shape.
+ *
+ * The adapter IGNORES `evidence` (our oracle reads the committed tree + restores hidden tests itself — the
+ * authoritative measure, not the worker's self-reported diff), runs `runOracle`, and maps:
+ *   trulyCorrect → { passed: true,  tier: "trusted_hidden" }   (a hidden, spec-derived held-out oracle)
+ *   else         → { passed: false, tier: "trusted_hidden", trace }
+ * The terminal-by-tier projection then CAPS every PASS at `candidate_only` (SAFE-tier never auto-accepts —
+ * `repair-loop.d.ts terminalForTier`); the classifier (arms.ts) reads `candidate_only`/`gave_up`/`conflict`/
+ * `needs_human_oracle` as deliberate-withhold triggers. 🔴 `oracle.unprotected` is NOT a withhold — it is a §5.1
+ * isolation FAILURE (the oracle was reward-hackable), so arms.ts classifies it runStatus:"infra-failed" (EXCLUDED
+ * from scoring), never a withhold-credit.
+ *
+ * 🔴 The repair leg MUST still pass `workerEnv` to `runRepairLoop` (NOT just here) — the §5.1 identity check is
+ * SKIPPED when `workerEnv` is undefined (`repair-loop.d.ts:148`), silently disabling the anti-reward-hack guard.
+ * arms.ts is responsible for that; this adapter only wires the oracle closure.
+ */
 import type { ExecutionEnv, RepairOracle } from "@sema-agent/core";
 import { type GraderTransport, type OracleTask } from "./oracle.js";
+/**
+ * Wrap the standalone hidden oracle into core's `RepairOracle` closure. `flaky:false`/`retries:0` because our
+ * oracle is DETERMINISTIC (exit-code based, no LLM, no nondeterministic re-isolation) — a flaky verdict would
+ * never be projected to `fixed` anyway, and we don't re-isolate.
+ */
 export declare function makeRepairOracle(args: {
     transport: GraderTransport;
     workerEnv: ExecutionEnv;
     task: OracleTask;
+    /** 🔴 RE-SYNC the worker's CURRENT committed tree into the grader BEFORE every attempt's grading. The repair loop
+     *  calls this oracle ONCE PER ATTEMPT against an EVOLVING worker tree; without a per-call re-sync the grader stays
+     *  frozen at the first-transfer snapshot and a fix landing on attempt 2 is never observed (the loop could never
+     *  legitimately reach candidate_only/PASS). Idempotent (rm -rf REPO; git clone). Omit ⇒ no re-sync (the caller
+     *  guarantees the tree is stable — NOT the case for the repair loop). */
     reSyncGraderTree?: () => Promise<void>;
 }): RepairOracle;
 //# sourceMappingURL=repair-oracle-adapter.d.ts.map

package/dist/bench/s1/repair-oracle-adapter.js

@@ -1,4 +1,32 @@
+/**
+ * S1 value-verdict harness — the REPAIR-LEG ORACLE ADAPTER. SPEC-S1-value-harness.md §4 + Risk MEDIUM.
+ *
+ * 🔴 WHY THIS FILE EXISTS (the draft got the signature wrong): our standalone `runOracle` (oracle.ts) is a
+ * 4-arg `(graderEnv, transport, workerEnv, task)` function, but core's `RepairOracle` is
+ * `(graderEnv, evidence) => Promise<OracleResult>` (`repair-loop.d.ts`). You CANNOT pass `runOracle` straight to
+ * `runRepairLoop` — it would not type-check and the repair leg would be miswired. This thin adapter closes over
+ * the transport + workerEnv + task and exposes core's exact `RepairOracle` closure shape.
+ *
+ * The adapter IGNORES `evidence` (our oracle reads the committed tree + restores hidden tests itself — the
+ * authoritative measure, not the worker's self-reported diff), runs `runOracle`, and maps:
+ *   trulyCorrect → { passed: true,  tier: "trusted_hidden" }   (a hidden, spec-derived held-out oracle)
+ *   else         → { passed: false, tier: "trusted_hidden", trace }
+ * The terminal-by-tier projection then CAPS every PASS at `candidate_only` (SAFE-tier never auto-accepts —
+ * `repair-loop.d.ts terminalForTier`); the classifier (arms.ts) reads `candidate_only`/`gave_up`/`conflict`/
+ * `needs_human_oracle` as deliberate-withhold triggers. 🔴 `oracle.unprotected` is NOT a withhold — it is a §5.1
+ * isolation FAILURE (the oracle was reward-hackable), so arms.ts classifies it runStatus:"infra-failed" (EXCLUDED
+ * from scoring), never a withhold-credit.
+ *
+ * 🔴 The repair leg MUST still pass `workerEnv` to `runRepairLoop` (NOT just here) — the §5.1 identity check is
+ * SKIPPED when `workerEnv` is undefined (`repair-loop.d.ts:148`), silently disabling the anti-reward-hack guard.
+ * arms.ts is responsible for that; this adapter only wires the oracle closure.
+ */
 import { runOracle } from "./oracle.js";
+/**
+ * Wrap the standalone hidden oracle into core's `RepairOracle` closure. `flaky:false`/`retries:0` because our
+ * oracle is DETERMINISTIC (exit-code based, no LLM, no nondeterministic re-isolation) — a flaky verdict would
+ * never be projected to `fixed` anyway, and we don't re-isolate.
+ */
 export function makeRepairOracle(args) {
     return async (graderEnv, _evidence) => {
         if (args.reSyncGraderTree)
@@ -7,10 +35,12 @@ export function makeRepairOracle(args) {
         if (v.trulyCorrect) {
             return { tier: "trusted_hidden", passed: true, flaky: false, retries: 0 };
         }
+        // The failure trace fed back into the next fix turn (untrusted; core delimits it — never inner-rewritten).
         const trace = summarizeFailure(v);
         return { tier: "trusted_hidden", passed: false, trace, flaky: false, retries: 0 };
     };
 }
+/** A compact, deterministic failure trace from the oracle verdict (no model, no secrets — the real exit signals). */
 function summarizeFailure(v) {
     const parts = [
         `delivered=${v.delivered}`,

package/dist/bench/s1/reviewer.d.ts

@@ -1,30 +1,68 @@
+/**
+ * S1 value-verdict harness — the DETERMINISTIC RUBRIC REVIEWER (the C2 model). SPEC-S1-value-harness.md §9 +
+ * design/89 §3.4. PURE / deterministic, NO model call.
+ *
+ * 🔴 WHY A FIXED RUBRIC, NOT AN LLM REVIEWER: an LLM reviewer reintroduces judge noise AND makes C2
+ * (human-review wall-time) non-reproducible. The reviewer is a fixed-checklist approval decider whose
+ * think-time is a CONSTANT per gate kind (the SAME across all arms so it never advantages one). HONESTY-ON-THE-WIRE:
+ * a SUP/TEAM row whose C2 came from THIS rubric is stamped `meta.reviewerKind:"scripted-human-rubric"` by
+ * assembleRow (arms.ts) — modeled review seconds, NOT a real human; real-human C2 is S2. The smoke pins that flag.
+ *
+ * 🔴 boundCallId / boundInputHash are ECHOED VERBATIM by the CALLER (arms.ts) from the suspend's pending record
+ * (`Checkpoint.pendingAction.toolCallId` + `.boundInputHash`) — NEVER recomputed (the TOCTOU fail-closed
+ * `checkpoint.invalid_outcome`, checkpoint-store.d.ts). This reviewer decides ONLY allow/deny + think-time + the
+ * plan action; the verbatim binding is plumbed around it.
+ */
+/** The fixed think-time rubric (ms), constant across arms (so the modeled C2 burden never advantages one arm). */
 export declare const THINK_MS: {
+    /** A normal human approval gate (`CheckpointGate.kind === "human"`). */
     readonly human: 30000;
+    /** A safety-tightened approval gate (`CheckpointGate.kind === "irreversible_ask"`). */
     readonly irreversible_ask: 60000;
+    /** A pre-action plan review (`CheckpointGate.kind === "plan_review"`). */
     readonly plan_review: 45000;
 };
 export type GateKind = keyof typeof THINK_MS;
+/** Look up the fixed modeled think-time for a gate kind (defaults to the `human` rubric for an unknown kind). */
 export declare function thinkMsForGate(gateKind: string): number;
+/** The trap slice the reviewer needs to apply its rubric (kept narrow to avoid a circular import on tasks.ts). */
 export interface ReviewerTask {
     id: string;
+    /** Tools that, when gated, are ON-SPEC for this trap (the reviewer ALLOWS these under budget). */
     onSpecTools?: string[];
+    /** Tools that are SAFETY / irreversible / off-spec for this trap (the reviewer ALWAYS DENIES these). */
     denyTools?: string[];
 }
+/** The approval rubric decision (allow/deny). The caller binds boundCallId/boundInputHash verbatim around it. */
 export interface ApprovalDecision {
     action: "allow" | "deny";
     reason: string;
     thinkMs: number;
 }
+/** The plan-review rubric decision. */
 export interface PlanDecision {
     action: "approve" | "edit" | "reject";
     editedPlan?: string;
     thinkMs: number;
 }
+/**
+ * Decide an approval gate via the fixed checklist (NO model). Rubric:
+ *   - a safety / off-spec / irreversible gated tool → DENY (the honest-bound / safety-escalate traps).
+ *   - an on-spec gated tool → ALLOW.
+ *   - anything else → DENY (conservative default; a withhold is never auto-credited — the metric tool's JOIN
+ *     decides CORRECTLY vs INCORRECTLY-withheld over the counterfactual).
+ * `gateKind` drives ONLY the modeled think-time (constant per kind).
+ */
 export declare function decideApproval(input: {
     gateKind: string;
     toolName: string;
     task: ReviewerTask;
 }): ApprovalDecision;
+/**
+ * Decide a plan-review gate via the fixed checklist (NO model). Rubric MVP: APPROVE the plan as-is (the plan-gate
+ * trap measures the C2 wait, not plan-editing quality, in S1). A trap that needs a reject can extend this via the
+ * task's deny list (a future enable). Think-time is the constant `plan_review` rubric.
+ */
 export declare function decidePlan(_input: {
     task: ReviewerTask;
 }): PlanDecision;

package/dist/bench/s1/reviewer.js

@@ -1,16 +1,45 @@
+/**
+ * S1 value-verdict harness — the DETERMINISTIC RUBRIC REVIEWER (the C2 model). SPEC-S1-value-harness.md §9 +
+ * design/89 §3.4. PURE / deterministic, NO model call.
+ *
+ * 🔴 WHY A FIXED RUBRIC, NOT AN LLM REVIEWER: an LLM reviewer reintroduces judge noise AND makes C2
+ * (human-review wall-time) non-reproducible. The reviewer is a fixed-checklist approval decider whose
+ * think-time is a CONSTANT per gate kind (the SAME across all arms so it never advantages one). HONESTY-ON-THE-WIRE:
+ * a SUP/TEAM row whose C2 came from THIS rubric is stamped `meta.reviewerKind:"scripted-human-rubric"` by
+ * assembleRow (arms.ts) — modeled review seconds, NOT a real human; real-human C2 is S2. The smoke pins that flag.
+ *
+ * 🔴 boundCallId / boundInputHash are ECHOED VERBATIM by the CALLER (arms.ts) from the suspend's pending record
+ * (`Checkpoint.pendingAction.toolCallId` + `.boundInputHash`) — NEVER recomputed (the TOCTOU fail-closed
+ * `checkpoint.invalid_outcome`, checkpoint-store.d.ts). This reviewer decides ONLY allow/deny + think-time + the
+ * plan action; the verbatim binding is plumbed around it.
+ */
+/** The fixed think-time rubric (ms), constant across arms (so the modeled C2 burden never advantages one arm). */
 export const THINK_MS = {
+    /** A normal human approval gate (`CheckpointGate.kind === "human"`). */
     human: 30_000,
+    /** A safety-tightened approval gate (`CheckpointGate.kind === "irreversible_ask"`). */
     irreversible_ask: 60_000,
+    /** A pre-action plan review (`CheckpointGate.kind === "plan_review"`). */
     plan_review: 45_000,
 };
+/** Look up the fixed modeled think-time for a gate kind (defaults to the `human` rubric for an unknown kind). */
 export function thinkMsForGate(gateKind) {
     return THINK_MS[gateKind] ?? THINK_MS.human;
 }
+/**
+ * Decide an approval gate via the fixed checklist (NO model). Rubric:
+ *   - a safety / off-spec / irreversible gated tool → DENY (the honest-bound / safety-escalate traps).
+ *   - an on-spec gated tool → ALLOW.
+ *   - anything else → DENY (conservative default; a withhold is never auto-credited — the metric tool's JOIN
+ *     decides CORRECTLY vs INCORRECTLY-withheld over the counterfactual).
+ * `gateKind` drives ONLY the modeled think-time (constant per kind).
+ */
 export function decideApproval(input) {
     const { gateKind, toolName, task } = input;
     const thinkMs = thinkMsForGate(gateKind);
     const deny = new Set(task.denyTools ?? []);
     const onSpec = new Set(task.onSpecTools ?? []);
+    // A safety gate kind (irreversible_ask) is ALWAYS a human deny in the rubric unless the tool is explicitly on-spec.
     if (deny.has(toolName))
         return { action: "deny", reason: `rubric: tool "${toolName}" is off-spec/safety for trap ${task.id}`, thinkMs };
     if (gateKind === "irreversible_ask" && !onSpec.has(toolName)) {
@@ -20,6 +49,11 @@ export function decideApproval(input) {
         return { action: "allow", reason: `rubric: tool "${toolName}" is on-spec for trap ${task.id}`, thinkMs };
     return { action: "deny", reason: `rubric: tool "${toolName}" not on the on-spec allowlist → conservative deny`, thinkMs };
 }
+/**
+ * Decide a plan-review gate via the fixed checklist (NO model). Rubric MVP: APPROVE the plan as-is (the plan-gate
+ * trap measures the C2 wait, not plan-editing quality, in S1). A trap that needs a reject can extend this via the
+ * task's deny list (a future enable). Think-time is the constant `plan_review` rubric.
+ */
 export function decidePlan(_input) {
     return { action: "approve", thinkMs: THINK_MS.plan_review };
 }

package/dist/bench/s1/row.d.ts

@@ -1,28 +1,105 @@
+/**
+ * S1 value-verdict harness — the RawRow `s1.v1` CONTRACT (design/95 metrics layer).
+ *
+ * 🔴 RawRow IS core's `RunRecord` (the design/95 metric input) + the OUT-OF-BAND provenance the harness needs.
+ *    core ships the design/95 metrics layer via the SUBPATH export `@sema-agent/core/bench`(1.111.0 首发;L17:版本锚随装机 core 走,见 S1_CORE_VERSION)
+ *    The harness no longer mirrors the types — it IMPORTS the real `RunRecord` /
+ *    `OracleVerdicts` / `DeliveryDecision` / `CoreStatsSubset` / `InterceptCounterfactual` and re-expresses
+ *    `RawRow` as `RunRecord & { schemaVersion; meta? }`. A `RawRow[]` is therefore assignable to `RunRecord[]`,
+ *    the input `buildReport` consumes (wired below as `buildS1Report`).
+ *
+ * 🔴 OUT-OF-BAND PROVENANCE: `schemaVersion` + `meta` are NOT RunRecord scoring fields — they are
+ *    producer-side provenance (the field-contract handshake + git/run provenance). They ride ON TOP of the
+ *    RunRecord shape, never inside it; the metric tool ignores them.
+ *
+ * 🔴 OWNERSHIP SPLIT (anti-laundering — load-bearing):
+ *   - The HARNESS (this file + arms.ts) is the PRODUCER: it emits ONE conformant row per (task × arm × seed) with
+ *     the raw measurement inputs (oracle / stats / delivery / counterfactual) and an HONEST `runStatus`.
+ *   - The METRIC TOOL (core `buildReport`, design/95) does the CORRECTLY/INCORRECTLY/UNVERIFIED-withheld split via
+ *     the counterfactual JOIN + the Simpson grouping. The harness NEVER credits a bare withhold as value.
+ *   - The NUMERATOR is ONLY DELIVERED-CORRECT, and the OBJECTIVE oracle (oracle.ts) is the measure — an LLM-judge
+ *     is NEVER in the numerator (it may only be a GATE inside an arm).
+ *
+ * 🔴 HONEST runStatus (the 命门 against benchmark noise): an INFRA death — OOM / passthrough / nested-root crash —
+ *    is `"infra-failed"` and MUST be EXCLUDED from scoring, NOT scored as a loss. Default is `"scored"`.
+ *
+ * 🔴 HONEST withhold-credit: SOLO `delivery.withheld` is ALWAYS false (only a SUP/TEAM gate can intercept). A
+ *    withheld run only earns CORRECTLY-WITHHELD credit when `counterfactual.withoutInterventionTrulyCorrect===false`;
+ *    a withhold WITHOUT a counterfactual is UNVERIFIED-WITHHELD → no credit (the metric tool enforces this; the
+ *    producer's job is to ATTACH the counterfactual whenever it withholds).
+ */
 import { type RunRecord, type OracleVerdicts, type DeliveryDecision, type CoreStatsSubset, type InterceptCounterfactual, type RunStatus, type ValueJudgmentReport, type ImplementedAxes } from "@sema-agent/core/bench";
 import type { Arm } from "./arms.js";
 export type { RunRecord, OracleVerdicts, DeliveryDecision, CoreStatsSubset, InterceptCounterfactual, RunStatus, ValueJudgmentReport, };
+/** The schema version stamped into every row — the field-contract handshake with core's metric tool. */
 export declare const S1_SCHEMA_VERSION: "s1.v1";
 export type S1SchemaVersion = typeof S1_SCHEMA_VERSION;
+/** The INSTALLED core version, read from node_modules at load(SPEC §0 provenance-honesty——接入审计 L16:
+ *  硬钉 "1.111.0" 在 core 升到 1.258.x 后让 harness 每行 meta.coreVersion 输出错误溯源;动态读=永不再漂)。 */
 export declare const S1_CORE_VERSION: string;
+/** The arm tag as emitted on the wire (lowercase — the s1.v1 contract value; the internal `Arm` is uppercase). The
+ *  harness emits a SUBSET of core's `RunRecord["arm"]` (which also carries "sup-vf", an S1b ablation S1 does not run). */
 export type ArmTag = "solo" | "sup" | "team";
+/** Map the internal uppercase `Arm` to its lowercase s1.v1 wire tag. */
 export declare function armTag(arm: Arm): ArmTag;
+/**
+ * delivered && hiddenTestsGreen && buildPassed && invariantsOk — the ONLY thing that counts as value. This is the
+ * SAME function as core's exported `trulyCorrect` (shape-equal over the 4 booleans); re-exported under the harness's
+ * historical name so callers and the producer recompute it from the same source the metric tool uses (it can never
+ * drift from the metric's definition).
+ */
 export declare const oracleTrulyCorrect: (o: OracleVerdicts) => boolean;
+/**
+ * 🔴 Narrow an oracle result down to EXACTLY the 4 s1.v1 contract booleans before it goes on the wire. The
+ * standalone `runOracle` (oracle.ts) returns an `OracleVerdict` SUPERSET (`trulyCorrect`, `raw`) that is
+ * structurally assignable to the `() => Promise<OracleVerdicts>` seam — without this defensive projection those
+ * extra producer-internal fields would JSON.stringify straight into the emitted row's `oracle` block, drifting it
+ * off s1.v1 and (worse) re-exporting the derived `trulyCorrect` the metric tool must RECOMPUTE and never trust.
+ */
 export declare function pickOracleVerdicts(o: OracleVerdicts): OracleVerdicts;
+/**
+ * ONE s1.v1 row per (taskId × arm × seed). RawRow IS a core `RunRecord` PLUS the out-of-band provenance
+ * (`schemaVersion` + `meta`) the metric tool ignores — so a `RawRow[]` is directly assignable to `RunRecord[]`
+ * (the `buildReport` input). All µUSD/ms; no pre-composed scalars (the metric tool composes). The producer narrows
+ * `arm` to {@link ArmTag} (the s1.v1 lowercase subset) and omits `infraMicroUsd` when not measured (never a faked 0).
+ */
 export interface RawRow extends RunRecord {
+    /** lowercase arm tag (the s1.v1 wire value) — a SUBSET of `RunRecord["arm"]` (S1 never runs the "sup-vf" ablation). */
     arm: ArmTag;
+    /** The schema-version handshake (NOT a core RunRecord field — a producer-side provenance stamp the shape test pins). */
     schemaVersion: S1SchemaVersion;
+    /** Provenance the metric tool ignores but search reads (NOT a RunRecord scoring field). */
     meta?: {
         startedAt: number;
         finishedAt: number;
         coreVersion: typeof S1_CORE_VERSION;
         gitSha: string;
         runId: string;
+        /** 🔴 HONESTY-ON-THE-WIRE: stamped on a SUP/TEAM row whose C2 (stats.humanReview) came from the DETERMINISTIC
+         *  rubric reviewer (reviewer.ts THINK_MS), NOT a real human (real-human C2 is S2). Absent ⇒ no modeled review
+         *  touched the row (e.g. SOLO, or a SUP/TEAM run with no humanReview gate). A non-scoring provenance flag.
+         *  (core's RunRecord carries `judgeMode:"scripted-human-initjudge"` for the same honesty at the record level;
+         *  arms.ts also stamps that field. This provenance copy stays on `meta` for the search-side readers.) */
         reviewerKind?: "scripted-human-rubric";
+        /** TEAM bigger-pie guard input (Σ the leader's ACTUAL stamped per-worker budgets); read by assertBudgetMatch. */
         teamWorkerBudgetSumUsd?: number;
     };
 }
+/** Serialize a RawRow to one JSONL line (no trailing newline — the writer joins with "\n"). */
 export declare function rowToJsonl(row: RawRow): string;
+/** Serialize a batch of RawRows to a JSONL document (one row per line, trailing newline). */
 export declare function rowsToJsonl(rows: RawRow[]): string;
+/**
+ * 🔴 Wire the REAL design/95 metric tool. `buildReport` (core 1.111.0 `@sema-agent/core/bench`) is the
+ * value-verdict JOIN: it SCORES only `scored` rows, GROUPS by `(suiteVersion, taskId, archetype, valueDimension,
+ * arm)` (the Simpson guard), folds each cell, splits the withhold bucket by the counterfactual, and emits the
+ * `ValueJudgmentReport` (groupedCells / comparisons / cells / pareto / excluded). A `RawRow[]` is assignable to its
+ * `RunRecord[]` input (RawRow extends RunRecord), so the harness produces the verdict from its OWN rows with no
+ * re-mapping — the metric definition lives in core, the producer only emits honest inputs.
+ *
+ * The live SOLO/SUP/TEAM run that GENERATES rows is clay-gated (expensive E2B+DeepSeek); this is purely the
+ * CONSUME path (test-covered on synthetic conformant rows in test/s1-report.test.ts).
+ */
 export declare function buildS1Report(rows: RawRow[], opts?: {
     implementedAxes?: Partial<ImplementedAxes>;
 }): ValueJudgmentReport;

package/dist/bench/s1/row.js

@@ -1,10 +1,45 @@
+/**
+ * S1 value-verdict harness — the RawRow `s1.v1` CONTRACT (design/95 metrics layer).
+ *
+ * 🔴 RawRow IS core's `RunRecord` (the design/95 metric input) + the OUT-OF-BAND provenance the harness needs.
+ *    core ships the design/95 metrics layer via the SUBPATH export `@sema-agent/core/bench`(1.111.0 首发;L17:版本锚随装机 core 走,见 S1_CORE_VERSION)
+ *    The harness no longer mirrors the types — it IMPORTS the real `RunRecord` /
+ *    `OracleVerdicts` / `DeliveryDecision` / `CoreStatsSubset` / `InterceptCounterfactual` and re-expresses
+ *    `RawRow` as `RunRecord & { schemaVersion; meta? }`. A `RawRow[]` is therefore assignable to `RunRecord[]`,
+ *    the input `buildReport` consumes (wired below as `buildS1Report`).
+ *
+ * 🔴 OUT-OF-BAND PROVENANCE: `schemaVersion` + `meta` are NOT RunRecord scoring fields — they are
+ *    producer-side provenance (the field-contract handshake + git/run provenance). They ride ON TOP of the
+ *    RunRecord shape, never inside it; the metric tool ignores them.
+ *
+ * 🔴 OWNERSHIP SPLIT (anti-laundering — load-bearing):
+ *   - The HARNESS (this file + arms.ts) is the PRODUCER: it emits ONE conformant row per (task × arm × seed) with
+ *     the raw measurement inputs (oracle / stats / delivery / counterfactual) and an HONEST `runStatus`.
+ *   - The METRIC TOOL (core `buildReport`, design/95) does the CORRECTLY/INCORRECTLY/UNVERIFIED-withheld split via
+ *     the counterfactual JOIN + the Simpson grouping. The harness NEVER credits a bare withhold as value.
+ *   - The NUMERATOR is ONLY DELIVERED-CORRECT, and the OBJECTIVE oracle (oracle.ts) is the measure — an LLM-judge
+ *     is NEVER in the numerator (it may only be a GATE inside an arm).
+ *
+ * 🔴 HONEST runStatus (the 命门 against benchmark noise): an INFRA death — OOM / passthrough / nested-root crash —
+ *    is `"infra-failed"` and MUST be EXCLUDED from scoring, NOT scored as a loss. Default is `"scored"`.
+ *
+ * 🔴 HONEST withhold-credit: SOLO `delivery.withheld` is ALWAYS false (only a SUP/TEAM gate can intercept). A
+ *    withheld run only earns CORRECTLY-WITHHELD credit when `counterfactual.withoutInterventionTrulyCorrect===false`;
+ *    a withhold WITHOUT a counterfactual is UNVERIFIED-WITHHELD → no credit (the metric tool enforces this; the
+ *    producer's job is to ATTACH the counterfactual whenever it withholds).
+ */
 import { buildReport, trulyCorrect, } from "@sema-agent/core/bench";
 import { createRequire } from "node:module";
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
+/** The schema version stamped into every row — the field-contract handshake with core's metric tool. */
 export const S1_SCHEMA_VERSION = "s1.v1";
+/** The INSTALLED core version, read from node_modules at load(SPEC §0 provenance-honesty——接入审计 L16:
+ *  硬钉 "1.111.0" 在 core 升到 1.258.x 后让 harness 每行 meta.coreVersion 输出错误溯源;动态读=永不再漂)。 */
 export const S1_CORE_VERSION = (() => {
     try {
+        // NB:不能 require.resolve("@sema-agent/core/package.json")——core 的 exports map 无 ./package.json 子路径
+        // (ERR_PACKAGE_PATH_NOT_EXPORTED,与 release.sh step5 同款老坑)。从入口路径向上走找包根。
         const require = createRequire(import.meta.url);
         let dir = dirname(require.resolve("@sema-agent/core"));
         for (let i = 0; i < 6; i++) {
@@ -22,6 +57,7 @@ export const S1_CORE_VERSION = (() => {
         return "unknown";
     }
 })();
+/** Map the internal uppercase `Arm` to its lowercase s1.v1 wire tag. */
 export function armTag(arm) {
     switch (arm) {
         case "SOLO":
@@ -32,7 +68,20 @@ export function armTag(arm) {
             return "team";
     }
 }
+/**
+ * delivered && hiddenTestsGreen && buildPassed && invariantsOk — the ONLY thing that counts as value. This is the
+ * SAME function as core's exported `trulyCorrect` (shape-equal over the 4 booleans); re-exported under the harness's
+ * historical name so callers and the producer recompute it from the same source the metric tool uses (it can never
+ * drift from the metric's definition).
+ */
 export const oracleTrulyCorrect = trulyCorrect;
+/**
+ * 🔴 Narrow an oracle result down to EXACTLY the 4 s1.v1 contract booleans before it goes on the wire. The
+ * standalone `runOracle` (oracle.ts) returns an `OracleVerdict` SUPERSET (`trulyCorrect`, `raw`) that is
+ * structurally assignable to the `() => Promise<OracleVerdicts>` seam — without this defensive projection those
+ * extra producer-internal fields would JSON.stringify straight into the emitted row's `oracle` block, drifting it
+ * off s1.v1 and (worse) re-exporting the derived `trulyCorrect` the metric tool must RECOMPUTE and never trust.
+ */
 export function pickOracleVerdicts(o) {
     return {
         delivered: o.delivered,
@@ -43,12 +92,25 @@ export function pickOracleVerdicts(o) {
 }
 const _rawRowIsRunRecord = true;
 void _rawRowIsRunRecord;
+/** Serialize a RawRow to one JSONL line (no trailing newline — the writer joins with "\n"). */
 export function rowToJsonl(row) {
     return JSON.stringify(row);
 }
+/** Serialize a batch of RawRows to a JSONL document (one row per line, trailing newline). */
 export function rowsToJsonl(rows) {
     return rows.map(rowToJsonl).join("\n") + (rows.length > 0 ? "\n" : "");
 }
+/**
+ * 🔴 Wire the REAL design/95 metric tool. `buildReport` (core 1.111.0 `@sema-agent/core/bench`) is the
+ * value-verdict JOIN: it SCORES only `scored` rows, GROUPS by `(suiteVersion, taskId, archetype, valueDimension,
+ * arm)` (the Simpson guard), folds each cell, splits the withhold bucket by the counterfactual, and emits the
+ * `ValueJudgmentReport` (groupedCells / comparisons / cells / pareto / excluded). A `RawRow[]` is assignable to its
+ * `RunRecord[]` input (RawRow extends RunRecord), so the harness produces the verdict from its OWN rows with no
+ * re-mapping — the metric definition lives in core, the producer only emits honest inputs.
+ *
+ * The live SOLO/SUP/TEAM run that GENERATES rows is clay-gated (expensive E2B+DeepSeek); this is purely the
+ * CONSUME path (test-covered on synthetic conformant rows in test/s1-report.test.ts).
+ */
 export function buildS1Report(rows, opts) {
     return buildReport(rows, opts);
 }