@indigoai-us/hq-cli 5.142.0 → 5.143.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.143.0] — 2026-09-23
+
+### Fixed
+
+- `hq dm` and report commands now reject non-recipient and non-company channel
+  requests locally, and report updates retry one fresh revision after a
+  conflict.
+- `hq mesh project register` now verifies the company's Board view before
+  registering and reports an actionable local error when the Board is missing.
+
 ## [5.142.0] — 2026-09-23
 
 ### Added

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

@@ -5740,7 +5740,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly subcommands: readonly [];
         }, {
             readonly name: "register";
-            readonly description: "POST project registration to create or bind its project channel and Board";
+            readonly description: "Register an existing Board and bind its project channel; use project ensure to create or repair a Board";
             readonly aliases: readonly [];
             readonly hidden: false;
             readonly usage: "[options] <projectId>";

package/dist/command-catalog.generated.js

@@ -7409,7 +7409,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "name": "register",
-                        "description": "POST project registration to create or bind its project channel and Board",
+                        "description": "Register an existing Board and bind its project channel; use project ensure to create or repair a Board",
                         "aliases": [],
                         "hidden": false,
                         "usage": "[options] <projectId>",

package/dist/commands/agents.d.ts

@@ -336,6 +336,7 @@ export declare function formatJobsTable(jobs: AgentJobView[]): string;
 export declare function formatPauseResult(result: PauseJobResult): string;
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export declare function appliedHint(applied: boolean): string;
+/** Agent uid shape (`agt_…`). */
 /** One message in a DM thread, as returned by `GET /v1/notify/thread`. */
 export interface DmThreadMessage {
     eventId: string;

package/dist/commands/agents.js

@@ -36,6 +36,7 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
+import { AGENT_UID_PATTERN, isAgentUid } from "../lib/notify-recipient.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -807,14 +808,6 @@ export function appliedHint(applied) {
         ? "applied to the running box now"
         : "saved — takes effect on the agent's next launch";
 }
-// ---------------------------------------------------------------------------
-// Talking to agents (DM). Agents are members addressable over HQ's DM system:
-// a message rides `POST /v1/notify/dm` (the wire contract accepts `agt_*`), the
-// agent's box picks it up and replies over DM (a first-class agent reply
-// channel), and the two-way conversation is read back via `GET /v1/notify/thread`.
-// ---------------------------------------------------------------------------
-/** Agent uid shape (`agt_…`). */
-const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
 /**
  * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
  * directly; anything else is treated as a slug or display name and resolved
@@ -909,6 +902,9 @@ async function resolveJobsTargetOrExit(ref, company) {
 }
 /** Send a DM to an agent. Returns nothing meaningful beyond success. */
 export async function sendAgentDm(token, agentUid, message) {
+    if (!isAgentUid(agentUid)) {
+        throw new Error(`Invalid agent recipient '${agentUid}': expected an agt_ uid.`);
+    }
     await agentsRequest({
         token,
         path: "/v1/notify/dm",

package/dist/commands/dm.js

@@ -4,11 +4,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { isMachineIdentity } from "@indigoai-us/hq-cloud";
 import { peekIdToken } from "../utils/id-token.js";
-const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
-// People (prs_) and agents (agt_) are both first-class DM participants; the
-// server applies the same membership-overlap gate to either and delivers
-// agt_* recipients into the agent's durable box inbox.
-const RECIPIENT_UID_PATTERN = /^(prs|agt)_[A-Za-z0-9_-]+$/;
+import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN } from "../lib/notify-recipient.js";
 /**
  * Classify a recipient arg as an email or a person/agent uid. Mirrors the
  * email/uid heuristic used by `hq members`. Returns null for neither.

package/dist/commands/mesh.js

@@ -400,7 +400,30 @@ async function runProjectRegister(projectId, opts) {
     }
     const { token, company } = await withCompany(opts);
     const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
-    const registration = await registerMeshProject(token, company.companyUid, projectId);
+    const companyRef = company.companySlug || company.companyUid;
+    try {
+        const board = await getProjectView(token, company.companyUid, projectId);
+        if (board.companyUid !== company.companyUid || board.projectId !== projectId) {
+            fail(`Work mesh project ${projectId} has no Board view in company ${companyRef}. Create the Board before registering it.`);
+        }
+    }
+    catch (err) {
+        if (httpStatus(err) === 404) {
+            fail(`Work mesh project ${projectId} has no Board view in company ${companyRef}. Create the Board before registering it.`);
+        }
+        throw err;
+    }
+    let registration;
+    try {
+        registration = await registerMeshProject(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        const failure = err;
+        if (failure.status === 403 && failure.code === "PROJECT_NOT_IN_COMPANY") {
+            fail(`Work mesh project ${projectId} could not be registered in company ${companyRef}: the Board or its genesis thread is missing. Run "hq mesh project ensure ${projectId} --company ${companyRef} --stories-file <prd.json>" to create or restore them.`);
+        }
+        throw err;
+    }
     const boardState = "registered";
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "project.register", principalUid, boardState, ...registration }, null, 2));
@@ -1601,7 +1624,7 @@ export function registerMeshCommand(program) {
         .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
     project
         .command("register <projectId>")
-        .description("POST project registration to create or bind its project channel and Board")
+        .description("Register an existing Board and bind its project channel; use project ensure to create or repair a Board")
         .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
         .option("--channel <channelId>", "Reserved: the current server chooses the project channel")
         .option("--json", "Print machine-readable JSON")

package/dist/commands/report.d.ts

@@ -1,8 +1,9 @@
 import { Command } from "commander";
 import { buildReportTarball, deployOrgContext, type ChannelReport, type DeployAccessPolicy, type ReportDeployment, type ReportPatch } from "../lib/report-publish.js";
+type ReportPatchInput = ReportPatch | ((current: ChannelReport) => ReportPatch);
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
 export declare function resolveReport(token: string, reportId: string, requestedChannelId?: string): Promise<ChannelReport>;
-export declare function patchReport(token: string, report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
+export declare function patchReport(token: string, report: ChannelReport, patch: ReportPatchInput): Promise<ChannelReport>;
 export declare function resolveCompanySlug(token: string, companyUid: string): Promise<string>;
 export declare function deployReportStatic(token: string, input: {
     slug: string;
@@ -12,4 +13,5 @@ export declare function deployReportStatic(token: string, input: {
 }): Promise<ReportDeployment>;
 export declare function registerReportCommand(program: Command): void;
 export declare function runReportCommand(action: () => Promise<void>): Promise<void>;
+export {};
 //# sourceMappingURL=report.d.ts.map

package/dist/commands/report.js

@@ -86,10 +86,39 @@ function print(value, json) {
     else
         console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
 }
+async function listReportChannels(token) {
+    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels" });
+    if (!channels.ok)
+        throw new ReportPublishError("Could not resolve the report channel.");
+    const listed = await channels.json();
+    return Array.isArray(listed.channels) ? listed.channels : [];
+}
+function isCompanyReportChannel(channel) {
+    return channel.scope === "company"
+        || (typeof channel.scope !== "string" && Boolean(channel.companyUid));
+}
+function requireCompanyReportChannel(channels, channelId) {
+    const channel = channels.find((row) => row.channelId === channelId);
+    if (!channel)
+        throw new ReportPublishError("Report channel was not found in your channels.");
+    if (!isCompanyReportChannel(channel))
+        throw new ReportPublishError("Channel reports require a company channel.");
+}
+async function readReportInChannel(token, channelId, reportId) {
+    const res = await vaultApiFetch({ token, path: reportPath(channelId, reportId) });
+    if (!res.ok)
+        return undefined;
+    const body = await res.json();
+    if (!body.report)
+        throw new ReportPublishError("Report response was incomplete.");
+    return body.report;
+}
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */
 export async function resolveReport(token, reportId, requestedChannelId) {
     const explicit = requestedChannelId ?? process.env.HQ_REPORT_CHANNEL_ID;
+    const channels = await listReportChannels(token);
     if (explicit) {
+        requireCompanyReportChannel(channels, explicit);
         const res = await vaultApiFetch({ token, path: reportPath(explicit, reportId) });
         if (!res.ok)
             throw new ReportPublishError("Report was not found in the supplied channel context.");
@@ -100,24 +129,20 @@ export async function resolveReport(token, reportId, requestedChannelId) {
     }
     const recordedChannel = locallyRecordedChannel(reportId);
     if (recordedChannel) {
-        const res = await vaultApiFetch({ token, path: reportPath(recordedChannel, reportId) });
-        if (res.ok) {
-            const body = await res.json();
-            if (body.report)
-                return body.report;
-        }
+        requireCompanyReportChannel(channels, recordedChannel);
+        const recorded = await readReportInChannel(token, recordedChannel, reportId);
+        if (recorded)
+            return recorded;
     }
     // The report API is intentionally channel-scoped. Discover only among the
     // caller's existing channels, using list endpoints so missing reports never
     // become one server-side 404 per channel.
-    const channels = await vaultApiFetch({ token, path: "/v1/notify/channels" });
-    if (!channels.ok)
-        throw new ReportPublishError("Could not resolve the report channel.");
-    const listed = await channels.json();
     let scannedChannels = 0;
-    for (const row of listed.channels ?? []) {
+    for (const row of channels) {
         if (!row.channelId)
             continue;
+        if (!isCompanyReportChannel(row))
+            continue;
         if (scannedChannels >= MAX_REPORT_DISCOVERY_CHANNELS)
             break;
         scannedChannels += 1;
@@ -125,19 +150,45 @@ export async function resolveReport(token, reportId, requestedChannelId) {
         if (!res.ok)
             continue;
         const body = await res.json();
-        const match = body.reports?.find((report) => report.reportId === reportId);
+        const reports = Array.isArray(body.reports) ? body.reports : [];
+        const match = reports.find((report) => report.reportId === reportId);
         if (match)
             return match;
     }
     throw new ReportPublishError(notFoundMessage(scannedChannels));
 }
 export async function patchReport(token, report, patch) {
-    const res = await vaultApiFetch({ token, path: reportPath(report.channelId, report.reportId), method: "PATCH", body: patch });
+    if (!report.companyUid)
+        throw new ReportPublishError("Channel reports require a company channel.");
+    const patchOnce = (current) => vaultApiFetch({
+        token,
+        path: reportPath(current.channelId, current.reportId),
+        method: "PATCH",
+        body: {
+            ...(typeof patch === "function" ? patch(current) : patch),
+            revision: current.revision,
+        },
+    });
+    let res = await patchOnce(report);
     if (res.status === 409) {
         const body = await res.json().catch(() => ({}));
         if (body.error === "already-running")
             throw new ReportPublishError("already running", "already-running");
-        throw new ReportPublishError("Report changed while it was being updated.");
+        if (body.error !== "revision-mismatch")
+            throw new ReportPublishError("Report changed while it was being updated.", "revision-conflict");
+        const latest = await readReportInChannel(token, report.channelId, report.reportId);
+        if (!latest)
+            throw new ReportPublishError("Could not reread the report after it changed.", "revision-conflict");
+        if (typeof patch !== "function") {
+            throw new ReportPublishError("Report changed while it was being updated; refresh and retry.", "revision-conflict");
+        }
+        res = await patchOnce(latest);
+        if (res.status === 409) {
+            const retryBody = await res.json().catch(() => ({}));
+            if (retryBody.error === "already-running")
+                throw new ReportPublishError("already running", "already-running");
+            throw new ReportPublishError("Report changed while it was being updated; refresh and retry.", "revision-conflict");
+        }
     }
     if (!res.ok)
         throw new ReportPublishError("Could not update the report record.");
@@ -267,7 +318,10 @@ async function discardDraftAction(reportId, options) {
         if (!res.ok && res.status !== 404)
             throw new ReportPublishError("Could not remove the draft deployment.");
     }
-    const updated = await patchReport(token, report, { draft: null, state: report.url ? "live" : "draft-pending" });
+    const updated = await patchReport(token, report, (current) => ({
+        draft: null,
+        state: current.url ? "live" : "draft-pending",
+    }));
     print(updated, options.json === true);
 }
 async function accessAction(reportId, options) {

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

@@ -17,6 +17,7 @@
  */
 import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
+import { isRecipientUid } from "../../../lib/notify-recipient.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
@@ -222,7 +223,7 @@ export function buildAgentMcpTools(clients) {
                 const message = str(args, "message", { required: true, max: 20_000 }).trim();
                 const body = /^[^\s]+@[^\s]+$/.test(to)
                     ? { toEmail: to.toLowerCase(), body: message }
-                    : /^(prs|agt)_[A-Za-z0-9_-]+$/.test(to)
+                    : isRecipientUid(to)
                         ? { toPersonUid: to, body: message }
                         : (() => {
                             throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid');

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

@@ -143,6 +143,10 @@ export declare class BotApiError extends Error {
     readonly tokenAgentUid?: string | undefined;
     constructor(status: number, path: string, code?: string | undefined, detail?: string | undefined, retryAfterMs?: number | undefined, tokenAgentUid?: string | undefined);
 }
+export declare class InvalidDmRecipientError extends Error {
+    readonly recipient: string;
+    constructor(recipient: string);
+}
 /** Parse a Retry-After header (delta-seconds or HTTP-date) to milliseconds. */
 export declare function retryAfterHeaderMs(value: string | null | undefined, nowMs?: number): number | undefined;
 export interface BotApiOptions {

package/dist/lib/bot/api.js

@@ -8,6 +8,7 @@
 import { vaultApiFetch } from "../../utils/vault-api.js";
 import { tokenAgentUid } from "../heartbeat-identity.js";
 import { assertNoSecretKeys } from "./local-config.js";
+import { isRecipientUid } from "../notify-recipient.js";
 export class BotApiError extends Error {
     status;
     path;
@@ -26,6 +27,14 @@ export class BotApiError extends Error {
         this.name = "BotApiError";
     }
 }
+export class InvalidDmRecipientError extends Error {
+    recipient;
+    constructor(recipient) {
+        super(`Invalid DM recipient '${recipient}': expected a prs_ or agt_ uid.`);
+        this.recipient = recipient;
+        this.name = "InvalidDmRecipientError";
+    }
+}
 /** Parse a Retry-After header (delta-seconds or HTTP-date) to milliseconds. */
 export function retryAfterHeaderMs(value, nowMs = Date.now()) {
     if (!value)
@@ -141,7 +150,10 @@ export class BotApi {
     }
     /** POST /v1/notify/dm — send as the bot (agent identity). */
     async sendDm(input) {
-        const payload = { toPersonUid: input.toPersonUid, body: input.body };
+        const recipient = input.toPersonUid.trim();
+        if (!isRecipientUid(recipient))
+            throw new InvalidDmRecipientError(input.toPersonUid);
+        const payload = { toPersonUid: recipient, body: input.body };
         if (input.rootEventId)
             payload.rootEventId = input.rootEventId;
         const { body } = await this.call("/v1/notify/dm", { method: "POST", body: payload });

package/dist/lib/notify-recipient.d.ts

@@ -0,0 +1,7 @@
+/** Canonical recipients accepted by the notify DM wire contract. */
+export declare const RECIPIENT_UID_PATTERN: RegExp;
+export declare const AGENT_UID_PATTERN: RegExp;
+export declare const EMAIL_PATTERN: RegExp;
+export declare function isRecipientUid(value: string): boolean;
+export declare function isAgentUid(value: string): boolean;
+//# sourceMappingURL=notify-recipient.d.ts.map

package/dist/lib/notify-recipient.js

@@ -0,0 +1,11 @@
+/** Canonical recipients accepted by the notify DM wire contract. */
+export const RECIPIENT_UID_PATTERN = /^(prs|agt)_[A-Za-z0-9_-]+$/;
+export const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+export const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
+export function isRecipientUid(value) {
+    return RECIPIENT_UID_PATTERN.test(value.trim());
+}
+export function isAgentUid(value) {
+    return AGENT_UID_PATTERN.test(value.trim());
+}
+//# sourceMappingURL=notify-recipient.js.map

package/dist/lib/report-publish.d.ts

@@ -124,8 +124,8 @@ export interface ReportAdoptDependencies {
     patch(report: ChannelReport, patch: ReportPatch): Promise<ChannelReport>;
 }
 export declare class ReportPublishError extends Error {
-    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed";
-    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed");
+    readonly code: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "revision-conflict";
+    constructor(message: string, code?: "already-running" | "source-invalid" | "deploy-failed" | "job-failed" | "revision-conflict");
 }
 /** A deliberately boring, token-safe failure reason stored on the report. */
 export declare function plainFailureReason(error: unknown): string;

package/dist/lib/report-publish.js

@@ -41,7 +41,7 @@ export class ReportPublishError extends Error {
 /** A deliberately boring, token-safe failure reason stored on the report. */
 export function plainFailureReason(error) {
     if (error instanceof ReportPublishError) {
-        if (error.code === "source-invalid" || error.code === "job-failed")
+        if (error.code === "source-invalid" || error.code === "job-failed" || error.code === "revision-conflict")
             return error.message.slice(0, 240);
         if (error.code === "already-running")
             return "already running";
@@ -264,9 +264,10 @@ export async function adoptReport(report, deps) {
 export async function publishReport(report, directory, draft, deps) {
     const startedAt = deps.now();
     let locked = false;
+    let current = report;
     try {
         try {
-            await deps.patch(report, { lastRun: { at: startedAt, status: "running" } });
+            current = await deps.patch(current, { lastRun: { at: startedAt, status: "running" } });
             locked = true;
         }
         catch (error) {
@@ -276,9 +277,9 @@ export async function publishReport(report, directory, draft, deps) {
         }
         const source = loadReportSource(directory);
         const deployment = await deps.deploy({
-            slug: reportDeploySlug(report, draft),
+            slug: reportDeploySlug(current, draft),
             files: source.files,
-            access: defaultAccessPolicy(report),
+            access: defaultAccessPolicy(current),
         });
         const completedAt = deps.now();
         const patch = {
@@ -295,13 +296,13 @@ export async function publishReport(report, directory, draft, deps) {
             patch.url = deployment.url;
             patch.deployAppId = deployment.appId;
         }
-        return await deps.patch(report, patch);
+        return await deps.patch(current, patch);
     }
     catch (error) {
         if (locked) {
             const reason = plainFailureReason(error);
             try {
-                await deps.patch(report, {
+                await deps.patch(current, {
                     lastRun: { at: deps.now(), status: "failed", reason },
                 });
             }
@@ -312,8 +313,8 @@ export async function publishReport(report, directory, draft, deps) {
             const notice = ownerFailureNotice({
                 code: error instanceof ReportPublishError ? error.code : undefined,
                 reason,
-                reportUrl: report.url,
-                ownerPersonUid: report.createdBy,
+                reportUrl: current.url,
+                ownerPersonUid: current.createdBy,
             });
             if (notice && deps.notifyOwner) {
                 try {

package/package.json

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