@indigoai-us/hq-cli 5.114.0 → 5.115.1

package/dist/commands/onboard-bot-membership.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A company created from a local bot's conversation is owned by the person
+ * (the turn runs with the owner's sign-in), so the bot that helped create it
+ * is not in it. The bot passes its own id along (HQ_BOT_AGENT_UID — an id,
+ * never a credential), and `hq onboard create-company` adds that bot as a
+ * member right after, so it can keep helping inside the new company.
+ *
+ * Best effort: a failure here never fails the company that was just created.
+ */
+import { inviteMember } from "./members.js";
+export declare const HQ_BOT_AGENT_UID_ENV = "HQ_BOT_AGENT_UID";
+/** The bot to add to `companyUid`, or null when this is not a bot's turn. */
+export declare function botToAddAfterCreateCompany(env: NodeJS.ProcessEnv, companyUid: string | undefined): {
+    agentUid: string;
+    companyUid: string;
+} | null;
+export interface AddBotDeps {
+    invite: typeof inviteMember;
+    callerUid: (token: string) => Promise<string>;
+}
+/** Add the bot as a member. Returns a one-line outcome for the log; never throws. */
+export declare function addBotToNewCompany(input: {
+    agentUid: string;
+    companyUid: string;
+    token: string;
+}, deps?: AddBotDeps): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+//# sourceMappingURL=onboard-bot-membership.d.ts.map

package/dist/commands/onboard-bot-membership.js

@@ -0,0 +1,40 @@
+/**
+ * A company created from a local bot's conversation is owned by the person
+ * (the turn runs with the owner's sign-in), so the bot that helped create it
+ * is not in it. The bot passes its own id along (HQ_BOT_AGENT_UID — an id,
+ * never a credential), and `hq onboard create-company` adds that bot as a
+ * member right after, so it can keep helping inside the new company.
+ *
+ * Best effort: a failure here never fails the company that was just created.
+ */
+import { getCallerPersonUid, inviteMember } from "./members.js";
+export const HQ_BOT_AGENT_UID_ENV = "HQ_BOT_AGENT_UID";
+const AGENT_UID_RE = /^agt_[A-Za-z0-9]{1,64}$/;
+/** The bot to add to `companyUid`, or null when this is not a bot's turn. */
+export function botToAddAfterCreateCompany(env, companyUid) {
+    const agentUid = env[HQ_BOT_AGENT_UID_ENV]?.trim() ?? "";
+    const company = companyUid?.trim() ?? "";
+    if (!AGENT_UID_RE.test(agentUid) || !company.startsWith("cmp_"))
+        return null;
+    return { agentUid, companyUid: company };
+}
+const defaultDeps = { invite: inviteMember, callerUid: getCallerPersonUid };
+/** Add the bot as a member. Returns a one-line outcome for the log; never throws. */
+export async function addBotToNewCompany(input, deps = defaultDeps) {
+    try {
+        const callerUid = await deps.callerUid(input.token);
+        await deps.invite({
+            target: input.agentUid,
+            role: "member",
+            sendEmail: false,
+            companyUid: input.companyUid,
+            callerUid,
+            token: input.token,
+        });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=onboard-bot-membership.js.map

package/dist/commands/onboard.js

@@ -25,6 +25,7 @@ import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 import { planOnboardJoin } from "./onboard-join.js";
 import { buildCreateCompanyWarning } from "./onboard-warning.js";
+import { addBotToNewCompany, botToAddAfterCreateCompany } from "./onboard-bot-membership.js";
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -63,6 +64,15 @@ export function registerOnboardCommand(program) {
                 console.error(chalk.red(`\n✗ Onboarding failed: ${result.error}`));
                 process.exit(1);
             }
+            // Created from a local bot's conversation: keep that bot in the company.
+            const bot = botToAddAfterCreateCompany(process.env, result.result?.companyUid);
+            if (bot) {
+                const added = await addBotToNewCompany({ ...bot, token: accessToken });
+                if (added.ok)
+                    console.log(chalk.green(`✓ Added your bot (${bot.agentUid}) to ${options.name} as a member`));
+                else
+                    console.log(chalk.yellow(`! Could not add your bot (${bot.agentUid}) to ${options.name}: ${added.reason}. Invite it later with: hq members invite ${bot.agentUid} --company ${options.slug} --role member`));
+            }
         }
         catch (err) {
             console.error(chalk.red("\n✗ Error:"), err instanceof Error ? err.message : String(err));

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

@@ -45,6 +45,8 @@ export interface AgentRecord {
     ownerUid?: string | null;
     computeMode?: string;
     botKind?: string;
+    /** Company bots: the `cmp_` uids the server made it a member of. */
+    companyMemberships?: string[];
     online?: boolean;
     runtime?: {
         status?: string;
@@ -180,9 +182,18 @@ export declare class BotApi {
         promotion: BotPromotionState;
         upload: BotPromotionUpload;
     }>;
+    /**
+     * POST /v1/agents — a local bot identity. `kind` is the bot kind the cloud
+     * stores and enforces ("personal" acts as its owner through mirror-owner;
+     * "company" is evaluated as itself through its memberships). Default personal.
+     */
     createLocalBot(input: {
         name: string;
         slug?: string;
+        kind?: "personal" | "company";
+        /** Company bots: the company it acts for, plus any further companies. The server makes it a member of each. */
+        companyUid?: string;
+        companyMemberships?: string[];
     }): Promise<{
         agent: AgentRecord;
         identity: {

package/dist/lib/bot/api.js

@@ -180,6 +180,11 @@ export class BotApi {
     async promotionUpload(agentUid, input) {
         return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote/snapshot-upload`, { method: "POST", body: input })).body;
     }
+    /**
+     * POST /v1/agents — a local bot identity. `kind` is the bot kind the cloud
+     * stores and enforces ("personal" acts as its owner through mirror-owner;
+     * "company" is evaluated as itself through its memberships). Default personal.
+     */
     async createLocalBot(input) {
         const { body } = await this.call("/v1/agents", {
             method: "POST",
@@ -187,7 +192,9 @@ export class BotApi {
                 name: input.name,
                 ...(input.slug ? { slug: input.slug } : {}),
                 computeMode: "local",
-                botKind: "personal",
+                botKind: input.kind ?? "personal",
+                ...(input.companyUid ? { companyUid: input.companyUid } : {}),
+                ...(input.companyMemberships?.length ? { companyMemberships: input.companyMemberships } : {}),
                 role: "local-bot",
             },
         });

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

@@ -4,6 +4,31 @@
 export declare const BOT_RUNTIMES: readonly ["claude", "codex", "grok"];
 export type BotRuntimeId = (typeof BOT_RUNTIMES)[number];
 export declare function isBotRuntimeId(value: unknown): value is BotRuntimeId;
+/**
+ * What a bot is (owner decisions, 2026-09-15):
+ * - "personal": acts as its owner. Every turn (DMs, kickoff, rooms) runs with
+ *   the owner's sign-in, so it reaches everything the owner can and can create
+ *   companies, bots, invites and shares for them. Setup is a personal bot.
+ * - "company": acts as itself with its own identity, like a cloud agent. It is
+ *   a member of one or more companies (`companies`) and reaches only theirs.
+ */
+export declare const BOT_KINDS: readonly ["personal", "company"];
+export type BotKind = (typeof BOT_KINDS)[number];
+export declare function isBotKind(value: unknown): value is BotKind;
+/** The id of HQ's bundled setup worker; a bot running it is always personal. */
+export declare const SETUP_BOT_WORKER_ID = "setup";
+/** Trim, validate and dedupe company slugs; throws an expected error on a bad one. */
+export declare function normalizeBotCompanies(values: readonly string[] | undefined): string[];
+/**
+ * The kind a bot runs as. A bot.json without a `kind` was created before
+ * kinds existed: every such bot's cloud row says botKind "personal", it acted
+ * as its owner, and it was never invited into a company — so it is personal,
+ * even one running a company worker (its `companySlug` is still the company
+ * bind of its turns, not a membership). Setup is always personal.
+ */
+export declare function effectiveBotKind(config: Pick<BotConfig, "kind" | "workerId">): BotKind;
+/** The companies a bot belongs to (empty for a personal bot: its owner's memberships apply). */
+export declare function effectiveBotCompanies(config: Pick<BotConfig, "kind" | "companies" | "workerId">): string[];
 /** Longest `intro` (first-start hello DM) a bot may store. */
 export declare const BOT_INTRO_MAX_CHARS = 500;
 /** Longest `kickoff` (first-start model turn prompt) a bot may store. */
@@ -48,6 +73,14 @@ export interface BotConfig {
     /** The person (prs_) who created and owns the bot. */
     ownerUid: string;
     runtime: BotRuntimeId;
+    /**
+     * "personal" (acts as its owner everywhere) or "company" (acts as itself,
+     * member of `companies`). Missing on bots created before kinds existed:
+     * see effectiveBotKind for the rule readBotConfig applies.
+     */
+    kind?: BotKind;
+    /** Company bots only: slugs of the companies the bot is a member of. */
+    companies?: string[];
     /** Optional model override handed to the runtime CLI (unset = the CLI's own default). */
     model?: string;
     /** Thinking level for the runtime CLI (see BOT_EFFORT_LEVELS; unset = DEFAULT_BOT_EFFORT). */
@@ -95,6 +128,8 @@ export interface BotConfig {
     enabled: boolean;
     /** Set once the bot has introduced itself to the owner (US-008 intro). */
     introSentAt?: string;
+    /** The kickoff could not run because the coding tool needed a sign-in; it runs once that works. */
+    kickoffPendingSignIn?: boolean;
 }
 export declare function readBotConfig(dir: string): BotConfig | null;
 export declare function writeBotConfig(dir: string, config: BotConfig): void;

package/dist/lib/bot/config.js

@@ -8,6 +8,62 @@ export const BOT_RUNTIMES = ["claude", "codex", "grok"];
 export function isBotRuntimeId(value) {
     return typeof value === "string" && BOT_RUNTIMES.includes(value);
 }
+/**
+ * What a bot is (owner decisions, 2026-09-15):
+ * - "personal": acts as its owner. Every turn (DMs, kickoff, rooms) runs with
+ *   the owner's sign-in, so it reaches everything the owner can and can create
+ *   companies, bots, invites and shares for them. Setup is a personal bot.
+ * - "company": acts as itself with its own identity, like a cloud agent. It is
+ *   a member of one or more companies (`companies`) and reaches only theirs.
+ */
+export const BOT_KINDS = ["personal", "company"];
+export function isBotKind(value) {
+    return typeof value === "string" && BOT_KINDS.includes(value);
+}
+/** The id of HQ's bundled setup worker; a bot running it is always personal. */
+export const SETUP_BOT_WORKER_ID = "setup";
+/** Company slugs are path segments and cloud lookups: keep them plain. */
+const COMPANY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Trim, validate and dedupe company slugs; throws an expected error on a bad one. */
+export function normalizeBotCompanies(values) {
+    const out = [];
+    for (const raw of values ?? []) {
+        const slug = (raw ?? "").trim();
+        if (!slug)
+            continue;
+        if (!COMPANY_SLUG_RE.test(slug) || slug === "personal") {
+            throw Object.assign(new Error(`"${slug}" is not a company slug (letters, digits, . _ -).`), { expected: true });
+        }
+        if (!out.includes(slug))
+            out.push(slug);
+    }
+    return out;
+}
+/**
+ * The kind a bot runs as. A bot.json without a `kind` was created before
+ * kinds existed: every such bot's cloud row says botKind "personal", it acted
+ * as its owner, and it was never invited into a company — so it is personal,
+ * even one running a company worker (its `companySlug` is still the company
+ * bind of its turns, not a membership). Setup is always personal.
+ */
+export function effectiveBotKind(config) {
+    if (config.workerId === SETUP_BOT_WORKER_ID)
+        return "personal";
+    return isBotKind(config.kind) ? config.kind : "personal";
+}
+/** The companies a bot belongs to (empty for a personal bot: its owner's memberships apply). */
+export function effectiveBotCompanies(config) {
+    if (effectiveBotKind(config) !== "company")
+        return [];
+    // Tolerant on read: a malformed slug is dropped, never a reason to lose the bot.
+    const listed = [];
+    for (const raw of config.companies ?? []) {
+        const slug = typeof raw === "string" ? raw.trim() : "";
+        if (slug && COMPANY_SLUG_RE.test(slug) && !listed.includes(slug))
+            listed.push(slug);
+    }
+    return listed;
+}
 /** Longest `intro` (first-start hello DM) a bot may store. */
 export const BOT_INTRO_MAX_CHARS = 500;
 /** Longest `kickoff` (first-start model turn prompt) a bot may store. */
@@ -105,10 +161,21 @@ export function readBotConfig(dir) {
         }
         if (!isBotRuntimeId(raw.runtime))
             return null;
-        const { intro: rawIntro, kickoff: rawKickoff, ...rest } = raw;
+        const { intro: rawIntro, kickoff: rawKickoff, kind: _kind, companies: _companies, ...rest } = raw;
         const intro = typeof rawIntro === "string" && rawIntro.trim() ? rawIntro : undefined;
         const kickoff = typeof rawKickoff === "string" && rawKickoff.trim() ? rawKickoff : undefined;
-        return { ...rest, ...(intro ? { intro } : {}), ...(kickoff ? { kickoff } : {}), enabled: raw.enabled !== false };
+        // Older bot.json files carry no kind: they read (and, on the first patch,
+        // persist) as personal, so every reader sees a kind.
+        const kind = effectiveBotKind(raw);
+        const companies = effectiveBotCompanies(raw);
+        return {
+            ...rest,
+            kind,
+            ...(kind === "company" ? { companies } : {}),
+            ...(intro ? { intro } : {}),
+            ...(kickoff ? { kickoff } : {}),
+            enabled: raw.enabled !== false,
+        };
     }
     catch {
         return null;

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

@@ -16,6 +16,7 @@
  *
  * Pure over an injected reader so tests never touch the real HQ.
  */
+import type { BotKind } from "./config.js";
 export declare const MEMORY_FILE_BUDGET_BYTES: number;
 export declare const MEMORY_TOTAL_BUDGET_BYTES: number;
 export declare const CONTEXT_FILE_BUDGET_BYTES: number;
@@ -84,9 +85,20 @@ export interface BuildSystemPromptInput {
     workerSource?: "scaffold" | "worker";
     workerId?: string;
     companySlug?: string;
+    /** "personal" (acts as its owner everywhere) or "company" (acts as itself). Default personal. */
+    kind?: BotKind;
+    /** Company bots: the slugs of the companies the bot is a member of. */
+    companies?: string[];
     /** hqRoot-relative (default `${workerDir}/memory`) or absolute. */
     memoryDir?: string;
 }
+/**
+ * One paragraph saying which kind of bot this is and what that means for the
+ * `hq` commands it runs. The owner's decision (2026-09-15): a personal bot
+ * 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;
 /**
  * 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
@@ -94,7 +106,7 @@ export interface BuildSystemPromptInput {
  */
 export declare function buildSystemPrompt(input: BuildSystemPromptInput): string;
 /** Fixed text sent to any non-owner who DMs the bot (never reaches the model). */
-export declare function nonOwnerRefusalText(botName: string): string;
+export declare function nonOwnerRefusalText(botName: string, kind?: BotKind): string;
 /**
  * The one-time introduction the bot DMs its owner when it first comes online.
  * A bot created with `--intro` sends that text verbatim instead.

package/dist/lib/bot/prompt.js

@@ -229,6 +229,32 @@ export function readPromptSources(hqRoot, workerDir, io = defaultPromptFs, opts
     }
     return { workerYaml, persona: read("persona.md"), memory };
 }
+/**
+ * One paragraph saying which kind of bot this is and what that means for the
+ * `hq` commands it runs. The owner's decision (2026-09-15): a personal bot
+ * acts as its owner everywhere; a company bot acts as itself and cannot
+ * create anything for the owner.
+ */
+export function botKindParagraph(input) {
+    const kind = input.kind ?? "personal";
+    if (kind === "company") {
+        const list = (input.companies ?? []).filter((c) => c.trim());
+        const members = list.length > 0 ? list.map((c) => `\`${c}\``).join(", ") : "(none recorded yet)";
+        return (`You are a COMPANY bot: you act as yourself, ${input.agentUid}, with your own identity and your own permissions — never as your owner. ` +
+            `You are a member of these companies: ${members}. You can only reach those companies' files, memory, and secrets; ` +
+            `people in those companies can @mention you in their rooms, and your owner can message you directly, but you act as yourself there too. ` +
+            `Every \`hq\` command you run — in direct messages and in rooms — runs with your own sign-in: \`hq whoami\` and membership lookups describe you, the bot. ` +
+            `You cannot create a company, a bot, an invite or a share on your owner's behalf, and you cannot reach companies you are not a member of. ` +
+            `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.`);
+    }
+    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.`);
+}
 /**
  * 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
@@ -240,23 +266,19 @@ export function buildSystemPrompt(input) {
     const worker = input.sources.worker;
     const workerId = input.workerId ?? worker?.id ?? path.basename(input.workerDir);
     const company = input.companySlug ?? worker?.company;
+    const kind = input.kind ?? "personal";
     const parts = [];
     const opening = workerMode
-        ? `You are "${input.botName}", a personal HQ bot running the company worker \`${workerId}\`${company ? ` for \`${company}\`` : ""}, locally on your owner's computer.` +
+        ? `You are "${input.botName}", a ${kind} HQ bot running the company worker \`${workerId}\`${company ? ` for \`${company}\`` : ""}, locally on your owner's computer.` +
             (worker?.name ? ` The worker is "${worker.name}".` : "") +
             (worker?.description ? ` ${worker.description}` : "") +
             `\nYou work only inside \`${company ?? "this company"}\`'s context: its files, policies, services, and credentials — never another company's.`
-        : `You are "${input.botName}", a personal HQ bot that runs locally on your owner's computer.`;
+        : `You are "${input.botName}", a ${kind} HQ bot that runs locally on your owner's computer.`;
     parts.push(`${opening}\n` +
-        `Your HQ identity is ${input.agentUid}. Your owner is ${input.ownerUid}; only your owner can message you.\n` +
-        `You act with your owner's permissions, and every tool and command is pre-approved for you — do not ask for approval, just do the work. ` +
-        `Their HQ folder is ${input.hqRoot}; it is your working directory, so its files, skills, and \`hq\` commands are available directly.\n` +
-        `\`hq\` commands you run authenticate as you, the bot (${input.agentUid}), not as your owner: \`hq whoami\`, membership and company lookups describe the bot, ` +
-        `and a bot usually belongs to no company. Never use them to say who your owner is or which companies they belong to. ` +
-        `The exception is \`hq bot\` (create, list, rm, promote): it always acts as your owner, so you can create a bot for them when they ask; its owner is your owner. ` +
-        `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: in a room, never state which companies your owner belongs to.\n` +
+        `Your HQ identity is ${input.agentUid}. Your owner is ${input.ownerUid}; only your owner can send you direct messages.\n` +
+        `${kind === "personal" ? "You act with your owner's permissions" : "You act with your own permissions"}, and every tool and command is pre-approved for you — do not ask for approval, just do the work. ` +
+        `${kind === "personal" ? "Their" : "Your owner's"} HQ folder is ${input.hqRoot}; it is your working directory, so its files, skills, and \`hq\` commands are available directly.\n` +
+        `${botKindParagraph(input)}\n` +
         `Each message you receive is a direct message from your owner. Whatever you print as your final answer is sent back as a DM reply, ` +
         `so answer the person directly, in plain language, and keep it as short as the request allows. ` +
         `Do not narrate tool use or repeat the question. If you cannot do something, say so and suggest the nearest thing you can do.\n` +
@@ -311,7 +333,10 @@ export function buildSystemPrompt(input) {
     return `${parts.join("\n\n")}\n`;
 }
 /** Fixed text sent to any non-owner who DMs the bot (never reaches the model). */
-export function nonOwnerRefusalText(botName) {
+export function nonOwnerRefusalText(botName, kind = "personal") {
+    if (kind === "company") {
+        return `Hi — I'm ${botName}, a company bot, and I only take direct messages from my owner. You can @mention me in one of my companies' rooms.`;
+    }
     return `Hi — I'm ${botName}, a personal bot, and I only take messages from my owner. Please reach out to them directly.`;
 }
 /**

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

@@ -26,6 +26,11 @@
  *   started (error, crash, owner stop, restart) posts one "did not finish"
  *   message and is NOT run again — it may already have done outward things.
  *   inflight.json marks the turn in progress so a restart can say so.
+ * - a turn that fails because the coding tool's sign-in no longer works
+ *   (runtime-sign-in.ts) is not a failure of the message: the bot says once
+ *   per conversation that it needs a sign-in, keeps the message un-acked,
+ *   holds new turns, and tries again every SIGN_IN_RETRY_MS (and at once
+ *   after a restart). A turn that works clears it.
  * - failures before the model starts (missing binary) retry with backoff;
  *   5 model failures in 10 minutes → state `failed` and a clean exit (launchd
  *   does not respawn a clean exit). Owner stops never count.
@@ -34,7 +39,7 @@
  */
 import { type OwnerContext } from "./owner-context.js";
 import type { BotApi, InboxItem } from "./api.js";
-import type { BotConfig } from "./config.js";
+import type { BotConfig, BotKind } from "./config.js";
 import { type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
 import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
@@ -79,15 +84,37 @@ export interface BotRunDeps {
     progress?: Pick<ProgressPosterOptions, "coalesceMs" | "minGapMs" | "workingNoticeMs" | "setTimer" | "clearTimer" | "now">;
     /**
      * The owner's verified company context, prepended to every owner DM turn
-     * (never room turns) so the model never mistakes the bot's own (empty)
-     * memberships for its owner's.
+     * of a PERSONAL bot (never room turns, never a company bot's turns) so the
+     * model never mistakes the bot's own (empty) memberships for its owner's.
      * Omitted in tests that do not exercise it.
      */
     ownerContext?: () => Promise<OwnerContext>;
     /** Turns run at once across conversations (default MAX_PARALLEL_TURNS). */
     maxParallelTurns?: number;
+    /** Wait between retries while the coding tool needs a sign-in (default SIGN_IN_RETRY_MS). */
+    signInRetryMs?: number;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
+/**
+ * The environment a model turn's `hq` commands run in.
+ *
+ * The bot process carries its own machine identity in HQ_MACHINE_CREDS_FILE /
+ * HQ_MACHINE_TOKEN_STATE_DIR so its inbox, heartbeat and posts are the bot's.
+ * What a turn inherits depends on the bot's kind:
+ * - A PERSONAL bot acts as its owner on every turn (DMs, the kickoff, rooms):
+ *   everything the owner asks for — a company, a bot, an invite, a share —
+ *   belongs to the owner's account, and the cloud rightly refuses a bot that
+ *   tries to own it ("No person entity found"). Stripping the marker makes
+ *   every `hq` command in the turn use the owner's sign-in, the same one the
+ *   desktop app shares, so no command needs a special case. The bot's id
+ *   (never a credential) rides along in HQ_BOT_AGENT_UID so what the owner
+ *   creates in the turn — a company — can add the bot as a member afterwards.
+ * - A COMPANY bot acts as itself on every turn, like a cloud agent: the
+ *   machine identity stays, and the cloud evaluates it through its own
+ *   company memberships. It never acts as the owner, in DMs or in rooms.
+ * Pure so the rule is unit-testable.
+ */
+export declare function turnEnv(base: NodeJS.ProcessEnv, kind: BotKind, agentUid?: string): NodeJS.ProcessEnv;
 /** The core worker HQ's setup bot runs. */
 export declare const SETUP_WORKER_ID = "setup";
 /** The one message a person gets when a turn on their message did not finish. */