@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/lib/bot/fleet-python.d.ts

@@ -0,0 +1,47 @@
+type Exec = (executable: string, args: string[], options: Record<string, unknown>) => Buffer | string;
+export interface FleetPythonToolAsset {
+    name: string;
+    sha256: string;
+}
+export interface FleetPythonToolPin {
+    repository: string;
+    version: string;
+    assets: Record<string, FleetPythonToolAsset>;
+}
+export interface FleetPythonDeps {
+    fleetHome?: string;
+    platform?: NodeJS.Platform;
+    arch?: NodeJS.Architecture;
+    fetch?: typeof fetch;
+    run?: Exec;
+    tool?: FleetPythonToolPin;
+    pythonVersion?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface FleetPython {
+    uv: string;
+    python: string;
+    pythonDir: string;
+}
+export declare const HQ_FLEET_PYTHON_VERSION = "3.13.17";
+export declare const HQ_FLEET_PYTHON_TOOL: FleetPythonToolPin;
+export declare const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS: number;
+/** One lock for the whole machine: the installer and the private Python are shared by every bot. */
+export declare const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
+/**
+ * The environment uv runs with: the user's own uv settings (index mirrors,
+ * cache, insecure hosts, config files) are dropped so the private install only
+ * ever sees the pinned sources.
+ */
+export declare function fleetUvEnv(pythonDir: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The operating system's own tar when it is where it always is, so a `tar` on PATH or in the current folder is never run. */
+export declare function tarExecutable(platform: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;
+export declare function fleetPythonToolPath(deps?: FleetPythonDeps): string;
+/**
+ * The pinned installer and private Python, installed once per machine under
+ * the fleet folder and reused by every bot. Concurrent creates wait for each
+ * other on one machine-wide lock instead of racing over the shared folder.
+ */
+export declare function ensureFleetPython(deps?: FleetPythonDeps): Promise<FleetPython>;
+export {};
+//# sourceMappingURL=fleet-python.d.ts.map

package/dist/lib/bot/fleet-python.js

@@ -0,0 +1,218 @@
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fleetHome } from "./fleet-local.js";
+import { withBotLock } from "./lock.js";
+export const HQ_FLEET_PYTHON_VERSION = "3.13.17";
+export const HQ_FLEET_PYTHON_TOOL = {
+    repository: "astral-sh/uv",
+    version: "0.13.5",
+    assets: {
+        "darwin-arm64": { name: "uv-aarch64-apple-darwin.tar.gz", sha256: "743f85035a1996ecb350659e01cd9faea9709829be09b1b4b03c73eaf3c9cd73" },
+        "darwin-x64": { name: "uv-x86_64-apple-darwin.tar.gz", sha256: "b0f52b0e3945b4107d89024ea38e625683011fbfc05a0d98f9fa2d6dcee28c66" },
+        "linux-arm64": { name: "uv-aarch64-unknown-linux-gnu.tar.gz", sha256: "4bb69cf95ed13f23713bb7bc09f241896ea0c75b7c557e615a20604b82f9c403" },
+        "linux-x64": { name: "uv-x86_64-unknown-linux-gnu.tar.gz", sha256: "f68d291c75783122dad58ab77def0e13f3233f358731db5d6d7e8715603b928f" },
+        "win32-arm64": { name: "uv-aarch64-pc-windows-msvc.zip", sha256: "09f47edf90726084a70f9426f6e3ca4f46e9bf7cbf23b1716ec64d60b055fae3" },
+        "win32-x64": { name: "uv-x86_64-pc-windows-msvc.zip", sha256: "a38b8d1902b7cfbc76b423ba1bb456f623f42064cdc72628b6075b89afd1019a" },
+    },
+};
+export const FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+/** One lock for the whole machine: the installer and the private Python are shared by every bot. */
+export const FLEET_PYTHON_LOCK_NAME = "hq-fleet-python";
+function expectedError(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+function toolBinaryName(platform) {
+    return platform === "win32" ? "uv.exe" : "uv";
+}
+/** The last lines a failed child process wrote, or its exit code, so the user sees why. */
+function causeOf(error) {
+    if (error && typeof error === "object") {
+        const failure = error;
+        const stderr = failure.stderr === undefined ? "" : (Buffer.isBuffer(failure.stderr) ? failure.stderr.toString("utf8") : String(failure.stderr));
+        const tail = stderr.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(-3).join(" ");
+        if (tail)
+            return tail;
+        if (typeof failure.status === "number")
+            return `exit code ${failure.status}`;
+        if (failure.message)
+            return failure.message;
+    }
+    return String(error);
+}
+/**
+ * The environment uv runs with: the user's own uv settings (index mirrors,
+ * cache, insecure hosts, config files) are dropped so the private install only
+ * ever sees the pinned sources.
+ */
+export function fleetUvEnv(pythonDir, base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (!key.toUpperCase().startsWith("UV_"))
+            env[key] = value;
+    }
+    env.UV_PYTHON_INSTALL_DIR = pythonDir;
+    env.UV_NO_CONFIG = "1";
+    return env;
+}
+/** The operating system's own tar when it is where it always is, so a `tar` on PATH or in the current folder is never run. */
+export function tarExecutable(platform, env = process.env) {
+    const candidates = platform === "win32"
+        ? [path.join(env.SystemRoot ?? env.windir ?? "C:\\Windows", "System32", "tar.exe")]
+        : ["/usr/bin/tar", "/bin/tar"];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return "tar";
+}
+export function fleetPythonToolPath(deps = {}) {
+    const root = deps.fleetHome ?? fleetHome();
+    const tool = deps.tool ?? HQ_FLEET_PYTHON_TOOL;
+    return path.join(root, "tools", "uv", tool.version, toolBinaryName(deps.platform ?? process.platform));
+}
+function findFile(dir, name) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const child = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const found = findFile(child, name);
+            if (found)
+                return found;
+        }
+        else if (entry.isFile() && entry.name === name) {
+            return child;
+        }
+    }
+    return null;
+}
+function installedTool(binary) {
+    try {
+        const stat = fs.statSync(binary);
+        return stat.isFile() && stat.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function installTool(deps) {
+    const platform = deps.platform ?? process.platform;
+    const arch = deps.arch ?? process.arch;
+    const tool = deps.tool ?? HQ_FLEET_PYTHON_TOOL;
+    const binary = fleetPythonToolPath(deps);
+    if (installedTool(binary))
+        return binary;
+    const asset = tool.assets[`${platform}-${arch}`];
+    if (!asset) {
+        throw expectedError(`HQ Fleet Local does not support ${platform} on ${arch} yet.`);
+    }
+    const fetcher = deps.fetch ?? fetch;
+    const run = deps.run ?? execFileSync;
+    const url = `https://github.com/${tool.repository}/releases/download/${tool.version}/${asset.name}`;
+    let response;
+    try {
+        response = await fetcher(url, { signal: AbortSignal.timeout(FLEET_PYTHON_TOOL_DOWNLOAD_TIMEOUT_MS) });
+    }
+    catch {
+        throw expectedError("Could not download the HQ Fleet Local runtime installer. Check your internet connection and retry.");
+    }
+    if (!response.ok) {
+        throw expectedError(`Could not download the HQ Fleet Local runtime installer: GitHub returned HTTP ${response.status}.`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (crypto.createHash("sha256").update(bytes).digest("hex") !== asset.sha256) {
+        throw expectedError("The HQ Fleet Local runtime installer download did not match its pinned checksum.");
+    }
+    const toolDir = path.dirname(binary);
+    const staging = `${toolDir}.staging-${process.pid}-${crypto.randomUUID()}`;
+    fs.mkdirSync(staging, { recursive: true, mode: 0o700 });
+    try {
+        const archive = path.join(staging, asset.name);
+        fs.writeFileSync(archive, bytes, { mode: 0o600 });
+        const extracted = path.join(staging, "extracted");
+        fs.mkdirSync(extracted, { mode: 0o700 });
+        try {
+            run(tarExecutable(platform, deps.env ?? process.env), ["-xf", archive, "-C", extracted], { stdio: ["ignore", "ignore", "pipe"], windowsHide: true });
+        }
+        catch (error) {
+            throw expectedError(`HQ Fleet Local could not unpack its runtime installer (${causeOf(error)}).`);
+        }
+        const unpacked = findFile(extracted, toolBinaryName(platform));
+        if (!unpacked)
+            throw expectedError("The HQ Fleet Local runtime installer archive did not contain the installer.");
+        const prepared = path.join(staging, "tool");
+        fs.mkdirSync(prepared, { mode: 0o700 });
+        fs.copyFileSync(unpacked, path.join(prepared, path.basename(binary)));
+        fs.chmodSync(path.join(prepared, path.basename(binary)), 0o700);
+        fs.mkdirSync(path.dirname(toolDir), { recursive: true, mode: 0o700 });
+        fs.rmSync(toolDir, { recursive: true, force: true });
+        fs.renameSync(prepared, toolDir);
+    }
+    finally {
+        fs.rmSync(staging, { recursive: true, force: true });
+    }
+    return binary;
+}
+function realpathOrSelf(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function isInside(parent, child, platform) {
+    const fold = (value) => (platform === "win32" ? value.toLowerCase() : value);
+    const relative = path.relative(fold(realpathOrSelf(parent)), fold(realpathOrSelf(child)));
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+async function ensureFleetPythonLocked(root, deps) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? execFileSync;
+    const version = deps.pythonVersion ?? HQ_FLEET_PYTHON_VERSION;
+    const pythonDir = path.join(root, "python");
+    const uv = await installTool(deps);
+    const env = fleetUvEnv(pythonDir, deps.env ?? process.env);
+    fs.mkdirSync(pythonDir, { recursive: true, mode: 0o700 });
+    try {
+        run(uv, ["python", "install", version, "--no-config", "--no-bin", "--no-registry", "--install-dir", pythonDir], {
+            stdio: ["ignore", "ignore", "pipe"],
+            env,
+            windowsHide: true,
+        });
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local could not install its private Python ${version} (${causeOf(error)}). If this mentions a download, check your internet connection and retry.`);
+    }
+    let found;
+    try {
+        const output = run(uv, ["python", "find", version, "--managed-python", "--no-config"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+            encoding: "utf8",
+            windowsHide: true,
+        });
+        found = (Buffer.isBuffer(output) ? output.toString("utf8") : output).trim();
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local installed its private Python but could not locate it (${causeOf(error)}).`);
+    }
+    const python = path.resolve(found);
+    if (!found || !fs.existsSync(python) || !isInside(pythonDir, python, platform)) {
+        throw expectedError("HQ Fleet Local found a Python outside its private install and refused to use it.");
+    }
+    return { uv, python, pythonDir };
+}
+/**
+ * The pinned installer and private Python, installed once per machine under
+ * the fleet folder and reused by every bot. Concurrent creates wait for each
+ * other on one machine-wide lock instead of racing over the shared folder.
+ */
+export async function ensureFleetPython(deps = {}) {
+    const root = deps.fleetHome ?? fleetHome();
+    return withBotLock(FLEET_PYTHON_LOCK_NAME, () => ensureFleetPythonLocked(root, deps), {
+        command: "hq bot create",
+        root,
+    });
+}
+//# sourceMappingURL=fleet-python.js.map

package/dist/lib/bot/index.d.ts

@@ -25,4 +25,6 @@ export * from "./pack-link.js";
 export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
+export * from "./fleet-local.js";
+export * from "./fleet-python.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -25,4 +25,6 @@ export * from "./pack-link.js";
 export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
+export * from "./fleet-local.js";
+export * from "./fleet-python.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/local-config.d.ts

@@ -9,7 +9,7 @@
  * checks the result before it leaves this machine: a bot's machine credentials
  * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
  */
-import { type BotConfig, type BotKind, type BotMemoryMode, type BotRuntimeId } from "./config.js";
+import { type BotConfig, type BotEngineMetadata, type BotKind, type BotMemoryMode, type BotRuntimeId } from "./config.js";
 /**
  * Everything needed to rebuild a bot here, minus anything secret. Written on
  * create, returned by `GET /v1/agents/mine?local=1` and by the credential
@@ -18,6 +18,7 @@ import { type BotConfig, type BotKind, type BotMemoryMode, type BotRuntimeId } f
 export interface BotLocalConfig {
     v: 1;
     runtime?: BotRuntimeId;
+    engine?: BotEngineMetadata;
     /** "scaffold" (its own personal/workers/<name>) or "worker" (an HQ worker). */
     workerSource?: "scaffold" | "worker";
     workerId?: string;
@@ -37,7 +38,7 @@ export interface BotLocalConfig {
 /** Walks a value and throws when any key looks like it could carry a secret. */
 export declare function assertNoSecretKeys(value: unknown, path?: string): void;
 /** The bot.json fields a localConfig is built from — nothing else is read. */
-export type BotLocalConfigSource = Pick<BotConfig, "runtime" | "workerSource" | "workerId" | "companySlug" | "model" | "effort" | "kind" | "companies" | "autoApprove" | "memoryDir" | "displayName" | "intro" | "kickoff">;
+export type BotLocalConfigSource = Pick<BotConfig, "runtime" | "engine" | "workerSource" | "workerId" | "companySlug" | "model" | "effort" | "kind" | "companies" | "autoApprove" | "memoryDir" | "displayName" | "intro" | "kickoff">;
 /**
  * The non-secret settings of a bot, for the cloud to keep. Absolute paths
  * (hqRoot, memoryDir, workerDir) are deliberately left out: they belong to the

package/dist/lib/bot/local-config.js

@@ -9,7 +9,7 @@
  * checks the result before it leaves this machine: a bot's machine credentials
  * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
  */
-import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
+import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotEngineMetadata, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
 /** Same limit the server enforces on the stored value. */
 const BOT_LOCAL_CONFIG_MAX_BYTES = 8 * 1024;
 /** Key names the server rejects outright (case-insensitive, substring). */
@@ -41,7 +41,8 @@ export function buildBotLocalConfig(config) {
     const companies = effectiveBotCompanies(config);
     const local = {
         v: 1,
-        runtime: config.runtime,
+        ...(config.engine ? {} : { runtime: config.runtime }),
+        ...(config.engine ? { engine: config.engine } : {}),
         workerSource: config.workerSource ?? "scaffold",
         ...(config.workerId ? { workerId: config.workerId } : {}),
         ...(config.companySlug ? { companySlug: config.companySlug } : {}),
@@ -80,6 +81,8 @@ export function parseBotLocalConfig(value) {
     const runtime = str("runtime");
     if (isBotRuntimeId(runtime))
         out.runtime = runtime;
+    if (isBotEngineMetadata(raw.engine))
+        out.engine = raw.engine;
     const workerSource = str("workerSource");
     if (workerSource === "worker" || workerSource === "scaffold")
         out.workerSource = workerSource;

package/dist/lib/bot/promote.d.ts

@@ -1,5 +1,14 @@
 import type { BotApi, BotPromotionState } from "./api.js";
 import type { BotConfig } from "./config.js";
+import type { BotMachineCreds } from "./creds.js";
+/** A bot whose process and HQ machine credential live outside its state folder,
+ * such as an HQ Fleet Runtime bot: promotion stops its service through the
+ * runtime and reads the credential from the runtime's secure store.
+ */
+export interface LocalBotPromotionRuntime {
+    stop(): void;
+    machineCredential(): BotMachineCreds;
+}
 /** One recoverable local-to-cloud step, used by CLI and desktop. Never kills the
  * local runtime, recopies provider login files, or changes another bot.
  */
@@ -9,6 +18,7 @@ export declare function promoteLocalBot(input: {
     companyUid: string;
     api: BotApi;
     drainTimeoutMs?: number;
+    runtime?: LocalBotPromotionRuntime;
 }): Promise<{
     promotion: BotPromotionState;
     pending: boolean;

package/dist/lib/bot/promote.js

@@ -41,7 +41,7 @@ function readPrivateJson(file, limit) {
  * local runtime, recopies provider login files, or changes another bot.
  */
 export async function promoteLocalBot(input) {
-    const { dir, config, companyUid, api } = input;
+    const { dir, config, companyUid, api, runtime } = input;
     const existing = await api.promotionStatus(config.agentUid, companyUid);
     const holdFile = path.join(dir, "promotion-hold.json");
     const localHold = fs.existsSync(holdFile) ? readPrivateJson(holdFile, 2048) : null;
@@ -58,6 +58,7 @@ export async function promoteLocalBot(input) {
         recordActivePromotion(dir, hold, existing);
         return { promotion: existing, pending: false };
     }
+    runtime?.stop();
     await waitForPromotionDrain(dir, input.drainTimeoutMs ?? 60_000);
     const file = path.join(dir, `promotion-snapshot-${operationId}.json`);
     if (!fs.existsSync(file)) {
@@ -83,7 +84,7 @@ export async function promoteLocalBot(input) {
         throw new Error("Frozen snapshot does not match the cloud operation");
     let state = existing;
     if (!state || state.phase === "preparing") {
-        const machine = readPrivateJson(botCredsPath(dir), 8192);
+        const machine = runtime ? runtime.machineCredential() : readPrivateJson(botCredsPath(dir), 8192);
         if (!machine || typeof machine !== "object" || typeof machine.secret !== "string")
             throw new Error("Invalid bot machine credential");
         try {

package/dist/lib/bot/prompt.d.ts

@@ -103,6 +103,11 @@ export interface BuildSystemPromptInput {
     } | null;
     /** hqRoot-relative (default `${workerDir}/memory`) or absolute. */
     memoryDir?: string;
+    /**
+     * The bot runs on the HQ Fleet Runtime, which labels every message with the
+     * sender's HQ identity and prepends no "Owner context" block.
+     */
+    fleetRuntime?: boolean;
 }
 /**
  * One paragraph saying which kind of bot this is and what that means for the
@@ -110,7 +115,7 @@ export interface BuildSystemPromptInput {
  * acts as its owner everywhere; a company bot acts as itself and cannot
  * create anything for the owner.
  */
-export declare function botKindParagraph(input: Pick<BuildSystemPromptInput, "agentUid" | "ownerUid" | "kind" | "companies">): string;
+export declare function botKindParagraph(input: Pick<BuildSystemPromptInput, "agentUid" | "ownerUid" | "kind" | "companies" | "fleetRuntime">): string;
 /**
  * The standing instructions the bot runs under. The DM body is delivered as
  * the user turn; this text is the system prompt (claude/codex) or the prompt

package/dist/lib/bot/prompt.js

@@ -278,12 +278,17 @@ export function botKindParagraph(input) {
             `If asked to, say plainly that you are a company bot and cannot do that, and suggest your owner ask one of their personal bots (or do it themselves in HQ). ` +
             `Nobody's messages carry an "Owner context" block; never state which companies your owner belongs to.`);
     }
+    const ownerContext = input.fleetRuntime
+        ? `The runtime labels every message with the sender's HQ identity: messages from ${input.ownerUid} are your owner's, and only those carry your owner's authority. ` +
+            `When you need to know which companies your owner belongs to, run \`hq whoami\` yourself; never guess. ` +
+            `Other people read your answers in rooms: in a room, never state which companies your owner belongs to, and never repeat anything from their files or your DMs.`
+        : `Direct messages from your owner start with an "Owner context" block checked with your owner's own sign-in; that is the only source for your owner's companies. ` +
+            `If it says the check failed, say you could not check; never say your owner has no company unless that block says so. ` +
+            `Room messages do not carry it, and other people read your answers there: in a room, never state which companies your owner belongs to, and never repeat anything from their files or your DMs.`;
     return (`You are a PERSONAL bot: you act as your owner, ${input.ownerUid}. ` +
         `Every \`hq\` command you run — in direct messages, in rooms, and on your first task — runs with your owner's own sign-in, so it reaches everything they can: all of their companies and files. ` +
         `Creating a company, a bot, an invite or a share for them works directly, so do it yourself when they ask — never tell them to open a terminal or run a command. ` +
-        `Direct messages from your owner start with an "Owner context" block checked with your owner's own sign-in; that is the only source for your owner's companies. ` +
-        `If it says the check failed, say you could not check; never say your owner has no company unless that block says so. ` +
-        `Room messages do not carry it, and other people read your answers there: in a room, never state which companies your owner belongs to, and never repeat anything from their files or your DMs.`);
+        ownerContext);
 }
 /**
  * The standing instructions the bot runs under. The DM body is delivered as

package/dist/lib/bot/runtime/index.js

@@ -1,7 +1,6 @@
 import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { planBotRuntimeSpawn } from "./windows.js";
 import { GrokAcpClient } from "./grok-acp.js";
@@ -9,6 +8,7 @@ import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
 import { stripControlTokens } from "./sanitize.js";
+import { createTurnScratchDir } from "./scratch-dir.js";
 import { isRuntimeVersionTooOld, versionTooOldModel } from "../runtime-failure.js";
 import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, MAX_MODEL_FALLBACK_RETRIES, } from "./types.js";
 export * from "./types.js";
@@ -345,10 +345,13 @@ export function forgetModelFallbacks() {
  */
 export async function runRuntimeTurn(runtime, input, deps = {}) {
     const spawnImpl = deps.spawnImpl ?? defaultSpawn;
-    const scratchDir = deps.scratchDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "hq-bot-turn-"));
+    const turnEnv = input.env ?? deps.env ?? process.env;
+    const turnPlatform = deps.platform ?? input.platform ?? process.platform;
+    const scratch = deps.scratchDir ? { dir: deps.scratchDir } : createTurnScratchDir("hq-bot-turn-", { platform: turnPlatform });
+    const scratchDir = scratch.dir;
     const outputFile = path.join(scratchDir, "last-message.txt");
     const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
-    const turnInput = { ...input, platform: deps.platform ?? input.platform ?? process.platform };
+    const turnInput = { ...input, platform: turnPlatform };
     const nowMs = deps.now ?? Date.now;
     const memoKey = fallbackKey(runtime, input.model);
     const memo = rememberedModelFallbacks.get(memoKey);
@@ -358,7 +361,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     // Enforce at the model boundary too: old plists and direct `bot run` callers
     // may lack the guard. A bot prompt must never quit the user's desktop app.
-    const baseEnv = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    // When TMPDIR was unwritable, hand the runtime CLI the working temp root too.
+    const baseEnv = { ...turnEnv, ...(scratch.fallbackRoot ? { TMPDIR: scratch.fallbackRoot } : {}), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const env = { ...(runtime.runtimeEnv?.(baseEnv) ?? baseEnv), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);

package/dist/lib/bot/runtime/scratch-dir.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-turn scratch folder for the local bot runtime (feedback_f0131909).
+ *
+ * A bot started by launchd/systemd at login can inherit a TMPDIR it cannot
+ * write yet (an external volume that is not mounted or not yet readable by the
+ * agent), so `mkdtemp` failed with EPERM on every turn until `hq bot restart`
+ * re-launched it with a working TMPDIR. Try the configured folder first, then
+ * /tmp, then ~/.hq/tmp. When TMPDIR works nothing changes.
+ */
+export interface TurnScratchDir {
+    /** The created scratch folder. */
+    dir: string;
+    /** The temp root used, when it is not the configured one. */
+    fallbackRoot?: string;
+}
+export interface TurnScratchDeps {
+    /** The configured temp root. Defaults to os.tmpdir(), exactly as before. */
+    tmpdir?: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    warn?: (line: string) => void;
+}
+export declare function createTurnScratchDir(prefix: string, deps?: TurnScratchDeps): TurnScratchDir;
+//# sourceMappingURL=scratch-dir.d.ts.map

package/dist/lib/bot/runtime/scratch-dir.js

@@ -0,0 +1,41 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Warn once per unwritable folder per bot process, not on every turn. */
+const warned = new Set();
+/** Errors that mean "this folder cannot be used"; anything else is rethrown. */
+const UNUSABLE = new Set(["EPERM", "EACCES", "ENOENT", "ENOTDIR", "EROFS"]);
+export function createTurnScratchDir(prefix, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const home = deps.home ?? os.homedir();
+    const warn = deps.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const configured = deps.tmpdir ?? os.tmpdir();
+    const fallbacks = [];
+    if (platform !== "win32")
+        fallbacks.push("/tmp");
+    fallbacks.push(path.join(home, ".hq", "tmp"));
+    let firstError;
+    for (const root of [configured, ...fallbacks.filter((f) => f !== configured)]) {
+        try {
+            if (root !== configured)
+                fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+            const dir = fs.mkdtempSync(path.join(root, prefix));
+            if (root === configured) {
+                warned.delete(configured);
+                return { dir };
+            }
+            if (!warned.has(configured))
+                warn(`hq bot: temp folder ${configured} is not writable (${firstError?.code ?? "error"}); using ${root} instead. Fix TMPDIR or run hq bot restart.`);
+            warned.add(configured);
+            return { dir, fallbackRoot: root };
+        }
+        catch (err) {
+            const e = err;
+            if (!e.code || !UNUSABLE.has(e.code))
+                throw err;
+            firstError ??= e;
+        }
+    }
+    throw new Error(`hq bot cannot create a temporary folder: ${configured} is not writable (${firstError?.code ?? "error"}), and ${fallbacks.join(" and ")} did not work either. Fix TMPDIR or run hq bot restart.`);
+}
+//# sourceMappingURL=scratch-dir.js.map

package/dist/lib/caller-principal.d.ts

@@ -0,0 +1,4 @@
+export declare function callerIsMachinePrincipal(env?: NodeJS.ProcessEnv): boolean;
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export declare function tokenIsMachinePrincipal(token: string): boolean;
+//# sourceMappingURL=caller-principal.d.ts.map

package/dist/lib/caller-principal.js

@@ -0,0 +1,40 @@
+/**
+ * Whether the current caller is a machine principal (a local bot, an
+ * agent-kit agent, a hosted agent or an outpost) or a person login.
+ *
+ * The answer comes from the credentials the request will actually use, never
+ * from a user flag:
+ * - CLI sends go through `ensureCognitoToken()`, which picks machine tokens
+ *   exactly when `wantsMachineCognitoTokens()` is true (HQ_MACHINE_CREDS_FILE
+ *   set and valid, or the default machine creds file on a box with no person
+ *   session). This check reads local state only and makes no network call.
+ * - Callers that already hold a token (the agent-kit MCP tools) use
+ *   `tokenIsMachinePrincipal`, which reads the token's identity claims.
+ */
+import { wantsMachineCognitoTokens } from "../utils/machine-principal-state.js";
+import { peekIdToken } from "../utils/id-token.js";
+export function callerIsMachinePrincipal(env = process.env) {
+    try {
+        return wantsMachineCognitoTokens({}, env);
+    }
+    catch {
+        return false;
+    }
+}
+const MACHINE_ENTITY_TYPES = new Set(["agent", "outpost", "company-outpost"]);
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export function tokenIsMachinePrincipal(token) {
+    let claims;
+    try {
+        claims = peekIdToken(token);
+    }
+    catch {
+        return false;
+    }
+    const type = claims["custom:entityType"];
+    if (typeof type === "string" && MACHINE_ENTITY_TYPES.has(type))
+        return true;
+    const uid = claims["custom:entityUid"];
+    return typeof uid === "string" && /^(agt|out)_/.test(uid);
+}
+//# sourceMappingURL=caller-principal.js.map

package/dist/lib/capacity/collectors/grok.js

@@ -192,7 +192,10 @@ export function mapGrokBillingBody(body, options) {
 export async function collectGrok(options = {}) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     if (readCollectorMark(scoped)?.enabled === false && !options.allowDisabled) {
         return { readings: [], failures: [], view: null, skipped: "disabled", accountId: null };
     }
@@ -474,7 +477,10 @@ function stampAccount(row, options, planType) {
 async function collectEnumeratedGrok(options) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     const clock = options.now ?? ledger.now ?? (() => new Date());
     const cliVersion = options.cliVersion ?? readInstalledGrokVersion(options.readVersion);
     const groups = new Map();

package/dist/lib/cli-flag-keys.d.ts

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export declare const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export declare const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export declare const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,

package/dist/lib/cli-flag-keys.js

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,