@indigoai-us/hq-cli 5.345.32 → 5.345.34

package/dist/commands/lanes.js

@@ -33,6 +33,7 @@ import { registerLaneReviewCommand } from "./lanes-review.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { withCliFeatureUsed } from "../utils/cli-telemetry.js";
 import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { laneDepthCap } from "../lib/lanes/depth-cap.js";
 import { isSsmRunCommandProcess } from "../lib/lanes/ssm-command-context.js";
 import { runResidentCommandWithPackageLease } from "../utils/resident-package-preload.js";
 import { readLanesFlagLocalOverride, readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "../lib/lanes/registry-flag.js";
@@ -66,7 +67,7 @@ import { AccountResolutionError, compareLaneQueueOrder, LANE_PROVIDERS, LANE_STA
 import { laneStories, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "../lib/lanes/lane-company.js";
-import { doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, keepAliveExclusion, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
+import { doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, keepAliveExclusion, keepAliveSupersededBy, loadRetiredLaneEntries, matchesRetiredLaneEntry, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
 import { questionBodyAbsPath, resolveQuestionCompanyWithFallback, resolveProjectQuestionCompany, } from "../lib/lanes/questions.js";
 import { assertQuestionBodySecretSafe } from "../lib/lanes/questions.js";
 import { writeQuestionBody } from "../lib/lanes/questions.js";
@@ -2070,12 +2071,12 @@ function seniorLaneChain(hqRoot, ref, ctx, visited = new Set(), override) {
     const depth = isOverridden ? override.depth : derivedLaneDepth(hqRoot, lane.senior, ctx, override);
     return [...prefix, { lane_id: lane.lane_id, depth }];
 }
-function maxLaneDepthError(depth, chain, description, extraDetails = {}) {
-    const parentLane = [...chain].reverse().find((entry) => entry.depth < MAX_LANE_DEPTH);
+function maxLaneDepthError(depth, chain, description, cap, extraDetails = {}) {
+    const parentLane = [...chain].reverse().find((entry) => entry.depth < cap.max);
     const nextStep = parentLane
         ? `Ask your senior lane ${parentLane.lane_id} to create this worker instead, or re-parent this lane under a shallower senior.`
         : "Ask a shallower senior to create this lane, or re-parent it to a shallower senior.";
-    return new LanesError("max_lane_depth", `${description}: senior chain length ${depth} exceeds cap ${MAX_LANE_DEPTH}`, { ...extraDetails, depth, max: MAX_LANE_DEPTH, senior_chain: chain, next_step: nextStep });
+    return new LanesError("max_lane_depth", `${description}: senior chain length ${depth} exceeds cap ${cap.max} (${cap.source === "company" ? "company config" : "default config"})`, { ...extraDetails, depth, max: cap.max, source: cap.source, senior_chain: chain, next_step: nextStep });
 }
 function callerDepth(hqRoot, ctx) {
     const laneId = ctx.env.HQ_LANE_ID?.trim();
@@ -3068,21 +3069,22 @@ async function runCreate(ctx, opts) {
         }
         assertKnownOutpost(requested, known);
     }
+    let company = companyFlag
+        ? await ctx.resolveCompany(companyFlag)
+        : null;
+    const depthCap = laneDepthCap(hqRoot, company?.slug);
     const depth = callerDepth(hqRoot, ctx);
-    if (depth >= MAX_LANE_DEPTH) {
+    if (depth >= depthCap.max) {
         const callerLaneId = ctx.env.HQ_LANE_ID?.trim();
         const chain = callerLaneId
             ? seniorLaneChain(hqRoot, { kind: "lane", id: callerLaneId }, ctx)
             : seniorLaneChain(hqRoot, sessionIdFromEnv(ctx.env)
                 ? { kind: "session", id: sessionIdFromEnv(ctx.env) }
                 : { kind: "user" }, ctx);
-        throw maxLaneDepthError(depth + 1, chain, `A depth-${depth} caller may not spawn a depth-${depth + 1} lane`);
+        throw maxLaneDepthError(depth + 1, chain, `A depth-${depth} caller may not spawn a depth-${depth + 1} lane`, depthCap);
     }
     const senior = opts.senior ? parseSeniorRef(opts.senior) : defaultSenior(ctx);
     assertSeniorExists(hqRoot, senior, ctx);
-    let company = companyFlag
-        ? await ctx.resolveCompany(companyFlag)
-        : null;
     const seniorCompany = companyOfSenior(hqRoot, senior, ctx);
     if (company === null && seniorCompany.binding === "company") {
         const seniorCompanyIdentifier = seniorCompany.slug ?? (seniorCompany.uid
@@ -3104,8 +3106,8 @@ async function runCreate(ctx, opts) {
     }
     const hireGrant = requestedHireGrant ?? 0;
     const laneDepth = derivedLaneDepth(hqRoot, senior, ctx);
-    if (laneDepth > MAX_LANE_DEPTH) {
-        throw maxLaneDepthError(laneDepth, seniorLaneChain(hqRoot, senior, ctx), `Creating lane at depth ${laneDepth} is refused`);
+    if (laneDepth > depthCap.max) {
+        throw maxLaneDepthError(laneDepth, seniorLaneChain(hqRoot, senior, ctx), `Creating lane at depth ${laneDepth} is refused`, depthCap);
     }
     // A no-company lane must not call company resolution (openMeshTransport).
     if (storyIds.length > 0 && ctx.storyLedgerEnabled()) {
@@ -6007,6 +6009,71 @@ async function runKeepAlive(ctx, laneId, opts) {
         lane: updated,
     });
 }
+async function runLaneDoctor(ctx, pendingQuestionsForLane) {
+    const hqRoot = ctx.hqRoot();
+    const lanes = loadAllLanes(hqRoot);
+    const retiredEntries = loadRetiredLaneEntries(hqRoot);
+    const findings = [];
+    for (const lane of lanes) {
+        if (lane.keep_alive !== true || isTerminalLaneState(lane.state))
+            continue;
+        const retiredEntry = retiredEntries.find((entry) => matchesRetiredLaneEntry(entry, lane.lane_id));
+        if (retiredEntry !== undefined) {
+            findings.push({
+                kind: "retired_keep_alive_conflict",
+                lane_id: lane.lane_id,
+                state: lane.state,
+                registry_entry: {
+                    path: path.join(hqRoot, "workspace", "lane-briefs", "juniors.json"),
+                    index: retiredEntry.index,
+                    lane: retiredEntry.lane,
+                    retired_at: retiredEntry.retired_at ?? null,
+                },
+            });
+        }
+        const companyForLane = (candidate) => resolveLaneCompany(hqRoot, candidate).company;
+        const company = companyForLane(lane);
+        const lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+            company: company ?? undefined,
+            env: ctx.env,
+        });
+        const successor = keepAliveSupersededBy(lane, lanes, lineageAware, companyForLane);
+        if (successor !== undefined) {
+            findings.push({
+                kind: "superseded_keep_alive_conflict",
+                lane_id: lane.lane_id,
+                state: lane.state,
+                superseded_by: successor.lane_id,
+                suggested_action: `Review successor ${successor.lane_id} and correct stale supersession metadata before retrying. Message delivery still requires an authorized caller and the running-superseded delivery flag.`,
+            });
+        }
+        if (lane.state === "awaiting_input") {
+            const staleCutoff = Date.parse(ctx.now().toISOString()) - 24 * 60 * 60 * 1000;
+            const pendingQuestions = await pendingQuestionsForLane(ctx, lane);
+            for (const question of pendingQuestions) {
+                const askedAt = Date.parse(question.asked_at);
+                if (!Number.isFinite(askedAt) || askedAt > staleCutoff)
+                    continue;
+                const companySlug = lane.company?.slug ?? lane.mesh_company ?? "<company-slug>";
+                findings.push({
+                    kind: "awaiting_input_keep_alive",
+                    lane_id: lane.lane_id,
+                    state: lane.state,
+                    question_id: question.question_id,
+                    asked_at: question.asked_at,
+                    audience: question.audience,
+                    suggested_command: `hq lanes questions answer ${question.question_id} --company ${companySlug} --freeform <answer>`,
+                });
+            }
+        }
+    }
+    printJson({
+        ok: findings.length === 0,
+        action: "doctor",
+        checked_keep_alive_lanes: lanes.filter((lane) => lane.keep_alive === true && !isTerminalLaneState(lane.state)).length,
+        findings,
+    });
+}
 function assertKeepAliveChangeAllowed(ctx, lane, laneId) {
     const callerAuthorization = callerSeniorAuthorization(ctx, lane.senior);
     if (!callerAuthorization.authorized) {
@@ -7184,10 +7251,11 @@ function runReparentLocked(ctx, laneId, opts, finishedChildrenDoNotCount = false
         throw new LanesError("senior_cycle", `Re-parent would create a cycle through ${laneId}`, { lane_id: laneId, senior: nextSenior });
     }
     const newDepth = derivedLaneDepth(hqRoot, nextSenior, ctx);
-    if (newDepth > MAX_LANE_DEPTH) {
+    const depthCap = laneDepthCap(hqRoot, lane.company?.slug);
+    if (newDepth > depthCap.max) {
         const chain = seniorLaneChain(hqRoot, nextSenior, ctx);
         chain.push({ lane_id: lane.lane_id, depth: newDepth });
-        throw maxLaneDepthError(newDepth, chain, `Re-parent would put lane at depth ${newDepth}`);
+        throw maxLaneDepthError(newDepth, chain, `Re-parent would put lane at depth ${newDepth}`, depthCap);
     }
     const pending = pendingQuestionsForLane(hqRoot, laneId);
     const oldDepth = derivedLaneDepth(hqRoot, lane.senior, ctx);
@@ -7204,10 +7272,11 @@ function runReparentLocked(ctx, laneId, opts, finishedChildrenDoNotCount = false
         assertLaneRunsHereForOperatorMutation(ctx, other, "reparent descendant of");
         const oldDescendantDepth = derivedLaneDepth(hqRoot, other.senior, ctx);
         const descendantDepth = derivedLaneDepth(hqRoot, other.senior, ctx, override);
-        if (descendantDepth > MAX_LANE_DEPTH) {
+        const descendantCap = laneDepthCap(hqRoot, other.company?.slug);
+        if (descendantDepth > descendantCap.max) {
             const chain = seniorLaneChain(hqRoot, other.senior, ctx, new Set(), override);
             chain.push({ lane_id: other.lane_id, depth: descendantDepth });
-            throw maxLaneDepthError(descendantDepth, chain, `Re-parent would put descendant ${other.lane_id} at depth ${descendantDepth}`, { lane_id: other.lane_id });
+            throw maxLaneDepthError(descendantDepth, chain, `Re-parent would put descendant ${other.lane_id} at depth ${descendantDepth}`, descendantCap, { lane_id: other.lane_id });
         }
         if (descendantDepth > oldDescendantDepth &&
             pendingQuestionsForLane(hqRoot, other.lane_id).length > 0) {
@@ -8646,6 +8715,7 @@ export function registerLanesCommand(parent, deps = {}) {
         resolveCommandLane: resolveMessageLaneTarget,
         resolveActiveQuestionCompany,
         hasPendingQuestionForLane: questionHandlers.hasPendingQuestionForLane,
+        pendingQuestionsForLane: questionHandlers.pendingQuestionsForLane,
         cancelFallbackQuestionsForLane: questionHandlers.cancelFallbackQuestionsForLane,
         resolveResumeProfile,
         reuseProfileRefreshEnabled,
@@ -8677,6 +8747,7 @@ export function registerLanesCommand(parent, deps = {}) {
         recordResumeSetup,
         resolveCommandLane: (commandCtx, laneId) => resolveCommandLaneTarget(commandCtx, laneId),
         hasPendingQuestionForLane: questionHandlers.hasPendingQuestionForLane,
+        pendingQuestionsForLane: questionHandlers.pendingQuestionsForLane,
         cancelFallbackQuestionsForLane: questionHandlers.cancelFallbackQuestionsForLane,
         resolveResumeProfile,
         reuseProfileRefreshEnabled,
@@ -8862,6 +8933,12 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (opts) => {
         await runBackfillGrants(ctx, opts);
     }));
+    lanes
+        .command("doctor")
+        .description("Report active keep-alive lanes blocked by retired, superseded, or pending-question state")
+        .action(wrap(async () => {
+        await runLaneDoctor(ctx, questionHandlers.pendingQuestionsForLane);
+    }));
     lanes
         .command("list")
         .description("List lanes")

package/dist/commands/mesh.js

@@ -14,8 +14,8 @@ import chalk from "chalk";
 import { ensureCognitoToken, isExpiring, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, addProjectMember, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
-import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, } from "../lib/mesh/project-board.js";
-import { mapSourceStoryStatus } from "../lib/mesh/story-status.js";
+import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, reconcileProjectStories, } from "../lib/mesh/project-board.js";
+import { ACCEPTED_LEDGER_STATES, mapSourceStoryStatus, UnknownProjectStoryStateError } from "../lib/mesh/story-status.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, effectiveUsageAttribution, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, setUsageAttribution, } from "../lib/work-context/config.js";
@@ -257,32 +257,43 @@ function projectStoriesFromJson(value, source) {
     if (!rawStories) {
         fail(`${source} must be a JSON story array or an object with userStories.`);
     }
-    const stories = rawStories.map((raw, index) => {
+    const rejectedStories = [];
+    const stories = rawStories.flatMap((raw, index) => {
         const story = record(raw);
         const id = typeof story?.id === "string" ? story.id.trim() : "";
         const title = typeof story?.title === "string" ? story.title.trim() : "";
         if (!story || !id || !title) {
             fail(`${source} userStories[${index}] requires string id and title.`);
         }
-        const status = mapSourceStoryStatus(story, `${source} userStories[${index}]`);
+        let status;
+        try {
+            status = mapSourceStoryStatus({ ...story, id }, `${source} userStories[${index}]`);
+        }
+        catch (err) {
+            if (!(err instanceof UnknownProjectStoryStateError))
+                throw err;
+            rejectedStories.push(err);
+            return [];
+        }
         const resolvedStatus = status || (story.passes === true ? "done" : undefined);
-        return {
-            id,
-            title,
-            ...(typeof story.description === "string" ? { description: story.description } : {}),
-            ...(Array.isArray(story.acceptanceCriteria)
-                ? {
-                    acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
-                }
-                : {}),
-            ...(resolvedStatus ? { status: resolvedStatus } : {}),
-            // hq-pro makes passes mirror the Board status. A completed PRD story
-            // without an explicit status must therefore become done.
-            passes: resolvedStatus === "done",
-            ...(typeof story.priority === "number" && Number.isFinite(story.priority)
-                ? { priority: story.priority }
-                : {}),
-        };
+        return [{
+                id,
+                title,
+                ...(typeof story.description === "string" ? { description: story.description } : {}),
+                ...(Array.isArray(story.acceptanceCriteria)
+                    ? {
+                        acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
+                    }
+                    : {}),
+                ...(resolvedStatus ? { status: resolvedStatus } : {}),
+                ...(typeof story.state === "string" ? { ledgerState: story.state.trim() } : {}),
+                // hq-pro makes passes mirror the Board status. A completed PRD story
+                // without an explicit status must therefore become done.
+                passes: resolvedStatus === "done",
+                ...(typeof story.priority === "number" && Number.isFinite(story.priority)
+                    ? { priority: story.priority }
+                    : {}),
+            }];
     });
     const metadata = record(plan?.metadata);
     const repos = metadata && Object.hasOwn(metadata, "repos")
@@ -292,12 +303,44 @@ function projectStoriesFromJson(value, source) {
         ...(typeof plan?.name === "string" ? { name: plan.name } : {}),
         ...(typeof plan?.description === "string" ? { description: plan.description } : {}),
         stories,
+        rejectedStories,
         ...(repos ? { repos } : {}),
     };
 }
-function parseProjectPlan(raw, source) {
+function projectStateErrors(rejected) {
+    return rejected.map((error) => ({
+        code: error.code,
+        file: error.source.split(" userStories[")[0],
+        storyId: error.storyId,
+        field: "state",
+        value: error.value,
+        accepted: ACCEPTED_LEDGER_STATES,
+    }));
+}
+class RejectedProjectStoryStatesError extends Error {
+    rejected;
+    code = "PROJECT_STORY_STATE_INVALID";
+    constructor(rejected) {
+        super(rejected.map((error) => `${error.code}: ${error.message}`).join("\n"));
+        this.rejected = rejected;
+        this.name = "RejectedProjectStoryStatesError";
+    }
+}
+function failProjectStoryStates(rejected, json) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, errors: projectStateErrors(rejected) }));
+    else
+        for (const error of rejected)
+            console.error(`${error.code}: ${error.message}`);
+    process.exitCode = 1;
+}
+function parseProjectPlan(raw, source, options = {}) {
     try {
-        return projectStoriesFromJson(JSON.parse(raw), source);
+        const plan = projectStoriesFromJson(JSON.parse(raw), source);
+        if (plan.rejectedStories.length && !options.allowRejectedStories) {
+            throw new RejectedProjectStoryStatesError(plan.rejectedStories);
+        }
+        return plan;
     }
     catch (err) {
         if (err instanceof SyntaxError)
@@ -330,6 +373,10 @@ async function runProjectSet(projectId, opts) {
         : opts.storiesJson
             ? parseProjectPlan(opts.storiesJson, "--stories-json")
             : undefined;
+    if (source?.rejectedStories.length) {
+        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+        return;
+    }
     const explicitRepos = opts.reposJson
         ? parseProjectReposJson(opts.reposJson, "--repos-json")
         : opts.repo?.length
@@ -479,8 +526,12 @@ async function runProjectMemberAdd(projectId, personUid, opts) {
 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 source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
     const { token, company } = await withCompany(opts);
+    if (source.rejectedStories.length && source.stories.length === 0) {
+        failProjectStoryStates(source.rejectedStories, Boolean(opts.json));
+        return;
+    }
     let current;
     try {
         current = await getProjectView(token, company.companyUid, projectId);
@@ -506,12 +557,13 @@ async function runProjectEnsure(projectId, opts) {
         }));
         if (opts.json) {
             console.log(JSON.stringify({
-                ok: true,
+                ok: source.rejectedStories.length === 0,
                 action: "project.ensure.dry-run",
                 projectId,
                 companyUid: company.companyUid,
                 sourceStatuses,
                 stories: boardStatuses,
+                ...(source.rejectedStories.length ? { errors: projectStateErrors(source.rejectedStories) } : {}),
             }, null, 2));
         }
         else {
@@ -523,6 +575,8 @@ async function runProjectEnsure(projectId, opts) {
             for (const story of boardStatuses)
                 console.log(`${story.id}\t${story.status}`);
         }
+        if (source.rejectedStories.length)
+            process.exitCode = 1;
         return;
     }
     // Genesis thread, then the view, then register. Register returns 403
@@ -606,13 +660,74 @@ async function runProjectEnsure(projectId, opts) {
         channelId: registration.channelId,
         version: verified.version,
         stories: verified.stories,
+        ...(source.rejectedStories.length ? { ok: false, errors: projectStateErrors(source.rejectedStories) } : {}),
     };
     noteCallingSessionBound(payload.projectId, company);
     if (opts.json) {
         console.log(JSON.stringify(payload));
+        if (source.rejectedStories.length)
+            process.exitCode = 1;
         return;
     }
     console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
+    if (source.rejectedStories.length)
+        failProjectStoryStates(source.rejectedStories, false);
+}
+async function runProjectReconcile(projectId, opts) {
+    if (!opts.storiesFile?.trim())
+        fail("`--stories-file <prd.json>` is required.");
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile, { allowRejectedStories: true });
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    if (current && (current.companyUid !== company.companyUid || current.projectId !== projectId)) {
+        fail("Work mesh project reconcile: Board company or project id did not match the request.");
+    }
+    const reconciliation = reconcileProjectStories(source.stories, current?.stories ?? []);
+    const errors = [
+        ...projectStateErrors(source.rejectedStories),
+        ...(!current ? [{ code: "PROJECT_BOARD_NOT_FOUND", projectId }] : []),
+    ];
+    const mismatches = reconciliation.mismatches;
+    const clean = mismatches.length === 0 && errors.length === 0;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: clean,
+            action: "project.reconcile",
+            projectId,
+            companyUid: company.companyUid,
+            mismatches,
+            stateDriftCount: reconciliation.stateDriftCount,
+            ledgerStateUnsupported: reconciliation.ledgerStateUnsupported,
+            errors,
+        }, null, 2));
+    }
+    else if (clean) {
+        const note = reconciliation.ledgerStateUnsupported.length
+            ? `; Board does not return ledgerState for ${reconciliation.ledgerStateUnsupported.length} stories yet`
+            : "";
+        console.log(`Work mesh: project ${projectId} matches ${source.stories.length} ledger stories${note}`);
+    }
+    else {
+        for (const mismatch of mismatches) {
+            console.log(`${mismatch.storyId}\tledger=${mismatch.ledgerState ?? "<none>"}\texpected=${mismatch.expectedBoardStatus ?? "<none>"}\tboard=${mismatch.boardStatus ?? "<missing>"}\tboardLedger=${mismatch.boardLedgerState ?? "<unsupported>"}\tstateDrift=${mismatch.stateDrift}\tmissing=${mismatch.missingOnBoard}\textra=${mismatch.extraOnBoard}`);
+        }
+        if (reconciliation.ledgerStateUnsupported.length) {
+            console.log(`Board does not return ledgerState for ${reconciliation.ledgerStateUnsupported.length} stories: ${reconciliation.ledgerStateUnsupported.join(", ")}`);
+        }
+        if (!current)
+            console.error(`PROJECT_BOARD_NOT_FOUND: Board project ${projectId} was not found.`);
+        for (const error of source.rejectedStories)
+            console.error(`${error.code}: ${error.message}`);
+    }
+    if (!clean)
+        process.exitCode = 1;
 }
 async function runPrdSync(opts) {
     const sessionId = opts.session.trim();
@@ -689,6 +804,8 @@ async function runPrdSync(opts) {
             });
         }
         catch (err) {
+            if (err instanceof RejectedProjectStoryStatesError)
+                throw err;
             const reason = err instanceof Error ? err.message : String(err);
             console.error(`work-mesh: prd-sync ensure failed; emitting anyway (${reason.slice(0, 160)})`);
         }
@@ -828,8 +945,8 @@ async function runBindProject(target, opts) {
         }
         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);
+        const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
         await ensureProjectBoard({
             token,
             company: {
@@ -2026,6 +2143,13 @@ export function registerMeshCommand(program, deps = {}) {
         .option("--dry-run", "Read the current Board and print computed story statuses without writing")
         .option("--json", "Print {projectId, threadId, channelId, version, stories}")
         .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
+    project
+        .command("reconcile <projectId>")
+        .description("Read the project Board and report drift from a PRD ledger")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .requiredOption("--stories-file <path>", "PRD JSON file with userStories")
+        .option("--json", "Print machine-readable mismatch records")
+        .action((projectId, opts) => wrap(() => runProjectReconcile(projectId, opts))());
     project
         .command("register <projectId>")
         .description("Register an existing Board and bind its project channel; use project ensure to create or repair a Board")

package/dist/commands/reindex.js

@@ -47,6 +47,9 @@ const WORKTREE_HOOK_SWEEP_BUDGET_MS = 5_000;
  * bounded, which is the point.
  */
 const HOOK_CHECK_TIMEOUT_MS = 60_000;
+// Leave ten seconds inside the desktop's 30-second package-lease wait for
+// process startup and cleanup when reindex runs from a lifecycle hook.
+const HOOK_CHECK_FROM_HOOK_TIMEOUT_MS = 20_000;
 /** Ceiling override, in milliseconds. Present so tests need not wait a minute. */
 function hookCheckTimeoutMs() {
     const raw = process.env.HQ_HOOK_CHECK_TIMEOUT_MS?.trim();
@@ -367,11 +370,11 @@ function hasCommandHook(value) {
  * an older, unscoped checker — report healthy while the drift only this checker
  * detects goes unseen.
  */
-function runShippedHookCheck(hqRoot) {
+function runShippedHookCheck(hqRoot, timeoutLimitMs) {
     const checker = path.join(hqRoot, HOOK_CHECK_RELATIVE_PATH);
     if (!fs.existsSync(checker))
         return undefined;
-    const budgetMs = hookCheckTimeoutMs();
+    const budgetMs = Math.min(hookCheckTimeoutMs(), timeoutLimitMs ?? Number.POSITIVE_INFINITY);
     try {
         const result = spawnSync('bash', [checker, '--root', hqRoot], {
             encoding: 'utf8',
@@ -406,7 +409,7 @@ function runShippedHookCheck(hqRoot) {
  * reindex fires on every Stop / PostToolUse hook, that was the single most
  * expensive discarded result in the command.
  */
-function inspectHookHealth(hqRoot) {
+function inspectHookHealth(hqRoot, timeoutLimitMs) {
     const settingsPath = path.join(hqRoot, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
         return { state: 'extreme', reason: '.claude/settings.json is missing' };
@@ -435,7 +438,7 @@ function inspectHookHealth(hqRoot) {
             reason: `missing command hook wiring for ${HOOK_EVENTS.filter((event) => !commandEvents.includes(event)).join(', ')}`,
         };
     }
-    const checkerResult = runShippedHookCheck(hqRoot);
+    const checkerResult = runShippedHookCheck(hqRoot, timeoutLimitMs);
     if (checkerResult !== undefined && checkerResult.status !== 0) {
         return {
             state: 'minor',
@@ -491,12 +494,12 @@ function runSilently(operation) {
  * configuration is repaired only after a successful reindex; partial and
  * malformed configurations remain untouched and receive recovery guidance.
  */
-function repairExtremeHookDrift(hqRoot, allowRepair = true) {
+function repairExtremeHookDrift(hqRoot, allowRepair = true, timeoutLimitMs) {
     // `hq reindex` can still be invoked from an arbitrary directory. Never turn
     // an absent settings file there into a rescue attempt.
     if (!isHqRoot(hqRoot))
         return;
-    const health = inspectHookHealth(hqRoot);
+    const health = inspectHookHealth(hqRoot, timeoutLimitMs);
     if (health.state === 'healthy')
         return;
     printHookHealthWarning(hqRoot, health.reason);
@@ -510,7 +513,7 @@ function repairExtremeHookDrift(hqRoot, allowRepair = true) {
             paths: ['.claude'],
             assumeYes: true,
         }));
-        const afterRepair = inspectHookHealth(hqRoot);
+        const afterRepair = inspectHookHealth(hqRoot, timeoutLimitMs);
         if (result.status === 0 && afterRepair.state === 'healthy') {
             console.log('reindex: repaired HQ hook config');
             return;
@@ -691,7 +694,7 @@ export function registerReindexCommand(program) {
         const sweepStartedAt = Date.now();
         removeStaleHqWorktrees(hqRoot, sweepStartedAt, opts.fromHook ? sweepStartedAt + WORKTREE_HOOK_SWEEP_BUDGET_MS : Number.POSITIVE_INFINITY);
         const { status } = reindex({ repoRoot: opts.repoRoot });
-        repairExtremeHookDrift(hqRoot, status === 0);
+        repairExtremeHookDrift(hqRoot, status === 0, opts.fromHook ? HOOK_CHECK_FROM_HOOK_TIMEOUT_MS : undefined);
         if (status === 0) {
             // Only safe once reindex actually ran: a refused --from-hook reindex
             // means a sync/rescue holds the shared operation lock and may be