@indigoai-us/hq-cli 5.122.2 → 5.123.0

package/dist/lib/mesh/live/daemon/board-refresh.d.ts

@@ -1,6 +1,9 @@
 /**
  * Refresh ~/.hq/work-context/sessions/<sid>/board.md for bound sessions
- * from GET /companies/{companyUid}/board at most every 60s.
+ * from the ProjectView read route at most every 60s.
+ *
+ * Board JSON remains the fallback for older projects, but story status is
+ * authoritative in ProjectView because `hq mesh story` writes there.
  * Metadata-only snapshot — never prompts or tokens.
  */
 export declare const BOARD_REFRESH_INTERVAL_MS = 60000;

package/dist/lib/mesh/live/daemon/board-refresh.js

@@ -1,6 +1,9 @@
 /**
  * Refresh ~/.hq/work-context/sessions/<sid>/board.md for bound sessions
- * from GET /companies/{companyUid}/board at most every 60s.
+ * from the ProjectView read route at most every 60s.
+ *
+ * Board JSON remains the fallback for older projects, but story status is
+ * authoritative in ProjectView because `hq mesh story` writes there.
  * Metadata-only snapshot — never prompts or tokens.
  */
 import * as fs from "node:fs";
@@ -115,9 +118,72 @@ export async function refreshBoundSessionBoards(deps) {
     }
     return { refreshed, skipped, errors };
 }
+function storiesFromProject(project) {
+    const storiesRaw = Array.isArray(project.stories) ? project.stories : [];
+    const stories = [];
+    for (const s of storiesRaw) {
+        if (!s || typeof s !== "object" || Array.isArray(s))
+            continue;
+        const row = s;
+        const id = typeof row.id === "string"
+            ? row.id
+            : typeof row.storyId === "string"
+                ? row.storyId
+                : typeof row.taskId === "string"
+                    ? row.taskId
+                    : "";
+        if (!id)
+            continue;
+        stories.push({
+            id,
+            title: typeof row.title === "string"
+                ? row.title.slice(0, 120)
+                : typeof row.name === "string"
+                    ? row.name.slice(0, 120)
+                    : undefined,
+            status: typeof row.status === "string" ? row.status : undefined,
+        });
+    }
+    return stories;
+}
+function projectViewSnapshot(raw, companyUid, projectId) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const project = raw;
+    if (project.companyUid !== companyUid || project.projectId !== projectId)
+        return null;
+    return {
+        projectId,
+        projectName: typeof project.name === "string"
+            ? project.name
+            : typeof project.title === "string"
+                ? project.title
+                : undefined,
+        stories: storiesFromProject(project),
+    };
+}
+function isMissingProject(error) {
+    // hq-pro's GET ProjectView handler emits PROJECT_VIEW_NOT_FOUND; retain the
+    // legacy PROJECT_NOT_FOUND code for compatibility with older producers.
+    return (error instanceof Error &&
+        /^404\s+(?:PROJECT_VIEW_NOT_FOUND|PROJECT_NOT_FOUND)\b/.test(error.message));
+}
 /** Build a BoardReader from meshJson-compatible fetch. */
 export function createVaultBoardReader(opts) {
     return async (companyUid, projectId) => {
+        // ProjectView is the live story-status source. Only use board.json when
+        // this project has not been migrated into ProjectView yet.
+        try {
+            const view = await opts.getJson(`/v1/work-mesh/projects/${encodeURIComponent(projectId)}?companyUid=${encodeURIComponent(companyUid)}`);
+            const snapshot = projectViewSnapshot(view, companyUid, projectId);
+            if (snapshot)
+                return snapshot;
+            throw new Error("ProjectView response did not match the requested company and project");
+        }
+        catch (error) {
+            if (!isMissingProject(error))
+                throw error;
+        }
         const raw = await opts.getJson(`/companies/${encodeURIComponent(companyUid)}/board`);
         if (!raw || typeof raw !== "object")
             return null;
@@ -140,35 +206,10 @@ export function createVaultBoardReader(opts) {
             const id = typeof p.id === "string" ? p.id : typeof p.projectId === "string" ? p.projectId : "";
             if (id !== projectId)
                 continue;
-            const storiesRaw = Array.isArray(p.stories)
-                ? p.stories
-                : Array.isArray(p.tasks)
-                    ? p.tasks
-                    : [];
-            const stories = [];
-            for (const s of storiesRaw) {
-                if (!s || typeof s !== "object" || Array.isArray(s))
-                    continue;
-                const row = s;
-                const sid = typeof row.id === "string"
-                    ? row.id
-                    : typeof row.storyId === "string"
-                        ? row.storyId
-                        : typeof row.taskId === "string"
-                            ? row.taskId
-                            : "";
-                if (!sid)
-                    continue;
-                stories.push({
-                    id: sid,
-                    title: typeof row.title === "string"
-                        ? row.title.slice(0, 120)
-                        : typeof row.name === "string"
-                            ? row.name.slice(0, 120)
-                            : undefined,
-                    status: typeof row.status === "string" ? row.status : undefined,
-                });
-            }
+            const stories = storiesFromProject({
+                ...p,
+                stories: Array.isArray(p.stories) ? p.stories : p.tasks,
+            });
             return {
                 projectId,
                 projectName: typeof p.name === "string"

package/dist/lib/mesh/live/daemon/credentials.d.ts

@@ -49,6 +49,11 @@ export interface PresenceCompany {
     companyUid: string;
     presenceTopic: string;
 }
+export interface DroppedPresenceCompany {
+    companyUid: string;
+    /** Server-supplied cause when available; otherwise a deliberately neutral label. */
+    reason: string;
+}
 export interface Contract3Bundle {
     contractVersion: 3;
     credentials: IotCredentials;
@@ -58,7 +63,7 @@ export interface Contract3Bundle {
     actorUid: string;
     actorType: "human" | "agent";
     companies: PresenceCompany[];
-    droppedCompanies: string[];
+    droppedCompanies: DroppedPresenceCompany[];
     expiresAt: string;
 }
 export type CredentialsFetcher = () => Promise<Contract3Bundle>;

package/dist/lib/mesh/live/daemon/credentials.js

@@ -229,9 +229,25 @@ export function normalizeContract3Bundle(raw) {
     if (!expiresAt) {
         throw new Error("contract-3 vend missing expiresAt");
     }
-    const dropped = Array.isArray(r.droppedCompanies)
-        ? r.droppedCompanies.filter((x) => typeof x === "string")
-        : [];
+    const droppedCompanies = [];
+    for (const item of Array.isArray(r.droppedCompanies) ? r.droppedCompanies : []) {
+        if (typeof item === "string" && item.trim()) {
+            droppedCompanies.push({ companyUid: item, reason: "unknown" });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const row = item;
+        const companyUid = typeof row.companyUid === "string" ? row.companyUid.trim() : "";
+        if (!companyUid)
+            continue;
+        droppedCompanies.push({
+            companyUid,
+            reason: typeof row.reason === "string" && row.reason.trim()
+                ? row.reason.trim()
+                : "not included",
+        });
+    }
     return {
         contractVersion: 3,
         credentials: {
@@ -246,7 +262,7 @@ export function normalizeContract3Bundle(raw) {
         actorUid,
         actorType,
         companies,
-        droppedCompanies: dropped,
+        droppedCompanies,
         expiresAt,
     };
 }

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -32,6 +32,8 @@ export interface DaemonDoctorReport {
     actorKind: CognitoActorKind;
     /** Credential vend refused (disabled / unsupported / 403). */
     presenceRefusal?: DaemonStateFile["presenceRefusal"];
+    /** Companies the current presence credential did not include. */
+    presenceDroppedCompanies: NonNullable<DaemonStateFile["presenceDroppedCompanies"]>;
     /** Pending events awaiting a retry drain (POST /v1/mesh/events). */
     emitRetryDepth: number;
     /** Last successful direct-emit POST time. */

package/dist/lib/mesh/live/daemon/doctor.js

@@ -105,6 +105,10 @@ export function collectDaemonDoctor(deps = {}) {
             `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
     }
     const presenceRefusal = state?.presenceRefusal ?? null;
+    const presenceDroppedCompanies = state?.presenceDroppedCompanies ?? [];
+    if (presenceDroppedCompanies.length > 0) {
+        unhealthyReasons.push(`presence unavailable for ${presenceDroppedCompanies.length} companies`);
+    }
     if (presenceRefusal) {
         unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
     }
@@ -132,6 +136,7 @@ export function collectDaemonDoctor(deps = {}) {
         tokenSource: auth.tokenSource,
         actorKind: auth.actorKind,
         presenceRefusal,
+        presenceDroppedCompanies,
         emitMode,
         subscribed,
         emitRetryDepth: emitRetry,
@@ -174,6 +179,13 @@ export function formatDaemonDoctor(report) {
     if (report.presenceRefusal) {
         lines.push(`presence refusal: ${report.presenceRefusal.code} (HTTP ${report.presenceRefusal.status}); next retry at ${report.presenceRefusal.nextRetryAt}`);
     }
+    if (report.presenceDroppedCompanies.length > 0) {
+        lines.push(`presence not published for ${report.presenceDroppedCompanies.length} companies: ` +
+            report.presenceDroppedCompanies
+                .map((company) => `${company.companyUid} (${company.reason})`)
+                .join(", ") +
+            `; presence credential holds ${report.companiesOnline.length} companies; these were not included`);
+    }
     if (report.unhealthy) {
         lines.push(`health: UNHEALTHY`);
         for (const reason of report.unhealthyReasons) {

package/dist/lib/mesh/live/daemon/run.js

@@ -162,7 +162,7 @@ export async function runMeshDaemon(deps = {}) {
         });
     let presence = null;
     if (deps.enablePresence !== false) {
-        const fetchCredentials = deps.fetchCredentials ??
+        const fetchCredentialsRaw = deps.fetchCredentials ??
             (async () => {
                 const t = await getToken();
                 return createContract3Fetcher({
@@ -171,6 +171,11 @@ export async function runMeshDaemon(deps = {}) {
                     env,
                 })();
             });
+        const fetchCredentials = async () => {
+            const bundle = await fetchCredentialsRaw();
+            patchDaemonState(dir, { presenceDroppedCompanies: bundle.droppedCompanies }, now);
+            return bundle;
+        };
         const presenceOpts = {
             fetchCredentials,
             mqttConnect: deps.mqttConnect,

package/dist/lib/mesh/live/daemon/state.d.ts

@@ -3,6 +3,7 @@
  */
 import type { MqttConnectionState } from "./presence.js";
 import type { FlushSummary } from "../flush.js";
+import type { DroppedPresenceCompany } from "./credentials.js";
 export interface PresenceRefusalState {
     code: string;
     status: number;
@@ -14,6 +15,8 @@ export interface DaemonStateFile {
     startedAt: string;
     mqttState: MqttConnectionState;
     companiesOnline: string[];
+    /** Companies omitted from the current presence credential bundle. */
+    presenceDroppedCompanies?: DroppedPresenceCompany[];
     actorUid?: string;
     lastFlushAt?: string;
     lastFlushResult?: FlushSummary & {

package/dist/utils/cli-telemetry.d.ts

@@ -1,4 +1,25 @@
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
+/**
+ * Exact stderr line printed once on the first signed-in TTY run that is not
+ * `--json`. Wording matches the event body: CLI version + timestamp only.
+ */
+export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+/**
+ * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
+ * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
+ */
+export declare function isCliTelemetryDisabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function telemetryDisclosureMarkerPath(): string;
+/**
+ * Print the one-line disclosure at most once per machine. Returns whether
+ * the notice has been shown (this run or a previous one). `--json` and
+ * non-TTY stdout skip the print and do not record the marker.
+ */
+export declare function maybeDiscloseCliTelemetry(stderr?: {
+    write: (chunk: string) => unknown;
+}, stdout?: {
+    isTTY?: boolean;
+}, argv?: readonly string[]): boolean;
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.

package/dist/utils/cli-telemetry.js

@@ -1,8 +1,80 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
+/**
+ * Exact stderr line printed once on the first signed-in TTY run that is not
+ * `--json`. Wording matches the event body: CLI version + timestamp only.
+ */
+export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
+const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
 let cliSessionStartedPromise;
+/**
+ * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
+ * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
+ */
+export function isCliTelemetryDisabled(env = process.env) {
+    const raw = env.HQ_TELEMETRY?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return TELEMETRY_DISABLED_VALUES.has(raw);
+}
+function hqConfigDir() {
+    const home = process.env.HOME?.trim() || os.homedir();
+    return path.join(home, ".hq");
+}
+export function telemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), DISCLOSURE_MARKER);
+}
+function wantsJsonOutput(argv = process.argv) {
+    return argv.includes("--json");
+}
+function canPrintDisclosure(stdout = process.stdout, argv = process.argv) {
+    return Boolean(stdout.isTTY) && !wantsJsonOutput(argv);
+}
+function hasShownDisclosure() {
+    try {
+        return fs.existsSync(telemetryDisclosureMarkerPath());
+    }
+    catch {
+        return false;
+    }
+}
+function recordDisclosureShown() {
+    try {
+        const dir = hqConfigDir();
+        // Do not create ~/.hq. Signed-in runs already have it (cached tokens).
+        if (!fs.existsSync(dir))
+            return;
+        fs.writeFileSync(telemetryDisclosureMarkerPath(), `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // Marker write is best effort; a repeat print is better than crashing.
+    }
+}
+/**
+ * Print the one-line disclosure at most once per machine. Returns whether
+ * the notice has been shown (this run or a previous one). `--json` and
+ * non-TTY stdout skip the print and do not record the marker.
+ */
+export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    if (hasShownDisclosure())
+        return true;
+    if (!canPrintDisclosure(stdout, argv))
+        return false;
+    try {
+        stderr.write(`${TELEMETRY_DISCLOSURE_LINE}\n`);
+    }
+    catch {
+        return false;
+    }
+    recordDisclosureShown();
+    return true;
+}
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.
@@ -13,12 +85,16 @@ export function emitCliSessionStarted(timeoutMs = TELEMETRY_TIMEOUT_MS) {
 }
 async function emitCachedCliSessionStarted(timeoutMs) {
     try {
+        if (isCliTelemetryDisabled())
+            return;
         const cached = loadCachedTokens();
         if (!cached || isExpiring(cached, 120))
             return;
         const token = isMachineIdentity() ? cached.idToken : cached.accessToken;
         if (!token)
             return;
+        const disclosed = maybeDiscloseCliTelemetry();
+        const consentBasis = disclosed ? "disclosed" : "no-consent";
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
@@ -33,7 +109,7 @@ async function emitCachedCliSessionStarted(timeoutMs) {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
-                            consentBasis: "no-consent",
+                            consentBasis,
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.122.2",
+  "version": "5.123.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,8 @@
     "assets/scaffold",
     "assets/bot-workers",
     "assets/mesh-daemon",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.md"
   ],
   "scripts": {
     "build": "node scripts/generate-dsn.mjs && tsc && node scripts/generate-command-catalog.mjs --check && node scripts/copy-schemas.mjs && node scripts/chmod-bins.mjs",