@indigoai-us/hq-cli 5.138.0 → 5.140.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.140.0] — 2026-09-23
+
+### Fixed
+
+- `hq lanes monitor-check` now recognizes a live Claude Monitor task launched through the CLI's shell/node process wrapper, so active lanes are not reported as uncovered.
+- A session hint now binds to the best existing project. An exact Board is used as-is. An exact local PRD gets a Board through the same genesis-thread, view, then register path as `project ensure`, and is bound. A single clear match is bound with a recorded reason. When nothing matches, or two candidates are close, the session stays `needs_project` and the start hook lists the candidates. `hq mesh context bind-project` applies the answer. A flush HTTP 404 downgrades that session, holds its events, and logs one line instead of dead-lettering them. `hq mesh doctor` lists `needs_project` sessions.
+
+## [5.139.0] — 2026-09-23
+
+### Added
+
+- `hq mesh project ensure <projectId> --company <slug> --stories-file prd.json` registers a missing Board view, merges an existing one without replacing live story status or assignee, then checks the company, project id, story ids, and repo paths. `hq mesh project set --create` writes a view when the GET is a 404.
+
+### Fixed
+
+- `hq report` now resolves report ids through local channel context and channel report lists instead of probing every channel with a report GET that can produce avoidable 404s.
+
 ## [5.138.0] — 2026-09-23
 
 ### Fixed

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

@@ -5708,11 +5708,36 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--repo <path[@branch]>";
                 readonly description: "Repository binding (repeatable)";
+            }, {
+                readonly flags: "--create";
+                readonly description: "Create the Board view when the GET is a 404";
             }, {
                 readonly flags: "--json";
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "ensure";
+            readonly description: "Idempotently register a PRD on the Board and verify the view";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <projectId>";
+            readonly arguments: readonly [{
+                readonly name: "projectId";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company slug or cloud uid";
+            }, {
+                readonly flags: "--stories-file <path>";
+                readonly description: "PRD JSON file with userStories and metadata.repos";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print {projectId, threadId, channelId, version, stories}";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "register";
             readonly description: "POST project registration to create or bind its project channel and Board";
@@ -5831,6 +5856,32 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "bind-project";
+            readonly description: "Bind this session to a project id, a numbered candidate, or new <slug>";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <target> [slug]";
+            readonly arguments: readonly [{
+                readonly name: "target";
+                readonly required: true;
+                readonly variadic: false;
+            }, {
+                readonly name: "slug";
+                readonly required: false;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--session <sid>";
+                readonly description: "Canonical session id";
+            }, {
+                readonly flags: "--company <slug|uid>";
+                readonly description: "Company override when creating a Board";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "organize";
             readonly description: "List or submit one-time project/task decisions (US-007B / US-005B)";

package/dist/command-catalog.generated.js

@@ -7367,6 +7367,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--repo <path[@branch]>",
                                 "description": "Repository binding (repeatable)"
                             },
+                            {
+                                "flags": "--create",
+                                "description": "Create the Board view when the GET is a 404"
+                            },
                             {
                                 "flags": "--json",
                                 "description": "Print machine-readable JSON"
@@ -7374,6 +7378,35 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "ensure",
+                        "description": "Idempotently register a PRD on the Board and verify the view",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <projectId>",
+                        "arguments": [
+                            {
+                                "name": "projectId",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company slug or cloud uid"
+                            },
+                            {
+                                "flags": "--stories-file <path>",
+                                "description": "PRD JSON file with userStories and metadata.repos"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print {projectId, threadId, channelId, version, stories}"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "register",
                         "description": "POST project registration to create or bind its project channel and Board",
@@ -7526,6 +7559,40 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "bind-project",
+                        "description": "Bind this session to a project id, a numbered candidate, or new <slug>",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <target> [slug]",
+                        "arguments": [
+                            {
+                                "name": "target",
+                                "required": true,
+                                "variadic": false
+                            },
+                            {
+                                "name": "slug",
+                                "required": false,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--session <sid>",
+                                "description": "Canonical session id"
+                            },
+                            {
+                                "flags": "--company <slug|uid>",
+                                "description": "Company override when creating a Board"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "organize",
                         "description": "List or submit one-time project/task decisions (US-007B / US-005B)",

package/dist/commands/mesh.js

@@ -12,6 +12,7 @@ import chalk from "chalk";
 import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+import { ensureProjectBoard } from "../lib/mesh/project-board.js";
 import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, } from "../lib/work-context/config.js";
@@ -36,7 +37,9 @@ import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, findAncest
 import { workContextRoot } from "../lib/work-context/paths.js";
 import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-context/migrate.js";
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
-import { readSessionState } from "../lib/work-context/state.js";
+import { readSessionState, updateSessionState } from "../lib/work-context/state.js";
+import { findLocalPrd, listNeedsProjectSessions } from "../lib/work-context/bind-best.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "../lib/work-context/contract.js";
 import { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "../lib/work-context/reconcile.js";
 import { resolveCompany } from "../lib/work-context/company.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../lib/work-context/repo-remote.js";
@@ -282,6 +285,33 @@ function parseProjectPlan(raw, source) {
         throw err;
     }
 }
+function httpStatus(err) {
+    if (err && typeof err === "object" && "status" in err && typeof err.status === "number") {
+        return err.status;
+    }
+    return undefined;
+}
+function mergeProjectStories(current, planned) {
+    const currentById = new Map(current.map((story) => [story.id, story]));
+    const plannedIds = new Set(planned.map((story) => story.id));
+    const merged = planned.map((story) => {
+        const live = currentById.get(story.id);
+        if (!live)
+            return story;
+        const status = live.status || story.status;
+        return {
+            ...story,
+            ...(status ? { status } : {}),
+            passes: status === "done" ? true : typeof live.passes === "boolean" ? live.passes : story.passes,
+            ...(live.assigneeUid ? { assigneeUid: live.assigneeUid } : {}),
+        };
+    });
+    return [...merged, ...current.filter((story) => !plannedIds.has(story.id))];
+}
+function mergeProjectRepos(current, planned) {
+    const plannedPaths = new Set(planned.map((repo) => repo.path));
+    return [...planned, ...current.filter((repo) => !plannedPaths.has(repo.path))];
+}
 async function runProjectSet(projectId, opts) {
     if (opts.storiesFile && opts.storiesJson) {
         fail("Pass only one of --stories-file or --stories-json.");
@@ -300,32 +330,63 @@ async function runProjectSet(projectId, opts) {
             ? opts.repo.map((repo, index) => parseProjectRepoSpec(repo, `--repo[${index}]`))
             : undefined;
     const { token, company } = await withCompany(opts);
-    const current = await getProjectView(token, company.companyUid, projectId);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) === 404 && opts.create) {
+            if (!source && !opts.name?.trim()) {
+                fail("`--create` needs --name or a stories file when the Board view does not exist.");
+            }
+            current = undefined;
+        }
+        else {
+            throw err;
+        }
+    }
+    if (!current && !opts.create) {
+        fail(`Work mesh project ${projectId} has no Board view. Re-run with --create to add one.`);
+    }
     const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
     const PROJECT_CHANGED = "The Board changed while you were editing. Re-run to pick up the latest.";
     let view;
-    try {
-        view = await putProjectView(token, company.companyUid, projectId, {
-            name: opts.name?.trim() || source?.name || current.name,
-            ...(opts.description !== undefined
-                ? { description: opts.description }
-                : source?.description !== undefined
-                    ? { description: source.description }
-                    : { description: current.description }),
-            stories: source?.stories ?? current.stories,
-            repos: explicitRepos ?? source?.repos ?? current.repos,
-            ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+    if (!current) {
+        const ensured = await ensureProjectBoard({
+            token,
+            company,
+            projectId,
+            name: opts.name?.trim() || source?.name || projectId,
+            description: opts.description !== undefined ? opts.description : source?.description ?? "",
+            stories: source?.stories ?? [],
+            repos: explicitRepos ?? source?.repos ?? [],
         });
+        view = ensured.view;
     }
-    catch (err) {
-        const conflict = err;
-        if (conflict.status === 409 && conflict.code === "VERSION_CONFLICT") {
-            if (opts.json) {
-                console.log(JSON.stringify({ ok: false, code: "VERSION_CONFLICT", error: PROJECT_CHANGED }));
+    else {
+        try {
+            view = await putProjectView(token, company.companyUid, projectId, {
+                name: opts.name?.trim() || source?.name || current.name,
+                ...(opts.description !== undefined
+                    ? { description: opts.description }
+                    : source?.description !== undefined
+                        ? { description: source.description }
+                        : { description: current.description }),
+                stories: source?.stories ?? current.stories,
+                repos: explicitRepos ?? source?.repos ?? current.repos,
+                ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+            });
+        }
+        catch (err) {
+            const conflict = err;
+            if (conflict.status === 409 && conflict.code === "VERSION_CONFLICT") {
+                if (opts.json) {
+                    console.log(JSON.stringify({ ok: false, code: "VERSION_CONFLICT", error: PROJECT_CHANGED }));
+                }
+                fail(PROJECT_CHANGED);
             }
-            fail(PROJECT_CHANGED);
+            throw err;
         }
-        throw err;
     }
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "project.set", principalUid, ...view }, null, 2));
@@ -347,6 +408,100 @@ async function runProjectRegister(projectId, opts) {
     }
     console.log(`Work mesh: project ${registration.projectId} registered (${boardState}; channel ${registration.channelId} ${registration.channelCreated ? "created" : "bound"})`);
 }
+async function runProjectEnsure(projectId, opts) {
+    if (!opts.storiesFile?.trim())
+        fail("`--stories-file <prd.json>` is required.");
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile);
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    // Genesis thread, then the view, then register. Register returns 403
+    // PROJECT_NOT_IN_COMPANY until both exist. A missing view uses that chain
+    // from ensureProjectBoard; an existing view is merged, then registered.
+    let registration;
+    let verified;
+    if (!current) {
+        const ensured = await ensureProjectBoard({
+            token,
+            company,
+            projectId,
+            name: source.name || projectId,
+            description: source.description ?? "",
+            stories: source.stories,
+            repos: source.repos ?? [],
+        });
+        registration = ensured.registration;
+        verified = ensured.view;
+    }
+    else {
+        const genesis = await ensureProjectThread(token, company, projectId, {
+            summary: source.name || projectId,
+        });
+        if (!genesis.threadId)
+            fail("Work mesh did not return a threadId.");
+        {
+            const stories = mergeProjectStories(current.stories, source.stories);
+            const repos = mergeProjectRepos(current.repos, source.repos ?? []);
+            const name = source.name || current.name;
+            const description = source.description !== undefined ? source.description : current.description;
+            const changed = name !== current.name ||
+                description !== current.description ||
+                JSON.stringify(stories) !== JSON.stringify(current.stories) ||
+                JSON.stringify(repos) !== JSON.stringify(current.repos);
+            if (changed) {
+                await putProjectView(token, company.companyUid, projectId, {
+                    name,
+                    description,
+                    stories,
+                    repos,
+                    ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+                });
+            }
+        }
+        registration = await registerMeshProject(token, company.companyUid, projectId);
+        if (!registration.threadId || !registration.channelId) {
+            fail("Work mesh registration did not return a threadId and channelId.");
+        }
+        verified = await getProjectView(token, company.companyUid, projectId);
+    }
+    if (verified.companyUid !== company.companyUid) {
+        fail(`Work mesh project ensure: company mismatch (expected ${company.companyUid}, got ${verified.companyUid}).`);
+    }
+    if (verified.projectId !== projectId) {
+        fail(`Work mesh project ensure: project id mismatch (expected ${projectId}, got ${verified.projectId}).`);
+    }
+    for (const story of source.stories) {
+        if (!verified.stories.some((row) => row.id === story.id)) {
+            fail(`Work mesh project ensure: missing story ${story.id}.`);
+        }
+    }
+    for (const repo of source.repos ?? []) {
+        if (!verified.repos.some((row) => row.path === repo.path)) {
+            fail(`Work mesh project ensure: missing repo ${repo.path}.`);
+        }
+    }
+    if (verified.version === undefined) {
+        fail("Work mesh project ensure: verified view has no version.");
+    }
+    const payload = {
+        projectId: verified.projectId,
+        threadId: registration.threadId,
+        channelId: registration.channelId,
+        version: verified.version,
+        stories: verified.stories,
+    };
+    if (opts.json) {
+        console.log(JSON.stringify(payload));
+        return;
+    }
+    console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
+}
 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" +
@@ -358,13 +513,86 @@ async function runDoctor(opts) {
         fail("Could not resolve the authenticated principal. Sign in again and retry `hq mesh doctor`.");
     }
     const warmed = await warmMeshConversationCache(token, principalUid);
+    const needsProject = listNeedsProjectSessions(workContextHomeRoot());
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "doctor", ...warmed }, null, 2));
+        console.log(JSON.stringify({ ok: true, action: "doctor", ...warmed, needsProject }, 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})`);
+    if (needsProject.length === 0) {
+        console.log("needs_project sessions: none");
+        return;
+    }
+    console.log(`needs_project sessions: ${needsProject.length}`);
+    for (const row of needsProject) {
+        const choices = row.candidates.map((candidate) => candidate.projectId).join(", ") || "(none)";
+        console.log(`- ${row.sessionId}: ${row.reason ?? "no reason recorded"}; candidates: ${choices}`);
+    }
+}
+async function runBindProject(target, opts) {
+    const sessionId = opts.session.trim();
+    const root = workContextHomeRoot();
+    const current = readSessionState(sessionId, root);
+    if (!current)
+        fail(`No work-context state for session ${sessionId}.`);
+    let projectId = target.trim();
+    if (projectId === "new") {
+        const slug = opts.slug?.trim();
+        if (!slug)
+            fail("Usage: hq mesh context bind-project new <slug> --session <sid>");
+        const hqRoot = process.env.HQ_ROOT?.trim() || findHqRoot();
+        const prdPath = findLocalPrd(hqRoot, current.companySlug, slug);
+        if (!prdPath) {
+            fail(`No PRD for ${slug}. Run /prd before binding a new project.`);
+        }
+        if (!current.companyUid)
+            fail(`Session ${sessionId} has no company. Bind a company first.`);
+        const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
+        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+        await ensureProjectBoard({
+            token,
+            company: {
+                companyUid: current.companyUid,
+                companySlug: current.companySlug || company.companySlug,
+            },
+            projectId: slug,
+            name: plan.name || slug,
+            description: plan.description ?? "",
+            stories: plan.stories,
+            repos: plan.repos ?? [],
+        });
+        projectId = slug;
+    }
+    else if (/^[1-9][0-9]*$/.test(projectId)) {
+        const index = Number(projectId) - 1;
+        const chosen = current.projectCandidates?.[index];
+        if (!chosen)
+            fail(`No candidate ${projectId} on session ${sessionId}.`);
+        projectId = chosen.projectId;
+    }
+    const updated = updateSessionState(sessionId, root, (state) => {
+        if (!state)
+            return null;
+        return {
+            ...state,
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            contextStatus: state.taskId ? "bound" : "needs_task",
+            projectId,
+            projectGate: undefined,
+            projectCandidates: undefined,
+            projectBindReason: `operator selected ${projectId}`,
+            updatedAt: new Date().toISOString(),
+        };
+    });
+    if (!updated)
+        fail(`No work-context state for session ${sessionId}.`);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "context.bind-project", sessionId, projectId, contextStatus: updated.contextStatus }));
+        return;
+    }
+    console.log(`Work mesh: session ${sessionId} bound to project ${projectId}`);
 }
 async function runContextReconcile(opts) {
     if (!opts.observationFile && !opts.observationJson) {
@@ -455,6 +683,20 @@ async function runContextReconcile(opts) {
         fetchCandidates,
         offline,
         validateMembership,
+        ensureProjectBoard: token
+            ? async ({ companyUid, projectId, prdPath }) => {
+                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+                await ensureProjectBoard({
+                    token,
+                    company: { companyUid, companySlug: companyUid },
+                    projectId,
+                    name: plan.name || projectId,
+                    description: plan.description ?? "",
+                    stories: plan.stories,
+                    repos: plan.repos ?? [],
+                });
+            }
+            : undefined,
     });
     for (const line of outcome.diagnostics) {
         console.error(line);
@@ -1347,8 +1589,16 @@ export function registerMeshCommand(program) {
         .option("--stories-json <json>", "Story array or JSON object with userStories")
         .option("--repos-json <json>", "Repository array, such as [{path,branch}]")
         .option("--repo <path[@branch]>", "Repository binding (repeatable)", collectRepeatable)
+        .option("--create", "Create the Board view when the GET is a 404")
         .option("--json", "Print machine-readable JSON")
         .action((projectId, opts) => wrap(() => runProjectSet(projectId, opts))());
+    project
+        .command("ensure <projectId>")
+        .description("Idempotently register a PRD on the Board and verify the view")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .requiredOption("--stories-file <path>", "PRD JSON file with userStories and metadata.repos")
+        .option("--json", "Print {projectId, threadId, channelId, version, stories}")
+        .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
     project
         .command("register <projectId>")
         .description("POST project registration to create or bind its project channel and Board")
@@ -1392,6 +1642,15 @@ export function registerMeshCommand(program) {
         .option("--use-device-default", "Opt in to historical repair using the device default (lower-confidence attribution)")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runContextBackfillHeld(opts))());
+    context
+        .command("bind-project")
+        .description("Bind this session to a project id, a numbered candidate, or new <slug>")
+        .argument("<target>", "Project id, candidate number, or new")
+        .argument("[slug]", "Project slug when target is new")
+        .requiredOption("--session <sid>", "Canonical session id")
+        .option("--company <slug|uid>", "Company override when creating a Board")
+        .option("--json", "Print machine-readable JSON")
+        .action((target, slug, opts) => wrap(() => runBindProject(target, { ...opts, slug }))());
     context
         .command("organize")
         .description("List or submit one-time project/task decisions (US-007B / US-005B)")

package/dist/commands/report.d.ts

@@ -1,4 +1,3 @@
-/** `hq report` — safe channel-report lifecycle commands for bot runbooks. */
 import { Command } from "commander";
 import { buildReportTarball, deployOrgContext, type ChannelReport, type DeployAccessPolicy, type ReportDeployment, type ReportPatch } from "../lib/report-publish.js";
 /** Explicit context has priority; discovery is the authenticated fallback for normal CLI use. */