@indigoai-us/hq-cli 5.189.0 → 5.190.0

package/dist/lib/lanes/store.js

@@ -15,6 +15,7 @@ import { resolveLanesHqRoot } from "./hq-root.js";
 import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, isLaneVersionConflict, } from "./errors.js";
 import { HISTORY_CAP, HOST_KINDS, LANE_STORY_STATUSES, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isQueuedReason, isLaneState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseMajorSchema, REQUIRED_LANE_RECORD_FIELDS, LANE_FIELD_WRITERS, LANE_WRITERS, } from "./types.js";
 import { laneStories } from "./stories.js";
+import { laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, } from "./story-ledger.js";
 export const LANES_STORE_REL = path.join("workspace", "lanes");
 export const LANE_RECORDS_DIR = "lanes";
 export const QUESTION_RECORDS_DIR = "questions";
@@ -319,13 +320,18 @@ function legacyLaneStory(raw) {
 }
 function parseLaneStories(raw, filePath) {
     if (raw.stories === undefined) {
+        if (raw.story_id === "" && typeof raw.no_story_reason === "string") {
+            raw.stories = [];
+            return;
+        }
         // v1 records carried one story in the top-level fields. Keep the old
         // fields authoritative for the migration and give worker-completed work
         // the review state until a senior explicitly verifies it.
         raw.stories = [legacyLaneStory(raw)];
         return;
     }
-    if (!Array.isArray(raw.stories) || raw.stories.length === 0) {
+    if (!Array.isArray(raw.stories) ||
+        (raw.stories.length === 0 && !(raw.story_id === "" && typeof raw.no_story_reason === "string"))) {
         throw new LaneSchemaError("stories must be a non-empty array when present", {
             path: filePath,
             field: "stories",
@@ -397,7 +403,28 @@ export function parseLaneRecord(raw, filePath) {
         });
     }
     requireString(raw.project_id, "project_id");
-    requireString(raw.story_id, "story_id");
+    if (typeof raw.story_id !== "string" ||
+        (raw.story_id.trim() === "" && raw.no_story_reason === undefined)) {
+        throw new LaneSchemaError("Expected non-empty string for story_id", {
+            path: filePath,
+            field: "story_id",
+            value: raw.story_id,
+        });
+    }
+    if (raw.no_story_reason !== undefined && (typeof raw.no_story_reason !== "string" || raw.no_story_reason.trim() === "")) {
+        throw new LaneSchemaError("no_story_reason must be a non-empty string", { path: filePath, field: "no_story_reason" });
+    }
+    if (raw.story_id.trim() !== "" && raw.no_story_reason !== undefined) {
+        throw new LaneSchemaError("no_story_reason requires an empty story_id", { path: filePath, field: "no_story_reason" });
+    }
+    if (raw.ledger_sync_error !== undefined && (typeof raw.ledger_sync_error !== "string" || raw.ledger_sync_error.trim() === "")) {
+        throw new LaneSchemaError("ledger_sync_error must be a non-empty string", { path: filePath, field: "ledger_sync_error" });
+    }
+    if (raw.pending_question_ids !== undefined && (!Array.isArray(raw.pending_question_ids) ||
+        raw.pending_question_ids.some((id) => typeof id !== "string" || id.trim() === "") ||
+        new Set(raw.pending_question_ids).size !== raw.pending_question_ids.length)) {
+        throw new LaneSchemaError("pending_question_ids must be an array of unique non-empty ids", { path: filePath, field: "pending_question_ids" });
+    }
     requireTimestamp(raw.created_at, "created_at", filePath);
     requireTimestamp(raw.updated_at, "updated_at", filePath);
     if (raw.queued_reason !== undefined && !isQueuedReason(raw.queued_reason)) {
@@ -435,6 +462,15 @@ export function parseLaneRecord(raw, filePath) {
         throw new LaneSchemaError(`Unknown worker policy delivery mode ${JSON.stringify(raw.worker_policy_delivery)}`, { path: filePath, field: "worker_policy_delivery", value: raw.worker_policy_delivery });
     }
     parseLaneStories(raw, filePath);
+    if (raw.last_envelope !== undefined) {
+        if (!isPlainObject(raw.last_envelope) || typeof raw.last_envelope.ref !== "string" ||
+            typeof raw.last_envelope.at !== "string" ||
+            !["done", "ask", "blocked"].includes(raw.last_envelope.decision) ||
+            (raw.last_envelope.artifacts !== undefined && !Array.isArray(raw.last_envelope.artifacts)) ||
+            (raw.last_envelope.blocked_reason !== undefined && typeof raw.last_envelope.blocked_reason !== "string")) {
+            throw new LaneSchemaError("last_envelope is malformed", { path: filePath, field: "last_envelope" });
+        }
+    }
     parseOptionalCompanyField(raw, filePath);
     parseOptionalMeshCompanyField(raw, filePath);
     if (!isPlainObject(raw.senior)) {
@@ -867,13 +903,14 @@ export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
         attribution_history: init.attribution_history ?? [],
     };
     parseLaneRecord(record, filePath);
-    return withRecordLock(filePath, deps, () => {
+    const created = withRecordLock(filePath, deps, () => {
         if (deps.existsSync(filePath)) {
             throw new LanesError("lane_exists", `Lane ${lane_id} already exists`, { lane_id });
         }
         atomicWriteJson(filePath, record, deps);
         return record;
     });
+    return syncStoryLedgerForLane(hqRoot, created, deps);
 }
 /** Hierarchy lock: separate from record writes so callers can CAS-write while holding it. */
 export function withLaneHireLocks(hqRoot, laneIds, fn, deps = defaultStoreDeps()) {
@@ -899,7 +936,9 @@ export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, dep
     if (!LANE_WRITERS.includes(writer)) {
         throw new LanesError("lane_writer_unknown", `Unknown lane writer ${String(writer)}`, { writer });
     }
-    return casWrite(laneRecordPath(hqRoot, laneId), expectedVersion, parseLaneRecord, mergeLaneRecords, (current) => {
+    let before;
+    const updated = casWrite(laneRecordPath(hqRoot, laneId), expectedVersion, parseLaneRecord, mergeLaneRecords, (current) => {
+        before = current;
         // `current` is the pre-update snapshot and stays untouched: the updater
         // receives a deep clone, so mutating its argument in place cannot reach
         // the record the ownership check compares against.
@@ -916,6 +955,66 @@ export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, dep
         }
         return updated;
     }, deps);
+    if (laneStoryLedgerEnabled() && before && laneLedgerRelevantChange(before, updated)) {
+        return syncStoryLedgerForLane(hqRoot, updated, deps);
+    }
+    return updated;
+}
+function laneLedgerRelevantChange(before, after) {
+    return before.state !== after.state || before.project_id !== after.project_id ||
+        before.story_id !== after.story_id || before.no_story_reason !== after.no_story_reason ||
+        JSON.stringify(before.pending_question_ids) !== JSON.stringify(after.pending_question_ids) ||
+        JSON.stringify(before.stories) !== JSON.stringify(after.stories) ||
+        JSON.stringify(before.last_envelope) !== JSON.stringify(after.last_envelope);
+}
+function syncStoryLedgerForLane(hqRoot, lane, deps) {
+    if (!laneStoryLedgerEnabled())
+        return lane;
+    try {
+        const questionRefs = [];
+        for (const questionId of lane.pending_question_ids ?? []) {
+            const question = readQuestion(hqRoot, questionId, deps);
+            const sameCompany = question.company === null
+                ? lane.company === null
+                : lane.company !== null &&
+                    question.company.uid === lane.company.uid &&
+                    question.company.slug === lane.company.slug;
+            if (question.lane_id !== lane.lane_id || !sameCompany) {
+                throw new LanesError("story_ledger_question_mismatch", `Pending question ${questionId} does not belong to lane ${lane.lane_id}`, {
+                    lane_id: lane.lane_id,
+                    question_id: questionId,
+                    question_lane_id: question.lane_id,
+                    company: question.company?.slug ?? null,
+                });
+            }
+            if (question.status === "pending") {
+                questionRefs.push({
+                    question_id: question.question_id,
+                    project_id: question.project_id,
+                    story_id: question.story_id,
+                });
+            }
+        }
+        syncLaneToProjectStoryLedger(hqRoot, lane, questionRefs);
+        if (lane.ledger_sync_error !== undefined) {
+            retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => current.ledger_sync_error === undefined
+                ? current
+                : { ...current, ledger_sync_error: undefined }, deps);
+        }
+        return readLane(hqRoot, lane.lane_id, deps);
+    }
+    catch (error) {
+        const message = (error instanceof Error ? error.message : String(error)).slice(0, 1000) || "Story ledger synchronization failed";
+        try {
+            retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => current.ledger_sync_error === message
+                ? current
+                : { ...current, ledger_sync_error: message }, deps);
+            return readLane(hqRoot, lane.lane_id, deps);
+        }
+        catch (recordError) {
+            throw new LanesError("story_ledger_sync_error_unrecorded", "Story ledger synchronization failed and the failure could not be recorded on lane " + lane.lane_id, { lane_id: lane.lane_id, cause: recordError instanceof Error ? recordError.message : String(recordError) });
+        }
+    }
 }
 /**
  * Replace the primary copy with a terminal snapshot returned by the Outpost
@@ -948,7 +1047,7 @@ export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane,
         });
     }
     const filePath = laneRecordPath(hqRoot, laneId);
-    return withRecordLock(filePath, deps, () => {
+    const synced = withRecordLock(filePath, deps, () => {
         const current = readMergedRecord(filePath, parseLaneRecord, mergeLaneRecords, deps);
         if (current === null) {
             throw new LaneSchemaError(`Record disappeared under lock: ${filePath}`, {
@@ -982,6 +1081,7 @@ export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane,
         atomicWriteJson(filePath, synced, deps);
         return synced;
     });
+    return syncStoryLedgerForLane(hqRoot, synced, deps);
 }
 /** Compare-and-set with conflict retry. Callers that race a concurrent writer re-read. */
 export function retryUpdateLane(hqRoot, laneId, writer, updater, deps = defaultStoreDeps(), attempts = 5) {
@@ -1056,7 +1156,7 @@ export function createQuestion(hqRoot, init, deps = defaultStoreDeps()) {
         routing_history: init.routing_history ?? [],
     };
     parseQuestionRecord(record, filePath);
-    return withRecordLock(filePath, deps, () => {
+    const created = withRecordLock(filePath, deps, () => {
         if (deps.existsSync(filePath)) {
             throw new LanesError("question_exists", `Question ${question_id} already exists`, { question_id });
         }
@@ -1064,12 +1164,35 @@ export function createQuestion(hqRoot, init, deps = defaultStoreDeps()) {
         syncPendingMarker(hqRoot, record, deps);
         return record;
     });
+    syncLaneQuestionReference(hqRoot, created, deps);
+    return created;
 }
 export function updateQuestion(hqRoot, questionId, expectedVersion, updater, deps = defaultStoreDeps()) {
     const next = casWrite(questionRecordPath(hqRoot, questionId), expectedVersion, parseQuestionRecord, mergeQuestionRecords, updater, deps);
     syncPendingMarker(hqRoot, next, deps);
+    syncLaneQuestionReference(hqRoot, next, deps);
     return next;
 }
+function syncLaneQuestionReference(hqRoot, question, deps) {
+    if (!laneStoryLedgerEnabled())
+        return;
+    const lane = tryReadLane(hqRoot, question.lane_id, deps);
+    if (!lane || question.company?.slug !== lane.company?.slug || question.company?.uid !== lane.company?.uid)
+        return;
+    retryUpdateLane(hqRoot, lane.lane_id, "story-ledger", (current) => {
+        if (question.company?.slug !== current.company?.slug || question.company?.uid !== current.company?.uid)
+            return current;
+        const ids = new Set(current.pending_question_ids ?? []);
+        const hadQuestion = ids.has(question.question_id);
+        if (question.status === "pending")
+            ids.add(question.question_id);
+        else
+            ids.delete(question.question_id);
+        if (hadQuestion === (question.status === "pending"))
+            return current;
+        return { ...current, pending_question_ids: [...ids].sort() };
+    }, deps);
+}
 export function appendQuestionRouting(hqRoot, questionId, expectedVersion, entry, deps = defaultStoreDeps()) {
     return updateQuestion(hqRoot, questionId, expectedVersion, (current) => ({
         ...current,

package/dist/lib/lanes/stories.js

@@ -26,6 +26,9 @@ function legacyStatus(lane) {
  * lane write, so reading an old record never changes it on disk by itself.
  */
 export function laneStories(lane) {
+    if (lane.no_story_reason && (!Array.isArray(lane.stories) || lane.stories.length === 0)) {
+        return [];
+    }
     if (Array.isArray(lane.stories) && lane.stories.length > 0) {
         return lane.stories;
     }

package/dist/lib/lanes/story-ledger.d.ts

@@ -0,0 +1,78 @@
+import { type LaneRecord, type LaneState } from "./types.js";
+export declare const LANE_STORY_LEDGER_FLAG = "lanes.story-ledger";
+declare const STORY_STATES: readonly ["todo", "in_progress", "blocked", "in_review", "verification", "done", "dropped"];
+export interface ProjectStoryLedger {
+    projectId: string;
+    companySlug?: string;
+    path: string;
+}
+export interface StoryLedgerWriteDeps {
+    /** Test seam for an unlocked manager edit immediately before the conflict check. */
+    beforeRename?: (filePath: string, attempt: number) => void;
+    /** Test seam for a fresh lock replacing the path after a stale lock was inspected. */
+    beforeStaleLockRename?: (lockPath: string) => void;
+    /** Deterministic clock seam for stale-lock and timeout tests. */
+    clock?: {
+        now: () => number;
+        sleep: (ms: number) => void;
+    };
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}
+export interface StoryLedgerQuestionRef {
+    question_id: string;
+    project_id: string;
+    story_id: string;
+}
+export interface LaneStatusSnapshot {
+    schema_version: "hq-lanes-status.v1";
+    project_id: string;
+    ledger_path: string;
+    generated_at: string;
+    workers: Array<{
+        lane_id: string;
+        company: string | null;
+        provider: string;
+        account: string | null;
+        model: string | null;
+        effort: string | null;
+        stories: string[];
+        no_story_reason: string | null;
+        state: LaneState;
+        queued_reason: string | null;
+    }>;
+    prs: Array<{
+        story_id: string;
+        reference: string;
+    }>;
+    blockers: Array<{
+        story_id: string;
+        lane_id?: string;
+        reason: string;
+    }>;
+    pending_questions: Array<{
+        story_id: string;
+        lane_id: string;
+        question_ids: string[];
+    }>;
+    story_counts: {
+        total: number;
+        by_state: Record<(typeof STORY_STATES)[number], number>;
+    };
+}
+export declare function laneStoryLedgerEnabled(): boolean;
+export declare function resolveProjectStoryLedger(hqRoot: string, projectId: string, companySlug?: string): ProjectStoryLedger;
+export declare function validateProjectStories(hqRoot: string, projectId: string, storyIds: readonly string[], companySlug?: string): ProjectStoryLedger;
+export declare function syncLaneToProjectStoryLedger(hqRoot: string, lane: LaneRecord, questionRefs?: readonly StoryLedgerQuestionRef[], deps?: StoryLedgerWriteDeps): void;
+export declare function buildLaneStatusSnapshot(input: {
+    hqRoot: string;
+    projectId: string;
+    companySlug?: string;
+    companyUid?: string;
+    lanes: readonly LaneRecord[];
+    generatedAt: string;
+    pendingQuestions?: ReadonlyMap<string, readonly StoryLedgerQuestionRef[]>;
+}): LaneStatusSnapshot;
+export declare function formatLaneStatusHuman(snapshot: LaneStatusSnapshot): string;
+export {};
+//# sourceMappingURL=story-ledger.d.ts.map