@indigoai-us/hq-cli 5.101.4 → 5.101.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [Unreleased]
+
+## [5.101.6] — 2026-08-17
+
+### Added
+
+- **`hq mesh`** — native work-mesh verbs in the CLI (Cognito + hq-pro REST +
+  `~/.hq/work-mesh/cache`). No pack helper required. Verbs: `check`
+  (`status` / `projects`), `start`, `progress`, `blocked`, `done`, `note`,
+  `story`, `doctor` (warms directory + inbox + pair DMs). Does **not** start
+  MQTT listen and is not `hq doctor` (hook guardrails). `--apply` Board PUTs
+  from local prd.json are not in the CLI yet.
+
+### Fixed
+
+- `hq mesh doctor` now keys `directory` / `inbox` / `contacts` on the real
+  `prs_*` / `agt_*` principal. `custom:entityUid` is read from the Cognito ID
+  token first; if the JWT has only email/sub (typical human access tokens),
+  doctor falls back to `/v1/realtime/credentials` and keeps only the uid —
+  AWS IoT creds are discarded. Leftover `session.json` is removed once the
+  real principal is known.
+
+## [5.101.5] — 2026-08-17
+
+- No user-facing changes recorded.
+
 ## [5.101.4] — 2026-08-16
 
 - No user-facing changes recorded.

package/dist/commands/mesh.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `hq mesh` — work-mesh verbs for agents and local sessions.
+ *
+ * Native hq-cli: Cognito + hq-pro REST + ~/.hq/work-mesh/cache. Does not
+ * require hq-pack-work-mesh on disk and does not start MQTT listen.
+ * Distinct from `hq doctor` (hook guardrails).
+ */
+import { Command } from "commander";
+import { type MeshCompany, type MeshThread } from "../lib/mesh/api.js";
+export declare function formatCheckLines(threads: MeshThread[], company: MeshCompany, projectId?: string): string[];
+export declare function registerMeshCommand(program: Command): void;
+//# sourceMappingURL=mesh.d.ts.map

package/dist/commands/mesh.js

@@ -0,0 +1,173 @@
+/**
+ * `hq mesh` — work-mesh verbs for agents and local sessions.
+ *
+ * Native hq-cli: Cognito + hq-pro REST + ~/.hq/work-mesh/cache. Does not
+ * require hq-pack-work-mesh on disk and does not start MQTT listen.
+ * Distinct from `hq doctor` (hook guardrails).
+ */
+import chalk from "chalk";
+import { loadCachedTokens } from "../utils/cognito-session.js";
+import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveThreads, patchStoryStatus, requireToken, resolveMeshCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+export function formatCheckLines(threads, company, projectId) {
+    if (threads.length === 0) {
+        return ["Work mesh: no active project threads found."];
+    }
+    const scope = projectId
+        ? `${company.companySlug || company.companyUid}/${projectId}`
+        : company.companySlug || company.companyUid;
+    const lines = [`Work mesh: ${threads.length} active thread(s) for ${scope}`];
+    for (const thread of threads.slice(0, 8)) {
+        const owner = thread.ownerUid ? ` owner=${thread.ownerUid}` : "";
+        const summary = thread.progressSummary ||
+            thread.sourceSignalSummary ||
+            thread.blockedReason ||
+            "";
+        lines.push(`- ${thread.threadStatus ?? "unknown"} ${thread.threadId ?? "?"}${owner}${summary ? `: ${summary}` : ""}`);
+    }
+    return lines;
+}
+function fail(message) {
+    console.error(chalk.red(message));
+    process.exit(1);
+}
+function requireProject(opts) {
+    const project = opts.project?.trim();
+    if (!project)
+        fail("`--project <slug>` is required.");
+    return project;
+}
+async function withCompany(opts) {
+    const token = await requireToken();
+    const company = await resolveMeshCompany(token, opts.company);
+    return { token, company };
+}
+async function runCheck(opts) {
+    const { token, company } = await withCompany(opts);
+    const threads = await listActiveThreads(token, company.companyUid, opts.project);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "check", company, projectId: opts.project, threads }, null, 2));
+        return;
+    }
+    for (const line of formatCheckLines(threads, company, opts.project)) {
+        console.log(line);
+    }
+}
+async function runEvent(verb, opts) {
+    const { token, company } = await withCompany(opts);
+    const projectId = requireProject(opts);
+    const ensured = await ensureProjectThread(token, company, projectId, {
+        threadId: opts.threadId,
+        summary: opts.summary,
+    });
+    const eventKind = verb === "start" ? "claim" : verb;
+    const event = await appendThreadEvent(token, company.companyUid, ensured.threadId, eventKind, eventPayload(eventKind, opts, callerLabelFromToken(token)));
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            action: verb,
+            eventKind,
+            company,
+            projectId,
+            threadId: ensured.threadId,
+            created: ensured.created,
+            ...event,
+        }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: ${verb} ${ensured.threadId}${event.eventId ? ` (${event.eventId})` : ""}`);
+}
+async function runStory(opts) {
+    const storyId = opts.story?.trim();
+    const status = opts.status?.trim();
+    if (!storyId || !status || !STORY_STATUSES.has(status)) {
+        fail("story requires --story <id> and --status queued|in_progress|review|done");
+    }
+    const { token, company } = await withCompany(opts);
+    const projectId = requireProject(opts);
+    const patched = await patchStoryStatus(token, company.companyUid, projectId, storyId, status);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "story", company, ...patched, storyId }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: story ${storyId} → ${patched.status} (v${patched.version ?? "?"})`);
+}
+async function runDoctor(opts) {
+    if (opts.apply) {
+        fail("`hq mesh doctor --apply` (paced Board PUTs from local prd.json) is not in the CLI yet.\n" +
+            "Omit --apply to warm the conversation cache (directory, inbox, pair DMs).");
+    }
+    const token = await requireToken();
+    const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    const warmed = await warmMeshConversationCache(token, principalUid);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "doctor", ...warmed }, null, 2));
+        return;
+    }
+    console.log(`Work mesh cache warmed at ${warmed.cacheRoot}` +
+        ` (directory=${warmed.directory} inbox=${warmed.inbox}` +
+        ` contacts=${warmed.contacts} pair-threads=${warmed.threads})`);
+}
+function wrap(action) {
+    return async () => {
+        try {
+            await action();
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+    };
+}
+function collectRepeatable(value, previous = []) {
+    return previous.concat(value);
+}
+function addSharedFlags(cmd) {
+    return cmd
+        .option("--company <slug|uid>", "Company slug or cloud uid")
+        .option("--project <slug>", "HQ project slug / projectId")
+        .option("--thread-id <id>", "Explicit work thread id")
+        .option("--json", "Print machine-readable JSON");
+}
+export function registerMeshCommand(program) {
+    const mesh = program
+        .command("mesh")
+        .description("Work mesh — register project work, report progress, and warm ~/.hq/work-mesh/cache");
+    addSharedFlags(mesh
+        .command("check")
+        .alias("status")
+        .alias("projects")
+        .description("Show active work-mesh threads for a company/project")).action((opts) => wrap(() => runCheck(opts))());
+    addSharedFlags(mesh
+        .command("start")
+        .description("Ensure a project thread exists and claim/report start")
+        .option("--summary <text>", "What you are starting")).action((opts) => wrap(() => runEvent("start", opts))());
+    addSharedFlags(mesh
+        .command("progress")
+        .description("Append a progress event to the project thread")
+        .requiredOption("--summary <text>", "Progress summary")).action((opts) => wrap(() => runEvent("progress", opts))());
+    addSharedFlags(mesh
+        .command("blocked")
+        .description("Append a blocked event to the project thread")
+        .option("--reason <text>", "Why you are blocked")
+        .option("--ask <text>", "Repeatable ask", collectRepeatable)
+        .option("--summary <text>", "Optional summary")).action((opts) => wrap(() => runEvent("blocked", opts))());
+    addSharedFlags(mesh
+        .command("done")
+        .description("Mark the project thread done")
+        .option("--summary <text>", "What shipped")).action((opts) => wrap(() => runEvent("done", opts))());
+    addSharedFlags(mesh
+        .command("note")
+        .description("Append a note with no status change")
+        .option("--summary <text>", "Note text")).action((opts) => wrap(() => runEvent("note", opts))());
+    addSharedFlags(mesh
+        .command("story")
+        .description("PATCH one Board story status")
+        .requiredOption("--story <id>", "Story id, e.g. US-001")
+        .requiredOption("--status <status>", "queued|in_progress|review|done")).action((opts) => wrap(() => runStory(opts))());
+    mesh
+        .command("doctor")
+        .description("Warm ~/.hq/work-mesh/cache from hq-pro (directory, inbox, pair DMs). Not `hq doctor`.")
+        .option("--apply", "Reserved — Board PUTs from local prd are not in the CLI yet")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runDoctor(opts))());
+}
+//# sourceMappingURL=mesh.js.map

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

@@ -0,0 +1,88 @@
+/**
+ * Native work-mesh client for `hq mesh`.
+ *
+ * Talks to hq-pro over the shared vault fetch + Cognito session. Writes the
+ * machine cache apps already read. Does not spawn the pack helper and does
+ * not start MQTT listen.
+ */
+export declare const STORY_STATUSES: Set<string>;
+export declare const ACTIVE_STATUSES: Set<string>;
+export interface MeshCompany {
+    companyUid: string;
+    companySlug: string;
+}
+export interface MeshThread {
+    threadId?: string;
+    projectId?: string;
+    companyUid?: string;
+    threadStatus?: string;
+    ownerUid?: string;
+    progressSummary?: string;
+    sourceSignalSummary?: string;
+    blockedReason?: string;
+    lastActivityAt?: string;
+    createdAt?: string;
+}
+export declare function meshJson(token: string, path: string, init?: {
+    method?: string;
+    body?: Record<string, unknown>;
+    query?: Record<string, string>;
+}): Promise<unknown>;
+export declare function resolveMeshCompany(token: string, company?: string): Promise<MeshCompany>;
+export declare function requireToken(): Promise<string>;
+export declare function listActiveThreads(token: string, companyUid: string, projectId?: string): Promise<MeshThread[]>;
+export declare function clamp(value: string, max: number): string;
+export declare function eventPayload(kind: string, opts: {
+    summary?: string;
+    reason?: string;
+    ask?: string[];
+}, claimedBy: string): Record<string, unknown>;
+export declare function ensureProjectThread(token: string, company: MeshCompany, projectId: string, opts: {
+    threadId?: string;
+    summary?: string;
+}): Promise<{
+    threadId: string;
+    created: boolean;
+}>;
+export declare function appendThreadEvent(token: string, companyUid: string, threadId: string, eventKind: string, payload: Record<string, unknown>): Promise<{
+    eventId?: string;
+    createdAt?: string;
+}>;
+export declare function patchStoryStatus(token: string, companyUid: string, projectId: string, storyId: string, status: string): Promise<{
+    status: string;
+    version?: number;
+    projectId: string;
+}>;
+export declare function pairDmUidsFromInbox(inbox: unknown): string[];
+export interface WarmCacheResult {
+    directory: boolean;
+    inbox: boolean;
+    contacts: boolean;
+    threads: number;
+    cacheRoot: string;
+}
+/** Warm inbox + contacts + pair threads + directory into the local cache. */
+export declare function warmMeshConversationCache(token: string, principalUid: string, cacheRoot?: string): Promise<WarmCacheResult>;
+export declare function entityUidFromJwt(token: string): string | undefined;
+export declare function principalUidFromTopic(topic: unknown): string | undefined;
+/** Extract prs_/agt_ from a realtime credentials payload. Never returns secrets. */
+export declare function principalUidFromRealtimePayload(data: unknown): string | undefined;
+/**
+ * Cache key for directory/inbox/contacts. `custom:entityUid` rides the ID
+ * token (access tokens only have email/sub), so prefer the cached idToken.
+ */
+export declare function meshCachePrincipalUid(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined, fallbackToken?: string): string;
+/**
+ * Resolve the cache principal. JWT first; if the human access/id tokens have
+ * no entityUid, ask `/v1/realtime/credentials` (same fallback as the pack
+ * doctor). Only the uid is kept — credentials are discarded.
+ */
+export declare function resolveMeshPrincipalUid(token: string, tokens?: {
+    idToken?: string;
+    accessToken?: string;
+} | null): Promise<string>;
+export declare function callerLabelFromToken(token: string): string;
+//# sourceMappingURL=api.d.ts.map

package/dist/lib/mesh/api.js

@@ -0,0 +1,319 @@
+/**
+ * Native work-mesh client for `hq mesh`.
+ *
+ * Talks to hq-pro over the shared vault fetch + Cognito session. Writes the
+ * machine cache apps already read. Does not spawn the pack helper and does
+ * not start MQTT listen.
+ */
+import { ensureCognitoToken } from "../../utils/cognito-session.js";
+import { peekIdToken } from "../../utils/id-token.js";
+import { getCompanyUid, vaultApiFetch } from "../../utils/vault-api.js";
+import { meshCacheRoot, removeSessionFallbackFiles, writeMeshCacheFile, } from "./cache.js";
+const PRINCIPAL_UID = /^(prs|agt)_/;
+export const STORY_STATUSES = new Set([
+    "queued",
+    "in_progress",
+    "review",
+    "done",
+]);
+export const ACTIVE_STATUSES = new Set([
+    "open",
+    "claimed",
+    "in-progress",
+    "blocked",
+    "needs-human",
+]);
+export async function meshJson(token, path, init = {}) {
+    const res = await vaultApiFetch({
+        token,
+        path,
+        method: init.method,
+        body: init.body,
+        query: init.query,
+    });
+    const text = await res.text();
+    let data = {};
+    if (text) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { raw: text };
+        }
+    }
+    if (!res.ok) {
+        const err = data;
+        throw new Error(err.error || err.message || `${res.status} ${res.statusText}`);
+    }
+    return data;
+}
+export async function resolveMeshCompany(token, company) {
+    const explicit = process.env.HQ_WORK_MESH_COMPANY_UID || process.env.HQ_COMPANY_UID;
+    if (explicit?.trim()) {
+        return { companyUid: explicit.trim(), companySlug: company || explicit.trim() };
+    }
+    if (company && /^(cmp|co)_/.test(company)) {
+        return { companyUid: company, companySlug: company };
+    }
+    const uid = await getCompanyUid(token, company);
+    return { companyUid: uid, companySlug: company || uid };
+}
+export async function requireToken() {
+    return ensureCognitoToken();
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+export async function listActiveThreads(token, companyUid, projectId) {
+    const collected = [];
+    for (const status of ACTIVE_STATUSES) {
+        let cursor = "";
+        for (let page = 0; page < 10; page += 1) {
+            const query = {
+                companyUid,
+                status,
+                limit: "100",
+            };
+            if (cursor)
+                query.cursor = cursor;
+            const data = asRecord(await meshJson(token, "/v1/work-mesh/threads", { query }));
+            const rows = Array.isArray(data?.threads)
+                ? data.threads
+                : Array.isArray(data?.items)
+                    ? data.items
+                    : [];
+            for (const row of rows) {
+                const rec = asRecord(row);
+                if (!rec)
+                    continue;
+                collected.push(rec);
+            }
+            cursor = typeof data?.nextCursor === "string" ? data.nextCursor : "";
+            if (!cursor)
+                break;
+        }
+    }
+    return collected
+        .filter((thread) => !projectId || thread.projectId === projectId)
+        .sort((a, b) => String(b.lastActivityAt || b.createdAt || "").localeCompare(String(a.lastActivityAt || a.createdAt || "")));
+}
+export function clamp(value, max) {
+    return value.length <= max ? value : value.slice(0, max);
+}
+export function eventPayload(kind, opts, claimedBy) {
+    if (kind === "claim") {
+        return {
+            claimedBy: clamp(claimedBy, 120),
+            leaseTtlIso: new Date(Date.now() + 120 * 60 * 1000).toISOString(),
+            note: clamp(opts.summary || "Starting HQ project work.", 280),
+        };
+    }
+    if (kind === "progress") {
+        return { summary: clamp(opts.summary || "Project work is in progress.", 280) };
+    }
+    if (kind === "blocked") {
+        return {
+            reason: clamp(opts.reason || opts.summary || "Project work is blocked.", 500),
+            asks: (opts.ask ?? []).filter(Boolean).slice(0, 5),
+        };
+    }
+    if (kind === "done") {
+        return { summary: clamp(opts.summary || "Project work completed.", 280) };
+    }
+    return {
+        text: clamp(opts.summary || "HQ project note.", 500),
+        noteKind: "audit",
+    };
+}
+export async function ensureProjectThread(token, company, projectId, opts) {
+    if (opts.threadId)
+        return { threadId: opts.threadId, created: false };
+    const existing = (await listActiveThreads(token, company.companyUid, projectId))[0];
+    if (existing?.threadId)
+        return { threadId: existing.threadId, created: false };
+    const created = asRecord(await meshJson(token, "/v1/work-mesh/threads", {
+        method: "POST",
+        body: {
+            companyUid: company.companyUid,
+            projectId,
+            sourceSignalSummary: clamp(opts.summary || `HQ project ${projectId}`, 280),
+            routing: {
+                priority: "normal",
+                tags: ["hq-project", `project:${projectId}`],
+            },
+        },
+    }));
+    const threadId = String(created?.threadId || "").trim();
+    if (!threadId)
+        throw new Error("Work mesh did not return a threadId");
+    return { threadId, created: true };
+}
+export async function appendThreadEvent(token, companyUid, threadId, eventKind, payload) {
+    const data = asRecord(await meshJson(token, `/v1/work-mesh/threads/${encodeURIComponent(threadId)}/events`, {
+        method: "POST",
+        body: { companyUid, eventKind, payload },
+    }));
+    return {
+        eventId: typeof data?.eventId === "string" ? data.eventId : undefined,
+        createdAt: typeof data?.createdAt === "string" ? data.createdAt : undefined,
+    };
+}
+export async function patchStoryStatus(token, companyUid, projectId, storyId, status) {
+    const view = asRecord(await meshJson(token, `/v1/work-mesh/projects/${encodeURIComponent(projectId)}/stories/${encodeURIComponent(storyId)}`, {
+        method: "PATCH",
+        body: { companyUid, status },
+    }));
+    if (view && typeof view.projectId === "string" && typeof view.companyUid === "string") {
+        writeMeshCacheFile(["projects", view.companyUid, `${view.projectId}.json`], view);
+    }
+    const stories = Array.isArray(view?.stories) ? view.stories : [];
+    const patched = stories
+        .map(asRecord)
+        .find((row) => row && row.id === storyId);
+    return {
+        projectId: String(view?.projectId || projectId),
+        status: typeof patched?.status === "string" ? patched.status : status,
+        version: typeof view?.version === "number" ? view.version : undefined,
+    };
+}
+export function pairDmUidsFromInbox(inbox) {
+    const rec = asRecord(inbox);
+    const ids = new Set();
+    const events = Array.isArray(rec?.events) ? rec.events : [];
+    for (const event of events) {
+        const row = asRecord(event);
+        const uid = String(row?.fromPersonUid || "").trim();
+        if (/^(prs|agt)_[A-Za-z0-9]+$/.test(uid))
+            ids.add(uid);
+    }
+    const pairs = Array.isArray(rec?.pairUnreads) ? rec.pairUnreads : [];
+    for (const pair of pairs) {
+        const row = asRecord(pair);
+        const uid = String(row?.withPersonUid || "").trim();
+        if (/^(prs|agt)_[A-Za-z0-9]+$/.test(uid))
+            ids.add(uid);
+    }
+    return [...ids].sort();
+}
+/** Warm inbox + contacts + pair threads + directory into the local cache. */
+export async function warmMeshConversationCache(token, principalUid, cacheRoot = meshCacheRoot()) {
+    const result = {
+        directory: false,
+        inbox: false,
+        contacts: false,
+        threads: 0,
+        cacheRoot,
+    };
+    try {
+        const directory = await meshJson(token, "/v1/notify/channels", {
+            query: { cursor: "" },
+        });
+        writeMeshCacheFile(["directory", `${principalUid}.json`], directory, cacheRoot);
+        result.directory = true;
+    }
+    catch {
+        // Directory warm is best-effort; inbox is the pair-DM path.
+    }
+    const inbox = await meshJson(token, "/v1/notify/inbox", {
+        query: { limit: "50" },
+    });
+    writeMeshCacheFile(["inbox", `${principalUid}.json`], inbox, cacheRoot);
+    result.inbox = true;
+    try {
+        const contacts = await meshJson(token, "/v1/notify/contacts");
+        writeMeshCacheFile(["contacts", `${principalUid}.json`], contacts, cacheRoot);
+        result.contacts = true;
+    }
+    catch {
+        // Contacts roster is optional for the rail.
+    }
+    for (const uid of pairDmUidsFromInbox(inbox)) {
+        try {
+            const thread = await meshJson(token, "/v1/notify/thread", {
+                query: { withPersonUid: uid, limit: "50" },
+            });
+            writeMeshCacheFile(["dms", `${uid}.json`], thread, cacheRoot);
+            result.threads += 1;
+        }
+        catch {
+            // one pair must not fail the rest
+        }
+    }
+    if (PRINCIPAL_UID.test(principalUid)) {
+        removeSessionFallbackFiles(cacheRoot);
+    }
+    return result;
+}
+export function entityUidFromJwt(token) {
+    const uid = peekIdToken(token)["custom:entityUid"];
+    return typeof uid === "string" && PRINCIPAL_UID.test(uid) ? uid : undefined;
+}
+export function principalUidFromTopic(topic) {
+    if (typeof topic !== "string")
+        return undefined;
+    const match = /^hq\/((?:prs|agt)_[0-9A-HJKMNP-TV-Z]{26})(?:\/|$)/.exec(topic);
+    return match?.[1];
+}
+/** Extract prs_/agt_ from a realtime credentials payload. Never returns secrets. */
+export function principalUidFromRealtimePayload(data) {
+    const rec = asRecord(data);
+    if (!rec)
+        return undefined;
+    const claimed = rec.principalUid;
+    if (typeof claimed === "string" && PRINCIPAL_UID.test(claimed))
+        return claimed;
+    const topics = asRecord(rec.topics);
+    return (principalUidFromTopic(topics?.dm) ||
+        principalUidFromTopic(rec.topic));
+}
+/**
+ * Cache key for directory/inbox/contacts. `custom:entityUid` rides the ID
+ * token (access tokens only have email/sub), so prefer the cached idToken.
+ */
+export function meshCachePrincipalUid(tokens, fallbackToken) {
+    for (const token of [tokens?.idToken, tokens?.accessToken, fallbackToken]) {
+        if (!token)
+            continue;
+        const uid = entityUidFromJwt(token);
+        if (uid)
+            return uid;
+    }
+    return "session";
+}
+/**
+ * Resolve the cache principal. JWT first; if the human access/id tokens have
+ * no entityUid, ask `/v1/realtime/credentials` (same fallback as the pack
+ * doctor). Only the uid is kept — credentials are discarded.
+ */
+export async function resolveMeshPrincipalUid(token, tokens) {
+    const fromJwt = meshCachePrincipalUid(tokens, token);
+    if (fromJwt !== "session")
+        return fromJwt;
+    try {
+        const data = await meshJson(token, "/v1/realtime/credentials", {
+            method: "POST",
+            body: { contractVersion: 2 },
+        });
+        const uid = principalUidFromRealtimePayload(data);
+        if (uid)
+            return uid;
+    }
+    catch {
+        // best-effort; session.json is worse than failing doctor
+    }
+    return "session";
+}
+export function callerLabelFromToken(token) {
+    const claims = peekIdToken(token);
+    const entityUid = claims["custom:entityUid"];
+    if (typeof entityUid === "string" && entityUid)
+        return entityUid;
+    if (typeof claims.email === "string" && claims.email)
+        return claims.email;
+    if (typeof claims.sub === "string" && claims.sub)
+        return claims.sub;
+    return "hq-cli";
+}
+//# sourceMappingURL=api.js.map

package/dist/lib/mesh/cache.d.ts

@@ -0,0 +1,10 @@
+/**
+ * On-disk work-mesh cache. Same layout the desktop/web apps and the pack
+ * helper read: ~/.hq/work-mesh/cache/{projects,channels,directory,inbox,contacts,dms}.
+ */
+export declare function meshCacheRoot(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function isSafeCacheSegment(value: string): boolean;
+export declare function writeMeshCacheFile(segments: string[], value: unknown, root?: string): string | null;
+/** Drop leftover session.json once we know the real prs_/agt_ cache key. */
+export declare function removeSessionFallbackFiles(root?: string): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/lib/mesh/cache.js

@@ -0,0 +1,42 @@
+/**
+ * On-disk work-mesh cache. Same layout the desktop/web apps and the pack
+ * helper read: ~/.hq/work-mesh/cache/{projects,channels,directory,inbox,contacts,dms}.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export function meshCacheRoot(home = os.homedir(), env = process.env) {
+    const override = env.HQ_WORK_MESH_CACHE?.trim();
+    if (override)
+        return override;
+    return path.join(home, ".hq", "work-mesh", "cache");
+}
+export function isSafeCacheSegment(value) {
+    const trimmed = value.trim();
+    return Boolean(trimmed &&
+        trimmed.length <= 128 &&
+        !trimmed.includes("..") &&
+        /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(trimmed));
+}
+export function writeMeshCacheFile(segments, value, root = meshCacheRoot()) {
+    if (segments.length === 0 || !segments.every(isSafeCacheSegment))
+        return null;
+    const dest = path.join(root, ...segments);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const tmp = `${dest}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(tmp, dest);
+    return dest;
+}
+/** Drop leftover session.json once we know the real prs_/agt_ cache key. */
+export function removeSessionFallbackFiles(root = meshCacheRoot()) {
+    for (const dir of ["directory", "inbox", "contacts"]) {
+        try {
+            fs.unlinkSync(path.join(root, dir, "session.json"));
+        }
+        catch {
+            // missing is fine
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/main.js

@@ -61,10 +61,12 @@ import { registerCoreCommands } from "./commands/core.js";
 import { registerSearchCommand } from "./commands/search.js";
 import { registerIndexCommand } from "./commands/index-cmd.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerMeshCommand } from "./commands/mesh.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
+import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
 import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
@@ -273,6 +275,9 @@ registerIndexCommand(program);
 // check registry so later check families (vault, sync, MCP, …) plug in without
 // engine changes.
 registerDoctorCommand(program);
+// Work mesh (subcommand group — `hq mesh …`). Native REST + cache. Distinct
+// from `hq doctor` (hook guardrails). Does not start MQTT listen.
+registerMeshCommand(program);
 program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });
@@ -438,7 +443,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // Ordered FIRST so the narrow native-binding signature wins over the
         // broader environmental / transport / generic branches.
         const qmdMsg = qmdNativeBindingErrorMessage(err);
-        const envMsg = qmdMsg ? null : environmentalFsErrorMessage(err);
+        // A `hq search <query> -c <collection>` against a collection that is not
+        // indexed on THIS machine is the user's local index state, not an hq-cli
+        // defect — the remedy is an explicit `hq index sync`. finishRunQmd already
+        // types the condition QmdCollectionMissingError, but nothing caught it, so
+        // it fell through to the capture below; because the synthesized message
+        // embeds the caller's whole argv, each distinct query minted a brand-new
+        // permanent issue. Print an actionable line naming the missing collection
+        // and skip capture (HQ-CLI-S, Sentry 7672722729). Evaluated AFTER the
+        // native-binding check so that narrower signature keeps priority, and
+        // BEFORE the environmental / transport / generic branches. Scoped to
+        // caller-supplied reads (search/vsearch/query/get); a collection-missing
+        // raised by hq's OWN reconciliation (`collection add`/`context add`) names
+        // a collection hq built itself, so it stays a captured internal error.
+        const collectionMsg = qmdMsg ? null : qmdMissingCollectionMessage(err);
+        const envMsg = qmdMsg || collectionMsg ? null : environmentalFsErrorMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -449,10 +468,13 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = qmdMsg || envMsg ? null : networkTransportErrorMessage(err);
+        const transportMsg = qmdMsg || collectionMsg || envMsg ? null : networkTransportErrorMessage(err);
         if (qmdMsg) {
             deps.stderr.write(`hq: ${qmdMsg}\n`);
         }
+        else if (collectionMsg) {
+            deps.stderr.write(`hq: ${collectionMsg}\n`);
+        }
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }

package/dist/utils/qmd-collection-missing-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * If `err` is a caller-driven "collection not found" from `hq search` (or its
+ * `get` sibling), return an actionable, query-free remedy naming the missing
+ * collection; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * environmentalFsErrorMessage / networkTransportErrorMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export declare function qmdMissingCollectionMessage(err: unknown): string | null;
+//# sourceMappingURL=qmd-collection-missing-error.d.ts.map

package/dist/utils/qmd-collection-missing-error.js

@@ -0,0 +1,95 @@
+// src/utils/qmd-collection-missing-error.ts
+//
+// Classify a "collection not found" qmd failure that came from a caller-supplied
+// READ — `hq search`, its `--mode` siblings (vsearch/query), or `hq search get`
+// — as the user's LOCAL index state, not an hq-cli code defect. The collection
+// the caller named is simply not indexed on this machine; the remedy is an
+// explicit `hq index sync`, so the CLI prints an actionable line and SKIPS
+// Sentry capture. Sibling of qmd-native-binding-error.ts (HQ-CLI-J, unbuilt
+// bindings), environmental-error.ts (HQ-CLI-2, full disk), and
+// network-transport-error.ts (HQ-CLI-G, connectivity): a failure that is NOT an
+// hq-cli defect is printed with an actionable message and never filed as a crash.
+//
+// HQ-CLI-S (Sentry 7672722729): `hq search <query> -c <collection>` against a
+// collection that isn't indexed locally made qmd exit 1 with `Collection not
+// found: <collection>`. finishRunQmd already classifies that wording into the
+// dedicated QmdCollectionMissingError subclass, but nothing caught it, so it
+// unwound to the top-level handler's final else and was captured. Worse, the
+// synthesized message interpolates the caller's whole argv, so each distinct
+// query minted a brand-new permanent issue. This classifier closes that boundary.
+//
+// The gate is deliberately narrow on TWO axes so it can neither be tripped by
+// user input nor silence a real bug:
+//   1. CLASS: only a QmdCollectionMissingError (the typed subclass finishRunQmd
+//      raises for the collection-not-found wording) qualifies — never a plain
+//      QmdExitError, a native-binding failure, or any other error.
+//   2. INVOCATION: only qmd's caller-supplied-collection READS — `search`,
+//      `vsearch`, `query`, `get` — qualify. A collection-missing raised by hq's
+//      OWN reconciliation (`collection add`/`collection list`, `context add`)
+//      names a collection hq constructed itself, so a not-found there is an
+//      internal inconsistency worth reporting: it must keep crashing and
+//      capturing, so the classifier returns null for those invocations.
+//
+// The collection name is read STRUCTURALLY from the error's own `args` (the
+// token after `-c`/`--collection`), never by parsing qmd's stderr, and the
+// caller's free-text query (args[1]) is never echoed — the same unbounded-
+// fingerprint discipline that motivated the fix. The name is itself a
+// user-supplied `-c` value, so before it is interpolated it is passed through
+// redactErrorText — the same credential-redaction + control-character-flattening
+// + length-bounding chain the generic error path uses — so a newline, terminal
+// escape sequence, credential-like token, or oversized value can neither forge a
+// second `hq:` line nor leak; if nothing survives redaction the message falls
+// back to the name-free variant.
+import { redactErrorText } from "./redact-error-text.js";
+/** qmd subcommands whose collection is chosen by the CALLER (a read surface). */
+const CALLER_COLLECTION_READS = new Set(["search", "vsearch", "query", "get"]);
+/**
+ * The two-pronged, factual remedy. `hq index sync` builds the collections HQ can
+ * derive from this local root; `hq index collections` shows what is actually
+ * registered (covering a name that maps to a company not present here, which
+ * sync will never create). Neither claims the named collection will appear.
+ */
+function remedyMessage(collection) {
+    return collection
+        ? `No local search collection named '${collection}'. Run 'hq index sync' to build it, or 'hq index collections' to see what is registered.`
+        : "No local search collection was found for that query. Run 'hq index sync' to build the local index, or 'hq index collections' to see what is registered.";
+}
+/** The collection name the caller passed after `-c`/`--collection`, or null. */
+function collectionFromArgs(args) {
+    for (let i = 0; i < args.length - 1; i += 1) {
+        if (args[i] === "-c" || args[i] === "--collection") {
+            const value = args[i + 1];
+            if (typeof value === "string" && value.length > 0)
+                return value;
+        }
+    }
+    return null;
+}
+/**
+ * If `err` is a caller-driven "collection not found" from `hq search` (or its
+ * `get` sibling), return an actionable, query-free remedy naming the missing
+ * collection; otherwise return `null`. Mirrors qmdNativeBindingErrorMessage /
+ * environmentalFsErrorMessage / networkTransportErrorMessage so the top-level
+ * handler can branch on it the same way: a non-null result means
+ * print-and-skip-Sentry, null means "handle as usual (capture to Sentry)".
+ */
+export function qmdMissingCollectionMessage(err) {
+    if (err === null || typeof err !== "object")
+        return null;
+    const record = err;
+    if (record.name !== "QmdCollectionMissingError")
+        return null;
+    const args = Array.isArray(record.args) ? record.args : [];
+    const subcommand = args[0];
+    if (typeof subcommand !== "string" || !CALLER_COLLECTION_READS.has(subcommand)) {
+        return null;
+    }
+    const rawCollection = collectionFromArgs(args);
+    // The name is a user-supplied `-c` value: redact + flatten + bound it before
+    // printing so it cannot forge a second `hq:` line, emit terminal escapes, or
+    // leak a credential-shaped token. redactErrorText returns "" when nothing
+    // survives, in which case we fall back to the name-free variant.
+    const collection = rawCollection ? redactErrorText(rawCollection) || null : null;
+    return remedyMessage(collection);
+}
+//# sourceMappingURL=qmd-collection-missing-error.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.101.4",
+  "version": "5.101.6",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -24,7 +24,8 @@
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "vitest": "vitest",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepare": "husky || true"
   },
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
@@ -52,6 +53,8 @@
     "@vitest/coverage-v8": "4.1.6",
     "aws-sdk-client-mock": "^4.1.0",
     "eslint": "^10.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.2"
@@ -77,5 +80,8 @@
     "onlyBuiltDependencies": [
       "better-sqlite3"
     ]
+  },
+  "lint-staged": {
+    "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   }
 }