@indigoai-us/hq-cli 5.345.203 → 5.345.204

package/dist/lib/signals/steps/extract.js

@@ -49,8 +49,60 @@
  *   --ignore-user-config drops ~/.codex/config.toml (its MCP servers);
  *   --ignore-rules drops execpolicy allow rules. Codex has no turn cap flag;
  *   the per-item timeout is its only limit, and it reports no cost.
- *   grok: src/lib/bot/runtime/grok.ts has no restricted tool or sandbox
- *   mode, so the step refuses it.
+ *
+ * grok, checked 2026-11-05 against `grok --help` and the user guide grok
+ * 1.0.70 ships (its embedded 22-permissions-and-safety.md and 18-sandbox.md)
+ * on Shawon's Mac:
+ *   grok -p <prompt> --output-format streaming-json --cwd <turn dir>
+ *     --permission-mode dontAsk --tools read_file
+ *     --disallowed-tools search_tool,use_tool,run_terminal_cmd --disable-web-search
+ *     --no-subagents --max-turns <n> --sandbox hq_signals_extract
+ *     --allow "Read(<channel dir>/**)" --deny Bash
+ *     --deny MCPTool --deny WebFetch --deny WebSearch --deny Edit --deny Write
+ *     --deny Grep --deny "Read(~/.grok/**)"
+ *     --deny "Read(<turn home>/.grok/**)" --deny "Read(<real home>/.grok/**)"
+ *     --deny "Bash(ls)" --deny "Bash(cat)" ... (GROK_READ_ONLY_COMMANDS)
+ *   dontAsk denies every call no allow rule covers, but it still auto-approves
+ *   grok's own read-only tools and read-only shell list (ls, cat, head, git,
+ *   rg, ...), so those commands are denied by name (a Bash rule without `*`
+ *   is a prefix match). A `~` path in a rule is matched literally, before grok
+ *   expands `~`, so the login deny lists that spelling, the absolute isolated
+ *   home and the real home. The isolated auth.json stays readable by the grok
+ *   process itself (strict reads ~/.grok, and the process loads the login at
+ *   startup). Those Read denies are what keep it out of the model tool.
+ *   Grok gets only read_file; Bash and the terminal tool are disabled.
+ *   It returns candidate commands as JSON data. HQ validates the whole batch,
+ *   checks the pinned wrapper still matches the script it generated, then
+ *   executes that wrapper with fixed argv (never shell -c).
+ *   --disallowed-tools also drops the MCP bridge (search_tool, use_tool).
+ *   --sandbox names a profile the step writes to <turn dir>/.grok/sandbox.toml
+ *   for the turn: it extends grok's built-in `strict` (reads: cwd, system
+ *   paths, ~/.grok; writes: cwd, temp dirs, ~/.grok/sessions) with read-only
+ *   grants for bash's install prefix, core/scripts, the company's knowledge
+ *   preferences and the item's channel folder, and restrict_network = true.
+ *   The company's _candidates folders are not granted. The host writes them
+ *   after the turn, outside the sandbox. The profile is
+ *   kernel-enforced (Seatbelt on macOS, Landlock on Linux) for read_file and
+ *   every child process; grok refuses to start when it cannot be applied.
+ *   grok's own docs say child-process network blocking is Linux-only, so
+ *   extract does not select grok except on linux: it falls through to claude,
+ *   then codex. grok has no switch that skips user config: it always loads
+ *   ~/.grok/config.toml and the Claude-compatible permission rules in
+ *   ~/.claude/settings*.json. The turn therefore runs with HOME,
+ *   XDG_CONFIG_HOME, XDG_DATA_HOME and CLAUDE_CONFIG_DIR pointed at a fresh
+ *   isolated directory carrying only a private auth.json login copy, removed
+ *   when the turn ends, and with an env
+ *   allowlist instead of the parent process environment. GROK_SANDBOX,
+ *   GROK_SANDBOX_AUTO_ALLOW_BASH, GROK_CONFIG and GROK_CONFIG_PATH are not on
+ *   that allowlist, and the GROK_{CLAUDE,CURSOR}_*_ENABLED scans are off.
+ *   A refused command ends the grok turn (stopReason "cancelled") instead of
+ *   returning an error to the model. The `end` event carries num_turns and
+ *   total_cost_usd (cost may be absent; then 0, as for codex).
+ *   `grok --help` is probed once per grok binary path. A grok without every flag above
+ *   is never run: the step falls back to claude, then codex, when that tool
+ *   is installed and signed in, and otherwise fails the run naming the grok
+ *   version it needs. A main bot on grok with no grok installed falls back the
+ *   same way.
  */
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -61,6 +113,9 @@ import { splitFrontmatter } from "../../hot-channels/signals-pass.js";
 import { audienceKey } from "../../hot-channels/audience.js";
 import { readBotConfig, effectiveBotKind, isBotRuntimeId } from "../../bot/config.js";
 import { botsRoot } from "../../bot/paths.js";
+import { parseClaudeAuthStatus } from "../../bot/runtime/claude.js";
+import { parseCodexLoginStatus } from "../../bot/runtime/codex.js";
+import { SIGN_IN_CHECK_TIMEOUT_MS } from "../../bot/runtime-sign-in.js";
 import { CLAUDE_LOGGED_OUT_RE, CLAUDE_ISOLATION_ARGS, parseClaudeSignals } from "../../hot-channels/signals-pass.js";
 import { assertAllowedPath, assertNoEscapingLinks, guardedRemove, guardedWrite, realRelPath } from "../write-guard.js";
 export const EXTRACT_SIGNAL_TYPES = [
@@ -88,6 +143,40 @@ export function worklistTimeoutMs(limit) {
 }
 export const CODEX_PERMISSION_PROFILE = "hq_signals_extract";
 export const CANDIDATE_WRAPPER_NAME = "write-candidate.sh";
+/** The sandbox profile the step writes to <turn dir>/.grok/sandbox.toml for a grok turn. */
+export const GROK_SANDBOX_PROFILE = "hq_signals_extract";
+export const GROK_SANDBOX_FILE = path.join(".grok", "sandbox.toml");
+/** The oldest grok whose `--help` lists every flag in GROK_EXTRACT_FLAGS. */
+export const GROK_MIN_VERSION = "1.0.70";
+/** Flags a grok turn needs; one missing from `--help` means the installed grok cannot be locked down. */
+export const GROK_EXTRACT_FLAGS = [
+    "--permission-mode",
+    "--tools",
+    "--disallowed-tools",
+    "--allow",
+    "--deny",
+    "--sandbox",
+    "--disable-web-search",
+    "--no-subagents",
+    "--max-turns",
+    "--cwd",
+    "--output-format",
+];
+/**
+ * grok's built-in read-only shell list (its permissions guide, "Read-Only
+ * Shell Commands"): auto-approved even under dontAsk, so each is denied by
+ * name. A Bash rule without `*` is a prefix match, so `Bash(cat)` also covers
+ * `cat` with any arguments.
+ */
+export const GROK_READ_ONLY_COMMANDS = [
+    "ls", "cat", "pwd", "date", "whoami", "hostname", "uptime", "ps",
+    "head", "tail", "wc", "sort", "uniq", "tr", "cut",
+    "mkdir", "touch", "git", "grep", "rg", "kubectl",
+];
+/** Environment keys that could widen or relocate a grok turn's configuration. */
+const GROK_ENV_DROP = ["GROK_SANDBOX", "GROK_SANDBOX_AUTO_ALLOW_BASH", "GROK_CONFIG", "GROK_CONFIG_PATH"];
+/** The Claude and Cursor configuration scans grok runs at start, turned off for a turn. */
+const GROK_COMPAT_SCANS = ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS"].flatMap((s) => [`GROK_CLAUDE_${s}_ENABLED`, `GROK_CURSOR_${s}_ENABLED`]);
 /** The only tools a claude turn may use: Read inside the channel folder and the pinned wrapper. */
 export function claudeAllowedTools(channelDir, wrapperPath) {
     // A rule path that starts with `//` is absolute.
@@ -217,14 +306,21 @@ export function buildExtractPrompt(input) {
         "Rules:",
         input.runtime === "codex"
             ? "- Read the item with a shell command such as cat. Only files in the item's channel folder are readable."
-            : "- Read the item with the Read tool. Only files in the item's channel folder are readable.",
+            : input.runtime === "grok"
+                ? "- Read the item with the read_file tool. Only files in the item's channel folder are readable."
+                : "- Read the item with the Read tool. Only files in the item's channel folder are readable.",
         `- Write candidates ONLY with: bash ${input.wrapperPath} --kind signal|entity --type <type> --body "<text>"`,
         "- That command already fixes the company, audience and source ref for this item. Do not pass --company, --audience, --source-ref or --body-file; it refuses them.",
+        ...(input.runtime === "grok"
+            ? ['- You have no terminal tool. Return JSON only: {"commands":["bash ..."]}. HQ executes validated commands after your turn. At most 8 commands; use an empty array for no candidates.', "- Use exactly the flags above in that order; quote the body as a literal. No pipes, no &&, no ;, no substitutions, redirections or other commands outside quoted text."]
+            : []),
         `- Signal types (exactly these): ${EXTRACT_SIGNAL_TYPES.join(", ")}.`,
         `- Entity types: ${ENTITY_TYPES.join(", ")}.`,
         "- Every signal body must end with a citation: a one-sentence quote from the item or its timestamp, for example: (cite: \"we ship Friday\") or (cite: 00:12:31).",
         "- No other command can run, and no other file can be written.",
-        "- When finished, reply with one line: the number of candidates written.",
+        input.runtime === "grok"
+            ? '- Return only the JSON commands object, without markdown fences. This overrides the skill instructions about executing commands.'
+            : "- When finished, reply with one line: the number of candidates written.",
         "",
         ...(input.priorSignals?.length ? [
             "Already extracted for this source; do not repeat; return `update: <id>` to amend one",
@@ -290,11 +386,22 @@ export function buildCandidateWrapper(input) {
         "",
     ].join("\n");
 }
-/** Parse a stream-json transcript (or a codex --json event stream). */
+/**
+ * Parse a stream-json transcript (claude), a codex --json event stream, or a
+ * grok streaming-json event stream.
+ *
+ * grok writes `{"type":"text","data":…}` deltas and one terminal
+ * `{"type":"end","stopReason":…,"num_turns":n,"total_cost_usd":x}`; a refused
+ * tool call ends the turn with stopReason "cancelled", and an API failure is
+ * `{"type":"error","message":…}`. Both are mapped to an error result so the
+ * item fails and is retried; only "end_turn" is success.
+ */
 export function parseTurnOutput(stdout) {
     let result = null;
     let codexTurns = 0;
     let codexDone = false;
+    let grokText = "";
+    let grokError;
     for (const line of stdout.split("\n")) {
         const t = line.trim();
         if (!t.startsWith("{"))
@@ -317,6 +424,25 @@ export function parseTurnOutput(stdout) {
         }
         if (o.type === "turn.failed")
             codexTurns += 1;
+        if (o.type === "text" && typeof o.data === "string")
+            grokText += o.data;
+        if (o.type === "error" && typeof o.message === "string")
+            grokError = o.message;
+        if (o.type === "end") {
+            const stop = typeof o.stopReason === "string" ? o.stopReason : "";
+            const ok = /^end_?turn$/i.test(stop);
+            result = {
+                type: "result",
+                subtype: ok ? "success" : stop || "no stop reason",
+                is_error: !ok,
+                result: ok ? grokText : `grok stopped: ${stop || "no stop reason"}`,
+                ...(typeof o.num_turns === "number" ? { num_turns: o.num_turns } : {}),
+                ...(typeof o.total_cost_usd === "number" ? { total_cost_usd: o.total_cost_usd } : {}),
+            };
+        }
+    }
+    if (!result && grokError !== undefined) {
+        result = { type: "result", subtype: "error", is_error: true, result: grokError };
     }
     if (result) {
         const turns = typeof result.num_turns === "number" ? result.num_turns : 1;
@@ -564,24 +690,315 @@ function toolPrefixRoots(bins, envPath, hqRoot) {
     }
     return [...new Set(roots)];
 }
-/** TOML inline table for the codex permission profile's filesystem entries. */
-export function codexFilesystemProfile(scope, codexBin, envPath) {
-    const entries = [[":minimal", "read"]];
-    for (const r of toolPrefixRoots([codexBin, "bash"], envPath, scope.hqRoot))
-        entries.push([r, "read"]);
-    entries.push([scope.turnDir, "read"]);
-    entries.push([path.join(fs.realpathSync(scope.hqRoot), "core", "scripts"), "read"]);
-    const prefs = path.join(fs.realpathSync(scope.hqRoot), "companies", scope.company, "settings", "knowledge");
+/**
+ * The HQ paths a sandboxed turn may touch, beyond the turn dir and the tool
+ * install prefixes: core/scripts and the knowledge preferences the candidate
+ * script reads, the item's channel folder, and the company's _candidates
+ * folders it writes.
+ */
+function hqTurnGrants(scope) {
+    const hq = fs.realpathSync(scope.hqRoot);
+    const entries = [[path.join(hq, "core", "scripts"), "read"]];
+    const prefs = path.join(hq, "companies", scope.company, "settings", "knowledge");
     if (fs.existsSync(prefs))
         entries.push([prefs, "read"]);
-    const personalPrefs = path.join(fs.realpathSync(scope.hqRoot), "personal", "settings", "knowledge-preferences.yaml");
+    const personalPrefs = path.join(hq, "personal", "settings", "knowledge-preferences.yaml");
     if (fs.existsSync(personalPrefs))
         entries.push([personalPrefs, "read"]);
     entries.push([scope.channelDir, "read"]);
     for (const d of scope.candidateDirs)
         entries.push([d, "write"]);
+    return entries;
+}
+/** TOML inline table for the codex permission profile's filesystem entries. */
+export function codexFilesystemProfile(scope, codexBin, envPath) {
+    const entries = [[":minimal", "read"]];
+    for (const r of toolPrefixRoots([codexBin, "bash"], envPath, scope.hqRoot))
+        entries.push([r, "read"]);
+    entries.push([scope.turnDir, "read"]);
+    entries.push(...hqTurnGrants(scope));
     return `{${entries.map(([k, v]) => `${JSON.stringify(k)}=${JSON.stringify(v)}`).join(",")}}`;
 }
+/**
+ * The sandbox profile for a grok turn, written to <turn dir>/.grok/sandbox.toml.
+ * grok's `strict` already covers the turn dir (cwd), system paths and ~/.grok;
+ * the grants add bash's install prefix (Homebrew bash loads from it) and the
+ * read-only HQ paths of hqTurnGrants. Candidate folders are not granted:
+ * the host writes them after the turn, outside this sandbox.
+ */
+export function grokSandboxProfile(scope, envPath) {
+    const reads = [...toolPrefixRoots(["bash"], envPath, scope.hqRoot)];
+    for (const [p, mode] of hqTurnGrants(scope))
+        if (mode === "read")
+            reads.push(p);
+    const list = (items) => `[${items.map((p) => JSON.stringify(p)).join(", ")}]`;
+    return [
+        `[profiles.${GROK_SANDBOX_PROFILE}]`,
+        'extends = "strict"',
+        "restrict_network = true",
+        `read_only = ${list(reads)}`,
+        "read_write = []",
+        "",
+    ].join("\n");
+}
+/** Grok can read the source; candidate writing belongs to the host. */
+export function grokAllowRules(channelDir) {
+    return [`Read(${channelDir}/**)`];
+}
+/** Parse literal arguments only. No shell ever interprets model output. */
+export function grokCandidateArgv(command, wrapperPath) {
+    const words = [];
+    let i = 0;
+    while (i < command.length) {
+        while (command[i] === " " || command[i] === "\t")
+            i++;
+        if (i === command.length)
+            break;
+        let word = "";
+        while (i < command.length && command[i] !== " " && command[i] !== "\t") {
+            const ch = command[i++];
+            if (ch === "'" || ch === '"') {
+                const quote = ch;
+                let closed = false;
+                while (i < command.length) {
+                    const c = command[i++];
+                    if (c === quote) {
+                        closed = true;
+                        break;
+                    }
+                    if (quote === '"' && (c === "$" || c === "`"))
+                        return null;
+                    if (quote === '"' && c === "\\") {
+                        const next = command[i++];
+                        if (next !== '"' && next !== "\\")
+                            return null;
+                        word += next;
+                    }
+                    else
+                        word += c;
+                }
+                if (!closed)
+                    return null;
+            }
+            else if (ch === "\\" && command[i] === "'") {
+                word += command[i++];
+            }
+            else if (/^[a-zA-Z0-9_./:-]$/.test(ch))
+                word += ch;
+            else
+                return null;
+        }
+        words.push(word);
+    }
+    if (words.length !== 8 || words[0] !== "bash" || words[1] !== wrapperPath ||
+        words[2] !== "--kind" || !["signal", "entity"].includes(words[3]) ||
+        words[4] !== "--type" || !/^[a-z][a-z0-9_-]*$/.test(words[5]) ||
+        words[6] !== "--body" || !words[7] || words.some((w) => w.includes("\0")))
+        return null;
+    return words.slice(1);
+}
+/** True when the writer on disk is still the script this turn generated. */
+function wrapperMatchesGenerated(wrapperPath, expected) {
+    try {
+        return fs.readFileSync(wrapperPath, "utf8") === expected;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate the whole batch before writing. Only the host executes the pinned
+ * writer. When `expectedWrapper` is set, the file is compared to that text
+ * immediately before each exec. Strict can write the turn directory, so a
+ * writer that no longer matches is not run.
+ */
+export function executeGrokCandidates(text, wrapperPath, spawn, opts, expectedWrapper) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return "grok must return a JSON commands array";
+    }
+    if (!data || typeof data !== "object" || !("commands" in data) || !Array.isArray(data.commands) || data.commands.length > 8) {
+        return "grok must return at most 8 candidate commands";
+    }
+    const batch = [];
+    for (const command of data.commands) {
+        const argv = typeof command === "string" ? grokCandidateArgv(command, wrapperPath) : null;
+        if (!argv)
+            return "refused: command is not the pinned candidate wrapper";
+        batch.push(argv);
+    }
+    for (const argv of batch) {
+        if (expectedWrapper !== undefined && !wrapperMatchesGenerated(wrapperPath, expectedWrapper)) {
+            return "pinned candidate writer does not match the generated script";
+        }
+        const result = spawn("/bin/bash", argv, opts);
+        if (result.error || result.status !== 0)
+            return "pinned candidate writer failed";
+    }
+    return undefined;
+}
+/**
+ * Read denies for the grok login. Grok matches a `~` tool path literally and
+ * expands `~` only after that check, so the absolute temp home is not enough.
+ * `realHomes` is every home the original login might live under (the process
+ * HOME we copied from, and os.homedir() when that differs).
+ */
+export function grokAuthReadDenies(tempHome, realHomes) {
+    // `**` crosses `/`. The unrooted pattern matches auth.json under any
+    // directory, including a spelling the three homes do not list. The exact
+    // `~/.grok/auth.json` is the path the model can name without the temp dir.
+    const spellings = ["~/.grok/**", "~/.grok/auth.json", "**/.grok/auth.json"];
+    const add = (home) => {
+        for (const suffix of [".grok/**", path.join(".grok", "auth.json")]) {
+            const spelling = path.join(home, suffix);
+            if (!spellings.includes(spelling))
+                spellings.push(spelling);
+        }
+        try {
+            const real = fs.realpathSync(home);
+            if (real !== home)
+                add(real);
+        }
+        catch {
+            // The home may be created and removed around the turn. The path we were
+            // given is still denied above.
+        }
+    };
+    add(tempHome);
+    for (const home of realHomes)
+        add(home);
+    return spellings.map((p) => `Read(${p})`);
+}
+/** Deny rules of a grok turn: every other tool class, the login file, and the read-only shell list. */
+export function grokDenyRules(tempHome, realHomes) {
+    return [
+        "Bash",
+        "MCPTool",
+        "WebFetch",
+        "WebSearch",
+        "Edit",
+        "Write",
+        "Grep",
+        ...grokAuthReadDenies(tempHome, realHomes),
+        ...GROK_READ_ONLY_COMMANDS.map((c) => `Bash(${c})`),
+    ];
+}
+export function grokTurnArgs(prompt, scope, maxTurns, tempHome, realHomes) {
+    return [
+        "-p",
+        prompt,
+        "--output-format",
+        "streaming-json",
+        "--cwd",
+        scope.turnDir,
+        "--permission-mode",
+        "dontAsk",
+        "--tools",
+        "read_file",
+        "--disallowed-tools",
+        "search_tool,use_tool,run_terminal_cmd",
+        "--disable-web-search",
+        "--no-subagents",
+        "--max-turns",
+        String(maxTurns),
+        "--sandbox",
+        GROK_SANDBOX_PROFILE,
+        ...grokAllowRules(scope.channelDir).flatMap((r) => ["--allow", r]),
+        ...grokDenyRules(tempHome, realHomes).flatMap((r) => ["--deny", r]),
+    ];
+}
+/** Parent env keys copied into a grok turn. Everything else, including credentials, stays out. */
+export const GROK_ENV_ALLOW = [
+    "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE",
+    "USER", "LOGNAME", "SHELL", "SystemRoot", "COMSPEC", "PATHEXT", "WINDIR",
+    "TERM", "TZ", "HQ_ROOT",
+];
+/** The turn's environment for grok: an allowlist, no sandbox or config overrides, no Claude or Cursor configuration scans. */
+export function grokTurnEnv(base) {
+    const env = {};
+    for (const k of GROK_ENV_ALLOW)
+        if (base[k] !== undefined)
+            env[k] = base[k];
+    for (const k of GROK_ENV_DROP)
+        delete env[k];
+    for (const k of GROK_COMPAT_SCANS)
+        env[k] = "0";
+    return env;
+}
+/** Whether `grok --help` lists every flag a locked-down turn needs, and streaming-json output. */
+export function grokExtractSupportFromHelp(helpText) {
+    const missing = [];
+    for (const flag of GROK_EXTRACT_FLAGS) {
+        if (!new RegExp(`(^|\\s)${flag}(\\s|$|<|=)`).test(helpText))
+            missing.push(flag);
+    }
+    if (!missing.includes("--output-format") && !/\bstreaming-json\b/.test(helpText))
+        missing.push("--output-format streaming-json");
+    return missing.length ? { ok: false, missing } : { ok: true };
+}
+const cachedGrokSupport = new Map();
+export function resetGrokExtractProbeCache() {
+    cachedGrokSupport.clear();
+}
+/** Probe `grok --help` once per grok binary path (empty or failed output counts as every flag missing). */
+export function probeGrokExtractSupport(grokBin, readHelp) {
+    const hit = cachedGrokSupport.get(grokBin);
+    if (hit)
+        return hit;
+    let help;
+    try {
+        help = readHelp();
+    }
+    catch {
+        help = "";
+    }
+    const support = grokExtractSupportFromHelp(help);
+    cachedGrokSupport.set(grokBin, support);
+    return support;
+}
+/**
+ * Which runtime runs the turns. The main bot's runtime, except that a grok
+ * that is missing or cannot be locked down is never run: the step uses
+ * claude, then codex, when that tool is installed and signed in, and
+ * otherwise fails. The claude and codex checks run only when needed.
+ */
+export function chooseExtractRuntime(main, avail, platform = process.platform) {
+    if (main !== "grok")
+        return { runtime: main };
+    if (platform !== "linux") {
+        const reason = `grok only blocks child-process network on linux, so extract will not use it on ${platform}`;
+        for (const other of ["claude", "codex"]) {
+            const t = avail[other]();
+            if (t.installed && t.signedIn === true)
+                return { runtime: other, fallback: `${reason}; using ${other}` };
+        }
+        return { error: `${reason}; claude and codex are not installed or not signed in. Install grok ${GROK_MIN_VERSION} or newer on linux, or sign in to claude or codex, then run again.` };
+    }
+    const grok = avail.grok();
+    if (grok.installed && grok.support.ok)
+        return { runtime: "grok" };
+    const reason = !grok.installed
+        ? "the main bot runs on grok but grok is not installed"
+        : `the installed grok lacks ${grok.support.ok ? "" : grok.support.missing.join(", ")} (extract needs grok ${GROK_MIN_VERSION} or newer)`;
+    for (const other of ["claude", "codex"]) {
+        const t = avail[other]();
+        if (t.installed && t.signedIn === true)
+            return { runtime: other, fallback: `${reason}; using ${other}` };
+    }
+    return { error: `${reason}; claude and codex are not installed or not signed in. Install grok ${GROK_MIN_VERSION} or newer, or sign in to claude or codex, then run again.` };
+}
+/** Installed-and-signed-in check for a fallback tool, through the step's spawn. */
+function toolAvailability(ctx, bin, statusArgs, parse) {
+    if (!resolveOnPath(bin, process.env.PATH))
+        return { installed: false, signedIn: null };
+    const res = ctx.spawn(bin, statusArgs, { env: { ...process.env, HQ_NO_ENSURE_HQ_DESKTOP: "1" }, timeoutMs: SIGN_IN_CHECK_TIMEOUT_MS });
+    if (res.error)
+        return { installed: true, signedIn: null };
+    return { installed: true, signedIn: parse({ code: res.status, signal: null, stdout: res.stdout, stderr: res.stderr }) };
+}
 export function claudeTurnArgs(prompt, scope, maxTurns, budgetUsd) {
     return [
         "-p",
@@ -635,11 +1052,49 @@ export function codexTurnArgs(prompt, scope, codexBin, envPath) {
 }
 function runTurn(ctx, runtime, prompt, scope, budgetUsd, opts) {
     const cwd = scope.turnDir;
-    const cmd = runtime === "claude" ? opts.claudeBin : opts.codexBin;
-    const args = runtime === "claude"
+    const cmd = runtime === "claude" ? opts.claudeBin : runtime === "grok" ? opts.grokBin : opts.codexBin;
+    let args = runtime === "claude"
         ? claudeTurnArgs(prompt, scope, ctx.maxTurns, budgetUsd)
-        : codexTurnArgs(prompt, scope, opts.codexBin, process.env.PATH);
-    const res = ctx.spawn(cmd, args, { cwd, env: { ...process.env, HQ_ROOT: ctx.hqRoot }, timeoutMs: opts.turnTimeoutMs });
+        : runtime === "codex"
+            ? codexTurnArgs(prompt, scope, opts.codexBin, process.env.PATH)
+            : [];
+    let env = { ...process.env, HQ_ROOT: ctx.hqRoot };
+    let grokHome;
+    let res;
+    try {
+        if (runtime === "grok") {
+            const sourceHome = env.HOME ?? os.homedir();
+            const realHomes = [...new Set([sourceHome, os.homedir()])];
+            const sourceAuth = path.join(sourceHome, ".grok", "auth.json");
+            grokHome = fs.mkdtempSync(path.join(os.tmpdir(), "hq-grok-home-"));
+            // Preserve login without inheriting configuration, hooks, or permissions.
+            const authDir = path.join(grokHome, ".grok");
+            fs.mkdirSync(authDir, { mode: 0o700 });
+            if (fs.existsSync(sourceAuth)) {
+                const authCopy = path.join(authDir, "auth.json");
+                fs.copyFileSync(sourceAuth, authCopy, fs.constants.COPYFILE_EXCL);
+                fs.chmodSync(authCopy, 0o600);
+            }
+            // The profile named by --sandbox; grok refuses to start without it.
+            const profile = path.join(scope.turnDir, GROK_SANDBOX_FILE);
+            fs.mkdirSync(path.dirname(profile), { recursive: true });
+            fs.writeFileSync(profile, grokSandboxProfile(scope, process.env.PATH), { mode: 0o600 });
+            env = grokTurnEnv(env);
+            env.HOME = grokHome;
+            env.XDG_CONFIG_HOME = path.join(grokHome, "xdg");
+            env.XDG_DATA_HOME = path.join(grokHome, "xdg-data");
+            env.CLAUDE_CONFIG_DIR = path.join(grokHome, "claude");
+            env.HQ_ROOT = ctx.hqRoot;
+            for (const dir of [env.XDG_CONFIG_HOME, env.XDG_DATA_HOME, env.CLAUDE_CONFIG_DIR])
+                fs.mkdirSync(dir, { recursive: true });
+            args = grokTurnArgs(prompt, scope, ctx.maxTurns, grokHome, realHomes);
+        }
+        res = ctx.spawn(cmd, args, { cwd, env, timeoutMs: opts.turnTimeoutMs });
+    }
+    finally {
+        if (grokHome)
+            fs.rmSync(grokHome, { recursive: true, force: true });
+    }
     const parsed = parseTurnOutput(res.stdout);
     const all = `${res.stderr}\n${res.stdout}`;
     if (res.error) {
@@ -656,9 +1111,22 @@ function runTurn(ctx, runtime, prompt, scope, budgetUsd, opts) {
         return { ok: false, error: `${runtime} printed no result event`, errorKind: "other", turns: 0, costUsd: 0 };
     if (parsed.result.is_error === true || (typeof parsed.result.subtype === "string" && parsed.result.subtype !== "success")) {
         const text = typeof parsed.result.result === "string" ? parsed.result.result : String(parsed.result.subtype ?? "");
-        const c = classifyFailure(text, `${runtime} turn failed: ${text.slice(0, 200) || "error result"}`);
+        // grok names the refused command on stderr, not in the stream.
+        const refused = runtime === "grok" ? /^permission required: .*$/m.exec(res.stderr)?.[0] : undefined;
+        const detail = refused ? `${text} (${refused})` : text;
+        const c = classifyFailure(detail, `${runtime} turn failed: ${detail.slice(0, 300) || "error result"}`);
         return { ok: false, ...c, turns: parsed.turns, costUsd: parsed.costUsd };
     }
+    if (runtime === "grok") {
+        if (scope.wrapperBody === undefined) {
+            return { ok: false, error: "pinned candidate writer is missing", errorKind: "other", turns: parsed.turns, costUsd: parsed.costUsd };
+        }
+        const error = executeGrokCandidates(String(parsed.result.result ?? ""), scope.wrapperPath, ctx.spawn, {
+            cwd, env: grokTurnEnv({ ...process.env, HQ_ROOT: ctx.hqRoot }), timeoutMs: SCRIPT_TIMEOUT_MS,
+        }, scope.wrapperBody);
+        if (error)
+            return { ok: false, error, errorKind: "other", turns: parsed.turns, costUsd: parsed.costUsd };
+    }
     return { ok: true, turns: parsed.turns, costUsd: parsed.costUsd };
 }
 export async function extractPartialDocument(ctx, doc, prior) {
@@ -695,17 +1163,34 @@ export function createExtractStep(options = {}) {
             if (channels.length === 0 && unrunRedo.length === 0) {
                 return { status: "skipped", itemsIn: 0, itemsOut: 0, skippedReason: "no-sources", ...empty };
             }
-            const runtime = (options.resolveBotRuntime ?? defaultResolveBotRuntime)() ?? options.runtime ?? "claude";
-            if (runtime === "grok") {
-                return {
-                    status: "failed",
-                    itemsIn: 0,
-                    itemsOut: 0,
-                    error: "grok has no restricted tool mode; extract needs claude or codex",
-                    errorKind: "other",
-                    ...empty,
-                };
+            const turnOpts = {
+                claudeBin: options.claudeBin ?? "claude",
+                codexBin: options.codexBin ?? "codex",
+                grokBin: options.grokBin ?? "grok",
+                turnTimeoutMs: options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,
+            };
+            const mainRuntime = (options.resolveBotRuntime ?? defaultResolveBotRuntime)() ?? options.runtime ?? "claude";
+            const choice = chooseExtractRuntime(mainRuntime, {
+                grok: () => {
+                    const resolved = resolveOnPath(turnOpts.grokBin, process.env.PATH);
+                    if (!resolved)
+                        return { installed: false };
+                    turnOpts.grokBin = fs.realpathSync(resolved);
+                    const support = probeGrokExtractSupport(turnOpts.grokBin, () => {
+                        const r = ctx.spawn(turnOpts.grokBin, ["--help"], { env: grokTurnEnv(process.env), timeoutMs: SIGN_IN_CHECK_TIMEOUT_MS });
+                        if (r.error)
+                            throw r.error;
+                        return `${r.stdout}\n${r.stderr}`;
+                    });
+                    return { installed: true, support };
+                },
+                claude: () => toolAvailability(ctx, turnOpts.claudeBin, ["auth", "status", "--json"], parseClaudeAuthStatus),
+                codex: () => toolAvailability(ctx, turnOpts.codexBin, ["login", "status"], parseCodexLoginStatus),
+            }, options.platform ?? process.platform);
+            if ("error" in choice) {
+                return { status: "failed", itemsIn: 0, itemsOut: 0, error: choice.error, errorKind: "config", ...empty };
             }
+            const runtime = choice.runtime;
             const scripts = path.join(ctx.hqRoot, "core", "scripts");
             const worklist = path.join(scripts, "ontology-source-worklist.sh");
             const skillPath = path.join(ctx.hqRoot, "core", "workers", "public", "ontology", "skills", "process-source.md");
@@ -713,11 +1198,6 @@ export function createExtractStep(options = {}) {
                 return { status: "skipped", itemsIn: 0, itemsOut: 0, skippedReason: "ontology-worker-missing", ...empty };
             }
             const skillText = fs.readFileSync(skillPath, "utf8");
-            const turnOpts = {
-                claudeBin: options.claudeBin ?? "claude",
-                codexBin: options.codexBin ?? "codex",
-                turnTimeoutMs: options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS,
-            };
             const env = { ...process.env, HQ_ROOT: ctx.hqRoot };
             const limit = options.worklistLimit ?? DEFAULT_WORKLIST_LIMIT;
             let itemsIn = 0;
@@ -764,7 +1244,7 @@ export function createExtractStep(options = {}) {
                         errorKind = "other";
                     continue;
                 }
-                if (runtime === "codex") {
+                if (runtime === "codex" || runtime === "grok") {
                     try {
                         candidateDirs = ["signals", "ontology"].map((store) => {
                             const dir = assertAllowedPath(ctx.hqRoot, `companies/${ctx.company}/${store}/_candidates`, { company: ctx.company });
@@ -842,8 +1322,9 @@ export function createExtractStep(options = {}) {
                     const before = allCandidateFiles(ctx.hqRoot);
                     let turn;
                     try {
-                        fs.writeFileSync(wrapperPath, buildCandidateWrapper({ hqRoot: ctx.hqRoot, company: ctx.company, audience: (item.audience ?? []).join(","), sourceRef }), { mode: 0o700 });
-                        const scope = { hqRoot: ctx.hqRoot, company: ctx.company, channelDir, turnDir, wrapperPath, candidateDirs };
+                        const wrapperBody = buildCandidateWrapper({ hqRoot: ctx.hqRoot, company: ctx.company, audience: (item.audience ?? []).join(","), sourceRef });
+                        fs.writeFileSync(wrapperPath, wrapperBody, { mode: 0o700 });
+                        const scope = { hqRoot: ctx.hqRoot, company: ctx.company, channelDir, turnDir, wrapperPath, candidateDirs, wrapperBody };
                         const prompt = buildExtractPrompt({
                             skillText,
                             sourceRef,
@@ -853,7 +1334,7 @@ export function createExtractStep(options = {}) {
                             item,
                             itemPath: path.join(channelDir, path.basename(item.file)),
                             wrapperPath,
-                            runtime: runtime === "codex" ? "codex" : "claude",
+                            runtime,
                         });
                         turn = runTurn(ctx, runtime, prompt, scope, Math.max(0, remaining), turnOpts);
                     }
@@ -914,7 +1395,7 @@ export function createExtractStep(options = {}) {
                 ...(failures.length ? { failures } : {}),
                 ...(skippedItems.length ? { skippedItems } : {}),
                 ...(rejected ? { rejectedCandidates: rejected } : {}),
-                detail: { new: itemsOut, updated, skipped },
+                detail: { new: itemsOut, updated, skipped, runtime, ...(choice.fallback ? { fallback: choice.fallback } : {}) },
             };
             if (budgetStop) {
                 result.status = "partial";