@indigoai-us/hq-cli 5.236.0 → 5.237.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [5.237.0] — 2026-09-27
+
+### Added
+
+- Lane-store creates and updates record their hq-cli version. User-invoked
+  writes from older CLIs are refused, while background writers preserve newer
+  stamps and record Outpost owner versions separately. `hq lanes checks` warns
+  about newer stamps, and `HQ_LANES_ALLOW_OLDER_WRITE=1` provides a one-command
+  override with a warning.
+
 ## [5.236.0] — 2026-09-27
 
 ### Changed

package/dist/commands/lanes-checks.js

@@ -1,9 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
 import { loadLanesConfig } from "../lib/lanes/config.js";
 import { LanesError, isLanesError } from "../lib/lanes/errors.js";
 import { evaluateTrackerChecks } from "../lib/lanes/tracker-checks.js";
-import { laneRecordPath, listLaneIds, listQuestionIds, questionRecordPath, readLane, readQuestion } from "../lib/lanes/store.js";
+import { LANE_STORE_UPGRADE_COMMAND, isLaneStoreVersionNewer, laneRecordPath, listLaneIds, listQuestionIds, questionRecordPath, readLane, readQuestion } from "../lib/lanes/store.js";
 import { createLocalTrackerStore } from "../lib/lanes/tracker-store.js";
 import { LANES_TRACKER_FLAG } from "./lanes-tracker.js";
 function fail(error, message, details = {}) {
@@ -575,6 +576,25 @@ export async function resolveTrackerCompany(deps, requested) {
 async function checkReport(root, company, projects, directiveProjects, projectFilter, now) {
     const selectedProjects = [...projects.values()];
     const laneRecords = readScopedLanes(root, company, selectedProjects);
+    const warnings = laneRecords.flatMap((lane) => {
+        const storedVersion = [lane.written_by_version, lane.owner_written_by_version]
+            .filter((version) => version !== undefined)
+            .reduce((newest, candidate) => {
+            if (newest === undefined || isLaneStoreVersionNewer(candidate, newest))
+                return candidate;
+            return newest;
+        }, undefined);
+        return storedVersion !== undefined && isLaneStoreVersionNewer(storedVersion, CLI_VERSION)
+            ? [{
+                    code: "lane_store_newer_cli",
+                    lane_id: lane.lane_id,
+                    stored_version: storedVersion,
+                    running_version: CLI_VERSION,
+                    upgrade_command: LANE_STORE_UPGRADE_COMMAND,
+                    message: `Lane ${lane.lane_id} has a local or owner-host copy last written by hq-cli ${storedVersion}, newer than running hq-cli ${CLI_VERSION}. Upgrade before writing.`
+                }]
+            : [];
+    });
     const teams = readTeamInputs(root, company, selectedProjects, laneRecords);
     const questionRecords = readCompanyQuestions(root, company, projectFilter);
     const trackerRecords = await readTrackerCheckRecords(root, company, selectedProjects);
@@ -586,6 +606,7 @@ async function checkReport(root, company, projects, directiveProjects, projectFi
         ok: true,
         company: company.slug,
         generated_at: now.toISOString(),
+        ...(warnings.length === 0 ? {} : { warnings }),
         checks: evaluateTrackerChecks({
             now,
             thresholds: loadLanesConfig(root).tracker.checks,

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

@@ -52,6 +52,9 @@ export declare function tryReadLane(hqRoot: string, laneId: string, deps?: Store
 export declare function readLane(hqRoot: string, laneId: string, deps?: StoreDeps): LaneRecord;
 export declare function tryReadQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord | null;
 export declare function readQuestion(hqRoot: string, questionId: string, deps?: StoreDeps): QuestionRecord;
+/** Semver precedence includes prerelease identifiers (for example, rc.2 > rc.1). */
+export declare function isLaneStoreVersionNewer(storedVersion: string, runningVersion: string): boolean;
+export declare const LANE_STORE_UPGRADE_COMMAND = "npm install -g @indigoai-us/hq-cli@latest";
 export declare function createLane(hqRoot: string, init: Omit<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at"> & Partial<Pick<LaneRecord, "schema_version" | "lane_id" | "version" | "created_at" | "updated_at">>, deps?: StoreDeps): LaneRecord;
 /** Hierarchy lock: separate from record writes so callers can CAS-write while holding it. */
 export declare function withLaneHireLocks<T>(hqRoot: string, laneIds: readonly string[], fn: () => T, deps?: StoreDeps): T;

package/dist/lib/lanes/store.js

@@ -10,6 +10,8 @@ import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import semver from "semver";
+import { CLI_VERSION } from "../../cli-version.js";
 import { generateUlid } from "../mesh/live/ulid.js";
 import { resolveLanesHqRoot } from "./hq-root.js";
 import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, isLaneVersionConflict, } from "./errors.js";
@@ -391,6 +393,26 @@ export function parseLaneRecord(raw, filePath) {
     const schema_version = requireString(raw.schema_version, "schema_version");
     parseMajorSchema(schema_version, "hq-lane", 1);
     requireString(raw.lane_id, "lane_id");
+    if (raw.written_by_version !== undefined) {
+        const writtenByVersion = requireString(raw.written_by_version, "written_by_version");
+        if (!semver.valid(writtenByVersion)) {
+            throw new LaneSchemaError("written_by_version must be a valid semver version", {
+                path: filePath,
+                field: "written_by_version",
+                value: writtenByVersion,
+            });
+        }
+    }
+    if (raw.owner_written_by_version !== undefined) {
+        const ownerWrittenByVersion = requireString(raw.owner_written_by_version, "owner_written_by_version");
+        if (!semver.valid(ownerWrittenByVersion)) {
+            throw new LaneSchemaError("owner_written_by_version must be a valid semver version", {
+                path: filePath,
+                field: "owner_written_by_version",
+                value: ownerWrittenByVersion,
+            });
+        }
+    }
     requireInt(raw.version, "version");
     requireInt(raw.depth, "depth");
     requireInt(raw.priority, "priority");
@@ -950,6 +972,52 @@ export function readQuestion(hqRoot, questionId, deps = defaultStoreDeps()) {
         throw new LaneNotFoundError("question", questionId);
     return record;
 }
+/** Semver precedence includes prerelease identifiers (for example, rc.2 > rc.1). */
+export function isLaneStoreVersionNewer(storedVersion, runningVersion) {
+    if (!semver.valid(storedVersion)) {
+        throw new LanesError("lane_store_version_invalid", "Lane store writer version is not valid semver", {
+            stored_version: storedVersion,
+        });
+    }
+    if (!semver.valid(runningVersion)) {
+        throw new LanesError("lane_store_version_invalid", "Running hq-cli version is not valid semver", {
+            running_version: runningVersion,
+        });
+    }
+    return semver.gt(storedVersion, runningVersion);
+}
+const OLDER_LANE_STORE_WRITE_OVERRIDE = "HQ_LANES_ALLOW_OLDER_WRITE";
+export const LANE_STORE_UPGRADE_COMMAND = "npm install -g @indigoai-us/hq-cli@latest";
+const warnedBackgroundWriterLaneIds = new Set();
+function assertLaneStoreWriteAllowed(lane, laneId, writer) {
+    const storedVersion = lane.written_by_version;
+    if (storedVersion === undefined || !isLaneStoreVersionNewer(storedVersion, CLI_VERSION))
+        return;
+    const warning = `Lane ${laneId} was last written by hq-cli ${storedVersion}, newer than running hq-cli ${CLI_VERSION}. Upgrade with \`${LANE_STORE_UPGRADE_COMMAND}\` before writing.`;
+    if (writer === "command" || writer === "creator") {
+        if (process.env[OLDER_LANE_STORE_WRITE_OVERRIDE] === "1") {
+            console.warn(`${warning} Proceeding because ${OLDER_LANE_STORE_WRITE_OVERRIDE}=1 was set for this command.`);
+            return;
+        }
+        throw new LanesError("lane_store_newer_cli", `${warning} For a one-command override, set ${OLDER_LANE_STORE_WRITE_OVERRIDE}=1.`, {
+            lane_id: laneId,
+            stored_version: storedVersion,
+            running_version: CLI_VERSION,
+            upgrade_command: LANE_STORE_UPGRADE_COMMAND,
+            override: `${OLDER_LANE_STORE_WRITE_OVERRIDE}=1`,
+        });
+    }
+    if (!warnedBackgroundWriterLaneIds.has(laneId)) {
+        warnedBackgroundWriterLaneIds.add(laneId);
+        console.warn(`${warning} Continuing background ${writer} writes and preserving the newer stamp.`);
+    }
+}
+function newestLaneStoreVersion(storedVersion) {
+    if (storedVersion !== undefined && isLaneStoreVersionNewer(storedVersion, CLI_VERSION)) {
+        return storedVersion;
+    }
+    return CLI_VERSION;
+}
 function recordsEquivalentAsideFromClock(current, updated) {
     if (updated === current)
         return true;
@@ -961,7 +1029,7 @@ function recordsEquivalentAsideFromClock(current, updated) {
     };
     return JSON.stringify(strip(current)) === JSON.stringify(strip(updated));
 }
-function casWrite(filePath, expectedVersion, parse, merge, updater, deps) {
+function casWrite(filePath, expectedVersion, parse, merge, updater, deps, options = {}) {
     return withRecordLock(filePath, deps, () => {
         const current = readMergedRecord(filePath, parse, merge, deps);
         if (current === null) {
@@ -980,9 +1048,11 @@ function casWrite(filePath, expectedVersion, parse, merge, updater, deps) {
         if (recordsEquivalentAsideFromClock(current, updated)) {
             return current;
         }
+        options.beforeWrite?.(current);
         const next = {
             ...current,
             ...updated,
+            ...options.stamp?.(current),
             version: current.version + 1,
             updated_at: deps.now().toISOString(),
         };
@@ -996,6 +1066,7 @@ export function createLane(hqRoot, init, deps = defaultStoreDeps()) {
     const filePath = laneRecordPath(hqRoot, lane_id);
     const record = {
         ...init,
+        written_by_version: CLI_VERSION,
         hire_grant: init.hire_grant ?? 0,
         schema_version: init.schema_version ?? LANE_SCHEMA_VERSION,
         lane_id,
@@ -1060,7 +1131,10 @@ export function updateLane(hqRoot, laneId, expectedVersion, writer, updater, dep
             }
         }
         return updated;
-    }, deps);
+    }, deps, {
+        beforeWrite: (current) => assertLaneStoreWriteAllowed(current, laneId, writer),
+        stamp: (current) => ({ written_by_version: newestLaneStoreVersion(current.written_by_version) }),
+    });
     if (laneStoryLedgerEnabled() && before && laneLedgerRelevantChange(before, updated)) {
         return syncStoryLedgerForLane(hqRoot, updated, deps);
     }
@@ -1182,7 +1256,12 @@ export function syncLaneRecordFromOwner(hqRoot, laneId, outpostId, rawOwnerLane,
             current.outpost_command_id !== undefined
             ? { ...ownerLane, outpost_command_id: current.outpost_command_id }
             : ownerLane;
-        const synced = mergeLaneRecords(ownerSnapshot, [current]);
+        const merged = mergeLaneRecords(ownerSnapshot, [current]);
+        const synced = {
+            ...merged,
+            written_by_version: newestLaneStoreVersion(current.written_by_version),
+            owner_written_by_version: ownerLane.written_by_version,
+        };
         parseLaneRecord(synced, filePath);
         atomicWriteJson(filePath, synced, deps);
         return synced;

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

@@ -318,6 +318,10 @@ export interface LaneStory {
 export interface LaneRecord {
     schema_version: typeof LANE_SCHEMA_VERSION | string;
     lane_id: string;
+    /** CLI release that most recently wrote this lane record. Absent on legacy rows. */
+    written_by_version?: string;
+    /** CLI release that most recently wrote the owner-host copy synced to primary. */
+    owner_written_by_version?: string;
     /** `null` is a core/personal lane (spec §6.2 / §10). Not an empty slug. */
     company: LaneCompanyRef | null;
     /** Explicit Work Mesh attribution for a personal lane; never inferred from cwd. */

package/dist/lib/lanes/types.js

@@ -216,7 +216,7 @@ export const REQUIRED_LANE_RECORD_FIELDS = [
 export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spawn", "story-ledger"];
 /** Field ownership at the durable-record mutation boundary (spec §10.1). */
 export const LANE_FIELD_WRITERS = {
-    schema_version: ["creator"], lane_id: ["creator"], company: ["creator"],
+    schema_version: ["creator"], lane_id: ["creator"], written_by_version: [], owner_written_by_version: [], company: ["creator"],
     project_id: ["command"], story_id: ["command"], no_story_reason: ["creator", "command"], ledger_sync_error: ["story-ledger"], pending_question_ids: ["story-ledger"], stories: ["creator", "command", "watcher", "reconcile", "spawn"], thread_id: ["creator", "command", "spawn"], mesh_company: ["creator", "command"],
     depth: ["command"], senior: ["command"], senior_history: ["command"],
     hire_grant: ["creator", "command"],

package/package.json

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