@indigoai-us/hq-cli 5.345.134 → 5.345.136

package/dist/lib/fingerprint/self-core.js

@@ -0,0 +1,371 @@
+/**
+ * The network-free part of the session fingerprint builder: session id,
+ * company, machine id, the fingerprint.yaml cache, and the synchronous offline
+ * build. Lane start and the handoff commits import this module directly, so
+ * it must never import vault-api, cognito-session, hq-cloud, or any other
+ * network client, not even lazily. The person lookup lives in self.ts.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { peekIdToken } from "../../utils/id-token.js";
+import { build, COMPANY_RE } from "./format.js";
+export const SESSION_ID_ENV_VARS = [
+    "HQ_SESSION_ID",
+    "CLAUDE_CODE_SESSION_ID",
+    "CLAUDE_SESSION_ID",
+    "CODEX_SESSION_ID",
+    "CODEX_THREAD_ID",
+    "GROK_SESSION_ID",
+];
+export const IDENTITY_LOOKUP_TIMEOUT_MS = 3000;
+export const FINGERPRINT_FILE = "fingerprint.yaml";
+const SESSION_ID_RE = /^[A-Za-z0-9._-]+$/;
+export const IDENTITY_UID_RE = /^(prs|agt)_[A-Za-z0-9]{8,}$/;
+function registrationKeys(cache) {
+    const keys = {};
+    if (typeof cache?.registered_at === "string" && cache.registered_at)
+        keys.registered_at = cache.registered_at;
+    if (typeof cache?.registration_skipped === "string" && cache.registration_skipped) {
+        keys.registration_skipped = cache.registration_skipped;
+    }
+    return keys;
+}
+export function resolveSessionId(env) {
+    for (const name of SESSION_ID_ENV_VARS) {
+        const value = env[name];
+        if (!value)
+            continue;
+        if (value === "." || value === "..")
+            continue;
+        if (!SESSION_ID_RE.test(value))
+            continue;
+        return value;
+    }
+    return null;
+}
+export function sessionDir(hqRoot, sessionId) {
+    return path.join(hqRoot, "workspace", "sessions", sessionId);
+}
+/** Reads a YAML mapping. Unreadable or unparseable files warn and count as missing. */
+function readYamlRecord(file, warn) {
+    try {
+        const parsed = yaml.load(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        warn(`hq fingerprint: ignoring unreadable ${file}: ${err.message}`);
+        return null;
+    }
+}
+function resolveCompany(hqRoot, sessionId, env, warn) {
+    let company = null;
+    let from = "";
+    if (sessionId) {
+        const meta = readYamlRecord(path.join(sessionDir(hqRoot, sessionId), "meta.yaml"), warn);
+        const slug = meta?.company_slug;
+        if (typeof slug === "string" && slug.trim()) {
+            company = slug.trim();
+            from = "meta.yaml company_slug";
+        }
+    }
+    if (!company && env.HQ_COMPANY)
+        [company, from] = [env.HQ_COMPANY, "HQ_COMPANY"];
+    if (!company && env.HQ_SPAWN_COMPANY)
+        [company, from] = [env.HQ_SPAWN_COMPANY, "HQ_SPAWN_COMPANY"];
+    if (company && !COMPANY_RE.test(company)) {
+        warn(`hq fingerprint: ignoring ${from}: not a company slug`);
+        return null;
+    }
+    return company;
+}
+/**
+ * Read `<hqRoot>/.hq/machine-id`, creating it when missing. Mirrors
+ * getOrCreateMachineId in hq-cloud, which the package does not export (its
+ * exports map has no ./lib/machine-id entry). Falls back to the menubar id in
+ * ~/.hq/menubar.json before generating a new UUID, as hq-cloud does.
+ */
+export function readOrCreateMachineId(hqRoot) {
+    const file = path.join(hqRoot, ".hq", "machine-id");
+    try {
+        const existing = fs.readFileSync(file, "utf8").trim();
+        if (existing)
+            return existing;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    let id = null;
+    try {
+        const menubar = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".hq", "menubar.json"), "utf8"));
+        if (typeof menubar?.machineId === "string" && menubar.machineId)
+            id = menubar.machineId;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT" && !(err instanceof SyntaxError))
+            throw err;
+    }
+    id ??= randomUUID();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${id}\n`);
+    return id;
+}
+/** Read `<hqRoot>/.hq/machine-id` without creating it. Null when it is missing or empty. */
+export function readMachineIdIfPresent(hqRoot) {
+    try {
+        return fs.readFileSync(path.join(hqRoot, ".hq", "machine-id"), "utf8").trim() || null;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/** Machine ids are usually UUIDs. A free-form id is hashed so the fingerprint keeps 8 hex chars. */
+export function machineIdForFingerprint(machineId) {
+    const hex = machineId.toLowerCase().replace(/-/g, "");
+    if (/^[0-9a-f]{8,}$/.test(hex))
+        return machineId;
+    return createHash("sha256").update(machineId).digest("hex");
+}
+function tokenOwner(sub) {
+    return typeof sub === "string" && sub ? createHash("sha256").update(sub).digest("hex") : null;
+}
+function writeCacheAtomic(file, record, warn) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(tmp, yaml.dump(record));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not write ${file}: ${err.message}`);
+        fs.rmSync(tmp, { force: true });
+    }
+}
+function kindOfUid(uid) {
+    return uid.startsWith("agt_") ? "agent" : "person";
+}
+export function identityContext(deps, idToken, creds) {
+    const env = deps.env ?? process.env;
+    const hqRoot = deps.hqRoot;
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    const sessionId = resolveSessionId(env);
+    const claims = idToken ? peekIdToken(idToken) : {};
+    const entityType = typeof claims["custom:entityType"] === "string" ? claims["custom:entityType"] : null;
+    const entityUid = typeof claims["custom:entityUid"] === "string" ? claims["custom:entityUid"] : null;
+    const owner = tokenOwner(claims.sub);
+    let hostKind = "laptop";
+    if (entityType === "agent" || creds)
+        hostKind = "fleet";
+    if (entityType === "outpost" ||
+        entityType === "company-outpost" ||
+        entityUid?.startsWith("out_") ||
+        creds?.entityType === "outpost" ||
+        creds?.entityType === "company-outpost") {
+        hostKind = "outpost";
+    }
+    const cacheFile = sessionId && !deps.noRoot ? path.join(sessionDir(hqRoot, sessionId), FINGERPRINT_FILE) : null;
+    const rawCache = cacheFile ? readYamlRecord(cacheFile, warn) : null;
+    // A cache written for another signed-in user says nothing about this one.
+    const cached = rawCache && (rawCache.token_owner ?? null) === owner ? rawCache : null;
+    const agentPrincipal = entityType === "agent" || creds?.entityType === "agent" || entityUid?.startsWith("agt_") === true;
+    let identityUid = null;
+    let source = "none";
+    let needsLookup = false;
+    if (entityUid && IDENTITY_UID_RE.test(entityUid)) {
+        identityUid = entityUid;
+        source = "token";
+    }
+    else if (creds?.entityUid && IDENTITY_UID_RE.test(creds.entityUid)) {
+        identityUid = creds.entityUid;
+        source = "machine-creds";
+    }
+    else if (cached?.identity_lookup_done) {
+        identityUid = typeof cached.identity_uid === "string" ? cached.identity_uid : null;
+        source = "cache";
+    }
+    else if (sessionId && !deps.offline && idToken && hostKind !== "outpost" && !agentPrincipal) {
+        needsLookup = true;
+    }
+    return {
+        env,
+        hqRoot,
+        warn,
+        sessionId,
+        idToken,
+        owner,
+        hostKind,
+        cacheFile,
+        identityUid,
+        source,
+        lookupDone: cached?.identity_lookup_done === true,
+        needsLookup,
+        cachedRegistration: {
+            fingerprint: typeof rawCache?.fingerprint === "string" ? rawCache.fingerprint : null,
+            ...registrationKeys(rawCache),
+        },
+    };
+}
+/**
+ * The offline build as a synchronous call, for callers that cannot await
+ * (lane start). It never does the person lookup, so the loaders are required:
+ * the default ones live in self.ts, which loads them lazily and only
+ * asynchronously.
+ */
+export function buildSelfFingerprintOfflineSync(deps) {
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    let idToken = null;
+    try {
+        idToken = deps.loadIdToken();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read the cached token: ${err.message}`);
+    }
+    let creds = null;
+    try {
+        creds = deps.loadMachineCreds();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read machine creds: ${err.message}`);
+    }
+    const offlineDeps = { ...deps, offline: true };
+    return finishFingerprint(offlineDeps, identityContext(offlineDeps, idToken, creds));
+}
+export function finishFingerprint(deps, ctx) {
+    const result = finishFingerprintAtRoot(deps, ctx);
+    if (!deps.noRoot)
+        return result;
+    return { ...result, reason: result.reason ? `no HQ root; ${result.reason}` : "no HQ root" };
+}
+function finishFingerprintAtRoot(deps, ctx) {
+    const { env, hqRoot, warn, sessionId, idToken, owner, hostKind, cacheFile, identityUid, source, lookupDone } = ctx;
+    let rawMachineId = deps.noRoot ? null : env.HQ_MACHINE_ID?.trim() || null;
+    if (!rawMachineId && !deps.noRoot) {
+        try {
+            rawMachineId = (deps.readMachineId ?? (deps.readOnly ? readMachineIdIfPresent : readOrCreateMachineId))(hqRoot);
+        }
+        catch (err) {
+            warn(`hq fingerprint: could not read the machine id: ${err.message}`);
+        }
+    }
+    const machineId = rawMachineId ? machineIdForFingerprint(rawMachineId) : null;
+    const company = resolveCompany(hqRoot, deps.noRoot ? null : sessionId, env, warn);
+    const identityKind = identityUid ? kindOfUid(identityUid) : null;
+    if (!identityUid && !sessionId) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid: null,
+            identityKind: null,
+            machineId: rawMachineId,
+            hostKind,
+            sessionId: null,
+            source,
+            reason: idToken
+                ? "no session id in the environment and no identity uid on the cached token"
+                : "no session id in the environment and not signed in",
+        };
+    }
+    if (deps.readOnly && !machineId) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid,
+            identityKind,
+            machineId: null,
+            hostKind,
+            sessionId,
+            source,
+            reason: "no machine id and read-only mode does not create one",
+        };
+    }
+    let fingerprint;
+    try {
+        fingerprint = build({ company, identityUid, hostKind, machineId, sessionId });
+    }
+    catch (err) {
+        return {
+            fingerprint: null,
+            company,
+            identityUid,
+            identityKind,
+            machineId: rawMachineId,
+            hostKind,
+            sessionId,
+            source,
+            reason: `could not build fingerprint: ${err.message}`,
+        };
+    }
+    if (sessionId && cacheFile && !deps.readOnly) {
+        const record = {
+            fingerprint,
+            company,
+            identity_uid: identityUid,
+            identity_kind: identityKind,
+            identity_lookup_done: lookupDone,
+            token_owner: owner,
+            machine_id: rawMachineId,
+            host_kind: hostKind,
+            session_id: sessionId,
+            built_at: (deps.now ?? (() => new Date()))().toISOString(),
+            // The fingerprint names company, identity, machine and session, so the
+            // same value means hq-pro already holds this exact record.
+            ...(ctx.cachedRegistration?.fingerprint === fingerprint ? registrationKeys(ctx.cachedRegistration) : {}),
+        };
+        writeCacheAtomic(cacheFile, record, warn);
+    }
+    return {
+        fingerprint,
+        company,
+        identityUid,
+        identityKind,
+        machineId: rawMachineId,
+        hostKind,
+        sessionId,
+        source,
+    };
+}
+function cachePathFor(hqRoot, sessionId) {
+    return path.join(sessionDir(hqRoot, sessionId), FINGERPRINT_FILE);
+}
+/**
+ * The registration keys of this session's fingerprint.yaml, or null when the
+ * file is missing or holds another fingerprint (the registry step then has no
+ * record to mark).
+ */
+export function readRegistrationState(hqRoot, sessionId, fingerprint, warn) {
+    const cache = readYamlRecord(cachePathFor(hqRoot, sessionId), warn);
+    if (!cache || cache.fingerprint !== fingerprint)
+        return null;
+    const keys = registrationKeys(cache);
+    return { registeredAt: keys.registered_at ?? null, skipped: keys.registration_skipped ?? null };
+}
+/**
+ * Writes registered_at or registration_skipped into fingerprint.yaml. Re-reads
+ * the file first and writes nothing when it now holds another fingerprint.
+ * Returns true when the file was rewritten.
+ */
+export function recordRegistrationState(hqRoot, sessionId, fingerprint, update, warn) {
+    const file = cachePathFor(hqRoot, sessionId);
+    const cache = readYamlRecord(file, warn);
+    if (!cache || cache.fingerprint !== fingerprint)
+        return false;
+    const record = { ...cache };
+    if ("registeredAt" in update) {
+        record.registered_at = update.registeredAt;
+        delete record.registration_skipped;
+    }
+    else {
+        record.registration_skipped = update.skipped;
+    }
+    writeCacheAtomic(file, record, warn);
+    return true;
+}
+//# sourceMappingURL=self-core.js.map

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

@@ -0,0 +1,44 @@
+import type { RegistryFetch } from "./registry-client.js";
+import { type MachineCredsSummary, type SelfFingerprint, type SelfFingerprintDeps } from "./self-core.js";
+export * from "./self-core.js";
+/** An unparseable creds file yields null, so it never marks the host as fleet. */
+export declare function defaultLoadMachineCreds(): Promise<MachineCredsSummary | null>;
+export declare function buildSelfFingerprint(deps: SelfFingerprintDeps): Promise<SelfFingerprint>;
+export interface RegisterSelfDeps {
+    hqRoot: string;
+    env?: NodeJS.ProcessEnv;
+    offline?: boolean;
+    /** false when the caller passed --no-register. */
+    register?: boolean;
+    loadIdToken?: () => string | null | Promise<string | null>;
+    fetch?: RegistryFetch;
+    timeoutMs?: number;
+    /** Directory for fingerprint.log. Defaults to ~/.hq. */
+    logDir?: string;
+    now?: () => Date;
+}
+export type RegisterSelfOutcome = {
+    status: "registered";
+} | {
+    status: "already-registered";
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "failed";
+    reason: string;
+};
+/**
+ * Records this session's fingerprint with hq-pro (POST /v1/fingerprints), at
+ * most once per session. Fire-and-forget: it never writes to stdout or stderr
+ * and never throws, so the printed fingerprint and the exit code stay the
+ * same whatever the registry does.
+ *
+ * hq-pro denies company-outpost machine tokens, so outpost hosts skip the call
+ * and record `registration_skipped: outpost`. A 403 is also final and is
+ * recorded the same way. A 404 means the registry is not deployed for this
+ * API, so it records `registration_skipped: unavailable` and the session stops
+ * calling. Any other failure is logged and retried next run.
+ */
+export declare function registerSelfFingerprint(self: SelfFingerprint, deps: RegisterSelfDeps): Promise<RegisterSelfOutcome>;
+//# sourceMappingURL=self.d.ts.map

package/dist/lib/fingerprint/self.js

@@ -0,0 +1,191 @@
+/**
+ * Build the fingerprint for the current HQ session (`hq fingerprint self`).
+ *
+ * Sources, in order:
+ * - session id: the first valid value of HQ_SESSION_ID, CLAUDE_CODE_SESSION_ID,
+ *   CLAUDE_SESSION_ID, CODEX_SESSION_ID, CODEX_THREAD_ID, GROK_SESSION_ID (same
+ *   order as core/scripts/lib/session-id.sh). workspace/sessions/.current is
+ *   never read: it names whichever session wrote last, not this one.
+ * - identity: `custom:entityUid` on the cached ID token, then the agent uid in
+ *   the machine creds, then this session's fingerprint.yaml cache (only when
+ *   it was written for the same token owner), then a person lookup (3s cap,
+ *   skipped with --offline, without a session id, and for outpost and agent
+ *   principals). A lookup is cached once it succeeds or the server says the
+ *   caller has no person entity; transient failures retry next time.
+ * - machine: HQ_MACHINE_ID, then `<hqRoot>/.hq/machine-id`.
+ * - company: the session's meta.yaml company_slug, then HQ_COMPANY, then
+ *   HQ_SPAWN_COMPANY. A value that is not a slug is replaced with `-`.
+ *
+ * The result is written to workspace/sessions/<sid>/fingerprint.yaml when a
+ * session id is known. registerSelfFingerprint (US-007) then records the
+ * fingerprint with hq-pro once per session and writes `registered_at`, or
+ * `registration_skipped` when hq-pro will never accept it (outpost hosts, a
+ * 403). It never prints and never throws; failures go to ~/.hq/fingerprint.log.
+ * registry-client is imported lazily, only on the registration path.
+ *
+ * The commit-msg hook runs `self --offline` on every commit, so this module
+ * keeps its static imports light: cognito-session, hq-cloud, and vault-api are
+ * loaded only on the paths that need them. The network-free core lives in
+ * self-core.ts so lane start and the handoff commits never reach them.
+ */
+import * as fs from "node:fs";
+import { finishFingerprint, IDENTITY_LOOKUP_TIMEOUT_MS, IDENTITY_UID_RE, identityContext, machineIdForFingerprint, readRegistrationState, recordRegistrationState, } from "./self-core.js";
+export * from "./self-core.js";
+async function defaultLoadIdToken() {
+    const { loadCachedTokens } = await import("../../utils/cognito-session.js");
+    return loadCachedTokens()?.idToken ?? null;
+}
+/** An unparseable creds file yields null, so it never marks the host as fleet. */
+export async function defaultLoadMachineCreds() {
+    const { loadMachineCreds, machineCredsFilePath } = await import("@indigoai-us/hq-cloud");
+    if (!fs.existsSync(machineCredsFilePath()))
+        return null;
+    const creds = loadMachineCreds();
+    return creds ? { entityType: creds.entityType, entityUid: creds.entityUid } : null;
+}
+async function defaultResolveIdentity(idToken, signal) {
+    const { resolveCallerUid } = await import("../../utils/vault-api.js");
+    return resolveCallerUid(idToken, undefined, { signal });
+}
+/** Races the lookup against the timeout and aborts the request when time runs out. */
+async function withTimeout(run, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`identity lookup timed out after ${ms}ms`);
+            controller.abort(err);
+            reject(err);
+        }, ms);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** vault-api's NoPersonEntityError, matched by name so vault-api stays lazily loaded. */
+function isNoPersonEntityError(err) {
+    return err instanceof Error && err.name === "NoPersonEntityError";
+}
+export async function buildSelfFingerprint(deps) {
+    const warn = deps.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    let idToken = null;
+    try {
+        idToken = await (deps.loadIdToken ?? defaultLoadIdToken)();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read the cached token: ${err.message}`);
+    }
+    let creds = null;
+    try {
+        creds = await (deps.loadMachineCreds ?? defaultLoadMachineCreds)();
+    }
+    catch (err) {
+        warn(`hq fingerprint: could not read machine creds: ${err.message}`);
+    }
+    const ctx = identityContext(deps, idToken, creds);
+    if (ctx.needsLookup && ctx.idToken) {
+        const resolveIdentity = deps.resolveIdentity ?? defaultResolveIdentity;
+        const token = ctx.idToken;
+        try {
+            const resolved = await withTimeout((signal) => resolveIdentity(token, signal), deps.lookupTimeoutMs ?? IDENTITY_LOOKUP_TIMEOUT_MS);
+            ctx.lookupDone = true;
+            if (IDENTITY_UID_RE.test(resolved.uid)) {
+                ctx.identityUid = resolved.uid;
+                ctx.source = "lookup";
+            }
+        }
+        catch (err) {
+            // "No person entity" is a definitive answer; anything else may be transient.
+            if (isNoPersonEntityError(err))
+                ctx.lookupDone = true;
+            warn(`hq fingerprint: identity lookup failed: ${err.message}`);
+        }
+    }
+    return finishFingerprint(deps, ctx);
+}
+/**
+ * Records this session's fingerprint with hq-pro (POST /v1/fingerprints), at
+ * most once per session. Fire-and-forget: it never writes to stdout or stderr
+ * and never throws, so the printed fingerprint and the exit code stay the
+ * same whatever the registry does.
+ *
+ * hq-pro denies company-outpost machine tokens, so outpost hosts skip the call
+ * and record `registration_skipped: outpost`. A 403 is also final and is
+ * recorded the same way. A 404 means the registry is not deployed for this
+ * API, so it records `registration_skipped: unavailable` and the session stops
+ * calling. Any other failure is logged and retried next run.
+ */
+export async function registerSelfFingerprint(self, deps) {
+    const env = deps.env ?? process.env;
+    if (deps.register === false)
+        return { status: "skipped", reason: "--no-register" };
+    if (deps.offline || env.HQ_FINGERPRINT_OFFLINE === "1")
+        return { status: "skipped", reason: "offline" };
+    const { fingerprint, company, identityUid, sessionId, machineId, hostKind } = self;
+    if (!fingerprint || !company || company === "-" || !identityUid || !sessionId || !machineId) {
+        return { status: "skipped", reason: "incomplete fingerprint" };
+    }
+    // Cache read and write problems stay quiet here: the build already warned.
+    const quiet = () => { };
+    const state = readRegistrationState(deps.hqRoot, sessionId, fingerprint, quiet);
+    if (!state)
+        return { status: "skipped", reason: "no session cache" };
+    if (state.registeredAt)
+        return { status: "already-registered" };
+    if (state.skipped)
+        return { status: "skipped", reason: state.skipped };
+    try {
+        const registry = await import("./registry-client.js");
+        const log = (op, detail) => registry.appendFingerprintLog(op, detail, { dir: deps.logDir, now: deps.now });
+        if (hostKind === "outpost") {
+            log("register", `skipped outpost: hq-pro denies company-outpost machine tokens fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "outpost" }, quiet);
+            return { status: "skipped", reason: "outpost" };
+        }
+        let token = null;
+        try {
+            token = await (deps.loadIdToken ?? defaultLoadIdToken)();
+        }
+        catch (err) {
+            log("register", `failed: could not read the cached token: ${err.name}`);
+            return { status: "failed", reason: "token unreadable" };
+        }
+        if (!token)
+            return { status: "skipped", reason: "not signed in" };
+        const result = await registry.registerFingerprint({
+            fingerprint,
+            companySlug: company,
+            identityUid,
+            machineId: machineIdForFingerprint(machineId),
+            hostKind,
+            sessionId,
+        }, token, { fetch: deps.fetch, timeoutMs: deps.timeoutMs });
+        if (result.ok) {
+            const at = (deps.now ?? (() => new Date()))().toISOString();
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { registeredAt: at }, quiet);
+            return { status: "registered" };
+        }
+        const detail = registry.describeFailure(result);
+        if (result.status === 403) {
+            // A denial will not change on retry; stop calling for this fingerprint.
+            log("register", `skipped forbidden: ${detail} fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "forbidden" }, quiet);
+            return { status: "skipped", reason: "forbidden" };
+        }
+        if (result.status === 404) {
+            // The registry route is not deployed here; stop calling for this session.
+            log("register", `skipped unavailable: ${detail} fingerprint=${fingerprint}`);
+            recordRegistrationState(deps.hqRoot, sessionId, fingerprint, { skipped: "unavailable" }, quiet);
+            return { status: "skipped", reason: "unavailable" };
+        }
+        log("register", `failed: ${detail} fingerprint=${fingerprint}`);
+        return { status: "failed", reason: detail };
+    }
+    catch (err) {
+        return { status: "failed", reason: err.message };
+    }
+}
+//# sourceMappingURL=self.js.map