@indigoai-us/hq-cli 5.121.1 → 5.122.0

package/dist/commands/cloud-retire.js

@@ -0,0 +1,154 @@
+/**
+ * `hq cloud retire company <slug>` — soft-tombstone a cloud company so
+ * `hq cloud demote company` can run without `--propagate-deletes`.
+ *
+ * Console equivalent: Settings → Delete company (`DELETE /entity/{uid}`).
+ * Owner-only. The entity row, S3 bucket, KMS key, and memberships stay;
+ * `/membership/me` stops listing the company. Local files are not touched —
+ * demote is the follow-up that flips the local tree back to local-only.
+ *
+ * Confirm step is on by default (`[y/N]`). `--yes` skips it for scripts.
+ * A non-TTY stdin without `--yes` refuses rather than hanging.
+ *
+ * Exit codes (mirrors cloud-provision / cloud-demote):
+ *   0 — success, already tombstoned, or the operator cancelled.
+ *   1 — vault HTTP failure (auth/network/5xx).
+ *   2 — validation (bad slug, no entity, not owner, missing confirm).
+ */
+import * as fs from "node:fs";
+import * as readline from "node:readline";
+import chalk from "chalk";
+import { ProvisionError, companyConfigPath, createDefaultVaultClient, validateSlug, } from "./cloud-provision.js";
+import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+export function defaultConfirm(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/**
+ * Read `companyUid` from `companies/<slug>/.hq/config.json` when the by-slug
+ * lookup misses (a tombstoned company is filtered from that route).
+ */
+export function readLocalCompanyUid(hqRoot, slug) {
+    const cPath = companyConfigPath(hqRoot, slug);
+    if (!fs.existsSync(cPath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cPath, "utf-8"));
+        return typeof parsed.companyUid === "string" && parsed.companyUid.length > 0
+            ? parsed.companyUid
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function retireCompany(options) {
+    validateSlug(options.slug);
+    const accessToken = options.resolveAccessToken
+        ? await options.resolveAccessToken()
+        : await ensureCognitoToken();
+    const client = options.vaultClient ??
+        createDefaultVaultClient(options.vaultApiUrl, accessToken);
+    let entity;
+    try {
+        entity = await client.findCompanyBySlug(options.slug);
+    }
+    catch (err) {
+        if (err instanceof ProvisionError)
+            throw err;
+        throw new ProvisionError(1, `Vault GET by-slug failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (entity?.deleted === true) {
+        return {
+            ok: true,
+            company_slug: options.slug,
+            cloud_uid: entity.uid,
+            already_deleted: true,
+        };
+    }
+    const uid = entity?.uid ?? readLocalCompanyUid(options.hqRoot, options.slug);
+    if (!uid) {
+        throw new ProvisionError(2, `Refusing to retire '${options.slug}': no cloud entity found.`);
+    }
+    if (options.yes !== true) {
+        const tty = options.stdinIsTTY ?? process.stdin.isTTY === true;
+        if (!tty) {
+            throw new ProvisionError(2, `Refusing to retire '${options.slug}' without confirmation. Re-run with --yes.`);
+        }
+        const confirm = options.confirm ?? defaultConfirm;
+        const ok = await confirm(`Soft-tombstone cloud company '${options.slug}' (${uid})? ` +
+            `It will disappear from every member's picker. Vault files stay. ` +
+            `Then run: hq cloud demote company ${options.slug}`);
+        if (!ok) {
+            return {
+                ok: false,
+                company_slug: options.slug,
+                cloud_uid: uid,
+                already_deleted: false,
+                cancelled: true,
+            };
+        }
+    }
+    try {
+        await client.softDeleteCompany(uid);
+    }
+    catch (err) {
+        if (err instanceof ProvisionError)
+            throw err;
+        throw new ProvisionError(1, `Vault DELETE /entity/${uid} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        ok: true,
+        company_slug: options.slug,
+        cloud_uid: uid,
+        already_deleted: false,
+    };
+}
+/**
+ * Register `retire company <slug>` under the `cloud` command group.
+ */
+export function registerCloudRetireCommands(program) {
+    const retireCmd = program
+        .command("retire")
+        .description("Soft-tombstone a cloud-backed company (owner only)");
+    retireCmd
+        .command("company")
+        .description("Soft-tombstone a cloud company so `hq cloud demote company` can run. " +
+        "Does not delete vault files or local folders. Prompts unless --yes.")
+        .argument("<slug>", "Company slug")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .option("--vault-api-url <url>", `Vault API URL (default: ${DEFAULT_VAULT_API_URL})`, DEFAULT_VAULT_API_URL)
+        .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
+        .action(async (slug, options) => {
+        try {
+            const result = await retireCompany({
+                slug,
+                hqRoot: options.hqRoot,
+                vaultApiUrl: options.vaultApiUrl,
+                yes: options.yes,
+            });
+            process.stdout.write(JSON.stringify(result) + "\n");
+            if (result.cancelled) {
+                process.stderr.write(chalk.dim("[hq cloud retire] Cancelled — nothing was tombstoned.\n"));
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            if (err instanceof ProvisionError) {
+                process.stderr.write(chalk.red(`[hq cloud retire] ${err.message}\n`));
+                process.exit(err.code);
+            }
+            process.stderr.write(chalk.red(`[hq cloud retire] Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=cloud-retire.js.map

package/dist/commands/mesh.js

@@ -12,7 +12,7 @@ import * as readline from "node:readline/promises";
 import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveMembershipCompanies, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, getDefaultCompany, readDeviceConfig, recordMigrationCapabilitySnapshot, setDefaultCompany, } from "../lib/work-context/config.js";
-import { DefaultCompanyLockedError, DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
+import { DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
 import { CLI_KIND_TO_SCHEMA, resolveEnqueueSessionId, } from "../lib/mesh/live/index.js";
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
@@ -375,7 +375,7 @@ async function runContextDefaultGet(opts) {
 }
 async function runContextDefaultSet(slug, opts) {
     const root = workContextHomeRoot();
-    void opts.company; // retained for CLI compatibility; unlock is memberships-wide
+    void opts.company; // retained for CLI compatibility
     let token;
     try {
         token = await requireToken();
@@ -383,42 +383,38 @@ async function runContextDefaultSet(slug, opts) {
     catch {
         token = undefined;
     }
-    // US-017B: unlock only when EVERY active membership advertises migration.
+    // Migration remains useful diagnostic context, but it must never prevent a
+    // verified member from choosing their own device-local preference.
     let migrationCapability = false;
+    let migrationWarning;
     if (token) {
         const probe = await probeMigrationCapabilityForMemberships(token);
         recordMigrationCapabilitySnapshot(probe, { root });
         migrationCapability = probe.unlocked;
-        if (probe.offline && !opts.allowWithoutMigration) {
-            console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (offline or not logged in)"));
-            process.exitCode = 1;
-            return;
+        if (probe.offline) {
+            migrationWarning =
+                "Warning: migration capability could not be checked; membership for the selected company will still be verified.";
         }
-        if (!probe.unlocked && !opts.allowWithoutMigration) {
+        else if (!probe.unlocked) {
             const detail = probe.companies.length === 0
                 ? "no active memberships"
                 : probe.companies
                     .filter((c) => !c.migration)
                     .map((c) => c.companySlug || c.companyUid)
                     .join(", ");
-            console.error(chalk.red(`DEFAULT_COMPANY_LOCKED: migration capability is not true for every company you belong to (${detail || "locked"})`));
-            process.exitCode = 1;
-            return;
+            migrationWarning =
+                `Warning: migration capability is mixed or unavailable for ${detail || "some memberships"}; ` +
+                    "the selected company can still be set because membership is verified directly.";
         }
     }
-    else if (!opts.allowWithoutMigration) {
-        console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (no Cognito session)"));
-        process.exitCode = 1;
-        return;
-    }
-    if (!migrationCapability && opts.allowWithoutMigration) {
-        console.error(chalk.yellow("Warning: --allow-without-migration bypasses DEFAULT_COMPANY_LOCKED; a wrong default is hard to correct until migration is available for every company you belong to."));
+    else {
+        migrationWarning =
+            "Warning: migration capability could not be checked without a Cognito session; membership for the selected company must still be verified.";
     }
     try {
         const cfg = await setDefaultCompany(slug, {
             root,
             migrationCapability,
-            allowWithoutMigration: opts.allowWithoutMigration,
             validateMembership: async (candidate) => {
                 if (!token) {
                     throw new DefaultCompanyUnavailableError(`Cannot verify membership for company "${candidate}" (no Cognito session; offline or not logged in)`);
@@ -437,15 +433,16 @@ async function runContextDefaultSet(slug, opts) {
             },
         });
         if (opts.json) {
-            console.log(JSON.stringify({ ok: true, config: cfg }, null, 2));
+            console.log(JSON.stringify({ ok: true, config: cfg, migrationWarning }, null, 2));
             return;
         }
         const stored = cfg.defaultCompany;
         console.log(`Default company set to ${stored?.slug ?? slug}${stored?.uid ? ` (${stored.uid})` : ""}`);
+        if (migrationWarning)
+            console.error(chalk.yellow(migrationWarning));
     }
     catch (err) {
-        if (err instanceof DefaultCompanyLockedError ||
-            err instanceof DefaultCompanyUnavailableError) {
+        if (err instanceof DefaultCompanyUnavailableError) {
             console.error(chalk.red(`${err.code}: ${err.message}`));
             process.exitCode = 1;
             return;
@@ -715,13 +712,16 @@ async function runSessionStatus(opts) {
     }
     const { token, company } = await withCompany({ company: opts.company });
     const live = await fetchCompanyLive(token, company.companyUid);
+    const unattributedEvents = collectDaemonDoctor().unattributedEvents;
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "session-status", company, live }, null, 2));
+        console.log(JSON.stringify({ ok: true, action: "session-status", company, live, unattributedEvents }, null, 2));
         return;
     }
     for (const line of formatCompanyLiveTable(live, company.companySlug || company.companyUid)) {
         console.log(line);
     }
+    console.log(`unattributed events: ${unattributedEvents.total} ` +
+        `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
 }
 const HARNESSES = new Set([
     "claude-code",
@@ -1085,10 +1085,10 @@ export function registerMeshCommand(program) {
         .action((opts) => wrap(() => runContextDefaultGet(opts))());
     def
         .command("set")
-        .description("Set the device default company slug (unlocked when migration is true for every membership)")
+        .description("Set the device default company slug after verifying membership")
         .argument("<slug>", "Company slug")
-        .option("--allow-without-migration", "Bypass DEFAULT_COMPANY_LOCKED with a warning")
-        .option("--company <slug|uid>", "Deprecated no-op; unlock probes every active membership")
+        .option("--allow-without-migration", "Deprecated compatibility no-op; selected-company membership is always verified")
+        .option("--company <slug|uid>", "Deprecated no-op; the selected company is verified directly")
         .option("--json", "Print machine-readable JSON")
         .action((slug, opts) => wrap(() => runContextDefaultSet(slug, opts))());
     def

package/dist/lib/agent-kit/adopt-identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
+ * is signed in to HQ.
+ *
+ * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
+ * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
+ * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
+ * a computer with its owner lives in a sibling directory instead, so without
+ * this the CLI would find the layout of an agent and the credentials of a
+ * person: `hq agent probe` would report its owner's identity and the bot would
+ * act as them.
+ *
+ * So before any `hq agent` subcommand runs, the resolved tree is published to
+ * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
+ * a daemon unit that pins one stays pinned.
+ *
+ * The person's own session file is not read, moved, or changed by any of this.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export declare const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
+export declare const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
+/**
+ * Point the token layer at `paths` unless the caller already pinned it.
+ * Returns the variables it set, for tests and for `--verbose` output.
+ */
+export declare function adoptAgentIdentityEnv(paths: Pick<AgentKitPaths, "agentDir" | "machineCredsPath">, env?: NodeJS.ProcessEnv): Record<string, string>;
+//# sourceMappingURL=adopt-identity.d.ts.map

package/dist/lib/agent-kit/adopt-identity.js

@@ -0,0 +1,51 @@
+/**
+ * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
+ * is signed in to HQ.
+ *
+ * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
+ * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
+ * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
+ * a computer with its owner lives in a sibling directory instead, so without
+ * this the CLI would find the layout of an agent and the credentials of a
+ * person: `hq agent probe` would report its owner's identity and the bot would
+ * act as them.
+ *
+ * So before any `hq agent` subcommand runs, the resolved tree is published to
+ * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
+ * a daemon unit that pins one stays pinned.
+ *
+ * The person's own session file is not read, moved, or changed by any of this.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
+export const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
+/**
+ * Point the token layer at `paths` unless the caller already pinned it.
+ * Returns the variables it set, for tests and for `--verbose` output.
+ */
+export function adoptAgentIdentityEnv(paths, env = process.env) {
+    const applied = {};
+    if (env[MACHINE_CREDS_FILE_ENV]?.trim())
+        return applied;
+    // Only adopt a tree that actually holds an identity: on a host that has not
+    // enrolled yet, leaving the environment alone keeps today's error messages.
+    try {
+        if (!fs.statSync(paths.machineCredsPath).isFile())
+            return applied;
+    }
+    catch {
+        return applied;
+    }
+    applied[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
+    env[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
+    // Per-agent token cache. Two identities on one computer must never share a
+    // minted-token file; the agent's belongs inside the agent's own tree.
+    if (!env[MACHINE_TOKEN_STATE_DIR_ENV]?.trim()) {
+        const dir = path.join(paths.agentDir, "token-state");
+        applied[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
+        env[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
+    }
+    return applied;
+}
+//# sourceMappingURL=adopt-identity.js.map

package/dist/lib/agent-kit/paths.d.ts

@@ -13,6 +13,14 @@
  * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
  * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
  * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ *
+ * LOCAL BOTS. A bot that runs on its owner's own computer cannot use the
+ * default tree: that machine already has the owner's HQ session, and an agent
+ * identity must not share a host account with a person's login. Such a bot
+ * enrolls into a SIBLING directory instead — `~/.hq-agent/<name>/` with the
+ * same layout — and every `hq agent …` command finds it here, so the bot does
+ * not have to carry environment variables around to be itself. Two or more
+ * local agents are ambiguous on purpose: pick one with `HQ_AGENT_DIR`.
  */
 export declare const AGENT_DIR_ENV = "HQ_AGENT_DIR";
 export declare const HOST_KEY_NAME = "host-key";
@@ -35,6 +43,18 @@ export interface AgentKitPaths {
     skillsDir: string;
     lastHeartbeatPath: string;
 }
+/** Default name for a bot enrolled alongside its owner's own session. */
+export declare const DEFAULT_LOCAL_AGENT_NAME = "local";
+/** `~/.hq-agent` — the root, whether or not it holds an identity itself. */
+export declare function agentRootDir(home?: string): string;
+/** `~/.hq-agent/<name>` — an isolated home for one local bot. */
+export declare function localAgentDir(name: string, home?: string): string;
+/**
+ * Local agent homes under `~/.hq-agent`, by name, oldest name order. A
+ * directory counts only once it holds a creds file, so a half-written tree is
+ * never mistaken for an identity.
+ */
+export declare function listLocalAgentDirs(home?: string): string[];
 export declare function agentDir(home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function agentKitPaths(home?: string, env?: NodeJS.ProcessEnv): AgentKitPaths;
 export declare function componentStatePath(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent): string;

package/dist/lib/agent-kit/paths.js

@@ -13,7 +13,16 @@
  * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
  * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
  * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ *
+ * LOCAL BOTS. A bot that runs on its owner's own computer cannot use the
+ * default tree: that machine already has the owner's HQ session, and an agent
+ * identity must not share a host account with a person's login. Such a bot
+ * enrolls into a SIBLING directory instead — `~/.hq-agent/<name>/` with the
+ * same layout — and every `hq agent …` command finds it here, so the bot does
+ * not have to carry environment variables around to be itself. Two or more
+ * local agents are ambiguous on purpose: pick one with `HQ_AGENT_DIR`.
  */
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 export const AGENT_DIR_ENV = "HQ_AGENT_DIR";
@@ -23,11 +32,62 @@ export const MACHINE_CREDS_NAME = "machine-creds.json";
 export const KIT_CONFIG_NAME = "kit.json";
 export const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
 export const KIT_COMPONENTS = ["sync", "inbox"];
+/** Default name for a bot enrolled alongside its owner's own session. */
+export const DEFAULT_LOCAL_AGENT_NAME = "local";
+/** `~/.hq-agent` — the root, whether or not it holds an identity itself. */
+export function agentRootDir(home = os.homedir()) {
+    return path.join(home, ".hq-agent");
+}
+/** `~/.hq-agent/<name>` — an isolated home for one local bot. */
+export function localAgentDir(name, home = os.homedir()) {
+    return path.join(agentRootDir(home), name);
+}
+/**
+ * Local agent homes under `~/.hq-agent`, by name, oldest name order. A
+ * directory counts only once it holds a creds file, so a half-written tree is
+ * never mistaken for an identity.
+ */
+export function listLocalAgentDirs(home = os.homedir()) {
+    const root = agentRootDir(home);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => path.join(root, e.name))
+        .filter((dir) => {
+        try {
+            return fs.statSync(path.join(dir, MACHINE_CREDS_NAME)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
 export function agentDir(home = os.homedir(), env = process.env) {
     const override = env[AGENT_DIR_ENV]?.trim();
     if (override)
         return override;
-    return path.join(home, ".hq-agent");
+    const root = agentRootDir(home);
+    // An identity in the root wins: that is the dedicated-host layout, and a
+    // host that has one is not running a local bot beside a person.
+    try {
+        if (fs.statSync(path.join(root, MACHINE_CREDS_NAME)).isFile())
+            return root;
+    }
+    catch {
+        /* no identity in the root — fall through to the local homes */
+    }
+    const locals = listLocalAgentDirs(home);
+    // Exactly one is unambiguous. Two or more cannot be guessed, so keep the
+    // root and let the caller fail with a message naming HQ_AGENT_DIR rather
+    // than silently acting as whichever agent sorted first.
+    return locals.length === 1 ? locals[0] : root;
 }
 export function agentKitPaths(home = os.homedir(), env = process.env) {
     const dir = agentDir(home, env);

package/dist/lib/doctor/checks/work-context.js

@@ -178,7 +178,7 @@ function formatMigrationCapabilityCheck(cap, root) {
             status: "WARN",
             checkId: "work-context.migration-capability",
             target,
-            message: `Migration capability: offline at ${cap.checkedAt}; default-company stays locked.`,
+            message: `Migration capability: offline at ${cap.checkedAt}; selected-company membership is still verified when setting a default.`,
         };
     }
     const falseCount = cap.companies.filter((c) => !c.migration).length;

package/dist/lib/mesh/client.d.ts

@@ -73,8 +73,9 @@ export interface MigrationCapabilityProbe {
     companies: MigrationCapabilityCompanyResult[];
 }
 /**
- * Unlock rule for default-company mode (US-017B): migration must be true for
- * EVERY company the caller belongs to. Offline / empty memberships → locked.
+ * Diagnostic probe for migration capability across active memberships. The
+ * result is recorded and warned on, but does not gate a verified member from
+ * choosing a device-local default company.
  */
 export declare function probeMigrationCapabilityForMemberships(token: string, opts?: {
     listCompanies?: (token: string) => Promise<MeshCompany[]>;

package/dist/lib/mesh/client.js

@@ -119,8 +119,9 @@ export async function fetchMigrationCapability(token, companyUid) {
     }
 }
 /**
- * Unlock rule for default-company mode (US-017B): migration must be true for
- * EVERY company the caller belongs to. Offline / empty memberships → locked.
+ * Diagnostic probe for migration capability across active memberships. The
+ * result is recorded and warned on, but does not gate a verified member from
+ * choosing a device-local default company.
  */
 export async function probeMigrationCapabilityForMemberships(token, opts) {
     const now = (opts?.now ?? (() => new Date()))().toISOString();

package/dist/lib/mesh/live/backfill-held.d.ts

@@ -13,8 +13,9 @@
  * company (via the identity-file default resolver shipped in 5.108.22). The
  * daemon's next held retry then re-attributes and posts those events naturally.
  *
- * Constraints (owner directive):
- * - Explicit, opt-in only. Never automatic; never wired into a hook or daemon.
+ * Constraints:
+ * - The daemon runs this in bounded startup batches; the CLI command remains
+ *   available for an explicit full/manual recovery.
  * - Idempotent: sessions that already carry a companyUid are skipped.
  * - Never deletes held events; the daemon posts them on the next retry.
  * - Purely local to the box it runs on; no fleet fan-out.

package/dist/lib/mesh/live/backfill-held.js

@@ -13,8 +13,9 @@
  * company (via the identity-file default resolver shipped in 5.108.22). The
  * daemon's next held retry then re-attributes and posts those events naturally.
  *
- * Constraints (owner directive):
- * - Explicit, opt-in only. Never automatic; never wired into a hook or daemon.
+ * Constraints:
+ * - The daemon runs this in bounded startup batches; the CLI command remains
+ *   available for an explicit full/manual recovery.
  * - Idempotent: sessions that already carry a companyUid are skipped.
  * - Never deletes held events; the daemon posts them on the next retry.
  * - Purely local to the box it runs on; no fleet fan-out.

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -3,6 +3,7 @@
  * outbox/last-flush, and unhealthy when unacked spool age > 60s while online.
  */
 import { type CognitoActorKind, type CognitoTokenSource } from "../../../../utils/cognito-session.js";
+import { type UnattributedEventCounts } from "../spool.js";
 import { type DaemonStateFile } from "./state.js";
 export declare const UNHEALTHY_SPOOL_AGE_MS = 60000;
 export interface DaemonDoctorReport {
@@ -17,6 +18,8 @@ export interface DaemonDoctorReport {
     spoolDepth: number;
     heldCount: number;
     deadLetterCount: number;
+    /** Events in any local queue still marked no-company / NEEDS_COMPANY / NONE. */
+    unattributedEvents: UnattributedEventCounts;
     outboxDepth: number;
     lastFlushAt?: string;
     lastFlushResult?: DaemonStateFile["lastFlushResult"];

package/dist/lib/mesh/live/daemon/doctor.js

@@ -7,7 +7,7 @@ import * as os from "node:os";
 import { describeCognitoTokenSource, } from "../../../../utils/cognito-session.js";
 import { outboxStats, } from "../../../work-context/outbox.js";
 import { workContextRoot } from "../../../work-context/paths.js";
-import { countJsonlLines, } from "../spool.js";
+import { countJsonlLines, countUnattributedEvents, } from "../spool.js";
 import { workMeshDeadLetterPath, workMeshHeldPath, workMeshRoot, workMeshSpoolPath, } from "../paths.js";
 import { daemonDir, daemonPidPath } from "./paths.js";
 import { readEmitState } from "../emit.js";
@@ -78,6 +78,7 @@ export function collectDaemonDoctor(deps = {}) {
     const spoolDepth = countJsonlLines(spoolPath);
     const heldCount = countJsonlLines(heldPath);
     const deadLetterCount = countJsonlLines(deadPath);
+    const unattributedEvents = countUnattributedEvents(meshRoot);
     const outbox = outboxStats(ctxRoot);
     const mqttState = state?.mqttState ?? (running ? "unknown" : "closed");
     const companiesOnline = state?.companiesOnline ?? [];
@@ -96,6 +97,13 @@ export function collectDaemonDoctor(deps = {}) {
     if (deadLetterCount > 0) {
         unhealthyReasons.push(`dead-letter count=${deadLetterCount}`);
     }
+    if (emitMode === "legacy" && heldCount > 0) {
+        unhealthyReasons.push(`held events awaiting company attribution=${heldCount}`);
+    }
+    if (unattributedEvents.total > 0) {
+        unhealthyReasons.push(`unattributed events=${unattributedEvents.total} ` +
+            `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
+    }
     const presenceRefusal = state?.presenceRefusal ?? null;
     if (presenceRefusal) {
         unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
@@ -114,6 +122,7 @@ export function collectDaemonDoctor(deps = {}) {
         spoolDepth,
         heldCount,
         deadLetterCount,
+        unattributedEvents,
         outboxDepth: outbox.depth,
         lastFlushAt: state?.lastFlushAt,
         lastFlushResult: state?.lastFlushResult,
@@ -150,7 +159,8 @@ export function formatDaemonDoctor(report) {
         // receive-only (direct) mode.
         lines.push(`spool depth: ${report.spoolDepth}`, `held: ${report.heldCount}`, `outbox depth: ${report.outboxDepth}`);
     }
-    lines.push(`dead-letter: ${report.deadLetterCount}`, `token source: ${report.tokenSource}`, `actor kind: ${report.actorKind}`);
+    lines.push(`dead-letter: ${report.deadLetterCount}`, `unattributed events: ${report.unattributedEvents.total} ` +
+        `(spool=${report.unattributedEvents.spool} held=${report.unattributedEvents.held} dead-letter=${report.unattributedEvents.deadLetter})`, `token source: ${report.tokenSource}`, `actor kind: ${report.actorKind}`);
     if (report.emitMode === "legacy") {
         lines.push(`last flush: ${report.lastFlushAt ?? "(never)"}${report.lastFlushResult
             ? ` ok=${report.lastFlushResult.ok} posted=${report.lastFlushResult.posted}`

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -9,6 +9,7 @@
  * - SIGTERM/SIGINT: flush once more, MQTT DISCONNECT (server derives offline), exit
  */
 import { type FlushSummary } from "../flush.js";
+import { type BackfillHeldResult } from "../backfill-held.js";
 import { type CredentialsFetcher, type TimerHost } from "./credentials.js";
 import { type PidLockDeps } from "./pid-lock.js";
 import { PresenceClient, type MqttConnectFn } from "./presence.js";
@@ -16,6 +17,8 @@ import { TranscriptWatcher, type TranscriptFs } from "./transcript-watch.js";
 import { type MeshEmitMode } from "./mode.js";
 export declare const SPOOL_DEBOUNCE_MS = 2000;
 export declare const FLUSH_INTERVAL_MS = 10000;
+/** Keep startup recovery bounded: the next daemon start continues the backlog. */
+export declare const HELD_BACKFILL_STARTUP_BATCH_SIZE = 100;
 /**
  * Only producer appends to spool.jsonl should wake the watcher. Every other
  * file in the work-mesh root (held.jsonl, spool.<ts>.claimed, held.<ts>.claimed,
@@ -44,6 +47,10 @@ export interface DaemonRunDeps {
         quarantined: number;
         skipped?: number;
     }>;
+    /** Injected held-session recovery (tests). Runs once before the startup flush. */
+    backfillHeld?: () => Promise<BackfillHeldResult>;
+    /** Maximum distinct held sessions reconciled during one daemon startup. */
+    heldBackfillBatchSize?: number;
     /** Injected board refresh (tests). */
     refreshBoards?: () => Promise<{
         refreshed: number;