@indigoai-us/hq-cli 5.139.0 → 5.140.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [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

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

@@ -5856,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

@@ -7559,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";
@@ -345,47 +348,44 @@ async function runProjectSet(projectId, opts) {
     if (!current && !opts.create) {
         fail(`Work mesh project ${projectId} has no Board view. Re-run with --create to add one.`);
     }
-    if (!current) {
-        // Register requires a genesis thread and a project view. Create the thread
-        // before the PUT; register runs after the view exists.
-        await ensureProjectThread(token, company, projectId, {
-            summary: opts.name?.trim() || source?.name || projectId,
-        });
-    }
     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 || projectId,
-            ...(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 }));
-            }
-            fail(PROJECT_CHANGED);
-        }
-        throw err;
-    }
-    if (!current) {
-        const registration = await registerMeshProject(token, company.companyUid, projectId);
-        if (!registration.threadId || !registration.channelId) {
-            fail("Work mesh registration did not return a threadId and channelId.");
+    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 } : {}),
+            });
         }
-        const verified = await getProjectView(token, company.companyUid, projectId);
-        if (verified.projectId !== projectId || verified.companyUid !== company.companyUid) {
-            fail(`Work mesh project set --create: verified view does not match ${company.companyUid}/${projectId}.`);
+        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);
+            }
+            throw err;
         }
     }
     if (opts.json) {
@@ -422,44 +422,54 @@ async function runProjectEnsure(projectId, opts) {
             throw err;
     }
     // Genesis thread, then the view, then register. Register returns 403
-    // PROJECT_NOT_IN_COMPANY until both exist.
-    const genesis = await ensureProjectThread(token, company, projectId, {
-        summary: source.name || projectId,
-    });
-    if (!genesis.threadId)
-        fail("Work mesh did not return a threadId.");
+    // 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) {
-        await putProjectView(token, company.companyUid, projectId, {
+        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 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 } : {}),
-            });
+        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);
     }
-    const registration = await registerMeshProject(token, company.companyUid, projectId);
-    if (!registration.threadId || !registration.channelId) {
-        fail("Work mesh registration did not return a threadId and channelId.");
-    }
-    const 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}).`);
     }
@@ -503,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) {
@@ -600,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);
@@ -1545,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/lib/lanes/monitor.js

@@ -348,7 +348,26 @@ function defaultProcessCommands() {
     }
 }
 function processHasExactCommand(processCommands, command) {
-    return processCommands.some((line) => line.trim() === command);
+    const laneIds = parseCanonicalWatchCommand(command);
+    if (!laneIds)
+        return false;
+    const expectedSuffix = ["lanes", "watch", ...laneIds];
+    return processCommands.some((line) => {
+        const tokens = line.trim().split(/\s+/u);
+        const suffixStart = tokens.length - expectedSuffix.length;
+        if (suffixStart < 1)
+            return false;
+        if (!expectedSuffix.every((token, index) => tokens[suffixStart + index] === token)) {
+            return false;
+        }
+        const hqToken = tokens[suffixStart - 1];
+        if (path.basename(hqToken) !== "hq")
+            return false;
+        const prefix = tokens.slice(0, suffixStart - 1);
+        return (prefix.length === 0 ||
+            (prefix.length === 1 &&
+                ["bun", "deno", "node", "nodejs", "ts-node", "tsx"].includes(path.basename(prefix[0]))));
+    });
 }
 export function readLiveMonitorEvidence(sessionId, options = {}) {
     if (!SESSION_ID_PATTERN.test(sessionId)) {

package/dist/lib/mesh/live/flush.d.ts

@@ -16,7 +16,7 @@ export declare const HELD_TTL_MS: number;
 export declare const HELD_RETRY_INTERVAL_MS: number;
 /** Cap held.jsonl size; oldest overflow is dead-lettered with HELD_OVERFLOW. */
 export declare const HELD_MAX_LINES = 20000;
-export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
+export type HeldReason = "STATE_ABSENT" | "NEEDS_COMPANY" | "COMPANY_CONFLICT" | "NEEDS_PROJECT" | "HELD_EXPIRED" | "HELD_OVERFLOW";
 export interface HeldLineRecord {
     /** Original spool event fields. */
     event: Record<string, unknown>;

package/dist/lib/mesh/live/flush.js

@@ -12,7 +12,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { resolveCompany } from "../../work-context/company.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../../work-context/repo-remote.js";
-import { readSessionState } from "../../work-context/state.js";
+import { readSessionState, updateSessionState } from "../../work-context/state.js";
 import { repairAckedRegisterStates } from "../../work-context/outbox.js";
 import { workContextRoot } from "../../work-context/paths.js";
 import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.js";
@@ -222,6 +222,7 @@ export async function flushSessionEvents(deps) {
         const markDisposed = (event) => {
             pendingRestore.delete(event);
         };
+        const loggedProject404 = new Set();
         for (const [sessionId, items] of bySession) {
             const state = readSessionState(sessionId, deps.workContextRoot);
             if (state?.companyConfidence === "device_default" &&
@@ -286,6 +287,36 @@ export async function flushSessionEvents(deps) {
                     accountBatchSuccess(result.body, originalChunk, deps.workMeshRoot, now, summary, markDisposed);
                     continue;
                 }
+                if (!result.retryable && result.status === 404) {
+                    const rejectedProjectId = decision.projectId;
+                    updateSessionState(sessionId, deps.workContextRoot, (current) => {
+                        if (!current)
+                            return current;
+                        return {
+                            ...current,
+                            contextStatus: "needs_project",
+                            projectGate: "missing_board",
+                            projectBindReason: "server returned HTTP 404 for this session's project",
+                            projectCandidates: rejectedProjectId
+                                ? [{ projectId: rejectedProjectId }]
+                                : current.projectCandidates,
+                            projectId: undefined,
+                            taskId: undefined,
+                            updatedAt: now().toISOString(),
+                        };
+                    });
+                    if (!loggedProject404.has(sessionId)) {
+                        loggedProject404.add(sessionId);
+                        deps.log?.(`work-mesh: session ${sessionId} project missing (HTTP 404); downgraded to needs_project and held events`);
+                    }
+                    const heldAt = now().toISOString();
+                    for (const item of originalChunk) {
+                        appendHeldLine(heldEnvelope(item.event, "NEEDS_PROJECT", item.heldAt ?? heldAt), deps.workMeshRoot);
+                        summary.held += 1;
+                        markDisposed(item.event);
+                    }
+                    continue;
+                }
                 if (!result.retryable) {
                     const at = now().toISOString();
                     for (const item of originalChunk) {
@@ -484,6 +515,9 @@ function classifySession(state) {
     if (state.contextStatus === "company_conflict") {
         return { action: "hold", heldReason: "COMPANY_CONFLICT" };
     }
+    if (state.projectGate === "choose" || state.projectGate === "missing_board") {
+        return { action: "hold", heldReason: "NEEDS_PROJECT" };
+    }
     if (!WRITABLE_CONTEXT_STATUSES.has(state.contextStatus)) {
         return { action: "hold", heldReason: "STATE_ABSENT" };
     }

package/dist/lib/mesh/project-board.d.ts

@@ -0,0 +1,19 @@
+import { type MeshCompany, type MeshProjectRegistration, type MeshProjectRepo, type MeshProjectStoryInput, type MeshProjectView } from "./api.js";
+/**
+ * Create a missing Board. Register returns 403 PROJECT_NOT_IN_COMPANY until
+ * the genesis thread and the project view both exist, so the order is fixed:
+ * thread, view, register, then a GET to confirm the view.
+ */
+export declare function ensureProjectBoard(input: {
+    token: string;
+    company: MeshCompany;
+    projectId: string;
+    name: string;
+    description?: string;
+    stories: MeshProjectStoryInput[];
+    repos?: MeshProjectRepo[];
+}): Promise<{
+    view: MeshProjectView;
+    registration: MeshProjectRegistration;
+}>;
+//# sourceMappingURL=project-board.d.ts.map

package/dist/lib/mesh/project-board.js

@@ -0,0 +1,27 @@
+import { ensureProjectThread, getProjectView, putProjectView, registerMeshProject, } from "./api.js";
+/**
+ * Create a missing Board. Register returns 403 PROJECT_NOT_IN_COMPANY until
+ * the genesis thread and the project view both exist, so the order is fixed:
+ * thread, view, register, then a GET to confirm the view.
+ */
+export async function ensureProjectBoard(input) {
+    const genesis = await ensureProjectThread(input.token, input.company, input.projectId, {
+        summary: input.name || input.projectId,
+    });
+    if (!genesis.threadId) {
+        throw new Error("Work mesh did not return a threadId.");
+    }
+    await putProjectView(input.token, input.company.companyUid, input.projectId, {
+        name: input.name || input.projectId,
+        description: input.description ?? "",
+        stories: input.stories,
+        repos: input.repos ?? [],
+    });
+    const registration = await registerMeshProject(input.token, input.company.companyUid, input.projectId);
+    const view = await getProjectView(input.token, input.company.companyUid, input.projectId);
+    if (view.projectId !== input.projectId || view.companyUid !== input.company.companyUid) {
+        throw new Error(`Work mesh project board does not match ${input.company.companyUid}/${input.projectId}.`);
+    }
+    return { view, registration };
+}
+//# sourceMappingURL=project-board.js.map

package/dist/lib/work-context/bind-best.d.ts

@@ -0,0 +1,64 @@
+/**
+ * US-036: pick the best existing project for a session hint.
+ * Exact Board, then exact local PRD, then a ranked match.
+ * A tie or an empty field stays unbound so the session can ask.
+ */
+export interface BindCandidate {
+    projectId: string;
+    title?: string;
+    score: number;
+}
+export interface CatalogProject {
+    projectId: string;
+    title?: string;
+    repos: string[];
+    journalMtimeMs?: number;
+    hasPrd: boolean;
+    hasBoard: boolean;
+    prdPath?: string;
+}
+export type RefineAction = {
+    action: "keep";
+} | {
+    action: "bind";
+    projectId: string;
+    reason: string;
+} | {
+    action: "create";
+    projectId: string;
+    prdPath: string;
+    reason: string;
+} | {
+    action: "ask";
+    reason: string;
+    candidates: BindCandidate[];
+};
+export declare function scoreProject(hint: string, row: CatalogProject, repoPath: string | undefined, nowMs: number): number;
+export declare function discoverProjects(input: {
+    hqRoot?: string;
+    companySlug?: string;
+    companyUid?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): CatalogProject[];
+export declare function refineProjectBinding(input: {
+    hint?: string;
+    hqRoot?: string;
+    companySlug?: string;
+    companyUid?: string;
+    repoPath?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    nowMs?: number;
+}): RefineAction;
+export declare function findLocalPrd(hqRoot: string | undefined, companySlug: string | undefined, projectId: string): string | null;
+export declare function listNeedsProjectSessions(workContextRoot: string): Array<{
+    sessionId: string;
+    reason?: string;
+    candidates: BindCandidate[];
+}>;
+export declare function formatProjectAsk(candidates: Array<{
+    projectId: string;
+    title?: string;
+}>): string;
+//# sourceMappingURL=bind-best.d.ts.map

package/dist/lib/work-context/bind-best.js

@@ -0,0 +1,299 @@
+/**
+ * US-036: pick the best existing project for a session hint.
+ * Exact Board, then exact local PRD, then a ranked match.
+ * A tie or an empty field stays unbound so the session can ask.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { meshCacheRoot } from "../mesh/cache.js";
+const MARGIN = 15;
+const CLEAR_FLOOR = 25;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function tokens(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((part) => part.length > 2);
+}
+export function scoreProject(hint, row, repoPath, nowMs) {
+    const hintL = hint.toLowerCase();
+    const idL = row.projectId.toLowerCase();
+    let score = 0;
+    if (idL === hintL)
+        score += 100;
+    else if (idL.startsWith(hintL) || hintL.startsWith(idL))
+        score += 40;
+    const hintTokens = new Set(tokens(hint));
+    const titleTokens = new Set(tokens(`${row.projectId} ${row.title ?? ""}`));
+    for (const token of hintTokens) {
+        if (titleTokens.has(token))
+            score += 15;
+    }
+    if (repoPath) {
+        const repoL = repoPath.toLowerCase();
+        if (row.repos.some((repo) => {
+            const item = repo.toLowerCase();
+            return item.length > 0 && (repoL.includes(item) || item.includes(repoL));
+        })) {
+            score += 50;
+        }
+    }
+    if (row.journalMtimeMs) {
+        const age = nowMs - row.journalMtimeMs;
+        if (age >= 0 && age < 14 * DAY_MS)
+            score += 10;
+        else if (age >= 0 && age < 60 * DAY_MS)
+            score += 5;
+    }
+    return score;
+}
+function readJson(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function reposFromMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object")
+        return [];
+    const repos = metadata.repos;
+    if (!Array.isArray(repos))
+        return [];
+    const out = [];
+    for (const repo of repos) {
+        if (typeof repo === "string" && repo.trim())
+            out.push(repo.trim());
+        else if (repo && typeof repo === "object" && typeof repo.path === "string") {
+            const value = repo.path.trim();
+            if (value)
+                out.push(value);
+        }
+    }
+    return out;
+}
+function journalMtime(dir) {
+    const candidates = ["journal.md", "journal.json", path.join("journal", "index.md")];
+    let newest = 0;
+    for (const name of candidates) {
+        try {
+            const stat = fs.statSync(path.join(dir, name));
+            if (stat.mtimeMs > newest)
+                newest = stat.mtimeMs;
+        }
+        catch {
+            /* absent */
+        }
+    }
+    try {
+        const journalDir = path.join(dir, "journal");
+        for (const name of fs.readdirSync(journalDir)) {
+            const stat = fs.statSync(path.join(journalDir, name));
+            if (stat.mtimeMs > newest)
+                newest = stat.mtimeMs;
+        }
+    }
+    catch {
+        /* absent */
+    }
+    return newest > 0 ? newest : undefined;
+}
+function absorbDir(map, dir, projectId) {
+    const prdPath = path.join(dir, "prd.json");
+    const prd = fs.existsSync(prdPath) ? readJson(prdPath) : null;
+    const current = map.get(projectId) ?? {
+        projectId,
+        repos: [],
+        hasPrd: false,
+        hasBoard: false,
+    };
+    if (prd) {
+        current.hasPrd = true;
+        current.prdPath = prdPath;
+        const title = typeof prd.name === "string" ? prd.name
+            : typeof prd.title === "string" ? prd.title
+                : undefined;
+        if (title)
+            current.title = title;
+        const repos = reposFromMetadata(prd.metadata);
+        if (repos.length)
+            current.repos = repos;
+    }
+    const journal = journalMtime(dir);
+    if (journal)
+        current.journalMtimeMs = Math.max(current.journalMtimeMs ?? 0, journal);
+    map.set(projectId, current);
+}
+function listProjectDirs(parent, map) {
+    if (!fs.existsSync(parent))
+        return;
+    let names;
+    try {
+        names = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+            continue;
+        const dir = path.join(parent, name);
+        try {
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        absorbDir(map, dir, name);
+    }
+}
+export function discoverProjects(input) {
+    const map = new Map();
+    const hqRoot = input.hqRoot?.trim();
+    const slug = input.companySlug?.trim();
+    if (hqRoot && slug) {
+        listProjectDirs(path.join(hqRoot, "companies", slug, "projects"), map);
+        listProjectDirs(path.join(hqRoot, "personal", "projects"), map);
+    }
+    if (input.companyUid) {
+        const cache = path.join(meshCacheRoot(input.home ?? os.homedir(), input.env), "projects", input.companyUid);
+        if (fs.existsSync(cache)) {
+            for (const name of fs.readdirSync(cache)) {
+                if (!name.endsWith(".json"))
+                    continue;
+                const projectId = name.slice(0, -".json".length);
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(projectId))
+                    continue;
+                const view = readJson(path.join(cache, name));
+                const current = map.get(projectId) ?? {
+                    projectId,
+                    repos: [],
+                    hasPrd: false,
+                    hasBoard: false,
+                };
+                current.hasBoard = true;
+                const title = typeof view?.name === "string" ? view.name : undefined;
+                if (title && !current.title)
+                    current.title = title;
+                const repos = Array.isArray(view?.repos) ? reposFromMetadata({ repos: view?.repos }) : [];
+                if (repos.length && current.repos.length === 0)
+                    current.repos = repos;
+                map.set(projectId, current);
+            }
+        }
+    }
+    return [...map.values()];
+}
+export function refineProjectBinding(input) {
+    const hint = input.hint?.trim();
+    if (!hint)
+        return { action: "keep" };
+    const catalog = discoverProjects(input);
+    const exact = catalog.find((row) => row.projectId === hint);
+    if (exact?.hasBoard) {
+        return { action: "bind", projectId: hint, reason: "exact slug has a Board" };
+    }
+    if (exact?.hasPrd && exact.prdPath) {
+        return {
+            action: "create",
+            projectId: hint,
+            prdPath: exact.prdPath,
+            reason: "exact slug has a local PRD; Board created from that PRD",
+        };
+    }
+    if (catalog.length === 0)
+        return { action: "keep" };
+    const nowMs = input.nowMs ?? Date.now();
+    const ranked = catalog
+        .filter((row) => row.projectId !== hint)
+        .map((row) => ({
+        projectId: row.projectId,
+        title: row.title,
+        score: scoreProject(hint, row, input.repoPath, nowMs),
+    }))
+        .filter((row) => row.score > 0)
+        .sort((a, b) => b.score - a.score || a.projectId.localeCompare(b.projectId));
+    if (ranked.length === 0) {
+        return {
+            action: "ask",
+            reason: `no project matches ${hint}`,
+            candidates: [],
+        };
+    }
+    const top = ranked[0];
+    const second = ranked[1];
+    const clear = top.score >= CLEAR_FLOOR && (!second || top.score - second.score >= MARGIN);
+    if (clear) {
+        return {
+            action: "bind",
+            projectId: top.projectId,
+            reason: `best match for ${hint}: ${top.projectId} (score ${top.score})`,
+        };
+    }
+    return {
+        action: "ask",
+        reason: `unclear match for ${hint}`,
+        candidates: ranked.slice(0, 5).map((row) => ({
+            projectId: row.projectId,
+            ...(row.title ? { title: row.title } : {}),
+            score: row.score,
+        })),
+    };
+}
+export function findLocalPrd(hqRoot, companySlug, projectId) {
+    if (!hqRoot || !companySlug)
+        return null;
+    const candidates = [
+        path.join(hqRoot, "companies", companySlug, "projects", projectId, "prd.json"),
+        path.join(hqRoot, "personal", "projects", projectId, "prd.json"),
+    ];
+    return candidates.find((file) => fs.existsSync(file)) ?? null;
+}
+export function listNeedsProjectSessions(workContextRoot) {
+    const dir = path.join(workContextRoot, "sessions");
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const raw = readJson(path.join(dir, name));
+        if (!raw || raw.contextStatus !== "needs_project")
+            continue;
+        const sessionId = typeof raw.sessionId === "string" ? raw.sessionId : name.replace(/\.json$/, "");
+        const candidates = Array.isArray(raw.projectCandidates)
+            ? raw.projectCandidates.flatMap((item) => {
+                if (!item || typeof item !== "object")
+                    return [];
+                const projectId = item.projectId;
+                if (typeof projectId !== "string" || !projectId)
+                    return [];
+                const title = item.title;
+                const score = item.score;
+                return [{
+                        projectId,
+                        ...(typeof title === "string" ? { title } : {}),
+                        score: typeof score === "number" ? score : 0,
+                    }];
+            })
+            : [];
+        out.push({
+            sessionId,
+            ...(typeof raw.projectBindReason === "string" ? { reason: raw.projectBindReason } : {}),
+            candidates,
+        });
+    }
+    return out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+}
+export function formatProjectAsk(candidates) {
+    const parts = candidates.map((candidate, index) => {
+        const title = candidate.title?.trim() || candidate.projectId;
+        return `${index + 1}) ${candidate.projectId} ${title}`;
+    });
+    return `This session is not bound to a project. Best matches: ${parts.join(" ")}. Reply with a number, a project id, or \`new <slug>\`.`;
+}
+//# sourceMappingURL=bind-best.js.map

package/dist/lib/work-context/contract.d.ts

@@ -61,6 +61,14 @@ export interface ContextResult {
     bindingEpisodeId?: string;
     clientOperationId: string;
     errorCode?: string;
+    /** Why a project was chosen, or why the session is asking. Local consumers only. */
+    projectBindReason?: string;
+    /** Ranked alternatives when classification is needs_project. */
+    projectCandidates?: Array<{
+        projectId: string;
+        title?: string;
+        score?: number;
+    }>;
 }
 export type NormalizeTaskIdResult = {
     ok: true;

package/dist/lib/work-context/reconcile.d.ts

@@ -69,6 +69,15 @@ export interface ReconcileDeps {
      * companyUid when local resolution only yielded a slug. Injectable for tests.
      */
     validateMembership?: (slug: string) => Promise<MembershipValidationResult> | MembershipValidationResult;
+    /**
+     * Register a Board and PUT the local PRD. Called only when online and the
+     * exact slug already has a local project folder.
+     */
+    ensureProjectBoard?: (input: {
+        companyUid: string;
+        projectId: string;
+        prdPath: string;
+    }) => Promise<void>;
 }
 export interface ReconcileOutcome {
     result: ContextResult;

package/dist/lib/work-context/reconcile.js

@@ -9,6 +9,7 @@ import { invalidateDefaultCompanyMemberships, } from "./config.js";
 import { WORK_CONTEXT_CONTRACT_VERSION, normalizeTaskId, } from "./contract.js";
 import { EXIT_INVALID_IDENTITY, EXIT_NOT_TRACKING, EXIT_OK, InvalidDecisionOriginError, NotTrackingError, } from "./errors.js";
 import { decisionFromCandidates, } from "./organize.js";
+import { refineProjectBinding } from "./bind-best.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
 import { enqueueOutbox, listOutboxOperations, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
@@ -35,6 +36,10 @@ function resultOf(parts) {
         out.bindingEpisodeId = parts.bindingEpisodeId;
     if (parts.errorCode)
         out.errorCode = parts.errorCode;
+    if (parts.projectBindReason)
+        out.projectBindReason = parts.projectBindReason;
+    if (parts.projectCandidates)
+        out.projectCandidates = parts.projectCandidates;
     return out;
 }
 function parseUntrackedOrigin(obs) {
@@ -441,8 +446,77 @@ export async function reconcileObservation(obs, deps) {
             projectResolved = null;
         }
     }
-    const projectId = projectResolved?.projectId;
-    const taskId = projectResolved?.taskId;
+    let projectId = projectResolved?.projectId;
+    let taskId = projectResolved?.taskId;
+    let projectBindReason;
+    let projectCandidates;
+    let projectGate;
+    if (projectResolved &&
+        projectId &&
+        projectResolved.source !== "existing_binding" &&
+        obs.source !== "transcript" &&
+        hqRoot &&
+        resolvedCompany.slug) {
+        const refined = refineProjectBinding({
+            hint: projectId,
+            hqRoot,
+            companySlug: resolvedCompany.slug,
+            companyUid: resolvedCompany.uid,
+            repoPath: cwd,
+            env,
+            nowMs: nowFn().getTime(),
+        });
+        if (refined.action === "bind") {
+            if (refined.projectId !== projectId)
+                taskId = undefined;
+            projectId = refined.projectId;
+            projectBindReason = refined.reason;
+            diagnostics.push(`project bind: ${refined.reason}`);
+        }
+        else if (refined.action === "create") {
+            projectBindReason = refined.reason;
+            if (!deps.offline && resolvedCompany.uid && deps.ensureProjectBoard) {
+                try {
+                    await deps.ensureProjectBoard({
+                        companyUid: resolvedCompany.uid,
+                        projectId,
+                        prdPath: refined.prdPath,
+                    });
+                    diagnostics.push(`project board created for ${projectId}`);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    diagnostics.push(`project board create failed: ${message}`);
+                    projectBindReason = `Board create failed for ${projectId}: ${message}`;
+                    projectCandidates = [{ projectId, title: projectId }];
+                    projectGate = "choose";
+                    projectId = undefined;
+                    taskId = undefined;
+                    projectResolved = null;
+                }
+            }
+            else {
+                diagnostics.push(`project bind: local PRD for ${projectId}; Board create waits for online reconcile`);
+            }
+        }
+        else if (refined.action === "ask") {
+            projectBindReason = refined.reason;
+            projectCandidates = refined.candidates;
+            projectGate = "choose";
+            projectId = undefined;
+            taskId = undefined;
+            projectResolved = null;
+            diagnostics.push(`project ask: ${refined.reason}`);
+        }
+    }
+    const bindResultFields = {
+        ...(projectBindReason ? { projectBindReason } : {}),
+        ...(projectCandidates ? { projectCandidates } : {}),
+    };
+    const bindStateFields = {
+        ...bindResultFields,
+        ...(projectGate ? { projectGate } : {}),
+    };
     // Trusted / deterministic auto-bind never asks.
     // Transcript-sourced sessions never ask (US-018).
     const fromTranscript = obs.source === "transcript";
@@ -457,7 +531,10 @@ export async function reconcileObservation(obs, deps) {
         (projectResolved.source === "deterministic_cwd" ||
             projectResolved.source === "deterministic_registry"));
     let classification;
-    if (autoBound) {
+    if (projectGate === "choose") {
+        classification = "needs_project";
+    }
+    else if (autoBound) {
         classification = "bound";
     }
     else if (projectId && taskId) {
@@ -569,6 +646,7 @@ export async function reconcileObservation(obs, deps) {
             ...(typeof toolWrites === "number" ? { toolWrites } : {}),
             ...(hasTurn ? { hasTurn: true } : {}),
             ...(decision ? { decision } : {}),
+            ...bindStateFields,
             ...transcriptFields,
         }, prior), deps.root);
         const kind = registerClassification === "bound"
@@ -591,6 +669,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 bindingEpisodeId: acknowledgedPrior.bindingEpisodeId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics,
@@ -652,6 +731,7 @@ export async function reconcileObservation(obs, deps) {
             ...(hasTurn ? { hasTurn: true } : {}),
             ...(decision ? { decision } : {}),
             ...(companyConfidence ? { companyConfidence } : {}),
+            ...bindStateFields,
             ...transcriptFields,
         }, prior);
         statePath = writeSessionState(stateWrite, deps.root);
@@ -690,6 +770,7 @@ export async function reconcileObservation(obs, deps) {
                 companySlug: resolvedCompany.slug,
                 projectId,
                 taskId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, "offline/local: operation remains queued"],
@@ -736,6 +817,7 @@ export async function reconcileObservation(obs, deps) {
                 startedAt,
                 ...(typeof toolWrites === "number" ? { toolWrites } : {}),
                 ...(hasTurn ? { hasTurn: true } : {}),
+                ...bindStateFields,
                 ...transcriptFields,
             }, 
             // Merge against the just-written projection rather than the stale
@@ -761,6 +843,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 bindingEpisodeId: delivered.receiptId,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, `acked receipt=${delivered.receiptId}`],
@@ -781,6 +864,7 @@ export async function reconcileObservation(obs, deps) {
                 projectId,
                 taskId,
                 errorCode: delivered.code,
+                ...bindResultFields,
             }),
             exitCode: EXIT_OK,
             diagnostics: [...diagnostics, `transient ${delivered.code}; remains queued`],
@@ -801,6 +885,7 @@ export async function reconcileObservation(obs, deps) {
             projectId,
             taskId,
             errorCode: delivered.code,
+            ...bindResultFields,
         }),
         exitCode: EXIT_OK,
         diagnostics: [...diagnostics, `quarantined: ${delivered.code}`],

package/dist/lib/work-context/state.d.ts

@@ -91,6 +91,19 @@ export interface SessionStateFile {
     transcriptMarker?: "from transcript";
     /** Historical repair under device-default evidence is intentionally weak. */
     companyConfidence?: "device_default";
+    /** Why the current project was chosen, or why the session is asking. */
+    projectBindReason?: string;
+    /** Ranked alternatives when the session is waiting for a project choice. */
+    projectCandidates?: Array<{
+        projectId: string;
+        title?: string;
+        score?: number;
+    }>;
+    /**
+     * When set, flush holds events instead of posting them.
+     * `choose` — the match was unclear. `missing_board` — the server 404'd the project.
+     */
+    projectGate?: "choose" | "missing_board";
     updatedAt: string;
 }
 /**

package/dist/lib/work-context/state.js

@@ -29,6 +29,9 @@ export const SESSION_STATE_ALLOWLIST = new Set([
     "localHarness",
     "transcriptMarker",
     "companyConfidence",
+    "projectBindReason",
+    "projectCandidates",
+    "projectGate",
     "updatedAt",
 ]);
 const SESSION_STATE_LOCK_TIMEOUT_MS = 5_000;
@@ -228,6 +231,12 @@ export function projectSessionState(state) {
         out.transcriptMarker = state.transcriptMarker;
     if (state.companyConfidence)
         out.companyConfidence = state.companyConfidence;
+    if (state.projectBindReason)
+        out.projectBindReason = state.projectBindReason;
+    if (state.projectCandidates?.length)
+        out.projectCandidates = state.projectCandidates;
+    if (state.projectGate)
+        out.projectGate = state.projectGate;
     return out;
 }
 /**

package/package.json

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