@indigoai-us/hq-cli 5.168.0 → 5.169.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.169.0] — 2026-09-24
+
+### Fixed
+
+- `hq lanes create` and `hq lanes story <add|start|block|done>` keep story work
+  local when an existing Work Mesh Board rejects a missing story. The
+  `story_warning` identifies the project and story and suggests:
+  `hq mesh project ensure <projectId> --company <slug> --stories-file prd.json`.
+
 ## [5.168.0] — 2026-09-24
 
 ### Fixed

package/dist/commands/lanes.js

@@ -1340,13 +1340,23 @@ async function emitLaneTerminalStateSoft(ctx, lane) {
     }
 }
 async function emitLaneStartedForStories(ctx, company, lane, threadId) {
-    const ready = ctx.mesh.ensureLaneThread
-        ? await ensureLaneThreadRecord(ctx, lane, lane.project_id, lane.story_id, "running")
-        : lane;
+    let ready = lane;
+    if (ctx.mesh.ensureLaneThread) {
+        try {
+            ready = await ensureLaneThreadRecord(ctx, lane, lane.project_id, lane.story_id, "running");
+        }
+        catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning !== undefined)
+                return [warning];
+            throw err;
+        }
+    }
     const stableThreadId = ready.thread_id ?? threadId;
     if (!stableThreadId)
-        return;
+        return [];
     const failures = [];
+    const warnings = [];
     for (const story of laneStories(ready)) {
         try {
             await emitLaneMeshEvent(ctx, company, stableThreadId, "lane_started", {
@@ -1355,14 +1365,59 @@ async function emitLaneStartedForStories(ctx, company, lane, threadId) {
                 project_id: story.project_id,
                 story_id: story.story_id,
             });
-            await ctx.mesh.patchStoryStatus(company, story.project_id, story.story_id, "in_progress");
         }
         catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning !== undefined) {
+                warnings.push(warning);
+                continue;
+            }
             failures.push(err);
+            continue;
+        }
+        try {
+            await ctx.mesh.patchStoryStatus(company, story.project_id, story.story_id, "in_progress");
+        }
+        catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning !== undefined)
+                warnings.push(warning);
+            else
+                failures.push(err);
         }
     }
     if (failures.length > 0)
         throw failures[0];
+    return warnings;
+}
+async function assertStoriesOnBoard(ctx, company, projectId, storyIds) {
+    const check = ctx.mesh.assertProjectStoriesOnBoard;
+    if (!check) {
+        throw new LanesError("story_board_check_unavailable", "Cannot confirm stories are on the Work Mesh Board; refusing to write lane state", { project_id: projectId, story_id: storyIds[0] ?? null });
+    }
+    await check.call(ctx.mesh, company, projectId, storyIds);
+}
+function storyNotOnBoardWarning(err) {
+    return isLanesError(err) && err.error === "story_not_on_board"
+        ? err.message
+        : undefined;
+}
+function combinedStoryWarning(lane, additional = []) {
+    const warnings = [storyWarning(lane), ...additional]
+        .filter((warning) => warning !== undefined && warning.trim().length > 0);
+    return [...new Set(warnings)].join(" ") || null;
+}
+async function storyBoardWarning(ctx, company, projectId, storyIds) {
+    try {
+        await assertStoriesOnBoard(ctx, company, projectId, storyIds);
+        return undefined;
+    }
+    catch (err) {
+        const warning = storyNotOnBoardWarning(err);
+        if (warning !== undefined)
+            return warning;
+        throw err;
+    }
 }
 export const PICKUP_TERMINAL_REASONS = [
     "account_not_logged_in",
@@ -1631,6 +1686,12 @@ async function runCreate(ctx, opts) {
     }
     const seniorCompany = companyOfSenior(hqRoot, senior, ctx);
     assertSameTenant(company, senior, seniorCompany);
+    const createStoryWarnings = [];
+    if (meshCompany) {
+        const warning = await storyBoardWarning(ctx, meshCompany, project, storyIds);
+        if (warning !== undefined)
+            createStoryWarnings.push(warning);
+    }
     let resolvedWorker;
     if (opts.worker) {
         resolvedWorker = resolveLaneWorker(hqRoot, opts.worker, company?.slug);
@@ -2079,19 +2140,25 @@ async function runCreate(ctx, opts) {
         try {
             lane = await ensureLaneThreadRecord(ctx, lane);
         }
-        catch {
-            try {
-                lane = casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
-                    ...current,
-                    state: "failed",
-                    queued_reason: undefined,
-                    terminal_reason: "mesh_thread_registration_failed",
-                }));
+        catch (err) {
+            const warning = storyNotOnBoardWarning(err);
+            if (warning !== undefined) {
+                createStoryWarnings.push(warning);
             }
-            catch {
-                throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed for ${lane.lane_id}, and its local record could not be marked terminal.`, { lane_id: lane.lane_id });
+            else {
+                try {
+                    lane = casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
+                        ...current,
+                        state: "failed",
+                        queued_reason: undefined,
+                        terminal_reason: "mesh_thread_registration_failed",
+                    }));
+                }
+                catch {
+                    throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed for ${lane.lane_id}, and its local record could not be marked terminal.`, { lane_id: lane.lane_id });
+                }
+                throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed; lane ${lane.lane_id} was marked failed.`, { lane_id: lane.lane_id, state: lane.state });
             }
-            throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed; lane ${lane.lane_id} was marked failed.`, { lane_id: lane.lane_id, state: lane.state });
         }
     }
     // Thread registration runs after persistence; anchor the reservation after
@@ -2137,8 +2204,9 @@ async function runCreate(ctx, opts) {
             runCompaction: ctx.runCompaction,
             locateTranscript: ctx.locateTranscript,
         });
-        if (meshCompany)
-            await emitLaneStartedForStories(ctx, meshCompany, started, started.thread_id);
+        if (meshCompany) {
+            createStoryWarnings.push(...await emitLaneStartedForStories(ctx, meshCompany, started, started.thread_id));
+        }
     }
     else if (outpostId) {
         started = await dispatchCreatedOutpostLane(ctx, {
@@ -2174,7 +2242,7 @@ async function runCreate(ctx, opts) {
         project_id: started.project_id,
         story_id: started.story_id,
         stories: laneStories(started),
-        story_warning: storyWarning(started) ?? null,
+        story_warning: combinedStoryWarning(started, createStoryWarnings),
         thread_id: started.thread_id ?? null,
         senior: started.senior,
         depth: started.depth,
@@ -4138,6 +4206,17 @@ async function ensureStoryThread(ctx, lane, projectId, storyId = lane.story_id)
         return lane;
     return ensureLaneThreadRecord(ctx, lane, projectId, storyId);
 }
+async function ensureStoryThreadForTransition(ctx, lane, projectId, storyId) {
+    try {
+        return { lane: await ensureStoryThread(ctx, lane, projectId, storyId) };
+    }
+    catch (err) {
+        const warning = storyNotOnBoardWarning(err);
+        if (warning === undefined)
+            throw err;
+        return { lane, warning };
+    }
+}
 async function ensureLaneThreadRecord(ctx, lane, projectId = lane.project_id, storyId = lane.story_id, laneStatus = lane.state) {
     const company = lane.mesh_company ?? lane.company;
     if (!company)
@@ -4185,8 +4264,12 @@ function sameCommittedStory(current, expected, projectId, storyId) {
 async function commitStoryTransition(ctx, before, next, projectId, storyId, event, status, payload = {}) {
     try {
         await emitStoryTransition(ctx, next, projectId, storyId, event, status, payload);
+        return undefined;
     }
     catch (err) {
+        const warning = storyNotOnBoardWarning(err);
+        if (warning !== undefined)
+            return warning;
         try {
             const current = readLane(ctx.hqRoot(), next.lane_id);
             if (!sameCommittedStory(current, next, projectId, storyId)) {
@@ -4231,14 +4314,26 @@ async function runStoryAdd(ctx, laneId, storyId, opts) {
     const normalizedStoryId = storyId.trim();
     if (!normalizedStoryId)
         throw new LanesError("missing_story", "<story-id> is required", {});
+    const company = lane.mesh_company ?? lane.company;
+    const warnings = [];
+    if (company) {
+        const warning = await storyBoardWarning(ctx, company, projectId, [normalizedStoryId]);
+        if (warning !== undefined)
+            warnings.push(warning);
+    }
     const at = ctx.now().toISOString();
-    lane = await ensureStoryThread(ctx, lane, projectId);
+    const thread = await ensureStoryThreadForTransition(ctx, lane, projectId, normalizedStoryId);
+    lane = thread.lane;
+    if (thread.warning !== undefined)
+        warnings.push(thread.warning);
     const before = lane;
     const next = casUpdateLane(hqRoot, laneId, (current) => {
         assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
         return addCarriedStory(current, projectId, normalizedStoryId, at);
     });
-    await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress");
+    const transitionWarning = await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress");
+    if (transitionWarning !== undefined)
+        warnings.push(transitionWarning);
     const finalLane = readLane(hqRoot, laneId);
     printJson({
         ok: true,
@@ -4247,7 +4342,7 @@ async function runStoryAdd(ctx, laneId, storyId, opts) {
         project_id: projectId,
         story_id: normalizedStoryId,
         status: "in_progress",
-        story_warning: storyWarning(finalLane) ?? null,
+        story_warning: combinedStoryWarning(finalLane, warnings),
         lane: finalLane,
     });
 }
@@ -4264,15 +4359,21 @@ async function runStoryStart(ctx, laneId, storyId, opts) {
         });
     }
     const at = ctx.now().toISOString();
-    lane = await ensureStoryThread(ctx, lane, target.projectId);
+    const warnings = [];
+    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+    lane = thread.lane;
+    if (thread.warning !== undefined)
+        warnings.push(thread.warning);
     const before = lane;
     const next = casUpdateLane(hqRoot, laneId, (current) => {
         assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
         return updateCarriedStory(current, target.projectId, target.storyId, "in_progress", at);
     });
-    await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_started", "in_progress");
+    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_started", "in_progress");
+    if (transitionWarning !== undefined)
+        warnings.push(transitionWarning);
     const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.start", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "in_progress", story_warning: storyWarning(finalLane) ?? null, lane: finalLane });
+    printJson({ ok: true, action: "story.start", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "in_progress", story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
 }
 async function runStoryBlock(ctx, laneId, storyId, opts) {
     const hqRoot = ctx.hqRoot();
@@ -4290,15 +4391,21 @@ async function runStoryBlock(ctx, laneId, storyId, opts) {
     if (!reason)
         throw new LanesError("missing_block_reason", "--reason is required", {});
     const at = ctx.now().toISOString();
-    lane = await ensureStoryThread(ctx, lane, target.projectId);
+    const warnings = [];
+    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+    lane = thread.lane;
+    if (thread.warning !== undefined)
+        warnings.push(thread.warning);
     const before = lane;
     const next = casUpdateLane(hqRoot, laneId, (current) => {
         assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
         return updateCarriedStory(current, target.projectId, target.storyId, "blocked", at, { blocked_reason: reason });
     });
-    await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_blocked", "blocked", { blocked_reason: reason });
+    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_blocked", "blocked", { blocked_reason: reason });
+    if (transitionWarning !== undefined)
+        warnings.push(transitionWarning);
     const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.block", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "blocked", blocked_reason: reason, story_warning: storyWarning(finalLane) ?? null, lane: finalLane });
+    printJson({ ok: true, action: "story.block", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "blocked", blocked_reason: reason, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
 }
 async function runStoryDone(ctx, laneId, storyId, opts) {
     const hqRoot = ctx.hqRoot();
@@ -4323,7 +4430,11 @@ async function runStoryDone(ctx, laneId, storyId, opts) {
         });
     }
     const at = ctx.now().toISOString();
-    lane = await ensureStoryThread(ctx, lane, target.projectId);
+    const warnings = [];
+    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
+    lane = thread.lane;
+    if (thread.warning !== undefined)
+        warnings.push(thread.warning);
     const before = lane;
     const next = casUpdateLane(hqRoot, laneId, (current) => {
         assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
@@ -4332,9 +4443,11 @@ async function runStoryDone(ctx, laneId, storyId, opts) {
             verified_by: current.senior,
         });
     });
-    await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_done", "done", { summary: "Senior verification complete" });
+    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_done", "done", { summary: "Senior verification complete" });
+    if (transitionWarning !== undefined)
+        warnings.push(transitionWarning);
     const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.done", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "done", verified: true, story_warning: storyWarning(finalLane) ?? null, lane: finalLane });
+    printJson({ ok: true, action: "story.done", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "done", verified: true, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
 }
 /**
  * Registration state of the drain hook in the lane's account home, read the

package/dist/lib/lanes/mesh-events.d.ts

@@ -42,6 +42,7 @@
  * of opening a browser nobody is watching, and the watcher records
  * `mesh_event_failed` and moves on. No credential file is read here.
  */
+import { LanesError } from "./errors.js";
 import type { LaneCompanyRef, LaneEnvelope, LaneRecord, TerminalLaneState } from "./types.js";
 export declare const LANE_MESH_EVENTS: readonly ["lane_started", "lane_progress", "lane_question", "lane_question_at_user", "lane_ask", "lane_blocked", "lane_done", "lane_failed", "lane_interrupted", "lane_cancelled", "lane_killed"];
 export type LaneMeshEvent = (typeof LANE_MESH_EVENTS)[number];
@@ -73,6 +74,8 @@ export interface LaneMesh {
     ensureLaneThread?: (company: LaneCompanyRef, lane: LaneRecord, laneStatus?: string, signal?: AbortSignal) => Promise<string>;
     appendThreadEvent: (company: LaneCompanyRef, threadId: string, event: LaneMeshEvent, payload: Record<string, unknown>, signal?: AbortSignal) => Promise<void>;
     patchStoryStatus: (company: LaneCompanyRef, projectId: string, storyId: string, status: string) => Promise<void>;
+    /** Read-only Board membership check before a command writes lane state. */
+    assertProjectStoriesOnBoard?: (company: LaneCompanyRef, projectId: string, storyIds: readonly string[]) => Promise<void>;
 }
 export interface CreateLaneMeshOptions {
     /** False for detached callers (the watcher). See the token note above. */
@@ -88,6 +91,7 @@ export interface CreateLaneMeshOptions {
         status: string;
     }) => Promise<void>;
 }
+export declare function storyNotOnBoardError(company: LaneCompanyRef, projectId: string, storyId: string): LanesError;
 export declare function createLaneMesh(opts?: CreateLaneMeshOptions): LaneMesh;
 /** Resolve the explicit mesh attribution before falling back to the lane tenant. */
 export declare function laneMeshCompany(lane: Pick<LaneRecord, "company" | "mesh_company">): LaneCompanyRef | undefined;

package/dist/lib/lanes/mesh-events.js

@@ -220,6 +220,31 @@ function isProjectViewNotFound(error) {
     return (candidate.code === "PROJECT_VIEW_NOT_FOUND" ||
         (typeof candidate.message === "string" && candidate.message.includes("PROJECT_VIEW_NOT_FOUND")));
 }
+function isUnknownProjectStory(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    return (candidate.status === 400 &&
+        candidate.code === "PROJECT_VIEW_INVALID" &&
+        typeof candidate.message === "string" &&
+        candidate.message.includes("Unknown story"));
+}
+function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+export function storyNotOnBoardError(company, projectId, storyId) {
+    const command = "hq mesh project ensure " + shellQuote(projectId) +
+        " --company " + shellQuote(company.slug) +
+        " --stories-file '<prd.json>'";
+    const message = "Story " + JSON.stringify(storyId) + " is not on the Work Mesh Board for project " +
+        JSON.stringify(projectId) + ". Add it to the project PRD, then run: " + command;
+    return new LanesError("story_not_on_board", message, {
+        message,
+        project_id: projectId,
+        story_id: storyId,
+        command,
+    });
+}
 function isAlreadyRegistered(error) {
     if (!error || typeof error !== "object")
         return false;
@@ -293,18 +318,61 @@ export function createLaneMesh(opts = {}) {
                 senior: { kind: lane.senior.kind, id: lane.senior.id },
                 laneVersion: lane.version,
             };
-            const ensured = await ensureLaneMeshThread(tok, resolved, lane.project_id, descriptor, isMeshLaneStatus(laneStatus) ? laneStatus : "running", signal);
-            return ensured.threadId;
+            try {
+                const ensured = await ensureLaneMeshThread(tok, resolved, lane.project_id, descriptor, isMeshLaneStatus(laneStatus) ? laneStatus : "running", signal);
+                return ensured.threadId;
+            }
+            catch (error) {
+                if (lane.story_id && isUnknownProjectStory(error)) {
+                    throw storyNotOnBoardError(company, lane.project_id, lane.story_id);
+                }
+                throw error;
+            }
         },
         async appendThreadEvent(company, threadId, event, payload, signal) {
             const wire = toWireThreadEvent(event, payload);
             const tok = await token();
             await appendThreadEvent(tok, company.uid, threadId, wire.eventKind, wire.payload, signal);
         },
+        async assertProjectStoriesOnBoard(company, projectId, storyIds) {
+            if (storyIds.length === 0)
+                return;
+            const tok = await token();
+            let view;
+            try {
+                view = await getProjectView(tok, company.uid, projectId);
+            }
+            catch (error) {
+                // A missing Board has a separate, established repair path in
+                // patchStoryStatus. Keep it available; an existing Board is strict.
+                if (isProjectViewNotFound(error))
+                    return;
+                throw error;
+            }
+            if (view.companyUid !== company.uid || view.projectId !== projectId) {
+                throw new LanesError("project_board_scope_mismatch", "Work Mesh returned a Board for a different company or project", { project_id: projectId });
+            }
+            for (const storyId of storyIds) {
+                if (!view.stories.some((story) => story.id === storyId)) {
+                    throw storyNotOnBoardError(company, projectId, storyId);
+                }
+            }
+        },
         async patchStoryStatus(company, projectId, storyId, status) {
             const tok = await token();
+            const patch = async () => {
+                try {
+                    await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+                }
+                catch (error) {
+                    if (isUnknownProjectStory(error)) {
+                        throw storyNotOnBoardError(company, projectId, storyId);
+                    }
+                    throw error;
+                }
+            };
             try {
-                await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+                await patch();
             }
             catch (error) {
                 if (!isProjectViewNotFound(error))
@@ -316,7 +384,7 @@ export function createLaneMesh(opts = {}) {
                     storyId,
                     status,
                 });
-                await patchStoryStatus(tok, company.uid, projectId, storyId, status);
+                await patch();
             }
         },
     };

package/package.json

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