@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/test-utils/isolated-flag-company-context.js

@@ -0,0 +1,18 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { vi } from "vitest";
+/** Keep process-wide flag tests independent of the developer machine binding. */
+export function isolateFlagCompanyContext() {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "hq-flag-company-context-"));
+    vi.stubEnv("HOME", home);
+    vi.stubEnv("HQ_COMPANY_UID", undefined);
+    vi.stubEnv("HQ_COMPANY_SLUG", undefined);
+    vi.stubEnv("HQ_SPAWN_COMPANY", undefined);
+    vi.stubEnv("HQ_SESSION_ID", undefined);
+    vi.stubEnv("HQ_AGENT_IDENTITY_FILE", "");
+    vi.stubEnv("HQ_ROOT", undefined);
+    vi.stubEnv("HQ_WORK_CONTEXT_ROOT", undefined);
+    return () => fs.rmSync(home, { recursive: true, force: true });
+}
+//# sourceMappingURL=isolated-flag-company-context.js.map

package/dist/lib/work-context/bind-best.d.ts

@@ -0,0 +1,66 @@
+/**
+ * US-036: pick the best existing project for a session hint.
+ * Exact Board, then exact local PRD, then a ranked match.
+ * A tie or an empty field stays unbound so the session can ask.
+ */
+export interface BindCandidate {
+    projectId: string;
+    title?: string;
+    score: number;
+}
+export interface CatalogProject {
+    projectId: string;
+    title?: string;
+    repos: string[];
+    journalMtimeMs?: number;
+    hasPrd: boolean;
+    hasBoard: boolean;
+    prdPath?: string;
+}
+export type RefineAction = {
+    action: "keep";
+} | {
+    action: "bind";
+    projectId: string;
+    reason: string;
+} | {
+    action: "create";
+    projectId: string;
+    prdPath: string;
+    reason: string;
+} | {
+    action: "ask";
+    reason: string;
+    candidates: BindCandidate[];
+};
+export declare function scoreProject(hint: string, row: CatalogProject, repoPath: string | undefined, nowMs: number): number;
+export declare function discoverProjects(input: {
+    hqRoot?: string;
+    companySlug?: string;
+    companyUid?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): CatalogProject[];
+/** discoverProjects memoized by directory mtime. A cache hit does not rescan. */
+export declare function discoverProjectsCached(input: Parameters<typeof discoverProjects>[0], nowMs?: number): CatalogProject[];
+export declare function refineProjectBinding(input: {
+    hint?: string;
+    hqRoot?: string;
+    companySlug?: string;
+    companyUid?: string;
+    repoPath?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    nowMs?: number;
+}): RefineAction;
+export declare function findLocalPrd(hqRoot: string | undefined, companySlug: string | undefined, projectId: string): string | null;
+export declare function listNeedsProjectSessions(workContextRoot: string): Array<{
+    sessionId: string;
+    reason?: string;
+    candidates: BindCandidate[];
+}>;
+export declare function formatProjectAsk(candidates: Array<{
+    projectId: string;
+    title?: string;
+}>): string;
+//# sourceMappingURL=bind-best.d.ts.map

package/dist/lib/work-context/bind-best.js

@@ -0,0 +1,344 @@
+/**
+ * US-036: pick the best existing project for a session hint.
+ * Exact Board, then exact local PRD, then a ranked match.
+ * A tie or an empty field stays unbound so the session can ask.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { meshCacheRoot } from "../mesh/cache.js";
+const MARGIN = 15;
+const CLEAR_FLOOR = 25;
+const DAY_MS = 24 * 60 * 60 * 1000;
+function tokens(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((part) => part.length > 2);
+}
+export function scoreProject(hint, row, repoPath, nowMs) {
+    const hintL = hint.toLowerCase();
+    const idL = row.projectId.toLowerCase();
+    let score = 0;
+    if (idL === hintL)
+        score += 100;
+    else if (idL.startsWith(hintL) || hintL.startsWith(idL))
+        score += 40;
+    const hintTokens = new Set(tokens(hint));
+    const titleTokens = new Set(tokens(`${row.projectId} ${row.title ?? ""}`));
+    for (const token of hintTokens) {
+        if (titleTokens.has(token))
+            score += 15;
+    }
+    if (repoPath) {
+        const repoL = repoPath.toLowerCase();
+        if (row.repos.some((repo) => {
+            const item = repo.toLowerCase();
+            return item.length > 0 && (repoL.includes(item) || item.includes(repoL));
+        })) {
+            score += 50;
+        }
+    }
+    if (row.journalMtimeMs) {
+        const age = nowMs - row.journalMtimeMs;
+        if (age >= 0 && age < 14 * DAY_MS)
+            score += 10;
+        else if (age >= 0 && age < 60 * DAY_MS)
+            score += 5;
+    }
+    return score;
+}
+function readJson(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isInactiveProject(hqRoot, project) {
+    if (!hqRoot || !project.prdPath)
+        return false;
+    const state = readJson(path.join(hqRoot, "workspace", "orchestrator", project.projectId, "state.json"));
+    const status = typeof state?.status === "string" ? state.status.trim().toLowerCase() : "";
+    if (status !== "archived" && status !== "retired")
+        return false;
+    if (typeof state?.prd_path !== "string" || !state.prd_path.trim())
+        return false;
+    return path.resolve(hqRoot, state.prd_path) === path.resolve(project.prdPath);
+}
+function reposFromMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object")
+        return [];
+    const repos = metadata.repos;
+    if (!Array.isArray(repos))
+        return [];
+    const out = [];
+    for (const repo of repos) {
+        if (typeof repo === "string" && repo.trim())
+            out.push(repo.trim());
+        else if (repo && typeof repo === "object" && typeof repo.path === "string") {
+            const value = repo.path.trim();
+            if (value)
+                out.push(value);
+        }
+    }
+    return out;
+}
+function journalMtime(dir) {
+    const candidates = ["journal.md", "journal.json", path.join("journal", "index.md")];
+    let newest = 0;
+    for (const name of candidates) {
+        try {
+            const stat = fs.statSync(path.join(dir, name));
+            if (stat.mtimeMs > newest)
+                newest = stat.mtimeMs;
+        }
+        catch {
+            /* absent */
+        }
+    }
+    try {
+        const journalDir = path.join(dir, "journal");
+        for (const name of fs.readdirSync(journalDir)) {
+            const stat = fs.statSync(path.join(journalDir, name));
+            if (stat.mtimeMs > newest)
+                newest = stat.mtimeMs;
+        }
+    }
+    catch {
+        /* absent */
+    }
+    return newest > 0 ? newest : undefined;
+}
+function absorbDir(map, dir, projectId) {
+    const prdPath = path.join(dir, "prd.json");
+    const prd = fs.existsSync(prdPath) ? readJson(prdPath) : null;
+    const current = map.get(projectId) ?? {
+        projectId,
+        repos: [],
+        hasPrd: false,
+        hasBoard: false,
+    };
+    if (prd) {
+        current.hasPrd = true;
+        current.prdPath = prdPath;
+        const title = typeof prd.name === "string" ? prd.name
+            : typeof prd.title === "string" ? prd.title
+                : undefined;
+        if (title)
+            current.title = title;
+        const repos = reposFromMetadata(prd.metadata);
+        if (repos.length)
+            current.repos = repos;
+    }
+    const journal = journalMtime(dir);
+    if (journal)
+        current.journalMtimeMs = Math.max(current.journalMtimeMs ?? 0, journal);
+    map.set(projectId, current);
+}
+function listProjectDirs(parent, map) {
+    if (!fs.existsSync(parent))
+        return;
+    let names;
+    try {
+        names = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+            continue;
+        const dir = path.join(parent, name);
+        try {
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        absorbDir(map, dir, name);
+    }
+}
+export function discoverProjects(input) {
+    const map = new Map();
+    const hqRoot = input.hqRoot?.trim();
+    const slug = input.companySlug?.trim();
+    if (hqRoot && slug) {
+        listProjectDirs(path.join(hqRoot, "companies", slug, "projects"), map);
+        listProjectDirs(path.join(hqRoot, "personal", "projects"), map);
+    }
+    if (input.companyUid) {
+        const cache = path.join(meshCacheRoot(input.home ?? os.homedir(), input.env), "projects", input.companyUid);
+        if (fs.existsSync(cache)) {
+            for (const name of fs.readdirSync(cache)) {
+                if (!name.endsWith(".json"))
+                    continue;
+                const projectId = name.slice(0, -".json".length);
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(projectId))
+                    continue;
+                const view = readJson(path.join(cache, name));
+                const current = map.get(projectId) ?? {
+                    projectId,
+                    repos: [],
+                    hasPrd: false,
+                    hasBoard: false,
+                };
+                current.hasBoard = true;
+                const title = typeof view?.name === "string" ? view.name : undefined;
+                if (title && !current.title)
+                    current.title = title;
+                const repos = Array.isArray(view?.repos) ? reposFromMetadata({ repos: view?.repos }) : [];
+                if (repos.length && current.repos.length === 0)
+                    current.repos = repos;
+                map.set(projectId, current);
+            }
+        }
+    }
+    return [...map.values()];
+}
+const CATALOG_CACHE_TTL_MS = 5000;
+let catalogCache = null;
+function catalogStamp(input) {
+    const hqRoot = input.hqRoot?.trim();
+    const slug = input.companySlug?.trim();
+    const dirs = [
+        hqRoot && slug ? path.join(hqRoot, "companies", slug, "projects") : "",
+        hqRoot ? path.join(hqRoot, "personal", "projects") : "",
+        input.companyUid
+            ? path.join(meshCacheRoot(input.home ?? os.homedir(), input.env), "projects", input.companyUid)
+            : "",
+    ];
+    return dirs.map((dir) => {
+        if (!dir)
+            return "0";
+        try {
+            return String(fs.statSync(dir).mtimeMs);
+        }
+        catch {
+            return "0";
+        }
+    }).join("|");
+}
+/** discoverProjects memoized by directory mtime. A cache hit does not rescan. */
+export function discoverProjectsCached(input, nowMs = Date.now()) {
+    const key = `${input.hqRoot ?? ""}|${input.companySlug ?? ""}|${input.companyUid ?? ""}|${input.home ?? ""}|${catalogStamp(input)}`;
+    if (catalogCache && catalogCache.key === key && nowMs - catalogCache.at < CATALOG_CACHE_TTL_MS) {
+        return catalogCache.rows;
+    }
+    const rows = discoverProjects(input);
+    catalogCache = { key, at: nowMs, rows };
+    return rows;
+}
+export function refineProjectBinding(input) {
+    const hint = input.hint?.trim();
+    if (!hint)
+        return { action: "keep" };
+    const catalog = discoverProjectsCached(input, input.nowMs ?? Date.now())
+        .filter((project) => !isInactiveProject(input.hqRoot?.trim(), project));
+    const exact = catalog.find((row) => row.projectId === hint);
+    if (exact?.hasBoard) {
+        return { action: "bind", projectId: hint, reason: "exact slug has a Board" };
+    }
+    if (exact?.hasPrd && exact.prdPath) {
+        return {
+            action: "create",
+            projectId: hint,
+            prdPath: exact.prdPath,
+            reason: "exact slug has a local PRD; Board created from that PRD",
+        };
+    }
+    if (catalog.length === 0)
+        return { action: "keep" };
+    const nowMs = input.nowMs ?? Date.now();
+    const ranked = catalog
+        .filter((row) => row.projectId !== hint)
+        .map((row) => ({
+        projectId: row.projectId,
+        title: row.title,
+        score: scoreProject(hint, row, input.repoPath, nowMs),
+    }))
+        .filter((row) => row.score > 0)
+        .sort((a, b) => b.score - a.score || a.projectId.localeCompare(b.projectId));
+    if (ranked.length === 0) {
+        return {
+            action: "ask",
+            reason: `no project matches ${hint}`,
+            candidates: [],
+        };
+    }
+    const top = ranked[0];
+    const second = ranked[1];
+    const clear = top.score >= CLEAR_FLOOR && (!second || top.score - second.score >= MARGIN);
+    if (clear) {
+        return {
+            action: "bind",
+            projectId: top.projectId,
+            reason: `best match for ${hint}: ${top.projectId} (score ${top.score})`,
+        };
+    }
+    return {
+        action: "ask",
+        reason: `unclear match for ${hint}`,
+        candidates: ranked.slice(0, 5).map((row) => ({
+            projectId: row.projectId,
+            ...(row.title ? { title: row.title } : {}),
+            score: row.score,
+        })),
+    };
+}
+export function findLocalPrd(hqRoot, companySlug, projectId) {
+    if (!hqRoot || !companySlug)
+        return null;
+    const candidates = [
+        path.join(hqRoot, "companies", companySlug, "projects", projectId, "prd.json"),
+        path.join(hqRoot, "personal", "projects", projectId, "prd.json"),
+    ];
+    return candidates.find((file) => fs.existsSync(file)) ?? null;
+}
+export function listNeedsProjectSessions(workContextRoot) {
+    const dir = path.join(workContextRoot, "sessions");
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const raw = readJson(path.join(dir, name));
+        if (!raw || raw.contextStatus !== "needs_project")
+            continue;
+        const sessionId = typeof raw.sessionId === "string" ? raw.sessionId : name.replace(/\.json$/, "");
+        const candidates = Array.isArray(raw.projectCandidates)
+            ? raw.projectCandidates.flatMap((item) => {
+                if (!item || typeof item !== "object")
+                    return [];
+                const projectId = item.projectId;
+                if (typeof projectId !== "string" || !projectId)
+                    return [];
+                const title = item.title;
+                const score = item.score;
+                return [{
+                        projectId,
+                        ...(typeof title === "string" ? { title } : {}),
+                        score: typeof score === "number" ? score : 0,
+                    }];
+            })
+            : [];
+        out.push({
+            sessionId,
+            ...(typeof raw.projectBindReason === "string" ? { reason: raw.projectBindReason } : {}),
+            candidates,
+        });
+    }
+    return out.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+}
+export function formatProjectAsk(candidates) {
+    const parts = candidates.map((candidate, index) => {
+        const title = candidate.title?.trim() || candidate.projectId;
+        return `${index + 1}) ${candidate.projectId} ${title}`;
+    });
+    return `This session is not bound to a project. Best matches: ${parts.join(" ")}. Reply with a number, a project id, or \`new <slug>\`.`;
+}
+//# sourceMappingURL=bind-best.js.map

package/dist/lib/work-context/bind-calling-session.d.ts

@@ -0,0 +1,26 @@
+/**
+ * US-040: when this process ensures a project, bind the calling session
+ * if it is still unresolved in the same company. Never move a session
+ * that is already on a different project.
+ */
+export interface CallingCompany {
+    companyUid: string;
+    companySlug: string;
+}
+export type BindCallingResult = {
+    bound: true;
+    sessionId: string;
+    projectId: string;
+} | {
+    bound: false;
+    reason: "no_session" | "no_state" | "company_mismatch" | "different_project" | "already_bound" | "not_unresolved";
+};
+export declare function bindCallingSession(input: {
+    root: string;
+    env?: NodeJS.ProcessEnv;
+    projectId: string;
+    company: CallingCompany;
+    now?: () => Date;
+}): BindCallingResult;
+export declare function formatSessionBoundLine(sessionId: string, projectId: string): string;
+//# sourceMappingURL=bind-calling-session.d.ts.map

package/dist/lib/work-context/bind-calling-session.js

@@ -0,0 +1,63 @@
+/**
+ * US-040: when this process ensures a project, bind the calling session
+ * if it is still unresolved in the same company. Never move a session
+ * that is already on a different project.
+ */
+import { sessionIdFromEnv } from "../mesh/live/session-identity.js";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+import { readSessionState, updateSessionState } from "./state.js";
+function sameCompany(state, company) {
+    if (state.companyUid && state.companyUid === company.companyUid)
+        return true;
+    if (state.companySlug &&
+        company.companySlug &&
+        state.companySlug.toLowerCase() === company.companySlug.toLowerCase()) {
+        return true;
+    }
+    return false;
+}
+export function bindCallingSession(input) {
+    const sessionId = sessionIdFromEnv(input.env ?? process.env);
+    if (!sessionId)
+        return { bound: false, reason: "no_session" };
+    const current = readSessionState(sessionId, input.root);
+    if (!current)
+        return { bound: false, reason: "no_state" };
+    if (!sameCompany(current, input.company))
+        return { bound: false, reason: "company_mismatch" };
+    if (current.projectId && current.projectId !== input.projectId) {
+        return { bound: false, reason: "different_project" };
+    }
+    if (current.projectId === input.projectId && (current.contextStatus === "bound" || current.contextStatus === "needs_task")) {
+        return { bound: false, reason: "already_bound" };
+    }
+    if (current.contextStatus !== "needs_project" && current.contextStatus !== "unresolved") {
+        return { bound: false, reason: "not_unresolved" };
+    }
+    const nowIso = (input.now ?? (() => new Date()))().toISOString();
+    const updated = updateSessionState(sessionId, input.root, (state) => {
+        if (!state)
+            return null;
+        if (state.projectId && state.projectId !== input.projectId)
+            return state;
+        return {
+            ...state,
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            contextStatus: state.taskId ? "bound" : "needs_task",
+            projectId: input.projectId,
+            projectGate: undefined,
+            projectCandidates: undefined,
+            projectHint: undefined,
+            projectBindReason: `bound by project ensure to ${input.projectId}`,
+            updatedAt: nowIso,
+        };
+    });
+    if (!updated || updated.projectId !== input.projectId) {
+        return { bound: false, reason: "different_project" };
+    }
+    return { bound: true, sessionId, projectId: input.projectId };
+}
+export function formatSessionBoundLine(sessionId, projectId) {
+    return `Work mesh: session ${sessionId} bound to project ${projectId}`;
+}
+//# sourceMappingURL=bind-calling-session.js.map

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)
@@ -19,14 +20,12 @@
  */
 import type { TrustedExplicitContext } from "./contract.js";
 import { type SessionStateFile } from "./state.js";
-export type CompanyResolutionSource = "trusted_explicit" | "existing_scope" | "session_meta" | "repo_map" | "device_default" | "deterministic_cwd" | "deterministic_remote";
+type CompanyResolutionSource = "trusted_explicit" | "existing_scope" | "session_meta" | "repo_map" | "device_default" | "deterministic_cwd" | "deterministic_remote";
 export interface ResolvedCompany {
     slug?: string;
     uid?: string;
     source: CompanyResolutionSource;
 }
-/** Pointer to the US-017B correction client (never auto-switches). */
-export declare const COMPANY_CORRECTION_PATH_PREFIX = "hq mesh context correct --session";
 export declare function companyCorrectionPath(sessionId: string): string;
 export type CompanyResolution = {
     status: "resolved";
@@ -65,17 +64,29 @@ export interface CompanyResolveInput {
      * session-meta. Omitted (or unmapped) → the ladder falls through unchanged.
      */
     repoIdentityKey?: string | null;
+    /** Explicit historical repair may disable weak device-default evidence. */
+    allowDeviceDefault?: boolean;
 }
 /** Env naming the on-box identity.json (fleet agent boxes). */
 export declare const HQ_AGENT_IDENTITY_FILE_ENV = "HQ_AGENT_IDENTITY_FILE";
 export declare const DEFAULT_AGENT_IDENTITY_FILE = "/var/lib/hq-agent/identity.json";
+export declare function readAgentIdentityCompanyUid(env?: NodeJS.ProcessEnv): string | undefined;
 /**
- * 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).
+ * 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 readAgentIdentityCompanyUid(env?: NodeJS.ProcessEnv): string | undefined;
+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
+ * UID, so parsing for that field is not an eligibility check.
+ */
+export declare function hasAgentIdentityFile(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Compare companies: UIDs when both sides have them; otherwise normalized
  * slugs when both have slugs. Never treat uid+slug vs slug-only as a
@@ -101,15 +112,6 @@ export declare function projectIdFromCwd(cwd: string | undefined, hqRoot?: strin
  * Read company_slug from workspace/sessions/<sid>/meta.yaml (best-effort, no yaml dep).
  */
 export declare function readMetaCompanySlug(sessionId: string, hqRoot: string | undefined): string | undefined;
-/**
- * Deterministic mapping: exactly one of cwd companies/{slug} or remote owner.
- * Multiple distinct signals that disagree → no deterministic mapping (needs_company
- * unless a higher-precedence source exists). Matching signals collapse to one.
- */
-export declare function resolveDeterministicCompany(input: {
-    cwd?: string;
-    hqRoot?: string;
-    remoteOwnerSlug?: string | null;
-}): ResolvedCompany | null;
 export declare function resolveCompany(input: CompanyResolveInput): CompanyResolution;
+export {};
 //# sourceMappingURL=company.d.ts.map