@xaccefy/pi-casefile 0.8.1 → 0.8.3

package/src/pipeline-submit.ts

@@ -18,7 +18,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { getRunDir, getScratchpadRoot, scratchpad_write } from "./scratchpad.ts";
 
@@ -204,19 +204,43 @@ function statePath(runId: string): string {
 function readState(runId: string): SubmitState {
   const p = statePath(runId);
   if (!existsSync(p)) return { repairs: {}, accepted_findings: [] };
-  try {
-    const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SubmitState>;
-    return {
-      repairs: raw.repairs ?? {},
-      accepted_findings: raw.accepted_findings ?? [],
-    };
-  } catch {
-    return { repairs: {}, accepted_findings: [] };
+  const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SubmitState>;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Corrupt pipeline-submit state for ${runId}: root must be an object`);
+  }
+  const repairs = raw.repairs ?? {};
+  if (typeof repairs !== "object" || repairs === null || Array.isArray(repairs)) {
+    throw new Error(`Corrupt pipeline-submit state for ${runId}: repairs must be an object`);
+  }
+  for (const [k, v] of Object.entries(repairs)) {
+    if (typeof k !== "string" || typeof v !== "number" || !Number.isInteger(v) || v < 0) {
+      throw new Error(`Corrupt pipeline-submit state for ${runId}: invalid repair counter`);
+    }
+  }
+  const accepted = raw.accepted_findings ?? [];
+  if (!Array.isArray(accepted)) {
+    throw new Error(
+      `Corrupt pipeline-submit state for ${runId}: accepted_findings must be an array`,
+    );
   }
+  for (const [i, item] of accepted.entries()) {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      throw new Error(
+        `Corrupt pipeline-submit state for ${runId}: accepted_findings[${i}] invalid`,
+      );
+    }
+  }
+  return {
+    repairs: repairs as Record<string, number>,
+    accepted_findings: accepted as FindingRef[],
+  };
 }
 
 function writeState(runId: string, state: SubmitState): void {
-  writeFileSync(statePath(runId), JSON.stringify(state, null, 2), "utf8");
+  const p = statePath(runId);
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
+  renameSync(tmp, p);
 }
 
 /** Project root containing the scratchpad (file-existence checks resolve here). */
@@ -272,6 +296,109 @@ function isNonEmptyString(v: unknown): v is string {
   return typeof v === "string" && v.trim().length > 0;
 }
 
+function requireStringArray(errors: string[], path: string, value: unknown, minItems = 0): void {
+  if (!Array.isArray(value)) {
+    errors.push(`${path}: missing or not an array`);
+    return;
+  }
+  if (value.length < minItems) errors.push(`${path}: needs at least ${minItems} item(s)`);
+  value.forEach((item, i) => {
+    if (!isNonEmptyString(item)) errors.push(`${path}[${i}]: missing or empty string`);
+  });
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function validateReport(errors: string[], obj: Record<string, unknown>): void {
+  const findingSeverities = ["info", "low", "medium", "high", "critical"];
+  if (Array.isArray(obj.findings)) {
+    obj.findings.forEach((item, i) => {
+      const finding = asObject(item);
+      if (!finding) {
+        errors.push(`findings[${i}]: not an object`);
+        return;
+      }
+      for (const field of ["id", "vuln_class", "severity", "status"] as const) {
+        if (!isNonEmptyString(finding[field]))
+          errors.push(`findings[${i}].${field}: missing or empty`);
+      }
+      if (!isNonEmptyString(finding.file) && !isNonEmptyString(finding.endpoint)) {
+        errors.push(`findings[${i}]: provide file or endpoint`);
+      }
+      if (isNonEmptyString(finding.severity) && !findingSeverities.includes(finding.severity)) {
+        errors.push(`findings[${i}].severity: invalid value`);
+      }
+      if (isNonEmptyString(finding.status) && !["confirmed", "reported"].includes(finding.status)) {
+        errors.push(`findings[${i}].status: invalid value`);
+      }
+      if (finding.chain_with !== undefined)
+        requireStringArray(errors, `findings[${i}].chain_with`, finding.chain_with);
+    });
+  }
+
+  const coverage = asObject(obj.coverage);
+  if (coverage) {
+    const allowed = ["COVERED", "SKIPPED", "NOT_FOUND", "INCOMPLETE"];
+    for (const [key, value] of Object.entries(coverage)) {
+      if (!/^[a-z-]+$/.test(key)) errors.push(`coverage.${key}: invalid class key`);
+      if (typeof value !== "string" || !allowed.includes(value)) {
+        errors.push(`coverage.${key}: must be one of { ${allowed.join(" | ")} }`);
+      }
+    }
+  }
+
+  if (obj.chains !== undefined) {
+    if (!Array.isArray(obj.chains)) {
+      errors.push("chains: not an array");
+    } else {
+      obj.chains.forEach((item, i) => {
+        const chain = asObject(item);
+        if (!chain) {
+          errors.push(`chains[${i}]: not an object`);
+          return;
+        }
+        if (chain.title !== undefined && !isNonEmptyString(chain.title))
+          errors.push(`chains[${i}].title: missing or empty`);
+        if (chain.steps !== undefined)
+          requireStringArray(errors, `chains[${i}].steps`, chain.steps);
+        if (
+          chain.severity !== undefined &&
+          (!isNonEmptyString(chain.severity) ||
+            !(CHAIN_SEVERITIES as readonly string[]).includes(chain.severity))
+        ) {
+          errors.push(`chains[${i}].severity: invalid value`);
+        }
+        if (chain.blocked_by_controls !== undefined) {
+          requireStringArray(errors, `chains[${i}].blocked_by_controls`, chain.blocked_by_controls);
+        }
+      });
+    }
+  }
+
+  if (obj.patches_applied !== undefined) {
+    if (!Array.isArray(obj.patches_applied)) {
+      errors.push("patches_applied: not an array");
+    } else {
+      obj.patches_applied.forEach((item, i) => {
+        const patch = asObject(item);
+        if (!patch) {
+          errors.push(`patches_applied[${i}]: not an object`);
+          return;
+        }
+        for (const field of ["finding_id", "diff_summary", "re_attack_result"] as const) {
+          if (patch[field] !== undefined && !isNonEmptyString(patch[field])) {
+            errors.push(`patches_applied[${i}].${field}: missing or empty`);
+          }
+        }
+      });
+    }
+  }
+}
+
 function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string[] {
   const spec = SPECS[stage];
   const errors: string[] = [];
@@ -334,10 +461,78 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
     }
   }
 
-  // Chain items have their own inner contract (≥2 steps, severity enum).
+  if (stage === "trace") {
+    requireStringArray(errors, "call_chain", obj.call_chain, 1);
+    if (Array.isArray(obj.defenses_checked)) {
+      obj.defenses_checked.forEach((item, i) => {
+        const defense = asObject(item);
+        if (!defense) {
+          errors.push(`defenses_checked[${i}]: not an object`);
+          return;
+        }
+        if (!isNonEmptyString(defense.defense))
+          errors.push(`defenses_checked[${i}].defense: missing or empty`);
+        if (!isNonEmptyString(defense.location))
+          errors.push(`defenses_checked[${i}].location: missing or empty`);
+        if (
+          !isNonEmptyString(defense.verdict) ||
+          !["bypassed", "blocked", "not-present"].includes(defense.verdict)
+        ) {
+          errors.push(`defenses_checked[${i}].verdict: must be bypassed, blocked, or not-present`);
+        }
+      });
+    }
+  }
+
+  if (stage === "skeptic") {
+    requireStringArray(errors, "evidence_reviewed", obj.evidence_reviewed, 1);
+    if (obj.verdict === "DISPROVEN" && isNonEmptyString(obj.disproval_reason)) {
+      const allowed = [
+        "unreachable",
+        "framework_protection",
+        "input_validation_blocks",
+        "requires_privilege_attacker_lacks",
+        "intended_behavior",
+        "overstated_impact",
+        "duplicate",
+        "test_artifact",
+        "out_of_scope",
+      ];
+      if (!allowed.includes(obj.disproval_reason)) errors.push("disproval_reason: invalid value");
+    }
+  }
+
+  if (stage === "validate") {
+    if (obj.status === "killed" && isNonEmptyString(obj.kill_reason)) {
+      const allowed = [
+        "unreachable",
+        "framework_protection",
+        "input_validation_blocks",
+        "requires_privilege_attacker_lacks",
+        "poc_failed_3x",
+        "no_real_impact",
+        "intended_behavior",
+        "duplicate",
+      ];
+      if (!allowed.includes(obj.kill_reason)) errors.push("kill_reason: invalid value");
+    }
+    if (
+      obj.refinement_attempts !== undefined &&
+      (!Number.isInteger(obj.refinement_attempts) ||
+        (obj.refinement_attempts as number) < 1 ||
+        (obj.refinement_attempts as number) > 3)
+    ) {
+      errors.push("refinement_attempts: must be an integer from 1 to 3");
+    }
+  }
+
   if (stage === "chain" && Array.isArray(obj.chains)) {
     obj.chains.forEach((c, i) => {
-      const chain = c as Record<string, unknown>;
+      const chain = asObject(c);
+      if (!chain) {
+        errors.push(`chains[${i}]: not an object`);
+        return;
+      }
       if (!isNonEmptyString(chain.title)) errors.push(`chains[${i}].title: missing or empty`);
       if (
         !isNonEmptyString(chain.severity) ||
@@ -345,14 +540,17 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
       ) {
         errors.push(`chains[${i}].severity: must be one of { ${CHAIN_SEVERITIES.join(" | ")} }`);
       }
-      if (!Array.isArray(chain.steps) || chain.steps.length < 2) {
-        errors.push(`chains[${i}].steps: needs at least 2 case IDs`);
+      requireStringArray(errors, `chains[${i}].steps`, chain.steps, 2);
+      if (chain.blocked_by_controls !== undefined) {
+        requireStringArray(errors, `chains[${i}].blocked_by_controls`, chain.blocked_by_controls);
       }
       if (!isNonEmptyString(chain.narrative))
         errors.push(`chains[${i}].narrative: missing or empty`);
     });
   }
 
+  if (stage === "report") validateReport(errors, obj);
+
   return errors;
 }
 

package/src/poc-runner.ts

@@ -1,5 +1,13 @@
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 
@@ -17,8 +25,53 @@ export type PocRun = {
    * a crash is NOT a verdict, and callers must not treat it as one.
    */
   completed: boolean;
+  /**
+   * Sanitized but UNTRUNCATED output (capped only by the spawn maxBuffer).
+   * Marker presence/absence checks MUST run on this, never on `output`,
+   * which is sliced for display — a cheating script can print its marker
+   * past the 4000-char display window. Never persisted to the ledger.
+   */
+  rawOutput?: string;
+  /** True when `output` was truncated for display (rawOutput has more). */
+  truncated?: boolean;
+  /** True iff child output capture was complete. False on maxBuffer/timeouts/spawn failures. */
+  outputComplete?: boolean;
+  /** Harness mode used for this run. */
+  mode?: string;
+  /** Harness target used for this run. */
+  target?: string;
+  /**
+   * True when the run never started because of harness infrastructure
+   * failure (e.g. sandbox image pull failed) — set only by the runner,
+   * never derived from PoC-controlled output text.
+   */
+  infraError?: boolean;
+};
+
+/**
+ * Run-mode options for `runPoc`. Host execution is NEVER selectable by the
+ * agent alone: `local: true` only takes effect when the OPERATOR has set
+ * `PI_POC_ALLOW_LOCAL=1` (host is a fallback when Docker is unavailable;
+ * `PI_POC_FORCE_LOCAL=1` + ALLOW skips Docker on purpose). The default is a
+ * Docker sandbox; `network: "host"` gives the sandbox host networking while
+ * keeping the read-only FS / dropped caps / unprivileged user / resource limits.
+ */
+export type PocRunOptions = {
+  /** Docker sandbox networking: "none" (default) or "host" (live/network-dependent findings). */
+  network?: "none" | "host";
+  /** True to run on the host (no Docker). Requires operator opt-in PI_POC_ALLOW_LOCAL=1. */
+  local?: boolean;
+  /**
+   * Extra environment variables merged into the run. The harness sets
+   * `PI_POC_MODE` ("poc" | "control" | "disconfirmation") and `PI_POC_TARGET`
+   * (the case target) so PoCs can be written once and parameterized per run.
+   */
+  env?: Record<string, string>;
 };
 
+/** Operator-only opt-in for host execution (never agent-supplied). */
+const LOCAL_EXEC_ENV = "PI_POC_ALLOW_LOCAL";
+
 export type PocLanguage = {
   /** Docker image used when running inside the sandbox. */
   image: string;
@@ -160,27 +213,57 @@ function validatePocPath(pocPath: string): string {
   }
 
   const root = getProjectRoot();
+  // Operator escape hatch: PI_POC_ALLOW_ABSOLUTE=1 disables BOTH the lexical
+  // and the realpath containment checks (agent cannot set it).
+  const allowAbsolute = process.env.PI_POC_ALLOW_ABSOLUTE === "1";
   // Use path.relative so prefix-sibling escapes like /tmp/proj vs /tmp/proj-evil are rejected.
   // startsWith(`${root}/`) would accept /tmp/proj-evil when root is /tmp/proj.
   const rel = relative(root, normalized);
   const outsideWorkspace = rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
-  if (outsideWorkspace) {
-    const allowAbsolute = process.env.PI_POC_ALLOW_ABSOLUTE === "1";
-    if (!allowAbsolute) {
-      throw new Error(
-        `PoC path must be under the project workspace (${root}). ` +
-          `Set PI_POC_ALLOW_ABSOLUTE=1 to allow arbitrary absolute paths.`,
-      );
-    }
+  if (outsideWorkspace && !allowAbsolute) {
+    throw new Error(
+      `PoC path must be under the project workspace (${root}). ` +
+        `Set PI_POC_ALLOW_ABSOLUTE=1 to allow arbitrary absolute paths.`,
+    );
   }
 
   if (!existsSync(normalized)) {
     throw new Error(`PoC not found on disk: ${pocPath}`);
   }
 
+  // Symlink containment: the lexical checks above are defeated by a
+  // workspace file that is a symlink to a host path (e.g. $HOME/.env) —
+  // existsSync/copyFileSync/readFileSync all dereference. Resolve the real
+  // path and re-run the containment check on it, then require a regular
+  // file (FIFOs/devices/sockets are rejected).
+  let real: string;
+  try {
+    real = realpathSync(normalized);
+  } catch {
+    throw new Error(`PoC path cannot be resolved: ${pocPath}`);
+  }
+  if (!allowAbsolute) {
+    const realRel = relative(root, real);
+    const realOutside = realRel === "" ? false : realRel.startsWith("..") || isAbsolute(realRel);
+    if (realOutside) {
+      throw new Error(
+        `PoC path resolves outside the project workspace (${real}). ` +
+          `Symlinked files outside ${root} are rejected.`,
+      );
+    }
+  }
+  const realStat = statSync(real);
+  if (!realStat.isFile()) {
+    throw new Error(`PoC path must resolve to a regular file (got ${pocPath})`);
+  }
+
   return normalized;
 }
 
+/**
+ * Strip control chars / ANSI escapes from PoC output. Does NOT slice —
+ * truncation is display-only and must never hide content from marker checks.
+ */
 function sanitizeOutput(output: string): string {
   // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional
   const nulls = /\x00/g;
@@ -194,8 +277,37 @@ function sanitizeOutput(output: string): string {
     .replace(/\r/g, "\n")
     .replace(nulls, "")
     .replace(ansi, "")
-    .replace(ctrl, "")
-    .slice(0, OUTPUT_MAX_CHARS);
+    .replace(ctrl, "");
+}
+
+/** Split sanitized output into the raw (whole) and display (sliced) halves. */
+function splitOutput(raw: string): { rawOutput: string; output: string; truncated: boolean } {
+  const truncated = raw.length > OUTPUT_MAX_CHARS;
+  return { rawOutput: raw, output: raw.slice(0, OUTPUT_MAX_CHARS), truncated };
+}
+
+function runProvenance(env?: Record<string, string>): Pick<PocRun, "mode" | "target"> {
+  return { mode: env?.PI_POC_MODE, target: env?.PI_POC_TARGET };
+}
+
+function outputWasComplete(result: { error?: Error; signal: string | null }): boolean {
+  return !result.error && result.signal === null;
+}
+
+/** Reject control characters in harness-supplied PoC env values. */
+function sanitizePocEnv(env: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      throw new Error(`Invalid PoC env key: ${key}`);
+    }
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional
+    if (/[\x00-\x1f\x7f]/.test(value)) {
+      throw new Error(`PoC env value for ${key} contains control characters`);
+    }
+    out[key] = value;
+  }
+  return out;
 }
 
 function buildDockerArgs(
@@ -203,14 +315,23 @@ function buildDockerArgs(
   command: string,
   workspaceDir: string,
   containerName: string,
+  network: "none" | "host",
+  env?: Record<string, string>,
 ): string[] {
+  const envArgs: string[] = [];
+  for (const [key, value] of Object.entries(sanitizePocEnv(env ?? {}))) {
+    // Values are single tokens from the harness (PI_POC_MODE / PI_POC_TARGET);
+    // pass them as separate -e args so no shell quoting is involved.
+    envArgs.push("-e", `${key}=${value}`);
+  }
   return [
     "run",
     "--rm",
     "--name",
     containerName,
     "--network",
-    "none",
+    network,
+    ...envArgs,
     "--read-only",
     "--cap-drop",
     "ALL",
@@ -290,7 +411,12 @@ function ensureImage(image: string): void {
   }
 }
 
-function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
+function runSandboxed(
+  pocPath: string,
+  language: PocLanguage,
+  network: "none" | "host" = "none",
+  env?: Record<string, string>,
+): PocRun {
   const ranAt = new Date().toISOString();
   const sourceName = basename(pocPath);
   const workspaceDir = mkdtempSync(resolve(tmpdir(), "poc-runner-"));
@@ -311,6 +437,9 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
         ranAt,
         sandbox: true,
         completed: false,
+        infraError: true,
+        outputComplete: false,
+        ...runProvenance(env),
       };
     }
     copyFileSync(pocPath, `${workspaceDir}/${sourceName}`);
@@ -326,7 +455,7 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
 
     const result = spawnSync(
       "docker",
-      buildDockerArgs(language.image, wrapped, workspaceDir, containerName),
+      buildDockerArgs(language.image, wrapped, workspaceDir, containerName, network, env),
       {
         encoding: "utf8",
         timeout: TIMEOUT_MS,
@@ -337,14 +466,18 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
     const spawnErr = result.error ? `\n[spawn error] ${result.error.message}` : "";
     const raw = (result.stdout ?? "") + (result.stderr ?? "") + spawnErr;
     const completed = raw.includes(sentinel);
-    const output = sanitizeOutput(raw.replace(sentinel, ""));
+    const { rawOutput, output, truncated } = splitOutput(sanitizeOutput(raw.replace(sentinel, "")));
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
       output,
+      rawOutput,
+      truncated,
       ranAt,
       sandbox: true,
       completed,
+      outputComplete: outputWasComplete(result),
+      ...runProvenance(env),
     };
   } finally {
     // Best-effort: remove any container still running after a timeout/kill.
@@ -361,7 +494,7 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
   }
 }
 
-function runLocal(pocPath: string, language: PocLanguage): PocRun {
+function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, string>): PocRun {
   const ranAt = new Date().toISOString();
 
   // The run template is `<interpreter> [flags...] {{file}}`. Split the static
@@ -378,6 +511,11 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
     encoding: "utf8",
     timeout: TIMEOUT_MS,
     maxBuffer: MAX_BUFFER,
+    // Host runs get the harness env contract merged over the operator env;
+    // the spawn env is explicitly provided so PI_POC_MODE / PI_POC_TARGET
+    // reach the script without leaking through a shell. Same control-char
+    // rejection as the sandboxed path.
+    env: env ? { ...process.env, ...sanitizePocEnv(env) } : undefined,
   });
 
   // Local runs stay shell-free (space-containing paths stay single args), so
@@ -386,14 +524,20 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
   // means the script never ran to completion — fail closed on those.
   const spawnErr = result.error ? `\n[spawn error] ${result.error.message}` : "";
   const completed = !result.error && result.signal === null;
-  const output = sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr);
+  const { rawOutput, output, truncated } = splitOutput(
+    sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr),
+  );
   return {
     path: pocPath,
     exitCode: spawnExitCode(result),
     output,
+    rawOutput,
+    truncated,
     ranAt,
     sandbox: false,
     completed,
+    outputComplete: outputWasComplete(result),
+    ...runProvenance(env),
   };
 }
 
@@ -408,17 +552,59 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
  *
  * Security:
  * - PoC paths must be absolute and under the project workspace by default.
- * - Docker sandbox runs with no network, read-only root FS, dropped caps,
- *   no new privileges, and an unprivileged user.
- * - Local execution is restricted to interpreted languages.
+ * - Docker sandbox runs with read-only root FS, dropped caps, no new
+ *   privileges, an unprivileged user, and resource limits. Networking is
+ *   `none` by default; `network: "host"` adds host networking for live
+ *   findings WITHOUT giving up the FS/cap/user isolation.
+ * - Host execution (local: true) is NOT agent-selectable: the default is a
+ *   host-network Docker sandbox. Bare host requires the operator's
+ *   `PI_POC_ALLOW_LOCAL=1` and is used only when Docker is unavailable
+ *   (or when `PI_POC_FORCE_LOCAL=1` is also set). Without ALLOW the run
+ *   fails closed if Docker cannot start.
+ *
+ * Back-compat: `runPoc(path, true)` == sandboxed, `runPoc(path, false)` ==
+ * `{ local: true }` (host-network sandbox; host if operator-gated).
  */
-export function runPoc(pocPath: string, useSandbox = true): PocRun {
+export function runPoc(pocPath: string, options?: PocRunOptions | boolean): PocRun {
   const normalized = validatePocPath(pocPath);
   const { language } = resolveLanguage(normalized);
 
-  if (useSandbox) {
-    return runSandboxed(normalized, language);
+  const opts: PocRunOptions =
+    typeof options === "boolean"
+      ? options
+        ? { network: "none" }
+        : { local: true }
+      : (options ?? {});
+
+  // Host execution is gated by the OPERATOR, never by an agent-supplied flag.
+  // `local: true` means "network access needed":
+  //   1. Prefer a host-network Docker sandbox (isolation retained).
+  //   2. Fall back to bare host ONLY when Docker/image is unavailable AND the
+  //      operator set PI_POC_ALLOW_LOCAL=1.
+  //   3. PI_POC_FORCE_LOCAL=1 + ALLOW lets the operator (or test harness)
+  //      skip Docker and run on the host deliberately — still never agent-only.
+  if (opts.local === true) {
+    const allowLocal = process.env[LOCAL_EXEC_ENV] === "1";
+    const forceLocal = process.env.PI_POC_FORCE_LOCAL === "1";
+    if (forceLocal && allowLocal) {
+      return runLocal(normalized, language, opts.env);
+    }
+    const sandboxed = runSandboxed(normalized, language, "host", opts.env);
+    if (!sandboxed.infraError) {
+      return sandboxed;
+    }
+    if (allowLocal) {
+      return runLocal(normalized, language, opts.env);
+    }
+    return {
+      ...sandboxed,
+      output:
+        sandboxed.output +
+        `\n[host execution blocked] local:true cannot run on the host without the operator's ` +
+        `${LOCAL_EXEC_ENV}=1 — an agent-supplied local flag alone cannot enable host execution. ` +
+        "Ask the operator to opt in, or use the default (isolated) sandbox if the PoC does not need network.",
+    };
   }
 
-  return runLocal(normalized, language);
+  return runSandboxed(normalized, language, opts.network ?? "none", opts.env);
 }