@indigoai-us/hq-cli 5.249.1 → 5.251.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## [Unreleased]
 
+## [5.251.0] — 2026-09-27
+
+## [5.250.0] — 2026-09-27
+
+### Fixed
+
+- A Work Mesh session bound to a project and task keeps the binding episode the
+- An enrolled agent that sets `HQ_AGENT_DIR` now acts as that agent in every
+  command, not only under `hq agent`. `hq dm` and `hq secrets` used to look
+  for a person's session instead, find none, and open a browser sign-in. On
+  the Runneth pilot that hung the first reply for four minutes. Only the
+  explicit variable counts, so a bot living beside its owner on the owner's
+  computer never takes over the owner's commands.
+- On an agent host (Linux, no terminal, no display), a missing session now
+  fails at once with the fix instead of opening a browser sign-in that
+  nobody can complete.
+- `hq agent enroll --name` no longer overrides `HQ_AGENT_DIR`. A bot that
+  pointed its identity at persistent storage had it written under `$HOME`
+  instead, where a rebuild erases it, with a message claiming a person was
+  signed in when nobody was.
+- `wake.log` no longer records the wake command's standard output. A wake
+  command's normal output (a routine record, an echoed prompt) is not
+  diagnostic, and on a share without permissions the log is readable by
+  anything with access to the share. Errors are still logged.
+- Bots now reply in the group or channel a message came from. Their inbox
+  shows the channel id, `hq dm <channelId>` and the `hq_dm_send` tool post by
+  that id (including unnamed group DMs), and the wake and inbox instructions
+  say to answer there. Before, a bot answered a group message with a private
+  DM to the sender, so the group never heard back. The instructions also tell
+  bots not to answer another bot's greetings or sign-offs, so two bots stop
+  acknowledging each other in a loop.
+- An agent whose identity files were moved or copied no longer goes silent an
+  hour later. The credentials file records where the host key lives; when that
+  path is gone and the key sits beside the credentials file, the CLI now points
+  at it before running any agent command. `hq agent probe` also fails when the
+  host key is missing, instead of passing on a cached token and leaving the
+  agent to fail at its next refresh.
+
 ## [5.249.1] — 2026-09-27
 
 ## [5.249.0] — 2026-09-27

package/dist/commands/agent-enroll.js

@@ -204,14 +204,18 @@ function parseEnrollResponse(raw) {
  */
 export function resolveEnrollTarget(opts, env = process.env, home = os.homedir()) {
     const pinned = Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+    // A pinned tree is the environment's explicit choice and wins over --name:
+    // a bot that set HQ_AGENT_DIR to its persistent storage must never be
+    // redirected to a directory under $HOME, which may be erased on rebuild.
+    if (pinned)
+        return { paths: agentKitPaths(home, env), local: false };
     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)
+    // --replace is an explicit choice too; it is not silently redirected.
+    if (opts.replace)
         return { paths: base, local: false };
     if (detectExistingIdentity(base, env).kind !== "human") {
         return { paths: base, local: false };

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

@@ -54,6 +54,8 @@ export interface ProbeDeps {
     listSecrets: (token: string, companyUid: string) => Promise<number>;
     postResult: (token: string, result: ProbeResult) => Promise<number>;
     now?: () => Date;
+    /** Test seam; defaults to fs.existsSync. */
+    hostKeyExists?: (p: string) => boolean;
     sleep?: (ms: number) => Promise<void>;
     nonce?: () => string;
     dmTimeoutMs?: number;

package/dist/commands/agent-probe.js

@@ -63,7 +63,17 @@ export async function runProbe(deps) {
         const claims = peekIdToken(token);
         const uid = claims["custom:entityUid"];
         const type = claims["custom:entityType"];
-        if (type === "agent" && uid === self) {
+        if (type === "agent" && uid === self && !(deps.hostKeyExists ?? fs.existsSync)(deps.creds.hostKeyPath)) {
+            // A cached token hides a missing host key for up to an hour: the probe
+            // used to pass and the agent then went silent at its next refresh.
+            checks.push({
+                name: "whoami",
+                ok: false,
+                detail: `token minted from cache, but there is no host key at ${deps.creds.hostKeyPath}, so the next refresh will fail. Keep host-key beside machine-creds.json, or re-enroll`,
+            });
+            token = null;
+        }
+        else if (type === "agent" && uid === self) {
             checks.push({ name: "whoami", ok: true, detail: `${self} (external, ${deps.creds.companySlug})` });
         }
         else {

package/dist/commands/dm.js

@@ -84,6 +84,13 @@ export function parseChannelName(recipient) {
  * unit-testable.
  */
 export function matchChannelsByName(channels, name) {
+    // A channel id is exact and names nothing else, so it may target any scope,
+    // including an unnamed group DM. Bots reply this way: their inbox carries
+    // the id of the conversation a message arrived in, not its name.
+    const trimmed = name.trim().replace(/^#/, "");
+    if (/^chn_[A-Za-z0-9]+$/.test(trimmed)) {
+        return channels.filter((c) => c.channelId === trimmed);
+    }
     const targetSlug = channelSlug(name);
     const targetName = name.trim().toLowerCase();
     if (!targetSlug && !targetName)

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

@@ -18,6 +18,7 @@
  */
 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";
 /**
@@ -37,6 +38,14 @@ export function adoptAgentIdentityEnv(paths, env = process.env) {
     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

package/dist/lib/agent-kit/creds.d.ts

@@ -75,4 +75,32 @@ export interface ComponentReading {
  * older than `staleAfterMs` reads as `error` — silence is never health.
  */
 export declare function readComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, staleAfterMs: number, now?: () => Date): ComponentReading;
+export type HostKeyPathCheck = {
+    status: "ok";
+    hostKeyPath: string;
+} | {
+    status: "healed";
+    hostKeyPath: string;
+    previous: string;
+} | {
+    status: "missing";
+    hostKeyPath: string;
+} | {
+    status: "no-creds";
+};
+/**
+ * Make the recorded host-key path point at a key that exists.
+ *
+ * The creds file records the key's absolute path, and hq-cloud signs every
+ * token mint with the key at that path. When the identity is moved or copied —
+ * the Runneth pilot copied its files from a disposable $HOME to persistent
+ * storage — the recorded path goes stale, and nothing fails until the cached
+ * token expires up to an hour later. Then every mint fails and the agent goes
+ * silent until someone re-enrolls it.
+ *
+ * The key always travels with the creds file, so when the recorded path is
+ * gone and a key sits beside the creds file, point at that one. The key
+ * itself is never read or copied here; only the recorded path changes.
+ */
+export declare function ensureHostKeyPath(paths: Pick<AgentKitPaths, "machineCredsPath">): HostKeyPathCheck;
 //# sourceMappingURL=creds.d.ts.map

package/dist/lib/agent-kit/creds.js

@@ -26,7 +26,8 @@
  */
 import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
 import * as fs from "node:fs";
-import { componentStatePath } from "./paths.js";
+import * as path from "node:path";
+import { componentStatePath, HOST_KEY_NAME } from "./paths.js";
 import { writePrivateFile, } from "./private-file.js";
 /** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
 export function hostFingerprint(publicPem) {
@@ -130,4 +131,33 @@ export function readComponentStatus(paths, component, staleAfterMs, now = () =>
     }
     return { status: "ok", at };
 }
+/**
+ * Make the recorded host-key path point at a key that exists.
+ *
+ * The creds file records the key's absolute path, and hq-cloud signs every
+ * token mint with the key at that path. When the identity is moved or copied —
+ * the Runneth pilot copied its files from a disposable $HOME to persistent
+ * storage — the recorded path goes stale, and nothing fails until the cached
+ * token expires up to an hour later. Then every mint fails and the agent goes
+ * silent until someone re-enrolls it.
+ *
+ * The key always travels with the creds file, so when the recorded path is
+ * gone and a key sits beside the creds file, point at that one. The key
+ * itself is never read or copied here; only the recorded path changes.
+ */
+export function ensureHostKeyPath(paths) {
+    const creds = readExternalMachineCreds(paths);
+    if (!creds)
+        return { status: "no-creds" };
+    if (fs.existsSync(creds.hostKeyPath))
+        return { status: "ok", hostKeyPath: creds.hostKeyPath };
+    const sibling = path.join(path.dirname(paths.machineCredsPath), HOST_KEY_NAME);
+    if (sibling === creds.hostKeyPath || !fs.existsSync(sibling)) {
+        return { status: "missing", hostKeyPath: creds.hostKeyPath };
+    }
+    const raw = JSON.parse(fs.readFileSync(paths.machineCredsPath, "utf8"));
+    raw.hostKeyPath = sibling;
+    writePrivateFile(paths.machineCredsPath, `${JSON.stringify(raw, null, 2)}\n`, 0o600);
+    return { status: "healed", hostKeyPath: sibling, previous: creds.hostKeyPath };
+}
 //# sourceMappingURL=creds.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -50,6 +50,7 @@ export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean
     attachments?: InboxAttachment[] | undefined;
     id: string;
     channel: string | undefined;
+    channelId: string | undefined;
     from: string;
     fromUid: string | undefined;
     at: string | undefined;

package/dist/lib/agent-kit/inbox-state.js

@@ -118,6 +118,9 @@ export function summarizeInboxEntry(e, done) {
     return {
         id: e.id,
         channel: pick("channel"),
+        // Set when the message arrived in a channel or group DM. Reply there
+        // (`hq dm <channelId> "…"`), not to the sender privately.
+        channelId: pick("channelId"),
         from: pick("fromDisplayName", "fromEmail", "fromPersonUid") ?? "unknown",
         fromUid: pick("fromPersonUid"),
         at: pick("receivedAt", "createdAt", "mirroredAt"),

package/dist/lib/agent-kit/mcp/tools.js

@@ -213,11 +213,11 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_dm_send",
-            description: "Send an HQ direct message as this agent to a person (email or prs_…) or agent (agt_…). Use audience='agent' for progress/status messages that only agents need to see; audience='human' for messages a person must read; audience='both' when unsure.",
+            description: "Send an HQ message as this agent to a person (email or prs_…), an agent (agt_…), or a channel or group DM (chn_…). When replying to an inbox item that has a channelId, pass that channelId as `to` so the answer lands in the conversation it came from. Use audience='agent' for progress/status messages that only agents need to see; audience='human' for messages a person must read; audience='both' when unsure.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    to: { type: "string", description: "Email, prs_… or agt_… uid" },
+                    to: { type: "string", description: "Email, prs_… or agt_… uid, or a chn_… channel id" },
                     message: { type: "string" },
                     audience: { type: "string", enum: ["human", "agent", "both"], description: "Who this message is for (default: human)" },
                 },
@@ -231,12 +231,25 @@ export function buildAgentMcpTools(clients) {
                 if (audience !== undefined && !["human", "agent", "both"].includes(audience)) {
                     throw new McpToolInputError('"audience" must be human, agent, or both');
                 }
+                if (/^chn_[A-Za-z0-9]+$/.test(to)) {
+                    // A channel or group DM: post into it, so a reply lands where the
+                    // message arrived instead of in a private DM to the sender.
+                    const token = await clients.getToken();
+                    const res = await clients.apiJson(token, `/v1/notify/channels/${encodeURIComponent(to)}/messages`, {
+                        method: "POST",
+                        body: { body: message },
+                    });
+                    if (res.status < 200 || res.status >= 300) {
+                        return errorResult(`Channel send failed (${res.status}): ${describeError(res.body)}`);
+                    }
+                    return textResult(`posted in ${to}`);
+                }
                 const body = /^[^\s]+@[^\s]+$/.test(to)
                     ? { toEmail: to.toLowerCase(), body: message }
                     : isRecipientUid(to)
                         ? { toPersonUid: to, body: message }
                         : (() => {
-                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid');
+                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid, or a chn_… channel id');
                         })();
                 if (audience)
                     body.audience = audience;
@@ -252,7 +265,7 @@ export function buildAgentMcpTools(clients) {
             name: "hq_inbox_read",
             description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
                 "marked handled. Items with `attachments` carry files: download each with hq_attachment_fetch (pass its vaultPath " +
-                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
+                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, passing the item's channelId as `to` when it has one so the reply lands in that channel or group; do not reply to another bot's greeting or sign-off that asks for nothing. Then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/lib/agent-kit/skills.js

@@ -31,11 +31,17 @@ The kit's inbox poller mirrors every message addressed to you (DMs, channel
 mentions, jobs). Work through them like this:
 
 \`\`\`bash
-hq agent inbox                  # pending messages, oldest first (id, sender uid, text)
-hq dm <sender-uid> "reply"      # answer each one
+hq agent inbox                  # pending messages, oldest first (id, sender uid, channelId, text)
+hq dm <channelId> "reply"       # message came from a channel or group: answer in it
+hq dm <sender-uid> "reply"      # otherwise: answer the sender privately
 hq agent inbox done <id> [id…]  # mark handled so it is never answered twice
 \`\`\`
 
+Reply where the message arrived. A message with a \`channelId\` was posted in a
+channel or group DM, and the answer belongs there, not in a private DM to the
+sender. Do not reply to another bot's greeting, thanks or sign-off that asks
+for nothing: two bots acknowledging each other never stop.
+
 The MCP equivalents are \`hq_inbox_read\`, \`hq_dm_send\` and \`hq_inbox_done\`.
 If the kit has a wake configured (\`hq agent kit wake show\`), HQ pokes your
 framework whenever something is pending, so always drain the whole list and

package/dist/lib/agent-kit/wake.js

@@ -27,8 +27,10 @@ export const WAKE_STATE_NAME = "wake-state.json";
 export const DEFAULT_WAKE_RETRY_MS = 10 * 60_000;
 export const WAKE_URL_TIMEOUT_MS = 15_000;
 export const DEFAULT_WAKE_COMMAND_TIMEOUT_MS = 10 * 60_000;
-export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool), reply to each " +
-    "with `hq dm <sender-uid> \"…\"` (or hq_dm_send), then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
+export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool). Reply where each message " +
+    "arrived: if it has a channelId, post in that channel with `hq dm <channelId> \"…\"`; otherwise reply to the " +
+    "sender with `hq dm <sender-uid> \"…\"` (or hq_dm_send). Do not reply to another bot's greeting, thanks or " +
+    "sign-off that asks for nothing. Then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
 export function wakePath(paths) {
     return path.join(paths.agentDir, WAKE_FILE_NAME);
 }
@@ -197,7 +199,11 @@ export async function fireWake(config, notice, deps) {
     let child;
     try {
         child = doSpawn(config.command[0], config.command.slice(1), {
-            stdio: ["pipe", logFd, logFd],
+            // stdout is discarded: a wake command's normal output (a routine record,
+            // a prompt echo) has no diagnostic value and would land in a log that is
+            // world-readable on a share without permissions. stderr is kept so a
+            // failing wake can still be diagnosed.
+            stdio: ["pipe", "ignore", logFd],
             env: {
                 ...process.env,
                 HQ_WAKE_EVENT: notice.event,

package/dist/lib/work-context/outbox.js

@@ -8,7 +8,7 @@ import * as path from "node:path";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
 import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
 import { NotTrackingError } from "./errors.js";
-import { readSessionState, writeAcknowledgedRegisterBinding, } from "./state.js";
+import { readSessionState, stripRegisterReceiptEpisodes, updateSessionState, writeAcknowledgedRegisterBinding, } from "./state.js";
 import { isSafeWorkContextSegment, workContextOutboxDir, workContextOutboxPath, } from "./paths.js";
 /** Fields allowed on a durable outbox operation (privacy allowlist). */
 export const OUTBOX_ALLOWLIST = [
@@ -285,7 +285,35 @@ export function writeAckedRegisterState(op, root, receiptId, now = () => new Dat
 /** Repair older unresolved session projections from acknowledged registrations. */
 export function repairAckedRegisterStates(root, sessionIds, now = () => new Date()) {
     let repaired = 0;
-    for (const op of listOutboxOperations(root)) {
+    const operations = listOutboxOperations(root);
+    // A stored bindingEpisodeId that is a register receipt makes the server drop
+    // every batch. Clear it even when the register operation that produced it is
+    // no longer in the outbox: the id shape identifies it. This runs for every
+    // requested session, whatever its company or tracking status.
+    const receiptsBySession = new Map();
+    for (const op of operations) {
+        if (op.kind !== "register" || !op.receiptId)
+            continue;
+        const receipts = receiptsBySession.get(op.sessionId) ?? [];
+        receipts.push(op.receiptId);
+        receiptsBySession.set(op.sessionId, receipts);
+    }
+    for (const sessionId of sessionIds ?? receiptsBySession.keys()) {
+        if (!isSafeWorkContextSegment(sessionId))
+            continue;
+        const known = receiptsBySession.get(sessionId) ?? [];
+        // Take the lock only for a session that needs the repair.
+        const observed = readSessionState(sessionId, root);
+        if (!observed || stripRegisterReceiptEpisodes(observed, known) === observed)
+            continue;
+        updateSessionState(sessionId, root, (current) => {
+            if (!current)
+                return null;
+            const next = stripRegisterReceiptEpisodes(current, known);
+            return next === current ? null : next;
+        });
+    }
+    for (const op of operations) {
         if (op.delivery !== "acked" ||
             !op.receiptId ||
             op.kind !== "register" ||

package/dist/lib/work-context/reconcile.js

@@ -15,7 +15,7 @@ import { rebindNeedsProjectOnPrompt } from "./prompt-rebind.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
 import { enqueueOutbox, listOutboxOperations, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
-import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
+import { mergeLocalSessionFields, isRegisterReceiptEpisodeId, readSessionState, stripRegisterReceiptEpisodes, writeSessionState, } from "./state.js";
 function resultOf(parts) {
     const out = {
         contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
@@ -174,7 +174,22 @@ export async function reconcileObservation(obs, deps) {
         }
     }
     // Already untracked locally — stay untracked until explicit opt-in (no backfill).
-    const prior = readSessionState(sessionId, deps.root);
+    const observedPrior = readSessionState(sessionId, deps.root);
+    // Acked register operations for this session. A register response never
+    // carries a binding episode, so an already acknowledged binding is
+    // identified by its company / project / task, never by comparing the
+    // register receipt with the session's bindingEpisodeId.
+    const ackedRegisters = observedPrior
+        ? listOutboxOperations(deps.root).filter((operation) => operation.kind === "register" &&
+            operation.delivery === "acked" &&
+            operation.sessionId === sessionId &&
+            Boolean(operation.receiptId))
+        : [];
+    // Older clients stored a register receipt as the episode. Work from a
+    // projection with those cleared so no later write carries one forward.
+    const prior = observedPrior
+        ? stripRegisterReceiptEpisodes(observedPrior, ackedRegisters.map((operation) => operation.receiptId))
+        : observedPrior;
     if (prior?.contextStatus === "untracked" && prior.untrackedReceipt?.origin === "user") {
         return {
             result: resultOf({
@@ -690,15 +705,6 @@ export async function reconcileObservation(obs, deps) {
         registerClassification = "needs_project";
         diagnostics.push(`company rebind to ${resolvedCompany.slug ?? resolvedCompany.uid}; cleared project`);
     }
-    // Acked register operations for this session. A register that did not come
-    // back bound yields no binding episode, so its receipt (not the session's
-    // bindingEpisodeId) is what identifies an already acknowledged binding.
-    const ackedRegisters = prior
-        ? listOutboxOperations(deps.root).filter((operation) => operation.kind === "register" &&
-            operation.delivery === "acked" &&
-            operation.sessionId === sessionId &&
-            Boolean(operation.receiptId))
-        : [];
     const stateClassification = registerClassification === "unresolved" &&
         prior?.contextStatus === "needs_project" &&
         prior.companyUid === resolvedCompany.uid &&
@@ -711,22 +717,26 @@ export async function reconcileObservation(obs, deps) {
     // into a second semantic register operation: the prior receipt is the stable
     // identity for this exact company/project/task binding.
     const priorBindingIsBound = Boolean(projectId && taskId);
+    // A state that is not an acknowledged binding (for example one quarantined
+    // as company_conflict) must register again even when its fields still match.
+    const priorIsAcknowledgedBinding = prior?.contextStatus === "bound" ||
+        prior?.contextStatus === "needs_task" ||
+        prior?.contextStatus === "needs_project" ||
+        prior?.contextStatus === "unresolved";
     const acknowledgedReceipt = prior &&
+        priorIsAcknowledgedBinding &&
         prior.companyUid === resolvedCompany.uid &&
         prior.companySlug === resolvedCompany.slug &&
         prior.projectId === projectId &&
         prior.taskId === taskId
-        ? ackedRegisters.find((operation) => (priorBindingIsBound
-            ? operation.receiptId === prior.bindingEpisodeId
-            : !prior.bindingEpisodeId || operation.receiptId === prior.bindingEpisodeId) &&
-            operation.companyUid === resolvedCompany.uid &&
+        ? ackedRegisters.find((operation) => operation.companyUid === resolvedCompany.uid &&
             operation.companySlug === resolvedCompany.slug &&
             operation.projectId === projectId &&
             operation.taskId === taskId)?.receiptId
         : undefined;
     const acknowledgedPrior = acknowledgedReceipt ? prior : null;
     if (acknowledgedPrior) {
-        // A partial (not bound) acknowledged register carries no server episode.
+        // Only a bound session holds a server episode (issued by bind / organize).
         const retainedEpisodeId = priorBindingIsBound
             ? acknowledgedPrior.bindingEpisodeId
             : undefined;
@@ -895,10 +905,9 @@ export async function reconcileObservation(obs, deps) {
         // the true computed classification into durable session state; otherwise
         // the emitter and mesh presence lose the tenant the server already
         // acknowledged. projectId / taskId are written only when genuinely
-        // resolved, and a fresh bindingEpisodeId only when the session is bound —
-        // never fabricated on a partial path. (writeAckedRegisterState above may
-        // have already recorded a receipt-derived episode for a resolved partial
-        // binding; the default merge preserves that when the binding still matches.)
+        // resolved. A register ack never yields a bindingEpisodeId, bound or not:
+        // the server issues episodes only on bind / organize. The default merge
+        // keeps an episode the session already holds when the binding still matches.
         if (resolvedCompany.uid) {
             const bound = registerClassification === "bound";
             // A server ack of the company makes it authoritative: the durable status
@@ -919,7 +928,6 @@ export async function reconcileObservation(obs, deps) {
                 contextStatus: bound ? "bound" : ackedClassification,
                 ...(projectId ? { projectId } : {}),
                 ...(taskId ? { taskId } : {}),
-                ...(bound ? { bindingEpisodeId: delivered.receiptId } : {}),
                 updatedAt: nowFn().toISOString(),
                 startedAt,
                 ...(typeof toolWrites === "number" ? { toolWrites } : {}),
@@ -939,6 +947,12 @@ export async function reconcileObservation(obs, deps) {
                 : registerClassification === "needs_project"
                     ? "needs_project"
                     : "queued";
+        // Report the episode the session actually holds, never the receipt.
+        const ackedState = readSessionState(sessionId, deps.root);
+        const ackedEpisodeId = ackedState &&
+            !isRegisterReceiptEpisodeId(ackedState.bindingEpisodeId, [delivered.receiptId])
+            ? ackedState.bindingEpisodeId
+            : undefined;
         return {
             result: resultOf({
                 kind: kind === "queued" ? "queued" : kind,
@@ -950,7 +964,7 @@ export async function reconcileObservation(obs, deps) {
                 companySlug: resolvedCompany.slug,
                 projectId,
                 taskId,
-                bindingEpisodeId: delivered.receiptId,
+                ...(ackedEpisodeId ? { bindingEpisodeId: ackedEpisodeId } : {}),
                 ...bindResultFields,
             }),
             exitCode: EXIT_OK,

package/dist/lib/work-context/state.d.ts

@@ -158,6 +158,22 @@ export declare function mergeLocalSessionFields(next: SessionStateFile, prior: S
     preserveBindingEpisode?: boolean;
     preserveCompanyBinding?: boolean;
 }): SessionStateFile;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
+ */
+export declare function isRegisterReceiptEpisodeId(id: string | undefined, knownReceiptIds?: Iterable<string | undefined>): boolean;
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export declare function stripRegisterReceiptEpisodes(state: SessionStateFile, knownReceiptIds?: Iterable<string | undefined>): SessionStateFile;
 /**
  * Upgrade the local projection after the server acknowledges a register.
  *
@@ -165,6 +181,9 @@ export declare function mergeLocalSessionFields(next: SessionStateFile, prior: S
  * erase an explicit untracked choice, a conflicting existing company, or a
  * more specific binding for the same company. This is also used to repair
  * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
  */
 export declare function writeAcknowledgedRegisterBinding(binding: AcknowledgedRegisterBinding, root: string, now?: () => Date): SessionStateFile | null;
 /** True when a durable state file was written by the hook / reconcile path. */

package/dist/lib/work-context/state.js

@@ -342,6 +342,47 @@ function bindingStrength(state) {
         return 1;
     return 0;
 }
+const SERVER_EPISODE_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
+ */
+export function isRegisterReceiptEpisodeId(id, knownReceiptIds = []) {
+    if (!id)
+        return false;
+    for (const receiptId of knownReceiptIds) {
+        if (receiptId && receiptId === id)
+            return true;
+    }
+    if (SERVER_EPISODE_SHAPE.test(id))
+        return false;
+    return id.startsWith("op_");
+}
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export function stripRegisterReceiptEpisodes(state, knownReceiptIds = []) {
+    const known = [...knownReceiptIds];
+    const ownIsReceipt = isRegisterReceiptEpisodeId(state.bindingEpisodeId, known);
+    const leaveIsReceipt = isRegisterReceiptEpisodeId(state.presenceLeave?.bindingEpisodeId, known);
+    if (!ownIsReceipt && !leaveIsReceipt)
+        return state;
+    const out = { ...state };
+    if (ownIsReceipt)
+        out.bindingEpisodeId = undefined;
+    if (leaveIsReceipt && state.presenceLeave) {
+        const { bindingEpisodeId: _receipt, ...leave } = state.presenceLeave;
+        out.presenceLeave = leave;
+    }
+    return out;
+}
 /**
  * Upgrade the local projection after the server acknowledges a register.
  *
@@ -349,60 +390,68 @@ function bindingStrength(state) {
  * erase an explicit untracked choice, a conflicting existing company, or a
  * more specific binding for the same company. This is also used to repair
  * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
  */
 export function writeAcknowledgedRegisterBinding(binding, root, now = () => new Date()) {
     const acknowledged = acknowledgedStatus(binding);
     if (!acknowledged || !isSafeWorkContextSegment(binding.sessionId))
         return null;
-    const prior = readSessionState(binding.sessionId, root);
-    // Reconcile always writes the local projection before network delivery. Do
-    // not manufacture session files when replay sees an orphaned legacy outbox
-    // record with no corresponding tracked session.
-    if (!prior)
-        return null;
-    if (prior.contextStatus === "untracked" ||
-        (prior.companyUid && prior.companyUid !== binding.companyUid)) {
-        return prior;
-    }
-    const acknowledgementStrength = acknowledged === "bound" ? 3 : acknowledged === "needs_task" ? 2 : 1;
-    const priorStrength = bindingStrength(prior);
-    const preservePriorBinding = Boolean(prior.companyUid === binding.companyUid && priorStrength > acknowledgementStrength);
-    // The server issues no binding episode for a register that did not come
-    // back bound (unresolved / needs_project / needs_task). Its receipt must
-    // never stand in for one: session-event batches carry bindingEpisodeId and
-    // the server drops batches whose episode it does not recognise. Older
-    // clients stored that receipt here, so also repair a prior value that is
-    // exactly this partial register's receipt.
-    const receiptEpisode = acknowledged === "bound" ? binding.receiptId : undefined;
-    const priorEpisode = acknowledged !== "bound" && prior.bindingEpisodeId === binding.receiptId
-        ? undefined
-        : prior.bindingEpisodeId;
-    const sameBindingAsPrior = prior.companyUid === binding.companyUid &&
-        prior.projectId === binding.projectId &&
-        prior.taskId === binding.taskId;
-    const next = mergeLocalSessionFields({
-        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
-        sessionId: binding.sessionId,
-        companyUid: binding.companyUid,
-        companySlug: binding.companySlug ?? prior.companySlug,
-        contextStatus: preservePriorBinding ? prior.contextStatus : acknowledged,
-        projectId: preservePriorBinding ? prior.projectId : binding.projectId,
-        taskId: preservePriorBinding ? prior.taskId : binding.taskId,
-        bindingEpisodeId: preservePriorBinding
-            ? priorEpisode ?? receiptEpisode
-            : receiptEpisode ?? (sameBindingAsPrior ? priorEpisode : undefined),
-        updatedAt: now().toISOString(),
-    }, prior, { preserveBindingEpisode: false });
-    if (prior.companyUid === next.companyUid &&
-        prior.companySlug === next.companySlug &&
-        prior.contextStatus === next.contextStatus &&
-        prior.projectId === next.projectId &&
-        prior.taskId === next.taskId &&
-        prior.bindingEpisodeId === next.bindingEpisodeId) {
-        return prior;
-    }
-    writeSessionState(next, root);
-    return next;
+    let result = null;
+    updateSessionState(binding.sessionId, root, (current) => {
+        // Reconcile always writes the local projection before network delivery. Do
+        // not manufacture session files when replay sees an orphaned legacy outbox
+        // record with no corresponding tracked session.
+        if (!current)
+            return null;
+        // A register response never carries a server episode, bound or not. The
+        // server mints episodes only on bind / organize, and drops session-event
+        // batches whose episode it does not recognise. Older clients stored the
+        // register receipt as the episode, so clear it wherever it is found. This
+        // repair is independent of the binding decision below and therefore also
+        // applies to untracked and different-company states.
+        const prior = stripRegisterReceiptEpisodes(current, [binding.receiptId]);
+        const repaired = prior !== current;
+        if (prior.contextStatus === "untracked" ||
+            (prior.companyUid && prior.companyUid !== binding.companyUid)) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        const acknowledgementStrength = acknowledged === "bound" ? 3 : acknowledged === "needs_task" ? 2 : 1;
+        const priorStrength = bindingStrength(prior);
+        const preservePriorBinding = Boolean(prior.companyUid === binding.companyUid && priorStrength > acknowledgementStrength);
+        const sameBindingAsPrior = prior.companyUid === binding.companyUid &&
+            prior.projectId === binding.projectId &&
+            prior.taskId === binding.taskId;
+        const next = mergeLocalSessionFields({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId: binding.sessionId,
+            companyUid: binding.companyUid,
+            companySlug: binding.companySlug ?? prior.companySlug,
+            contextStatus: preservePriorBinding ? prior.contextStatus : acknowledged,
+            projectId: preservePriorBinding ? prior.projectId : binding.projectId,
+            taskId: preservePriorBinding ? prior.taskId : binding.taskId,
+            // Keep a server-issued episode only while the binding it was issued
+            // for is unchanged. Never derive one from the receipt.
+            bindingEpisodeId: preservePriorBinding || sameBindingAsPrior
+                ? prior.bindingEpisodeId
+                : undefined,
+            updatedAt: now().toISOString(),
+        }, prior, { preserveBindingEpisode: false });
+        if (prior.companyUid === next.companyUid &&
+            prior.companySlug === next.companySlug &&
+            prior.contextStatus === next.contextStatus &&
+            prior.projectId === next.projectId &&
+            prior.taskId === next.taskId &&
+            prior.bindingEpisodeId === next.bindingEpisodeId) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        result = next;
+        return next;
+    });
+    return result;
 }
 /** True when a durable state file was written by the hook / reconcile path. */
 export function isHookWrittenSessionState(state) {

package/dist/main.js

@@ -54,6 +54,9 @@ import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTree
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
+import * as os from "node:os";
+import { adoptAgentIdentityEnv } from "./lib/agent-kit/adopt-identity.js";
+import { agentKitPaths } from "./lib/agent-kit/paths.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
  * the hard version decision, pre-action observability, and release-health
@@ -160,6 +163,16 @@ program
     .description("HQ management CLI — modules, packages, and cloud sync")
     .version(CLI_VERSION);
 program.hook("preAction", async () => {
+    // A host that pinned HQ_AGENT_DIR has declared that it IS that agent, so
+    // every command — `hq dm`, `hq secrets`, not only `hq agent …` — must
+    // mint as the agent. Without this, those commands looked for a person
+    // session, found none, and opened a browser sign-in that a headless bot can
+    // never complete. Only the explicit variable counts: a bot that merely lives
+    // beside its owner on the owner's computer must not take over the owner's
+    // commands.
+    if (process.env.HQ_AGENT_DIR?.trim()) {
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    }
     // Both are best-effort and fully swallowed: neither can change the command's
     // result or exit code. They receive only the shared pre-finalization
     // allowance (up to 1.2s), and that bound is a TIMER, so it only preempts

package/dist/utils/cognito-session.d.ts

@@ -290,4 +290,16 @@ export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOp
     refreshed: boolean;
     reason?: string;
 }>;
+/**
+ * True on a Linux host with no terminal and no display — a container or
+ * server, where a browser sign-in can never be completed. macOS and Windows
+ * always have a way to open a browser, and a terminal means a person is there.
+ */
+export declare function isHeadlessHost(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: boolean): boolean;
+/**
+ * True when the environment explicitly names an HQ agent identity. Only the
+ * explicit variables count: guessing from the filesystem is unreliable, and a
+ * wrong guess would take an ordinary headless run off its sign-in path.
+ */
+export declare function hostRunsAnAgent(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=cognito-session.d.ts.map

package/dist/utils/cognito-session.js

@@ -943,6 +943,15 @@ async function ensureCognitoTokenUnserialized(options) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // An agent host with no display has no one to complete a browser sign-in,
+        // which then blocks until something kills the process. Fail with the fix
+        // instead. Scoped to agent hosts so an ordinary headless run keeps the
+        // existing sign-in and its remedies.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.accessToken;
@@ -1010,6 +1019,13 @@ async function ensureCognitoIdTokenUnserialized(options) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // A browser sign-in on a server has no one to complete it and blocks
+        // until something kills the process. Fail with the fix instead.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.idToken;
@@ -1121,4 +1137,24 @@ async function refreshCachedSessionUnserialized(options) {
         };
     }
 }
+/**
+ * True on a Linux host with no terminal and no display — a container or
+ * server, where a browser sign-in can never be completed. macOS and Windows
+ * always have a way to open a browser, and a terminal means a person is there.
+ */
+export function isHeadlessHost(env = process.env, platform = process.platform, tty = Boolean(process.stdin.isTTY || process.stdout.isTTY || process.stderr.isTTY)) {
+    if (platform !== "linux")
+        return false;
+    if (tty)
+        return false;
+    return !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim();
+}
+/**
+ * True when the environment explicitly names an HQ agent identity. Only the
+ * explicit variables count: guessing from the filesystem is unreliable, and a
+ * wrong guess would take an ordinary headless run off its sign-in path.
+ */
+export function hostRunsAnAgent(env = process.env) {
+    return Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+}
 //# sourceMappingURL=cognito-session.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.249.1",
+  "version": "5.251.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {