@indigoai-us/hq-cli 5.221.0 → 5.222.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.222.0] — 2026-09-26
+
+- Checkpoint ontology, behind `checkpoint.ontology.multi-writer` (off by
+  default): entity versions that sync set aside after losing a push race are
+  merged back at the start of each plan (aliases, back-references, the higher
+  `signal_count`, the later `last_updated`). Any other difference keeps both
+  and leaves the set-aside copy, and an entity deleted since is not
+  re-created. Every entity file the step writes is recorded in
+  `.hq/ontology-outbox/<company>.json`. The apply report counts duplicate
+  entity groups, and `hq core ontology duplicates --company <slug> [--json]`
+  lists them.
+
 ## [5.221.0] — 2026-09-26
 
 ### Added

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

@@ -5124,6 +5124,24 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "HQ installation to operate on";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "duplicates";
+            readonly description: "List same-type entities whose names collide, with a proposed survivor (read-only)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "company to scan";
+            }, {
+                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";

package/dist/command-catalog.generated.js

@@ -6626,6 +6626,29 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "duplicates",
+                        "description": "List same-type entities whose names collide, with a proposed survivor (read-only)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "company to scan"
+                            },
+                            {
+                                "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",

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

@@ -18,5 +18,11 @@ export interface OntologyCommandDeps {
 }
 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;
+/**
+ * `hq core ontology duplicates`: every group of same-type entities whose
+ * names collide, with a proposed survivor. Read-only; gated by
+ * `checkpoint.ontology.multi-writer`.
+ */
+export declare function runOntologyDuplicates(hqRoot: string, slug: string | undefined, json: boolean, deps?: OntologyCommandDeps): Promise<string>;
 export declare function registerCoreOntologyCommand(core: Command): void;
 //# sourceMappingURL=core-ontology.d.ts.map

package/dist/commands/core-ontology.js

@@ -11,9 +11,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
-import { planOntologyRun } from "../lib/checkpoint-ontology/plan.js";
+import { MULTI_WRITER_FLAG, planOntologyRun, } from "../lib/checkpoint-ontology/plan.js";
 import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.js";
-import { WriteBoundsError } from "../lib/checkpoint-ontology/company.js";
+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";
 export const ONTOLOGY_PAYLOAD_FILE = "payload.json";
 class OntologyUsageError extends Error {
 }
@@ -49,6 +51,16 @@ function companyBriefSuffix(brief) {
         return "";
     return `; company brief ${brief.status}${brief.reason ? ` (${brief.reason})` : ""}`;
 }
+function multiWriterSuffix(start) {
+    if (!start)
+        return "";
+    const parts = [];
+    if (start.merge_back.length > 0)
+        parts.push(`set-aside versions: ${summarizeMergeBack(start.merge_back)}`);
+    if (start.error)
+        parts.push(`multi-writer error ${start.error}`);
+    return parts.length > 0 ? `; ${parts.join("; ")}` : "";
+}
 export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
     const runDir = requireRunDir(runDirOption);
     const outcome = await planOntologyRun({
@@ -59,12 +71,13 @@ export async function runOntologyPlan(hqRoot, runDirOption, deps = {}) {
         now: deps.now?.(),
     });
     if (outcome.status === "skipped") {
-        return `ontology: skipped (${outcome.reason})${companyBriefSuffix(outcome.companyBrief)}`;
+        return `ontology: skipped (${outcome.reason})${companyBriefSuffix(outcome.companyBrief)}${multiWriterSuffix(outcome.multiWriter)}`;
     }
     const { plan } = outcome;
     return (`ontology: planned ${plan.inputs.length} input(s), ~${plan.budget.planned_tokens} tokens, ` +
         `${plan.pending_after_run} left for later runs; plan at ${outcome.planPath}` +
-        companyBriefSuffix(outcome.companyBrief));
+        companyBriefSuffix(outcome.companyBrief) +
+        multiWriterSuffix(plan.multi_writer));
 }
 export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
     const runDir = requireRunDir(runDirOption);
@@ -78,7 +91,36 @@ export function runOntologyApply(hqRoot, runDirOption, deps = {}) {
     return (`ontology: ${report.created.length} created, ${report.updated.length} updated, ` +
         `${report.matched} matched, ${report.rejected.length} rejected, ${report.deferred.length} deferred, ` +
         `${report.suspect_duplicates.length} suspect duplicate(s), ${report.write_errors.length} write error(s)` +
-        companyBriefSuffix(report.company_brief));
+        companyBriefSuffix(report.company_brief) +
+        (report.multi_writer?.duplicates ? `; ${report.multi_writer.duplicates.groups} duplicate group(s) in the company` : "") +
+        (report.multi_writer?.error ? `; multi-writer error ${report.multi_writer.error}` : ""));
+}
+/**
+ * `hq core ontology duplicates`: every group of same-type entities whose
+ * names collide, with a proposed survivor. Read-only; gated by
+ * `checkpoint.ontology.multi-writer`.
+ */
+export async function runOntologyDuplicates(hqRoot, slug, json, deps = {}) {
+    const resolution = resolveOntologyCompany(hqRoot, slug);
+    if (!resolution.ok)
+        throw new OntologyUsageError(`ontology: company rejected: ${resolution.reason}`);
+    const company = resolution.company;
+    if (!(await (deps.readFlag ?? registryFlagReader)(MULTI_WRITER_FLAG, company))) {
+        return json ? JSON.stringify({ company: company.slug, skipped: "flag off" }) : `ontology duplicates: skipped (${MULTI_WRITER_FLAG} is off)`;
+    }
+    const groups = findDuplicateGroups(buildEntityIndex(company.dir));
+    if (json)
+        return JSON.stringify({ company: company.slug, groups }, null, 2);
+    if (groups.length === 0)
+        return `ontology duplicates: none in ${company.slug}`;
+    const lines = [`ontology duplicates: ${groups.length} group(s) in ${company.slug}`];
+    for (const group of groups) {
+        lines.push(`${group.type} (${group.reason.replaceAll("_", " ")}), keep ${group.survivor}`);
+        for (const rel of group.paths)
+            if (rel !== group.survivor)
+                lines.push(`  ${rel}`);
+    }
+    return lines.join("\n");
 }
 function fail(error) {
     if (error instanceof OntologyUsageError || error instanceof ApplyError || error instanceof WriteBoundsError) {
@@ -105,6 +147,20 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
+    ontology
+        .command("duplicates")
+        .description("List same-type entities whose names collide, with a proposed survivor (read-only)")
+        .requiredOption("--company <slug>", "company to scan")
+        .option("--json", "print JSON")
+        .option("--hq-root <path>", "HQ installation to operate on")
+        .action(async (options) => {
+        try {
+            process.stdout.write(`${await runOntologyDuplicates(rootFor(options), options.company, options.json === true)}\n`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
     ontology
         .command("apply")
         .description("Validate the run's entity candidates and write them to the payload company")

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

@@ -0,0 +1,17 @@
+/**
+ * Alias rules shared by `apply` and the multi-writer merge-back.
+ */
+import type { EntityIndex } from "./tree.js";
+/** Longest canonical name or alias the writer accepts. */
+export declare const MAX_NAME_LENGTH = 200;
+/** The index key for a normalised name of one type. */
+export declare function entityKey(type: string, normalized: string): string;
+/**
+ * Aliases worth adding to the entity at `self`: new to it, and held by no
+ * other entity of any type, so an alias can never make a later match
+ * ambiguous. `own` holds the normalised names the entity already answers to.
+ */
+export declare function freshAliases(index: EntityIndex, type: string, self: string, own: Set<string>, names: string[]): string[];
+/** The normalised names an indexed entity answers to, plus aliases queued this run. */
+export declare function ownNames(index: EntityIndex, rel: string, queued: string[]): Set<string>;
+//# sourceMappingURL=aliases.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * Alias rules shared by `apply` and the multi-writer merge-back.
+ */
+import { canonicalizeName, isRejectedName, normalizeEntityName } from "./identity.js";
+/** Longest canonical name or alias the writer accepts. */
+export const MAX_NAME_LENGTH = 200;
+/** The index key for a normalised name of one type. */
+export function entityKey(type, normalized) {
+    return `${type}\0${normalized}`;
+}
+/**
+ * Aliases worth adding to the entity at `self`: new to it, and held by no
+ * other entity of any type, so an alias can never make a later match
+ * ambiguous. `own` holds the normalised names the entity already answers to.
+ */
+export function freshAliases(index, type, self, own, names) {
+    const seen = new Set(own);
+    const out = [];
+    for (const raw of names) {
+        const alias = canonicalizeName(raw);
+        if (!alias || alias.length > MAX_NAME_LENGTH)
+            continue;
+        const normalized = normalizeEntityName(alias, type);
+        if (!normalized || seen.has(normalized) || isRejectedName(normalized))
+            continue;
+        const holders = [
+            ...(index.canonical.get(entityKey(type, normalized)) ?? []),
+            ...(index.alias.get(entityKey(type, normalized)) ?? []),
+        ];
+        if (holders.some((holder) => holder !== self))
+            continue;
+        if ([...(index.types.get(normalized) ?? [])].some((other) => other !== type))
+            continue;
+        seen.add(normalized);
+        out.push(alias);
+    }
+    return out;
+}
+/** The normalised names an indexed entity answers to, plus aliases queued this run. */
+export function ownNames(index, rel, queued) {
+    const entity = index.byRel.get(rel);
+    return new Set([entity.canonical_name, ...entity.aliases, ...queued].map((name) => normalizeEntityName(name, entity.type)));
+}
+//# sourceMappingURL=aliases.js.map

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

@@ -5,6 +5,7 @@
  * sections 4.3, 5 and 14). The model output is untrusted input: a malformed
  * candidate is rejected and counted, never repaired.
  */
+import { type DuplicateReport, type MergeBackOutcome } from "./multi-writer.js";
 import { type CompanyBriefResult } from "./company-brief.js";
 import { type WritableEntityType } from "./identity.js";
 import { type EntityIndex } from "./tree.js";
@@ -76,6 +77,15 @@ export interface ApplyReport {
     }>;
     /** Present only when the plan ran the company brief and this apply created or updated entities. */
     company_brief?: CompanyBriefResult;
+    /** Present only when `checkpoint.ontology.multi-writer` was on for the plan (design section 20). */
+    multi_writer?: {
+        conflicts: MergeBackOutcome[];
+        /** Entity files this apply wrote and recorded in the outbox. */
+        outbox_recorded: number;
+        outbox_reset?: true;
+        error?: string;
+        duplicates?: DuplicateReport;
+    };
     duration_ms: number;
 }
 export interface ApplyOptions {

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

@@ -8,6 +8,8 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+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 { appendBackRefs, parseEntityFile, patchEntityFile, previewSignalContent, renderNewEntity, validateEntityFrontmatter, } from "./entity-file.js";
@@ -20,7 +22,7 @@ export const CAPS = {
     bytes: 200 * 1024,
     newAliasesPerEntity: 3,
     aliasesPerCandidate: 5,
-    nameLength: 200,
+    nameLength: MAX_NAME_LENGTH,
 };
 export const MIN_CREATE_CONFIDENCE = 0.7;
 export class ApplyError extends Error {
@@ -60,21 +62,18 @@ export function parseCandidate(raw) {
         evidence: typeof c.evidence === "string" ? c.evidence : "",
     };
 }
-function key(type, normalized) {
-    return `${type}\0${normalized}`;
-}
 /** Design section 5.3, tiers 1 to 4. */
 export function resolveCandidate(index, type, canonical) {
     const normalized = normalizeEntityName(canonical, type);
-    const byCanonical = [...(index.canonical.get(key(type, normalized)) ?? [])].sort();
+    const byCanonical = [...(index.canonical.get(entityKey(type, normalized)) ?? [])].sort();
     if (byCanonical.length > 0)
         return { tier: 1, target: byCanonical[0], duplicates: byCanonical.slice(1) };
-    const byAlias = [...(index.alias.get(key(type, normalized)) ?? [])].sort();
+    const byAlias = [...(index.alias.get(entityKey(type, normalized)) ?? [])].sort();
     if (byAlias.length === 1)
         return { tier: 2, target: byAlias[0] };
     if (byAlias.length > 1)
         return { tier: "ambiguous_alias", paths: byAlias };
-    const squashed = [...(index.squashed.get(key(type, squash(normalized))) ?? [])].sort();
+    const squashed = [...(index.squashed.get(entityKey(type, squash(normalized))) ?? [])].sort();
     if (squashed.length > 0)
         return { tier: "suspect_duplicate", paths: squashed };
     const otherTypes = [...(index.types.get(normalized) ?? [])].filter((other) => other !== type).sort();
@@ -95,14 +94,14 @@ export function overlappingEntities(index, type, canonical, aliases) {
         // A generic alias still counts when an existing entity already holds it.
         if (!normalized)
             continue;
-        for (const rel of index.canonical.get(key(type, normalized)) ?? [])
+        for (const rel of index.canonical.get(entityKey(type, normalized)) ?? [])
             paths.add(rel);
-        for (const rel of index.alias.get(key(type, normalized)) ?? [])
+        for (const rel of index.alias.get(entityKey(type, normalized)) ?? [])
             paths.add(rel);
     }
     if (type === "person") {
         const words = new Set(normalizeEntityName(canonical, type).split(" "));
-        const prefix = key(type, "");
+        const prefix = entityKey(type, "");
         for (const [name, rels] of index.canonical) {
             if (!name.startsWith(prefix))
                 continue;
@@ -114,39 +113,6 @@ export function overlappingEntities(index, type, canonical, aliases) {
     }
     return [...paths].sort();
 }
-/**
- * Aliases worth adding to the entity at `self`: new to it, and held by no
- * other entity of any type, so an alias can never make a later match
- * ambiguous. `own` holds the normalised names the entity already answers to.
- */
-function freshAliases(index, type, self, own, names) {
-    const seen = new Set(own);
-    const out = [];
-    for (const raw of names) {
-        const alias = canonicalizeName(raw);
-        if (!alias || alias.length > CAPS.nameLength)
-            continue;
-        const normalized = normalizeEntityName(alias, type);
-        if (!normalized || seen.has(normalized) || isRejectedName(normalized))
-            continue;
-        const holders = [
-            ...(index.canonical.get(key(type, normalized)) ?? []),
-            ...(index.alias.get(key(type, normalized)) ?? []),
-        ];
-        if (holders.some((holder) => holder !== self))
-            continue;
-        if ([...(index.types.get(normalized) ?? [])].some((other) => other !== type))
-            continue;
-        seen.add(normalized);
-        out.push(alias);
-    }
-    return out;
-}
-/** The normalised names an indexed entity answers to, plus aliases queued this run. */
-function ownNames(index, rel, queued) {
-    const entity = index.byRel.get(rel);
-    return new Set([entity.canonical_name, ...entity.aliases, ...queued].map((name) => normalizeEntityName(name, entity.type)));
-}
 function readJson(file) {
     return JSON.parse(fs.readFileSync(file, "utf8"));
 }
@@ -211,7 +177,33 @@ export function applyOntologyRun(options) {
         write_errors: [],
         duration_ms: 0,
     };
+    const outboxRels = new Set();
+    if (plan.multi_writer) {
+        report.multi_writer = {
+            conflicts: plan.multi_writer.merge_back ?? [],
+            outbox_recorded: 0,
+            ...(plan.multi_writer.error ? { error: plan.multi_writer.error } : {}),
+        };
+    }
+    // Design 20.4: the outbox entry is written before the entity file, so sync
+    // never sees a checkpoint write without one. A failed outbox write stops
+    // the entity write and leaves its inputs pending for the next run.
+    const recordBeforeWrite = (rel, content) => {
+        if (!report.multi_writer)
+            return null;
+        try {
+            if (recordOutbox(options.hqRoot, company, [{ rel, content }], options.now ?? new Date()).reset) {
+                report.multi_writer.outbox_reset = true;
+            }
+            return null;
+        }
+        catch (error) {
+            return `outbox:${error.name}`;
+        }
+    };
     const finish = () => {
+        if (report.multi_writer)
+            report.multi_writer.outbox_recorded = outboxRels.size;
         report.duration_ms = Date.now() - started;
         fs.writeFileSync(path.join(options.runDir, REPORT_FILE), `${JSON.stringify(report, null, 2)}\n`);
         return report;
@@ -377,6 +369,12 @@ export function applyOntologyRun(options) {
             blocked.add(candidate.input);
             continue;
         }
+        const createOutboxError = recordBeforeWrite(rel, content);
+        if (createOutboxError) {
+            report.write_errors.push({ path: rel, reason: createOutboxError });
+            blocked.add(candidate.input);
+            continue;
+        }
         try {
             safeWriteFile(options.hqRoot, [entityRoot], target, content);
         }
@@ -386,9 +384,11 @@ export function applyOntologyRun(options) {
             continue;
         }
         report.bytes_written += bytes;
+        if (report.multi_writer)
+            outboxRels.add(rel);
         report.created.push(rel);
         report.links.push({ input: candidate.input, action: "create", type: candidate.type, canonical_name: canonical, path: rel });
-        indexEntity(index, { ...fields, rel, slug, last_updated: now });
+        indexEntity(index, { ...fields, rel, slug, last_updated: now, first_seen: now });
     }
     applySignalRefs(company, plan, inputs, index, update);
     for (const rel of [...updates.keys()].sort()) {
@@ -423,6 +423,13 @@ export function applyOntologyRun(options) {
             report.deferred.push({ input: [...pending.inputs][0] ?? "", type: entity.type, name: entity.canonical_name, reason });
             continue;
         }
+        const patchOutboxError = recordBeforeWrite(rel, patched.content);
+        if (patchOutboxError) {
+            report.write_errors.push({ path: rel, reason: patchOutboxError });
+            for (const id of pending.inputs)
+                blocked.add(id);
+            continue;
+        }
         try {
             safeWriteFile(options.hqRoot, [entityRoot], target, patched.content);
         }
@@ -434,6 +441,8 @@ export function applyOntologyRun(options) {
         }
         report.bytes_written += bytes;
         report.backrefs_added += withRefs.added;
+        if (report.multi_writer)
+            outboxRels.add(rel);
         // An entity created earlier in this run is reported once, as created.
         if (!report.created.includes(rel))
             report.updated.push(rel);
@@ -443,6 +452,14 @@ export function applyOntologyRun(options) {
     if (plan.company_brief && report.created.length + report.updated.length > 0) {
         report.company_brief = writeCompanyBrief(options.hqRoot, company, options.now ?? new Date());
     }
+    if (report.multi_writer) {
+        try {
+            report.multi_writer.duplicates = scanDuplicates(company);
+        }
+        catch (error) {
+            report.multi_writer.error = `duplicates:${error.name}`;
+        }
+    }
     return finish();
 }
 let signalRefIndex = null;

package/dist/lib/checkpoint-ontology/entity-file.d.ts

@@ -43,6 +43,8 @@ export interface NewEntity {
 }
 /** A new entity file in the cloud schema, with a `# Name` heading. */
 export declare function renderNewEntity(entity: NewEntity): string;
+/** The frontmatter keys a checkpoint may change in an existing file. */
+export declare const OWNED_KEYS: ReadonlySet<string>;
 export interface EntityPatch {
     addAliases?: string[];
     signalCount?: number;

package/dist/lib/checkpoint-ontology/entity-file.js

@@ -111,7 +111,8 @@ export function renderNewEntity(entity) {
         "",
     ].join("\n");
 }
-const OWNED_KEYS = new Set(["aliases", "signal_count", "last_updated"]);
+/** The frontmatter keys a checkpoint may change in an existing file. */
+export const OWNED_KEYS = new Set(["aliases", "signal_count", "last_updated"]);
 /**
  * Replace one top-level key in a raw frontmatter block. The key's value may
  * span several lines (a block sequence); continuation lines are the ones that

package/dist/lib/checkpoint-ontology/multi-writer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Several checkpoint writers in one company vault (design section 20).
+ *
+ * Gated by `checkpoint.ontology.multi-writer`. Three parts:
+ *
+ * - The outbox records the exact bytes this machine's checkpoint wrote to
+ *   each entity file. Sync pushes an entity file only when it still matches
+ *   its outbox entry, so an old pulled copy is never uploaded (C1, C2).
+ * - Merge-back re-applies the monotone part of an entity version that sync
+ *   set aside after losing a push race (C3, C4). A version whose entity was
+ *   deleted stays aside (C6); one that differs in keys the checkpoint does
+ *   not own is merged for the owned keys and also stays aside (C8).
+ * - The duplicate scan reports entities of one type whose names collide, with
+ *   a proposed survivor. Nothing is deleted (C5, C7).
+ */
+import { type OntologyCompany } from "./company.js";
+import { type SignalBackRef } from "./entity-file.js";
+import { type EntityIndex } from "./tree.js";
+export declare const OUTBOX_SCHEMA = "hq-ontology-outbox.v1";
+export declare const OUTBOX_DIR = ".hq/ontology-outbox";
+export declare const OUTBOX_RETENTION_MS: number;
+/** Where sync parks a losing local body (hq-cloud `CONFLICT_BACKUPS_DIR`). */
+export declare const CONFLICT_BACKUPS_DIR = ".hq/conflict-backups";
+export declare const MERGED_BACKUPS_DIR = ".hq/conflict-backups/ontology-merged";
+export declare const STALE_BACKUP_MS: number;
+export declare const DUPLICATE_REPORT_LIMIT = 20;
+export interface OutboxEntry {
+    sha256: string;
+    written_at: string;
+}
+export interface Outbox {
+    schema: typeof OUTBOX_SCHEMA;
+    company: string;
+    entries: Record<string, OutboxEntry>;
+}
+export interface OutboxWrite {
+    /** Company-relative vault key, `ontology/entities/<type>/<file>.md`. */
+    rel: string;
+    content: string;
+}
+export declare function outboxPath(hqRoot: string, company: OntologyCompany): string;
+/** The company's outbox. A missing file is an empty outbox; an unreadable one throws. */
+export declare function readOutbox(hqRoot: string, company: OntologyCompany): Outbox;
+/**
+ * Record entity bytes this checkpoint wrote, and drop entries older than the
+ * retention window. An unreadable outbox is replaced: a lost entry only makes
+ * sync hold that file back, which is the safe direction.
+ */
+export declare function recordOutbox(hqRoot: string, company: OntologyCompany, writes: OutboxWrite[], now: Date): {
+    reset: boolean;
+};
+export type MergeBackResult = "merged" | "kept_both" | "stale" | "deleted" | "identity_conflict" | "invalid" | "write_error";
+export interface MergeBackOutcome {
+    /** HQ-relative path of the set-aside version. */
+    backup: string;
+    /** Company-relative entity file it belongs to. */
+    target: string;
+    result: MergeBackResult;
+    /** For `kept_both`, the keys that differ (`body` for prose); for `invalid` and `write_error`, the reason. */
+    detail?: string;
+}
+/** Back-reference lines in a body, as refs `appendBackRefs` can re-add. */
+export declare function readBackRefs(body: string): SignalBackRef[];
+export interface MergeBackRun {
+    outcomes: MergeBackOutcome[];
+    /** Entity files rewritten; each was recorded in the outbox before it was written. */
+    writes: OutboxWrite[];
+    outbox_reset?: true;
+}
+/**
+ * Re-apply set-aside entity versions of this company to the current files
+ * (design 20.4). Never deletes an entity file and never re-creates one.
+ */
+export declare function mergeBackConflicts(hqRoot: string, company: OntologyCompany, now: Date): MergeBackRun;
+export interface DuplicateGroup {
+    type: string;
+    /** `same_name`: equal canonical names, or one's canonical name is the other's unshared alias. `similar_name`: canonical names match once spaces are removed. */
+    reason: "same_name" | "similar_name";
+    paths: string[];
+    /** Highest `signal_count`, then earliest `first_seen`, then path. */
+    survivor: string;
+}
+export interface DuplicateReport {
+    groups: number;
+    shown: DuplicateGroup[];
+}
+/** Groups of writable entities of one type whose names collide. Read-only. */
+export declare function findDuplicateGroups(index: EntityIndex): DuplicateGroup[];
+/** The duplicate scan for a company, capped for the apply report. */
+export declare function scanDuplicates(company: OntologyCompany, limit?: number): DuplicateReport;
+export interface MultiWriterStart {
+    merge_back: MergeBackOutcome[];
+    /** Why merge-back or the outbox write stopped, when it did. */
+    error?: string;
+    outbox_reset?: true;
+}
+/**
+ * The start of a checkpoint run: merge back set-aside versions (each merged
+ * file is recorded in the outbox before it is written). Runs in `plan`, so a
+ * run with no changed inputs still merges. Errors are returned, not thrown,
+ * so the rest of the checkpoint goes on.
+ */
+export declare function startMultiWriterRun(hqRoot: string, company: OntologyCompany, now: Date): MultiWriterStart;
+/** Count merge-back outcomes by result, for one-line summaries. */
+export declare function summarizeMergeBack(outcomes: MergeBackOutcome[]): string;
+//# sourceMappingURL=multi-writer.d.ts.map

package/dist/lib/checkpoint-ontology/multi-writer.js

@@ -0,0 +1,391 @@
+/**
+ * Several checkpoint writers in one company vault (design section 20).
+ *
+ * Gated by `checkpoint.ontology.multi-writer`. Three parts:
+ *
+ * - The outbox records the exact bytes this machine's checkpoint wrote to
+ *   each entity file. Sync pushes an entity file only when it still matches
+ *   its outbox entry, so an old pulled copy is never uploaded (C1, C2).
+ * - Merge-back re-applies the monotone part of an entity version that sync
+ *   set aside after losing a push race (C3, C4). A version whose entity was
+ *   deleted stays aside (C6); one that differs in keys the checkpoint does
+ *   not own is merged for the owned keys and also stays aside (C8).
+ * - The duplicate scan reports entities of one type whose names collide, with
+ *   a proposed survivor. Nothing is deleted (C5, C7).
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { entityKey, freshAliases, ownNames } from "./aliases.js";
+import { entitiesRoot, safeWriteFile } from "./company.js";
+import { appendBackRefs, OWNED_KEYS, parseEntityFile, patchEntityFile, validateEntityFrontmatter, } from "./entity-file.js";
+import { isWritableEntityType, squash } from "./identity.js";
+import { buildEntityIndex, indexAlias } from "./tree.js";
+export const OUTBOX_SCHEMA = "hq-ontology-outbox.v1";
+export const OUTBOX_DIR = ".hq/ontology-outbox";
+export const OUTBOX_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Where sync parks a losing local body (hq-cloud `CONFLICT_BACKUPS_DIR`). */
+export const CONFLICT_BACKUPS_DIR = ".hq/conflict-backups";
+export const MERGED_BACKUPS_DIR = ".hq/conflict-backups/ontology-merged";
+export const STALE_BACKUP_MS = 7 * 24 * 60 * 60 * 1000;
+export const DUPLICATE_REPORT_LIMIT = 20;
+/**
+ * Keys that differ between two versions of a new entity for reasons that say
+ * nothing about its content. The vault's value stands and the difference is
+ * not reported.
+ */
+const IGNORED_ON_MERGE = new Set(["first_seen"]);
+/** hq-cloud `buildConflictBackupPath`: `<file>.md.<YYYY-MM-DDTHH-MM-SSZ>-<machine>.md`. */
+const BACKUP_NAME_RE = /^(.+\.md)\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z)-([a-f0-9]+|unknown)\.md$/;
+const TYPE_DIR_RE = /^[a-z][a-z0-9-]*$/;
+/** One back-reference line, as `appendBackRefs` and the gardener write it. */
+const BACKREF_LINE_RE = /^- Referenced in \[([A-Za-z_]+): (.*)\]\(([^)\s]+)\)\s*$/;
+function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+export function outboxPath(hqRoot, company) {
+    return path.join(hqRoot, ...OUTBOX_DIR.split("/"), `${company.slug}.json`);
+}
+/** The company's outbox. A missing file is an empty outbox; an unreadable one throws. */
+export function readOutbox(hqRoot, company) {
+    const empty = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+    let raw;
+    try {
+        raw = fs.readFileSync(outboxPath(hqRoot, company), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return empty;
+        throw error;
+    }
+    const doc = JSON.parse(raw);
+    if (doc.schema !== OUTBOX_SCHEMA || doc.company !== company.slug || !doc.entries || typeof doc.entries !== "object") {
+        throw new Error("outbox has an unexpected shape");
+    }
+    return { schema: OUTBOX_SCHEMA, company: company.slug, entries: doc.entries };
+}
+/**
+ * Record entity bytes this checkpoint wrote, and drop entries older than the
+ * retention window. An unreadable outbox is replaced: a lost entry only makes
+ * sync hold that file back, which is the safe direction.
+ */
+export function recordOutbox(hqRoot, company, writes, now) {
+    let outbox;
+    let reset = false;
+    try {
+        outbox = readOutbox(hqRoot, company);
+    }
+    catch {
+        outbox = { schema: OUTBOX_SCHEMA, company: company.slug, entries: {} };
+        reset = true;
+    }
+    const cutoff = now.getTime() - OUTBOX_RETENTION_MS;
+    const entries = {};
+    for (const [rel, entry] of Object.entries(outbox.entries)) {
+        const at = Date.parse(entry?.written_at ?? "");
+        if (typeof entry?.sha256 === "string" && Number.isFinite(at) && at >= cutoff)
+            entries[rel] = entry;
+    }
+    for (const write of writes)
+        entries[write.rel] = { sha256: sha256(write.content), written_at: now.toISOString() };
+    const sorted = Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+    const doc = { schema: OUTBOX_SCHEMA, company: company.slug, entries: sorted };
+    safeWriteFile(hqRoot, [path.join(hqRoot, ...OUTBOX_DIR.split("/"))], outboxPath(hqRoot, company), `${JSON.stringify(doc, null, 2)}\n`);
+    return { reset };
+}
+/** A directory that exists and is not a symlink. */
+function isRealDir(dir) {
+    try {
+        return fs.lstatSync(dir).isDirectory();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Set-aside entity versions of this company, oldest first per entity. */
+function listEntityBackups(hqRoot, company) {
+    const segments = [...CONFLICT_BACKUPS_DIR.split("/"), "companies", company.slug, "ontology", "entities"];
+    for (let i = 1; i <= segments.length; i += 1) {
+        if (!isRealDir(path.join(hqRoot, ...segments.slice(0, i))))
+            return [];
+    }
+    const root = path.join(hqRoot, ...segments);
+    const out = [];
+    for (const typeDir of fs.readdirSync(root, { withFileTypes: true })) {
+        // Other entity types (contacts, deals) belong to other writers.
+        if (!typeDir.isDirectory() || !TYPE_DIR_RE.test(typeDir.name) || !isWritableEntityType(typeDir.name))
+            continue;
+        for (const file of fs.readdirSync(path.join(root, typeDir.name), { withFileTypes: true })) {
+            const match = file.isFile() ? BACKUP_NAME_RE.exec(file.name) : null;
+            if (!match)
+                continue;
+            out.push({
+                full: path.join(root, typeDir.name, file.name),
+                hqRel: [...segments, typeDir.name, file.name].join("/"),
+                target: `ontology/entities/${typeDir.name}/${match[1]}`,
+                stampedAt: match[2],
+            });
+        }
+    }
+    return out.sort((a, b) => a.target.localeCompare(b.target) || a.stampedAt.localeCompare(b.stampedAt) || a.hqRel.localeCompare(b.hqRel));
+}
+/** The later of two ISO timestamps; an unparseable one loses. */
+function later(a, b) {
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (!Number.isFinite(ta))
+        return b;
+    if (!Number.isFinite(tb))
+        return a;
+    return tb > ta ? b : a;
+}
+/** Back-reference lines in a body, as refs `appendBackRefs` can re-add. */
+export function readBackRefs(body) {
+    const out = [];
+    for (const line of body.split(/\r?\n/)) {
+        const match = BACKREF_LINE_RE.exec(line);
+        if (match)
+            out.push({ signalType: match[1], preview: match[2], href: match[3] });
+    }
+    return out;
+}
+/** The body with back-reference lines and blank lines removed, for comparing prose. */
+function proseOf(body) {
+    return body
+        .split(/\r?\n/)
+        .filter((line) => !BACKREF_LINE_RE.test(line) && !/^##\s+Relationships\s*$/.test(line))
+        .map((line) => line.trimEnd())
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/** Keys the checkpoint does not own whose values differ, plus `body` for prose. */
+function unownedDifferences(backup, current) {
+    const keys = [...new Set([...Object.keys(backup.frontmatter), ...Object.keys(current.frontmatter)])].sort();
+    const out = keys.filter((key) => !OWNED_KEYS.has(key) && !IGNORED_ON_MERGE.has(key) && !isDeepStrictEqual(backup.frontmatter[key], current.frontmatter[key]));
+    if (proseOf(backup.body) !== proseOf(current.body))
+        out.push("body");
+    return out;
+}
+/**
+ * Re-apply set-aside entity versions of this company to the current files
+ * (design 20.4). Never deletes an entity file and never re-creates one.
+ */
+export function mergeBackConflicts(hqRoot, company, now) {
+    const run = { outcomes: [], writes: [] };
+    const backups = listEntityBackups(hqRoot, company);
+    if (backups.length === 0)
+        return run;
+    const index = buildEntityIndex(company.dir);
+    const entityRoot = entitiesRoot(company);
+    for (const backup of backups) {
+        const outcome = (result, detail) => run.outcomes.push({ backup: backup.hqRel, target: backup.target, result, ...(detail ? { detail } : {}) });
+        const saved = parseEntityFile(fs.readFileSync(backup.full, "utf8"));
+        const savedFields = saved ? validateEntityFrontmatter(saved.frontmatter) : "unparseable";
+        if (!saved || typeof savedFields === "string") {
+            outcome("invalid", `backup:${savedFields}`);
+            continue;
+        }
+        const savedUpdated = String(saved.frontmatter.last_updated);
+        const savedAt = Date.parse(savedUpdated);
+        if (!Number.isFinite(savedAt)) {
+            outcome("invalid", "backup:last_updated");
+            continue;
+        }
+        if (now.getTime() - savedAt > STALE_BACKUP_MS) {
+            outcome("stale");
+            continue;
+        }
+        const targetFull = path.join(company.dir, backup.target);
+        let targetStat;
+        try {
+            targetStat = fs.lstatSync(targetFull);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            outcome("deleted");
+            continue;
+        }
+        if (!targetStat.isFile()) {
+            outcome("invalid", "current:not_a_file");
+            continue;
+        }
+        const currentContent = fs.readFileSync(targetFull, "utf8");
+        const current = parseEntityFile(currentContent);
+        const currentFields = current ? validateEntityFrontmatter(current.frontmatter) : "unparseable";
+        if (!current || typeof currentFields === "string") {
+            outcome("invalid", `current:${currentFields}`);
+            continue;
+        }
+        if (savedFields.id !== currentFields.id || savedFields.type !== currentFields.type) {
+            outcome("identity_conflict");
+            continue;
+        }
+        if (!isWritableEntityType(currentFields.type)) {
+            outcome("invalid", "current:type_not_checkpoint_owned");
+            continue;
+        }
+        const differences = unownedDifferences(saved, current);
+        const type = currentFields.type;
+        const aliases = index.byRel.has(backup.target)
+            ? freshAliases(index, type, backup.target, ownNames(index, backup.target, []), savedFields.aliases)
+            : [];
+        const withRefs = appendBackRefs(currentContent, readBackRefs(saved.body));
+        const currentUpdated = String(current.frontmatter.last_updated);
+        const lastUpdated = later(currentUpdated, savedUpdated);
+        const patched = patchEntityFile(withRefs.content, {
+            addAliases: aliases,
+            signalCount: savedFields.signal_count,
+            lastUpdated,
+            // A later timestamp alone is a change too; otherwise the merge result
+            // would depend on which version this machine holds.
+            bodyChanged: withRefs.added > 0 || lastUpdated !== currentUpdated,
+        });
+        if (!patched.ok) {
+            outcome("write_error", patched.reason);
+            continue;
+        }
+        if (patched.changed) {
+            // Outbox first: a file sync may push must never lack its entry, and a
+            // failed outbox write leaves the file and the backup for the next run.
+            try {
+                if (recordOutbox(hqRoot, company, [{ rel: backup.target, content: patched.content }], now).reset)
+                    run.outbox_reset = true;
+            }
+            catch (error) {
+                outcome("write_error", `outbox:${error.name}`);
+                continue;
+            }
+            try {
+                safeWriteFile(hqRoot, [entityRoot], targetFull, patched.content);
+            }
+            catch (error) {
+                outcome("write_error", error.name);
+                continue;
+            }
+            run.writes = run.writes.filter((write) => write.rel !== backup.target);
+            run.writes.push({ rel: backup.target, content: patched.content });
+            for (const alias of aliases)
+                indexAlias(index, type, backup.target, alias);
+            const entity = index.byRel.get(backup.target);
+            if (entity)
+                entity.aliases = [...entity.aliases, ...aliases];
+        }
+        if (differences.length > 0) {
+            outcome("kept_both", differences.join(","));
+            continue;
+        }
+        const mergedFull = path.join(hqRoot, ...MERGED_BACKUPS_DIR.split("/"), ...backup.hqRel.split("/").slice(CONFLICT_BACKUPS_DIR.split("/").length));
+        fs.mkdirSync(path.dirname(mergedFull), { recursive: true });
+        fs.renameSync(backup.full, mergedFull);
+        outcome("merged");
+    }
+    return run;
+}
+/** Groups of writable entities of one type whose names collide. Read-only. */
+export function findDuplicateGroups(index) {
+    const parent = new Map();
+    const find = (rel) => {
+        let root = rel;
+        while (parent.get(root) !== root)
+            root = parent.get(root);
+        parent.set(rel, root);
+        return root;
+    };
+    const union = (rels) => {
+        const list = [...rels].filter((rel) => isWritableEntityType(index.byRel.get(rel)?.type));
+        for (const rel of list)
+            if (!parent.has(rel))
+                parent.set(rel, rel);
+        for (const rel of list.slice(1)) {
+            const a = find(list[0]);
+            const b = find(rel);
+            if (a !== b)
+                parent.set(b, a);
+        }
+    };
+    // Only the matches `resolveCandidate` treats as one entity link files: equal
+    // canonical names, or a canonical name that is exactly one other file's
+    // alias. An alias several files share (a Slack id, "hq") is ambiguous, not
+    // a duplicate, and following it chains unrelated entities together.
+    const exactPairs = new Set();
+    const sameName = (rels) => {
+        if (rels.length < 2)
+            return;
+        union(rels);
+        for (const rel of rels)
+            exactPairs.add(rel);
+    };
+    const squashed = new Map();
+    for (const [name, rels] of index.canonical) {
+        const holders = index.alias.get(name);
+        const aliasHolder = holders && holders.size === 1 ? [...holders] : [];
+        sameName([...new Set([...rels, ...aliasHolder])]);
+        const [type, normalized] = name.split("\0");
+        const squashKey = entityKey(type, squash(normalized));
+        squashed.set(squashKey, [...(squashed.get(squashKey) ?? []), ...rels]);
+    }
+    // Canonical names that match once spaces and punctuation are removed.
+    for (const rels of squashed.values())
+        if (rels.length > 1)
+            union(rels);
+    const groups = new Map();
+    for (const rel of parent.keys()) {
+        const root = find(rel);
+        groups.set(root, [...(groups.get(root) ?? []), rel]);
+    }
+    const out = [];
+    for (const members of groups.values()) {
+        if (members.length < 2)
+            continue;
+        const paths = members.sort();
+        const ranked = [...paths].sort((a, b) => {
+            const ea = index.byRel.get(a);
+            const eb = index.byRel.get(b);
+            const fa = Date.parse(ea.first_seen ?? "");
+            const fb = Date.parse(eb.first_seen ?? "");
+            return (eb.signal_count - ea.signal_count ||
+                (Number.isFinite(fa) ? fa : Infinity) - (Number.isFinite(fb) ? fb : Infinity) ||
+                a.localeCompare(b));
+        });
+        out.push({
+            type: index.byRel.get(paths[0]).type,
+            reason: paths.filter((rel) => exactPairs.has(rel)).length >= 2 ? "same_name" : "similar_name",
+            paths,
+            survivor: ranked[0],
+        });
+    }
+    return out.sort((a, b) => b.paths.length - a.paths.length || a.paths[0].localeCompare(b.paths[0]));
+}
+/** The duplicate scan for a company, capped for the apply report. */
+export function scanDuplicates(company, limit = DUPLICATE_REPORT_LIMIT) {
+    const groups = findDuplicateGroups(buildEntityIndex(company.dir));
+    return { groups: groups.length, shown: groups.slice(0, limit) };
+}
+/**
+ * The start of a checkpoint run: merge back set-aside versions (each merged
+ * file is recorded in the outbox before it is written). Runs in `plan`, so a
+ * run with no changed inputs still merges. Errors are returned, not thrown,
+ * so the rest of the checkpoint goes on.
+ */
+export function startMultiWriterRun(hqRoot, company, now) {
+    let merged;
+    try {
+        merged = mergeBackConflicts(hqRoot, company, now);
+    }
+    catch (error) {
+        return { merge_back: [], error: `merge_back:${error.name}` };
+    }
+    return { merge_back: merged.outcomes, ...(merged.outbox_reset ? { outbox_reset: true } : {}) };
+}
+/** Count merge-back outcomes by result, for one-line summaries. */
+export function summarizeMergeBack(outcomes) {
+    const counts = new Map();
+    for (const outcome of outcomes)
+        counts.set(outcome.result, (counts.get(outcome.result) ?? 0) + 1);
+    return [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([result, n]) => `${n} ${result.replaceAll("_", " ")}`).join(", ");
+}
+//# sourceMappingURL=multi-writer.js.map

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

@@ -9,6 +9,7 @@
  */
 import { type CompanyBriefResult } from "./company-brief.js";
 import { type OntologyCompany } from "./company.js";
+import { type MultiWriterStart } from "./multi-writer.js";
 export declare const ONTOLOGY_FLAG = "checkpoint.ontology";
 export declare const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
 export declare const COMPANY_BRIEF_FLAG = "checkpoint.ontology.company-brief";
@@ -25,6 +26,12 @@ export declare const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annot
  * state directory, so the foreground checkpoint makes no network call.
  */
 export declare const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
+/**
+ * Several writers in one company vault (design section 20): record written
+ * entity bytes in the outbox, merge back set-aside versions, and report
+ * duplicate entities.
+ */
+export declare const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
 export declare const PLAN_FILE = "ontology-plan.json";
 export declare const CANDIDATES_FILE = "ontology-candidates.json";
 export declare const REPORT_FILE = "ontology-report.json";
@@ -88,6 +95,8 @@ export interface OntologyPlan {
         status: CompanyBriefResult["status"];
         reason?: string;
     };
+    /** Present only when `checkpoint.ontology.multi-writer` was on for this plan. */
+    multi_writer?: MultiWriterStart;
     inputs: PlanInput[];
     /** The session's summary, decisions and learnings, for the `session` input. */
     session_text: string | null;
@@ -123,6 +132,7 @@ export type PlanOutcome = {
     status: "skipped";
     reason: string;
     companyBrief?: CompanyBriefResult;
+    multiWriter?: MultiWriterStart;
 } | {
     status: "planned";
     plan: OntologyPlan;

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

@@ -12,6 +12,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeCompanyBrief } from "./company-brief.js";
 import { resolveOntologyCompany, safeWriteFile, stateRoot } from "./company.js";
+import { startMultiWriterRun } from "./multi-writer.js";
 import { buildEntityIndex, listKnowledgeFiles, listSignalFiles, readSignal } from "./tree.js";
 export const ONTOLOGY_FLAG = "checkpoint.ontology";
 export const SHARED_INPUTS_FLAG = "checkpoint.ontology.shared-inputs";
@@ -29,6 +30,12 @@ export const IGNORE_ANNOTATIONS_FLAG = "checkpoint.ontology.ignore-annotations";
  * state directory, so the foreground checkpoint makes no network call.
  */
 export const GROK_BACKEND_FLAG = "checkpoint.ontology.grok-backend";
+/**
+ * Several writers in one company vault (design section 20): record written
+ * entity bytes in the outbox, merge back set-aside versions, and report
+ * duplicate entities.
+ */
+export const MULTI_WRITER_FLAG = "checkpoint.ontology.multi-writer";
 export const PLAN_FILE = "ontology-plan.json";
 export const CANDIDATES_FILE = "ontology-candidates.json";
 export const REPORT_FILE = "ontology-report.json";
@@ -212,14 +219,19 @@ export async function planOntologyRun(options) {
         return { status: "skipped", reason: "flag off" };
     }
     const sharedInputs = await options.readFlag(SHARED_INPUTS_FLAG, company);
-    // Before the ledger, so a nothing-changed plan still records the brief.
-    const companyBrief = (await options.readFlag(COMPANY_BRIEF_FLAG, company))
-        ? writeCompanyBrief(hqRoot, company, options.now ?? new Date())
-        : undefined;
+    const briefOn = await options.readFlag(COMPANY_BRIEF_FLAG, company);
     const ignoreAnnotations = (await options.readFlag(IGNORE_ANNOTATIONS_FLAG, company)) && payload.backend === "grok";
     recordBackendPreference(hqRoot, company, await options.readFlag(GROK_BACKEND_FLAG, company));
+    const multiWriterOn = await options.readFlag(MULTI_WRITER_FLAG, company);
     const touched = sessionTouched(hqRoot, company, payload.files);
+    // A first run takes its boundary from the entity tree, so the ledger is
+    // refreshed before merge-back moves any `last_updated` forward.
     const { ledger, firstRun } = refreshLedger(company, readLedger(hqRoot, company), touched, sharedInputs);
+    // Merge-back and the brief come before the nothing-changed return, so such
+    // a plan still merges set-aside versions and records the brief; the brief
+    // follows merge-back so its counts include merged entities.
+    const multiWriter = multiWriterOn ? startMultiWriterRun(hqRoot, company, options.now ?? new Date()) : undefined;
+    const companyBrief = briefOn ? writeCompanyBrief(hqRoot, company, options.now ?? new Date()) : undefined;
     const pending = Object.entries(ledger.entries)
         .filter(([, entry]) => entry.state === "pending" && (sharedInputs || entry.reason === "session-touched"))
         .sort(([aRel, a], [bRel, b]) => reasonRank(a.reason) - reasonRank(b.reason) || a.mtime_ms - b.mtime_ms || aRel.localeCompare(bRel));
@@ -268,7 +280,12 @@ export async function planOntologyRun(options) {
     writeLedger(hqRoot, company, ledger);
     if (inputs.length === 0) {
         const reason = pending.length > 0 ? "over budget" : "nothing changed";
-        return companyBrief ? { status: "skipped", reason, companyBrief } : { status: "skipped", reason };
+        return {
+            status: "skipped",
+            reason,
+            ...(companyBrief ? { companyBrief } : {}),
+            ...(multiWriter ? { multiWriter } : {}),
+        };
     }
     // Session content is scoped to the session's user (design section 6, D2).
     // v1 records the existing entities it names as links in the report and
@@ -304,6 +321,7 @@ export async function planOntologyRun(options) {
                     : { status: companyBrief.status },
             }
             : {}),
+        ...(multiWriter ? { multi_writer: multiWriter } : {}),
         inputs,
         session_text: sessionText,
         pending_after_run: remaining,

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

@@ -9,6 +9,8 @@ export interface IndexedEntity extends EntityFields {
     rel: string;
     slug: string;
     last_updated: string | null;
+    /** Absent for an entity created in this run before it was re-read. */
+    first_seen?: string | null;
 }
 export interface EntityIndex {
     byRel: Map<string, IndexedEntity>;

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

@@ -78,12 +78,13 @@ export function buildEntityIndex(companyDir) {
                 index.invalid.add(rel);
                 continue;
             }
-            const lastUpdated = parsed.frontmatter.last_updated;
+            const { last_updated: lastUpdated, first_seen: firstSeen } = parsed.frontmatter;
             indexEntity(index, {
                 ...fields,
                 rel,
                 slug: file.name.slice(0, -3),
                 last_updated: typeof lastUpdated === "string" ? lastUpdated : null,
+                first_seen: typeof firstSeen === "string" ? firstSeen : null,
             });
         }
     }

package/package.json

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