@indigoai-us/hq-cli 5.188.1 → 5.190.0

package/dist/lib/bot/promotion-upload.js

@@ -7,6 +7,22 @@ function assertState(state, bundle, companyUid, operationId) {
         state.phase !== "preparing")
         throw new Error("Promotion preparation returned a different identity or phase");
 }
+function hasValidEncryptionHeaders(headers) {
+    const valuesFor = (name) => Object.entries(headers)
+        .filter(([key]) => key.toLowerCase() === name)
+        .map(([, value]) => value);
+    const encryptionValues = valuesFor("x-amz-server-side-encryption");
+    const keyIdValues = valuesFor("x-amz-server-side-encryption-aws-kms-key-id");
+    // Multiple differently-cased copies are ambiguous, even when their values
+    // happen to match. Accept one exact SSE-KMS pair or no effective SSE values.
+    if (encryptionValues.length > 1 || keyIdValues.length > 1)
+        return false;
+    const encryption = encryptionValues[0] ?? "";
+    const keyId = keyIdValues[0] ?? "";
+    if (!encryption.trim() && !keyId.trim())
+        return true;
+    return encryption === "aws:kms" && Boolean(keyId.trim());
+}
 /** Only the presigned object request receives these bytes. Owner authorization
  * is handled by BotApi and is never forwarded to S3 or a redirect destination.
  */
@@ -15,8 +31,7 @@ async function uploadObject(upload, bytes, fetchImpl) {
     if (url.protocol !== "https:" || url.username || url.password || url.port ||
         !/^[a-z0-9.-]+\.s3(?:[.-][a-z0-9-]+)?\.amazonaws\.com$/.test(url.hostname) ||
         upload.method !== "PUT" || upload.bytes !== bytes.length || upload.sha256 !== sha(bytes) ||
-        upload.headers["x-amz-server-side-encryption"] !== "aws:kms" ||
-        !upload.headers["x-amz-server-side-encryption-aws-kms-key-id"] ||
+        !hasValidEncryptionHeaders(upload.headers) ||
         upload.headers["if-none-match"] !== "*" ||
         upload.headers["x-amz-checksum-sha256"] !== Buffer.from(upload.sha256, "hex").toString("base64") ||
         Object.keys(upload.headers).some(key => /^(authorization|cookie)$/i.test(key))) {

package/dist/lib/lanes/index.d.ts

@@ -16,6 +16,8 @@ export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFT
 export type { ConfigLoadDeps, ConfigWriteDeps } from "./config.js";
 export { resolveLanesHqRoot } from "./hq-root.js";
 export type { LanesHqRootOpts } from "./hq-root.js";
+export { LANE_STORY_LEDGER_FLAG, buildLaneStatusSnapshot, formatLaneStatusHuman, laneStoryLedgerEnabled, resolveProjectStoryLedger, syncLaneToProjectStoryLedger, validateProjectStories, } from "./story-ledger.js";
+export type { LaneStatusSnapshot, ProjectStoryLedger, StoryLedgerWriteDeps } from "./story-ledger.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
 export type { OutpostDispatchResult, OutpostPickupPayload, } from "./outpost-dispatch.js";
 export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";

package/dist/lib/lanes/index.js

@@ -10,6 +10,7 @@ export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HIS
 export { ACTIVE_LANE_STORY_STATUSES, activeLaneStories, laneStories, laneStory, storyKey, storyStatusForEnvelope, storyWarning, withCurrentStory, withLaneStories, } from "./stories.js";
 export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFTER_MS, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, providerCompactAfterMs, providerAutoCompactTokens, providerQuotaDefaultHoldMs, DEFAULT_QUOTA_HOLD_MS, writeLanesConfig, } from "./config.js";
 export { resolveLanesHqRoot } from "./hq-root.js";
+export { LANE_STORY_LEDGER_FLAG, buildLaneStatusSnapshot, formatLaneStatusHuman, laneStoryLedgerEnabled, resolveProjectStoryLedger, syncLaneToProjectStoryLedger, validateProjectStories, } from "./story-ledger.js";
 export { buildOutpostPickupCommand, parseOutpostPickupPayload, } from "./outpost-dispatch.js";
 export { LANES_STORE_REL, LANE_RECORDS_DIR, PENDING_INDEX_DIR, QUESTION_RECORDS_DIR, appendCappedHistory, appendLaneAttribution, appendLaneSeniorHistory, appendQuestionRouting, createLane, createQuestion, isConflictSidecarName, laneRecordPath, lanesStoreRoot, listLaneIds, listQuestionIds, mergeLaneRecords, mergeQuestionRecords, mintLaneId, mintQuestionId, parseLaneRecord, parseQuestionRecord, pendingMarkerPath, questionRecordPath, readLane, readQuestion, resolveStoreHqRoot, sanitizeHostComponent, tryReadLane, tryReadQuestion, retryUpdateLane, retryUpdateQuestion, syncLaneRecordFromOwner, updateLane, updateQuestion, withLaneHireLocks, } from "./store.js";
 export { DEFAULT_LANE_WATCH_INTERVAL_MS, MAX_LANE_WATCH_INTERVAL_MS, MAX_WATCHED_LANES, MAX_WATCH_OUTPUT_LINES, runLaneWatch, } from "./watch.js";

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -35,6 +35,8 @@ export interface OutpostLaneCommand {
     story?: string;
     account?: string;
     model?: string;
+    effort?: string;
+    worker?: string;
     hire?: string;
     grantContext?: string;
     compact?: boolean;
@@ -81,6 +83,8 @@ export declare function buildOutpostBalanceMoveCommand(input: {
 export declare function buildOutpostIdentityBackfillCommand(expectedId: string): string;
 /** Build the same `hq outposts exec` remote command used by lane pickup. */
 export declare function buildOutpostLaneCommand(input: OutpostLaneCommand): string;
+/** True when a remote CLI exited after rejecting the forwarded effort flag. */
+export declare function outpostRejectedEffortOption(result: Pick<OutpostDispatchResult, "exitCode" | "stdout" | "stderr">): boolean;
 export declare function stageOutpostPayload(port: Pick<OutpostExecPort, "stageExecInput">, outpostId: string, bytes: Uint8Array, put?: typeof fetch): Promise<{
     getUrl: string;
 }>;

package/dist/lib/lanes/outpost-dispatch.js

@@ -104,6 +104,8 @@ export function buildOutpostLaneCommand(input) {
         ["--story", input.story],
         ["--account", input.account],
         ["--model", input.model],
+        ["--effort", input.effort],
+        ["--worker", input.worker],
         ["--hire", input.hire],
         ["--grant-context", input.grantContext],
     ]) {
@@ -114,6 +116,12 @@ export function buildOutpostLaneCommand(input) {
         args.push("--no-compact");
     return withRemoteHqDir(joinCommandParts(args));
 }
+/** True when a remote CLI exited after rejecting the forwarded effort flag. */
+export function outpostRejectedEffortOption(result) {
+    if (result.exitCode === 0)
+        return false;
+    return /(?:unknown|unrecognized) option[^\n]{0,120}--effort/i.test(`${result.stderr}\n${result.stdout}`);
+}
 export async function stageOutpostPayload(port, outpostId, bytes, put = fetch) {
     const staged = await port.stageExecInput(outpostId);
     const upload = await put(staged.putUrl, {

package/dist/lib/lanes/spawn.d.ts

@@ -9,6 +9,7 @@
  */
 import { PROVIDER_HOME_ENV } from "./accounts.js";
 import { type RunCompactionFn } from "./compaction.js";
+import { type ResolvedEffort } from "./effort.js";
 import { type KnownModelsDeps } from "./models.js";
 import { type LaunchTrigger } from "./delivery.js";
 import { type MachineIdentity } from "./machine-identity.js";
@@ -283,6 +284,8 @@ export interface SpawnLaunchOptions {
      * (`hq lanes message --no-compact`). Default true.
      */
     compact?: boolean;
+    /** Effort resolved by an explicit resume/message request, or pinned from its record. */
+    effort?: ResolvedEffort;
 }
 /**
  * Bind the account, spawn the worker and its watcher outside the caller's

package/dist/lib/lanes/spawn.js

@@ -15,7 +15,7 @@ import { PROVIDER_HOME_ENV, accountStatus, isLoggedOut, resolveAccount, selectBa
 import { COMPACTION_PROMPT, compactionAfterUsage, compactionDue, compactLaneSession, } from "./compaction.js";
 import { installDrainHook } from "./hooks-install.js";
 import { loadLanesConfig, providerAutoCompactTokens, providerCompactAfterMs, } from "./config.js";
-import { appendEffortFlag, resolveLaneEffort } from "./effort.js";
+import { appendEffortFlag, resolveLaneEffort, } from "./effort.js";
 import { defaultProbe, validateLaneModel, validateProfileLaneModel, } from "./models.js";
 import { claimableStatesFor, planLaneLaunch, providerSupportsSessionResume, } from "./delivery.js";
 import { AccountResolutionError, LanesError } from "./errors.js";
@@ -1719,7 +1719,13 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         accountModel: accountCfg?.model,
         providerModel: config.providers[lane.provider].model,
     });
-    const effort = resolveLaneEffort({
+    const pendingResumeEffort = pendingResume !== undefined
+        ? {
+            ...(existing.effort !== undefined ? { effort: existing.effort } : {}),
+            source: existing.effort_source ?? "none",
+        }
+        : undefined;
+    const effort = launch.effort ?? pendingResumeEffort ?? resolveLaneEffort({
         cliEffort: existing.effort_source === "cli" ? existing.effort : undefined,
         profileEffort,
         accountEffort: accountCfg?.effort,

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