@indigoai-us/hq-cli 5.345.134 → 5.345.135

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

package/dist/lib/fingerprint/registry-client.js

@@ -0,0 +1,141 @@
+/**
+ * Client for the hq-pro fingerprint registry (session-fingerprints US-006):
+ *
+ *   POST /v1/fingerprints          record this session's fingerprint
+ *   GET  /v1/fingerprints/{value}  resolve a fingerprint to its record
+ *
+ * Every call is capped at REGISTRY_TIMEOUT_MS and never throws: failures come
+ * back as a typed result. vault-api is imported lazily, and self.ts and the
+ * command import this module lazily, so the offline builder (self-core.ts,
+ * offline.ts) never reaches it.
+ *
+ * Failures are written as one line to ~/.hq/fingerprint.log. A line names the
+ * operation, the HTTP status or the error class, and the server's error text,
+ * never a token or a request header.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const REGISTRY_TIMEOUT_MS = 3000;
+export const FINGERPRINT_LOG_FILE = "fingerprint.log";
+async function defaultFetch(opts) {
+    const { vaultApiFetch } = await import("../../utils/vault-api.js");
+    return vaultApiFetch(opts);
+}
+/** Runs the request with an AbortController that fires after the timeout. */
+async function withDeadline(run, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const err = new Error(`timed out after ${ms}ms`);
+            err.name = "TimeoutError";
+            controller.abort(err);
+            reject(err);
+        }, ms);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        // A body that is not JSON (an HTML gateway page, an empty 502) has no
+        // fields to read; the caller reports the status instead.
+        return null;
+    }
+}
+function serverError(body, status) {
+    if (body && typeof body === "object") {
+        const record = body;
+        if (typeof record.error === "string")
+            return record.error;
+        if (typeof record.message === "string")
+            return record.message;
+    }
+    return `HTTP ${status}`;
+}
+function thrownError(err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    return { ok: false, status: null, error: `${e.name}: ${e.message}` };
+}
+export async function registerFingerprint(body, token, opts = {}) {
+    const fetchImpl = opts.fetch ?? defaultFetch;
+    try {
+        const response = await withDeadline((signal) => fetchImpl({
+            baseUrl: opts.baseUrl,
+            token,
+            path: "/v1/fingerprints",
+            method: "POST",
+            body: { ...body },
+            signal,
+        }), opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const json = await readJson(response);
+        if (response.status === 200 || response.status === 201) {
+            return { ok: true, status: response.status, row: json };
+        }
+        return { ok: false, status: response.status, error: serverError(json, response.status) };
+    }
+    catch (err) {
+        return thrownError(err);
+    }
+}
+export async function lookupFingerprint(value, token, opts = {}) {
+    const fetchImpl = opts.fetch ?? defaultFetch;
+    try {
+        const response = await withDeadline((signal) => fetchImpl({
+            baseUrl: opts.baseUrl,
+            token,
+            path: `/v1/fingerprints/${encodeURIComponent(value)}`,
+            signal,
+        }), opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
+        const json = await readJson(response);
+        if (response.status === 200 && json && typeof json === "object") {
+            return { ok: true, found: true, record: json };
+        }
+        // Unknown values and fingerprints of other companies get the same 404.
+        if (response.status === 404)
+            return { ok: true, found: false };
+        return { ok: false, status: response.status, error: serverError(json, response.status) };
+    }
+    catch (err) {
+        return thrownError(err);
+    }
+}
+export function fingerprintLogPath(dir = path.join(os.homedir(), ".hq")) {
+    return path.join(dir, FINGERPRINT_LOG_FILE);
+}
+/** Strips newlines and anything shaped like a bearer token or a JWT. */
+function sanitize(text) {
+    return text
+        .replace(/[\r\n]+/g, " ")
+        .replace(/Bearer\s+\S+/gi, "Bearer <redacted>")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g, "<redacted>")
+        .replace(/\bhqk_[A-Za-z0-9_-]+/g, "<redacted>")
+        .slice(0, 300);
+}
+/**
+ * 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 function appendFingerprintLog(op, detail, opts = {}) {
+    const file = fingerprintLogPath(opts.dir);
+    const at = (opts.now ?? (() => new Date()))().toISOString();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${at} ${op} ${sanitize(detail)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Nowhere left to report it without changing the command's output.
+    }
+}
+export function describeFailure(result) {
+    return result.status === null ? result.error : `status=${result.status} ${result.error}`;
+}
+//# sourceMappingURL=registry-client.js.map

package/dist/lib/fingerprint/resolve-local.d.ts

@@ -0,0 +1,14 @@
+import type { HostKind, IdentityKind } from "./format.js";
+export interface LocalFingerprintRecord {
+    fingerprint: string;
+    identityUid: string | null;
+    identityKind: IdentityKind | null;
+    machineId: string | null;
+    hostKind: HostKind | null;
+    sessionId: string | null;
+    company: string | null;
+    builtAt: string | null;
+    source: "local";
+}
+export declare function resolveLocalFingerprint(hqRoot: string, value: string): LocalFingerprintRecord | null;
+//# sourceMappingURL=resolve-local.d.ts.map

package/dist/lib/fingerprint/resolve-local.js

@@ -0,0 +1,67 @@
+/**
+ * Resolve a fingerprint against this machine's session records
+ * (workspace/sessions/<sid>/fingerprint.yaml). Exact value match only.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { FINGERPRINT_FILE } from "./self-core.js";
+function str(value) {
+    return typeof value === "string" && value ? value : null;
+}
+export function resolveLocalFingerprint(hqRoot, value) {
+    const sessionsDir = path.join(hqRoot, "workspace", "sessions");
+    let entries;
+    try {
+        entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const file = path.join(sessionsDir, entry.name, FINGERPRINT_FILE);
+        let raw;
+        try {
+            raw = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                process.stderr.write(`hq fingerprint: skipping unreadable ${file}: ${err.message}\n`);
+            }
+            continue;
+        }
+        // A cheap substring check skips the YAML parse for the many sessions that do not match.
+        if (!raw.includes(value))
+            continue;
+        let record;
+        try {
+            record = yaml.load(raw);
+        }
+        catch (err) {
+            process.stderr.write(`hq fingerprint: skipping unreadable ${file}: ${err.message}\n`);
+            continue;
+        }
+        if (!record || typeof record !== "object")
+            continue;
+        const r = record;
+        if (r.fingerprint !== value)
+            continue;
+        return {
+            fingerprint: value,
+            identityUid: str(r.identity_uid),
+            identityKind: str(r.identity_kind) ?? null,
+            machineId: str(r.machine_id),
+            hostKind: str(r.host_kind) ?? null,
+            sessionId: str(r.session_id),
+            company: str(r.company),
+            builtAt: str(r.built_at),
+            source: "local",
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-local.js.map

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

@@ -0,0 +1,139 @@
+import { type HostKind, type IdentityKind } from "./format.js";
+export declare const SESSION_ID_ENV_VARS: readonly ["HQ_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "GROK_SESSION_ID"];
+export declare const IDENTITY_LOOKUP_TIMEOUT_MS = 3000;
+export declare const FINGERPRINT_FILE = "fingerprint.yaml";
+export declare const IDENTITY_UID_RE: RegExp;
+export type IdentitySource = "token" | "machine-creds" | "cache" | "lookup" | "none";
+export interface SelfFingerprint {
+    fingerprint: string | null;
+    company: string | null;
+    identityUid: string | null;
+    identityKind: IdentityKind | null;
+    machineId: string | null;
+    hostKind: HostKind;
+    sessionId: string | null;
+    source: IdentitySource;
+    reason?: string;
+}
+export interface MachineCredsSummary {
+    entityType?: string;
+    entityUid?: string;
+}
+export interface SelfFingerprintDeps {
+    hqRoot: string;
+    env?: NodeJS.ProcessEnv;
+    offline?: boolean;
+    /** Returns the cached ID token, or null when signed out. */
+    loadIdToken?: () => string | null | Promise<string | null>;
+    /** Returns the machine creds, or null when this host has none or they are unreadable. */
+    loadMachineCreds?: () => MachineCredsSummary | null | Promise<MachineCredsSummary | null>;
+    /** Resolves the caller's uid over the network. The signal aborts on timeout. */
+    resolveIdentity?: (idToken: string, signal: AbortSignal) => Promise<{
+        kind: IdentityKind;
+        uid: string;
+    }>;
+    readMachineId?: (hqRoot: string) => string | null;
+    /**
+     * Never create or write a file: read an existing machine id only, return a
+     * null fingerprint without one, and skip the session cache write. For the
+     * handoff commits, which must leave the tree as the shell script does.
+     */
+    readOnly?: boolean;
+    /**
+     * The caller found no HQ root, so `hqRoot` names no HQ tree. The machine is
+     * `-`, nothing under `hqRoot` is read or written, and the result carries
+     * `reason: "no HQ root"`.
+     */
+    noRoot?: boolean;
+    lookupTimeoutMs?: number;
+    now?: () => Date;
+    warn?: (message: string) => void;
+}
+interface FingerprintCacheFile {
+    fingerprint?: string | null;
+    company?: string | null;
+    identity_uid?: string | null;
+    identity_kind?: IdentityKind | null;
+    identity_lookup_done?: boolean;
+    /** sha256 of the ID token `sub` the identity was resolved for, or null without one. */
+    token_owner?: string | null;
+    machine_id?: string | null;
+    host_kind?: HostKind;
+    session_id?: string;
+    built_at?: string;
+    /** When hq-pro recorded this fingerprint (US-007). Set by the registry step in self.ts. */
+    registered_at?: string;
+    /** Why registration will not be tried again for this fingerprint, such as "outpost". */
+    registration_skipped?: string;
+}
+/** Registration keys carried across rewrites while the fingerprint stays the same. */
+type RegistrationKeys = Pick<FingerprintCacheFile, "registered_at" | "registration_skipped">;
+export declare function resolveSessionId(env: NodeJS.ProcessEnv): string | null;
+export declare function sessionDir(hqRoot: string, sessionId: string): string;
+/**
+ * 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 declare function readOrCreateMachineId(hqRoot: string): string | null;
+/** Read `<hqRoot>/.hq/machine-id` without creating it. Null when it is missing or empty. */
+export declare function readMachineIdIfPresent(hqRoot: string): string | null;
+/** Machine ids are usually UUIDs. A free-form id is hashed so the fingerprint keeps 8 hex chars. */
+export declare function machineIdForFingerprint(machineId: string): string;
+export interface IdentityContext {
+    env: NodeJS.ProcessEnv;
+    hqRoot: string;
+    warn: (message: string) => void;
+    sessionId: string | null;
+    idToken: string | null;
+    owner: string | null;
+    hostKind: HostKind;
+    cacheFile: string | null;
+    identityUid: string | null;
+    source: IdentitySource;
+    lookupDone: boolean;
+    /** True when no local source named the identity and a person lookup may run. */
+    needsLookup: boolean;
+    /** The cached fingerprint and its registration keys, kept when the value is unchanged. */
+    cachedRegistration?: {
+        fingerprint: string | null;
+    } & RegistrationKeys;
+}
+export declare function identityContext(deps: SelfFingerprintDeps, idToken: string | null, creds: MachineCredsSummary | null): IdentityContext;
+export interface SelfFingerprintSyncDeps extends Omit<SelfFingerprintDeps, "offline" | "loadIdToken" | "loadMachineCreds" | "resolveIdentity" | "lookupTimeoutMs"> {
+    /** Returns the cached ID token, or null when signed out. */
+    loadIdToken: () => string | null;
+    /** Returns the machine creds, or null when this host has none or they are unreadable. */
+    loadMachineCreds: () => MachineCredsSummary | null;
+}
+/**
+ * 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 declare function buildSelfFingerprintOfflineSync(deps: SelfFingerprintSyncDeps): SelfFingerprint;
+export declare function finishFingerprint(deps: SelfFingerprintDeps, ctx: IdentityContext): SelfFingerprint;
+export interface FingerprintRegistrationState {
+    registeredAt: string | null;
+    skipped: string | null;
+}
+/**
+ * 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 declare function readRegistrationState(hqRoot: string, sessionId: string, fingerprint: string, warn: (message: string) => void): FingerprintRegistrationState | 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 declare function recordRegistrationState(hqRoot: string, sessionId: string, fingerprint: string, update: {
+    registeredAt: string;
+} | {
+    skipped: string;
+}, warn: (message: string) => void): boolean;
+export {};
+//# sourceMappingURL=self-core.d.ts.map