fix(deepagent-code): enforce WSL2 validation boundary

Author: deepagent-ai

packages/core/src/deepagent/failure-triage.ts

@@ -1,5 +1,5 @@
 import { analyzeErrors, type ErrorPattern } from "./diagnosis"
-import type { ValidationResult } from "./round-state"
+import type { ValidationFailureKind, ValidationResult } from "./round-state"
 
 /**
  * T2 (S1-v3.4): failure triage — the "fixability × progress" three-light classifier.
@@ -38,12 +38,14 @@ export type TriageResult = {
   readonly reason: string // human-readable; flows into needs_human body / fold label
 }
 
-// Exit codes that indicate the command/environment, not the code, failed.
-//  127 = command not found, 126 = not executable, 124 = timeout (GNU coreutils convention).
-const ENV_EXIT_CODES = new Set([124, 126, 127])
-// 128 + signal: 137 = SIGKILL (OOM), 139 = SIGSEGV, 134 = SIGABRT — when these come from the
-// toolchain itself they are environment crashes, not user-code assertions.
-const SIGNAL_EXIT_CODES = new Set([134, 137, 139])
+const ENV_FAILURE_KINDS = new Set<ValidationFailureKind>([
+  "shell_bootstrap_failed",
+  "unsupported_platform",
+  "unsupported_dialect",
+  "timeout",
+  "signal",
+  "output_unavailable",
+])
 
 // Output signatures of environment / dependency / network / resource problems (not fixable by editing code).
 const ENV_OUTPUT =
@@ -66,8 +68,8 @@ const dominantCategory = (patterns: ErrorPattern[]): string | null => {
   return [...patterns].sort((a, b) => b.count - a.count || a.category.localeCompare(b.category))[0]!.category
 }
 
-const hasEnvExitCode = (failed: readonly ValidationResult[]): number | undefined =>
-  failed.find((f) => ENV_EXIT_CODES.has(f.exit_code) || SIGNAL_EXIT_CODES.has(f.exit_code))?.exit_code
+const environmentFailure = (failed: readonly ValidationResult[]): ValidationResult | undefined =>
+  failed.find((result) => ENV_FAILURE_KINDS.has(result.kind))
 
 /**
  * Classify a failing round into a tier (+ yellow substate). Pure function; all signals are passed in.
@@ -80,12 +82,12 @@ export const classifyFailure = (input: TriageInput): TriageResult => {
   const combined = [...input.failed.map((f) => f.output), input.errorOutput ?? ""].join("\n")
 
   // ── 🔴 RED: not auto-fixable (any one hit → immediate exit, no budget burn) ──
-  const envExit = hasEnvExitCode(input.failed)
-  if (envExit !== undefined) {
+  const transportFailure = environmentFailure(input.failed)
+  if (transportFailure) {
     return {
       tier: "not_auto_fixable",
       category,
-      reason: `command/environment failure (exit ${envExit}) — not auto-fixable`,
+      reason: `validation runner failure (${transportFailure.kind}, exit ${transportFailure.exit_code}) — not auto-fixable`,
     }
   }
   if (ENV_OUTPUT.test(combined)) {

packages/core/src/deepagent/goal-loop.ts

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect"
+import type { ValidationResult } from "./round-state"
 import { randomUUID } from "node:crypto"
 import type { DocumentStore } from "./document-store"
 import {
@@ -153,7 +154,9 @@ export class InvalidGoalError extends Schema.TaggedErrorClass<InvalidGoalError>(
  */
 export type GraderPorts = {
   /** Run the given validation commands; `pass` iff ALL succeeded. */
-  readonly runTests: (commands: readonly string[]) => Effect.Effect<{ readonly pass: boolean }>
+  readonly runTests: (
+    commands: readonly string[],
+  ) => Effect.Effect<{ readonly pass: boolean; readonly results?: readonly ValidationResult[] }>
   /**
    * Highest diagnostic severity currently present, or null when there are none. `checked` MUST be false
    * when the port could not actually compute diagnostics (LSP crashed/timed out, no client covered the
@@ -197,7 +200,10 @@ const evaluateOne = (
   Effect.gen(function* () {
     switch (criterion.kind) {
       case "tests_pass": {
-        const { pass } = yield* ports.runTests(criterion.commands)
+        const { pass, results } = yield* ports.runTests(criterion.commands)
+        const runnerFailure = results?.find((result) => result.kind !== "command_exit")
+        if (runnerFailure)
+          return `tests_pass: validation runner failed (${runnerFailure.kind}) for [${runnerFailure.command}]`
         return pass ? null : `tests_pass: one or more of [${criterion.commands.join(", ")}] failed`
       }
       case "no_diagnostics": {

packages/core/src/deepagent/round-state.ts

@@ -1,12 +1,21 @@
 import type { ActivationStage, AgentMode, RoundDecision, RunPhase } from "./mode"
 
+export type ValidationFailureKind =
+  | "command_exit"
+  | "shell_bootstrap_failed"
+  | "unsupported_platform"
+  | "unsupported_dialect"
+  | "timeout"
+  | "signal"
+  | "output_unavailable"
+
 export type ValidationResult = {
   readonly command: string
   readonly passed: boolean
-  // T1 (S1-v3.4): the raw process exit code, carried through for failure triage.
-  // 127 = command not found, 126 = not executable, 124 = timeout, 137 = OOM/SIGKILL, etc.
-  // These are the green/red dividing signals classifyFailure() needs; `passed` is still
-  // exactly `exit_code === 0`, so existing assertions are unaffected.
+  // `kind` is authoritative. `exit_code` is the process code for command_exit and a diagnostic
+  // compatibility value for runner failures; classifiers must never infer transport failures from
+  // an exit code alone because user commands are allowed to return 124/126/127.
+  readonly kind: ValidationFailureKind
   readonly exit_code: number
   readonly output: string
   readonly duration_ms: number
@@ -92,7 +101,10 @@ const stageForDecision = (decision: RoundDecision, current: ActivationStage): Ac
 // on exit_code (not output text) for the same reason validationFingerprint is — output carries volatile
 // noise (durations/timestamps) that must not make identical evidence look distinct.
 const candidateEvidenceKey = (c: CandidateRef): string =>
-  `${c.round}|${c.status}|${[...c.validations].map((v) => `${v.command}=${v.exit_code}`).sort().join(",")}`
+  `${c.round}|${c.status}|${[...c.validations]
+    .map((v) => `${v.command}=${v.kind}:${v.exit_code}`)
+    .sort()
+    .join(",")}`
 
 export const addCandidate = (state: RoundState, candidate: CandidateRef): RoundState => {
   // STALE-REHARVEST DEDUPE (single append site; covers BOTH the request-prep path and the micro-round

packages/core/src/deepagent/validation.ts

@@ -1,18 +1,40 @@
-import type { ValidationResult } from "./round-state"
+import type { ValidationFailureKind, ValidationResult } from "./round-state"
+
+export type ValidationCommandSource = "package_script" | "builtin" | "agents_md" | "user"
+export type ValidationScriptDialect = "posix"
+
+export type ValidationCommand =
+  | {
+      readonly id: string
+      readonly source: ValidationCommandSource
+      readonly transport: "argv"
+      readonly executable: string
+      readonly args: readonly string[]
+      readonly display: string
+    }
+  | {
+      readonly id: string
+      readonly source: ValidationCommandSource
+      readonly transport: ValidationScriptDialect
+      readonly script: string
+      readonly display: string
+    }
+
+export type ValidationCommandInput = string | ValidationCommand
 
 export type ValidationPlan = {
-  readonly commands: readonly string[]
+  readonly commands: readonly ValidationCommand[]
   readonly timeout_ms: number
   readonly failFast: boolean
 }
 
 export type ValidationConfig = {
   readonly cwd: string
-  readonly commands: readonly string[]
+  readonly commands: readonly ValidationCommandInput[]
   readonly timeout_ms?: number
 }
 
-export const inferValidationCommands = (context: {
+export const inferValidationPlan = (context: {
   readonly cwd: string
   readonly packageJson?: { scripts?: Record<string, string> }
   readonly agentsMd?: string
@@ -21,40 +43,105 @@ export const inferValidationCommands = (context: {
   // The package-script runner for this workspace (e.g. "npm run", "bun run"). Defaults to npm.
   // P2-7: single inference impl; the deepagent-code production path passes "bun run".
   readonly runner?: string
-}): string[] => {
-  const commands: string[] = []
+}): ValidationCommand[] => {
+  const commands: ValidationCommand[] = []
   const run = context.runner ?? "npm run"
-  const runnerBin = run.split(/\s+/)[0] ?? "npm" // "bun"/"npm" for the bare typecheck fallback
+  const runner = run.trim().split(/\s+/).filter(Boolean)
+  const runnerBin = runner[0] ?? "npm"
+  const packageScript = (name: string): ValidationCommand => ({
+    id: `package:${name}`,
+    source: "package_script",
+    transport: "argv",
+    executable: runnerBin,
+    args: [...runner.slice(1), name],
+    display: `${run} ${name}`,
+  })
 
   if (context.packageJson?.scripts) {
     const scripts = context.packageJson.scripts
-    if (scripts.typecheck) commands.push(`${run} typecheck`)
-    else if (scripts["type-check"]) commands.push(`${run} type-check`)
-    else if (context.hasTypeScript) commands.push(runnerBin === "bun" ? "bun typecheck" : "npx tsc --noEmit")
+    if (scripts.typecheck) commands.push(packageScript("typecheck"))
+    else if (scripts["type-check"]) commands.push(packageScript("type-check"))
+    else if (context.hasTypeScript)
+      commands.push(
+        runnerBin === "bun"
+          ? {
+              id: "builtin:typecheck",
+              source: "builtin",
+              transport: "argv",
+              executable: "bun",
+              args: ["typecheck"],
+              display: "bun typecheck",
+            }
+          : {
+              id: "builtin:typecheck",
+              source: "builtin",
+              transport: "argv",
+              executable: "npx",
+              args: ["tsc", "--noEmit"],
+              display: "npx tsc --noEmit",
+            },
+      )
 
-    if (scripts.lint) commands.push(`${run} lint`)
+    if (scripts.lint) commands.push(packageScript("lint"))
     // P1-3: the test command is part of the micro-round validation gate — a failing test means
     // "not done". Only added when a test script actually exists (no blind test runs).
-    if (scripts.test) commands.push(`${run} test`)
-    if (scripts.build && !scripts.test) commands.push(`${run} build`)
+    if (scripts.test) commands.push(packageScript("test"))
+    if (scripts.build && !scripts.test) commands.push(packageScript("build"))
   } else if (context.hasTypeScript) {
-    commands.push("npx tsc --noEmit")
+    commands.push({
+      id: "builtin:typecheck",
+      source: "builtin",
+      transport: "argv",
+      executable: "npx",
+      args: ["tsc", "--noEmit"],
+      display: "npx tsc --noEmit",
+    })
   }
 
   if (context.hasPython) {
-    commands.push("python -m py_compile *.py")
+    commands.push({
+      id: "builtin:python-compile",
+      source: "builtin",
+      transport: "argv",
+      executable: "python",
+      args: ["-m", "compileall", "-q", "."],
+      display: "python -m compileall -q .",
+    })
   }
 
   if (context.agentsMd) {
     const inferredFromAgents = extractCommandsFromAgentsMd(context.agentsMd)
-    for (const cmd of inferredFromAgents) {
-      if (!commands.includes(cmd)) commands.push(cmd)
-    }
+    for (const cmd of inferredFromAgents)
+      if (!commands.some((item) => item.display === cmd))
+        commands.push({
+          id: `agents:${commands.length}`,
+          source: "agents_md",
+          transport: "posix",
+          script: cmd,
+          display: cmd,
+        })
   }
 
   return commands
 }
 
+export const inferValidationCommands = (context: Parameters<typeof inferValidationPlan>[0]): string[] =>
+  inferValidationPlan(context).map((command) => command.display)
+
+export const normalizeValidationCommand = (command: ValidationCommandInput): ValidationCommand =>
+  typeof command === "string"
+    ? {
+        id: `user:${command}`,
+        source: "user",
+        transport: "posix",
+        script: command,
+        display: command,
+      }
+    : command
+
+export const validationCommandDisplay = (command: ValidationCommandInput): string =>
+  normalizeValidationCommand(command).display
+
 // P2-7: the single AGENTS.md command extractor (was duplicated in workspace-context with a
 // drifting regex). Matches both "`cmd` - typecheck" list items and "run `cmd` to typecheck" prose.
 export const extractCommandsFromAgentsMd = (content: string): string[] => {
@@ -70,7 +157,10 @@ export const extractCommandsFromAgentsMd = (content: string): string[] => {
 }
 
 export const buildValidationPlan = (config: ValidationConfig): ValidationPlan => ({
-  commands: config.commands.length > 0 ? config.commands : ["echo 'no validation commands configured'"],
+  commands:
+    config.commands.length > 0
+      ? config.commands.map(normalizeValidationCommand)
+      : [normalizeValidationCommand("echo 'no validation commands configured'")],
   timeout_ms: config.timeout_ms ?? 60_000,
   failFast: true,
 })
@@ -80,9 +170,11 @@ export const parseValidationOutput = (
   exitCode: number,
   output: string,
   duration_ms: number,
+  kind: ValidationFailureKind = "command_exit",
 ): ValidationResult => ({
   command,
-  passed: exitCode === 0,
+  passed: kind === "command_exit" && exitCode === 0,
+  kind,
   exit_code: exitCode,
   output: output.slice(-4000),
   duration_ms,

packages/core/test/deepagent/failure-triage.test.ts

@@ -5,12 +5,12 @@ import type { ValidationResult } from "../../src/deepagent/round-state"
 // T2 (S1-v3.4): classifyFailure — fixability × progress, priority RED > YELLOW > GREEN.
 
 const vr = (over: Partial<ValidationResult> = {}): ValidationResult => ({
-  command: "tsc",
-  passed: false,
-  exit_code: 1,
-  output: "",
-  duration_ms: 1,
-  ...over,
+  command: over.command ?? "tsc",
+  passed: over.passed ?? false,
+  kind: over.kind ?? "command_exit",
+  exit_code: over.exit_code ?? 1,
+  output: over.output ?? "",
+  duration_ms: over.duration_ms ?? 1,
 })
 
 const base = {
@@ -25,16 +25,25 @@ const base = {
 
 describe("failure-triage.classifyFailure", () => {
   describe("🔴 not_auto_fixable (environment)", () => {
-    it("exit 127 (command not found) → red", () => {
-      const r = FailureTriage.classifyFailure({ ...base, failed: [vr({ exit_code: 127 })] })
+    it("typed shell bootstrap failure → red", () => {
+      const r = FailureTriage.classifyFailure({
+        ...base,
+        failed: [vr({ kind: "shell_bootstrap_failed", exit_code: -1 })],
+      })
       expect(r.tier).toBe("not_auto_fixable")
-      expect(r.reason).toMatch(/exit 127/)
+      expect(r.reason).toMatch(/shell_bootstrap_failed/)
     })
-    for (const code of [126, 124, 137, 139, 134]) {
-      it(`exit ${code} → red`, () => {
-        expect(FailureTriage.classifyFailure({ ...base, failed: [vr({ exit_code: code })] }).tier).toBe(
-          "not_auto_fixable",
-        )
+    it("a command that deliberately exits 127 is not red because of the number alone", () => {
+      const r = FailureTriage.classifyFailure({
+        ...base,
+        failed: [vr({ kind: "command_exit", exit_code: 127, output: "application-specific status" })],
+      })
+      expect(r.tier).not.toBe("not_auto_fixable")
+      expect(r.reason).not.toMatch(/exit 127/)
+    })
+    for (const kind of ["unsupported_platform", "unsupported_dialect", "timeout", "signal"] as const) {
+      it(`${kind} → red`, () => {
+        expect(FailureTriage.classifyFailure({ ...base, failed: [vr({ kind })] }).tier).toBe("not_auto_fixable")
       })
     }
     for (const sig of [
@@ -150,13 +159,14 @@ describe("failure-triage.classifyFailure", () => {
   })
 
   describe("priority", () => {
-    it("red beats yellow: env exit code wins even when stagnant", () => {
+    it("a command exit 127 does not beat yellow merely because it is 127", () => {
       const r = FailureTriage.classifyFailure({
         ...base,
         stagnant: true,
         failed: [vr({ exit_code: 127, output: "error TS2322: Type X is not assignable" })],
       })
-      expect(r.tier).toBe("not_auto_fixable")
+      expect(r.tier).toBe("needs_narrowing")
+      expect(r.substate).toBe("stall")
     })
     it("yellow beats green: stall on a fixable category is not green", () => {
       const r = FailureTriage.classifyFailure({