@indigoai-us/hq-cli 5.345.202 → 5.345.204

package/dist/lib/lanes/throttle.js

@@ -34,6 +34,23 @@ export const MEMORY_PRESSURE_SYSCTLS = [
     "kern.memorystatus_vm_pressure_level",
     "hw.memsize",
 ];
+/**
+ * Default for throttle.memory_warn_min_free_percent. On darwin a warn pressure
+ * level holds admission only while the free percentage is at or below this.
+ */
+export const DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT = 20;
+/**
+ * Whether a darwin memory_pressure level holds admission on its own. Critical
+ * always holds. Warn holds only at or below warnMinFreePercent free, or when
+ * the free percentage is unknown.
+ */
+export function pressureLevelHolds(signal, warnMinFreePercent = DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT) {
+    if (signal.pressure_level === "critical")
+        return true;
+    if (signal.pressure_level !== "warn")
+        return false;
+    return signal.free_percent === undefined || signal.free_percent <= warnMinFreePercent;
+}
 export const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 function defaultSleep(ms) {
@@ -340,11 +357,11 @@ function formatMb(mb) {
     return `${Math.round(mb)} MB`;
 }
 /** Plain explanation of a memory hold: which signal, its value, and the threshold. */
-export function formatMemoryHoldMessage(signal, thresholdMb) {
+export function formatMemoryHoldMessage(signal, thresholdMb, warnMinFreePercent = DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT) {
     if (signal.source === "memory_pressure") {
         const reading = `memory_pressure reports ${signal.free_percent}% free (about ${formatMb(signal.available_mb)}), pressure level ${signal.pressure_level}`;
-        if (signal.pressure_level !== "normal") {
-            return `Holding new lanes: ${reading}. Lanes wait while the level is warn or critical (throttle.min_available_mem_mb is ${thresholdMb}).`;
+        if (pressureLevelHolds(signal, warnMinFreePercent)) {
+            return `Holding new lanes: ${reading}. Lanes wait while the level is critical, or warn with ${warnMinFreePercent}% free or less (throttle.memory_warn_min_free_percent; throttle.min_available_mem_mb is ${thresholdMb}).`;
         }
         return `Holding new lanes: ${reading}, below throttle.min_available_mem_mb ${thresholdMb}.`;
     }
@@ -379,6 +396,8 @@ export function evaluateThrottle(input) {
     const pause = input.throttle.cpu_busy_pause;
     const resume = input.throttle.cpu_busy_resume;
     const minMem = input.throttle.min_available_mem_mb;
+    const warnMinFree = input.throttle.memory_warn_min_free_percent ??
+        DEFAULT_MEMORY_WARN_MIN_FREE_PERCENT;
     // Each gate is opt-in: an unset threshold never blocks admission.
     let cpuBlocks = false;
     if (pause !== undefined && input.cpuCheckEnabled && input.busy !== null) {
@@ -389,8 +408,9 @@ export function evaluateThrottle(input) {
             cpuBlocks = input.busy >= pause;
         }
     }
-    // On darwin the signal is memory_pressure's: a warn or critical level holds
-    // even above the threshold, and a normal level holds only below it.
+    // On darwin the signal is memory_pressure's: a critical level holds even
+    // above the threshold, a warn level holds only at or below
+    // memory_warn_min_free_percent free, and otherwise only below the threshold.
     let memBlocks = false;
     let memorySignal;
     if (minMem !== undefined && input.availableMemMb !== null) {
@@ -398,8 +418,7 @@ export function evaluateThrottle(input) {
             ? input.memory
             : { source: "meminfo", available_mb: input.availableMemMb };
         memBlocks = input.availableMemMb < minMem ||
-            memorySignal.pressure_level === "warn" ||
-            memorySignal.pressure_level === "critical";
+            pressureLevelHolds(memorySignal, warnMinFree);
     }
     if (!cpuBlocks && !memBlocks) {
         return {
@@ -420,7 +439,7 @@ export function evaluateThrottle(input) {
         memory_hold: {
             ...memorySignal,
             threshold_mb: minMem,
-            message: formatMemoryHoldMessage(memorySignal, minMem),
+            message: formatMemoryHoldMessage(memorySignal, minMem, warnMinFree),
         },
     };
 }

package/dist/lib/lanes/types.d.ts

@@ -1226,6 +1226,11 @@ export interface ThrottleConfig {
     cpu_busy_pause?: number;
     cpu_busy_resume?: number;
     min_available_mem_mb?: number;
+    /**
+     * darwin only: a warn memory_pressure level holds admission only at or
+     * below this free percentage (0-100). Unset means 20. Critical always holds.
+     */
+    memory_warn_min_free_percent?: number;
 }
 /** Session liveness windows from spec §9. Missing keys keep these documented defaults. */
 export interface LivenessWindows {

package/dist/lib/service-manager/launchd.d.ts

@@ -114,6 +114,31 @@ export declare function activateLaunchd(plistPath: string, run: RunCommand, uid?
     sleep?: SleepFn;
     unloadDeadlineMs?: number;
 }): void;
+export interface LaunchdBootstrapResult {
+    ok: boolean;
+    attempts: number;
+    error?: string;
+}
+/**
+ * Bootstrap a plist that is not loaded, retrying launchd's transient EIO with
+ * backoff. A label that is already loaded counts as success. Unlike
+ * reloadLaunchd this never boots anything out, so it is safe to call on a
+ * running job.
+ */
+export declare function bootstrapLaunchd(plistPath: string, run: RunCommand, uid?: number, opts?: {
+    sleep?: SleepFn;
+}): LaunchdBootstrapResult;
+export interface LaunchdJobInfo {
+    loaded: boolean;
+    /** launchd's `state = ...` line (running, not running, spawn scheduled, ...). */
+    state?: string;
+    pid?: number;
+    /** The loaded job's program arguments (`arguments = { ... }`), when printed. */
+    arguments?: string[];
+}
+/** What `launchctl print gui/<uid>/<label>` says about one job. */
+export declare function launchdJobInfo(label: string, run: RunCommand, uid?: number): LaunchdJobInfo;
+export declare function parseLaunchctlPrintJob(stdout: string): LaunchdJobInfo;
 export declare function deactivateLaunchd(plistPath: string, run: RunCommand, uid?: number): void;
 export declare function launchdIsLoaded(label: string, run: RunCommand, uid?: number): boolean;
 //# sourceMappingURL=launchd.d.ts.map

package/dist/lib/service-manager/launchd.js

@@ -58,9 +58,11 @@ export function launchdPlistPath(home, spec) {
     return path.join(launchAgentsDir(home), `${spec.label}.plist`);
 }
 export function renderLaunchdPlist(spec, host) {
-    const discovered = discoverLaunchdIdentity(host.home);
-    const associatedBundleIdentifier = host.associatedBundleIdentifier ?? discovered.associatedBundleIdentifier;
-    const launcherBinary = host.launchdLauncherBinary ?? discovered.launcherBinary;
+    const discovered = spec.independentOfApp ? {} : discoverLaunchdIdentity(host.home);
+    const associatedBundleIdentifier = spec.independentOfApp
+        ? undefined
+        : host.associatedBundleIdentifier ?? discovered.associatedBundleIdentifier;
+    const launcherBinary = spec.independentOfApp ? undefined : host.launchdLauncherBinary ?? discovered.launcherBinary;
     const args = launchdProgramArguments({ ...host, launchdLauncherBinary: launcherBinary }, spec.args)
         .map((a) => `    <string>${escapeXml(a)}</string>`)
         .join("\n");
@@ -303,6 +305,52 @@ export function activateLaunchd(plistPath, run, uid, opts) {
     }
     throw new Error(`${detail}. ${target} is NOT loaded and will not run until it is. Load it with: launchctl bootstrap ${domain} ${plistPath}`);
 }
+/**
+ * Bootstrap a plist that is not loaded, retrying launchd's transient EIO with
+ * backoff. A label that is already loaded counts as success. Unlike
+ * reloadLaunchd this never boots anything out, so it is safe to call on a
+ * running job.
+ */
+export function bootstrapLaunchd(plistPath, run, uid, opts) {
+    const domain = guiDomain(uid);
+    const target = launchdServiceTarget(plistPath, uid);
+    const sleep = opts?.sleep ?? blockingSleep;
+    if (run("launchctl", ["print", target]).status === 0)
+        return { ok: true, attempts: 0 };
+    let last = run("launchctl", ["bootstrap", domain, plistPath]);
+    let attempts = 1;
+    for (const backoff of LAUNCHD_BOOTSTRAP_BACKOFF_MS) {
+        if (last.status === 0 || !isRetryableLaunchdBootstrap(last))
+            break;
+        sleep(backoff);
+        last = run("launchctl", ["bootstrap", domain, plistPath]);
+        attempts++;
+    }
+    // "already bootstrapped" races (another caller loaded it) are success.
+    if (last.status === 0 || run("launchctl", ["print", target]).status === 0)
+        return { ok: true, attempts };
+    return { ok: false, attempts, error: last.stderr.trim() || last.stdout.trim() || `exit ${last.status}` };
+}
+/** What `launchctl print gui/<uid>/<label>` says about one job. */
+export function launchdJobInfo(label, run, uid) {
+    const r = run("launchctl", ["print", `${guiDomain(uid)}/${label}`]);
+    if (r.status !== 0)
+        return { loaded: false };
+    return parseLaunchctlPrintJob(r.stdout);
+}
+export function parseLaunchctlPrintJob(stdout) {
+    const state = /^\s*state\s*=\s*(.+?)\s*$/m.exec(stdout)?.[1];
+    const pidText = /^\s*pid\s*=\s*(\d+)\s*$/m.exec(stdout)?.[1];
+    const pid = pidText ? Number(pidText) : undefined;
+    const argsBlock = /^\s*arguments\s*=\s*\{\s*\n([\s\S]*?)\n\s*\}/m.exec(stdout)?.[1];
+    const args = argsBlock?.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    return {
+        loaded: true,
+        ...(state ? { state } : {}),
+        ...(pid && pid > 0 ? { pid } : {}),
+        ...(args && args.length > 0 ? { arguments: args } : {}),
+    };
+}
 export function deactivateLaunchd(plistPath, run, uid) {
     run("launchctl", ["bootout", guiDomain(uid), plistPath]);
 }

package/dist/lib/service-manager/migration.d.ts

@@ -1,5 +1,11 @@
 import * as fs from "node:fs";
 import { type RunCommand, type SleepFn } from "./launchd.js";
+/**
+ * Agents that must load at login without the app, so they are never wrapped
+ * in the HQ.app launcher or attributed to its bundle. Kept in step with
+ * DAEMON_LAUNCHD_LABEL in daemon/install.ts.
+ */
+export declare const APP_INDEPENDENT_LAUNCHD_LABELS: ReadonlySet<string>;
 export interface LaunchdMigrationOptions {
     home: string;
     run: RunCommand;
@@ -19,4 +25,12 @@ export interface LaunchdMigrationResult {
 }
 /** First-CLI-run cleanup for HQ's old Node-first LaunchAgents and backup plists. */
 export declare function migrateLegacyNodeLaunchAgents(options: LaunchdMigrationOptions): LaunchdMigrationResult;
+/**
+ * The app-independent form of an HQ LaunchAgent plist written by an older
+ * install: the HQ.app launcher (`hq-sync-menubar --hq-launchd-task`) is
+ * dropped from ProgramArguments and the AssociatedBundleIdentifiers entry is
+ * removed. Everything else (environment, logs, KeepAlive) is kept as written.
+ * Returns null when the plist is already app-independent.
+ */
+export declare function appIndependentLaunchdPlist(source: string): string | null;
 //# sourceMappingURL=migration.d.ts.map

package/dist/lib/service-manager/migration.js

@@ -5,6 +5,12 @@ import { isVersionedNodePath, preferStableNodeBinary } from "../node-binary.js";
 import { preferStableHqBinary } from "../mesh/live/daemon/install.js";
 import { launchdMigrationMarkerPath, shouldRunLaunchdMigration, writeLaunchdMigrationMarker } from "./migration-state.js";
 const HQ_LABEL_PREFIXES = ["ai.indigo.hq-", "ai.getindigo.hq-"];
+/**
+ * Agents that must load at login without the app, so they are never wrapped
+ * in the HQ.app launcher or attributed to its bundle. Kept in step with
+ * DAEMON_LAUNCHD_LABEL in daemon/install.ts.
+ */
+export const APP_INDEPENDENT_LAUNCHD_LABELS = new Set(["ai.getindigo.hq-daemon"]);
 function xml(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
@@ -36,6 +42,8 @@ export function migrateLegacyNodeLaunchAgents(options) {
         }
         if (!name.endsWith(".plist") || !HQ_LABEL_PREFIXES.some((prefix) => name.startsWith(prefix)))
             continue;
+        if (APP_INDEPENDENT_LAUNCHD_LABELS.has(name.slice(0, -".plist".length)))
+            continue;
         const source = files.readFileSync(fullPath, "utf8");
         const args = launchdPlistProgramArguments(source);
         if (args.length < 2 || !isNodeProgram(args[0]))
@@ -82,4 +90,30 @@ export function migrateLegacyNodeLaunchAgents(options) {
     writeLaunchdMigrationMarker(options.home, deferred);
     return { migrated, backupsRemoved, deferred, alreadyDone: false };
 }
+/**
+ * The app-independent form of an HQ LaunchAgent plist written by an older
+ * install: the HQ.app launcher (`hq-sync-menubar --hq-launchd-task`) is
+ * dropped from ProgramArguments and the AssociatedBundleIdentifiers entry is
+ * removed. Everything else (environment, logs, KeepAlive) is kept as written.
+ * Returns null when the plist is already app-independent.
+ */
+export function appIndependentLaunchdPlist(source) {
+    const args = launchdPlistProgramArguments(source);
+    const launcherIndex = args.indexOf("--hq-launchd-task");
+    const wrapped = launcherIndex === 1 && args.length > 3;
+    const associated = /<key>AssociatedBundleIdentifiers<\/key>/.test(source);
+    if (!wrapped && !associated)
+        return null;
+    let updated = source;
+    if (wrapped) {
+        updated = updated.replace(/<key>ProgramArguments<\/key>\s*<array>[\s\S]*?<\/array>/, plistArgs(args.slice(2)).trimStart());
+    }
+    if (associated) {
+        updated = updated.replace(/[ \t]*<key>AssociatedBundleIdentifiers<\/key>\s*(?:<array>[\s\S]*?<\/array>|<string>[^<]*<\/string>)[ \t]*\n?/, "");
+    }
+    if (updated === source || /<key>AssociatedBundleIdentifiers<\/key>/.test(updated) || launchdPlistProgramArguments(updated).includes("--hq-launchd-task")) {
+        throw new Error("Could not safely rewrite the LaunchAgent to load without HQ.app");
+    }
+    return updated;
+}
 //# sourceMappingURL=migration.js.map

package/dist/lib/service-manager/systemd.d.ts

@@ -16,4 +16,17 @@ export declare function renderSystemdUserUnit(spec: ServiceSpec, host: ServiceHo
 export declare function activateSystemd(unitName: string, run: RunCommand): void;
 export declare function deactivateSystemd(unitName: string, run: RunCommand): void;
 export declare function systemdIsActive(unitName: string, run: RunCommand): boolean;
+export interface SystemdUnitInfo {
+    /** `systemctl is-enabled` printed enabled (or enabled-runtime / linked / alias). */
+    enabled: boolean;
+    /** `systemctl is-active` printed active (or activating / reloading). */
+    active: boolean;
+    /** The raw `is-enabled` / `is-active` answers, for status output. */
+    enabledState: string;
+    activeState: string;
+    /** MainPID when systemd reports one. */
+    pid?: number;
+}
+/** Ask systemd about one unit; `scope: "user"` adds `--user`. */
+export declare function systemdUnitInfo(unitName: string, run: RunCommand, scope?: "user" | "system"): SystemdUnitInfo;
 //# sourceMappingURL=systemd.d.ts.map

package/dist/lib/service-manager/systemd.js

@@ -69,4 +69,23 @@ export function systemdIsActive(unitName, run) {
     const r = run("systemctl", ["--user", "is-active", "--quiet", unitName]);
     return r.status === 0;
 }
+/** Ask systemd about one unit; `scope: "user"` adds `--user`. */
+export function systemdUnitInfo(unitName, run, scope = "user") {
+    const prefix = scope === "user" ? ["--user"] : [];
+    const word = (args) => {
+        const r = run("systemctl", [...prefix, ...args, unitName]);
+        return (r.stdout.trim().split("\n")[0] ?? "").trim() || "unknown";
+    };
+    const enabledState = word(["is-enabled"]);
+    const activeState = word(["is-active"]);
+    const show = run("systemctl", [...prefix, "show", "-p", "MainPID", "--value", unitName]);
+    const pid = Number(show.stdout.trim());
+    return {
+        enabled: /^(enabled|enabled-runtime|linked|linked-runtime|alias|static|indirect|generated)$/.test(enabledState),
+        active: /^(active|activating|reloading)$/.test(activeState),
+        enabledState,
+        activeState,
+        ...(show.status === 0 && Number.isInteger(pid) && pid > 0 ? { pid } : {}),
+    };
+}
 //# sourceMappingURL=systemd.js.map

package/dist/lib/service-manager/types.d.ts

@@ -21,6 +21,14 @@ export interface ServiceSpec {
     restartSec: number;
     /** systemd unit file name; defaults to `hq-agent-<name>.service`. */
     unitName?: string;
+    /**
+     * macOS: run the job directly under node, without the HQ.app launcher and
+     * without AssociatedBundleIdentifiers, so launchd loads it at login whether
+     * or not the app is installed, enabled or allowed. The daemon sets this:
+     * on 2026-11-03 launchd skipped both app-associated agents at login and the
+     * daemon stayed down for 16 hours.
+     */
+    independentOfApp?: boolean;
 }
 export interface ServiceHostPaths {
     home: string;

package/dist/lib/signals/steps/extract.d.ts

@@ -1,6 +1,6 @@
 import { type StoredPriorSignal } from "../prior-signals.js";
 import { type BotRuntimeId } from "../../bot/config.js";
-import type { SignalsStep, StepContext, StepResult } from "./types.js";
+import type { SignalsStep, SpawnSyncFn, StepContext, StepResult } from "./types.js";
 export declare const EXTRACT_SIGNAL_TYPES: readonly ["action_item", "commitment", "decision", "risk", "question", "key_point", "participant_contribution", "summary"];
 export declare const DEFAULT_WORKLIST_LIMIT = 20;
 export declare const DEFAULT_TURN_TIMEOUT_MS: number;
@@ -13,6 +13,20 @@ export declare const WORKLIST_ITEM_TIMEOUT_MS = 10000;
 export declare function worklistTimeoutMs(limit: number): number;
 export declare const CODEX_PERMISSION_PROFILE = "hq_signals_extract";
 export declare const CANDIDATE_WRAPPER_NAME = "write-candidate.sh";
+/** The sandbox profile the step writes to <turn dir>/.grok/sandbox.toml for a grok turn. */
+export declare const GROK_SANDBOX_PROFILE = "hq_signals_extract";
+export declare const GROK_SANDBOX_FILE: string;
+/** The oldest grok whose `--help` lists every flag in GROK_EXTRACT_FLAGS. */
+export declare 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 declare const GROK_EXTRACT_FLAGS: readonly ["--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 declare const GROK_READ_ONLY_COMMANDS: readonly ["ls", "cat", "pwd", "date", "whoami", "hostname", "uptime", "ps", "head", "tail", "wc", "sort", "uniq", "tr", "cut", "mkdir", "touch", "git", "grep", "rg", "kubectl"];
 /** The only tools a claude turn may use: Read inside the channel folder and the pinned wrapper. */
 export declare function claudeAllowedTools(channelDir: string, wrapperPath: string): string[];
 export interface PriorSignal {
@@ -36,10 +50,13 @@ export interface ExtractStepOptions {
     resolveBotRuntime?: () => BotRuntimeId | null;
     claudeBin?: string;
     codexBin?: string;
+    grokBin?: string;
     worklistLimit?: number;
     turnTimeoutMs?: number;
     /** Run channels whose source.yaml says run: cloud too (passes --force). */
     force?: boolean;
+    /** OS used to decide whether grok's child-process network block exists. Default: this process. */
+    platform?: NodeJS.Platform;
 }
 interface SourceChannel {
     channel: string;
@@ -77,8 +94,11 @@ export declare function buildExtractPrompt(input: {
     item: WorkItem;
     itemPath: string;
     wrapperPath: string;
-    /** codex has no Read tool; it reads with shell commands inside its sandbox. */
-    runtime?: "claude" | "codex";
+    /**
+     * codex has no Read tool; it reads with shell commands inside its sandbox.
+     * grok reads with read_file and returns candidate commands as JSON data.
+     */
+    runtime?: "claude" | "codex" | "grok";
 }): string;
 /**
  * The per-item candidate command. It pins --company, --audience and
@@ -91,7 +111,16 @@ export declare function buildCandidateWrapper(input: {
     audience: string;
     sourceRef: string;
 }): string;
-/** 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 declare function parseTurnOutput(stdout: string): {
     result: Record<string, unknown> | null;
     turns: number;
@@ -134,9 +163,86 @@ export interface TurnScope {
     wrapperPath: string;
     /** companies/{co}/{signals,ontology}/_candidates, realpath. */
     candidateDirs: string[];
+    /**
+     * Text of the pinned writer, when this turn generated one. A grok turn
+     * compares the file to this immediately before executing it.
+     */
+    wrapperBody?: string;
 }
 /** TOML inline table for the codex permission profile's filesystem entries. */
 export declare function codexFilesystemProfile(scope: TurnScope, codexBin: string, envPath: string | undefined): string;
+/**
+ * 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 declare function grokSandboxProfile(scope: TurnScope, envPath: string | undefined): string;
+/** Grok can read the source; candidate writing belongs to the host. */
+export declare function grokAllowRules(channelDir: string): string[];
+/** Parse literal arguments only. No shell ever interprets model output. */
+export declare function grokCandidateArgv(command: string, wrapperPath: string): string[] | null;
+/**
+ * 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 declare function executeGrokCandidates(text: string, wrapperPath: string, spawn: SpawnSyncFn, opts: Parameters<SpawnSyncFn>[2], expectedWrapper?: string): string | 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 declare function grokAuthReadDenies(tempHome: string, realHomes: readonly string[]): string[];
+/** Deny rules of a grok turn: every other tool class, the login file, and the read-only shell list. */
+export declare function grokDenyRules(tempHome: string, realHomes: readonly string[]): string[];
+export declare function grokTurnArgs(prompt: string, scope: TurnScope, maxTurns: number, tempHome: string, realHomes: readonly string[]): string[];
+/** Parent env keys copied into a grok turn. Everything else, including credentials, stays out. */
+export declare const GROK_ENV_ALLOW: readonly ["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 declare function grokTurnEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export type GrokExtractSupport = {
+    ok: true;
+} | {
+    ok: false;
+    missing: string[];
+};
+/** Whether `grok --help` lists every flag a locked-down turn needs, and streaming-json output. */
+export declare function grokExtractSupportFromHelp(helpText: string): GrokExtractSupport;
+export declare function resetGrokExtractProbeCache(): void;
+/** Probe `grok --help` once per grok binary path (empty or failed output counts as every flag missing). */
+export declare function probeGrokExtractSupport(grokBin: string, readHelp: () => string): GrokExtractSupport;
+export type GrokAvailability = {
+    installed: false;
+} | {
+    installed: true;
+    support: GrokExtractSupport;
+};
+export interface ToolAvailability {
+    installed: boolean;
+    /** The tool's own answer; null when it did not say (then it is not used as a fallback). */
+    signedIn: boolean | null;
+}
+export type ExtractRuntimeChoice = {
+    runtime: BotRuntimeId;
+    fallback?: string;
+} | {
+    error: string;
+};
+/**
+ * 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 declare function chooseExtractRuntime(main: BotRuntimeId, avail: {
+    grok: () => GrokAvailability;
+    claude: () => ToolAvailability;
+    codex: () => ToolAvailability;
+}, platform?: NodeJS.Platform): ExtractRuntimeChoice;
 export declare function claudeTurnArgs(prompt: string, scope: TurnScope, maxTurns: number, budgetUsd: number): string[];
 export declare function codexTurnArgs(prompt: string, scope: TurnScope, codexBin: string, envPath: string | undefined): string[];
 export declare function extractPartialDocument(ctx: StepContext, doc: PartialDocument, prior: readonly PriorSignal[]): Promise<StepResult>;