@indigoai-us/hq-cli 5.250.0 → 5.252.0

package/CHANGELOG.md

@@ -2,10 +2,18 @@
 
 ## [Unreleased]
 
+## [5.252.0] — 2026-09-27
+### Added
+
+- `hq report publish` takes a snapshot of the finished page and publishes it as the report's preview image, using a browser already installed on the computer. A page that names its own preview image keeps it. If no browser is found the report publishes without a preview.
+
+## [5.251.0] — 2026-09-27
+
 ## [5.250.0] — 2026-09-27
 
 ### Fixed
 
+- A Work Mesh session bound to a project and task keeps the binding episode the
 - An enrolled agent that sets `HQ_AGENT_DIR` now acts as that agent in every
   command, not only under `hq agent`. `hq dm` and `hq secrets` used to look
   for a person's session instead, find none, and open a browser sign-in. On
@@ -37,7 +45,6 @@
   host key is missing, instead of passing on a cached token and leaving the
   agent to fail at its next refresh.
 
-
 ## [5.249.1] — 2026-09-27
 
 ## [5.249.0] — 2026-09-27

package/dist/commands/report.js

@@ -1,4 +1,5 @@
 /** `hq report` — safe channel-report lifecycle commands for bot runbooks. */
+import { snapshotReport } from "../lib/report-snapshot.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -339,6 +340,7 @@ async function publishWithOrg(token, report, directory, draft) {
             return deployReportStatic(token, { ...input, org });
         },
         now: () => new Date().toISOString(),
+        snapshot: (source) => snapshotReport(source),
     });
     rememberReportChannelAfterSuccess(published);
     return published;

package/dist/lib/report-publish.d.ts

@@ -91,7 +91,17 @@ export interface ReportPublishDependencies {
         to: string;
         body: string;
     }): Promise<void>;
+    /**
+     * PNG of the finished page for the gallery card, or null when none can be
+     * made. It is given a staged copy of the files as they will be published. Only asked for when the page does not name its own preview image.
+     */
+    snapshot?(directory: string): Promise<Buffer | null>;
 }
+/**
+ * Add a snapshot of the page as its preview when it has none of its own.
+ * A snapshot that fails never fails the publish.
+ */
+export declare function withPreviewSnapshot(source: ReportSource, snapshot: ReportPublishDependencies["snapshot"]): Promise<ReportSource>;
 /**
  * Plain owner DM after a failed run. Suppressed for the publish lock
  * ("already running") so a second run does not page the owner.

package/dist/lib/report-publish.js

@@ -10,12 +10,55 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { gzipSync } from "node:zlib";
+import { REPORT_PREVIEW_FILE } from "./report-snapshot.js";
 import { loadUpdateReportRunbook } from "./report-templates.js";
 /** Mirrors the deploy skill's static-report guardrails. */
 export const REPORT_SOURCE_MAX_BYTES = 25 * 1024 * 1024;
 export const REPORT_BUNDLE_MAX_BYTES = 10 * 1024 * 1024;
 export const REPORT_SOURCE_MAX_FILES = 100;
 export const REPORT_CSP = "default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'none'; frame-src 'none'; form-action 'none'";
+/**
+ * Write the files exactly as they will be published, protected index.html
+ * included, so the snapshot renders under the same rules as the live page
+ * and never opens the bot's raw page.
+ */
+function stageForSnapshot(files) {
+    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-stage-"));
+    for (const file of files) {
+        const target = path.resolve(stage, file.path);
+        if (target !== stage && !target.startsWith(stage + path.sep))
+            continue;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8"));
+    }
+    return stage;
+}
+/**
+ * Add a snapshot of the page as its preview when it has none of its own.
+ * A snapshot that fails never fails the publish.
+ */
+export async function withPreviewSnapshot(source, snapshot) {
+    if (source.previewImage || !snapshot)
+        return source;
+    let image = null;
+    let stage = null;
+    try {
+        stage = stageForSnapshot(source.files);
+        image = await snapshot(stage);
+    }
+    catch {
+        image = null;
+    }
+    finally {
+        if (stage)
+            fs.rmSync(stage, { recursive: true, force: true });
+    }
+    if (!image || image.byteLength === 0)
+        return source;
+    const files = source.files.filter((file) => file.path !== REPORT_PREVIEW_FILE);
+    files.push({ path: REPORT_PREVIEW_FILE, content: image.toString("base64"), encoding: "base64" });
+    return { ...source, files, previewImage: REPORT_PREVIEW_FILE };
+}
 /**
  * Plain owner DM after a failed run. Suppressed for the publish lock
  * ("already running") so a second run does not page the owner.
@@ -277,7 +320,7 @@ export async function publishReport(report, directory, draft, deps) {
                 throw error;
             throw new ReportPublishError("Could not take the report run lock.");
         }
-        const source = loadReportSource(directory);
+        const source = await withPreviewSnapshot(loadReportSource(directory), deps.snapshot);
         const deployment = await deps.deploy({
             slug: reportDeploySlug(current, draft),
             files: source.files,

package/dist/lib/report-snapshot.d.ts

@@ -0,0 +1,14 @@
+/** File name of the snapshot inside the published report. */
+export declare const REPORT_PREVIEW_FILE = "hq-preview.png";
+export declare const REPORT_PREVIEW_WIDTH = 1280;
+export declare const REPORT_PREVIEW_HEIGHT = 720;
+/** First installed browser that can take a snapshot, or null. */
+export declare function findSnapshotBrowser(env?: NodeJS.ProcessEnv, platform?: string, exists?: (file: string) => boolean): string | null;
+export declare function snapshotArgs(indexFile: string, outFile: string, profileDir: string): string[];
+export type SnapshotRunner = (browser: string, args: string[], outFile: string, timeoutMs: number) => Promise<void>;
+/** PNG of the report's first screen, or null when one cannot be made. */
+export declare function snapshotReport(directory: string, options?: {
+    browser?: string | null;
+    run?: SnapshotRunner;
+}): Promise<Buffer | null>;
+//# sourceMappingURL=report-snapshot.d.ts.map

package/dist/lib/report-snapshot.js

@@ -0,0 +1,135 @@
+/**
+ * Report preview snapshot.
+ *
+ * Renders a report's index.html in a browser already installed on this
+ * computer and returns a PNG of the first screen. The snapshot is a nicety:
+ * every failure (no browser, timeout, empty file) returns null and the
+ * publish carries on without a preview.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+/** File name of the snapshot inside the published report. */
+export const REPORT_PREVIEW_FILE = "hq-preview.png";
+export const REPORT_PREVIEW_WIDTH = 1280;
+export const REPORT_PREVIEW_HEIGHT = 720;
+const SNAPSHOT_TIMEOUT_MS = 30_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+const BROWSER_PATHS = {
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    ],
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    ],
+};
+/** First installed browser that can take a snapshot, or null. */
+export function findSnapshotBrowser(env = process.env, platform = process.platform, exists = fs.existsSync) {
+    const override = (env.HQ_REPORT_BROWSER ?? "").trim();
+    if (override)
+        return exists(override) ? override : null;
+    return (BROWSER_PATHS[platform] ?? []).find((file) => exists(file)) ?? null;
+}
+export function snapshotArgs(indexFile, outFile, profileDir) {
+    return [
+        "--headless=new",
+        "--disable-gpu",
+        "--hide-scrollbars",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-extensions",
+        `--user-data-dir=${profileDir}`,
+        `--window-size=${REPORT_PREVIEW_WIDTH},${REPORT_PREVIEW_HEIGHT}`,
+        "--virtual-time-budget=5000",
+        `--screenshot=${outFile}`,
+        pathToFileURL(indexFile).toString(),
+    ];
+}
+function stop(child) {
+    if (child.pid === undefined)
+        return;
+    try {
+        // The browser is its own process group, so its helpers stop with it.
+        if (process.platform === "win32")
+            child.kill("SIGKILL");
+        else
+            process.kill(-child.pid, "SIGKILL");
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Some browser versions write the snapshot and then never exit. The run is
+ * done when the file is complete, so the browser is stopped at that point
+ * instead of waited on.
+ */
+const runBrowser = (browser, args, outFile, timeoutMs) => new Promise((resolve, reject) => {
+    const child = spawn(browser, args, { stdio: "ignore", detached: process.platform !== "win32" });
+    let lastSize = -1;
+    let settled = false;
+    const finish = (error) => {
+        if (settled)
+            return;
+        settled = true;
+        clearInterval(poll);
+        clearTimeout(limit);
+        stop(child);
+        if (error)
+            reject(error);
+        else
+            resolve();
+    };
+    const poll = setInterval(() => {
+        let size = 0;
+        try {
+            size = fs.statSync(outFile).size;
+        }
+        catch {
+            return;
+        }
+        if (size > 0 && size === lastSize)
+            finish();
+        lastSize = size;
+    }, 250);
+    const limit = setTimeout(() => finish(new Error("The snapshot timed out.")), timeoutMs);
+    child.once("error", (error) => finish(error));
+    child.once("exit", () => finish(fs.existsSync(outFile) ? undefined : new Error("The browser wrote no snapshot.")));
+});
+/** PNG of the report's first screen, or null when one cannot be made. */
+export async function snapshotReport(directory, options = {}) {
+    const browser = options.browser === undefined ? findSnapshotBrowser() : options.browser;
+    if (!browser)
+        return null;
+    const indexFile = path.join(path.resolve(directory), "index.html");
+    if (!fs.existsSync(indexFile))
+        return null;
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-preview-"));
+    try {
+        const outFile = path.join(work, REPORT_PREVIEW_FILE);
+        await (options.run ?? runBrowser)(browser, snapshotArgs(indexFile, outFile, path.join(work, "profile")), outFile, SNAPSHOT_TIMEOUT_MS);
+        const bytes = fs.readFileSync(outFile);
+        return bytes.subarray(0, 4).equals(PNG_MAGIC) ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=report-snapshot.js.map

package/dist/lib/work-context/outbox.js

@@ -8,7 +8,7 @@ import * as path from "node:path";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
 import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
 import { NotTrackingError } from "./errors.js";
-import { readSessionState, writeAcknowledgedRegisterBinding, } from "./state.js";
+import { readSessionState, stripRegisterReceiptEpisodes, updateSessionState, writeAcknowledgedRegisterBinding, } from "./state.js";
 import { isSafeWorkContextSegment, workContextOutboxDir, workContextOutboxPath, } from "./paths.js";
 /** Fields allowed on a durable outbox operation (privacy allowlist). */
 export const OUTBOX_ALLOWLIST = [
@@ -285,7 +285,35 @@ export function writeAckedRegisterState(op, root, receiptId, now = () => new Dat
 /** Repair older unresolved session projections from acknowledged registrations. */
 export function repairAckedRegisterStates(root, sessionIds, now = () => new Date()) {
     let repaired = 0;
-    for (const op of listOutboxOperations(root)) {
+    const operations = listOutboxOperations(root);
+    // A stored bindingEpisodeId that is a register receipt makes the server drop
+    // every batch. Clear it even when the register operation that produced it is
+    // no longer in the outbox: the id shape identifies it. This runs for every
+    // requested session, whatever its company or tracking status.
+    const receiptsBySession = new Map();
+    for (const op of operations) {
+        if (op.kind !== "register" || !op.receiptId)
+            continue;
+        const receipts = receiptsBySession.get(op.sessionId) ?? [];
+        receipts.push(op.receiptId);
+        receiptsBySession.set(op.sessionId, receipts);
+    }
+    for (const sessionId of sessionIds ?? receiptsBySession.keys()) {
+        if (!isSafeWorkContextSegment(sessionId))
+            continue;
+        const known = receiptsBySession.get(sessionId) ?? [];
+        // Take the lock only for a session that needs the repair.
+        const observed = readSessionState(sessionId, root);
+        if (!observed || stripRegisterReceiptEpisodes(observed, known) === observed)
+            continue;
+        updateSessionState(sessionId, root, (current) => {
+            if (!current)
+                return null;
+            const next = stripRegisterReceiptEpisodes(current, known);
+            return next === current ? null : next;
+        });
+    }
+    for (const op of operations) {
         if (op.delivery !== "acked" ||
             !op.receiptId ||
             op.kind !== "register" ||

package/dist/lib/work-context/reconcile.js

@@ -15,7 +15,7 @@ import { rebindNeedsProjectOnPrompt } from "./prompt-rebind.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
 import { enqueueOutbox, listOutboxOperations, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, writeAckedRegisterState, } from "./outbox.js";
-import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
+import { mergeLocalSessionFields, isRegisterReceiptEpisodeId, readSessionState, stripRegisterReceiptEpisodes, writeSessionState, } from "./state.js";
 function resultOf(parts) {
     const out = {
         contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
@@ -174,7 +174,22 @@ export async function reconcileObservation(obs, deps) {
         }
     }
     // Already untracked locally — stay untracked until explicit opt-in (no backfill).
-    const prior = readSessionState(sessionId, deps.root);
+    const observedPrior = readSessionState(sessionId, deps.root);
+    // Acked register operations for this session. A register response never
+    // carries a binding episode, so an already acknowledged binding is
+    // identified by its company / project / task, never by comparing the
+    // register receipt with the session's bindingEpisodeId.
+    const ackedRegisters = observedPrior
+        ? listOutboxOperations(deps.root).filter((operation) => operation.kind === "register" &&
+            operation.delivery === "acked" &&
+            operation.sessionId === sessionId &&
+            Boolean(operation.receiptId))
+        : [];
+    // Older clients stored a register receipt as the episode. Work from a
+    // projection with those cleared so no later write carries one forward.
+    const prior = observedPrior
+        ? stripRegisterReceiptEpisodes(observedPrior, ackedRegisters.map((operation) => operation.receiptId))
+        : observedPrior;
     if (prior?.contextStatus === "untracked" && prior.untrackedReceipt?.origin === "user") {
         return {
             result: resultOf({
@@ -690,15 +705,6 @@ export async function reconcileObservation(obs, deps) {
         registerClassification = "needs_project";
         diagnostics.push(`company rebind to ${resolvedCompany.slug ?? resolvedCompany.uid}; cleared project`);
     }
-    // Acked register operations for this session. A register that did not come
-    // back bound yields no binding episode, so its receipt (not the session's
-    // bindingEpisodeId) is what identifies an already acknowledged binding.
-    const ackedRegisters = prior
-        ? listOutboxOperations(deps.root).filter((operation) => operation.kind === "register" &&
-            operation.delivery === "acked" &&
-            operation.sessionId === sessionId &&
-            Boolean(operation.receiptId))
-        : [];
     const stateClassification = registerClassification === "unresolved" &&
         prior?.contextStatus === "needs_project" &&
         prior.companyUid === resolvedCompany.uid &&
@@ -711,22 +717,26 @@ export async function reconcileObservation(obs, deps) {
     // into a second semantic register operation: the prior receipt is the stable
     // identity for this exact company/project/task binding.
     const priorBindingIsBound = Boolean(projectId && taskId);
+    // A state that is not an acknowledged binding (for example one quarantined
+    // as company_conflict) must register again even when its fields still match.
+    const priorIsAcknowledgedBinding = prior?.contextStatus === "bound" ||
+        prior?.contextStatus === "needs_task" ||
+        prior?.contextStatus === "needs_project" ||
+        prior?.contextStatus === "unresolved";
     const acknowledgedReceipt = prior &&
+        priorIsAcknowledgedBinding &&
         prior.companyUid === resolvedCompany.uid &&
         prior.companySlug === resolvedCompany.slug &&
         prior.projectId === projectId &&
         prior.taskId === taskId
-        ? ackedRegisters.find((operation) => (priorBindingIsBound
-            ? operation.receiptId === prior.bindingEpisodeId
-            : !prior.bindingEpisodeId || operation.receiptId === prior.bindingEpisodeId) &&
-            operation.companyUid === resolvedCompany.uid &&
+        ? ackedRegisters.find((operation) => operation.companyUid === resolvedCompany.uid &&
             operation.companySlug === resolvedCompany.slug &&
             operation.projectId === projectId &&
             operation.taskId === taskId)?.receiptId
         : undefined;
     const acknowledgedPrior = acknowledgedReceipt ? prior : null;
     if (acknowledgedPrior) {
-        // A partial (not bound) acknowledged register carries no server episode.
+        // Only a bound session holds a server episode (issued by bind / organize).
         const retainedEpisodeId = priorBindingIsBound
             ? acknowledgedPrior.bindingEpisodeId
             : undefined;
@@ -895,10 +905,9 @@ export async function reconcileObservation(obs, deps) {
         // the true computed classification into durable session state; otherwise
         // the emitter and mesh presence lose the tenant the server already
         // acknowledged. projectId / taskId are written only when genuinely
-        // resolved, and a fresh bindingEpisodeId only when the session is bound —
-        // never fabricated on a partial path. (writeAckedRegisterState above may
-        // have already recorded a receipt-derived episode for a resolved partial
-        // binding; the default merge preserves that when the binding still matches.)
+        // resolved. A register ack never yields a bindingEpisodeId, bound or not:
+        // the server issues episodes only on bind / organize. The default merge
+        // keeps an episode the session already holds when the binding still matches.
         if (resolvedCompany.uid) {
             const bound = registerClassification === "bound";
             // A server ack of the company makes it authoritative: the durable status
@@ -919,7 +928,6 @@ export async function reconcileObservation(obs, deps) {
                 contextStatus: bound ? "bound" : ackedClassification,
                 ...(projectId ? { projectId } : {}),
                 ...(taskId ? { taskId } : {}),
-                ...(bound ? { bindingEpisodeId: delivered.receiptId } : {}),
                 updatedAt: nowFn().toISOString(),
                 startedAt,
                 ...(typeof toolWrites === "number" ? { toolWrites } : {}),
@@ -939,6 +947,12 @@ export async function reconcileObservation(obs, deps) {
                 : registerClassification === "needs_project"
                     ? "needs_project"
                     : "queued";
+        // Report the episode the session actually holds, never the receipt.
+        const ackedState = readSessionState(sessionId, deps.root);
+        const ackedEpisodeId = ackedState &&
+            !isRegisterReceiptEpisodeId(ackedState.bindingEpisodeId, [delivered.receiptId])
+            ? ackedState.bindingEpisodeId
+            : undefined;
         return {
             result: resultOf({
                 kind: kind === "queued" ? "queued" : kind,
@@ -950,7 +964,7 @@ export async function reconcileObservation(obs, deps) {
                 companySlug: resolvedCompany.slug,
                 projectId,
                 taskId,
-                bindingEpisodeId: delivered.receiptId,
+                ...(ackedEpisodeId ? { bindingEpisodeId: ackedEpisodeId } : {}),
                 ...bindResultFields,
             }),
             exitCode: EXIT_OK,

package/dist/lib/work-context/state.d.ts

@@ -158,6 +158,22 @@ export declare function mergeLocalSessionFields(next: SessionStateFile, prior: S
     preserveBindingEpisode?: boolean;
     preserveCompanyBinding?: boolean;
 }): SessionStateFile;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
+ */
+export declare function isRegisterReceiptEpisodeId(id: string | undefined, knownReceiptIds?: Iterable<string | undefined>): boolean;
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export declare function stripRegisterReceiptEpisodes(state: SessionStateFile, knownReceiptIds?: Iterable<string | undefined>): SessionStateFile;
 /**
  * Upgrade the local projection after the server acknowledges a register.
  *
@@ -165,6 +181,9 @@ export declare function mergeLocalSessionFields(next: SessionStateFile, prior: S
  * erase an explicit untracked choice, a conflicting existing company, or a
  * more specific binding for the same company. This is also used to repair
  * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
  */
 export declare function writeAcknowledgedRegisterBinding(binding: AcknowledgedRegisterBinding, root: string, now?: () => Date): SessionStateFile | null;
 /** True when a durable state file was written by the hook / reconcile path. */

package/dist/lib/work-context/state.js

@@ -342,6 +342,47 @@ function bindingStrength(state) {
         return 1;
     return 0;
 }
+const SERVER_EPISODE_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
+ */
+export function isRegisterReceiptEpisodeId(id, knownReceiptIds = []) {
+    if (!id)
+        return false;
+    for (const receiptId of knownReceiptIds) {
+        if (receiptId && receiptId === id)
+            return true;
+    }
+    if (SERVER_EPISODE_SHAPE.test(id))
+        return false;
+    return id.startsWith("op_");
+}
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export function stripRegisterReceiptEpisodes(state, knownReceiptIds = []) {
+    const known = [...knownReceiptIds];
+    const ownIsReceipt = isRegisterReceiptEpisodeId(state.bindingEpisodeId, known);
+    const leaveIsReceipt = isRegisterReceiptEpisodeId(state.presenceLeave?.bindingEpisodeId, known);
+    if (!ownIsReceipt && !leaveIsReceipt)
+        return state;
+    const out = { ...state };
+    if (ownIsReceipt)
+        out.bindingEpisodeId = undefined;
+    if (leaveIsReceipt && state.presenceLeave) {
+        const { bindingEpisodeId: _receipt, ...leave } = state.presenceLeave;
+        out.presenceLeave = leave;
+    }
+    return out;
+}
 /**
  * Upgrade the local projection after the server acknowledges a register.
  *
@@ -349,60 +390,68 @@ function bindingStrength(state) {
  * erase an explicit untracked choice, a conflicting existing company, or a
  * more specific binding for the same company. This is also used to repair
  * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
  */
 export function writeAcknowledgedRegisterBinding(binding, root, now = () => new Date()) {
     const acknowledged = acknowledgedStatus(binding);
     if (!acknowledged || !isSafeWorkContextSegment(binding.sessionId))
         return null;
-    const prior = readSessionState(binding.sessionId, root);
-    // Reconcile always writes the local projection before network delivery. Do
-    // not manufacture session files when replay sees an orphaned legacy outbox
-    // record with no corresponding tracked session.
-    if (!prior)
-        return null;
-    if (prior.contextStatus === "untracked" ||
-        (prior.companyUid && prior.companyUid !== binding.companyUid)) {
-        return prior;
-    }
-    const acknowledgementStrength = acknowledged === "bound" ? 3 : acknowledged === "needs_task" ? 2 : 1;
-    const priorStrength = bindingStrength(prior);
-    const preservePriorBinding = Boolean(prior.companyUid === binding.companyUid && priorStrength > acknowledgementStrength);
-    // The server issues no binding episode for a register that did not come
-    // back bound (unresolved / needs_project / needs_task). Its receipt must
-    // never stand in for one: session-event batches carry bindingEpisodeId and
-    // the server drops batches whose episode it does not recognise. Older
-    // clients stored that receipt here, so also repair a prior value that is
-    // exactly this partial register's receipt.
-    const receiptEpisode = acknowledged === "bound" ? binding.receiptId : undefined;
-    const priorEpisode = acknowledged !== "bound" && prior.bindingEpisodeId === binding.receiptId
-        ? undefined
-        : prior.bindingEpisodeId;
-    const sameBindingAsPrior = prior.companyUid === binding.companyUid &&
-        prior.projectId === binding.projectId &&
-        prior.taskId === binding.taskId;
-    const next = mergeLocalSessionFields({
-        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
-        sessionId: binding.sessionId,
-        companyUid: binding.companyUid,
-        companySlug: binding.companySlug ?? prior.companySlug,
-        contextStatus: preservePriorBinding ? prior.contextStatus : acknowledged,
-        projectId: preservePriorBinding ? prior.projectId : binding.projectId,
-        taskId: preservePriorBinding ? prior.taskId : binding.taskId,
-        bindingEpisodeId: preservePriorBinding
-            ? priorEpisode ?? receiptEpisode
-            : receiptEpisode ?? (sameBindingAsPrior ? priorEpisode : undefined),
-        updatedAt: now().toISOString(),
-    }, prior, { preserveBindingEpisode: false });
-    if (prior.companyUid === next.companyUid &&
-        prior.companySlug === next.companySlug &&
-        prior.contextStatus === next.contextStatus &&
-        prior.projectId === next.projectId &&
-        prior.taskId === next.taskId &&
-        prior.bindingEpisodeId === next.bindingEpisodeId) {
-        return prior;
-    }
-    writeSessionState(next, root);
-    return next;
+    let result = null;
+    updateSessionState(binding.sessionId, root, (current) => {
+        // Reconcile always writes the local projection before network delivery. Do
+        // not manufacture session files when replay sees an orphaned legacy outbox
+        // record with no corresponding tracked session.
+        if (!current)
+            return null;
+        // A register response never carries a server episode, bound or not. The
+        // server mints episodes only on bind / organize, and drops session-event
+        // batches whose episode it does not recognise. Older clients stored the
+        // register receipt as the episode, so clear it wherever it is found. This
+        // repair is independent of the binding decision below and therefore also
+        // applies to untracked and different-company states.
+        const prior = stripRegisterReceiptEpisodes(current, [binding.receiptId]);
+        const repaired = prior !== current;
+        if (prior.contextStatus === "untracked" ||
+            (prior.companyUid && prior.companyUid !== binding.companyUid)) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        const acknowledgementStrength = acknowledged === "bound" ? 3 : acknowledged === "needs_task" ? 2 : 1;
+        const priorStrength = bindingStrength(prior);
+        const preservePriorBinding = Boolean(prior.companyUid === binding.companyUid && priorStrength > acknowledgementStrength);
+        const sameBindingAsPrior = prior.companyUid === binding.companyUid &&
+            prior.projectId === binding.projectId &&
+            prior.taskId === binding.taskId;
+        const next = mergeLocalSessionFields({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId: binding.sessionId,
+            companyUid: binding.companyUid,
+            companySlug: binding.companySlug ?? prior.companySlug,
+            contextStatus: preservePriorBinding ? prior.contextStatus : acknowledged,
+            projectId: preservePriorBinding ? prior.projectId : binding.projectId,
+            taskId: preservePriorBinding ? prior.taskId : binding.taskId,
+            // Keep a server-issued episode only while the binding it was issued
+            // for is unchanged. Never derive one from the receipt.
+            bindingEpisodeId: preservePriorBinding || sameBindingAsPrior
+                ? prior.bindingEpisodeId
+                : undefined,
+            updatedAt: now().toISOString(),
+        }, prior, { preserveBindingEpisode: false });
+        if (prior.companyUid === next.companyUid &&
+            prior.companySlug === next.companySlug &&
+            prior.contextStatus === next.contextStatus &&
+            prior.projectId === next.projectId &&
+            prior.taskId === next.taskId &&
+            prior.bindingEpisodeId === next.bindingEpisodeId) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        result = next;
+        return next;
+    });
+    return result;
 }
 /** True when a durable state file was written by the hook / reconcile path. */
 export function isHookWrittenSessionState(state) {

package/package.json

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