@indigoai-us/hq-cli 5.122.1 → 5.123.0

package/dist/lib/bot/daemon.js

@@ -13,7 +13,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
-import { resolveHqBinary, resolveNodeBinary } from "../mesh/live/daemon/install.js";
+import { resolveHqBinary, resolveNodeBinary, preferStableHqBinary } from "../mesh/live/daemon/install.js";
 import { botLogPath, launchdLabel } from "./paths.js";
 export function detectBotPlatform(platform = process.platform) {
     if (platform === "darwin")
@@ -192,7 +192,49 @@ function launchdLoaded(p, deps) {
         return false;
     return deps.launchctl(["print", `${launchdDomain(deps.uid)}/${p.label}`]).ok;
 }
-/** Write the unit and load it (RunAtLoad starts the bot immediately). */
+export function launchdPlistProgramArguments(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+}
+/** The hq script path baked into an installed unit, or null if none. */
+export function installedDaemonHqBinary(p, io = fs) {
+    if (io.existsSync(p.plistPath)) {
+        const args = launchdPlistProgramArguments(io.readFileSync(p.plistPath, "utf8"));
+        return args[1] ?? null;
+    }
+    if (io.existsSync(p.systemdUnitPath)) {
+        const unit = io.readFileSync(p.systemdUnitPath, "utf8");
+        const m = unit.match(/^ExecStart=\S+\s+(\S+)/m);
+        return m?.[1] ?? null;
+    }
+    return null;
+}
+/**
+ * Rewrite the unit when its hq path is missing or is the pre-move
+ * toolchain/node/bin/hq while toolchain/npm-global/bin/hq exists.
+ */
+export function repairBotDaemonIfStale(p, deps = {}) {
+    const io = deps.fsImpl ?? fs;
+    let current;
+    try {
+        current = installedDaemonHqBinary(p, {
+            existsSync: (q) => io.existsSync(q),
+            readFileSync: (q) => fs.readFileSync(q, "utf8"),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!current)
+        return null;
+    const missing = !io.existsSync(current);
+    const stale = preferStableHqBinary(current) !== current;
+    if (!missing && !stale)
+        return null;
+    return installBotDaemon(p, deps);
+}
 export function installBotDaemon(p, deps = {}) {
     const platform = deps.platform ?? detectBotPlatform();
     const io = deps.fsImpl ?? fs;

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

@@ -38,7 +38,7 @@
  * Everything with a side effect is injectable so the loop is unit-testable.
  */
 import { type OwnerContext } from "./owner-context.js";
-import type { BotApi, InboxItem } from "./api.js";
+import { type BotApi, type InboxItem } from "./api.js";
 import type { BotConfig, BotKind } from "./config.js";
 import { type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
@@ -46,6 +46,24 @@ import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "
 import { type BotState, type BotStatusFile } from "./status.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export declare const API_BACKOFF_BASE_MS = 4000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export declare const API_BACKOFF_CAP_MS: number;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export declare const API_RETRY_AFTER_CAP_MS: number;
+export declare const API_RETRY_AFTER_FLOOR_MS = 1000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export declare function apiPollDelayMs(opts: {
+    err: unknown;
+    attempt: number;
+    intervalMs: number;
+    random?: () => number;
+}): number;
 export declare const FAILURE_WINDOW_MS: number;
 export declare const FAILURE_LIMIT = 5;
 export declare const MAX_ATTEMPTS_PER_MESSAGE = 3;

package/dist/lib/bot/run.js

@@ -44,6 +44,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fullJitterDelayMs } from "../mesh/live/backoff.js";
 import { acquirePidLock, defaultPidLockDeps, releasePidLock } from "../mesh/live/daemon/pid-lock.js";
+import { BotApiError } from "./api.js";
 import { effectiveBotCompanies, effectiveBotKind, patchBotConfig, readBotConfig, SETUP_BOT_WORKER_ID } from "./config.js";
 import { ensureBotSessionMeta } from "./company-bind.js";
 import { readBotCredsIdentity } from "./creds.js";
@@ -62,6 +63,35 @@ import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
 export const HEARTBEAT_INTERVAL_MS = 30_000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export const API_BACKOFF_BASE_MS = 4_000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export const API_BACKOFF_CAP_MS = 5 * 60_000;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export const API_RETRY_AFTER_CAP_MS = 15 * 60_000;
+export const API_RETRY_AFTER_FLOOR_MS = 1_000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export function apiPollDelayMs(opts) {
+    const intervalMs = Math.max(0, opts.intervalMs);
+    const status = opts.err instanceof BotApiError ? opts.err.status : undefined;
+    const retryable = status === 429 || (typeof status === "number" && status >= 500) || !(opts.err instanceof BotApiError);
+    if (!retryable)
+        return intervalMs;
+    const retryAfter = opts.err instanceof BotApiError ? opts.err.retryAfterMs : undefined;
+    const header = typeof retryAfter === "number" && Number.isFinite(retryAfter)
+        ? Math.min(API_RETRY_AFTER_CAP_MS, Math.max(API_RETRY_AFTER_FLOOR_MS, retryAfter))
+        : 0;
+    const base = Math.max(intervalMs * 2, API_BACKOFF_BASE_MS);
+    const attempt = Math.max(0, opts.attempt);
+    const exp = Math.min(API_BACKOFF_CAP_MS, base * 2 ** attempt);
+    const random = opts.random ?? Math.random;
+    const jittered = Math.floor(exp * (1 + 0.2 * random()));
+    return Math.min(API_BACKOFF_CAP_MS, Math.max(intervalMs, exp, header, jittered));
+}
 export const FAILURE_WINDOW_MS = 10 * 60 * 1000;
 export const FAILURE_LIMIT = 5;
 export const MAX_ATTEMPTS_PER_MESSAGE = 3;
@@ -187,6 +217,7 @@ export function preflightCreds(dir, config) {
 export async function runBot(deps) {
     const now = deps.now ?? (() => new Date());
     const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
     const log = deps.log ?? createBotLogger(deps.dir, now);
     const pid = deps.pid ?? process.pid;
     const { dir, config, api, runtime } = deps;
@@ -374,18 +405,23 @@ export async function runBot(deps) {
         }
     };
     const heartbeatLoop = (async () => {
+        let heartbeatFails = 0;
         while (!stopping && state === "running") {
             try {
                 // The server's component vocabulary is the fleet one (sync/model/task…);
                 // runtime → model, inbox → task, sync → sync.
                 await api.heartbeat(config.agentUid, { model: modelHealth, task: "ok", sync: "ok" });
-                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true });
+                heartbeatFails = 0;
+                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: true, lastHeartbeatError: undefined });
+                await sleep(heartbeatIntervalMs);
             }
             catch (err) {
-                setStatus({ lastHeartbeatAt: now().toISOString(), lastHeartbeatOk: false });
-                log("warn", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+                heartbeatFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastHeartbeatOk: false, lastHeartbeatError: message.slice(0, 400) });
+                log("warn", `heartbeat failed: ${message}`);
+                await sleep(apiPollDelayMs({ err, attempt: heartbeatFails - 1, intervalMs: heartbeatIntervalMs, random }));
             }
-            await sleep(heartbeatIntervalMs);
         }
     })();
     // ── Inbox loop ─────────────────────────────────────────────────────────────
@@ -1000,6 +1036,7 @@ export async function runBot(deps) {
             }
         }
         await kickoff;
+        let inboxFails = 0;
         while (!stopping && state === "running") {
             if (hasPromotionHold(dir))
                 break;
@@ -1015,13 +1052,21 @@ export async function runBot(deps) {
             }
             try {
                 const items = await api.pullInbox(config.agentUid);
-                setStatus({ lastInboxPollAt: now().toISOString() });
+                inboxFails = 0;
+                setStatus({ lastInboxPollAt: now().toISOString(), lastInboxPollOk: true, lastInboxError: undefined });
                 for (const item of items)
                     enqueue(item);
                 pump();
             }
             catch (err) {
-                log("warn", `inbox poll failed: ${err instanceof Error ? err.message : String(err)}`);
+                inboxFails += 1;
+                const message = err instanceof Error ? err.message : String(err);
+                setStatus({ lastInboxPollOk: false, lastInboxError: message.slice(0, 400) });
+                log("warn", `inbox poll failed: ${message}`);
+                if (stopping || state !== "running")
+                    break;
+                await sleep(apiPollDelayMs({ err, attempt: inboxFails - 1, intervalMs: inboxIntervalMs, random }));
+                continue;
             }
             if (stopping || state !== "running")
                 break;

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

@@ -17,7 +17,12 @@ export interface BotStatusFile {
     recentFailures: number;
     lastHeartbeatAt?: string;
     lastHeartbeatOk?: boolean;
+    /** Last heartbeat error, when lastHeartbeatOk is false. */
+    lastHeartbeatError?: string;
     lastInboxPollAt?: string;
+    lastInboxPollOk?: boolean;
+    /** Last inbox poll error, when lastInboxPollOk is false. */
+    lastInboxError?: string;
     /** Bounded, redacted stderr excerpt of the last model-CLI failure. */
     lastError?: string;
     /** Inbound DMs answered since start. */

package/dist/lib/doctor/checks/bots.d.ts

@@ -0,0 +1,10 @@
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const BOTS_FAMILY_ID = "bots";
+export declare const BOTS_FAMILY_TITLE = "Local bots";
+export interface BotsDoctorDeps {
+    home: () => string;
+    root: (home?: string) => string;
+}
+export declare const botsFamily: CheckFamily;
+export declare function checkBots(_context: CheckContext, deps?: BotsDoctorDeps): CheckResult[];
+//# sourceMappingURL=bots.d.ts.map

package/dist/lib/doctor/checks/bots.js

@@ -0,0 +1,149 @@
+/**
+ * Local-bot doctor family: a running bot that cannot poll its inbox or
+ * heartbeat still looked healthy (`hq bot status` said online, `hq doctor`
+ * had no bot check). Offline, from ~/.hq/bots and installed LaunchAgents.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { botsRoot, botDir, launchdLabel } from "../../bot/paths.js";
+import { readBotConfig } from "../../bot/config.js";
+import { isPidAlive, readBotStatus } from "../../bot/status.js";
+export const BOTS_FAMILY_ID = "bots";
+export const BOTS_FAMILY_TITLE = "Local bots";
+const DEFAULT_DEPS = {
+    home: () => os.homedir(),
+    root: (home) => botsRoot(home ?? os.homedir()),
+};
+export const botsFamily = {
+    id: BOTS_FAMILY_ID,
+    title: BOTS_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkBots(context)),
+};
+export function checkBots(_context, deps = DEFAULT_DEPS) {
+    try {
+        return runChecks(deps);
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "bots.error",
+                message: `local bot checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+function launchdPlistHqBinary(plist) {
+    const block = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+    if (!block)
+        return null;
+    const args = [...block[1].matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1]);
+    return args[1] ?? null;
+}
+function runChecks(deps) {
+    const home = deps.home();
+    const root = deps.root(home);
+    if (!fs.existsSync(root)) {
+        return [
+            {
+                status: "NA",
+                checkId: "bots.none",
+                message: "No local bots on this computer.",
+            },
+        ];
+    }
+    const names = fs
+        .readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && readBotConfig(path.join(root, d.name)) !== null)
+        .map((d) => d.name)
+        .sort();
+    if (names.length === 0) {
+        return [
+            {
+                status: "NA",
+                checkId: "bots.none",
+                message: "No local bots on this computer.",
+            },
+        ];
+    }
+    const results = [];
+    for (const name of names) {
+        const dir = botDir(name, root);
+        const config = readBotConfig(dir);
+        if (!config)
+            continue;
+        const status = readBotStatus(dir);
+        const alive = !!status && status.state === "running" && isPidAlive(status.pid);
+        if (alive && status.lastHeartbeatOk === false) {
+            results.push({
+                status: "FAIL",
+                checkId: `bots.${name}.heartbeat`,
+                target: dir,
+                message: `${name} is running but cannot heartbeat to HQ${status.lastHeartbeatError ? ` (${status.lastHeartbeatError})` : ""}.`,
+                remediation: `hq bot logs ${name}`,
+            });
+        }
+        else if (alive) {
+            results.push({
+                status: "PASS",
+                checkId: `bots.${name}.heartbeat`,
+                target: dir,
+                message: `${name} last heartbeat succeeded.`,
+            });
+        }
+        if (alive && status.lastInboxPollOk === false) {
+            results.push({
+                status: "FAIL",
+                checkId: `bots.${name}.inbox`,
+                target: dir,
+                message: `${name} is running but cannot receive messages${status.lastInboxError ? ` (${status.lastInboxError})` : ""}.`,
+                remediation: `hq bot logs ${name}`,
+            });
+        }
+        else if (alive) {
+            results.push({
+                status: "PASS",
+                checkId: `bots.${name}.inbox`,
+                target: dir,
+                message: `${name} last inbox poll succeeded.`,
+            });
+        }
+        const plistPath = path.join(home, "Library", "LaunchAgents", `${launchdLabel(name)}.plist`);
+        if (fs.existsSync(plistPath)) {
+            let hqPath;
+            try {
+                hqPath = launchdPlistHqBinary(fs.readFileSync(plistPath, "utf8"));
+            }
+            catch {
+                hqPath = null;
+            }
+            if (hqPath && !fs.existsSync(hqPath)) {
+                results.push({
+                    status: "FAIL",
+                    checkId: `bots.${name}.daemon-binary`,
+                    target: hqPath,
+                    message: `${name} startup agent points at a missing hq binary.`,
+                    remediation: `hq bot daemon install ${name}`,
+                });
+            }
+            else if (hqPath) {
+                results.push({
+                    status: "PASS",
+                    checkId: `bots.${name}.daemon-binary`,
+                    target: hqPath,
+                    message: `${name} startup agent hq binary is present.`,
+                });
+            }
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            status: "NA",
+            checkId: "bots.idle",
+            message: `${names.length} local bot(s) are installed and not running.`,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=bots.js.map

package/dist/lib/doctor/registry.js

@@ -22,6 +22,7 @@ import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { integrationsFamily } from "./checks/integrations.js";
 import { syncHealthFamily } from "./checks/sync-health.js";
 import { workContextFamily } from "./checks/work-context.js";
+import { botsFamily } from "./checks/bots.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -256,6 +257,9 @@ export function createDefaultRegistry() {
     // Work context (US-007A): session state files, outbox depth/quarantine,
     // and default-company mode. Local-only reads under ~/.hq/work-context.
     registry.register(workContextFamily);
+    // Local bots: inbox/heartbeat reachability and a LaunchAgent whose hq
+    // path survived an HQ toolchain move. Local-only reads.
+    registry.register(botsFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/mesh/api.js

@@ -139,38 +139,106 @@ function asRecord(value) {
         ? value
         : null;
 }
-export async function listActiveThreads(token, companyUid, projectId) {
+function threadRows(data) {
+    const rows = Array.isArray(data?.threads)
+        ? data.threads
+        : Array.isArray(data?.items)
+            ? data.items
+            : [];
+    const out = [];
+    for (const row of rows) {
+        const rec = asRecord(row);
+        if (!rec)
+            continue;
+        out.push(rec);
+    }
+    return out;
+}
+function sortThreadsByActivity(threads) {
+    return [...threads].sort((a, b) => String(b.lastActivityAt || b.createdAt || "").localeCompare(String(a.lastActivityAt || a.createdAt || "")));
+}
+function isActiveThread(thread) {
+    const status = String(thread.threadStatus || "").toLowerCase();
+    return !status || ACTIVE_STATUSES.has(status);
+}
+function threadKey(thread) {
+    const id = typeof thread.threadId === "string" ? thread.threadId.trim() : "";
+    return id || undefined;
+}
+async function listThreadsByQuery(token, query) {
+    const collected = [];
+    let cursor = "";
+    for (let page = 0; page < 10; page += 1) {
+        const pageQuery = { ...query, limit: "100" };
+        if (cursor)
+            pageQuery.cursor = cursor;
+        const data = asRecord(await meshJson(token, "/v1/work-mesh/threads", { query: pageQuery }));
+        collected.push(...threadRows(data));
+        cursor = typeof data?.nextCursor === "string" ? data.nextCursor : "";
+        if (!cursor)
+            break;
+    }
+    return collected;
+}
+async function listThreadsByStatus(token, companyUid) {
     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;
+        collected.push(...(await listThreadsByQuery(token, { companyUid, status })));
+    }
+    return collected;
+}
+/**
+ * Project threads are often missing from the status index. Prefer
+ * `projectId` + `status=open`; if that combined query is rejected, fall
+ * back to `projectId` alone.
+ */
+async function listProjectThreads(token, companyUid, projectId) {
+    try {
+        return await listThreadsByQuery(token, {
+            companyUid,
+            projectId,
+            status: "open",
+        });
+    }
+    catch {
+        try {
+            return await listThreadsByQuery(token, { companyUid, projectId });
+        }
+        catch {
+            return [];
         }
     }
-    return collected
-        .filter((thread) => !projectId || thread.projectId === projectId)
-        .sort((a, b) => String(b.lastActivityAt || b.createdAt || "").localeCompare(String(a.lastActivityAt || a.createdAt || "")));
+}
+function mergeProjectAndStatusThreads(projectThreads, statusThreads, projectId) {
+    const seen = new Set();
+    const merged = [];
+    for (const thread of sortThreadsByActivity(projectThreads.filter((t) => (!t.projectId || t.projectId === projectId) && isActiveThread(t)))) {
+        const key = threadKey(thread);
+        if (key) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
+        merged.push(thread);
+    }
+    for (const thread of sortThreadsByActivity(statusThreads.filter((t) => t.projectId === projectId && isActiveThread(t)))) {
+        const key = threadKey(thread);
+        if (key) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+        }
+        merged.push(thread);
+    }
+    return merged;
+}
+export async function listActiveThreads(token, companyUid, projectId) {
+    const statusListed = await listThreadsByStatus(token, companyUid);
+    if (!projectId) {
+        return sortThreadsByActivity(statusListed);
+    }
+    const projectListed = await listProjectThreads(token, companyUid, projectId);
+    return mergeProjectAndStatusThreads(projectListed, statusListed, projectId);
 }
 export function clamp(value, max) {
     return value.length <= max ? value : value.slice(0, max);

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"