@f-o-h/cli 0.1.10 → 0.1.11

package/README.md

@@ -4,7 +4,7 @@ AI-operator provisioning CLI for Front Of House.
 
 Public mirror: https://github.com/iiko38/front-of-house-cli
 
-Current published baseline: `@f-o-h/cli@0.1.10`
+Current published baseline: `@f-o-h/cli@0.1.11`
 
 This mirror is a generated release artifact. The private product monorepo is not
 published here, and no open-source license is granted unless stated separately.
@@ -104,11 +104,25 @@ foh eval external-agent run \
   --prompt-version blank-setup.v1
 ```
 
-The command writes a versioned prompt, launches an instrumented shell, captures
-FOH CLI commands into `commands.ndjson`, and finalizes `run.json` as an
-`external_agent_run.v1` artifact when the shell exits.
-
-## Local Scenario Suites
+The command writes a versioned prompt, launches an instrumented shell, captures
+FOH CLI commands into `commands.ndjson`, and finalizes `run.json` as an
+`external_agent_run.v1` artifact when the shell exits.
+
+For guarded programmable-runner planning:
+
+```bash
+foh eval external-agent execute \
+  --runner codex \
+  --batch test-results/external-agent-runs/<batch>/batch.json \
+  --dry-run \
+  --json
+```
+
+This writes `executor-plan.json`, creates intentionally empty clean workspaces
+outside the private repo, validates the local Codex binary/help flags, and
+prints exact `codex exec` commands without executing them.
+
+## Local Scenario Suites
 
 `foh test run --suite <file>` runs deterministic widget-runtime checks for a
 specific agent. The suite format supports reply text checks plus structured

package/dist/foh.js

@@ -6046,7 +6046,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve10.call(this, root, ref);
+      let _sch = resolve11.call(this, root, ref);
       if (_sch === void 0) {
         const schema2 = (_a2 = root.localRefs) === null || _a2 === void 0 ? void 0 : _a2[ref];
         const { schemaId } = this.opts;
@@ -6073,7 +6073,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve10(root, ref) {
+    function resolve11(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -6648,55 +6648,55 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve10(baseURI, relativeURI, options) {
+    function resolve11(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative, options, skipNormalization) {
+    function resolveComponent(base, relative2, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative = parse3(serialize(relative, options), options);
+        relative2 = parse3(serialize(relative2, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative.scheme) {
-        target.scheme = relative.scheme;
-        target.userinfo = relative.userinfo;
-        target.host = relative.host;
-        target.port = relative.port;
-        target.path = removeDotSegments(relative.path || "");
-        target.query = relative.query;
+      if (!options.tolerant && relative2.scheme) {
+        target.scheme = relative2.scheme;
+        target.userinfo = relative2.userinfo;
+        target.host = relative2.host;
+        target.port = relative2.port;
+        target.path = removeDotSegments(relative2.path || "");
+        target.query = relative2.query;
       } else {
-        if (relative.userinfo !== void 0 || relative.host !== void 0 || relative.port !== void 0) {
-          target.userinfo = relative.userinfo;
-          target.host = relative.host;
-          target.port = relative.port;
-          target.path = removeDotSegments(relative.path || "");
-          target.query = relative.query;
+        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
+          target.userinfo = relative2.userinfo;
+          target.host = relative2.host;
+          target.port = relative2.port;
+          target.path = removeDotSegments(relative2.path || "");
+          target.query = relative2.query;
         } else {
-          if (!relative.path) {
+          if (!relative2.path) {
             target.path = base.path;
-            if (relative.query !== void 0) {
-              target.query = relative.query;
+            if (relative2.query !== void 0) {
+              target.query = relative2.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative.path[0] === "/") {
-              target.path = removeDotSegments(relative.path);
+            if (relative2.path[0] === "/") {
+              target.path = removeDotSegments(relative2.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative.path;
+                target.path = "/" + relative2.path;
               } else if (!base.path) {
-                target.path = relative.path;
+                target.path = relative2.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative.query;
+            target.query = relative2.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -6704,7 +6704,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative.fragment;
+      target.fragment = relative2.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -6875,7 +6875,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve10,
+      resolve: resolve11,
       resolveComponent,
       equal,
       serialize,
@@ -10105,21 +10105,21 @@ async function promptLine(label, {
   allowEmpty = false,
   defaultValue
 } = {}) {
-  return await new Promise((resolve10) => {
+  return await new Promise((resolve11) => {
     const suffix = defaultValue ? ` [${defaultValue}]` : "";
     const rl = (0, import_readline.createInterface)({ input: process.stdin, output: process.stdout, terminal: true });
     rl.question(`${label}${suffix}: `, (answer) => {
       rl.close();
       const value = String(answer ?? "").trim();
       if (!value && typeof defaultValue === "string") {
-        resolve10(defaultValue);
+        resolve11(defaultValue);
         return;
       }
       if (!value && !allowEmpty) {
-        resolve10("");
+        resolve11("");
         return;
       }
-      resolve10(value);
+      resolve11(value);
     });
   });
 }
@@ -10127,7 +10127,7 @@ async function promptSecret(label) {
   if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== "function") {
     return await promptLine(label);
   }
-  return await new Promise((resolve10) => {
+  return await new Promise((resolve11) => {
     const stdin = process.stdin;
     const stdout = process.stdout;
     const wasRaw = Boolean(stdin.isRaw);
@@ -10141,7 +10141,7 @@ async function promptSecret(label) {
     const finish = () => {
       cleanup();
       stdout.write("\n");
-      resolve10(value);
+      resolve11(value);
     };
     const onData = (chunk) => {
       const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
@@ -10150,7 +10150,7 @@ async function promptSecret(label) {
           cleanup();
           process.exitCode = 130;
           stdout.write("\n");
-          return resolve10("");
+          return resolve11("");
         }
         if (char === "\r" || char === "\n") {
           finish();
@@ -10419,7 +10419,7 @@ async function storeAuthenticatedSession(params) {
   return output;
 }
 function sleep(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 async function runDeviceLogin(opts) {
   const jsonMode = Boolean(opts.json);
@@ -10957,7 +10957,7 @@ async function pollUntil(check2, opts) {
   }
 }
 function sleep2(ms) {
-  return new Promise((resolve10) => setTimeout(resolve10, ms));
+  return new Promise((resolve11) => setTimeout(resolve11, ms));
 }
 
 // src/commands/compliance.ts
@@ -13995,8 +13995,8 @@ function registerAgentGuardrailCommands(agent) {
     try {
       rule = JSON.parse(opts.rule);
     } catch {
-      const { readFileSync: readFileSync10 } = await import("fs");
-      rule = JSON.parse(readFileSync10(opts.rule, "utf-8"));
+      const { readFileSync: readFileSync11 } = await import("fs");
+      rule = JSON.parse(readFileSync11(opts.rule, "utf-8"));
     }
     const data = await apiFetch(`/v1/console/agents/${opts.agent}/guardrails`, {
       method: "POST",
@@ -14596,9 +14596,9 @@ function registerAgent(program3) {
       process.stdout.write(yaml);
       return;
     }
-    const { writeFileSync: writeFileSync7 } = await import("fs");
+    const { writeFileSync: writeFileSync8 } = await import("fs");
     const outputPath = opts.output ?? "tenant.yaml";
-    writeFileSync7(
+    writeFileSync8(
       outputPath,
       `# tenant.yaml - Front Of House agent manifest
 # Edit this file and run: foh plan tenant.yaml
@@ -16033,11 +16033,11 @@ function registerVoice(program3) {
     }
     const outputPath = String(opts.out || `foh-voice-preview-${provider}-${voiceId}.mp3`).trim();
     const audio = Buffer.from(await res.arrayBuffer());
-    const { mkdirSync: mkdirSync6, writeFileSync: writeFileSync7 } = await import("fs");
-    const { dirname: dirname5, resolve: resolve10 } = await import("path");
-    const absolutePath = resolve10(outputPath);
-    mkdirSync6(dirname5(absolutePath), { recursive: true });
-    writeFileSync7(absolutePath, audio);
+    const { mkdirSync: mkdirSync7, writeFileSync: writeFileSync8 } = await import("fs");
+    const { dirname: dirname5, resolve: resolve11 } = await import("path");
+    const absolutePath = resolve11(outputPath);
+    mkdirSync7(dirname5(absolutePath), { recursive: true });
+    writeFileSync8(absolutePath, audio);
     format({
       status: "ok",
       provider,
@@ -30518,7 +30518,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve10) => setTimeout(resolve10, pollInterval));
+        await new Promise((resolve11) => setTimeout(resolve11, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -30535,7 +30535,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve11, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -30613,7 +30613,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve10(parseResult.data);
+            resolve11(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -30874,12 +30874,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve10, reject) => {
+    return new Promise((resolve11, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve10, interval);
+      const timeoutId = setTimeout(resolve11, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -31979,7 +31979,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve10) => setTimeout(resolve10, pollInterval));
+      await new Promise((resolve11) => setTimeout(resolve11, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -32628,19 +32628,19 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve10) => {
+    return new Promise((resolve11) => {
       const json3 = serializeMessage(message);
       if (this._stdout.write(json3)) {
-        resolve10();
+        resolve11();
       } else {
-        this._stdout.once("drain", resolve10);
+        this._stdout.once("drain", resolve11);
       }
     });
   }
 };
 
 // src/lib/cli-version.ts
-var CLI_VERSION = "0.1.10";
+var CLI_VERSION = "0.1.11";
 
 // src/commands/mcp-serve.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -32825,7 +32825,7 @@ async function runFohCli(params) {
     effectiveArgv.push("--json");
   }
   const command = `foh ${effectiveArgv.join(" ")}`;
-  return await new Promise((resolve10) => {
+  return await new Promise((resolve11) => {
     const child = (0, import_node_child_process.spawn)(process.execPath, [cliEntry, ...effectiveArgv], {
       stdio: ["ignore", "pipe", "pipe"],
       env: {
@@ -32850,7 +32850,7 @@ async function runFohCli(params) {
     });
     child.once("error", (error2) => {
       clearTimeout(timeoutHandle);
-      resolve10({
+      resolve11({
         ok: false,
         command,
         argv: effectiveArgv,
@@ -32866,7 +32866,7 @@ async function runFohCli(params) {
       const stderrText = finalizeBoundedText(stderrBuffer);
       const exitCode = Number.isFinite(code ?? NaN) ? Number(code) : 1;
       const stdoutJson = tryParseJson(stdoutText);
-      resolve10({
+      resolve11({
         ok: !timedOut && exitCode === 0,
         command,
         argv: effectiveArgv,
@@ -34775,8 +34775,8 @@ function registerSetup(program3) {
         }
         try {
           const manifest = await agentExport(resolvedAgentId, { apiUrlOverride: opts.apiUrl });
-          const { writeFileSync: writeFileSync7 } = await import("fs");
-          writeFileSync7(
+          const { writeFileSync: writeFileSync8 } = await import("fs");
+          writeFileSync8(
             "tenant.yaml",
             `# tenant.yaml - Front Of House agent manifest
 # Edit this file and run: foh plan tenant.yaml
@@ -34944,8 +34944,8 @@ function registerSim(program3) {
       }
       const cert = response.certificate;
       if (opts.out) {
-        const { writeFileSync: writeFileSync7 } = await import("fs");
-        writeFileSync7(opts.out, JSON.stringify(cert, null, 2) + "\n", "utf-8");
+        const { writeFileSync: writeFileSync8 } = await import("fs");
+        writeFileSync8(opts.out, JSON.stringify(cert, null, 2) + "\n", "utf-8");
         process.stderr.write(`  Certificate written to ${opts.out}
 `);
       }
@@ -34995,8 +34995,8 @@ function registerSim(program3) {
         });
       }
       if (opts.out) {
-        const { writeFileSync: writeFileSync7 } = await import("fs");
-        writeFileSync7(opts.out, JSON.stringify(response.certificate, null, 2) + "\n", "utf-8");
+        const { writeFileSync: writeFileSync8 } = await import("fs");
+        writeFileSync8(opts.out, JSON.stringify(response.certificate, null, 2) + "\n", "utf-8");
         process.stderr.write(`  Final certificate written to ${opts.out}
 `);
       }
@@ -37710,7 +37710,7 @@ async function runSelf(args, apiUrlOverride) {
   if (apiUrlOverride && !spawnArgs.includes("--api-url")) {
     spawnArgs.push("--api-url", apiUrlOverride);
   }
-  return await new Promise((resolve10, reject) => {
+  return await new Promise((resolve11, reject) => {
     const child = (0, import_child_process2.spawn)(process.execPath, [process.argv[1], ...spawnArgs], {
       stdio: "inherit",
       env: {
@@ -37720,7 +37720,7 @@ async function runSelf(args, apiUrlOverride) {
       }
     });
     child.once("error", reject);
-    child.once("close", (code) => resolve10(typeof code === "number" ? code : 1));
+    child.once("close", (code) => resolve11(typeof code === "number" ? code : 1));
   });
 }
 function shouldUseInteractiveHome(argv) {
@@ -38098,17 +38098,17 @@ function detectUpdateAvailability(currentVersion, cwd = process.cwd()) {
 async function applyRepoUpdate(repoRoot) {
   const scriptPath = (0, import_path9.join)(repoRoot, "scripts", "Install-FohCli.ps1");
   if (process.platform === "win32") {
-    return await new Promise((resolve10, reject) => {
+    return await new Promise((resolve11, reject) => {
       const child = (0, import_child_process3.spawn)(
         "powershell",
         ["-ExecutionPolicy", "Bypass", "-File", scriptPath],
         { stdio: "inherit" }
       );
       child.once("error", reject);
-      child.once("close", (code) => resolve10(typeof code === "number" ? code : 1));
+      child.once("close", (code) => resolve11(typeof code === "number" ? code : 1));
     });
   }
-  return await new Promise((resolve10, reject) => {
+  return await new Promise((resolve11, reject) => {
     const child = (0, import_child_process3.spawn)(
       "corepack",
       ["pnpm", "cli:install:global"],
@@ -38118,7 +38118,7 @@ async function applyRepoUpdate(repoRoot) {
       }
     );
     child.once("error", reject);
-    child.once("close", (code) => resolve10(typeof code === "number" ? code : 1));
+    child.once("close", (code) => resolve11(typeof code === "number" ? code : 1));
   });
 }
 function shouldShowUpdateNotice(argv = process.argv) {
@@ -38254,9 +38254,9 @@ function registerUpdate(program3) {
 }
 
 // src/commands/eval.ts
-var import_fs13 = require("fs");
-var import_path11 = require("path");
-var import_child_process4 = require("child_process");
+var import_fs14 = require("fs");
+var import_path12 = require("path");
+var import_child_process5 = require("child_process");
 
 // src/lib/external-agent-capture.ts
 var import_fs12 = require("fs");
@@ -38307,6 +38307,284 @@ function readCommandRecords(runDir) {
   return (0, import_fs12.readFileSync)(commandLogPath, "utf8").split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
 }
 
+// src/lib/external-agent-executor.ts
+var import_fs13 = require("fs");
+var import_os2 = require("os");
+var import_path11 = require("path");
+var import_child_process4 = require("child_process");
+var CODEX_EXECUTOR_DENIED_ENV_PREFIXES = [
+  "SUPABASE_",
+  "DATABASE_",
+  "OPENAI_",
+  "XAI_",
+  "ANTHROPIC_",
+  "WHATSAPP_",
+  "TWILIO_",
+  "STRIPE_"
+];
+var CODEX_EXECUTOR_DENIED_ENV_NAMES = [
+  "DATABASE_URL",
+  "NPM_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "META_APP_SECRET",
+  "FACEBOOK_APP_SECRET",
+  "GOOGLE_CLIENT_SECRET",
+  "JWT_SECRET",
+  "SESSION_SECRET"
+];
+var CHILD_ENV_ALLOWLIST = [
+  "APPDATA",
+  "CODEX_HOME",
+  "ComSpec",
+  "HOME",
+  "LOCALAPPDATA",
+  "PATH",
+  "Path",
+  "SystemRoot",
+  "TEMP",
+  "TMP",
+  "USERPROFILE",
+  "WINDIR"
+];
+var ExternalAgentExecutorError = class extends Error {
+  reasonCode;
+  constructor(reasonCode, message) {
+    super(message);
+    this.name = "ExternalAgentExecutorError";
+    this.reasonCode = reasonCode;
+  }
+};
+function isDeniedEnvKey(key) {
+  const upper = key.toUpperCase();
+  if (CODEX_EXECUTOR_DENIED_ENV_NAMES.some((name) => upper === name)) return true;
+  return CODEX_EXECUTOR_DENIED_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix));
+}
+function buildCodexExecutorEnv(input) {
+  const source = input.sourceEnv ?? process.env;
+  const env = {};
+  for (const key of CHILD_ENV_ALLOWLIST) {
+    const value = source[key];
+    if (typeof value === "string" && value.length > 0 && !isDeniedEnvKey(key)) {
+      env[key] = value;
+    }
+  }
+  env[EXTERNAL_AGENT_RUN_DIR_ENV] = input.runDir;
+  env[EXTERNAL_AGENT_PROMPT_VERSION_ENV] = input.promptVersion;
+  env.FOH_CLI_SUPPRESS_BANNER = "1";
+  return env;
+}
+function normalizeForCompare(path2) {
+  const resolved = (0, import_path11.resolve)(path2);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function isPathInside(childPath, parentPath) {
+  const child = normalizeForCompare(childPath);
+  const parent = normalizeForCompare(parentPath);
+  const rel = (0, import_path11.relative)(parent, child);
+  return rel === "" || !!rel && !rel.startsWith("..") && !(0, import_path11.isAbsolute)(rel);
+}
+function requireString(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ExternalAgentExecutorError("invalid_external_agent_batch", `Batch field ${field} must be a non-empty string.`);
+  }
+  return value;
+}
+function readBatch(batchPath) {
+  if (!(0, import_fs13.existsSync)(batchPath)) {
+    throw new ExternalAgentExecutorError("external_agent_batch_not_found", `Batch file not found: ${batchPath}`);
+  }
+  const parsed = JSON.parse((0, import_fs13.readFileSync)(batchPath, "utf8"));
+  if (parsed.schema_version !== "external_agent_batch_plan.v1") {
+    throw new ExternalAgentExecutorError("invalid_external_agent_batch", "Batch schema_version must be external_agent_batch_plan.v1.");
+  }
+  if (!Array.isArray(parsed.runs) || parsed.runs.length === 0) {
+    throw new ExternalAgentExecutorError("invalid_external_agent_batch", "Batch runs must be a non-empty array.");
+  }
+  return parsed;
+}
+function defaultRunnerProbe(command, args) {
+  const result = process.platform === "win32" && command.toLowerCase().endsWith(".cmd") ? (0, import_child_process4.spawnSync)(
+    "powershell.exe",
+    ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", `& ${[command, ...args].map(quotePowerShellArg).join(" ")}`],
+    { encoding: "utf8" }
+  ) : (0, import_child_process4.spawnSync)(command, args, { encoding: "utf8" });
+  return {
+    status: typeof result.status === "number" ? result.status : null,
+    stdout: String(result.stdout || ""),
+    stderr: String(result.stderr || ""),
+    error: result.error
+  };
+}
+function quotePowerShellArg(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function resolveCodexProbeCommand() {
+  if (process.platform !== "win32") return "codex";
+  const appData = process.env.APPDATA;
+  if (appData) {
+    const appDataShim = (0, import_path11.join)(appData, "npm", "codex.cmd");
+    if ((0, import_fs13.existsSync)(appDataShim)) return appDataShim;
+  }
+  return "codex.cmd";
+}
+function validateCodexRunner(options) {
+  if (options.skipRunnerProbe) {
+    return { binaryChecked: false, requiredFlagsChecked: false };
+  }
+  const probe = options.runnerProbe ?? defaultRunnerProbe;
+  const probeCommand = resolveCodexProbeCommand();
+  const version2 = probe(probeCommand, ["--version"]);
+  if (version2.error || version2.status !== 0) {
+    throw new ExternalAgentExecutorError("external_agent_runner_binary_missing", "Codex runner probe failed: `codex --version` did not exit 0.");
+  }
+  const help = probe(probeCommand, ["exec", "--help"]);
+  if (help.error || help.status !== 0) {
+    throw new ExternalAgentExecutorError("external_agent_runner_help_unavailable", "Codex runner probe failed: `codex exec --help` did not exit 0.");
+  }
+  const helpText = `${help.stdout}
+${help.stderr}`;
+  const requiredFlags = [
+    "--cd",
+    "--skip-git-repo-check",
+    "--ephemeral",
+    "--ignore-rules",
+    "--sandbox",
+    "--full-auto",
+    "--json",
+    "--output-last-message"
+  ];
+  const missing = requiredFlags.filter((flag) => !helpText.includes(flag));
+  if (missing.length > 0) {
+    throw new ExternalAgentExecutorError(
+      "external_agent_runner_required_flags_missing",
+      `Codex runner is missing required exec flag(s): ${missing.join(", ")}`
+    );
+  }
+  return { binaryChecked: true, requiredFlagsChecked: true };
+}
+function safeRunId(value) {
+  return value.toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "run";
+}
+function resolveWorkspaceRoot(input) {
+  if (input.workspaceRoot) return (0, import_path11.resolve)(input.workspaceRoot);
+  const batchStem = (0, import_path11.basename)((0, import_path11.resolve)(input.batchPath)).replace(/[^a-zA-Z0-9_.-]+/g, "-");
+  const repoStem = (0, import_path11.basename)((0, import_path11.resolve)(input.privateRepoRoot)).replace(/[^a-zA-Z0-9_.-]+/g, "-");
+  return (0, import_path11.resolve)((0, import_os2.tmpdir)(), "foh-external-agent-workspaces", repoStem, batchStem);
+}
+function promptVersionFromPath(promptPath) {
+  const raw = (0, import_fs13.readFileSync)(promptPath, "utf8");
+  if (raw.includes("Do not assume access to the private source repository")) return "blank-setup.v1";
+  return "unknown";
+}
+function createExternalAgentExecutorPlan(options) {
+  const runner = String(options.runner || "codex");
+  if (runner !== "codex") {
+    throw new ExternalAgentExecutorError("unsupported_external_agent_runner", `Unsupported runner: ${runner}`);
+  }
+  const batchPath = (0, import_path11.resolve)(options.batchPath);
+  const batch = readBatch(batchPath);
+  const runnerProbe = validateCodexRunner(options);
+  const privateRepoRoot = (0, import_path11.resolve)(options.privateRepoRoot || options.cwd || process.cwd());
+  const workspaceRoot = resolveWorkspaceRoot({ batchPath, workspaceRoot: options.workspaceRoot, privateRepoRoot });
+  if (isPathInside(workspaceRoot, privateRepoRoot)) {
+    throw new ExternalAgentExecutorError(
+      "external_agent_workspace_inside_private_repo",
+      `Workspace root must be outside the private repository. workspace=${workspaceRoot} repo=${privateRepoRoot}`
+    );
+  }
+  (0, import_fs13.mkdirSync)(workspaceRoot, { recursive: true });
+  const batchDir = (0, import_path11.resolve)(String(batch.batch_dir || (0, import_path11.resolve)(batchPath, "..")));
+  const timeoutMinutes = Number.isFinite(options.timeoutMinutes) && Number(options.timeoutMinutes) > 0 ? Number(options.timeoutMinutes) : 30;
+  const runs = batch.runs.map((run) => {
+    const runId = safeRunId(requireString(run.run_id, "runs[].run_id"));
+    const runDir = (0, import_path11.resolve)(requireString(run.run_dir, `runs[${runId}].run_dir`));
+    const promptPath = (0, import_path11.resolve)(requireString(run.prompt_path, `runs[${runId}].prompt_path`));
+    const workspaceDir = (0, import_path11.join)(workspaceRoot, runId);
+    (0, import_fs13.mkdirSync)(workspaceDir, { recursive: true });
+    (0, import_fs13.writeFileSync)(
+      (0, import_path11.join)(workspaceDir, "README.md"),
+      [
+        "# FOH External-Agent Workspace",
+        "",
+        "This directory is intentionally empty.",
+        "Use only public FOH docs, public API docs, and the public npm CLI package.",
+        "Do not assume access to the private source repository.",
+        ""
+      ].join("\n"),
+      "utf8"
+    );
+    const env = buildCodexExecutorEnv({
+      sourceEnv: options.env,
+      runDir,
+      promptVersion: promptVersionFromPath(promptPath)
+    });
+    const jsonlPath = (0, import_path11.join)(runDir, "codex-exec.jsonl");
+    const lastMessagePath = (0, import_path11.join)(runDir, "codex-last-message.md");
+    const args = [
+      "exec",
+      "--cd",
+      workspaceDir,
+      "--skip-git-repo-check",
+      "--ephemeral",
+      "--ignore-rules",
+      "--ignore-user-config",
+      "--sandbox",
+      "workspace-write",
+      "--full-auto",
+      "--json",
+      "--output-last-message",
+      lastMessagePath,
+      "-"
+    ];
+    return {
+      run_id: runId,
+      model_provider: String(run.model_provider || "unknown"),
+      model_name: String(run.model_name || "unknown-model"),
+      run_dir: runDir,
+      prompt_path: promptPath,
+      workspace_dir: workspaceDir,
+      command: "codex",
+      args,
+      env_keys: Object.keys(env).sort(),
+      outputs: {
+        jsonl: jsonlPath,
+        last_message: lastMessagePath
+      }
+    };
+  });
+  return {
+    schema_version: "external_agent_executor_plan.v1",
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    runner,
+    mode: "dry_run",
+    batch_path: batchPath,
+    batch_dir: batchDir,
+    private_repo_root: privateRepoRoot,
+    workspace_root: workspaceRoot,
+    timeout_minutes: timeoutMinutes,
+    safety: {
+      workspace_outside_private_repo: true,
+      repo_files_copied: false,
+      child_env_mode: "allowlist",
+      denied_env_prefixes: [...CODEX_EXECUTOR_DENIED_ENV_PREFIXES],
+      denied_env_names: [...CODEX_EXECUTOR_DENIED_ENV_NAMES],
+      runner_probe: {
+        binary_checked: runnerProbe.binaryChecked,
+        required_flags_checked: runnerProbe.requiredFlagsChecked
+      }
+    },
+    runs
+  };
+}
+function writeExternalAgentExecutorPlan(plan) {
+  const path2 = (0, import_path11.join)(plan.batch_dir, "executor-plan.json");
+  (0, import_fs13.mkdirSync)(plan.batch_dir, { recursive: true });
+  (0, import_fs13.writeFileSync)(path2, `${JSON.stringify(plan, null, 2)}
+`, "utf8");
+  return path2;
+}
+
 // src/commands/eval.ts
 var DEFAULT_PROMPT_VERSION = "blank-setup.v1";
 var DEFAULT_BATCH_MODELS = "openai/codex,anthropic/claude,cursor/agent";
@@ -38326,13 +38604,13 @@ function defaultRunDir(modelName, promptVersion) {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").replace("T", "-").slice(0, 23);
   const safeModel = String(modelName || "unknown-model").toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
   const safePrompt = String(promptVersion || DEFAULT_PROMPT_VERSION).toLowerCase().replace(/[^a-z0-9_.-]+/g, "-");
-  return (0, import_path11.resolve)("test-results", "external-agent-runs", date4, `${safeModel}-${safePrompt}-${stamp}`);
+  return (0, import_path12.resolve)("test-results", "external-agent-runs", date4, `${safeModel}-${safePrompt}-${stamp}`);
 }
 function defaultBatchDir(promptVersion) {
   const date4 = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").replace("T", "-").slice(0, 23);
   const safePrompt = String(promptVersion || DEFAULT_PROMPT_VERSION).toLowerCase().replace(/[^a-z0-9_.-]+/g, "-");
-  return (0, import_path11.resolve)("test-results", "external-agent-runs", date4, `batch-${safePrompt}-${stamp}`);
+  return (0, import_path12.resolve)("test-results", "external-agent-runs", date4, `batch-${safePrompt}-${stamp}`);
 }
 function safeSlug(value) {
   return String(value || "unknown").toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
@@ -38360,14 +38638,14 @@ function inferShell(raw) {
 }
 function writePrompt(runDir, promptVersion) {
   const prompt = PROMPTS[promptVersion] ?? PROMPTS[DEFAULT_PROMPT_VERSION];
-  const path2 = (0, import_path11.join)(runDir, "prompt.txt");
-  (0, import_fs13.writeFileSync)(path2, `${prompt}
+  const path2 = (0, import_path12.join)(runDir, "prompt.txt");
+  (0, import_fs14.writeFileSync)(path2, `${prompt}
 `, "utf8");
   return path2;
 }
 function writeSession(runDir, session) {
-  const path2 = (0, import_path11.join)(runDir, "session.json");
-  (0, import_fs13.writeFileSync)(path2, `${JSON.stringify(session, null, 2)}
+  const path2 = (0, import_path12.join)(runDir, "session.json");
+  (0, import_fs14.writeFileSync)(path2, `${JSON.stringify(session, null, 2)}
 `, "utf8");
   return path2;
 }
@@ -38418,7 +38696,7 @@ function buildRunArtifact(input) {
     },
     summary: status === "pass" ? "External-agent capture session completed and was marked pass." : `External-agent capture session completed with ${commands.length} captured FOH command(s); classify and improve reason ${reasonCode}.`,
     next_commands: status === "pass" ? ["corepack pnpm eval:external-agent:runs:summary"] : [
-      `foh bug improve --from external-agent-run --file ${(0, import_path11.join)(input.runDir, "run.json")} --out ${(0, import_path11.join)(input.runDir, "improvement-packet.json")} --json`,
+      `foh bug improve --from external-agent-run --file ${(0, import_path12.join)(input.runDir, "run.json")} --out ${(0, import_path12.join)(input.runDir, "improvement-packet.json")} --json`,
       "corepack pnpm eval:external-agent:runs:summary"
     ]
   };
@@ -38428,13 +38706,13 @@ function registerEval(program3) {
   const external = evalCommand.command("external-agent").description("Capture clean external coding-agent setup attempts");
   external.command("batch").description("Create a deterministic multi-model external-agent batch plan").option("--models <list>", "Comma-separated provider/model list", DEFAULT_BATCH_MODELS).option("--prompt-version <version>", "Prompt version", DEFAULT_PROMPT_VERSION).option("--workspace-type <type>", "Workspace type label", "clean-no-repo").option("--agent-shell <name>", "Agent shell label", "vscode-terminal").option("--out-dir <path>", "Batch output directory").option("--json", "Output as JSON").action(async (opts) => {
     const promptVersion = String(opts.promptVersion || DEFAULT_PROMPT_VERSION);
-    const batchDir = (0, import_path11.resolve)(String(opts.outDir || defaultBatchDir(promptVersion)));
+    const batchDir = (0, import_path12.resolve)(String(opts.outDir || defaultBatchDir(promptVersion)));
     const models = parseModelList(String(opts.models || DEFAULT_BATCH_MODELS));
-    (0, import_fs13.mkdirSync)(batchDir, { recursive: true });
+    (0, import_fs14.mkdirSync)(batchDir, { recursive: true });
     const runs = models.map((model, index) => {
       const runId = `${String(index + 1).padStart(2, "0")}-${safeSlug(model.provider)}-${safeSlug(model.name)}`;
-      const runDir = (0, import_path11.join)(batchDir, runId);
-      (0, import_fs13.mkdirSync)(runDir, { recursive: true });
+      const runDir = (0, import_path12.join)(batchDir, runId);
+      (0, import_fs14.mkdirSync)(runDir, { recursive: true });
       const promptPath = writePrompt(runDir, promptVersion);
       const commandArgs = [
         "eval",
@@ -38475,8 +38753,8 @@ function registerEval(program3) {
       runs,
       summary_command: `corepack pnpm eval:external-agent:runs:summary -- --root ${batchDir}`
     };
-    const batchPath = (0, import_path11.join)(batchDir, "batch.json");
-    (0, import_fs13.writeFileSync)(batchPath, `${JSON.stringify(batch, null, 2)}
+    const batchPath = (0, import_path12.join)(batchDir, "batch.json");
+    (0, import_fs14.writeFileSync)(batchPath, `${JSON.stringify(batch, null, 2)}
 `, "utf8");
     format(cliEnvelope({
       schemaVersion: "external_agent_batch_plan_result.v1",
@@ -38496,8 +38774,8 @@ function registerEval(program3) {
   external.command("run").description("Launch an instrumented shell and emit external_agent_run.v1 when it exits").option("--model-provider <name>", "Model provider label", "unknown").option("--model-name <name>", "Model name label", "unknown-model").option("--prompt-version <version>", "Prompt version", DEFAULT_PROMPT_VERSION).option("--workspace-type <type>", "Workspace type label", "clean-no-repo").option("--agent-shell <name>", "Agent shell label", "vscode-terminal").option("--out-dir <path>", "Run output directory").option("--status <status>", "Final status when not interactively classified: pass|hold|fail", "hold").option("--reason-code <code>", "Failure/hold reason code", "external_agent_run_needs_review").option("--shell <command>", "Shell command to launch for capture").option("--no-shell", "Do not launch a shell; create/finalize artifacts immediately").option("--json", "Output as JSON").action(async (opts) => {
     const status = normalizeStatus(opts.status);
     const promptVersion = String(opts.promptVersion || DEFAULT_PROMPT_VERSION);
-    const runDir = (0, import_path11.resolve)(String(opts.outDir || defaultRunDir(opts.modelName, promptVersion)));
-    (0, import_fs13.mkdirSync)(runDir, { recursive: true });
+    const runDir = (0, import_path12.resolve)(String(opts.outDir || defaultRunDir(opts.modelName, promptVersion)));
+    (0, import_fs14.mkdirSync)(runDir, { recursive: true });
     const runId = runDir.split(/[\\/]/).filter(Boolean).slice(-1)[0];
     const promptPath = writePrompt(runDir, promptVersion);
     const shell = inferShell(opts.shell);
@@ -38519,7 +38797,7 @@ function registerEval(program3) {
       }
     };
     writeSession(runDir, session);
-    (0, import_fs13.writeFileSync)((0, import_path11.join)(runDir, "notes.md"), "# External Agent Run Notes\n\n", "utf8");
+    (0, import_fs14.writeFileSync)((0, import_path12.join)(runDir, "notes.md"), "# External Agent Run Notes\n\n", "utf8");
     let shellExitCode = null;
     if (opts.shell !== false) {
       process.stdout.write(`
@@ -38529,7 +38807,7 @@ Prompt: ${promptPath}
 Exit the shell to finalize run.json.
 
 `);
-      const result = (0, import_child_process4.spawnSync)(shell.command, shell.args, {
+      const result = (0, import_child_process5.spawnSync)(shell.command, shell.args, {
         stdio: "inherit",
         env: {
           ...process.env,
@@ -38541,8 +38819,8 @@ Exit the shell to finalize run.json.
       shellExitCode = typeof result.status === "number" ? result.status : null;
     }
     const artifact = buildRunArtifact({ runDir, session, status, reasonCode: opts.reasonCode, shellExitCode });
-    const runPath = (0, import_path11.join)(runDir, "run.json");
-    (0, import_fs13.writeFileSync)(runPath, `${JSON.stringify(artifact, null, 2)}
+    const runPath = (0, import_path12.join)(runDir, "run.json");
+    (0, import_fs14.writeFileSync)(runPath, `${JSON.stringify(artifact, null, 2)}
 `, "utf8");
     format(cliEnvelope({
       schemaVersion: "external_agent_capture_result.v1",
@@ -38552,12 +38830,68 @@ Exit the shell to finalize run.json.
       artifacts: {
         run: runPath,
         prompt: promptPath,
-        commands: (0, import_path11.join)(runDir, "commands.ndjson")
+        commands: (0, import_path12.join)(runDir, "commands.ndjson")
       },
       nextCommands: artifact.next_commands,
       extra: { run: artifact }
     }), { json: Boolean(opts.json) });
   });
+  external.command("execute").description("Create a guarded dry-run executor plan for programmable external-agent runners").requiredOption("--batch <path>", "Path to external_agent_batch_plan.v1 batch.json").option("--runner <runner>", "Runner implementation", "codex").option("--workspace-root <path>", "Clean executor workspace root; must be outside the private repo").option("--private-repo-root <path>", "Private repository root to guard against").option("--timeout-minutes <minutes>", "Per-run timeout planned for future execution", "30").option("--skip-runner-probe", "Skip local runner binary/help probing").option("--dry-run", "Write the executor plan without launching the runner", true).option("--json", "Output as JSON").action(async (opts) => {
+    if (opts.dryRun === false) {
+      format(cliEnvelope({
+        schemaVersion: "external_agent_executor_plan_result.v1",
+        status: "blocked",
+        reasonCode: "external_agent_executor_live_run_not_enabled",
+        summary: "Live external-agent execution is intentionally blocked until dry-run safety gates have passed.",
+        nextCommands: [
+          `foh eval external-agent execute --runner ${opts.runner || "codex"} --batch ${opts.batch} --dry-run --json`
+        ]
+      }), { json: Boolean(opts.json) });
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      const plan = createExternalAgentExecutorPlan({
+        batchPath: String(opts.batch),
+        runner: String(opts.runner || "codex"),
+        workspaceRoot: opts.workspaceRoot ? String(opts.workspaceRoot) : void 0,
+        privateRepoRoot: opts.privateRepoRoot ? String(opts.privateRepoRoot) : void 0,
+        timeoutMinutes: Number(opts.timeoutMinutes || 30),
+        skipRunnerProbe: Boolean(opts.skipRunnerProbe),
+        cwd: process.cwd()
+      });
+      const planPath = writeExternalAgentExecutorPlan(plan);
+      format(cliEnvelope({
+        schemaVersion: "external_agent_executor_plan_result.v1",
+        status: "exported",
+        reasonCode: "external_agent_executor_plan_created",
+        summary: `External-agent ${plan.runner} dry-run executor plan created for ${plan.runs.length} run(s).`,
+        artifacts: {
+          plan: planPath
+        },
+        nextCommands: [
+          "Review executor-plan.json for workspace/env isolation before enabling any live runner.",
+          ...plan.runs.map((run) => `${run.command} ${run.args.map(quoteArg).join(" ")} < ${quoteArg(run.prompt_path)} > ${quoteArg(run.outputs.jsonl)}`)
+        ],
+        extra: { plan }
+      }), { json: Boolean(opts.json) });
+    } catch (error2) {
+      if (error2 instanceof ExternalAgentExecutorError) {
+        format(cliEnvelope({
+          schemaVersion: "external_agent_executor_plan_result.v1",
+          status: "blocked",
+          reasonCode: error2.reasonCode,
+          summary: error2.message,
+          nextCommands: [
+            "Fix the executor plan input or workspace path and rerun with --dry-run."
+          ]
+        }), { json: Boolean(opts.json) });
+        process.exitCode = 1;
+        return;
+      }
+      throw error2;
+    }
+  });
 }
 
 // src/lib/banner.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f-o-h/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "FOH CLI - AI-operator provisioning tool for Front Of House",
   "license": "UNLICENSED",
   "bin": {