@indigoai-us/hq-cli 5.121.2 → 5.122.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [5.122.1] — 2026-09-19
+
+### Fixed
+
+- `hq cloud provision company` no longer silently accepts a server-suffixed
+  slug. When another owner already holds the requested name, the vault assigns
+  `<slug>-<tag>` and used to write local config as if the original name had
+  been granted — sync then cannot push, because it looks for a folder matching
+  the cloud slug. Provision now fails before writing, and retires the
+  just-created entity so it does not leave a suffixed orphan.
+
+- Work Mesh now keeps the company you selected when its session context is
+  acknowledged or recovered after a restart. Mesh activity stays attached to
+  the right company instead of being held for missing attribution.
+
+## [5.122.0] — 2026-09-18
+
+### Added
+
+- A bot can now join HQ from the computer its owner already uses. Before,
+  `hq agent enroll` refused on such a machine — the owner is signed in there,
+  and an agent identity must not share a host account with a person's login —
+  which left two bad options: a second user account, or `--replace`.
+
+  Enrollment now moves the bot into its own directory instead of refusing:
+  `~/.hq-agent/<name>/`, with its own credentials, key, state and logs. The
+  owner's session file is never read, moved, or changed. `hq agent probe`,
+  `hq agent kit`, `hq agent inbox` and `hq agent mcp` all find that directory
+  on their own, so the bot is itself without anyone exporting environment
+  variables. Use `--name <bot>` to choose the directory, or to run a second
+  bot on the same computer.
+
+  Two or more local bots are deliberately ambiguous: `hq agent` commands then
+  ask for `HQ_AGENT_DIR` rather than guessing which identity to act as.
+
 ## [5.121.2] — 2026-09-18
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -4271,6 +4271,9 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--replace";
             readonly description: "Overwrite an existing machine identity on this host";
+        }, {
+            readonly flags: "--name <bot>";
+            readonly description: "Enroll into ~/.hq-agent/<bot>/ — for a bot sharing a computer with its owner";
         }, {
             readonly flags: "--api-base-url <url>";
             readonly description: "hq-pro control plane (default: HQ_VAULT_API_URL or production)";
@@ -5747,7 +5750,7 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly subcommands: readonly [];
             }, {
                 readonly name: "set";
-                readonly description: "Set the device default company slug (unlocked when migration is true for every membership)";
+                readonly description: "Set the device default company slug after verifying membership";
                 readonly aliases: readonly [];
                 readonly hidden: false;
                 readonly usage: "[options] <slug>";
@@ -5758,10 +5761,10 @@ export declare const COMMAND_CATALOG: readonly [{
                 }];
                 readonly options: readonly [{
                     readonly flags: "--allow-without-migration";
-                    readonly description: "Bypass DEFAULT_COMPANY_LOCKED with a warning";
+                    readonly description: "Deprecated compatibility no-op; selected-company membership is always verified";
                 }, {
                     readonly flags: "--company <slug|uid>";
-                    readonly description: "Deprecated no-op; unlock probes every active membership";
+                    readonly description: "Deprecated no-op; the selected company is verified directly";
                 }, {
                     readonly flags: "--json";
                     readonly description: "Print machine-readable JSON";

package/dist/command-catalog.generated.js

@@ -5529,6 +5529,10 @@ export const COMMAND_CATALOG = [
                         "flags": "--replace",
                         "description": "Overwrite an existing machine identity on this host"
                     },
+                    {
+                        "flags": "--name <bot>",
+                        "description": "Enroll into ~/.hq-agent/<bot>/ — for a bot sharing a computer with its owner"
+                    },
                     {
                         "flags": "--api-base-url <url>",
                         "description": "hq-pro control plane (default: HQ_VAULT_API_URL or production)"
@@ -7414,7 +7418,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "name": "set",
-                                "description": "Set the device default company slug (unlocked when migration is true for every membership)",
+                                "description": "Set the device default company slug after verifying membership",
                                 "aliases": [],
                                 "hidden": false,
                                 "usage": "[options] <slug>",
@@ -7428,11 +7432,11 @@ export const COMMAND_CATALOG = [
                                 "options": [
                                     {
                                         "flags": "--allow-without-migration",
-                                        "description": "Bypass DEFAULT_COMPANY_LOCKED with a warning"
+                                        "description": "Deprecated compatibility no-op; selected-company membership is always verified"
                                     },
                                     {
                                         "flags": "--company <slug|uid>",
-                                        "description": "Deprecated no-op; unlock probes every active membership"
+                                        "description": "Deprecated no-op; the selected company is verified directly"
                                     },
                                     {
                                         "flags": "--json",

package/dist/commands/agent-enroll.d.ts

@@ -88,7 +88,29 @@ export interface EnrollOptions {
     company?: string;
     replace?: boolean;
     apiBaseUrl?: string;
+    /** Enroll into `~/.hq-agent/<name>/` — a bot sharing a host with a person. */
+    name?: string;
 }
+/**
+ * Where this enrollment should write, given what already lives on the host.
+ *
+ * A bot that runs on its owner's own computer is the common case, not an
+ * error: the machine has the owner's HQ session, and the two identities have
+ * to coexist. So an unpinned enrollment onto such a host does NOT refuse and
+ * does NOT overwrite anything — it moves into `~/.hq-agent/<name>/`, its own
+ * tree with its own credentials, key, state and logs. The person's session
+ * file is neither read nor touched, and `hq agent …` finds the bot's tree on
+ * its own afterwards (see agentDir).
+ */
+export declare function resolveEnrollTarget(opts: {
+    name?: string;
+    replace?: boolean;
+}, env?: NodeJS.ProcessEnv, home?: string): {
+    paths: AgentKitPaths;
+    local: boolean;
+};
+/** Lowercase slug, so the directory name can never escape `~/.hq-agent`. */
+export declare function validateLocalAgentName(name: string): string;
 export interface EnrollResult {
     agentUid: string;
     companySlug: string;
@@ -98,6 +120,10 @@ export interface EnrollResult {
     hostKeyPath: string;
     /** Set when --company disagreed with the server's company. */
     companyMismatch?: string;
+    /** True when this enrolled beside a person's session in its own directory. */
+    local: boolean;
+    /** The tree this identity lives in. */
+    agentDir: string;
 }
 /** Pure-ish orchestration so tests can drive it without a TTY or network. */
 export declare function enrollHost(opts: EnrollOptions, deps?: EnrollDeps): Promise<EnrollResult>;

package/dist/commands/agent-enroll.js

@@ -22,7 +22,7 @@ import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-s
 import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
-import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { DEFAULT_LOCAL_AGENT_NAME, agentKitPaths, localAgentDir, } from "../lib/agent-kit/paths.js";
 export const ENROLL_PATH = "/v1/agents/enroll";
 /** Canonical code: un-grouped, uppercase (server hashes exactly this). */
 export function normalizeEnrollmentCode(raw) {
@@ -63,9 +63,14 @@ export function refusalMessage(existing) {
         case "none":
             return null;
         case "human":
+            // Reached only when a caller pins the tree (HQ_AGENT_DIR / --dir) at a
+            // home that would sit on top of a person's login. The unpinned path
+            // enrolls into a sibling directory instead of refusing — see
+            // resolveEnrollTarget.
             return (`A human HQ session exists at ${existing.file}. An agent identity must not ` +
-                `share a host account with a person's login. Run enrollment under a dedicated ` +
-                `user (or container), or pass --replace to enroll anyway — the human session ` +
+                `share a host account with a person's login. Enroll into a directory of its ` +
+                `own (drop HQ_AGENT_DIR and this happens automatically, or pass ` +
+                `--name <bot>), or pass --replace to enroll here anyway — the human session ` +
                 `file is left untouched and never read.`);
         case "machine":
             return (`This host already has a machine identity at ${existing.file}` +
@@ -169,10 +174,49 @@ function parseEnrollResponse(raw) {
         },
     };
 }
+/**
+ * Where this enrollment should write, given what already lives on the host.
+ *
+ * A bot that runs on its owner's own computer is the common case, not an
+ * error: the machine has the owner's HQ session, and the two identities have
+ * to coexist. So an unpinned enrollment onto such a host does NOT refuse and
+ * does NOT overwrite anything — it moves into `~/.hq-agent/<name>/`, its own
+ * tree with its own credentials, key, state and logs. The person's session
+ * file is neither read nor touched, and `hq agent …` finds the bot's tree on
+ * its own afterwards (see agentDir).
+ */
+export function resolveEnrollTarget(opts, env = process.env, home = os.homedir()) {
+    const pinned = Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+    if (opts.name) {
+        const dir = localAgentDir(validateLocalAgentName(opts.name), home);
+        return { paths: agentKitPaths(home, { ...env, HQ_AGENT_DIR: dir }), local: true };
+    }
+    const base = agentKitPaths(home, env);
+    // A pinned tree is the caller's explicit choice; --replace is an explicit
+    // choice too. Neither gets silently redirected.
+    if (pinned || opts.replace)
+        return { paths: base, local: false };
+    if (detectExistingIdentity(base, env).kind !== "human") {
+        return { paths: base, local: false };
+    }
+    const dir = localAgentDir(DEFAULT_LOCAL_AGENT_NAME, home);
+    return { paths: agentKitPaths(home, { ...env, HQ_AGENT_DIR: dir }), local: true };
+}
+/** Lowercase slug, so the directory name can never escape `~/.hq-agent`. */
+export function validateLocalAgentName(name) {
+    const trimmed = (name ?? "").trim();
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/.test(trimmed) || trimmed.includes("--")) {
+        throw new EnrollError(`Invalid --name "${name}": use 1–40 lowercase letters, digits and single hyphens (e.g. "grokbot").`);
+    }
+    return trimmed;
+}
 /** Pure-ish orchestration so tests can drive it without a TTY or network. */
 export async function enrollHost(opts, deps = {}) {
     const env = deps.env ?? process.env;
-    const paths = deps.paths ?? agentKitPaths(os.homedir(), env);
+    const target = deps.paths
+        ? { paths: deps.paths, local: false }
+        : resolveEnrollTarget({ name: opts.name, replace: opts.replace }, env);
+    const paths = target.paths;
     const doFetch = deps.fetch ?? fetch;
     const apiBaseUrl = (opts.apiBaseUrl ?? env.HQ_VAULT_API_URL ?? DEFAULT_VAULT_API_URL).replace(/\/+$/, "");
     const code = normalizeEnrollmentCode(opts.code);
@@ -224,6 +268,8 @@ export async function enrollHost(opts, deps = {}) {
     };
     writeMachineCreds(paths, creds);
     return {
+        local: target.local,
+        agentDir: paths.agentDir,
         agentUid: parsed.agentUid,
         companySlug: parsed.companySlug,
         companyUid: parsed.companyUid,
@@ -241,6 +287,7 @@ export function registerAgentEnrollCommand(agent) {
         .description("Enroll this host as an external HQ agent using a one-time code")
         .option("--company <slug>", "Expected company slug (warns when the code belongs elsewhere)")
         .option("--replace", "Overwrite an existing machine identity on this host")
+        .option("--name <bot>", "Enroll into ~/.hq-agent/<bot>/ — for a bot sharing a computer with its owner")
         .option("--api-base-url <url>", "hq-pro control plane (default: HQ_VAULT_API_URL or production)")
         .action(async (code, opts) => {
         try {
@@ -249,8 +296,16 @@ export function registerAgentEnrollCommand(agent) {
                 company: opts.company,
                 replace: opts.replace,
                 apiBaseUrl: opts.apiBaseUrl,
+                name: opts.name,
             });
             console.log(chalk.green(`Enrolled as ${result.agentUid} in ${result.companySlug}.`));
+            if (result.local) {
+                // Say it plainly: this host belongs to a person, and the bot is a
+                // guest on it. Nothing of theirs was read, moved or overwritten.
+                console.log(chalk.dim(`  This computer already has a person signed in, so this agent lives in its own\n` +
+                    `  directory beside them: ${result.agentDir}. Their session was not read or changed.\n` +
+                    `  Every hq agent command finds this tree on its own — no environment to set.`));
+            }
             console.log(`  host fingerprint: ${result.hostFingerprint}`);
             console.log(`  credentials:      ${result.credsPath} (0600)`);
             console.log(`  host key:         ${result.hostKeyPath} (0600)`);
@@ -260,8 +315,10 @@ export function registerAgentEnrollCommand(agent) {
             }
             console.log("");
             console.log("Next:");
-            console.log("  hq whoami                # should report the agent identity");
-            console.log("  hq agent kit install     # sync, work-mesh, inbox and heartbeat services");
+            console.log(result.local
+                ? "  hq agent probe           # its first line reports this agent, not you"
+                : "  hq whoami                # should report the agent identity");
+            console.log("  hq agent kit install     # inbox poller and heartbeat services");
             console.log("  hq agent probe           # end-to-end check, reported to the console");
         }
         catch (err) {

package/dist/commands/agent.js

@@ -8,6 +8,9 @@
  *   hq agent mcp                  stdio MCP server for the bot framework
  *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
+import * as os from "node:os";
+import { adoptAgentIdentityEnv } from "../lib/agent-kit/adopt-identity.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { registerAgentEnrollCommand } from "./agent-enroll.js";
 import { registerAgentInboxCommand } from "./agent-inbox.js";
 import { registerAgentKitCommand } from "./agent-kit.js";
@@ -16,7 +19,18 @@ import { registerAgentProbeCommand } from "./agent-probe.js";
 export function registerAgentCommand(program) {
     const agent = program
         .command("agent")
-        .description("Enroll and run this host as an external HQ agent");
+        .description("Enroll and run this host as an external HQ agent")
+        // A bot that shares a computer with its owner keeps its identity in its
+        // own directory. Publish that tree to the environment before any
+        // subcommand runs, so the CLI and hq-cloud both mint as the AGENT rather
+        // than falling back to the one fixed path — and, on a person's computer,
+        // to the person. Enroll is exempt: it is the command that decides where
+        // the tree goes.
+        .hook("preAction", (_thisCommand, actionCommand) => {
+        if (actionCommand.name() === "enroll")
+            return;
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    });
     registerAgentEnrollCommand(agent);
     registerAgentKitCommand(agent);
     registerAgentProbeCommand(agent);

package/dist/commands/cloud-provision.js

@@ -513,6 +513,52 @@ export async function provisionCompany(options) {
         createdEntity = true;
         log(`created vault entity uid=${entity.uid}`);
     }
+    // hq-pro auto-suffixes a company slug when another owner already holds the
+    // bare name (`<slug>-<ownerTag>`). `/entity/check-slug/me` only looks at the
+    // caller's namespace, so it reports "available" and we POST; the server then
+    // returns a different slug. Writing companies/<requested>/.hq/config.json
+    // with the requested slug (or syncing with --company <assigned>) leaves the
+    // local folder and the cloud slug pointing at two different paths — share()
+    // derives syncRoot from ctx.slug, so the company can never be pushed.
+    // Fail before any local write. Retire a just-created entity so we do not
+    // leave a suffixed orphan.
+    if (entity.slug !== options.slug) {
+        const assigned = entity.slug || "(missing)";
+        let retired = false;
+        if (createdEntity) {
+            try {
+                await vaultClient.softDeleteCompany(entity.uid);
+                retired = true;
+                log(`retired vault entity uid=${entity.uid} — assigned slug ${assigned} differs from requested ${options.slug}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log(`failed to retire mismatched vault entity uid=${entity.uid}: ${msg}`);
+            }
+        }
+        const retireNote = retired
+            ? `The just-created entity ${entity.uid} was retired.`
+            : createdEntity
+                ? `Retire entity ${entity.uid} with \`hq cloud retire company\`, then retry after the original slug is free.`
+                : `Existing entity ${entity.uid} was not modified.`;
+        throw new ProvisionError(1, `Cloud assigned slug "${assigned}" instead of requested "${options.slug}". ` +
+            `Local folder is companies/${options.slug}; sync derives the company folder from the cloud slug, so this company cannot be pushed. ` +
+            `${retireNote} Ask an admin to release the original slug, or rename the local folder to "${assigned}" and re-run.`, {
+            ok: false,
+            company_slug: options.slug,
+            cloud_uid: entity.uid,
+            bucket_name: entity.bucketName ?? "",
+            vault_api_url: options.vaultApiUrl,
+            kms_key_id: entity.kmsKeyId ?? null,
+            created_entity: createdEntity,
+            manifest_patched: false,
+            config_written: false,
+            initial_sync: {
+                ok: false,
+                error: `assigned slug "${assigned}" differs from requested "${options.slug}"`,
+            },
+        });
+    }
     if (!entity.bucketName) {
         // Vault returned an entity without a bucket — this would happen if the
         // provisioning Lambda asynchronously failed. We have a `cloud_uid` but

package/dist/commands/mesh.js

@@ -12,7 +12,7 @@ import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveMembershipCompanies, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, getDefaultCompany, readDeviceConfig, recordMigrationCapabilitySnapshot, setDefaultCompany, } from "../lib/work-context/config.js";
-import { DefaultCompanyLockedError, DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
+import { DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
 import { CLI_KIND_TO_SCHEMA, resolveEnqueueSessionId, } from "../lib/mesh/live/index.js";
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
@@ -375,7 +375,7 @@ async function runContextDefaultGet(opts) {
 }
 async function runContextDefaultSet(slug, opts) {
     const root = workContextHomeRoot();
-    void opts.company; // retained for CLI compatibility; unlock is memberships-wide
+    void opts.company; // retained for CLI compatibility
     let token;
     try {
         token = await requireToken();
@@ -383,42 +383,38 @@ async function runContextDefaultSet(slug, opts) {
     catch {
         token = undefined;
     }
-    // US-017B: unlock only when EVERY active membership advertises migration.
+    // Migration remains useful diagnostic context, but it must never prevent a
+    // verified member from choosing their own device-local preference.
     let migrationCapability = false;
+    let migrationWarning;
     if (token) {
         const probe = await probeMigrationCapabilityForMemberships(token);
         recordMigrationCapabilitySnapshot(probe, { root });
         migrationCapability = probe.unlocked;
-        if (probe.offline && !opts.allowWithoutMigration) {
-            console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (offline or not logged in)"));
-            process.exitCode = 1;
-            return;
+        if (probe.offline) {
+            migrationWarning =
+                "Warning: migration capability could not be checked; membership for the selected company will still be verified.";
         }
-        if (!probe.unlocked && !opts.allowWithoutMigration) {
+        else if (!probe.unlocked) {
             const detail = probe.companies.length === 0
                 ? "no active memberships"
                 : probe.companies
                     .filter((c) => !c.migration)
                     .map((c) => c.companySlug || c.companyUid)
                     .join(", ");
-            console.error(chalk.red(`DEFAULT_COMPANY_LOCKED: migration capability is not true for every company you belong to (${detail || "locked"})`));
-            process.exitCode = 1;
-            return;
+            migrationWarning =
+                `Warning: migration capability is mixed or unavailable for ${detail || "some memberships"}; ` +
+                    "the selected company can still be set because membership is verified directly.";
         }
     }
-    else if (!opts.allowWithoutMigration) {
-        console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (no Cognito session)"));
-        process.exitCode = 1;
-        return;
-    }
-    if (!migrationCapability && opts.allowWithoutMigration) {
-        console.error(chalk.yellow("Warning: --allow-without-migration bypasses DEFAULT_COMPANY_LOCKED; a wrong default is hard to correct until migration is available for every company you belong to."));
+    else {
+        migrationWarning =
+            "Warning: migration capability could not be checked without a Cognito session; membership for the selected company must still be verified.";
     }
     try {
         const cfg = await setDefaultCompany(slug, {
             root,
             migrationCapability,
-            allowWithoutMigration: opts.allowWithoutMigration,
             validateMembership: async (candidate) => {
                 if (!token) {
                     throw new DefaultCompanyUnavailableError(`Cannot verify membership for company "${candidate}" (no Cognito session; offline or not logged in)`);
@@ -437,15 +433,16 @@ async function runContextDefaultSet(slug, opts) {
             },
         });
         if (opts.json) {
-            console.log(JSON.stringify({ ok: true, config: cfg }, null, 2));
+            console.log(JSON.stringify({ ok: true, config: cfg, migrationWarning }, null, 2));
             return;
         }
         const stored = cfg.defaultCompany;
         console.log(`Default company set to ${stored?.slug ?? slug}${stored?.uid ? ` (${stored.uid})` : ""}`);
+        if (migrationWarning)
+            console.error(chalk.yellow(migrationWarning));
     }
     catch (err) {
-        if (err instanceof DefaultCompanyLockedError ||
-            err instanceof DefaultCompanyUnavailableError) {
+        if (err instanceof DefaultCompanyUnavailableError) {
             console.error(chalk.red(`${err.code}: ${err.message}`));
             process.exitCode = 1;
             return;
@@ -715,13 +712,16 @@ async function runSessionStatus(opts) {
     }
     const { token, company } = await withCompany({ company: opts.company });
     const live = await fetchCompanyLive(token, company.companyUid);
+    const unattributedEvents = collectDaemonDoctor().unattributedEvents;
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "session-status", company, live }, null, 2));
+        console.log(JSON.stringify({ ok: true, action: "session-status", company, live, unattributedEvents }, null, 2));
         return;
     }
     for (const line of formatCompanyLiveTable(live, company.companySlug || company.companyUid)) {
         console.log(line);
     }
+    console.log(`unattributed events: ${unattributedEvents.total} ` +
+        `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
 }
 const HARNESSES = new Set([
     "claude-code",
@@ -1085,10 +1085,10 @@ export function registerMeshCommand(program) {
         .action((opts) => wrap(() => runContextDefaultGet(opts))());
     def
         .command("set")
-        .description("Set the device default company slug (unlocked when migration is true for every membership)")
+        .description("Set the device default company slug after verifying membership")
         .argument("<slug>", "Company slug")
-        .option("--allow-without-migration", "Bypass DEFAULT_COMPANY_LOCKED with a warning")
-        .option("--company <slug|uid>", "Deprecated no-op; unlock probes every active membership")
+        .option("--allow-without-migration", "Deprecated compatibility no-op; selected-company membership is always verified")
+        .option("--company <slug|uid>", "Deprecated no-op; the selected company is verified directly")
         .option("--json", "Print machine-readable JSON")
         .action((slug, opts) => wrap(() => runContextDefaultSet(slug, opts))());
     def

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,51 @@
+/**
+ * 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";
+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;
+    }
+    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/paths.d.ts

@@ -13,6 +13,14 @@
  * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
  * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
  * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ *
+ * LOCAL BOTS. A bot that runs on its owner's own computer cannot use the
+ * default tree: that machine already has the owner's HQ session, and an agent
+ * identity must not share a host account with a person's login. Such a bot
+ * enrolls into a SIBLING directory instead — `~/.hq-agent/<name>/` with the
+ * same layout — and every `hq agent …` command finds it here, so the bot does
+ * not have to carry environment variables around to be itself. Two or more
+ * local agents are ambiguous on purpose: pick one with `HQ_AGENT_DIR`.
  */
 export declare const AGENT_DIR_ENV = "HQ_AGENT_DIR";
 export declare const HOST_KEY_NAME = "host-key";
@@ -35,6 +43,18 @@ export interface AgentKitPaths {
     skillsDir: string;
     lastHeartbeatPath: string;
 }
+/** Default name for a bot enrolled alongside its owner's own session. */
+export declare const DEFAULT_LOCAL_AGENT_NAME = "local";
+/** `~/.hq-agent` — the root, whether or not it holds an identity itself. */
+export declare function agentRootDir(home?: string): string;
+/** `~/.hq-agent/<name>` — an isolated home for one local bot. */
+export declare function localAgentDir(name: string, home?: string): string;
+/**
+ * Local agent homes under `~/.hq-agent`, by name, oldest name order. A
+ * directory counts only once it holds a creds file, so a half-written tree is
+ * never mistaken for an identity.
+ */
+export declare function listLocalAgentDirs(home?: string): string[];
 export declare function agentDir(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function agentKitPaths(home?: string, env?: NodeJS.ProcessEnv): AgentKitPaths;
 export declare function componentStatePath(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent): string;