@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/index.js

@@ -2,18 +2,14 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
-import "./node-network-compat.js";
-import { CLI_VERSION } from "./cli-version.js";
+import "./node-network-compat-fast.js";
+import { isVersionRequest, wantsLabelledVersionReport } from "./version-request.js";
 // Dependency-light: a pure parser + table, no command graph. Safe to load on
 // every path (including --version) without reintroducing the heavy startup.
-import { isFastCoreRequest } from "./commands/scaffold-fast.js";
+import { isFastCoreRequest, parseFastCore, parseSecretsEnvFastRequest, } from "./fast-scaffold.js";
 // Also dependency-light: registers a process-level rejection boundary; its only
 // heavy import (main.js) is lazy and reached only when a rejection fires.
 import { installProcessRejectionBoundary } from "./unhandled-rejection-boundary.js";
-function isVersionRequest(argv) {
-    const args = argv.slice(2);
-    return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
-}
 // Install BEFORE any dispatch so a floated rejection on ANY path (the command
 // graph or the fast-core forwarder) becomes a non-zero exit. @sentry/node's
 // onUnhandledRejection integration defaults to 'warn' — it captures but does
@@ -22,12 +18,66 @@ function isVersionRequest(argv) {
 // so runCli's finally still finalizes release health and flushes Sentry.
 installProcessRejectionBoundary();
 if (isVersionRequest(process.argv)) {
-    process.stdout.write(`${CLI_VERSION}\n`);
+    // Bare `--version` is the CLI semver only (the contract field updaters
+    // compare). `hq version` and `--json` print the labelled HQ/CLI report.
+    // Lazy so this path still skips the command graph.
+    if (wantsLabelledVersionReport(process.argv)) {
+        void import("./lib/flag-registry.js").then(({ kickFlagRegistryReadiness }) => {
+            kickFlagRegistryReadiness();
+            return import("./utils/version-report.js").then(({ runVersionCommand }) => runVersionCommand(process.argv));
+        });
+    }
+    else {
+        // Keep the benchmarked updater fast route limited to the installed semver.
+        // Registry checks and flag resolution belong to the regular command path.
+        void import("./cli-version.js").then(({ CLI_VERSION }) => {
+            process.stdout.write(`${CLI_VERSION}\n`);
+        });
+    }
+}
+else if (parseFastCore(process.argv)?.entry.kind === "native" &&
+    (process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "true" ||
+        process.env.HQ_FLAG_HQ_CORE_NATIVE_FAST_ROUTE === "1")) {
+    // An explicit enabled override has already decided the global gate. Skip the
+    // snapshot reader import on hot native plumbing paths; runFastCore still
+    // checks the command-family flag before choosing native or shell rollback.
+    void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
+}
+else if (parseFastCore(process.argv)?.entry.kind === "native") {
+    // Native routes are default-off. Resolve the company-scoped persisted flag
+    // without loading the command graph; a miss or stale snapshot takes the
+    // existing full-graph route.
+    void import("./native-fast-route.js").then(async ({ nativeFastRouteEnabled }) => {
+        if (await nativeFastRouteEnabled(process.argv)) {
+            const { runFastCore } = await import("./fast-core.js");
+            await runFastCore(process.argv);
+        }
+        else {
+            const { runCli } = await import("./main.js");
+            await runCli();
+        }
+    });
+}
+else if (parseSecretsEnvFastRequest(process.argv)) {
+    const request = parseSecretsEnvFastRequest(process.argv);
+    void import("./secrets-env-fast-route.js").then(async (route) => {
+        await route.dispatchSecretsEnvFastRequest(request, {
+            isEnabled: () => route.secretsEnvFastRouteEnabled(request),
+            runFast: async () => {
+                const { runSecretsEnvFastPath } = await import("./secrets-env-fast-path.js");
+                return runSecretsEnvFastPath(request);
+            },
+            runCurrent: async () => {
+                const { runCli } = await import("./main.js");
+                await runCli();
+            },
+        });
+    });
 }
 else if (isFastCoreRequest(process.argv)) {
     // Hot relocated plumbing (`hq core hq-session`, `hq core checkpoint-stop-gate`)
     // dispatches straight to the bundled-script runner, so it never pays for the
-    // ~60-module command graph main.ts imports. See src/commands/scaffold-fast.ts.
+    // ~60-module command graph main.ts imports. See src/fast-scaffold.ts.
     void import("./fast-core.js").then(({ runFastCore }) => runFastCore(process.argv));
 }
 else {

package/dist/lanes-drain-hook.d.ts

@@ -0,0 +1,14 @@
+import type { LaneDrainHookInput } from "./lib/lanes/dropbox.js";
+interface DrainHookResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+type DropboxModule = typeof import("./lib/lanes/dropbox.js");
+export interface DrainHookRunnerDeps {
+    /** Test seam for proving the steady-state path does not load the drainer. */
+    loadDropbox?: () => Promise<Pick<DropboxModule, "runDrainHook">>;
+}
+export declare function runLaneDrainHook(env: NodeJS.ProcessEnv, input?: LaneDrainHookInput, inputError?: string, deps?: DrainHookRunnerDeps): Promise<DrainHookResult>;
+export {};
+//# sourceMappingURL=lanes-drain-hook.d.ts.map

package/dist/lanes-drain-hook.js

@@ -0,0 +1,203 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MESSAGE_REPLAY_STATE_NAME, readMessageReplayState, updateMessageReplayTranscript, writeMessageReplayState, } from "./lib/lanes/message-replay.js";
+function parseHookInput(text) {
+    if (text.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`invalid_hook_input_json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("invalid_hook_input_shape: expected a JSON object");
+    }
+    const value = parsed;
+    for (const key of ["transcript_path", "session_id", "hook_event_name"]) {
+        if (value[key] !== undefined && value[key] !== null && typeof value[key] !== "string") {
+            throw new Error(`invalid_hook_input_field: ${key} must be a string`);
+        }
+    }
+    return {
+        ...(typeof value.transcript_path === "string" ? { transcript_path: value.transcript_path } : {}),
+        ...(typeof value.session_id === "string" ? { session_id: value.session_id } : {}),
+        ...(typeof value.hook_event_name === "string" ? { hook_event_name: value.hook_event_name } : {}),
+    };
+}
+function laneIdIsSafe(laneId) {
+    return laneId !== "" && laneId.trim() === laneId &&
+        !laneId.includes("/") && !laneId.includes("\\") &&
+        !laneId.includes("\0") && laneId !== "." && laneId !== ".." &&
+        !laneId.includes("..");
+}
+function fileExists(filePath) {
+    try {
+        fs.statSync(filePath);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function listVisibleNames(dir) {
+    try {
+        return fs.readdirSync(dir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+/** Return true whenever the full drainer may have work or a condition to report. */
+function dropboxMayNeedDrain(box) {
+    const inbox = path.join(box, "inbox.jsonl");
+    if (fileExists(inbox))
+        return true;
+    const draining = path.join(box, "draining");
+    if (listVisibleNames(draining).length > 0)
+        return true;
+    const inflightRoot = path.join(box, "inflight");
+    for (const name of listVisibleNames(inflightRoot)) {
+        const inflight = path.join(inflightRoot, name);
+        const stat = fs.statSync(inflight);
+        if (!stat.isDirectory())
+            return true;
+        if (listVisibleNames(inflight).length > 0)
+            return true;
+    }
+    return false;
+}
+function replayMayNeedWork(box, turnId, input, env) {
+    if (!/^[A-Za-z0-9-]{1,80}$/.test(turnId))
+        return false;
+    const statePath = path.join(box, MESSAGE_REPLAY_STATE_NAME);
+    let state;
+    let hasLegacyFlag = false;
+    try {
+        state = readMessageReplayState(statePath, turnId, () => {
+            hasLegacyFlag = true;
+        });
+    }
+    catch {
+        // Keep the existing named replay error behavior for missing or unreadable state.
+        return true;
+    }
+    if (hasLegacyFlag || !input.transcript_path)
+        return hasLegacyFlag;
+    if (!state.provider)
+        return true;
+    try {
+        const update = updateMessageReplayTranscript(state, input.transcript_path, state.provider, env);
+        if (update === "compacted")
+            return true;
+        writeMessageReplayState(statePath, state);
+        return false;
+    }
+    catch {
+        // The full path preserves the existing named replay error reporting.
+        return true;
+    }
+}
+function recordToolActivity(hqRoot, laneId) {
+    try {
+        const activityPath = path.join(hqRoot, "workspace", "lanes-runs", laneId, "logs", "tool-activity.json");
+        fs.mkdirSync(path.dirname(activityPath), { recursive: true });
+        const record = {
+            at: new Date().toISOString(),
+            hook_pid: process.pid,
+            hook_event: "PreToolUse",
+        };
+        const tempPath = `${activityPath}.${process.pid}.${process.hrtime.bigint()}.${randomBytes(4).toString("hex")}.tmp`;
+        fs.writeFileSync(tempPath, `${JSON.stringify(record)}\n`, "utf8");
+        fs.renameSync(tempPath, activityPath);
+        return "";
+    }
+    catch (err) {
+        return `hq-lanes-drain: failed to record tool activity: ${err instanceof Error ? err.message : String(err)}\n`;
+    }
+}
+function finish(result) {
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+}
+async function runFullPath(env, input, deps) {
+    const loadDropbox = deps.loadDropbox ?? (() => import("./lib/lanes/dropbox.js"));
+    const { runDrainHook } = await loadDropbox();
+    return runDrainHook(env, input);
+}
+export async function runLaneDrainHook(env, input = {}, inputError = "", deps = {}) {
+    const withInputError = (result) => ({
+        ...result,
+        stderr: `${inputError}${result.stderr}`,
+    });
+    const laneId = env.HQ_LANE_ID ?? "";
+    if (laneId === "") {
+        return withInputError({ exitCode: 0, stdout: "", stderr: "" });
+    }
+    const hqRoot = env.HQ_ROOT ?? "";
+    if (hqRoot === "" || !laneIdIsSafe(laneId)) {
+        return withInputError(await runFullPath(env, input, deps));
+    }
+    const box = path.join(hqRoot, "workspace", "lanes-runs", laneId, "dropbox");
+    let noWork = false;
+    try {
+        noWork = !dropboxMayNeedDrain(box) &&
+            !replayMayNeedWork(box, env.HQ_LANE_TURN_ID ?? "", input, env);
+    }
+    catch {
+        // Filesystem uncertainty must use the full path so it retains its named errors.
+    }
+    if (!noWork) {
+        return withInputError(await runFullPath(env, input, deps));
+    }
+    let stderr = recordToolActivity(hqRoot, laneId);
+    const directories = [
+        box,
+        path.join(box, "draining"),
+        path.join(box, "delivered"),
+        path.join(box, "inflight"),
+    ];
+    try {
+        for (const directory of directories)
+            fs.mkdirSync(directory, { recursive: true });
+    }
+    catch (err) {
+        const message = `Failed to open drop box ${box}: ${err instanceof Error ? err.message : String(err)}`;
+        stderr += `hq-lanes-drain: ${message}\n`;
+        return withInputError({ exitCode: 1, stdout: "", stderr });
+    }
+    return withInputError({ exitCode: 0, stdout: "", stderr });
+}
+async function main() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    const text = Buffer.concat(chunks).toString("utf8");
+    let input = {};
+    let inputError = "";
+    try {
+        input = parseHookInput(text);
+    }
+    catch (err) {
+        inputError = `hq-lanes-drain: ${err instanceof Error ? err.message : String(err)}\n`;
+    }
+    finish(await runLaneDrainHook(process.env, input, inputError));
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        process.stderr.write(`hq-lanes-drain: hook_runner_failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        // A hook runner failure must not stop the provider's requested tool call.
+        process.exitCode = 0;
+    });
+}
+//# sourceMappingURL=lanes-drain-hook.js.map

package/dist/lazy-commands.d.ts

@@ -1,55 +1,31 @@
-/**
- * Hot-command manifest for the entrypoint's lazy registration.
- *
- * main.ts used to import the entire ~60-module command graph at module scope,
- * so every invocation paid for every command. That is fine for a human typing
- * one command and ruinous for the calls automation makes in a loop: the
- * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
- * (each worker resolves credentials before every external command it executes),
- * and each of those processes spent ~0.75 CPU-seconds importing commands it
- * never ran — around half a core, continuously. Measured on Outpost 2
- * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
- *
- * A command listed here registers ITSELF and nothing else. Anything not listed
- * — `--help`, a bare `hq`, an unknown command, every other command — falls back
- * to `registerAllCommands`, the complete unchanged graph. That fallback is what
- * makes this safe to extend one command at a time: an entry is a performance
- * opt-in, never a behaviour change, and a command that is absent here is simply
- * as fast as it was before.
- *
- * This mirrors commands/scaffold-fast.ts, which does the same thing for the
- * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
- * parity test registers each entry BOTH ways and asserts the resulting command
- * shape is identical, so a manifest entry cannot silently diverge from the real
- * registration.
- *
- * TO ADD A COMMAND: it must register exactly one top-level command, be
- * registered onto `program` (not onto a subcommand group), and have no other
- * module contributing subcommands to it. The parity test enforces the shape;
- * these three conditions are what make the entry correct in the first place.
- */
-import type { Command } from "commander";
+import { Command } from "commander";
 export type LazyCommand = {
-    /** The top-level token this matches — `hq <name> …`. */
+    /** Canonical top-level name; aliases resolve to this name. */
     name: string;
-    /** Registers this one command onto `program`, importing only its module. */
+    /** Registers every contributor for this root and no unrelated root. */
     register: (program: Command) => Promise<void>;
 };
 /**
- * The hot paths, in descending order of how often automation calls them.
- *
- * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
- * loop: every fleet worker shells through one of them before each external
- * command, which is exactly the shape that makes eager import expensive.
+ * One entry for every root, including groups that are assembled by several
+ * registrar modules. The routing metadata itself is generated from the eager
+ * command graph and checked in tests and the build.
  */
 export declare const LAZY_COMMANDS: readonly LazyCommand[];
 /**
- * Resolve `process.argv` to a manifest entry, or null to use the full graph.
- *
- * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
- * before the command name, so argv[2] is the command token when there is one;
- * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
- * fallback, which is the intended behaviour — help must list every command.
+ * Keep the registration seam at register-all.js. Besides making one place own
+ * the graph, this lets the torn-install recovery wrap failures while an update
+ * replaces the installed tree between startup and command registration.
+ */
+export declare function registerCommandRoot(program: Command, root: string): Promise<boolean>;
+/**
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export declare function registerCommandCatalog(program: Command): void;
+/**
+ * Resolve the root requested by Commander argv. Root help, a bare invocation,
+ * and unknown tokens deliberately return null so the lightweight catalog can
+ * preserve the complete help and unknown-command recovery surfaces.
  */
 export declare function findLazyCommand(argv: readonly string[]): LazyCommand | null;
 //# sourceMappingURL=lazy-commands.d.ts.map

package/dist/lazy-commands.js

@@ -1,68 +1,70 @@
+import { Command } from "commander";
+import { COMMAND_CATALOG } from "./command-catalog.generated.js";
+const commandCatalog = COMMAND_CATALOG;
 /**
- * Hot-command manifest for the entrypoint's lazy registration.
- *
- * main.ts used to import the entire ~60-module command graph at module scope,
- * so every invocation paid for every command. That is fine for a human typing
- * one command and ruinous for the calls automation makes in a loop: the
- * hq-sentry agent fleet on an outpost runs `hq secrets` about 39 times a minute
- * (each worker resolves credentials before every external command it executes),
- * and each of those processes spent ~0.75 CPU-seconds importing commands it
- * never ran — around half a core, continuously. Measured on Outpost 2
- * (i-09424eff61920a4ac) 2026-09-05; see register-all.ts for the numbers.
- *
- * A command listed here registers ITSELF and nothing else. Anything not listed
- * — `--help`, a bare `hq`, an unknown command, every other command — falls back
- * to `registerAllCommands`, the complete unchanged graph. That fallback is what
- * makes this safe to extend one command at a time: an entry is a performance
- * opt-in, never a behaviour change, and a command that is absent here is simply
- * as fast as it was before.
- *
- * This mirrors commands/scaffold-fast.ts, which does the same thing for the
- * relocated `hq core …` scripts, and carries the same anti-drift discipline: a
- * parity test registers each entry BOTH ways and asserts the resulting command
- * shape is identical, so a manifest entry cannot silently diverge from the real
- * registration.
- *
- * TO ADD A COMMAND: it must register exactly one top-level command, be
- * registered onto `program` (not onto a subcommand group), and have no other
- * module contributing subcommands to it. The parity test enforces the shape;
- * these three conditions are what make the entry correct in the first place.
+ * One entry for every root, including groups that are assembled by several
+ * registrar modules. The routing metadata itself is generated from the eager
+ * command graph and checked in tests and the build.
  */
+export const LAZY_COMMANDS = commandCatalog.map((command) => ({
+    name: command.name,
+    register: async (program) => {
+        const registered = await registerCommandRoot(program, command.name);
+        if (!registered)
+            throw new Error(`No registration plan for '${command.name}'`);
+    },
+}));
 /**
- * The hot paths, in descending order of how often automation calls them.
- *
- * `secrets` and `run` are the two commands HQ's own tooling puts on the inner
- * loop: every fleet worker shells through one of them before each external
- * command, which is exactly the shape that makes eager import expensive.
+ * Keep the registration seam at register-all.js. Besides making one place own
+ * the graph, this lets the torn-install recovery wrap failures while an update
+ * replaces the installed tree between startup and command registration.
  */
-export const LAZY_COMMANDS = [
-    {
-        name: "secrets",
-        register: async (program) => {
-            const { registerSecretsCommand } = await import("./commands/secrets.js");
-            registerSecretsCommand(program);
-        },
-    },
-    {
-        name: "run",
-        register: async (program) => {
-            const { registerRunCommand } = await import("./commands/run.js");
-            registerRunCommand(program);
-        },
-    },
-];
+export async function registerCommandRoot(program, root) {
+    const registration = await import("./register-all.js");
+    return registration.registerCommandRoot(program, root);
+}
+function commandDefinition(command) {
+    const stub = new Command(command.name)
+        .description(command.description);
+    for (const alias of command.aliases)
+        stub.alias(alias);
+    for (const argument of command.arguments) {
+        const name = `${argument.name}${argument.variadic ? "..." : ""}`;
+        stub.argument(argument.required ? `<${name}>` : `[${name}]`);
+    }
+    for (const option of command.options)
+        stub.option(option.flags, option.description);
+    if (command.hidden)
+        stub._hidden = true;
+    return stub;
+}
 /**
- * Resolve `process.argv` to a manifest entry, or null to use the full graph.
- *
- * argv is `[node, hq, <name>, ...rest]`. `hq` declares no program-level options
- * before the command name, so argv[2] is the command token when there is one;
- * `--help`, `--version`, and a bare `hq` all fail the lookup and take the
- * fallback, which is the intended behaviour — help must list every command.
+ * Register only generated root metadata. This is enough for root help and
+ * Commander suggestions, without evaluating an implementation module.
+ */
+export function registerCommandCatalog(program) {
+    for (const command of commandCatalog)
+        program.addCommand(commandDefinition(command));
+}
+function commandForToken(token) {
+    return commandCatalog.find((candidate) => candidate.name === token || candidate.aliases.includes(token));
+}
+/**
+ * Resolve the root requested by Commander argv. Root help, a bare invocation,
+ * and unknown tokens deliberately return null so the lightweight catalog can
+ * preserve the complete help and unknown-command recovery surfaces.
  */
 export function findLazyCommand(argv) {
-    const name = argv[2];
-    if (typeof name !== "string")
+    let commandIndex = 2;
+    while (argv[commandIndex] === "--verbose")
+        commandIndex += 1;
+    const first = argv[commandIndex];
+    const token = first === "help" ? argv[commandIndex + 1] : first;
+    if (typeof token !== "string" || token.startsWith("-"))
+        return null;
+    const command = commandForToken(token);
+    if (!command)
         return null;
-    return LAZY_COMMANDS.find((candidate) => candidate.name === name) ?? null;
+    return LAZY_COMMANDS.find((candidate) => candidate.name === command.name) ?? null;
 }
 //# sourceMappingURL=lazy-commands.js.map

package/dist/lib/agent-kit/adopt-identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
+ * is signed in to HQ.
+ *
+ * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
+ * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
+ * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
+ * a computer with its owner lives in a sibling directory instead, so without
+ * this the CLI would find the layout of an agent and the credentials of a
+ * person: `hq agent probe` would report its owner's identity and the bot would
+ * act as them.
+ *
+ * So before any `hq agent` subcommand runs, the resolved tree is published to
+ * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
+ * a daemon unit that pins one stays pinned.
+ *
+ * The person's own session file is not read, moved, or changed by any of this.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export declare const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
+export declare const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
+/**
+ * Point the token layer at `paths` unless the caller already pinned it.
+ * Returns the variables it set, for tests and for `--verbose` output.
+ */
+export declare function adoptAgentIdentityEnv(paths: Pick<AgentKitPaths, "agentDir" | "machineCredsPath">, env?: NodeJS.ProcessEnv): Record<string, string>;
+//# sourceMappingURL=adopt-identity.d.ts.map

package/dist/lib/agent-kit/adopt-identity.js

@@ -0,0 +1,60 @@
+/**
+ * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
+ * is signed in to HQ.
+ *
+ * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
+ * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
+ * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
+ * a computer with its owner lives in a sibling directory instead, so without
+ * this the CLI would find the layout of an agent and the credentials of a
+ * person: `hq agent probe` would report its owner's identity and the bot would
+ * act as them.
+ *
+ * So before any `hq agent` subcommand runs, the resolved tree is published to
+ * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
+ * a daemon unit that pins one stays pinned.
+ *
+ * The person's own session file is not read, moved, or changed by any of this.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensureHostKeyPath } from "./creds.js";
+export const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
+export const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
+/**
+ * Point the token layer at `paths` unless the caller already pinned it.
+ * Returns the variables it set, for tests and for `--verbose` output.
+ */
+export function adoptAgentIdentityEnv(paths, env = process.env) {
+    const applied = {};
+    if (env[MACHINE_CREDS_FILE_ENV]?.trim())
+        return applied;
+    // Only adopt a tree that actually holds an identity: on a host that has not
+    // enrolled yet, leaving the environment alone keeps today's error messages.
+    try {
+        if (!fs.statSync(paths.machineCredsPath).isFile())
+            return applied;
+    }
+    catch {
+        return applied;
+    }
+    // A moved or copied identity keeps a stale host-key path until the next
+    // token refresh fails; repoint it at the key beside the creds file first.
+    try {
+        ensureHostKeyPath(paths);
+    }
+    catch {
+        /* never block a command on the repair; probe reports a missing key */
+    }
+    applied[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
+    env[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
+    // Per-agent token cache. Two identities on one computer must never share a
+    // minted-token file; the agent's belongs inside the agent's own tree.
+    if (!env[MACHINE_TOKEN_STATE_DIR_ENV]?.trim()) {
+        const dir = path.join(paths.agentDir, "token-state");
+        applied[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
+        env[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
+    }
+    return applied;
+}
+//# sourceMappingURL=adopt-identity.js.map

package/dist/lib/agent-kit/attachment-download.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Vault object download for chat attachments, shared by `hq agent mcp`
+ * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
+ * machine token, so the server's per-key ACL stays the authority. The body is
+ * read with a hard byte cap so a crafted key cannot pull a large object into
+ * memory.
+ */
+import type { Readable } from "node:stream";
+export type VaultObjectDownloader = (scopeUid: string, key: string) => Promise<Buffer>;
+/** Drain a stream into memory, refusing past `max` bytes. */
+export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
+/**
+ * A downloader bound to one identity. `baseUrl` pins the API the token is sent
+ * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
+ * vault API, the same one the caller's other API calls use).
+ */
+export declare function createVaultObjectDownloader(opts: {
+    getToken: () => Promise<string>;
+    baseUrl?: string;
+}): VaultObjectDownloader;
+//# sourceMappingURL=attachment-download.d.ts.map