@indigoai-us/hq-cli 5.345.85 → 5.345.87

package/dist/commands/scan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `hq scan secrets` — offline secret scanner (the HQ pre-commit gate).
+ *
+ *   hq scan secrets               scan the staged changes of the current repo
+ *   hq scan secrets <file...>     scan whole files instead
+ *   hq scan secrets --json        findings as JSON
+ *
+ * Rules: the vendored gitleaks default rule set (MIT, vendor/gitleaks/) plus
+ * HQ's own token patterns. No network, no account, no quota.
+ *
+ * Exit codes: 0 clean, 1 possible secret found, 2 the scan could not run.
+ * A pre-commit hook blocks on any non-zero exit, so the gate fails closed.
+ * Output names the rule, file and line; secret values are never printed.
+ */
+import { Command } from "commander";
+interface ScanSecretsOptions {
+    json?: boolean;
+    staged?: boolean;
+}
+export declare function runScanSecrets(paths: string[], opts: ScanSecretsOptions, cwd?: string): number;
+export declare function registerScanCommand(program: Command): void;
+export {};
+//# sourceMappingURL=scan.d.ts.map

package/dist/commands/scan.js

@@ -0,0 +1,59 @@
+/**
+ * `hq scan secrets` — offline secret scanner (the HQ pre-commit gate).
+ *
+ *   hq scan secrets               scan the staged changes of the current repo
+ *   hq scan secrets <file...>     scan whole files instead
+ *   hq scan secrets --json        findings as JSON
+ *
+ * Rules: the vendored gitleaks default rule set (MIT, vendor/gitleaks/) plus
+ * HQ's own token patterns. No network, no account, no quota.
+ *
+ * Exit codes: 0 clean, 1 possible secret found, 2 the scan could not run.
+ * A pre-commit hook blocks on any non-zero exit, so the gate fails closed.
+ * Output names the rule, file and line; secret values are never printed.
+ */
+import { ScanInputError, scanFiles, scanStaged } from "../lib/secret-scan/staged.js";
+function report(findings, scope) {
+    if (!findings.length)
+        return;
+    const n = findings.length;
+    process.stderr.write(`HQ secret scan: ${n} possible secret${n === 1 ? "" : "s"} in ${scope} (values hidden)\n`);
+    for (const f of findings) {
+        process.stderr.write(`  ${f.file}:${f.line}  ${f.ruleId}  ${f.description}\n`);
+    }
+    process.stderr.write("\nRemove the secret from the change, then stage it again. Keep real credentials in the HQ vault\n" +
+        "(hq secrets, hq run). A known false positive can carry a `gitleaks:allow` comment on that line.\n");
+}
+export function runScanSecrets(paths, opts, cwd = process.cwd()) {
+    let findings;
+    try {
+        findings = paths.length && !opts.staged ? scanFiles(paths) : scanStaged(cwd);
+    }
+    catch (err) {
+        const msg = err instanceof ScanInputError ? err.message : `scan failed: ${err instanceof Error ? err.message : String(err)}`;
+        if (opts.json)
+            process.stdout.write(`${JSON.stringify({ ok: false, error: msg })}\n`);
+        process.stderr.write(`HQ secret scan: ${msg}\n`);
+        return 2;
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ ok: findings.length === 0, findings })}\n`);
+    }
+    else {
+        report(findings, paths.length && !opts.staged ? "the given files" : "staged changes");
+    }
+    return findings.length ? 1 : 0;
+}
+export function registerScanCommand(program) {
+    const scan = program.command("scan").description("Local, offline scanners");
+    scan
+        .command("secrets")
+        .description("Scan staged changes (or files) for secrets; exits 1 on a finding")
+        .argument("[files...]", "Scan these files instead of the staged changes")
+        .option("--staged", "Scan the staged changes (default when no files are given)")
+        .option("--json", "Print findings as JSON")
+        .action((files, opts) => {
+        process.exitCode = runScanSecrets(files ?? [], opts);
+    });
+}
+//# sourceMappingURL=scan.js.map

package/dist/commands/storage-core.d.ts

@@ -51,6 +51,8 @@ export declare function coreHasFlag(script: string, flag: string): boolean;
  * ref names are taken from it and the line itself (which tells the user to
  * delete them) is dropped.
  */
+/** Plain fallback when core's prune refusal carried no message. */
+export declare function pruneNothingToFreeMessage(n: number): string;
 export declare function parseRefusal(stdout: string, stderr: string): LocalReport;
 /** Core exit code for a failed precondition (remote-tracking branches, ...). */
 export declare const CORE_PRECONDITION_EXIT = 5;

package/dist/commands/storage-core.js

@@ -70,14 +70,22 @@ function normalizeHoldingRefs(raw) {
  * ref names are taken from it and the line itself (which tells the user to
  * delete them) is dropped.
  */
+/** Plain fallback when core's prune refusal carried no message. */
+export function pruneNothingToFreeMessage(n) {
+    return (`Pruning would free nothing: ${n} ${n === 1 ? "branch, saved version or worktree still uses" : "branches, saved versions or worktrees still use"} ` +
+        "this history. Nothing was changed.");
+}
 export function parseRefusal(stdout, stderr) {
     let refs = [];
     let count;
+    let message;
     try {
         const parsed = JSON.parse(stdout);
         refs = normalizeHoldingRefs(parsed.holding_refs);
         if (typeof parsed.holding_refs_count === "number")
             count = parsed.holding_refs_count;
+        if (typeof parsed.message === "string" && parsed.message.trim())
+            message = parsed.message;
     }
     catch {
         const m = /\(([^()]*refs\/[^()]*)\)/.exec(stderr);
@@ -88,11 +96,14 @@ export function parseRefusal(stdout, stderr) {
                 .map((name) => ({ name, commit_date: null }));
         }
     }
+    const n = count ?? refs.length;
     return {
         available: true,
         refused: "nothing_to_free",
+        // Same shape as offload's refusal: a plain `message` beside the code.
+        message: message ?? pruneNothingToFreeMessage(n),
         holding_refs: refs,
-        holding_refs_count: count ?? refs.length,
+        holding_refs_count: n,
     };
 }
 /** Core exit code for a failed precondition (remote-tracking branches, ...). */

package/dist/commands/storage-offload.d.ts

@@ -261,6 +261,16 @@ export interface OffloadResult {
          */
         refused?: string;
         message?: string;
+        /**
+         * Dry run only: the refusal a real run would hit, or null when none. A
+         * dry run that predicts a refusal still exits 0; only a real run that
+         * refuses exits 4 or 5.
+         */
+        would_refuse?: {
+            code: string;
+            message: string;
+            holders: string[];
+        } | null;
     };
     current: {
         offloaded: {

package/dist/commands/storage-offload.js

@@ -495,6 +495,7 @@ export async function runOffload(opts, deps) {
         result.history.message = refusal.message;
         if (!opts.dryRun)
             return result;
+        result.history.would_refuse = { code: refusal.refused, message: refusal.message, holders: [] };
     }
     else if (blobs.length === 0 && held.length > 0) {
         // Same contract as prune: nothing to free is a refusal (exit 4), decided
@@ -503,9 +504,12 @@ export async function runOffload(opts, deps) {
         result.history.message = worktreeHoldsAllCopy(held);
         if (!opts.dryRun)
             return result;
+        result.history.would_refuse = { code: "nothing_to_free", message: result.history.message, holders: heldWorktrees(held) };
     }
     const noBackup = coreHasFlag(script, "--no-backup");
     if (opts.dryRun) {
+        if (result.history.would_refuse === undefined)
+            result.history.would_refuse = null;
         // Dry run fills the real-run fields with estimates so a preview reads the
         // same keys: every candidate uploaded, and history shrinks by its size.
         const planned = refusal ? 0 : result.history.candidate_bytes;

package/dist/commands/storage.d.ts

@@ -213,6 +213,12 @@ export declare function holderName(ref: string): string;
 export declare function formatHoldingRefusal(local: LocalReport): string[];
 /** Exit code for a prune result: 4 for nothing to free, 5 for a precondition, else 0/1. */
 export declare function pruneExitCode(result: StoragePruneResult): number;
+/**
+ * Exit code for an offload result: a real run that refuses exits 4 (nothing
+ * to free) or 5 (precondition); a dry run that predicts a refusal exits 0 and
+ * reports it in `history.would_refuse`. Errors exit 1.
+ */
+export declare function offloadExitCode(result: OffloadResult): number;
 /** Plain lines for a local prune that was not refused (dry or real). */
 export declare function formatLocalPrune(local: LocalReport, dryRun: boolean): string[];
 export declare function formatStoragePrune(result: StoragePruneResult): string;

package/dist/commands/storage.js

@@ -743,9 +743,15 @@ export function formatOffload(r) {
     const lines = [];
     const h = r.history;
     if (h.refused) {
+        // Core's and the CLI's refusal messages may already say nothing changed;
+        // add that sentence only when the message lacks it.
+        const msg = (h.message ?? "").trim();
+        const lead = /^nothing was uploaded or changed\.\s*/i;
         lines.push(r.dry_run
-            ? `History: a real run would stop before uploading: ${h.message ?? ""}`.trimEnd()
-            : `History: nothing was uploaded or changed. ${h.message ?? ""}`.trimEnd());
+            ? `History: a real run would stop before uploading: ${msg.replace(lead, "")}`.trimEnd()
+            : lead.test(msg)
+                ? `History: ${msg}`
+                : `History: nothing was uploaded or changed. ${msg}`.trimEnd());
     }
     else if (h.available === false) {
         lines.push(`History: not available - ${h.reason ?? "unknown"}`);
@@ -812,6 +818,10 @@ export function formatHoldingRefusal(local) {
 /** Exit code for a prune result: 4 for nothing to free, 5 for a precondition, else 0/1. */
 export function pruneExitCode(result) {
     const local = result.local;
+    // A dry run that ran is a success even when it predicts a refusal; the
+    // JSON reports that in `would_refuse` / `local.refused`.
+    if (result.dry_run)
+        return result.cloud.some((c) => c.errors.length > 0) ? 1 : 0;
     if (local?.refused === "nothing_to_free")
         return 4;
     if (local && typeof local.refused === "string")
@@ -820,6 +830,16 @@ export function pruneExitCode(result) {
         return 1;
     return 0;
 }
+/**
+ * Exit code for an offload result: a real run that refuses exits 4 (nothing
+ * to free) or 5 (precondition); a dry run that predicts a refusal exits 0 and
+ * reports it in `history.would_refuse`. Errors exit 1.
+ */
+export function offloadExitCode(result) {
+    if (result.history.refused && !result.dry_run)
+        return result.history.refused === "nothing_to_free" ? 4 : 5;
+    return result.errors.length > 0 ? 1 : 0;
+}
 /** Plain lines for a local prune that was not refused (dry or real). */
 export function formatLocalPrune(local, dryRun) {
     const w = local.would_refuse && typeof local.would_refuse === "object" ? local.would_refuse : null;
@@ -1126,10 +1146,9 @@ export function registerStorageCommand(program) {
             if (!result)
                 return;
             console.log(opts.json ? JSON.stringify(result, null, 2) : formatOffload(result));
-            if (result.history.refused)
-                process.exitCode = result.history.refused === "nothing_to_free" ? 4 : 5;
-            else if (result.errors.length > 0)
-                process.exitCode = 1;
+            const code = offloadExitCode(result);
+            if (code !== 0)
+                process.exitCode = code;
         }
         catch (err) {
             console.error(chalk.red(err.message));

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

@@ -117,6 +117,8 @@ export interface AgentRecord {
             at?: string;
         } | null;
     };
+    /** "assistant" on HQ's setup assistant, null on other local bots; absent on older servers. */
+    agentRole?: string | null;
 }
 /**
  * One of the caller's own local bots, as `GET /v1/agents/mine?local=1` lists
@@ -133,6 +135,8 @@ export interface MyLocalBot {
     online?: boolean;
     lastHeartbeatAt?: string | null;
     localConfig?: unknown;
+    /** "assistant" on HQ's setup assistant, null on other local bots; absent on older servers. */
+    agentRole?: string | null;
 }
 /** What the credential re-issue route hands back (a rotated machine secret). */
 export interface ReissuedBotCredentials {
@@ -349,6 +353,17 @@ export declare class BotApi {
     listMine(opts?: {
         local?: boolean;
     }): Promise<MyLocalBot[]>;
+    /**
+     * PUT /v1/agents/{uid}/display-name, owner-only: the one write for a bot's
+     * name. The server sets the entity name, the profile display name and the
+     * saved local settings' display name together, and answers 200 for the
+     * same name twice. A server that predates the route answers 404 or 405;
+     * callers decide what that means (see writeCloudDisplayName).
+     */
+    setDisplayName(agentUid: string, displayName: string): Promise<{
+        agentUid: string;
+        displayName: string;
+    }>;
     /** DELETE /v1/agents/{uid} — owner tears the identity down. */
     deleteLocalBot(agentUid: string): Promise<{
         uid: string;

package/dist/lib/bot/api.js

@@ -311,6 +311,17 @@ export class BotApi {
         });
         return Array.isArray(body.agents) ? body.agents : [];
     }
+    /**
+     * PUT /v1/agents/{uid}/display-name, owner-only: the one write for a bot's
+     * name. The server sets the entity name, the profile display name and the
+     * saved local settings' display name together, and answers 200 for the
+     * same name twice. A server that predates the route answers 404 or 405;
+     * callers decide what that means (see writeCloudDisplayName).
+     */
+    async setDisplayName(agentUid, displayName) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/display-name`, { method: "PUT", body: { displayName } }, [200]);
+        return { agentUid: body.agentUid ?? agentUid, displayName: body.displayName ?? displayName };
+    }
     /** DELETE /v1/agents/{uid} — owner tears the identity down. */
     async deleteLocalBot(agentUid) {
         const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}`, { method: "DELETE" });

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

@@ -124,6 +124,12 @@ export interface BotConfig {
      * create; `name` stays the handle every hq bot command uses. Unset = `name`.
      */
     displayName?: string;
+    /**
+     * True while `displayName` is newer than HQ's copy: the last rename was
+     * kept on this computer because the server had no name route yet. Until a
+     * rename reaches HQ, this copy wins over the cloud's older name.
+     */
+    displayNameLocalOnly?: boolean;
     /**
      * Verbatim hello the bot DMs its owner when it first comes online (and on
      * `hq bot intro`). Unset = the default introduction.

package/dist/lib/bot/display-name.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A bot's name and role, as the CLI reports them to the desktop app.
+ *
+ * The name people see lives in the cloud (entity name, profile display name
+ * and the saved local settings, written together by
+ * `PUT /v1/agents/{uid}/display-name`). bot.json keeps a copy so the running
+ * bot can introduce itself. A handle (`setup`) or a slug (`setup-1a2b3c4d`)
+ * is never a name, so it is never reported as one.
+ *
+ * The role marks HQ's setup assistant, so clients find it by role or agent
+ * uid and never by its name or handle.
+ */
+import { type BotApi, type MyLocalBot } from "./api.js";
+import { type BotConfig } from "./config.js";
+export declare const ASSISTANT_ROLE: "assistant";
+export type BotRole = typeof ASSISTANT_ROLE | null;
+/** The setup assistant's cloud slug: the handle plus the owner's suffix. */
+export declare function setupSlugFor(ownerUid: string): string;
+/**
+ * A cloud name worth showing a person, or null when it is empty or is just
+ * the bot's handle or slug (bots created before names existed carry those).
+ */
+export declare function personFacingName(value: string | null | undefined, handles: ReadonlyArray<string | null | undefined>): string | null;
+/** The role of a bot set up on this computer. */
+export declare function localBotRole(config: Pick<BotConfig, "name" | "workerId">): BotRole;
+/**
+ * The role of a bot as the cloud lists it: the server's `agentRole` marker,
+ * else (an older server) the reserved setup slug and the setup worker.
+ */
+export declare function remoteBotRole(bot: MyLocalBot): BotRole;
+/** The cloud name of a listed bot, never its handle or slug. */
+export declare function remoteBotDisplayName(bot: MyLocalBot, handle: string | null): string | null;
+/**
+ * Where a name write ended up. "cloud": the server stored it. "local-only":
+ * the server does not have the name route yet (404/405), so only bot.json
+ * has it until the server is updated.
+ */
+export type NameSaved = "cloud" | "local-only";
+export interface CloudNameWriteResult {
+    saved: NameSaved;
+    /** Why the write stayed local, for the log; never shown to a person. */
+    detail?: string;
+}
+/**
+ * A 405, or a 404 from API Gateway itself, means this server has no name
+ * route yet. The route's own 404 (unknown agent) answers `{ error: "Not found" }`
+ * or carries a code, and is not a missing route: the caller has to hear that
+ * HQ does not know the bot.
+ */
+export declare function isNameRouteMissing(err: unknown): boolean;
+/** The route's own 404: HQ has no such agent (deleted, or a stale bot.json). */
+export declare function isUnknownAgent(err: unknown): boolean;
+/**
+ * Write a bot's name to the cloud. A server without the route is not a
+ * failure: the caller keeps the name on this computer and the result says so.
+ * Any other error is thrown for the caller to handle.
+ */
+export declare function writeCloudDisplayName(api: Pick<BotApi, "setDisplayName">, agentUid: string, displayName: string, opts?: {
+    attempts?: number;
+    retryDelayMs?: number;
+}): Promise<CloudNameWriteResult>;
+/** 409 DISPLAY_NAME_WRITE_CONFLICT: the record changed during the server's own retries. */
+export declare function isNameWriteConflict(err: unknown): boolean;
+//# sourceMappingURL=display-name.d.ts.map

package/dist/lib/bot/display-name.js

@@ -0,0 +1,117 @@
+/**
+ * A bot's name and role, as the CLI reports them to the desktop app.
+ *
+ * The name people see lives in the cloud (entity name, profile display name
+ * and the saved local settings, written together by
+ * `PUT /v1/agents/{uid}/display-name`). bot.json keeps a copy so the running
+ * bot can introduce itself. A handle (`setup`) or a slug (`setup-1a2b3c4d`)
+ * is never a name, so it is never reported as one.
+ *
+ * The role marks HQ's setup assistant, so clients find it by role or agent
+ * uid and never by its name or handle.
+ */
+import { BotApiError } from "./api.js";
+import { SETUP_BOT_WORKER_ID } from "./config.js";
+import { parseBotLocalConfig } from "./local-config.js";
+export const ASSISTANT_ROLE = "assistant";
+/** The handle the desktop app creates HQ's setup assistant under. */
+const SETUP_HANDLE = "setup";
+/** The setup assistant's cloud slug: the handle plus the owner's suffix. */
+export function setupSlugFor(ownerUid) {
+    return `${SETUP_HANDLE}-${ownerUid.trim().slice(-8).toLowerCase()}`;
+}
+/**
+ * A cloud name worth showing a person, or null when it is empty or is just
+ * the bot's handle or slug (bots created before names existed carry those).
+ */
+export function personFacingName(value, handles) {
+    const name = (value ?? "").trim();
+    if (!name)
+        return null;
+    const lower = name.toLowerCase();
+    for (const h of handles) {
+        if (h && h.trim().toLowerCase() === lower)
+            return null;
+    }
+    return name;
+}
+/** The role of a bot set up on this computer. */
+export function localBotRole(config) {
+    return config.name === SETUP_HANDLE && config.workerId === SETUP_BOT_WORKER_ID ? ASSISTANT_ROLE : null;
+}
+/**
+ * The role of a bot as the cloud lists it: the server's `agentRole` marker,
+ * else (an older server) the reserved setup slug and the setup worker.
+ */
+export function remoteBotRole(bot) {
+    if (bot.agentRole === ASSISTANT_ROLE)
+        return ASSISTANT_ROLE;
+    const local = parseBotLocalConfig(bot.localConfig);
+    const owner = (bot.ownerUid ?? "").trim();
+    if (owner &&
+        (bot.slug ?? "").trim().toLowerCase() === setupSlugFor(owner) &&
+        local?.workerSource === "worker" &&
+        local.workerId === SETUP_BOT_WORKER_ID) {
+        return ASSISTANT_ROLE;
+    }
+    return null;
+}
+/** The cloud name of a listed bot, never its handle or slug. */
+export function remoteBotDisplayName(bot, handle) {
+    const raw = bot;
+    const handles = [handle, bot.slug, bot.agentUid];
+    if (typeof raw.displayName === "string") {
+        const shown = personFacingName(raw.displayName, handles);
+        if (shown)
+            return shown;
+    }
+    return personFacingName(bot.name, handles) ?? personFacingName(parseBotLocalConfig(bot.localConfig)?.displayName, handles);
+}
+/**
+ * A 405, or a 404 from API Gateway itself, means this server has no name
+ * route yet. The route's own 404 (unknown agent) answers `{ error: "Not found" }`
+ * or carries a code, and is not a missing route: the caller has to hear that
+ * HQ does not know the bot.
+ */
+export function isNameRouteMissing(err) {
+    if (!(err instanceof BotApiError))
+        return false;
+    if (err.status === 405)
+        return true;
+    return err.status === 404 && !err.code && err.detail !== "Not found";
+}
+/** The route's own 404: HQ has no such agent (deleted, or a stale bot.json). */
+export function isUnknownAgent(err) {
+    return err instanceof BotApiError && err.status === 404 && !isNameRouteMissing(err);
+}
+/**
+ * Write a bot's name to the cloud. A server without the route is not a
+ * failure: the caller keeps the name on this computer and the result says so.
+ * Any other error is thrown for the caller to handle.
+ */
+export async function writeCloudDisplayName(api, agentUid, displayName, opts = {}) {
+    const attempts = Math.max(1, opts.attempts ?? 3);
+    for (let attempt = 1;; attempt++) {
+        try {
+            await api.setDisplayName(agentUid, displayName);
+            return { saved: "cloud" };
+        }
+        catch (err) {
+            if (isNameRouteMissing(err)) {
+                return { saved: "local-only", detail: `the server has no name route yet (${err.status})` };
+            }
+            // The server gave up because the record kept changing under it; the
+            // write is safe to repeat.
+            if (isNameWriteConflict(err) && attempt < attempts) {
+                await new Promise((r) => setTimeout(r, (opts.retryDelayMs ?? 250) * attempt));
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/** 409 DISPLAY_NAME_WRITE_CONFLICT: the record changed during the server's own retries. */
+export function isNameWriteConflict(err) {
+    return err instanceof BotApiError && err.status === 409 && err.code === "DISPLAY_NAME_WRITE_CONFLICT";
+}
+//# sourceMappingURL=display-name.js.map

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

@@ -20,4 +20,6 @@ export * from "./local-name.js";
 export * from "./job-run.js";
 export * from "./job-completions.js";
 export * from "./inflight.js";
+export * from "./lock.js";
+export * from "./display-name.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -20,4 +20,6 @@ export * from "./local-name.js";
 export * from "./job-run.js";
 export * from "./job-completions.js";
 export * from "./inflight.js";
+export * from "./lock.js";
+export * from "./display-name.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,84 @@
+/**
+ * One writer per bot at a time.
+ *
+ * `hq bot create`, `adopt`, `restore`, `rm` and `set` all change the same
+ * bot's folder, and an adopt also rotates the bot's machine secret. Two of
+ * them running at once for the same bot (the desktop's automatic restore and
+ * its first-run create, a minute after sign-in) used to race on a
+ * check-then-write of bot.json: the loser either threw "already set up on this
+ * computer" or, worse, wrote a credential the winner had already rotated away.
+ *
+ * The lock is a file under the bots folder, `~/.hq/bots/.locks/<name>.lock`,
+ * created with O_CREAT|O_EXCL. It sits beside the bot's folder rather than in
+ * it: a folder that exists only to hold a lock would read as "a different bot
+ * already has this name" to the code that picks a restored bot's folder, and
+ * as "something is left here" to `hq bot rm`. Its body names the holder (pid,
+ * host, start time, a random token), so:
+ *   - a holder whose process is gone, or that has held it for longer than
+ *     {@link BOT_LOCK_STALE_MS}, is reclaimed;
+ *   - release only removes the lock it took (the token must match), so a
+ *     reclaim by another process never makes this process remove someone
+ *     else's lock.
+ *
+ * The lock is re-entrant within one async call chain (AsyncLocalStorage):
+ * create holds it and calls the shared adopt path, which takes it again
+ * without waiting on itself. Two separate chains in one process still
+ * serialize, exactly like two processes.
+ */
+/** Not a valid bot name (it starts with a dot), so no bot can collide with it. */
+export declare const BOT_LOCKS_DIRNAME = ".locks";
+/** A holder older than this is treated as crashed, whatever its pid says. */
+export declare const BOT_LOCK_STALE_MS: number;
+/** How long a second writer waits for the first before giving up. */
+export declare const BOT_LOCK_WAIT_MS: number;
+export interface BotLockHolder {
+    pid: number;
+    host: string;
+    startedAt: string;
+    token: string;
+    command: string;
+}
+export interface BotLockOptions {
+    /** What is taking the lock, for the "busy" message and the lock body. */
+    command?: string;
+    /** Total wait for a live holder. Default {@link BOT_LOCK_WAIT_MS}. */
+    waitMs?: number;
+    /** Poll interval while waiting. */
+    pollMs?: number;
+    /** Stale age. Default {@link BOT_LOCK_STALE_MS}. */
+    staleMs?: number;
+    /** Bots root override (tests). */
+    root?: string;
+    now?: () => number;
+    isPidAlive?: (pid: number) => boolean;
+    /** Called once when this call has to wait for another holder. */
+    onWait?: (holder: BotLockHolder | null) => void;
+    /** Called when a stale holder is reclaimed. */
+    onReclaim?: (holder: BotLockHolder | null, why: string) => void;
+}
+export declare class BotLockBusyError extends Error {
+    readonly botName: string;
+    readonly holder: BotLockHolder | null;
+    readonly expected: true;
+    constructor(botName: string, holder: BotLockHolder | null);
+}
+export declare function botLockPath(name: string, root?: string): string;
+/**
+ * Why an existing lock may be taken over, or null while its holder is live.
+ * Exported for tests.
+ */
+export declare function botLockStaleReason(raw: string, mtimeMs: number, opts: {
+    now: number;
+    staleMs: number;
+    isPidAlive: (pid: number) => boolean;
+    host: string;
+}): string | null;
+/**
+ * Let go of every lock this process holds. Runs on process exit, so a command
+ * that ends through process.exit (every `hq bot` failure does) frees its bot
+ * at once instead of leaving it to the stale-holder reclaim.
+ */
+export declare function releaseAllHeldBotLocks(): void;
+/** Take the bot's lock (waiting for a live holder), run `fn`, and let go. */
+export declare function withBotLock<T>(name: string, fn: () => Promise<T>, opts?: BotLockOptions): Promise<T>;
+//# sourceMappingURL=lock.d.ts.map