@indigoai-us/hq-cli 5.231.1 → 5.232.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.232.0] — 2026-09-27
+
+### Added
+
+- `checkpoint.ontology.sync-gated` (off by default) turns the checkpoint
+  ontology step on like `checkpoint.ontology`. Older CLI builds do not read it,
+  so it can be turned on widely without them. With either flag on, the step runs
+  only when the hq-cloud bundled with this CLI and the one the hq daemon runs
+  are both 6.18.7 or later; otherwise it skips and says which copy is older.
+  It also skips while the daemon's sync still runs from before its hq-cloud
+  copy was installed. `hq core ontology apply` checks again before it writes and
+  reports `sync_client_old` with the reason. Earlier hq-cloud releases pushed
+  stale copies of deleted entities.
+
 ## [5.231.1] — 2026-09-27
 
 ### Fixed

package/dist/commands/core-ontology.js

@@ -86,6 +86,8 @@ export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
         throw new OntologyUsageError("ontology: the run payload names no company");
     }
     const report = applyOntologyRun({ hqRoot, runDir, company, now: deps.now?.() });
+    if (report.status === "sync_client_old")
+        return `ontology: skipped (${report.skip_reason}); nothing written`;
     if (report.status !== "applied")
         return `ontology: ${report.status.replaceAll("_", " ")}; nothing written`;
     return (`ontology: ${report.created.length} created, ${report.updated.length} updated, ` +

package/dist/lib/checkpoint-ontology/apply.d.ts

@@ -7,6 +7,7 @@
  */
 import { type DuplicateReport, type MergeBackOutcome } from "./multi-writer.js";
 import { type CompanyBriefResult } from "./company-brief.js";
+import { type SyncClientVersions } from "./sync-client.js";
 import { type WritableEntityType } from "./identity.js";
 import { type EntityIndex } from "./tree.js";
 export declare const CAPS: {
@@ -30,7 +31,9 @@ export interface ApplyReport {
     schema: "hq-checkpoint-ontology-report.v1";
     company: string;
     run_id: string;
-    status: "applied" | "no_candidates" | "invalid_candidates";
+    status: "applied" | "no_candidates" | "invalid_candidates" | "sync_client_old";
+    /** Present only with status `sync_client_old`: which sync client copy is older or unknown. */
+    skip_reason?: string;
     planned_inputs: number;
     planned_tokens: number;
     candidates: number;
@@ -94,6 +97,8 @@ export interface ApplyOptions {
     /** The payload company. Must equal the plan's company. */
     company: string;
     now?: Date;
+    /** Test seam for the sync client check; defaults to reading this machine's hq-cloud copies. */
+    syncClientVersions?: () => SyncClientVersions;
 }
 export declare class ApplyError extends Error {
     constructor(message: string);

package/dist/lib/checkpoint-ontology/apply.js

@@ -12,6 +12,7 @@ import { entityKey, freshAliases, MAX_NAME_LENGTH, ownNames } from "./aliases.js
 import { recordOutbox, scanDuplicates } from "./multi-writer.js";
 import { writeCompanyBrief } from "./company-brief.js";
 import { entitiesRoot, resolveOntologyCompany, safeWriteFile } from "./company.js";
+import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { appendBackRefs, parseEntityFile, patchEntityFile, previewSignalContent, renderNewEntity, validateEntityFrontmatter, } from "./entity-file.js";
 import { canonicalizeName, entityId, isRejectedName, isWritableEntityType, normalizeEntityName, squash, toSlug, } from "./identity.js";
 import { CANDIDATES_FILE, CANDIDATES_SCHEMA, PLAN_FILE, PLAN_SCHEMA, REPORT_FILE, readLedger, writeLedger, } from "./plan.js";
@@ -232,6 +233,15 @@ export function applyOntologyRun(options) {
         fs.writeFileSync(path.join(options.runDir, REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
         return report;
     };
+    // CO-45: the sync client can change between plan and apply, so check it
+    // again before anything is written.
+    const syncClient = checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)());
+    if (!syncClient.ok) {
+        report.status = "sync_client_old";
+        report.skip_reason = syncClient.reason;
+        report.inputs_pending = plan.inputs.filter((i) => i.kind !== "session").map((i) => i.id);
+        return finish();
+    }
     const candidatesPath = path.join(options.runDir, CANDIDATES_FILE);
     if (!fs.existsSync(candidatesPath)) {
         report.status = "no_candidates";

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -11,7 +11,16 @@ import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
 import { type MultiWriterStart } from "./multi-writer.js";
 import { type EntityHint } from "./hints.js";
+import { type SyncClientVersions } from "./sync-client.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
+/**
+ * Turns the step on like `checkpoint.ontology`, but only builds that check the
+ * sync client read it (CO-45, owner decision CO-D-005). Older CLI builds read
+ * only `checkpoint.ontology`, so this key can default on without starting the
+ * step next to an hq-cloud older than 6.18.7. Either key needs a sync client of
+ * 6.18.7 or later; see ./sync-client.ts.
+ */
+export declare const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
  * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
@@ -159,6 +168,8 @@ export interface PlanOptions {
     payload: CheckpointPayloadLike;
     readFlag: FlagReader;
     now?: Date;
+    /** This machine's hq-cloud versions; defaults to reading them. */
+    syncClientVersions?: () => SyncClientVersions;
 }
 export type PlanOutcome = {
     status: "skipped";

package/dist/lib/checkpoint-ontology/plan.js

@@ -14,8 +14,17 @@ import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
 import { startMultiWriterRun } from "./multi-writer.js";
 import { entityHints, wordWeights } from "./hints.js";
+import { checkSyncClient, readSyncClientVersions } from "./sync-client.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
+/**
+ * Turns the step on like `checkpoint.ontology`, but only builds that check the
+ * sync client read it (CO-45, owner decision CO-D-005). Older CLI builds read
+ * only `checkpoint.ontology`, so this key can default on without starting the
+ * step next to an hq-cloud older than 6.18.7. Either key needs a sync client of
+ * 6.18.7 or later; see ./sync-client.ts.
+ */
+export const ONTOLOGY_SYNC_GATED_FLAG = "checkpoint.ontology.sync-gated";
 export const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
 /**
  * Applies only when the payload's sibling backend is grok. On gold-v2, Claude
@@ -231,10 +240,12 @@ export async function planOntologyRun(options) {
     if (!resolution.ok)
         return { status: "skipped", reason: resolution.reason };
     const company = resolution.company;
-    if (!(await options.readFlag(ONTOLOGY_FLAG, company))) {
+    const ontologyOn = (await options.readFlag(ONTOLOGY_FLAG, company)) || (await options.readFlag(ONTOLOGY_SYNC_GATED_FLAG, company));
+    const syncClient = ontologyOn ? checkSyncClient((options.syncClientVersions ?? readSyncClientVersions)()) : null;
+    if (!ontologyOn || !syncClient?.ok) {
         // A preference recorded while the ontology was on must not outlive it.
         fs.rmSync(backendPreferencePath(hqRoot, company), { force: true });
-        return { status: "skipped", reason: "flag off" };
+        return { status: "skipped", reason: syncClient && !syncClient.ok ? syncClient.reason : "flag off" };
     }
     const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";

package/dist/lib/checkpoint-ontology/sync-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The sync client check for the checkpoint ontology step (CO-45, owner
+ * decision CO-D-005).
+ *
+ * The step writes entity files locally and a sync client pushes them. hq-cloud
+ * before 6.18.7 pushed stale local copies of deleted entities as new objects
+ * and overwrote newer entities with older ones (INC-CO-RESURRECT). hq-flags
+ * cannot target by client version, so the step checks this machine's hq-cloud
+ * copies itself: the one bundled with this CLI (`hq sync`) and the one the hq
+ * daemon runs. If either is older than 6.18.7, or the bundled copy cannot be
+ * read, the step does not run. The daemon picks up a new hq-cloud only when
+ * its sync unit restarts, so a sync unit that started before its copy was
+ * installed may still run older code; the step does not run then either.
+ *
+ * The desktop app's sync runner is not visible from here. The vault's
+ * `vault.refuse-stale-entity-recreate` guard refuses those two writes from any
+ * client.
+ */
+export declare const MIN_SYNC_CLIENT_VERSION = "6.18.7";
+export interface SyncClientVersions {
+    /** hq-cloud bundled with this CLI, or null when it cannot be read. */
+    bundled: string | null;
+    /** hq-cloud the hq daemon runs, or null when it cannot be read. */
+    daemon: string | null;
+    /** True when the daemon's running sync unit started before that copy was installed. */
+    daemonRestartPending?: boolean;
+}
+export type SyncClientCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Read this machine's hq-cloud versions. Never throws. */
+export declare function readSyncClientVersions(): SyncClientVersions;
+/** Every readable copy must be at least 6.18.7, and the bundled copy must be readable. */
+export declare function checkSyncClient(versions: SyncClientVersions): SyncClientCheck;
+//# sourceMappingURL=sync-client.d.ts.map

package/dist/lib/checkpoint-ontology/sync-client.js

@@ -0,0 +1,84 @@
+/**
+ * The sync client check for the checkpoint ontology step (CO-45, owner
+ * decision CO-D-005).
+ *
+ * The step writes entity files locally and a sync client pushes them. hq-cloud
+ * before 6.18.7 pushed stale local copies of deleted entities as new objects
+ * and overwrote newer entities with older ones (INC-CO-RESURRECT). hq-flags
+ * cannot target by client version, so the step checks this machine's hq-cloud
+ * copies itself: the one bundled with this CLI (`hq sync`) and the one the hq
+ * daemon runs. If either is older than 6.18.7, or the bundled copy cannot be
+ * read, the step does not run. The daemon picks up a new hq-cloud only when
+ * its sync unit restarts, so a sync unit that started before its copy was
+ * installed may still run older code; the step does not run then either.
+ *
+ * The desktop app's sync runner is not visible from here. The vault's
+ * `vault.refuse-stale-entity-recreate` guard refuses those two writes from any
+ * client.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import semver from "semver";
+import { bundledHqCloud, currentHqCloud } from "../daemon/hq-cloud.js";
+import { daemonPaths } from "../daemon/paths.js";
+export const MIN_SYNC_CLIENT_VERSION = "6.18.7";
+/** Read this machine's hq-cloud versions. Never throws. */
+export function readSyncClientVersions() {
+    const bundled = bundledHqCloud()?.version ?? null;
+    let daemon = null;
+    let daemonRestartPending = false;
+    try {
+        const paths = daemonPaths();
+        const picked = currentHqCloud(paths.root);
+        daemon = picked?.version ?? null;
+        if (picked) {
+            try {
+                daemonRestartPending = syncStartedBefore(paths.statePath, path.join(picked.root, "package.json"));
+            }
+            catch (err) {
+                // Unknown start time: assume the running sync may be older.
+                daemonRestartPending = true;
+                console.warn(`ontology: could not read the hq daemon's sync start time: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`ontology: could not read the hq daemon's hq-cloud version: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { bundled, daemon, daemonRestartPending };
+}
+/** Whether the daemon's running sync unit started before `copyPackageJson` was written. No state file: no running unit. */
+function syncStartedBefore(statePath, copyPackageJson) {
+    let state;
+    try {
+        state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    const sync = state.units?.find((u) => u.id === "sync" && u.status === "running");
+    if (!sync || typeof sync.startedAt !== "number")
+        return false;
+    return fs.statSync(copyPackageJson).mtimeMs > sync.startedAt;
+}
+/** Every readable copy must be at least 6.18.7, and the bundled copy must be readable. */
+export function checkSyncClient(versions) {
+    if (versions.bundled === null) {
+        return { ok: false, reason: `sync client version unknown; needs hq-cloud ${MIN_SYNC_CLIENT_VERSION} or later` };
+    }
+    for (const [name, version] of [["bundled", versions.bundled], ["daemon", versions.daemon]]) {
+        if (version === null)
+            continue;
+        const parsed = semver.valid(version);
+        if (parsed === null || semver.lt(parsed, MIN_SYNC_CLIENT_VERSION)) {
+            return { ok: false, reason: `sync client hq-cloud ${version} (${name}) is older than ${MIN_SYNC_CLIENT_VERSION}` };
+        }
+    }
+    if (versions.daemonRestartPending) {
+        return { ok: false, reason: `the hq daemon's sync has not restarted onto hq-cloud ${versions.daemon ?? "(unknown)"} yet` };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=sync-client.js.map

package/package.json

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