{"record":{"id":"e135feb0ee0ed0a3","repo":"JuliusBrussee/caveman","slug":"probe-returned-false","errorCode":null,"errorMessage":"probe returned false","messagePattern":"probe returned false","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/cli.ts","lineNumber":152,"sourceCode":"async function doctor(args: string[]): Promise<void> {\n  if (args.some((value) => value !== \"--json\")) {\n    throw new Error(\"usage: caveman-agent doctor [--json]\");\n  }\n  const json = args.includes(\"--json\");\n  const root = process.cwd();\n  const checks: DoctorCheck[] = [];\n  const node = process.versions.node;\n  checks.push(compareNodeVersion(node, \"22.19.0\") >= 0\n    ? { id: \"node\", status: \"pass\", detail: `Node ${node}` }\n    : {\n      id: \"node\",\n      status: \"fail\",\n      detail: `Node ${node}; framework requires >=22.19.0`,\n      fix: \"install Node 22.19 or newer\",\n    });\n\n  try {\n    if (!await verifySandboxConformance()) throw new Error(\"probe returned false\");\n    checks.push({ id: \"sandbox\", status: \"pass\", detail: \"tool sandbox containment probe passed\" });\n  } catch (error) {\n    checks.push({\n      id: \"sandbox\",\n      status: \"fail\",\n      detail: `tool sandbox containment unavailable: ${safeDiagnostic(error)}`,\n      fix: process.platform === \"win32\"\n        ? \"run sandbox-required agents in WSL2; native Windows host-mode agents work, but required containment stays fail-closed\"\n        : \"use supported Node runtime and OS; do not run production tools with sandbox fixture\",\n    });\n  }\n\n  // Missing engine and missing runtime are WARN, not FAIL: without them runs\n  // still reach a real model response in observe-only mode (no transform or\n  // gateway telemetry; provider usage and local context estimates remain). Only conditions that make even an\n  // observe-only run untrustworthy fail this command.\n  try {\n    const registry = await loadTransformRegistry();","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/cli.ts#L134-L170","documentation":"Inside doctor's sandbox check, verifySandboxConformance() (exported from runtime.ts:818) runs a containment probe against the tool sandbox and returned false rather than throwing — meaning the probe completed but the sandbox failed to contain it. Doctor wraps this in its own throw so the check is recorded as a failure with the platform-specific fix text (WSL2 on Windows, supported runtime/OS otherwise).","triggerScenarios":"Running `caveman-agent doctor` on a host where the tool sandbox fails containment: unsupported kernel/seccomp, sandbox fixture mode active in production, containers missing the required syscall surface (e.g. restricted gVisor/Firecracker microVMs), or macOS/Windows without the required sandbox facility.","commonSituations":"First-run diagnostics on a new dev machine or CI container; running inside `docker run` without adequate privileges; production deployment on a hardened runner where unprivileged user namespaces are disabled (sysctl kernel.unprivileged_userns_clone=0).","solutions":["Apply the fix doctor prints: on Windows use WSL2 for sandbox-required agents; elsewhere ensure a supported Node/OS combo and never run production tools with the sandbox fixture.","On Linux CI, enable unprivileged user namespaces and the seccomp surface the sandbox needs (or run the container with the runtime's recommended flags).","Re-run `caveman-agent doctor` to confirm the sandbox check flips to pass before attempting builds (build itself hard-fails with cave_sandbox_conformance_failed otherwise)."],"exampleFix":"# before: hardened runner, userns disabled\nsysctl kernel.unprivileged_userns_clone=0\n\n# after: enable unprivileged userns, re-probe\nsudo sysctl kernel.unprivileged_userns_clone=1\ncaveman-agent doctor","handlingStrategy":"try-catch","validationCode":"import { verifySandboxConformance } from \"@caveman/agent\";\nconst sandboxOk = await verifySandboxConformance();\nif (!sandboxOk) {\n  console.error(\"sandbox containment failed; fix host (userns/seccomp/WSL2) before proceeding\");\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await verifySandboxConformance();\n} catch (error) {\n  // doctor already wraps this into a structured check; in your own code treat\n  // false/throw as an environment blocker, not a transient failure\n  reportEnvironmentBlocker(\"sandbox\", error);\n}","preventionTips":["Run `caveman-agent doctor` as a CI preflight on every new runner image before any build job.","Keep unprivileged user namespaces enabled on Linux hosts and avoid stripped-down seccomp profiles.","On Windows, plan sandbox-required agents to run under WSL2 from the start."],"tags":["sandbox","doctor","environment","security"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}