@indigoai-us/hq-cli 5.271.0 → 5.273.0-alpha.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [5.273.0-alpha.0] — 2026-09-28
+
+### Added
+
+- `hq daemon sync` reports runner ownership and health, starts an immediate sync pass, pauses or resumes sync, and sets per-company sync mode. The daemon waits for an existing desktop runner to release its lease before starting its own.
+
+## [5.272.0] — 2026-09-28
+
+### Added
+
+- Add `hq core ontology merge-copies`, gated by
+  `checkpoint.ontology.merge-copies`. It merges each `<name> N.md` entity copy
+  into its own original (aliases, back-references, relationship links and
+  signal count), repoints links to the copy, and with `--delete` removes merged
+  copies from the vault. Dry run by default.
+
 ## [5.271.0] — 2026-09-28
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5148,6 +5148,33 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "HQ installation to operate on";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "merge-copies";
+            readonly description: "Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "company to change";
+            }, {
+                readonly flags: "--apply";
+                readonly description: "merge each copy into its original and re-point links (writes entity files)";
+            }, {
+                readonly flags: "--delete";
+                readonly description: "delete fully merged copies from the vault by exact key (after sync pushed the merge)";
+            }, {
+                readonly flags: "--limit <n>";
+                readonly description: "handle at most this many copies";
+            }, {
+                readonly flags: "--json";
+                readonly description: "print JSON";
+            }, {
+                readonly flags: "--hq-root <path>";
+                readonly description: "HQ installation to operate on";
+            }];
+            readonly subcommands: readonly [];
         }, {
             readonly name: "apply";
             readonly description: "Validate the run's entity candidates and write them to the payload company";
@@ -9071,6 +9098,120 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Print machine-readable JSON";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "sync";
+        readonly description: "Inspect and control the daemon's company sync runner";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "status";
+            readonly description: "Show sync ownership, heartbeat, last pass and log path";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "now";
+            readonly description: "Start a fresh sync pass immediately";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "pause";
+            readonly description: "Pause daemon sync until resumed";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "resume";
+            readonly description: "Resume daemon sync after a pause";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "take-ownership";
+            readonly description: "Persist daemon ownership of desktop sync and reconcile";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "mode";
+            readonly description: "Read or change a company's sync footprint";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "get";
+                readonly description: "Read a company's current all/shared sync mode";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <company>";
+                readonly arguments: readonly [{
+                    readonly name: "company";
+                    readonly required: true;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "set";
+                readonly description: "Set a company's sync mode to all or shared";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <company> <mode>";
+                readonly arguments: readonly [{
+                    readonly name: "company";
+                    readonly required: true;
+                    readonly variadic: false;
+                }, {
+                    readonly name: "mode";
+                    readonly required: true;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }];
+        }];
     }, {
         readonly name: "logs";
         readonly description: "Print the supervisor log, or one service's log";

package/dist/command-catalog.generated.js

@@ -6657,6 +6657,41 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "merge-copies",
+                        "description": "Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "company to change"
+                            },
+                            {
+                                "flags": "--apply",
+                                "description": "merge each copy into its original and re-point links (writes entity files)"
+                            },
+                            {
+                                "flags": "--delete",
+                                "description": "delete fully merged copies from the vault by exact key (after sync pushed the merge)"
+                            },
+                            {
+                                "flags": "--limit <n>",
+                                "description": "handle at most this many copies"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "print JSON"
+                            },
+                            {
+                                "flags": "--hq-root <path>",
+                                "description": "HQ installation to operate on"
+                            }
+                        ],
+                        "subcommands": []
+                    },
                     {
                         "name": "apply",
                         "description": "Validate the run's entity candidates and write them to the payload company",
@@ -11732,6 +11767,150 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "sync",
+                "description": "Inspect and control the daemon's company sync runner",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "status",
+                        "description": "Show sync ownership, heartbeat, last pass and log path",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "now",
+                        "description": "Start a fresh sync pass immediately",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "pause",
+                        "description": "Pause daemon sync until resumed",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "resume",
+                        "description": "Resume daemon sync after a pause",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "take-ownership",
+                        "description": "Persist daemon ownership of desktop sync and reconcile",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "mode",
+                        "description": "Read or change a company's sync footprint",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "get",
+                                "description": "Read a company's current all/shared sync mode",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <company>",
+                                "arguments": [
+                                    {
+                                        "name": "company",
+                                        "required": true,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "set",
+                                "description": "Set a company's sync mode to all or shared",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <company> <mode>",
+                                "arguments": [
+                                    {
+                                        "name": "company",
+                                        "required": true,
+                                        "variadic": false
+                                    },
+                                    {
+                                        "name": "mode",
+                                        "required": true,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            }
+                        ]
+                    }
+                ]
+            },
             {
                 "name": "logs",
                 "description": "Print the supervisor log, or one service's log",

package/dist/commands/core-ontology.d.ts

@@ -9,12 +9,15 @@
  */
 import { Command } from "commander";
 import { type FlagReader } from "../lib/checkpoint-ontology/plan.js";
+import { type DeleteVaultKey } from "../lib/checkpoint-ontology/merge-copies.js";
 export declare const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 /** The hq-flags read, scoped to the payload company. */
 export declare const registryFlagReader: FlagReader;
 export interface OntologyCommandDeps {
     readFlag?: FlagReader;
     now?: () => Date;
+    /** Builds the exact-key vault delete for a company uid. */
+    vaultDeleter?: (companyUid: string) => Promise<DeleteVaultKey>;
 }
 export declare function runOntologyPlan(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): Promise<string>;
 export declare function runOntologyApply(hqRoot: string, runDirOption: string | undefined, deps?: OntologyCommandDeps): string;
@@ -24,5 +27,18 @@ export declare function runOntologyApply(hqRoot: string, runDirOption: string |
  * `checkpoint.ontology.multi-writer`.
  */
 export declare function runOntologyDuplicates(hqRoot: string, slug: string | undefined, json: boolean, deps?: OntologyCommandDeps): Promise<string>;
+export interface MergeCopiesCommandOptions {
+    apply?: boolean;
+    delete?: boolean;
+    limit?: number;
+    json?: boolean;
+}
+/**
+ * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
+ * original (`--apply`), then delete merged copies from the vault
+ * (`--delete`). Without either it only reports. Gated by
+ * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
+ */
+export declare function runOntologyMergeCopies(hqRoot: string, slug: string | undefined, options: MergeCopiesCommandOptions, deps?: OntologyCommandDeps): Promise<string>;
 export declare function registerCoreOntologyCommand(core: Command): void;
 //# sourceMappingURL=core-ontology.d.ts.map

package/dist/commands/core-ontology.js

@@ -16,6 +16,9 @@ import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.j
 import { resolveOntologyCompany, WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
 import { findDuplicateGroups, summarizeMergeBack, } from "../lib/checkpoint-ontology/multi-writer.js";
 import { buildEntityIndex } from "../lib/checkpoint-ontology/tree.js";
+import { MERGE_COPIES_FLAG, mergeCopies, } from "../lib/checkpoint-ontology/merge-copies.js";
+import { callDeleteEndpoint } from "./files.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 export const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 class OntologyUsageError extends Error {
 }
@@ -124,6 +127,72 @@ export async function runOntologyDuplicates(hqRoot, slug, json, deps = {}) {
     }
     return lines.join("\n");
 }
+/** Delete one exact company vault key, refusing when the server would match anything else. */
+async function companyVaultDeleter(companyUid) {
+    const token = (await resolveVaultCredential()).token;
+    return async (key) => {
+        const preview = await callDeleteEndpoint({ token, companyUid, prefix: key, dryRun: true });
+        if (preview.matched === 0)
+            return 0;
+        if (preview.matched !== 1 || preview.keys.length !== 1 || preview.keys[0] !== key) {
+            throw new Error(`vault preview matched ${preview.matched} object(s), not exactly ${key}`);
+        }
+        return (await callDeleteEndpoint({ token, companyUid, prefix: key, dryRun: false })).deleted;
+    };
+}
+function mergeCopiesSummary(report) {
+    const held = report.plans.filter((plan) => plan.held).length;
+    const lines = [
+        `ontology merge-copies (${report.mode.replace("_", " ")}) in ${report.company}: ${report.plans.length} of ${report.copies_found} copies, ${held} held, ${report.skipped.length} skipped`,
+        `  merged ${report.merged.length}, relinked ${report.relinked.length}, deleted ${report.deleted.length}, not ready ${report.not_ready.length}, errors ${report.errors.length}`,
+        `  duplicate groups ${report.duplicate_groups_before} -> ${report.duplicate_groups_after}; broken entity links ${report.broken_links_before} -> ${report.broken_links_after}`,
+    ];
+    for (const plan of report.plans.filter((entry) => entry.held))
+        lines.push(`  held ${plan.copy}: ${plan.held}`);
+    for (const error of report.errors)
+        lines.push(`  error ${error.path}: ${error.error}`);
+    return lines.join("\n");
+}
+/**
+ * `hq core ontology merge-copies`: merge `<slug> <n>.md` copies into their
+ * original (`--apply`), then delete merged copies from the vault
+ * (`--delete`). Without either it only reports. Gated by
+ * `checkpoint.ontology.merge-copies` and `checkpoint.ontology.multi-writer`.
+ */
+export async function runOntologyMergeCopies(hqRoot, slug, options, deps = {}) {
+    if (options.apply && options.delete) {
+        throw new OntologyUsageError("ontology: run --apply first, let sync push the merged files, then run --delete");
+    }
+    if (options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1)) {
+        throw new OntologyUsageError("ontology: --limit must be a positive whole number");
+    }
+    const resolution = resolveOntologyCompany(hqRoot, slug);
+    if (!resolution.ok)
+        throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
+    const company = resolution.company;
+    const readFlag = deps.readFlag ?? registryFlagReader;
+    for (const flag of [MERGE_COPIES_FLAG, MULTI_WRITER_FLAG]) {
+        if (!(await readFlag(flag, company))) {
+            return options.json ? JSON.stringify({ company: company.slug, skipped: `${flag} off` }) : `ontology merge-copies: skipped (${flag} is off)`;
+        }
+    }
+    const mode = options.apply ? "merge" : options.delete ? "delete" : "dry_run";
+    let deleteVaultKey;
+    if (mode === "delete") {
+        if (!company.cloudUid)
+            throw new OntologyUsageError("ontology: the company has no cloud_uid in the manifest");
+        deleteVaultKey = await (deps.vaultDeleter ?? companyVaultDeleter)(company.cloudUid);
+    }
+    const report = await mergeCopies({
+        hqRoot,
+        company,
+        mode,
+        now: deps.now?.() ?? new Date(),
+        ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        ...(deleteVaultKey ? { deleteVaultKey } : {}),
+    });
+    return options.json ? JSON.stringify(report, null, 2) : mergeCopiesSummary(report);
+}
 function fail(error) {
     if (error instanceof OntologyUsageError || error instanceof ApplyError || error instanceof WriteBoundsError) {
         process.stderr.write(`${error.message}\n`);
@@ -163,6 +232,23 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
+    ontology
+        .command("merge-copies")
+        .description("Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)")
+        .requiredOption("--company <slug>", "company to change")
+        .option("--apply", "merge each copy into its original and re-point links (writes entity files)")
+        .option("--delete", "delete fully merged copies from the vault by exact key (after sync pushed the merge)")
+        .option("--limit <n>", "handle at most this many copies", (value) => Number(value))
+        .option("--json", "print JSON")
+        .option("--hq-root <path>", "HQ installation to operate on")
+        .action(async (options) => {
+        try {
+            process.stdout.write(`${await runOntologyMergeCopies(rootFor(options), options.company, options)}\n`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
     ontology
         .command("apply")
         .description("Validate the run's entity candidates and write them to the payload company")

package/dist/commands/daemon.d.ts

@@ -16,6 +16,7 @@
 import type { Command } from "commander";
 import { type LegacyUnit } from "../lib/daemon/legacy.js";
 import type { HostApp } from "../lib/daemon/supervisor.js";
+import { type SyncModeVaultClient } from "./sync-mode.js";
 import type { RunCommand } from "../lib/service-manager/launchd.js";
 export interface DaemonCommandDeps {
     env: NodeJS.ProcessEnv;
@@ -38,6 +39,8 @@ export interface DaemonCommandDeps {
     userHome: (user: string) => string;
     /** The pid is a live `hq daemon run`. */
     daemonAlive: (pid: number) => boolean;
+    /** Test seam for the company sync-mode commands. */
+    syncModeClient?: () => Promise<SyncModeVaultClient>;
     windowsUser?: string;
     windowsHeadlessLauncher?: string;
     systemUnitDir?: string;