@indigoai-us/hq-cli 5.130.0 → 5.132.0

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

@@ -101,7 +101,12 @@ export declare function restartDaemonServiceIfInstalled(opts?: {
     platform?: DaemonInstallPlatform;
     home?: string;
     uid?: number;
+    /** HQ root the daemon was serving, or the root this update was run from. */
+    hqRoot?: string;
+    env?: NodeJS.ProcessEnv;
     existsSync?: typeof fs.existsSync;
+    readFileSync?: typeof fs.readFileSync;
+    writeFileSync?: typeof fs.writeFileSync;
     run?: (command: string, args: string[]) => {
         status: number | null;
     };

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

@@ -17,7 +17,7 @@ import * as path from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveDaemonAssetDir } from "./log.js";
 import { LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, WINDOWS_TASK_NAME, daemonDir, daemonLogPath, daemonPidPath, } from "./paths.js";
-import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot } from "./config.js";
+import { isInstallableHqRoot, readDaemonConfig, registerTrustedHqRoot, verifyHqRoot } from "./config.js";
 import { defaultPidLockDeps, pidLockStatus, readPidLock } from "./pid-lock.js";
 /**
  * `schtasks /End` terminates the task's root process only. The daemon is
@@ -49,6 +49,86 @@ export const defaultSchtasks = (args) => {
         stderr: r.error ? r.error.message : (r.stderr ?? ""),
     };
 };
+function readServiceText(file, existsSync, readFileSync) {
+    if (!existsSync(file))
+        return "";
+    const raw = readFileSync(file);
+    const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw));
+    if ((buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) || buf.includes(0)) {
+        return buf.toString("utf16le").replace(/^\uFEFF/, "");
+    }
+    return buf.toString("utf8");
+}
+function hqRootFromUnitText(platform, text) {
+    if (platform === "win32")
+        return parseWindowsTaskHqRoot(text);
+    if (platform === "darwin") {
+        const match = /<key>HQ_ROOT<\/key>\s*<string>([^<]*)<\/string>/.exec(text);
+        return match?.[1] ?? null;
+    }
+    const match = /^Environment=HQ_ROOT=(.*)$/m.exec(text);
+    if (!match)
+        return null;
+    const value = match[1].trim();
+    return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1) : value;
+}
+/**
+ * Record the HQ root the daemon was serving and replace a pre-allowlist unit
+ * before the process is restarted. A unit with no HQ_ROOT (or Restart=on-failure)
+ * comes back with an empty root allowlist unless this runs first.
+ */
+function migrateLegacyDaemonUnit(opts) {
+    const { platform, home } = opts;
+    if (platform !== "darwin" && platform !== "linux" && platform !== "win32")
+        return;
+    const unitPath = platform === "darwin"
+        ? path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`)
+        : platform === "linux"
+            ? path.join(home, ".config", "systemd", "user", SYSTEMD_UNIT_NAME)
+            : path.join(daemonDir(undefined, home, opts.env), `${WINDOWS_TASK_NAME}.xml`);
+    if (!opts.existsSync(unitPath))
+        return;
+    const text = readServiceText(unitPath, opts.existsSync, opts.readFileSync);
+    const fromUnit = hqRootFromUnitText(platform, text);
+    const verified = verifyHqRoot(fromUnit ?? undefined)
+        ?? verifyHqRoot(opts.hqRoot)
+        ?? verifyHqRoot(opts.env?.HQ_ROOT);
+    if (!verified)
+        return;
+    registerTrustedHqRoot(daemonDir(undefined, home, opts.env), verified);
+    const legacy = platform === "linux"
+        ? !text.includes("Environment=HQ_ROOT=") || /Restart=on-failure/.test(text)
+        : platform === "darwin"
+            ? !/<key>HQ_ROOT<\/key>/.test(text)
+            : !fromUnit;
+    if (!legacy)
+        return;
+    const paths = buildInstallPaths({
+        home,
+        env: opts.env,
+        hqRoot: verified,
+        hqBinary: "/usr/bin/hq",
+        nodeBinary: process.execPath || "/usr/bin/node",
+    });
+    try {
+        paths.hqBinary = resolveHqBinary(process.argv, opts.env ?? process.env);
+    }
+    catch {
+        // The rendered command only has to name a binary; install already resolved one.
+    }
+    if (platform === "darwin") {
+        opts.writeFileSync(unitPath, renderLaunchdPlist(paths), { mode: 0o600 });
+        return;
+    }
+    if (platform === "linux") {
+        opts.writeFileSync(unitPath, renderSystemdUserUnit(paths), { mode: 0o600 });
+        opts.run("systemctl", ["--user", "daemon-reload"]);
+        return;
+    }
+    const rendered = renderWindowsTaskXml(paths);
+    opts.writeFileSync(unitPath, encodeWindowsTaskXml(rendered));
+    opts.run("schtasks.exe", ["/Create", "/TN", WINDOWS_TASK_NAME, "/XML", unitPath, "/F"]);
+}
 /**
  * Restart the installed user daemon after a CLI upgrade. This is deliberately
  * best-effort: an update must remain successful if a user has no service,
@@ -58,8 +138,11 @@ export function restartDaemonServiceIfInstalled(opts = {}) {
     const platform = opts.platform ?? detectPlatform();
     const home = opts.home ?? os.homedir();
     const existsSync = opts.existsSync ?? fs.existsSync;
+    const readFileSync = opts.readFileSync ?? fs.readFileSync;
+    const writeFileSync = opts.writeFileSync ?? fs.writeFileSync;
     const run = opts.run ?? ((command, args) => spawnSync(command, args, { stdio: "ignore" }));
     try {
+        migrateLegacyDaemonUnit({ platform, home, hqRoot: opts.hqRoot, env: opts.env, existsSync, readFileSync, writeFileSync, run });
         if (platform === "darwin") {
             const plist = path.join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
             if (!existsSync(plist))

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

@@ -90,6 +90,11 @@ export interface DaemonRunDeps {
     resolveMembership?: (token: string, slug: string, signal?: AbortSignal) => Promise<{
         companyUid: string;
     } | null>;
+    /**
+     * Machine credential (fleet box or local bot). A refused or empty membership
+     * probe defers; it does not clear the company. Defaults to isMachineIdentity().
+     */
+    machineIdentity?: boolean;
     /** Test seam immediately before a device-default revocation's guarded commit. */
     beforeDeviceDefaultRevocationCommit?: () => void;
     log?: (dir: string, line: string) => void;

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

@@ -14,7 +14,7 @@ import * as path from "node:path";
 import { CLI_VERSION } from "../../../../cli-version.js";
 import { createWorkSessionDeliverer } from "../../client.js";
 import { listActiveMembershipCompanies, meshJson, resolveActiveMembershipCompany } from "../../api.js";
-import { ensureCognitoToken } from "../../../../utils/cognito-session.js";
+import { ensureCognitoToken, isMachineIdentity } from "../../../../utils/cognito-session.js";
 import { replayOutbox } from "../../../work-context/outbox.js";
 import { workContextRoot } from "../../../work-context/paths.js";
 import { ensureDefaultCompany } from "../../../work-context/default-company.js";
@@ -137,9 +137,13 @@ export async function runMeshDaemon(deps = {}) {
     // expires after ~1h to every vend/flush forever, so the second credential
     // renewal (~96 min in) and everything after it failed with HTTP 401 and the
     // daemon went dark once its IoT credentials expired.
+    // ensureCognitoToken refuses a refresh whose subject differs from the
+    // active person cache and restores the file. The daemon must not replace
+    // the operator login with another cached session.
     const defaultGetToken = async () => ensureCognitoToken({ interactive: false, tokenSource: "machine" });
     const getToken = deps.getToken ?? defaultGetToken;
     const resolveMembership = deps.resolveMembership ?? resolveActiveMembershipCompany;
+    const machineIdentity = deps.machineIdentity ?? isMachineIdentity();
     /** The sole authorization seam for daemon tenant I/O derived from a device default. */
     const tenantGate = {
         authorize: async (input) => {
@@ -158,9 +162,18 @@ export async function runMeshDaemon(deps = {}) {
                     authorization = await Promise.race([
                         (async () => {
                             const membership = await resolveMembership(await getToken(), slug, controller.signal);
-                            return membership
-                                ? { status: "authorized", uid: membership.companyUid }
-                                : { status: "denied" };
+                            if (membership)
+                                return { status: "authorized", uid: membership.companyUid };
+                            // A machine token often cannot read /membership/me (401/403, or an
+                            // empty person-membership list). That is "cannot tell", not "not
+                            // a member". Leave the company in place and retry.
+                            if (machineIdentity) {
+                                return {
+                                    status: "unavailable",
+                                    error: "membership probe on a machine token did not confirm a company; company left unchanged",
+                                };
+                            }
+                            return { status: "denied" };
                         })(),
                         new Promise((resolve) => {
                             controller.signal.addEventListener("abort", () => resolve({

package/dist/lib/mesh/live/emit-client.d.ts

@@ -23,6 +23,8 @@ export interface EmitEventResult {
     status: EmitEventStatus;
     /** Present when status != accepted (no_company_evidence | not_a_member | …). */
     reason?: string;
+    /** Server rejection code when status is rejected (`code`, else `reason`). */
+    code?: string;
     /** Resolved company (accepted, or unassigned-into-single-company). */
     companyUid?: string;
 }

package/dist/lib/mesh/live/emit-client.js

@@ -58,10 +58,7 @@ export function parseEmitResults(body) {
             if (!status)
                 continue;
             const res = { eventId, status };
-            if (typeof r.reason === "string" && r.reason.trim())
-                res.reason = r.reason.trim();
-            else if (typeof r.code === "string" && r.code.trim())
-                res.reason = r.code.trim();
+            applyEmitReasonAndCode(res, r);
             if (typeof r.companyUid === "string" && r.companyUid.trim()) {
                 res.companyUid = r.companyUid.trim();
             }
@@ -86,16 +83,26 @@ export function parseEmitResults(body) {
                 if (!eventId)
                     continue;
                 const res = { eventId, status: "rejected" };
-                if (typeof r.reason === "string" && r.reason.trim())
-                    res.reason = r.reason.trim();
-                else if (typeof r.code === "string" && r.code.trim())
-                    res.reason = r.code.trim();
+                applyEmitReasonAndCode(res, r);
                 out.push(res);
             }
         }
     }
     return out.length > 0 ? out : null;
 }
+function applyEmitReasonAndCode(res, raw) {
+    const reason = typeof raw.reason === "string" ? raw.reason.trim() : "";
+    const code = typeof raw.code === "string" ? raw.code.trim() : "";
+    if (reason)
+        res.reason = reason;
+    else if (code)
+        res.reason = code;
+    if (res.status !== "rejected")
+        return;
+    const rejectionCode = code || reason;
+    if (rejectionCode)
+        res.code = rejectionCode;
+}
 function normalizeStatus(v) {
     if (typeof v !== "string")
         return null;

package/dist/lib/mesh/live/emit-evidence.d.ts

@@ -37,6 +37,17 @@ export interface BuildEmitEvidenceInput {
     readMeta?: (sessionId: string, hqRoot: string | undefined) => string | undefined;
     /** Injectable work-tree finder (tests). */
     findRepo?: (startDir: string) => string | null;
+    /**
+     * Env for HQ_SPAWN_COMPANY and the identity file. Defaults to empty so a
+     * unit test does not inherit the developer shell. Callers that emit pass
+     * `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable machine-company reader (tests). */
+    readMachineCompany?: (env: NodeJS.ProcessEnv) => {
+        slug?: string;
+        uid?: string;
+    } | undefined;
 }
 /** Dedupe absolute-ish paths, preserving first-seen order. */
 export declare function normalizeTouchedPaths(paths: Array<string | undefined | null>): string[];
@@ -46,4 +57,12 @@ export declare function normalizeTouchedPaths(paths: Array<string | undefined |
  * first touched file). All fields are omitted when empty.
  */
 export declare function buildEmitEvidence(input: BuildEmitEvidenceInput): EmitEvidence;
+/**
+ * A machine credential with no company must not be posted. The server would
+ * file it as company NONE. Hold it instead.
+ */
+export declare function machineEmitDisposition(input: {
+    machine: boolean;
+    companySlug?: string;
+}): "post" | "hold";
 //# sourceMappingURL=emit-evidence.d.ts.map

package/dist/lib/mesh/live/emit-evidence.js

@@ -9,7 +9,7 @@
  * work-tree off disk. Never reads prompts/tokens; never hits the network.
  */
 import * as path from "node:path";
-import { readMetaCompanySlug } from "../../work-context/company.js";
+import { readMachineCompanyBinding, readMetaCompanySlug } from "../../work-context/company.js";
 import { findWorkTreeRoot } from "../../work-context/repo-remote.js";
 function clean(v) {
     return typeof v === "string" && v.trim() ? v.trim() : undefined;
@@ -41,7 +41,16 @@ export function buildEmitEvidence(input) {
     const cwd = clean(input.cwd);
     const hqRoot = clean(input.hqRoot);
     const touchedPaths = normalizeTouchedPaths(input.touchedPaths ?? []);
-    const companySlug = clean(input.companySlug) ?? clean(readMeta(input.sessionId, hqRoot));
+    const env = input.env ?? {};
+    const machine = (input.readMachineCompany ?? readMachineCompanyBinding)(env);
+    const spawned = clean(env.HQ_SPAWN_COMPANY);
+    // Explicit, spawn, session meta, then the box binding (slug, else uid).
+    // A uid with no slug still rides companySlug so the event is not company NONE.
+    const companySlug = clean(input.companySlug) ??
+        spawned ??
+        clean(readMeta(input.sessionId, hqRoot)) ??
+        (machine && machine.slug !== spawned ? clean(machine.slug) : undefined) ??
+        clean(machine?.uid);
     let repoPath = clean(input.repoPath);
     if (!repoPath) {
         // Search from the cwd (a directory) or the directory of the first touched
@@ -69,6 +78,15 @@ export function buildEmitEvidence(input) {
         evidence.task = task;
     return evidence;
 }
+/**
+ * A machine credential with no company must not be posted. The server would
+ * file it as company NONE. Hold it instead.
+ */
+export function machineEmitDisposition(input) {
+    if (input.machine && !clean(input.companySlug))
+        return "hold";
+    return "post";
+}
 /** Directory of the first absolute touched file, for work-tree discovery. */
 function firstFileDir(touchedPaths) {
     const abs = touchedPaths.find((p) => path.isAbsolute(p));

package/dist/lib/mesh/live/emit.d.ts

@@ -47,8 +47,17 @@ export interface EmitEventsSummary {
     retryDepth: number;
     batches: number;
     statuses: Record<EmitEventStatus, number>;
+    /** Server code for each terminally rejected event. */
+    rejections: Array<{
+        eventId: string;
+        code: string;
+    }>;
     lastPostAt?: string;
 }
+export declare function formatEmitRejectionLines(rejections: ReadonlyArray<{
+    eventId: string;
+    code: string;
+}>): string[];
 /** Drain the retry file, post pending + new events, persist failures. */
 export declare function emitEvents(deps: EmitEventsDeps): Promise<EmitEventsSummary>;
 //# sourceMappingURL=emit.d.ts.map

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

@@ -41,9 +41,23 @@ function writeEmitState(workMeshRoot, state) {
         /* best-effort */
     }
 }
+function rejectionCodeFromBody(body, status) {
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+        const rec = body;
+        if (typeof rec.code === "string" && rec.code.trim())
+            return rec.code.trim();
+        if (typeof rec.error === "string" && /^[A-Z0-9_]+$/.test(rec.error.trim())) {
+            return rec.error.trim();
+        }
+    }
+    return `HTTP_${status}`;
+}
 function eventIdOf(e) {
     return typeof e.eventId === "string" && e.eventId.trim() ? e.eventId.trim() : null;
 }
+export function formatEmitRejectionLines(rejections) {
+    return rejections.map((row) => `work-mesh: rejected eventId=${row.eventId} code=${row.code}`);
+}
 /** Drain the retry file, post pending + new events, persist failures. */
 export async function emitEvents(deps) {
     const now = deps.now ?? (() => new Date());
@@ -74,6 +88,7 @@ export async function emitEvents(deps) {
         retryDepth: 0,
         batches: 0,
         statuses: { accepted: 0, unassigned: 0, rejected: 0 },
+        rejections: [],
     };
     const keep = [];
     let anyPosted = false;
@@ -95,7 +110,13 @@ export async function emitEvents(deps) {
                 // Non-retryable 4xx (e.g. 401/400) → drop with a log (never user data).
                 summary.rejected += chunk.length;
                 summary.statuses.rejected += chunk.length;
-                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status}`);
+                const batchCode = rejectionCodeFromBody(result.body, result.status);
+                for (const event of chunk) {
+                    const id = eventIdOf(event);
+                    if (id)
+                        summary.rejections.push({ eventId: id, code: batchCode });
+                }
+                deps.log?.(`emit batch dropped (${chunk.length}) non-retryable status=${result.status} code=${batchCode}`);
             }
             continue;
         }
@@ -121,8 +142,13 @@ export async function emitEvents(deps) {
                 summary.accepted += 1;
             else if (r.status === "unassigned")
                 summary.unassigned += 1;
-            else
+            else if (id) {
                 summary.rejected += 1;
+                summary.rejections.push({
+                    eventId: id,
+                    code: r.code || r.reason || "rejected",
+                });
+            }
         }
     }
     const written = writeEmitRetry(deps.workMeshRoot, keep, retryMax);

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

@@ -92,8 +92,14 @@ function isLocallyReconcilableHeldEvent(event, state, workContextRoot) {
         repoIdentityKey,
     }).status === "resolved");
 }
-function deadLetterEnvelope(event, reason, responseCode, at) {
-    return JSON.stringify({ event, reason, responseCode, at });
+function deadLetterEnvelope(event, reason, responseCode, at, code) {
+    return JSON.stringify({
+        event,
+        reason,
+        responseCode,
+        at,
+        ...(code ? { code } : {}),
+    });
 }
 function groupBySession(events) {
     const map = new Map();
@@ -431,7 +437,7 @@ function accountBatchSuccess(body, originalChunk, meshRoot, now, summary, markDi
         const item = byId.get(row.eventId);
         if (!item)
             continue;
-        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at), meshRoot);
+        appendDeadLetterLine(deadLetterEnvelope(item.event, row.code, row.code, at, row.code), meshRoot);
         summary.deadLettered += 1;
         rejectedIds.add(row.eventId);
         markDisposed(item.event);

package/dist/lib/search-index/index.js

@@ -1,6 +1,5 @@
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
-import { createRequire } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,9 +9,9 @@ import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js
 import { isQmdQueryDocumentError } from '../../utils/qmd-query-document-error.js';
 import { isQmdStoreMissingError } from '../../utils/qmd-store-missing-error.js';
 import { isQmdStoreUnopenableError } from '../../utils/qmd-store-unopenable-error.js';
+import { markExpectedUserError } from '../../utils/expected-cli-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
-const require = createRequire(import.meta.url);
 /** The `path` implementation for a (possibly injected) platform. */
 function pathFor(platform) {
     return platform === 'win32' ? path.win32 : path.posix;
@@ -1005,6 +1004,22 @@ function describeQmdTermination(stdout, stderr) {
         return `qmd reported: ${summary.reason}`;
     return '';
 }
+/**
+ * qmd caller-state failures that the top-level boundary may surface without a
+ * crash report. The match is deliberately against qmd's raw stderr and a
+ * closed subcommand set: a query containing these words must not change the
+ * disposition of an unrelated qmd exit.
+ */
+function isExpectedQmdCallerFailure(args, stderr) {
+    const subcommand = args[0];
+    if (subcommand === 'get') {
+        return /^Document not found:\s+[^\r\n]+$/m.test(stderr);
+    }
+    if (subcommand === 'collection') {
+        return /(?:^|\b)Failed to parse\s+[^\r\n]+:\s*.+$/m.test(stderr);
+    }
+    return false;
+}
 /** Normalise a spawn result and raise the typed qmd failures. */
 function finishRunQmd(result, bin, args, attribution) {
     const normalized = {
@@ -1215,7 +1230,11 @@ function finishRunQmd(result, bin, args, attribution) {
     if (alreadyExists) {
         throw new QmdCollectionExistsError(message, args, normalized.status, normalized.stdout, normalized.stderr, alreadyExists[1]);
     }
-    throw new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    const exitError = new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    if (isExpectedQmdCallerFailure(args, normalized.stderr)) {
+        throw markExpectedUserError(exitError);
+    }
+    throw exitError;
 }
 /** Run qmd with captured output and typed failures. */
 export function runQmd(args, options = {}) {

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

@@ -77,7 +77,23 @@ export declare const DEFAULT_AGENT_IDENTITY_FILE = "/var/lib/hq-agent/identity.j
  * Missing/unreadable/malformed → undefined
  * (never throws; never logs file contents).
  */
+export interface AgentIdentityCompany {
+    uid?: string;
+    slug?: string;
+}
+/** Company uid and slug from the fleet identity file. Missing file → undefined. */
+export declare function readAgentIdentityCompany(env?: NodeJS.ProcessEnv): AgentIdentityCompany | undefined;
 export declare function readAgentIdentityCompanyUid(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Company named for a machine session.
+ * Order: HQ_SPAWN_COMPANY, identity-file slug, identity-file uid.
+ * Session meta is not included; callers place it between spawn and the file.
+ * No company → undefined. Never invents NONE.
+ */
+export declare function readMachineCompanyBinding(env?: NodeJS.ProcessEnv): {
+    slug?: string;
+    uid?: string;
+} | undefined;
 /**
  * Agent boxes must never infer a human device default. The file itself is the
  * machine marker; legacy identity files do not necessarily contain a company

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

@@ -38,13 +38,7 @@ function normalizeSlug(value) {
         return undefined;
     return s;
 }
-/**
- * Read `companyUid` from the agent identity file when
- * `HQ_AGENT_IDENTITY_FILE` is set, or the conventional fleet path otherwise.
- * Missing/unreadable/malformed → undefined
- * (never throws; never logs file contents).
- */
-export function readAgentIdentityCompanyUid(env = process.env) {
+function readAgentIdentityRecord(env) {
     // An explicit override (including empty/missing paths) never falls back to
     // another identity. This prevents accidental attribution to a different box.
     const file = (env[HQ_AGENT_IDENTITY_FILE_ENV] ?? DEFAULT_AGENT_IDENTITY_FILE).trim();
@@ -54,15 +48,49 @@ export function readAgentIdentityCompanyUid(env = process.env) {
         if (!fs.existsSync(file))
             return undefined;
         const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-        const uid = raw.companyUid;
-        return typeof uid === "string" && uid.trim().length > 0
-            ? uid.trim()
-            : undefined;
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return undefined;
+        return raw;
     }
     catch {
         return undefined;
     }
 }
+/** Company uid and slug from the fleet identity file. Missing file → undefined. */
+export function readAgentIdentityCompany(env = process.env) {
+    const raw = readAgentIdentityRecord(env);
+    if (!raw)
+        return undefined;
+    const uid = typeof raw.companyUid === "string" ? raw.companyUid.trim() : "";
+    const slug = normalizeSlug(typeof raw.companySlug === "string" ? raw.companySlug : undefined);
+    if (!uid && !slug)
+        return undefined;
+    return {
+        ...(uid ? { uid } : {}),
+        ...(slug ? { slug } : {}),
+    };
+}
+export function readAgentIdentityCompanyUid(env = process.env) {
+    return readAgentIdentityCompany(env)?.uid;
+}
+/**
+ * Company named for a machine session.
+ * Order: HQ_SPAWN_COMPANY, identity-file slug, identity-file uid.
+ * Session meta is not included; callers place it between spawn and the file.
+ * No company → undefined. Never invents NONE.
+ */
+export function readMachineCompanyBinding(env = process.env) {
+    const spawn = normalizeSlug(env.HQ_SPAWN_COMPANY);
+    const identity = readAgentIdentityCompany(env);
+    if (spawn)
+        return { slug: spawn, ...(identity?.uid ? { uid: identity.uid } : {}) };
+    if (!identity?.slug && !identity?.uid)
+        return undefined;
+    return {
+        ...(identity?.slug ? { slug: identity.slug } : {}),
+        ...(identity?.uid ? { uid: identity.uid } : {}),
+    };
+}
 /**
  * Agent boxes must never infer a human device default. The file itself is the
  * machine marker; legacy identity files do not necessarily contain a company
@@ -273,11 +301,15 @@ export function resolveCompany(input) {
     // 4. Agent-box identity file (HQ_AGENT_IDENTITY_FILE). Prefer as the
     // device-default role with source trusted_explicit — never device_default /
     // "default company mode". Below HQ_SPAWN_COMPANY; above device default.
-    const identityUid = readAgentIdentityCompanyUid(env);
-    if (identityUid) {
+    const identity = readAgentIdentityCompany(env);
+    if (identity?.uid || identity?.slug) {
         return {
             status: "resolved",
-            company: { uid: identityUid, source: "trusted_explicit" },
+            company: {
+                ...(identity.slug ? { slug: identity.slug } : {}),
+                ...(identity.uid ? { uid: identity.uid } : {}),
+                source: "trusted_explicit",
+            },
         };
     }
     // 4b. Persisted per-repo company map (gap 4). A person answered once for this

package/dist/lib/work-context/preflight-contract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Offline preflight ContextResult shapes that `hq mesh context reconcile --offline`
+ * can emit. migration_pending is a migrate-path status, not a preflight result.
+ *
+ * contractVersion is WORK_CONTEXT_CONTRACT_VERSION. Bump it only together with
+ * contracts/preflight/v<N>/ and the vendored copy in hq-core
+ * (core/hooks/SessionStart/preflight-fixtures.json). Each side pins the version
+ * in tests; a one-sided bump fails that side until the other is updated.
+ */
+import { type ContextResult } from "./contract.js";
+export declare const PREFLIGHT_CONTRACT_VERSION: 1;
+/** Classifications reconcile actually returns on the offline preflight path. */
+export declare const OFFLINE_PREFLIGHT_CLASSIFICATIONS: readonly ["unresolved", "needs_company", "company_conflict", "needs_project", "needs_task", "bound", "untracked"];
+export type OfflinePreflightClassification = (typeof OFFLINE_PREFLIGHT_CLASSIFICATIONS)[number];
+/**
+ * One representative result per emitted classification, using the kind and
+ * delivery the offline path actually returns (company-resolved results are
+ * kind "queued" / delivery "queued"; local-only results are delivery "clean").
+ */
+export declare function preflightFixtureFor(classification: OfflinePreflightClassification): ContextResult;
+export interface PreflightFixtureFile {
+    contractVersion: typeof PREFLIGHT_CONTRACT_VERSION;
+    source: "hq-cli contracts/preflight/v1/fixtures.json";
+    classifications: readonly OfflinePreflightClassification[];
+    fixtures: ContextResult[];
+}
+export declare function buildPreflightFixtures(): PreflightFixtureFile;
+//# sourceMappingURL=preflight-contract.d.ts.map