@indigoai-us/hq-cli 5.169.0 → 5.171.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.171.0] — 2026-09-24
+
+### Fixed
+
+- Local bots (`hq bot run`) now restart onto an updated hq-cli install. A
+  running bot checks the installed package behind its launch path every
+  minute. When a complete, valid, different version is seen on two checks in a
+  row, it stops taking new inbox items, lets running turns finish (queued items
+  stay un-acked for the next process), logs
+  `hq-cli updated <old> -> <new>; restarting to load it`, and exits 75 so
+  launchd, systemd, or `hq daemon` starts it again. A bot with no supervisor
+  starts its own replacement first. The new process logs its version at
+  startup and whether the update converged. A restart that comes back on the
+  old version blocks that target for 6 hours, and update restarts are capped
+  at 4 per hour. `hq bot status` shows the hq-cli version a bot is running.
+  Set `HQ_BOT_NO_CLI_UPDATE_RESTART=1` to turn this off.
+
+## [5.170.0] — 2026-09-24
+
+### Fixed
+
+- Switching the HQ session company (including `hq-session.sh set company_slug`) clears the Work Mesh project and task, posts `session_end` to the previous company, and holds a personal target as `needs_company`.
+
 ## [5.169.0] — 2026-09-24
 
 ### Fixed

package/dist/commands/bot.js

@@ -25,6 +25,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  * list (online flag), and rm. Secrets are never printed.
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
+import { CLI_UPDATE_DISABLE_ENV, createCliUpdateWatcher, handOffToUpdatedCli } from "../lib/bot/cli-update.js";
 import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
 import { registerBotContinuityCommand } from "./bot-continuity.js";
@@ -743,6 +744,14 @@ async function runBotResident(nameArg) {
         // Chat attachments are fetched with the bot's own machine identity against
         // the same API its inbox and posts use (BotApi has no baseUrl override either).
         downloadAttachment: createVaultObjectDownloader({ getToken: token }),
+        // Reload onto an updated hq-cli: the watched path is the script this
+        // process was launched with, which is what its supervisor launches next.
+        ...(process.env[CLI_UPDATE_DISABLE_ENV] === "1"
+            ? {}
+            : { cliUpdate: createCliUpdateWatcher({ dir, entry: process.argv[1] ?? null }) }),
+        onCliUpdateRestart: (_update, log) => {
+            handOffToUpdatedCli(name, log, { spawnReplacement: () => spawnDetachedRun(name, dir) });
+        },
     });
     await handle.done;
     void name;
@@ -796,6 +805,8 @@ async function runBotStatus(nameArg, opts) {
     console.log(`  creds:      ${creds ? `present for ${creds.entityUid}` : chalk.red("missing")}`);
     if (status) {
         console.log(`  started:    ${status.startedAt}   restarts: ${status.restarts}   replies: ${status.repliesSent}`);
+        if (status.cliVersion)
+            console.log(`  hq-cli:     ${status.cliVersion}`);
         if (status.runtimeSignIn?.state === "expired") {
             const tool = runtimeDisplayName(status.runtimeSignIn.runtime);
             console.log(`  ${chalk.yellow(`${tool} needs to sign in again`)} — sign in from HQ, or run \`${status.runtimeSignIn.runtime} ${status.runtimeSignIn.runtime === "claude" ? "auth login" : "login"}\`, then \`hq bot restart ${name}\``);

package/dist/lib/bot/cli-update.d.ts

@@ -0,0 +1,146 @@
+/**
+ * A resident bot notices that the hq-cli install it was started from has been
+ * updated on disk, and restarts itself onto the new code.
+ *
+ * `hq bot run <name>` loads the CLI once and runs for days. The install under
+ * it moves on (the attended self-updater, the `hq daemon` updater, a manual
+ * `npm i -g`), but nothing reloaded a running bot: on 2026-09-24 the bot
+ * dr-love was still running code from 2026-09-19 while its install had moved
+ * to 5.163.0, so a shipped attachment fix never reached it.
+ *
+ * The watcher re-resolves the entry script the process was launched with
+ * (process.argv[1], the same path launchd / systemd / `hq daemon` will launch
+ * again) to its package.json on a timer. Once a complete, valid, different
+ * version is seen on consecutive checks, the run loop stops taking new inbox
+ * items, lets the running turns finish, and exits with
+ * CLI_UPDATE_RESTART_EXIT_CODE so its supervisor starts it again on the new
+ * code (or, with no supervisor, starts its own replacement first).
+ *
+ * Convergence (policy hq-self-updater-must-verify-convergence-after-install):
+ * the restart is recorded in <botDir>/cli-update.json before the exit. The next
+ * process checks the version it actually loaded against that record: a match
+ * is logged as converged; a process that came back on the OLD version blocks
+ * that target for CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS instead of restarting
+ * again. Restarts are also capped per window, so an install that keeps
+ * flipping cannot turn into a restart loop.
+ */
+import type { BotLogger } from "./log.js";
+/**
+ * Exit code for "restart me onto the updated CLI". Non-zero on purpose: every
+ * supervisor a bot runs under restarts only a failed exit — launchd
+ * KeepAlive{SuccessfulExit:false}, systemd Restart=on-failure, and the
+ * `hq daemon` "on-failure" bot units — while a clean exit 0 (a stopped or
+ * disabled bot) stays down. Same value as the daemon's RESTART_EXIT_CODE.
+ */
+export declare const CLI_UPDATE_RESTART_EXIT_CODE = 75;
+/** How often the installed package.json is read. */
+export declare const CLI_UPDATE_CHECK_INTERVAL_MS = 60000;
+/** Consecutive checks that must agree on the new version before acting. */
+export declare const CLI_UPDATE_CONFIRMATIONS = 2;
+/** At most this many update restarts per window, whatever the versions. */
+export declare const CLI_UPDATE_RESTART_LIMIT = 4;
+export declare const CLI_UPDATE_RESTART_WINDOW_MS: number;
+/** A restart that came back on the old version blocks that target this long. */
+export declare const CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS: number;
+/** Set to "1" to turn the watcher off (development runs). */
+export declare const CLI_UPDATE_DISABLE_ENV = "HQ_BOT_NO_CLI_UPDATE_RESTART";
+export declare const CLI_UPDATE_LEDGER_FILE = "cli-update.json";
+export type InstalledCliRead = {
+    ok: true;
+    version: string;
+    packageRoot: string;
+} | {
+    ok: false;
+    reason: string;
+    packageRoot?: string;
+};
+export interface InstalledCliFs {
+    realpathSync(p: string): string;
+    readFileSync(p: string, encoding: "utf8"): string;
+}
+/**
+ * The hq-cli version installed behind `entry`, resolved the way the next launch
+ * of the same command line will resolve it: follow the symlinks now (a pnpm or
+ * versioned layout moves the link, npm rewrites the directory in place), then
+ * walk up to the package.json that names this CLI. Anything short of a
+ * readable manifest with a valid semver version is not a version.
+ */
+export declare function readInstalledCli(entry: string, io?: InstalledCliFs): InstalledCliRead;
+export interface CliUpdate {
+    from: string;
+    to: string;
+    packageRoot: string;
+}
+interface CliUpdateLedger {
+    v: 1;
+    /** Written just before an update restart; settled by the next process. */
+    pending?: {
+        from: string;
+        to: string;
+        at: string;
+    };
+    /** ISO times of recent update restarts (for the per-window cap). */
+    restarts: string[];
+    /** A target that did not converge, and when it may be tried again. */
+    blocked?: {
+        version: string;
+        until: string;
+    };
+}
+export declare function readCliUpdateLedger(dir: string): CliUpdateLedger;
+/** What the run loop needs from the watcher (injectable in tests). */
+export interface CliUpdateWatch {
+    /** The version of the code this process loaded. */
+    readonly runningVersion: string;
+    /** Settle the previous restart (converged or not) and say what is watched. */
+    startup(log: BotLogger): void;
+    /** A confirmed update to restart onto, or null. Cheap; rate-limits itself. */
+    poll(log: BotLogger): CliUpdate | null;
+    /** Record the restart about to happen, before the process exits. */
+    recordRestart(update: CliUpdate): void;
+}
+export interface CliUpdateWatcherOptions {
+    dir: string;
+    /** The script this process was launched with (process.argv[1]); null = do not watch. */
+    entry: string | null;
+    runningVersion?: string;
+    now?: () => number;
+    read?: (entry: string) => InstalledCliRead;
+    /** True while an installer is provably rewriting the package dir. */
+    rewriteInProgress?: (packageRoot: string) => boolean;
+    checkIntervalMs?: number;
+    confirmations?: number;
+    restartLimit?: number;
+    restartWindowMs?: number;
+    cooldownMs?: number;
+}
+export declare function createCliUpdateWatcher(opts: CliUpdateWatcherOptions): CliUpdateWatch;
+/**
+ * Who starts this bot again after it exits.
+ *
+ * - "hq-daemon": `hq daemon` sets HQ_DAEMON_UNIT=bots:<name> on its children;
+ *   the unit is "on-failure" (supervisor.ts).
+ * - "launchd": launchd sets XPC_SERVICE_NAME to the job label for every job it
+ *   spawns, including LaunchAgents installed before this code existed.
+ * - "systemd": the unit `hq-bot-<name>.service` shows up in the process cgroup.
+ * - "none": `hq bot start` without a service (Windows, --no-daemon, a Linux
+ *   unit never enabled) or a foreground run. Nobody restarts this process.
+ */
+export type BotSupervisor = "hq-daemon" | "launchd" | "systemd" | "none";
+export declare function detectBotSupervisor(name: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    readCgroup?: () => string | null;
+}): BotSupervisor;
+/**
+ * The last step of an update restart, run after the pid lock is released and
+ * just before the exit. A supervised bot only has to exit; an unsupervised one
+ * starts its replacement on the same entry script (now the new code) first,
+ * because nothing else will.
+ */
+export declare function handOffToUpdatedCli(name: string, log: BotLogger, deps: {
+    supervisor?: BotSupervisor;
+    spawnReplacement: () => number;
+}): BotSupervisor;
+export {};
+//# sourceMappingURL=cli-update.d.ts.map

package/dist/lib/bot/cli-update.js

@@ -0,0 +1,278 @@
+/**
+ * A resident bot notices that the hq-cli install it was started from has been
+ * updated on disk, and restarts itself onto the new code.
+ *
+ * `hq bot run <name>` loads the CLI once and runs for days. The install under
+ * it moves on (the attended self-updater, the `hq daemon` updater, a manual
+ * `npm i -g`), but nothing reloaded a running bot: on 2026-09-24 the bot
+ * dr-love was still running code from 2026-09-19 while its install had moved
+ * to 5.163.0, so a shipped attachment fix never reached it.
+ *
+ * The watcher re-resolves the entry script the process was launched with
+ * (process.argv[1], the same path launchd / systemd / `hq daemon` will launch
+ * again) to its package.json on a timer. Once a complete, valid, different
+ * version is seen on consecutive checks, the run loop stops taking new inbox
+ * items, lets the running turns finish, and exits with
+ * CLI_UPDATE_RESTART_EXIT_CODE so its supervisor starts it again on the new
+ * code (or, with no supervisor, starts its own replacement first).
+ *
+ * Convergence (policy hq-self-updater-must-verify-convergence-after-install):
+ * the restart is recorded in <botDir>/cli-update.json before the exit. The next
+ * process checks the version it actually loaded against that record: a match
+ * is logged as converged; a process that came back on the OLD version blocks
+ * that target for CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS instead of restarting
+ * again. Restarts are also capped per window, so an install that keeps
+ * flipping cannot turn into a restart loop.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import semver from "semver";
+import { CLI_NAME, CLI_VERSION } from "../../cli-version.js";
+import { installRewriteInProgress } from "../../utils/install-tree-torn.js";
+import { updateLockPath } from "../../utils/update-lock.js";
+import { launchdLabel } from "./paths.js";
+/**
+ * Exit code for "restart me onto the updated CLI". Non-zero on purpose: every
+ * supervisor a bot runs under restarts only a failed exit — launchd
+ * KeepAlive{SuccessfulExit:false}, systemd Restart=on-failure, and the
+ * `hq daemon` "on-failure" bot units — while a clean exit 0 (a stopped or
+ * disabled bot) stays down. Same value as the daemon's RESTART_EXIT_CODE.
+ */
+export const CLI_UPDATE_RESTART_EXIT_CODE = 75;
+/** How often the installed package.json is read. */
+export const CLI_UPDATE_CHECK_INTERVAL_MS = 60_000;
+/** Consecutive checks that must agree on the new version before acting. */
+export const CLI_UPDATE_CONFIRMATIONS = 2;
+/** At most this many update restarts per window, whatever the versions. */
+export const CLI_UPDATE_RESTART_LIMIT = 4;
+export const CLI_UPDATE_RESTART_WINDOW_MS = 60 * 60_000;
+/** A restart that came back on the old version blocks that target this long. */
+export const CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS = 6 * 60 * 60_000;
+/** Set to "1" to turn the watcher off (development runs). */
+export const CLI_UPDATE_DISABLE_ENV = "HQ_BOT_NO_CLI_UPDATE_RESTART";
+export const CLI_UPDATE_LEDGER_FILE = "cli-update.json";
+/**
+ * The hq-cli version installed behind `entry`, resolved the way the next launch
+ * of the same command line will resolve it: follow the symlinks now (a pnpm or
+ * versioned layout moves the link, npm rewrites the directory in place), then
+ * walk up to the package.json that names this CLI. Anything short of a
+ * readable manifest with a valid semver version is not a version.
+ */
+export function readInstalledCli(entry, io = fs) {
+    let real;
+    try {
+        real = io.realpathSync(entry);
+    }
+    catch {
+        return { ok: false, reason: `${entry} does not resolve` };
+    }
+    let dir = path.dirname(real);
+    for (let i = 0; i < 8; i++) {
+        const manifest = path.join(dir, "package.json");
+        let raw;
+        try {
+            raw = io.readFileSync(manifest, "utf8");
+        }
+        catch {
+            raw = null;
+        }
+        if (raw !== null) {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return { ok: false, reason: `${manifest} is not valid JSON`, packageRoot: dir };
+            }
+            if (parsed.name === CLI_NAME) {
+                const version = typeof parsed.version === "string" ? semver.valid(parsed.version) : null;
+                if (!version)
+                    return { ok: false, reason: `${manifest} has no valid version`, packageRoot: dir };
+                return { ok: true, version, packageRoot: dir };
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { ok: false, reason: `no ${CLI_NAME} package.json above ${real}` };
+}
+function ledgerPath(dir) {
+    return path.join(dir, CLI_UPDATE_LEDGER_FILE);
+}
+export function readCliUpdateLedger(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(ledgerPath(dir), "utf8"));
+        return {
+            v: 1,
+            restarts: Array.isArray(raw.restarts) ? raw.restarts.filter((s) => typeof s === "string") : [],
+            ...(raw.pending && typeof raw.pending.from === "string" && typeof raw.pending.to === "string" ? { pending: raw.pending } : {}),
+            ...(raw.blocked && typeof raw.blocked.version === "string" && typeof raw.blocked.until === "string" ? { blocked: raw.blocked } : {}),
+        };
+    }
+    catch {
+        return { v: 1, restarts: [] };
+    }
+}
+function writeCliUpdateLedger(dir, ledger) {
+    const target = ledgerPath(dir);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(tmp, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, target);
+}
+export function createCliUpdateWatcher(opts) {
+    const runningVersion = opts.runningVersion ?? CLI_VERSION;
+    const now = opts.now ?? Date.now;
+    const read = opts.read ?? ((entry) => readInstalledCli(entry));
+    const rewriteInProgress = opts.rewriteInProgress ?? ((packageRoot) => installRewriteInProgress({ packageRoot, lockPath: updateLockPath() }));
+    const checkIntervalMs = opts.checkIntervalMs ?? CLI_UPDATE_CHECK_INTERVAL_MS;
+    const confirmations = Math.max(1, opts.confirmations ?? CLI_UPDATE_CONFIRMATIONS);
+    const restartLimit = Math.max(1, opts.restartLimit ?? CLI_UPDATE_RESTART_LIMIT);
+    const restartWindowMs = opts.restartWindowMs ?? CLI_UPDATE_RESTART_WINDOW_MS;
+    const cooldownMs = opts.cooldownMs ?? CLI_UPDATE_NOT_CONVERGED_COOLDOWN_MS;
+    const { dir, entry } = opts;
+    let nextCheckAt = now() + checkIntervalMs;
+    let candidate = null;
+    let seen = 0;
+    /** Last "why not" line, so a condition that persists is logged once. */
+    let lastNote = null;
+    const note = (log, level, message) => {
+        if (message === lastNote)
+            return;
+        lastNote = message;
+        log(level, message);
+    };
+    const recentRestarts = (ledger, at) => ledger.restarts.filter((iso) => {
+        const t = Date.parse(iso);
+        return Number.isFinite(t) && at - t < restartWindowMs;
+    });
+    return {
+        runningVersion,
+        startup(log) {
+            if (!entry) {
+                log("info", "not watching for hq-cli updates (no entry script)");
+                return;
+            }
+            const ledger = readCliUpdateLedger(dir);
+            const pending = ledger.pending;
+            if (pending) {
+                delete ledger.pending;
+                if (runningVersion === pending.to) {
+                    log("info", `hq-cli update converged: now running ${runningVersion} (was ${pending.from})`);
+                    if (ledger.blocked?.version === runningVersion)
+                        delete ledger.blocked;
+                }
+                else if (runningVersion === pending.from) {
+                    const until = new Date(now() + cooldownMs).toISOString();
+                    ledger.blocked = { version: pending.to, until };
+                    log("error", `restarted to load hq-cli ${pending.to} but this process still loaded ${runningVersion}; ` +
+                        `not restarting for ${pending.to} again until ${until} (check which install ${entry} resolves to)`);
+                }
+                else {
+                    log("info", `restarted for hq-cli ${pending.to}; now running ${runningVersion}`);
+                }
+                try {
+                    writeCliUpdateLedger(dir, ledger);
+                }
+                catch (err) {
+                    log("warn", `could not update ${CLI_UPDATE_LEDGER_FILE}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            log("info", `watching ${entry} for hq-cli updates (running ${runningVersion})`);
+        },
+        poll(log) {
+            if (!entry)
+                return null;
+            const at = now();
+            if (at < nextCheckAt)
+                return null;
+            nextCheckAt = at + checkIntervalMs;
+            const installed = read(entry);
+            if (!installed.ok) {
+                candidate = null;
+                seen = 0;
+                note(log, "warn", `hq-cli install not readable, not restarting: ${installed.reason}`);
+                return null;
+            }
+            if (installed.version === runningVersion) {
+                candidate = null;
+                seen = 0;
+                lastNote = null;
+                return null;
+            }
+            if (rewriteInProgress(installed.packageRoot)) {
+                candidate = null;
+                seen = 0;
+                note(log, "info", `hq-cli ${installed.version} is still being installed; waiting for it to finish`);
+                return null;
+            }
+            if (candidate === installed.version)
+                seen += 1;
+            else {
+                candidate = installed.version;
+                seen = 1;
+            }
+            if (seen < confirmations) {
+                note(log, "info", `hq-cli ${installed.version} is installed (running ${runningVersion}); confirming before restarting`);
+                return null;
+            }
+            const ledger = readCliUpdateLedger(dir);
+            if (ledger.blocked?.version === installed.version && at < Date.parse(ledger.blocked.until)) {
+                note(log, "warn", `not restarting for hq-cli ${installed.version}: an earlier restart for it did not load it (retry after ${ledger.blocked.until})`);
+                return null;
+            }
+            if (recentRestarts(ledger, at).length >= restartLimit) {
+                note(log, "warn", `not restarting for hq-cli ${installed.version}: already restarted ${restartLimit} times for updates in the last ${Math.round(restartWindowMs / 60_000)} minutes`);
+                return null;
+            }
+            return { from: runningVersion, to: installed.version, packageRoot: installed.packageRoot };
+        },
+        recordRestart(update) {
+            const at = now();
+            const ledger = readCliUpdateLedger(dir);
+            ledger.restarts = [...recentRestarts(ledger, at), new Date(at).toISOString()];
+            ledger.pending = { from: update.from, to: update.to, at: new Date(at).toISOString() };
+            writeCliUpdateLedger(dir, ledger);
+        },
+    };
+}
+export function detectBotSupervisor(name, opts = {}) {
+    const env = opts.env ?? process.env;
+    const platform = opts.platform ?? process.platform;
+    if (env.HQ_DAEMON_UNIT === `bots:${name}`)
+        return "hq-daemon";
+    if (platform === "darwin" && env.XPC_SERVICE_NAME === launchdLabel(name))
+        return "launchd";
+    if (platform === "linux") {
+        const readCgroup = opts.readCgroup ??
+            (() => {
+                try {
+                    return fs.readFileSync("/proc/self/cgroup", "utf8");
+                }
+                catch {
+                    return null;
+                }
+            });
+        if (readCgroup()?.includes(`/hq-bot-${name}.service`))
+            return "systemd";
+    }
+    return "none";
+}
+/**
+ * The last step of an update restart, run after the pid lock is released and
+ * just before the exit. A supervised bot only has to exit; an unsupervised one
+ * starts its replacement on the same entry script (now the new code) first,
+ * because nothing else will.
+ */
+export function handOffToUpdatedCli(name, log, deps) {
+    const supervisor = deps.supervisor ?? detectBotSupervisor(name);
+    if (supervisor !== "none") {
+        log("info", `exiting for ${supervisor} to start the updated hq-cli`);
+        return supervisor;
+    }
+    log("info", `no supervisor; started replacement pid ${deps.spawnReplacement()}`);
+    return supervisor;
+}
+//# sourceMappingURL=cli-update.js.map

package/dist/lib/bot/run.d.ts

@@ -53,6 +53,7 @@ import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "
 import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
+import { type CliUpdate, type CliUpdateWatch } from "./cli-update.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
 export declare const HEARTBEAT_INTERVAL_MS = 30000;
 /** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
@@ -150,6 +151,17 @@ export interface BotRunDeps {
     agentUidSource?: HeartbeatAgentUidSource;
     credsSource?: HeartbeatCredsSource;
     reportIdentityMismatch?: HeartbeatIdentityMismatchReporter;
+    /**
+     * Watches the hq-cli install this process was started from (cli-update.ts).
+     * When it reports an update, the bot stops taking inbox items, lets running
+     * turns finish, and exits CLI_UPDATE_RESTART_EXIT_CODE. Unset = no watch.
+     */
+    cliUpdate?: CliUpdateWatch;
+    /**
+     * Called after the pid lock is released and just before the update-restart
+     * exit: the place to start a replacement when no supervisor will.
+     */
+    onCliUpdateRestart?: (update: CliUpdate, log: BotLogger) => void;
 }
 export declare const KICKOFF_MESSAGE_ID = "kickoff";
 /**

package/dist/lib/bot/run.js

@@ -74,6 +74,8 @@ import { HQ_BOT_AGENT_UID_ENV } from "../../commands/onboard-bot-membership.js";
 import { captureHeartbeatIdentityMismatch, identityMismatchMessage, isHeartbeatIdentityMismatch, } from "../heartbeat-identity.js";
 import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
+import { CLI_VERSION } from "../../cli-version.js";
+import { CLI_UPDATE_RESTART_EXIT_CODE } from "./cli-update.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
 export const HEARTBEAT_INTERVAL_MS = 30_000;
 /** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
@@ -285,7 +287,7 @@ export async function runBot(deps) {
         pid,
         ...(deps.isProcessAlive ? { isProcessAlive: deps.isProcessAlive } : {}),
     });
-    const finish = async (final, code, reason) => {
+    const finish = async (final, code, reason, beforeExit) => {
         if (state === "stopped" || state === "failed")
             return;
         state = final;
@@ -293,9 +295,18 @@ export async function runBot(deps) {
         log(final === "failed" ? "error" : "info", `bot ${final}: ${reason}`);
         if (!deps.skipPidLock)
             releasePidLock(dir, lockDeps);
+        try {
+            beforeExit?.();
+        }
+        catch (err) {
+            log("error", `before exit: ${err instanceof Error ? err.message : String(err)}`);
+        }
         resolveDone(final);
         exit(code);
     };
+    const cliVersion = deps.cliUpdate?.runningVersion ?? CLI_VERSION;
+    /** Set once an update restart is due: no new turns, then exit for the supervisor. */
+    let cliUpdatePending = null;
     // ── Preflight: creds, pid lock, owner verification ─────────────────────────
     const credsProblem = preflightCreds(dir, config);
     if (credsProblem) {
@@ -327,8 +338,9 @@ export async function runBot(deps) {
         return { stop: async () => { }, done, status: () => null, idle: () => true };
     }
     // A restart is the owner's "try again" after signing in: start clean.
-    setStatus({ ...fallback(), pid, state: "starting", canDrainForPromotion: false, runtimeSignIn: null });
-    log("info", `starting ${config.name} (${config.runtime}, ${kind} bot${companies.length ? ` of ${companies.join(", ")}` : ""}) as ${config.agentUid} for ${config.ownerUid}`);
+    setStatus({ ...fallback(), pid, state: "starting", canDrainForPromotion: false, runtimeSignIn: null, cliVersion });
+    log("info", `starting ${config.name} on hq-cli ${cliVersion} (${config.runtime}, ${kind} bot${companies.length ? ` of ${companies.join(", ")}` : ""}) as ${config.agentUid} for ${config.ownerUid}`);
+    deps.cliUpdate?.startup(log);
     try {
         const record = await api.getAgent(config.agentUid);
         // Promotion keeps the identity and owner. Ownership alone must not let
@@ -1476,6 +1488,17 @@ export async function runBot(deps) {
         while (!stopping && state === "running") {
             if (hasPromotionHold(dir))
                 break;
+            // The install under this process was updated: take nothing new, let the
+            // turns already running finish, then exit so the supervisor loads it.
+            // Queued items were never started or acked; the next process gets them.
+            const update = deps.cliUpdate?.poll(log) ?? null;
+            if (update) {
+                cliUpdatePending = update;
+                stopping = true;
+                const busy = running.size;
+                log("info", `hq-cli updated ${update.from} -> ${update.to}; restarting to load it${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
+                break;
+            }
             // A kickoff held for a sign-in retries on the same timer as messages.
             if (busyLanes.size === 0 &&
                 (!signInIssue || now().getTime() >= nextSignInRetryAt) &&
@@ -1525,6 +1548,9 @@ export async function runBot(deps) {
         return readBotStatus(dir);
     }
     const stop = async (mode = "abort") => {
+        // An owner stop or a promotion while an update restart drains wins: the
+        // bot then exits 0 and stays down instead of being restarted.
+        cliUpdatePending = null;
         if (stopping) {
             if (mode === "abort")
                 for (const turn of currentTurns)
@@ -1552,8 +1578,20 @@ export async function runBot(deps) {
         void stop("drain"); });
     setStatus({ canDrainForPromotion: true });
     void Promise.allSettled([heartbeatLoop, inboxLoop]).then(() => {
-        if (state === "running")
+        if (state !== "running")
+            return;
+        const update = cliUpdatePending;
+        if (!update) {
             void finish("stopped", 0, "loops ended");
+            return;
+        }
+        try {
+            deps.cliUpdate?.recordRestart(update);
+        }
+        catch (err) {
+            log("warn", `could not record the update restart: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        void finish("stopped", CLI_UPDATE_RESTART_EXIT_CODE, `hq-cli updated ${update.from} -> ${update.to}; restarting to load it`, () => deps.onCliUpdateRestart?.(update, log));
     });
     return { stop, done, status: readStatus, idle: () => pending.size === 0 };
 }

package/dist/lib/bot/status.d.ts

@@ -44,6 +44,8 @@ export interface BotStatusFile {
      * reason); cleared by the next turn that works. `null` = known to work.
      */
     runtimeSignIn?: RuntimeSignInIssue | null;
+    /** hq-cli version this process loaded (a bot keeps it until it restarts). */
+    cliVersion?: string;
     updatedAt: string;
 }
 export declare function defaultBotStatus(pid: number, runtime: BotRuntimeId, now?: () => Date): BotStatusFile;

package/dist/lib/mesh/live/flush.js

@@ -10,10 +10,12 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveCompany } from "../../work-context/company.js";
+import { readMetaCompanySlug, resolveCompany } from "../../work-context/company.js";
+import { companyBindingChanged, reboundSessionProjection, } from "../../work-context/company-rebind.js";
 import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../../work-context/repo-remote.js";
 import { rebindNeedsProjectOnPrompt } from "../../work-context/prompt-rebind.js";
-import { readSessionState, updateSessionState } from "../../work-context/state.js";
+import { readSessionState, updateSessionState, writeSessionState } from "../../work-context/state.js";
+import { generateUlid } from "./ulid.js";
 import { repairAckedRegisterStates } from "../../work-context/outbox.js";
 import { workContextRoot } from "../../work-context/paths.js";
 import { defaultSleep, FLUSH_MAX_ATTEMPTS, fullJitterDelayMs, } from "./backoff.js";
@@ -252,6 +254,23 @@ export async function flushSessionEvents(deps) {
             if (deps.signal?.aborted)
                 break sessionLoop;
             let state = readSessionState(sessionId, deps.workContextRoot);
+            state = applySessionMetaCompanyRebind(sessionId, items, state, deps, now);
+            const leaveResult = await postPresenceLeaveIfNeeded({
+                sessionId,
+                items,
+                state,
+                deps,
+                now,
+                maxAttempts,
+                sleep,
+                random,
+                summary,
+                markDisposed,
+            });
+            state = leaveResult.state;
+            if (leaveResult.abort)
+                continue;
+            const remainingItems = leaveResult.items;
             if (state?.companyConfidence === "device_default" &&
                 deps.authorizeDeviceDefaultTenant) {
                 const allowed = await deps.authorizeDeviceDefaultTenant(state);
@@ -259,7 +278,7 @@ export async function flushSessionEvents(deps) {
                 state = readSessionState(sessionId, deps.workContextRoot) ?? state;
                 if (!allowed) {
                     const heldAt = now().toISOString();
-                    for (const item of items) {
+                    for (const item of remainingItems) {
                         appendHeldLine(heldEnvelope(item.event, "NEEDS_COMPANY", item.heldAt ?? heldAt), deps.workMeshRoot);
                         summary.held += 1;
                         markDisposed(item.event);
@@ -269,33 +288,34 @@ export async function flushSessionEvents(deps) {
             }
             // After the company gate (which may restore a cleared company), try to
             // bind a needs_project session to an existing Board before classifying.
-            state = rebindUnboundSession(sessionId, items, state, deps, nowMs);
+            state = rebindUnboundSession(sessionId, remainingItems, state, deps, nowMs);
             const decision = classifySession(state);
             if (decision.action === "drop") {
                 appendDroppedReceipt({
                     v: 1,
                     sessionId,
-                    dropped: items.length,
+                    dropped: remainingItems.length,
                     reason: "untracked",
                     at: now().toISOString(),
                 }, deps.workMeshRoot);
-                summary.dropped += items.length;
-                for (const item of items)
+                summary.dropped += remainingItems.length;
+                for (const item of remainingItems)
                     markDisposed(item.event);
                 continue;
             }
             if (decision.action === "hold") {
                 const heldAt = now().toISOString();
-                for (const item of items) {
+                for (const item of remainingItems) {
                     appendHeldLine(heldEnvelope(item.event, decision.heldReason, item.heldAt ?? heldAt), deps.workMeshRoot);
                     summary.held += 1;
                     markDisposed(item.event);
                 }
                 continue;
             }
-            // Post a bounded portion of this session's backlog. Untouched events
-            // remain in pendingRestore and are put back on the spool below.
-            const flushItems = items.slice(0, SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH);
+            // Post a bounded portion of this session's remaining backlog (after any
+            // presence-leave). Untouched events stay in pendingRestore and are put
+            // back on the spool below.
+            const flushItems = remainingItems.slice(0, SESSION_EVENTS_MAX_PER_SESSION_PER_FLUSH);
             const stripped = flushItems.map((item) => stripLocalOnlyFields(item.event));
             for (let i = 0; i < stripped.length; i += SESSION_EVENTS_BATCH_MAX) {
                 const chunk = stripped.slice(i, i + SESSION_EVENTS_BATCH_MAX);
@@ -547,6 +567,135 @@ function eventText(event, key) {
     const value = event[key];
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+const SESSION_EVENT_HARNESSES = new Set([
+    "claude-code",
+    "claude-desktop",
+    "codex",
+    "grok",
+    "hq-sessions",
+    "agent-box",
+    "agents-v2",
+]);
+function applySessionMetaCompanyRebind(sessionId, items, state, deps, now) {
+    if (!state)
+        return state;
+    const hqRoot = items.map((item) => eventText(item.event, "hqRoot")).find(Boolean);
+    if (!hqRoot)
+        return state;
+    const meta = readMetaCompanySlug(sessionId, hqRoot);
+    if (!meta)
+        return state;
+    if (!companyBindingChanged(state, { slug: meta }))
+        return state;
+    const next = reboundSessionProjection({
+        prior: state,
+        sessionId,
+        nextSlug: meta,
+        nowIso: now().toISOString(),
+    });
+    writeSessionState(next, deps.workContextRoot);
+    return readSessionState(sessionId, deps.workContextRoot) ?? next;
+}
+function leaveContextStatus(leave) {
+    if (leave.projectId && leave.taskId)
+        return "bound";
+    if (leave.projectId)
+        return "needs_task";
+    return "needs_project";
+}
+function synthesizeSessionEnd(sessionId, sample, seq, at) {
+    const harnessRaw = eventText(sample, "harness");
+    const harness = harnessRaw && SESSION_EVENT_HARNESSES.has(harnessRaw)
+        ? harnessRaw
+        : "claude-code";
+    return stripLocalOnlyFields({
+        v: 1,
+        eventId: generateUlid(),
+        kind: "session_end",
+        sessionId,
+        harness,
+        adapterVersion: eventText(sample, "adapterVersion") || "1.0.0",
+        at,
+        seq,
+    });
+}
+async function postPresenceLeaveIfNeeded(input) {
+    const leave = input.state?.presenceLeave;
+    if (!leave?.companyUid) {
+        return { state: input.state, items: input.items, abort: false };
+    }
+    const oldSlug = leave.companySlug?.trim().toLowerCase();
+    const leaveItems = oldSlug
+        ? input.items.filter((item) => {
+            const slug = eventText(item.event, "companySlug")?.toLowerCase();
+            return slug === oldSlug;
+        })
+        : [];
+    const remaining = input.items.filter((item) => !leaveItems.includes(item));
+    const sample = leaveItems[0]?.event ?? input.items[0]?.event ?? {};
+    const maxSeq = input.items.reduce((max, item) => {
+        const seq = item.event.seq;
+        return typeof seq === "number" && Number.isFinite(seq) ? Math.max(max, seq) : max;
+    }, 0);
+    const sessionEnd = synthesizeSessionEnd(input.sessionId, sample, maxSeq + 1, input.now().toISOString());
+    const events = [
+        ...leaveItems.map((item) => stripLocalOnlyFields(item.event)),
+        sessionEnd,
+    ];
+    const body = {
+        contractVersion: 1,
+        companyUid: leave.companyUid,
+        sessionId: input.sessionId,
+        contextStatus: leaveContextStatus(leave),
+        events,
+    };
+    if (leave.bindingEpisodeId)
+        body.bindingEpisodeId = leave.bindingEpisodeId;
+    if (leave.projectId)
+        body.projectId = leave.projectId;
+    if (leave.taskId)
+        body.taskId = leave.taskId;
+    input.summary.batches += 1;
+    const result = await postBatchWithRetries(input.deps.poster, body, {
+        maxAttempts: input.maxAttempts,
+        sleep: input.sleep,
+        random: input.random,
+        signal: input.deps.signal,
+    });
+    if (!result.ok) {
+        const at = input.now().toISOString();
+        if (!result.retryable) {
+            for (const item of input.items) {
+                appendDeadLetterLine(deadLetterEnvelope(item.event, `HTTP_${result.status}`, result.status, at), input.deps.workMeshRoot);
+                input.summary.deadLettered += 1;
+                input.markDisposed(item.event);
+            }
+            return { state: input.state, items: [], abort: true };
+        }
+        for (const item of input.items) {
+            appendSpoolLine(JSON.stringify(canonicalizeForRestore(item.event)), input.deps.workMeshRoot);
+            input.summary.restored += 1;
+            input.markDisposed(item.event);
+        }
+        return { state: input.state, items: [], abort: true };
+    }
+    accountBatchSuccess({
+        accepted: events.length,
+        duplicates: 0,
+        rejected: [],
+    }, [...leaveItems, { event: sessionEnd }], input.deps.workMeshRoot, input.now, input.summary, input.markDisposed);
+    const cleared = updateSessionState(input.sessionId, input.deps.workContextRoot, (current) => {
+        if (!current)
+            return current;
+        const { presenceLeave: _leave, ...rest } = current;
+        return { ...rest, updatedAt: input.now().toISOString() };
+    });
+    return {
+        state: cleared ?? input.state,
+        items: remaining,
+        abort: false,
+    };
+}
 /**
  * Before a needs_project (or unresolved-with-company) batch is classified,
  * run the prompt-submit bind-best refinement. A bind updates the session

package/dist/lib/work-context/company-rebind.d.ts

@@ -0,0 +1,23 @@
+/**
+ * US-047: when the HQ session company changes, drop the old Work Mesh project
+ * and remember a presence leave for the previous company.
+ */
+import type { SessionStateFile } from "./state.js";
+export declare const NON_CLOUD_COMPANY_SLUG = "personal";
+export declare function isNonCloudCompanySlug(slug?: string | null): boolean;
+export declare function companyBindingChanged(prior: SessionStateFile | null | undefined, next: {
+    slug?: string;
+    uid?: string;
+}): boolean;
+export declare function presenceLeaveFromState(prior: SessionStateFile): NonNullable<SessionStateFile["presenceLeave"]> | undefined;
+export declare function reboundSessionProjection(input: {
+    prior: SessionStateFile;
+    sessionId: string;
+    nextSlug?: string;
+    nextUid?: string;
+    nowIso: string;
+    startedAt?: string;
+    toolWrites?: number;
+    hasTurn?: boolean;
+}): SessionStateFile;
+//# sourceMappingURL=company-rebind.d.ts.map

package/dist/lib/work-context/company-rebind.js

@@ -0,0 +1,59 @@
+/**
+ * US-047: when the HQ session company changes, drop the old Work Mesh project
+ * and remember a presence leave for the previous company.
+ */
+import { sameCompany } from "./company.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+export const NON_CLOUD_COMPANY_SLUG = "personal";
+export function isNonCloudCompanySlug(slug) {
+    return slug?.trim().toLowerCase() === NON_CLOUD_COMPANY_SLUG;
+}
+export function companyBindingChanged(prior, next) {
+    if (!prior)
+        return false;
+    if (!prior.companySlug && !prior.companyUid)
+        return false;
+    if (!next.slug && !next.uid)
+        return false;
+    return !sameCompany({ slug: prior.companySlug, uid: prior.companyUid }, next);
+}
+export function presenceLeaveFromState(prior) {
+    const uid = prior.companyUid?.trim();
+    if (!uid)
+        return undefined;
+    return {
+        companyUid: uid,
+        ...(prior.companySlug ? { companySlug: prior.companySlug } : {}),
+        ...(prior.projectId ? { projectId: prior.projectId } : {}),
+        ...(prior.taskId ? { taskId: prior.taskId } : {}),
+        ...(prior.bindingEpisodeId ? { bindingEpisodeId: prior.bindingEpisodeId } : {}),
+    };
+}
+export function reboundSessionProjection(input) {
+    const nonCloud = isNonCloudCompanySlug(input.nextSlug) || !input.nextUid;
+    const leave = presenceLeaveFromState(input.prior);
+    const out = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: input.sessionId,
+        contextStatus: nonCloud ? "needs_company" : "needs_project",
+        updatedAt: input.nowIso,
+    };
+    if (input.nextSlug)
+        out.companySlug = input.nextSlug;
+    if (!nonCloud && input.nextUid)
+        out.companyUid = input.nextUid;
+    const startedAt = input.startedAt ?? input.prior.startedAt;
+    if (startedAt)
+        out.startedAt = startedAt;
+    if (typeof input.toolWrites === "number")
+        out.toolWrites = input.toolWrites;
+    else if (typeof input.prior.toolWrites === "number") {
+        out.toolWrites = input.prior.toolWrites;
+    }
+    if (input.hasTurn || input.prior.hasTurn)
+        out.hasTurn = true;
+    if (leave)
+        out.presenceLeave = leave;
+    return out;
+}
+//# sourceMappingURL=company-rebind.js.map

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

@@ -3,8 +3,9 @@
  *
  * Order:
  *   1. trusted explicit (HQ_SPAWN_COMPANY env or observation.trustedContext/explicit)
- *   2. existing authoritative session scope
- *   3. session meta.yaml company_slug (/startwork)
+ *   2. existing authoritative session scope — unless session meta.yaml
+ *      names a different company (hq-session.sh rebind, US-047)
+ *   3. session meta.yaml company_slug (/startwork / hq-session.sh)
  *   4. agent-box identity file (HQ_AGENT_IDENTITY_FILE → companyUid; source
  *      trusted_explicit — never "default company mode"; below HQ_SPAWN_COMPANY,
  *      above device default)

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

@@ -3,8 +3,9 @@
  *
  * Order:
  *   1. trusted explicit (HQ_SPAWN_COMPANY env or observation.trustedContext/explicit)
- *   2. existing authoritative session scope
- *   3. session meta.yaml company_slug (/startwork)
+ *   2. existing authoritative session scope — unless session meta.yaml
+ *      names a different company (hq-session.sh rebind, US-047)
+ *   3. session meta.yaml company_slug (/startwork / hq-session.sh)
  *   4. agent-box identity file (HQ_AGENT_IDENTITY_FILE → companyUid; source
  *      trusted_explicit — never "default company mode"; below HQ_SPAWN_COMPANY,
  *      above device default)
@@ -254,12 +255,23 @@ export function resolveCompany(input) {
         ? input.existingState
         : readSessionState(input.sessionId, input.root);
     const prior = authoritativeCompanyFromState(state);
+    // 3. session meta.yaml company_slug — read before existing_scope so an
+    // operator rebind via hq-session.sh can replace a stale Work Mesh company.
+    const metaSlug = input.metaCompanySlug !== undefined
+        ? normalizeSlug(input.metaCompanySlug)
+        : readMetaCompanySlug(input.sessionId, input.hqRoot);
     if (prior) {
         const scoped = {
             slug: prior.slug,
             uid: prior.uid,
             source: "existing_scope",
         };
+        if (metaSlug && !sameCompany(scoped, { slug: metaSlug })) {
+            return {
+                status: "resolved",
+                company: { slug: metaSlug, source: "session_meta" },
+            };
+        }
         // Deterministic evidence from another company never silently replaces a
         // scoped session, even before it has a project binding. Preserve the
         // original scope and surface a conflict before tenant I/O.
@@ -288,10 +300,6 @@ export function resolveCompany(input) {
         }
         return { status: "resolved", company: scoped };
     }
-    // 3. session meta.yaml company_slug
-    const metaSlug = input.metaCompanySlug !== undefined
-        ? normalizeSlug(input.metaCompanySlug)
-        : readMetaCompanySlug(input.sessionId, input.hqRoot);
     if (metaSlug) {
         return {
             status: "resolved",

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

@@ -12,6 +12,7 @@ export * from "./config.js";
 export * from "./state.js";
 export * from "./outbox.js";
 export * from "./company.js";
+export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
 export * from "./project.js";
 export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
 export type { CandidatesResponse, FetchCandidatesFn, OrganizeCandidate, OrganizeListResult, OrganizeReceipt, OrganizeSubmitDecision, OrganizeSubmitResult, PostOrganizeFn, } from "./organize.js";

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

@@ -12,6 +12,7 @@ export * from "./config.js";
 export * from "./state.js";
 export * from "./outbox.js";
 export * from "./company.js";
+export { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
 export * from "./project.js";
 export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
 export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";

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

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import { InvalidSessionIdentityError, normalizeSessionIdentity, } from "../mesh/live/session-identity.js";
 import { companyCorrectionPath, companySlugFromCwd, resolveCompany, } from "./company.js";
+import { companyBindingChanged, isNonCloudCompanySlug, presenceLeaveFromState, reboundSessionProjection, } from "./company-rebind.js";
 import { invalidateDefaultCompanyMemberships, } from "./config.js";
 import { WORK_CONTEXT_CONTRACT_VERSION, normalizeTaskId, } from "./contract.js";
 import { EXIT_INVALID_IDENTITY, EXIT_NOT_TRACKING, EXIT_OK, InvalidDecisionOriginError, NotTrackingError, } from "./errors.js";
@@ -354,6 +355,43 @@ export async function reconcileObservation(obs, deps) {
     // A device default is weak, cached evidence: validate it authoritatively on
     // every tenant-I/O path so a membership revocation takes effect immediately.
     let resolvedCompany = company.company;
+    if (isNonCloudCompanySlug(resolvedCompany.slug)) {
+        const projection = prior
+            ? reboundSessionProjection({
+                prior,
+                sessionId,
+                nextSlug: resolvedCompany.slug,
+                nowIso,
+                startedAt,
+                toolWrites,
+                hasTurn,
+            })
+            : {
+                contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+                sessionId,
+                contextStatus: "needs_company",
+                companySlug: resolvedCompany.slug,
+                updatedAt: nowIso,
+                startedAt,
+                ...(typeof toolWrites === "number" ? { toolWrites } : {}),
+                ...(hasTurn ? { hasTurn: true } : {}),
+            };
+        const statePath = writeSessionState(mergeLocalSessionFields({ ...projection, ...transcriptFields }, prior, { preserveBindingEpisode: false, preserveCompanyBinding: false }), deps.root);
+        diagnostics.push(`company rebind to ${resolvedCompany.slug}; cleared project; held (non-cloud)`);
+        return {
+            result: resultOf({
+                kind: "needs_company",
+                classification: "needs_company",
+                delivery: "clean",
+                sessionId,
+                clientOperationId: obs.clientOperationId,
+                companySlug: resolvedCompany.slug,
+            }),
+            exitCode: EXIT_OK,
+            diagnostics: [...diagnostics, "needs_company: non-cloud session company; no tenant I/O"],
+            statePath,
+        };
+    }
     const deviceDefaultRequiresValidation = resolvedCompany.source === "device_default";
     if (deviceDefaultRequiresValidation && !deps.validateMembership) {
         return {
@@ -385,6 +423,7 @@ export async function reconcileObservation(obs, deps) {
                     invalidateDefaultCompanyMemberships({ root: deps.root, now: nowFn });
                 }
                 diagnostics.push(`membership denied for slug=${resolvedCompany.slug}; treating as needs_company`);
+                const deniedLeave = prior ? presenceLeaveFromState(prior) : undefined;
                 const statePath = writeSessionState(mergeLocalSessionFields({
                     contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
                     sessionId,
@@ -395,7 +434,10 @@ export async function reconcileObservation(obs, deps) {
                     ...(typeof toolWrites === "number" ? { toolWrites } : {}),
                     ...(hasTurn ? { hasTurn: true } : {}),
                     ...transcriptFields,
-                }, prior), deps.root);
+                    ...(deniedLeave ? { presenceLeave: deniedLeave } : {}),
+                }, prior, companyBindingChanged(prior, resolvedCompany)
+                    ? { preserveBindingEpisode: false, preserveCompanyBinding: false }
+                    : {}), deps.root);
                 return {
                     result: resultOf({
                         kind: "needs_company",
@@ -431,13 +473,23 @@ export async function reconcileObservation(obs, deps) {
         }
     }
     // Company resolved — resolve project/task (US-007B order).
+    const companyRebind = companyBindingChanged(prior, resolvedCompany);
+    const projectPrior = companyRebind && prior
+        ? {
+            ...prior,
+            projectId: undefined,
+            taskId: undefined,
+            bindingEpisodeId: undefined,
+            contextStatus: "needs_project",
+        }
+        : prior;
     let projectResolved = resolveProjectTask({
         sessionId,
         env,
         trusted,
         cwd,
         hqRoot,
-        existingState: prior,
+        existingState: projectPrior,
     });
     // Deterministic cwd projects belong to the cwd company. A higher-precedence
     // identity UID must not adopt a project from an unrelated/unverified slug.
@@ -537,7 +589,7 @@ export async function reconcileObservation(obs, deps) {
         }
     }
     const projectHint = !projectId
-        ? (prior?.projectHint || projectResolved?.projectId)
+        ? (companyRebind ? projectResolved?.projectId : (prior?.projectHint || projectResolved?.projectId))
         : undefined;
     const bindResultFields = {
         ...(projectBindReason ? { projectBindReason } : {}),
@@ -634,6 +686,10 @@ export async function reconcileObservation(obs, deps) {
     // Do not let a weak later observation erase a server-acknowledged company
     // binding. Keep the result unresolved so the normal candidate threshold can
     // still advance the session, while preserving the durable emitter projection.
+    if (companyRebind && !projectId && resolvedCompany.uid) {
+        registerClassification = "needs_project";
+        diagnostics.push(`company rebind to ${resolvedCompany.slug ?? resolvedCompany.uid}; cleared project`);
+    }
     const stateClassification = registerClassification === "unresolved" &&
         prior?.contextStatus === "needs_project" &&
         prior.companyUid === resolvedCompany.uid &&
@@ -707,9 +763,12 @@ export async function reconcileObservation(obs, deps) {
         };
     }
     let outboxOp;
-    const companyConfidence = company.status === "resolved" && company.company.source === "device_default"
+    const companyConfidence = !companyRebind &&
+        company.status === "resolved" &&
+        company.company.source === "device_default"
         ? "device_default"
         : undefined;
+    const presenceLeave = companyRebind && prior ? presenceLeaveFromState(prior) : undefined;
     try {
         outboxOp = enqueueOutbox({
             clientOperationId: obs.clientOperationId,
@@ -762,9 +821,12 @@ export async function reconcileObservation(obs, deps) {
             ...(hasTurn ? { hasTurn: true } : {}),
             ...(decision ? { decision } : {}),
             ...(companyConfidence ? { companyConfidence } : {}),
+            ...(presenceLeave ? { presenceLeave } : {}),
             ...bindStateFields,
             ...transcriptFields,
-        }, prior);
+        }, prior, companyRebind
+            ? { preserveBindingEpisode: false, preserveCompanyBinding: false }
+            : {});
         statePath = writeSessionState(stateWrite, deps.root);
     }
     catch (err) {
@@ -871,6 +933,7 @@ export async function reconcileObservation(obs, deps) {
                 sessionId,
                 clientOperationId: obs.clientOperationId,
                 companyUid: resolvedCompany.uid,
+                companySlug: resolvedCompany.slug,
                 projectId,
                 taskId,
                 bindingEpisodeId: delivered.receiptId,

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

@@ -106,6 +106,17 @@ export interface SessionStateFile {
     projectGate?: "choose" | "missing_board";
     /** Slug the session was trying to bind. Re-checked on the next prompt. */
     projectHint?: string;
+    /**
+     * LOCAL-ONLY. Pending session_end against a company this session just left
+     * (US-047). Flush posts it to that companyUid, then clears the field.
+     */
+    presenceLeave?: {
+        companyUid: string;
+        companySlug?: string;
+        projectId?: string;
+        taskId?: string;
+        bindingEpisodeId?: string;
+    };
     updatedAt: string;
 }
 /**

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

@@ -33,6 +33,7 @@ export const SESSION_STATE_ALLOWLIST = new Set([
     "projectCandidates",
     "projectGate",
     "projectHint",
+    "presenceLeave",
     "updatedAt",
 ]);
 const SESSION_STATE_LOCK_TIMEOUT_MS = 5_000;
@@ -240,6 +241,8 @@ export function projectSessionState(state) {
         out.projectGate = state.projectGate;
     if (state.projectHint && !state.projectId)
         out.projectHint = state.projectHint;
+    if (state.presenceLeave?.companyUid)
+        out.presenceLeave = state.presenceLeave;
     return out;
 }
 /**
@@ -298,9 +301,15 @@ export function mergeLocalSessionFields(next, prior, options = {}) {
     if (!out.companyConfidence && prior.companyConfidence && sameCompanyBinding) {
         out.companyConfidence = prior.companyConfidence;
     }
-    if (!out.projectId && !out.projectHint && prior.projectHint) {
+    if (!out.projectId &&
+        !out.projectHint &&
+        prior.projectHint &&
+        sameCompanyBinding) {
         out.projectHint = prior.projectHint;
     }
+    if (!out.presenceLeave && prior.presenceLeave) {
+        out.presenceLeave = prior.presenceLeave;
+    }
     if (out.projectId)
         out.projectHint = undefined;
     const sameBinding = prior.companyUid === out.companyUid &&

package/package.json

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