@indigoai-us/hq-cli 5.345.134 → 5.345.136

package/dist/lib/doctor/fix/apply.js

@@ -46,7 +46,7 @@ import { removeStrayGateEntries } from "../stray-gate-entries.js";
 import { deriveRemediation } from "./remediation.js";
 import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
-import { buildBotDaemonPaths, rewriteBotDaemonNodePath } from "../../bot/daemon.js";
+import { buildBotDaemonPaths, installedDaemonHqBinary, repairBotDaemonIfStale, rewriteBotDaemonNodePath, } from "../../bot/daemon.js";
 import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 import { readRefreshSyncProgress, writeRefreshSyncCursor, writeRefreshSyncLastRun, } from "./refresh-sync-progress.js";
 import { clientHealthShowManualOnlyEnabled } from "../client-health-reason-codes-flag.js";
@@ -130,6 +130,7 @@ export async function applyFixes(options) {
     const collect = options.runChecks ?? defaultRunChecks;
     const refreshSync = options.refreshSync ?? defaultRefreshSync;
     const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
+    const repairBotHqBinary = options.repairBotHqBinary ?? defaultRepairBotHqBinary;
     // 2. Collect findings, then plan each newly unlocked allowlisted repair.
     //    Identity is deliberately the check id + target pair: an unsuccessful
     //    repair must not be applied repeatedly in one invocation.
@@ -154,7 +155,7 @@ export async function applyFixes(options) {
             const rem = deriveRemediation(result);
             if (!rem?.autoFixable)
                 continue;
-            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath);
+            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath, repairBotHqBinary);
             if (!plan)
                 continue;
             const key = JSON.stringify([plan.checkId, plan.target]);
@@ -421,10 +422,12 @@ export function uncommittedHookConfigChanges(hqRoot) {
 }
 // --- Fix planning --------------------------------------------------------------
 /** Build the concrete plan for one auto-fixable finding, or null if unplannable. */
-function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath) {
+function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath, repairBotHqBinary = defaultRepairBotHqBinary) {
     switch (rem.fixClass) {
         case "bot-node-path":
             return planBotNodePath(result, rem, rewriteBotNodePath);
+        case "bot-hq-binary":
+            return planBotHqBinary(result, rem, repairBotHqBinary);
         case "executable-bit":
             return planExecutableBit(hqRoot, result, rem);
         case "gate-profile":
@@ -467,6 +470,63 @@ export function defaultRewriteBotNodePath(name) {
         return null;
     return rewriteBotDaemonNodePath(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot, hqBinary: "hq" }), { platform: "darwin" });
 }
+/** Reinstall one bot LaunchAgent whose hq binary is missing. */
+function planBotHqBinary(result, rem, repair) {
+    const name = rem.fixTarget;
+    if (!name)
+        return null;
+    return {
+        checkId: result.checkId,
+        fixClass: "bot-hq-binary",
+        target: name,
+        relpath: "",
+        preview: `  ~/Library/LaunchAgents/ai.getindigo.hq-bot.${name}.plist\n` +
+            `    ~ hq path -> the installed hq (same as hq bot daemon install ${name})\n` +
+            `      the agent is reloaded; its old hq path is missing, so it was not running`,
+        summary: `reinstall ${name} startup agent against the installed hq`,
+        apply: () => {
+            repair(name);
+        },
+        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
+    };
+}
+/** Real launchctl for the `bot-hq-binary` reload; a failure is a non-ok result. */
+const doctorLaunchctl = (args) => {
+    const r = spawnSync("launchctl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return { ok: r.status === 0, stdout: String(r.stdout ?? ""), stderr: String(r.stderr ?? r.error?.message ?? "") };
+};
+/**
+ * An hq path a bot may be pointed at unattended: an installed package entry
+ * or its stable shim, never a worktree or one-off build that happens to be
+ * running `hq doctor --fix`.
+ */
+export function isInstalledHqBinary(hqBinary) {
+    const normalized = hqBinary.replace(/\\/g, "/");
+    if (/\/node_modules\/@indigoai-us\/hq-cli\//i.test(normalized))
+        return true;
+    return /\/bin\/hq(\.cmd)?$/i.test(normalized);
+}
+/** Default `bot-hq-binary` repair against the real bot state and LaunchAgents. */
+export function defaultRepairBotHqBinary(name) {
+    if (process.platform !== "darwin")
+        return null;
+    const dir = botDir(name);
+    const config = readBotConfig(dir);
+    if (!config)
+        return null;
+    const paths = buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot });
+    if (!isInstalledHqBinary(paths.hqBinary) || !fs.existsSync(paths.hqBinary))
+        return null;
+    let from;
+    try {
+        from = installedDaemonHqBinary(paths);
+    }
+    catch {
+        from = null;
+    }
+    const repaired = repairBotDaemonIfStale(paths, { launchctl: doctorLaunchctl });
+    return repaired ? { from, to: paths.hqBinary } : null;
+}
 /** Pull one company or the personal vault to refresh a stale journal. */
 function planRefreshSync(hqRoot, result, rem, refreshSync) {
     const slug = rem.fixTarget;

package/dist/lib/doctor/fix/remediation.d.ts

@@ -40,7 +40,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "bot-node-path";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "bot-node-path" | "bot-hq-binary";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle

package/dist/lib/doctor/fix/remediation.js

@@ -119,6 +119,22 @@ export function deriveRemediation(result) {
             command: remediation ?? `hq bot start ${target}`,
         };
     }
+    // bot-hq-binary — a bot LaunchAgent whose hq path no longer exists (an
+    // update moved or removed it), so launchd cannot start the bot. The repair
+    // is what `hq bot daemon install <name>` does: rewrite the agent against
+    // the installed hq and reload it. A job whose hq is missing is not running a
+    // turn, so the reload cuts nothing short (feedback_c441dd9a).
+    const botBinary = /^bots\.(.+)\.daemon-binary$/.exec(checkId);
+    if (botBinary && result.status === "FAIL") {
+        const name = botBinary[1];
+        return {
+            autoFixable: true,
+            fixClass: "bot-hq-binary",
+            fixTarget: name,
+            action: `Reinstall the ${name} startup agent against the installed hq binary and reload it.`,
+            command: remediation ?? `hq bot daemon install ${name}`,
+        };
+    }
     // Available hq-core upgrade. WARN is intentional in `hq doctor` and is
     // not a broken sync; --fix has no mechanical repair for it.
     if (checkId === "sync.update.core") {

package/dist/lib/doctor/shared.d.ts

@@ -1,6 +1,16 @@
 /** Collect every `command` string from a `{hooks:{Event:[{hooks:[…]}]}}` doc. */
 export declare function collectCommands(parsed: unknown): string[];
-export declare function fileState(target: string): {
+/**
+ * Whether a file mode counts as executable for a hook check.
+ *
+ * Windows has no POSIX execute bit: Node reports 0o666 for every regular file
+ * that is not a .exe/.cmd/.bat/.com, and the hook runtimes start HQ's shell
+ * hooks through bash, which never consults it. A mode check there can only
+ * produce false FAILs (feedback_a60339e8, 27 of them on one install), so
+ * win32 treats every present file as executable.
+ */
+export declare function modeIsExecutable(mode: number, platform?: NodeJS.Platform): boolean;
+export declare function fileState(target: string, platform?: NodeJS.Platform): {
     present: boolean;
     executable: boolean;
 };

package/dist/lib/doctor/shared.js

@@ -23,10 +23,24 @@ export function collectCommands(parsed) {
     }
     return commands;
 }
-export function fileState(target) {
+/**
+ * Whether a file mode counts as executable for a hook check.
+ *
+ * Windows has no POSIX execute bit: Node reports 0o666 for every regular file
+ * that is not a .exe/.cmd/.bat/.com, and the hook runtimes start HQ's shell
+ * hooks through bash, which never consults it. A mode check there can only
+ * produce false FAILs (feedback_a60339e8, 27 of them on one install), so
+ * win32 treats every present file as executable.
+ */
+export function modeIsExecutable(mode, platform = process.platform) {
+    if (platform === "win32")
+        return true;
+    return (mode & 0o111) !== 0;
+}
+export function fileState(target, platform = process.platform) {
     try {
         const stat = fs.statSync(target);
-        return { present: stat.isFile(), executable: (stat.mode & 0o111) !== 0 };
+        return { present: stat.isFile(), executable: modeIsExecutable(stat.mode, platform) };
     }
     catch {
         return { present: false, executable: false };

package/dist/lib/fingerprint/fixtures.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared fingerprint test vectors. hq-pro (US-006) copies this list so the CLI
+ * and the server agree on what a valid fingerprint is.
+ */
+import type { FingerprintParts } from "./format.js";
+export interface ValidFingerprintVector {
+    name: string;
+    parts: FingerprintParts;
+    value: string;
+}
+export interface InvalidFingerprintVector {
+    name: string;
+    value: string;
+}
+export declare const FINGERPRINT_TEST_VECTORS: {
+    valid: ValidFingerprintVector[];
+    invalid: InvalidFingerprintVector[];
+};
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/lib/fingerprint/fixtures.js

@@ -0,0 +1,61 @@
+export const FINGERPRINT_TEST_VECTORS = {
+    valid: [
+        {
+            name: "person on a laptop",
+            parts: {
+                company: "indigo",
+                identityUid: "prs_01J8ZK4Q7M2N3P4R5S6T7V8W9X",
+                hostKind: "laptop",
+                machineId: "e3ef5a5a-f51d-435d-90b9-dd876caa249b",
+                sessionId: "fabb19c9-95a7-48a4-9a95-f77e28d0e3db",
+            },
+            value: "hqfp1:indigo:prs_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9",
+        },
+        {
+            name: "agent on a fleet box",
+            parts: {
+                company: "acme",
+                identityUid: "agt_01JA0000000000000000000000",
+                hostKind: "fleet",
+                machineId: "0123456789abcdef",
+                sessionId: "sess-1",
+            },
+            value: "hqfp1:acme:agt_01JA0000:fleet.01234567:sess-1",
+        },
+        {
+            name: "outpost with no company",
+            parts: {
+                company: null,
+                identityUid: "prs_01J8ZK4Q7M2N3P4R5S6T7V8W9X",
+                hostKind: "outpost",
+                machineId: "ABCDEF12-0000-0000-0000-000000000000",
+                sessionId: null,
+            },
+            value: "hqfp1:-:prs_01J8ZK4Q:outpost.abcdef12:-",
+        },
+        {
+            name: "session only",
+            parts: {
+                company: null,
+                identityUid: null,
+                hostKind: null,
+                machineId: null,
+                sessionId: "abcdefgh12345",
+            },
+            value: "hqfp1:-:-:-:abcdefgh",
+        },
+    ],
+    invalid: [
+        { name: "empty", value: "" },
+        { name: "wrong prefix", value: "hqfp2:indigo:prs_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9" },
+        { name: "too few fields", value: "hqfp1:indigo:prs_01J8ZK4Q:laptop.e3ef5a5a" },
+        { name: "too many fields", value: "hqfp1:indigo:prs_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9:x" },
+        { name: "bad identity prefix", value: "hqfp1:indigo:usr_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9" },
+        { name: "short identity", value: "hqfp1:indigo:prs_01J8:laptop.e3ef5a5a:fabb19c9" },
+        { name: "bad host kind", value: "hqfp1:indigo:prs_01J8ZK4Q:desktop.e3ef5a5a:fabb19c9" },
+        { name: "non-hex machine", value: "hqfp1:indigo:prs_01J8ZK4Q:laptop.zzzzzzzz:fabb19c9" },
+        { name: "long session", value: "hqfp1:indigo:prs_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9x" },
+        { name: "empty field", value: "hqfp1::prs_01J8ZK4Q:laptop.e3ef5a5a:fabb19c9" },
+    ],
+};
+//# sourceMappingURL=fixtures.js.map

package/dist/lib/fingerprint/format.d.ts

@@ -0,0 +1,50 @@
+/**
+ * HQ session fingerprint value format.
+ *
+ * A fingerprint names one HQ session without exposing a full identity, machine
+ * or session id:
+ *
+ *   hqfp1:<company>:<identity>:<machine>:<session>
+ *
+ * - company:  company slug, or "-"
+ * - identity: "prs_" or "agt_" plus the first 8 chars of the ULID, or "-"
+ * - machine:  "<laptop|outpost|fleet>.<first 8 hex chars of the machine id>", or "-"
+ * - session:  first 8 chars of the session id, or "-"
+ *
+ * No component may contain ":". hq-pro (US-006) copies the test vectors in
+ * ./fixtures.ts so both sides agree on the format.
+ */
+export declare const FINGERPRINT_PREFIX = "hqfp1";
+export declare const UNKNOWN = "-";
+export type HostKind = "laptop" | "outpost" | "fleet";
+export type IdentityKind = "person" | "agent";
+export declare const HOST_KINDS: readonly HostKind[];
+export interface FingerprintParts {
+    company: string | null;
+    /** Full `prs_*` or `agt_*` uid. Truncated by build(). */
+    identityUid: string | null;
+    hostKind: HostKind | null;
+    /** Full machine id (UUID or hex). Truncated by build(). */
+    machineId: string | null;
+    /** Full session id. Truncated by build(). */
+    sessionId: string | null;
+}
+export interface ParsedFingerprint {
+    value: string;
+    company: string | null;
+    /** Short identity, for example `prs_01J8ABCD`. */
+    identity: string | null;
+    identityKind: IdentityKind | null;
+    hostKind: HostKind | null;
+    /** Short machine id, 8 lowercase hex chars. */
+    machine: string | null;
+    /** Short session id, 8 chars. */
+    session: string | null;
+}
+export declare const COMPANY_RE: RegExp;
+/** Build a fingerprint value. Throws when a component is malformed or contains ":". */
+export declare function build(parts: FingerprintParts): string;
+/** Parse a fingerprint value. Returns null for anything that is not a valid hqfp1 value. */
+export declare function parse(value: string): ParsedFingerprint | null;
+export declare function isFingerprint(value: unknown): value is string;
+//# sourceMappingURL=format.d.ts.map

package/dist/lib/fingerprint/format.js

@@ -0,0 +1,105 @@
+/**
+ * HQ session fingerprint value format.
+ *
+ * A fingerprint names one HQ session without exposing a full identity, machine
+ * or session id:
+ *
+ *   hqfp1:<company>:<identity>:<machine>:<session>
+ *
+ * - company:  company slug, or "-"
+ * - identity: "prs_" or "agt_" plus the first 8 chars of the ULID, or "-"
+ * - machine:  "<laptop|outpost|fleet>.<first 8 hex chars of the machine id>", or "-"
+ * - session:  first 8 chars of the session id, or "-"
+ *
+ * No component may contain ":". hq-pro (US-006) copies the test vectors in
+ * ./fixtures.ts so both sides agree on the format.
+ */
+export const FINGERPRINT_PREFIX = "hqfp1";
+export const UNKNOWN = "-";
+export const HOST_KINDS = ["laptop", "outpost", "fleet"];
+export const COMPANY_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+const IDENTITY_RE = /^(prs|agt)_[A-Za-z0-9]{8}$/;
+const MACHINE_RE = /^(laptop|outpost|fleet)\.[0-9a-f]{8}$/;
+const SESSION_RE = /^[A-Za-z0-9._-]{1,8}$/;
+function assertNoColon(name, value) {
+    if (value.includes(":")) {
+        throw new Error(`fingerprint ${name} must not contain ":"`);
+    }
+}
+function shortIdentity(uid) {
+    const match = /^(prs|agt)_([A-Za-z0-9]+)$/.exec(uid);
+    if (!match || match[2].length < 8) {
+        throw new Error("fingerprint identity must be prs_ or agt_ followed by at least 8 ULID chars");
+    }
+    return `${match[1]}_${match[2].slice(0, 8)}`;
+}
+function shortMachine(hostKind, machineId) {
+    const hex = machineId.toLowerCase().replace(/-/g, "");
+    if (!/^[0-9a-f]{8,}$/.test(hex)) {
+        throw new Error("fingerprint machine id must start with at least 8 hex chars");
+    }
+    return `${hostKind}.${hex.slice(0, 8)}`;
+}
+/** Build a fingerprint value. Throws when a component is malformed or contains ":". */
+export function build(parts) {
+    const company = parts.company ?? UNKNOWN;
+    assertNoColon("company", company);
+    if (company !== UNKNOWN && !COMPANY_RE.test(company)) {
+        throw new Error("fingerprint company must be a slug");
+    }
+    let identity = UNKNOWN;
+    if (parts.identityUid) {
+        assertNoColon("identity", parts.identityUid);
+        identity = shortIdentity(parts.identityUid);
+    }
+    let machine = UNKNOWN;
+    if (parts.machineId) {
+        assertNoColon("machine", parts.machineId);
+        machine = shortMachine(parts.hostKind ?? "laptop", parts.machineId);
+    }
+    let session = UNKNOWN;
+    if (parts.sessionId) {
+        assertNoColon("session", parts.sessionId);
+        session = parts.sessionId.slice(0, 8);
+        if (!SESSION_RE.test(session)) {
+            throw new Error("fingerprint session id has invalid characters");
+        }
+    }
+    return [FINGERPRINT_PREFIX, company, identity, machine, session].join(":");
+}
+/** Parse a fingerprint value. Returns null for anything that is not a valid hqfp1 value. */
+export function parse(value) {
+    if (typeof value !== "string")
+        return null;
+    const fields = value.split(":");
+    if (fields.length !== 5)
+        return null;
+    const [prefix, company, identity, machine, session] = fields;
+    if (prefix !== FINGERPRINT_PREFIX)
+        return null;
+    if (company !== UNKNOWN && !COMPANY_RE.test(company))
+        return null;
+    if (identity !== UNKNOWN && !IDENTITY_RE.test(identity))
+        return null;
+    if (machine !== UNKNOWN && !MACHINE_RE.test(machine))
+        return null;
+    if (session !== UNKNOWN && !SESSION_RE.test(session))
+        return null;
+    const hostKind = machine === UNKNOWN ? null : machine.split(".")[0];
+    let identityKind = null;
+    if (identity !== UNKNOWN)
+        identityKind = identity.startsWith("agt_") ? "agent" : "person";
+    return {
+        value,
+        company: company === UNKNOWN ? null : company,
+        identity: identity === UNKNOWN ? null : identity,
+        identityKind,
+        hostKind,
+        machine: machine === UNKNOWN ? null : machine.split(".")[1],
+        session: session === UNKNOWN ? null : session,
+    };
+}
+export function isFingerprint(value) {
+    return typeof value === "string" && parse(value) !== null;
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/fingerprint/offline.d.ts

@@ -0,0 +1,16 @@
+export declare const FINGERPRINT_TRAILER = "HQ-Fingerprint";
+/**
+ * The fingerprint for `env`, or null when it cannot be built (no identity and
+ * no session id, or an error). `label` prefixes the stderr warning. With
+ * `readOnly` it creates no file and is null when no machine id exists yet.
+ */
+export declare function offlineFingerprint(hqRoot: string, env: NodeJS.ProcessEnv, label: string, options?: {
+    readOnly?: boolean;
+}): string | null;
+/**
+ * `git commit` args that add the HQ-Fingerprint trailer, or none without a
+ * value. The trailer is a final `-m` paragraph, which `git interpret-trailers`
+ * parses on any git; `--trailer` needs git 2.32. Spread after the subject `-m`.
+ */
+export declare function fingerprintTrailerArgs(fingerprint: string | null | undefined): string[];
+//# sourceMappingURL=offline.d.ts.map

package/dist/lib/fingerprint/offline.js

@@ -0,0 +1,44 @@
+/**
+ * Offline fingerprint for callers that cannot await: lane start and the
+ * handoff commits. Uses the cached ID token and the machine creds only; it
+ * never makes a network call.
+ */
+import * as fs from "node:fs";
+import { loadMachineCreds, machineCredsFilePath } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens } from "../../utils/person-token-cache.js";
+import { buildSelfFingerprintOfflineSync } from "./self-core.js";
+export const FINGERPRINT_TRAILER = "HQ-Fingerprint";
+/**
+ * The fingerprint for `env`, or null when it cannot be built (no identity and
+ * no session id, or an error). `label` prefixes the stderr warning. With
+ * `readOnly` it creates no file and is null when no machine id exists yet.
+ */
+export function offlineFingerprint(hqRoot, env, label, options = {}) {
+    try {
+        return buildSelfFingerprintOfflineSync({
+            hqRoot,
+            env,
+            readOnly: options.readOnly,
+            loadIdToken: () => loadCachedTokens()?.idToken ?? null,
+            loadMachineCreds: () => {
+                if (!fs.existsSync(machineCredsFilePath()))
+                    return null;
+                const creds = loadMachineCreds();
+                return creds ? { entityType: creds.entityType, entityUid: creds.entityUid } : null;
+            },
+        }).fingerprint;
+    }
+    catch (err) {
+        process.stderr.write(`${label}: could not build the fingerprint: ${err.message}\n`);
+        return null;
+    }
+}
+/**
+ * `git commit` args that add the HQ-Fingerprint trailer, or none without a
+ * value. The trailer is a final `-m` paragraph, which `git interpret-trailers`
+ * parses on any git; `--trailer` needs git 2.32. Spread after the subject `-m`.
+ */
+export function fingerprintTrailerArgs(fingerprint) {
+    return fingerprint ? ["-m", `${FINGERPRINT_TRAILER}: ${fingerprint}`] : [];
+}
+//# sourceMappingURL=offline.js.map

package/dist/lib/fingerprint/registry-client.d.ts

@@ -0,0 +1,74 @@
+import type { HostKind } from "./format.js";
+import type { VaultApiOptions } from "../../utils/vault-api.js";
+export declare const REGISTRY_TIMEOUT_MS = 3000;
+export declare const FINGERPRINT_LOG_FILE = "fingerprint.log";
+export type RegistryFetch = (opts: VaultApiOptions) => Promise<Response>;
+export interface RegistryClientOptions {
+    /** HTTP client. Defaults to vaultApiFetch, loaded on first use. */
+    fetch?: RegistryFetch;
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export interface RegisterFingerprintBody {
+    fingerprint: string;
+    companySlug: string;
+    identityUid: string;
+    machineId: string;
+    hostKind: HostKind;
+    sessionId: string;
+    label?: string;
+}
+/** hq-pro's FingerprintRow, as returned by POST /v1/fingerprints. */
+export interface FingerprintRow {
+    pk: string;
+    companyUid: string;
+    companySlug: string;
+    identityUid: string;
+    identityKind: string;
+    machineId: string;
+    hostKind: HostKind;
+    sessionId: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    recordedBySub?: string;
+}
+/** GET /v1/fingerprints/{value}: the row without recordedBySub, plus display names. */
+export interface ResolvedFingerprint extends Omit<FingerprintRow, "recordedBySub"> {
+    identityName: string | null;
+    machineLabel: string | null;
+}
+export type RegistryFailure = {
+    ok: false;
+    /** HTTP status, or null when no response arrived (timeout, transport error). */
+    status: number | null;
+    /** The server's `error` text, or the thrown error's class and message. */
+    error: string;
+};
+export type RegisterResult = {
+    ok: true;
+    status: number;
+    row: FingerprintRow;
+} | RegistryFailure;
+export type LookupResult = {
+    ok: true;
+    found: true;
+    record: ResolvedFingerprint;
+} | {
+    ok: true;
+    found: false;
+} | RegistryFailure;
+export declare function registerFingerprint(body: RegisterFingerprintBody, token: string, opts?: RegistryClientOptions): Promise<RegisterResult>;
+export declare function lookupFingerprint(value: string, token: string, opts?: RegistryClientOptions): Promise<LookupResult>;
+export interface FingerprintLogOptions {
+    /** Directory that holds fingerprint.log. Defaults to ~/.hq. */
+    dir?: string;
+    now?: () => Date;
+}
+export declare function fingerprintLogPath(dir?: string): string;
+/**
+ * Appends one line to ~/.hq/fingerprint.log. A log that cannot be written is
+ * dropped: registration is fire-and-forget and must not print or fail.
+ */
+export declare function appendFingerprintLog(op: string, detail: string, opts?: FingerprintLogOptions): void;
+export declare function describeFailure(result: RegistryFailure): string;
+//# sourceMappingURL=registry-client.d.ts.map