@indigoai-us/hq-cli 5.345.134 → 5.345.135

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.345.135] — 2026-10-15
+- `hq fingerprint self` prints the current session's HQ fingerprint, and `hq fingerprint <value>` resolves a fingerprint to its local session record. The commit-msg hook calls `hq fingerprint self --json --offline`, which stays offline and always exits 0.
+- Worker lanes get their own `HQ_SESSION_ID`, `HQ_LANE_ID`, `HQ_PARENT_SESSION_ID` and `HQ_COMPANY` with every inherited session id removed; lane records carry a `fingerprint` field shown by `lanes status --json` and `lanes show`; handoff commits add an `HQ-Fingerprint` trailer when a value exists. The handoff lookup is read-only and the offline builder never loads network modules (US-005).
+- `hq fingerprint self` records the session's fingerprint with the HQ registry once per session after printing it, and writes `registered_at` to the session's fingerprint.yaml. The call has a 3 s timeout and never changes the output or the exit code. Failures go to one line in `~/.hq/fingerprint.log` with no token values. `--no-register`, `--offline` and `HQ_FINGERPRINT_OFFLINE=1` skip it. Outpost hosts, which the registry does not accept, log a skip once and are not retried (US-007).
+- `hq fingerprint <value>` asks the HQ registry when no local session record matches, and prints source `registry` with the identity name, machine label and host kind. `--json` includes `source`, `label` and `firstSeenAt`. A value found nowhere prints `no fingerprint record` and exits 1. A local match makes no network call (US-007).
+- `hq fingerprint self` run outside an HQ folder prints a fingerprint with machine `-`, creates no files, skips registration and reports `reason: "no HQ root"` in `--json`. A registry that answers 404 records `registration_skipped: unavailable`, logs one line and is not called again for that session (US-005).
+
 ## [5.345.134] — 2026-10-15
 - `hq access --as <member>` now honors the most specific ACL row covering a path, so an empty folder lock reports no access instead of the write access of a broader grant. `hq access` also reports "no access" rather than "never created" when a caller cannot list a path that an ACL lock denies them.
 

package/dist/command-catalog.generated.d.ts

@@ -1352,6 +1352,51 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly hidden: false;
     }];
     readonly subcommands: readonly [];
+}, {
+    readonly name: "fingerprint";
+    readonly description: "Print this session's HQ fingerprint, or resolve a fingerprint to its session";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly helpOption: true;
+    readonly helpCommand: false;
+    readonly usage: "[options] [command] [value]";
+    readonly helpText: readonly [];
+    readonly arguments: readonly [{
+        readonly name: "value";
+        readonly required: false;
+        readonly variadic: false;
+        readonly description: "fingerprint value to resolve (hqfp1:...)";
+    }];
+    readonly options: readonly [{
+        readonly flags: "--json";
+        readonly description: "output JSON";
+        readonly hidden: false;
+    }];
+    readonly subcommands: readonly [{
+        readonly name: "self";
+        readonly description: "Print the fingerprint for the current HQ session";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly helpOption: true;
+        readonly helpCommand: false;
+        readonly usage: "[options]";
+        readonly helpText: readonly [];
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--json";
+            readonly description: "output JSON";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--offline";
+            readonly description: "never make a network call (identity lookup or registration)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--no-register";
+            readonly description: "do not record this fingerprint with the HQ registry";
+            readonly hidden: false;
+        }];
+        readonly subcommands: readonly [];
+    }];
 }, {
     readonly name: "capture";
     readonly description: "Record your screen with HQ Capture: start, record, stop, status and wait";

package/dist/command-catalog.generated.js

@@ -1621,6 +1621,62 @@ export const COMMAND_CATALOG = [
         ],
         "subcommands": []
     },
+    {
+        "name": "fingerprint",
+        "description": "Print this session's HQ fingerprint, or resolve a fingerprint to its session",
+        "aliases": [],
+        "hidden": false,
+        "helpOption": true,
+        "helpCommand": false,
+        "usage": "[options] [command] [value]",
+        "helpText": [],
+        "arguments": [
+            {
+                "name": "value",
+                "required": false,
+                "variadic": false,
+                "description": "fingerprint value to resolve (hqfp1:...)"
+            }
+        ],
+        "options": [
+            {
+                "flags": "--json",
+                "description": "output JSON",
+                "hidden": false
+            }
+        ],
+        "subcommands": [
+            {
+                "name": "self",
+                "description": "Print the fingerprint for the current HQ session",
+                "aliases": [],
+                "hidden": false,
+                "helpOption": true,
+                "helpCommand": false,
+                "usage": "[options]",
+                "helpText": [],
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "output JSON",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--offline",
+                        "description": "never make a network call (identity lookup or registration)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--no-register",
+                        "description": "do not record this fingerprint with the HQ registry",
+                        "hidden": false
+                    }
+                ],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "capture",
         "description": "Record your screen with HQ Capture: start, record, stop, status and wait",

package/dist/command-registration-plan.d.ts

@@ -213,6 +213,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/version.js";
     readonly exportName: "registerVersionCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "fingerprint";
+    readonly parent: "program";
+    readonly module: "./commands/fingerprint.js";
+    readonly exportName: "registerFingerprintCommand";
 }, {
     readonly type: "registrar";
     readonly root: "capture";

package/dist/command-registration-plan.js

@@ -38,6 +38,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "resolve-company", parent: "program", module: "./commands/link.js", exportName: "registerResolveCompanyCommand" },
     { type: "registrar", root: "provider", parent: "program", module: "./commands/provider.js", exportName: "registerProviderCommand" },
     { type: "registrar", root: "version", parent: "program", module: "./commands/version.js", exportName: "registerVersionCommand" },
+    { type: "registrar", root: "fingerprint", parent: "program", module: "./commands/fingerprint.js", exportName: "registerFingerprintCommand" },
     { type: "registrar", root: "capture", parent: "program", module: "./commands/capture.js", exportName: "registerCaptureCommand" },
     { type: "registrar", root: "auth", parent: "program", module: "./commands/auth.js", exportName: "registerAuthCommands" },
     { type: "registrar", root: "secrets", parent: "program", module: "./commands/secrets.js", exportName: "registerSecretsCommand" },

package/dist/commands/core-bucket-c-handoff-knowledge-native.d.ts

@@ -10,6 +10,8 @@ type CommandResult = {
     stderr: string | Buffer;
 };
 type GitRunner = (args: string[], cwd: string) => CommandResult;
+/** Builds the HQ-Fingerprint commit trailer value; null adds no trailer. */
+export type FingerprintBuilder = (root: string) => string | null;
 declare function samePath(left: string, right: string): boolean;
 declare function windowsNativePath(value: string): string;
 declare function safePath(value: unknown): value is string;
@@ -30,7 +32,7 @@ declare function parseNulPaths(status: string): {
     paths: string[];
     originals: string[];
 };
-export declare function runHandoffKnowledgeCommit(args: readonly string[], cwd?: string, git?: GitRunner): KnowledgeCommitResult;
+export declare function runHandoffKnowledgeCommit(args: readonly string[], cwd?: string, git?: GitRunner, buildFingerprint?: FingerprintBuilder): KnowledgeCommitResult;
 export declare const __handoffKnowledgeTest: {
     safePath: typeof safePath;
     validChangeset: typeof validChangeset;

package/dist/commands/core-bucket-c-handoff-knowledge-native.js

@@ -1,10 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fingerprintTrailerArgs, offlineFingerprint } from "../lib/fingerprint/offline.js";
 export const HANDOFF_KNOWLEDGE_COMMIT_ASSET = "core/scripts/handoff-knowledge-commit.sh";
 const USAGE = "Usage: handoff-knowledge-commit.sh --files-touched-json-file <path> [--root <hq-root>]";
 const fail = (message, code = 1) => ({ code, stdout: "", stderr: message + "\n" });
 const gitDefault = (args, cwd) => spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const fingerprintDefault = (root) => offlineFingerprint(root, process.env, "hq handoff", { readOnly: true });
 const text = (value) => typeof value === "string" ? value : value.toString("utf8");
 function canonicalPath(value) {
     const slashPath = value.replaceAll("\\", "/");
@@ -157,7 +159,7 @@ function parseNulPaths(status) {
     }
     return { paths, originals };
 }
-function commitKnowledge(git, root, changes, handled, output) {
+function commitKnowledge(git, root, changes, handled, output, trailer) {
     for (const entry of entriesUnder(root)) {
         let stat;
         try {
@@ -209,7 +211,7 @@ function commitKnowledge(git, root, changes, handled, output) {
             output.stderr.push(text(add.stderr));
             return { code: add.status ?? 1, stdout: output.stdout.join(""), stderr: output.stderr.join("") };
         }
-        const commit = git(["commit", "--only", "-m", "checkpoint: save session knowledge changes", "--", ...repoPaths], repo);
+        const commit = git(["commit", "--only", "-m", "checkpoint: save session knowledge changes", ...trailer(), "--", ...repoPaths], repo);
         output.stdout.push(text(commit.stdout));
         output.stderr.push(text(commit.stderr));
         if (commit.status !== 0)
@@ -217,7 +219,7 @@ function commitKnowledge(git, root, changes, handled, output) {
     }
     return undefined;
 }
-export function runHandoffKnowledgeCommit(args, cwd = process.cwd(), git = gitDefault) {
+export function runHandoffKnowledgeCommit(args, cwd = process.cwd(), git = gitDefault, buildFingerprint = fingerprintDefault) {
     let changesFile = "";
     let root = cwd;
     for (let index = 0; index < args.length;) {
@@ -270,7 +272,9 @@ export function runHandoffKnowledgeCommit(args, cwd = process.cwd(), git = gitDe
     });
     const output = { stdout: [], stderr: [] };
     const handled = new Set();
-    const commitFailure = commitKnowledge(git, root, changes, handled, output);
+    let trailerArgs;
+    const trailer = () => (trailerArgs ??= fingerprintTrailerArgs(buildFingerprint(root)));
+    const commitFailure = commitKnowledge(git, root, changes, handled, output, trailer);
     if (commitFailure)
         return commitFailure;
     for (const touched of changes) {

package/dist/commands/core-handoff.d.ts

@@ -13,6 +13,8 @@ type HandoffContext = {
     now?: () => Date;
     /** Test-only override for the finalizer's historical fixed /tmp paths. */
     tmpDir?: string;
+    /** Builds the HQ-Fingerprint commit trailer value. Defaults to the offline builder. */
+    buildFingerprint?: (root: string) => string | null;
 };
 export declare function runHandoffFinalize(args: string[], context: HandoffContext): RunResult;
 export declare function runHandoffPost(args: string[], context: HandoffContext): RunResult | Promise<RunResult>;

package/dist/commands/core-handoff.js

@@ -14,6 +14,7 @@ import { resolveLiveRoot } from "../utils/hq-roots.js";
 import { runBundledScript } from "../utils/run-bundled-script.js";
 import { describeCoreCommand } from "./core-command-catalog.js";
 import { shellDisplayPath } from "../lib/core-utils/shell-display-path.js";
+import { fingerprintTrailerArgs, offlineFingerprint } from "../lib/fingerprint/offline.js";
 import { compactJson, isRecord, jqTruthy, prettyJson, runHandoffOpenSteps, shellDate, } from "./core-handoff-open-steps.js";
 export { runHandoffOpenSteps };
 const ASSETS = {
@@ -585,7 +586,8 @@ export function runHandoffFinalize(args, context) {
         if (probe.hasGit && staged > 0) {
             const pending = git(["diff", "--cached", "--name-only"], root).stdout.split(/\r?\n/).filter(Boolean);
             if (pending.length > 0) {
-                const committed = git(["commit", "-m", `checkpoint: handoff ${threadId}`], root);
+                const fingerprint = (context.buildFingerprint ?? ((hqRoot) => offlineFingerprint(hqRoot, process.env, "hq handoff", { readOnly: true })))(root);
+                const committed = git(["commit", "-m", `checkpoint: handoff ${threadId}`, ...fingerprintTrailerArgs(fingerprint)], root);
                 if (committed.code === 0) {
                     hqCommitted = true;
                     commitStatus = "committed";

package/dist/commands/core-pipeline-workflow-runner-native.js

@@ -340,18 +340,20 @@ function readSessionCompanySlugs(sid) {
     return [...new Set(slugs)];
 }
 function parentSessionId() {
-    return String(process.env.HQ_PARENT_SESSION_ID
-        || process.env.HQ_SESSION_ID
+    const own = process.env.HQ_SESSION_ID
         || process.env.CLAUDE_CODE_SESSION_ID
         || process.env.CLAUDE_SESSION_ID
         || process.env.CODEX_SESSION_ID
-        || process.env.CODEX_THREAD_ID
-        || '').replace(/\s+/g, '');
+        || process.env.CODEX_THREAD_ID;
+    // Inside a lane worker HQ_PARENT_SESSION_ID names the session that started
+    // the worker; the worker's own session is the parent of what it spawns.
+    const laneWorker = Boolean(process.env.HQ_LANE_ID?.trim()) && Boolean(own?.trim());
+    return String((laneWorker ? own : process.env.HQ_PARENT_SESSION_ID || own) || '').replace(/\s+/g, '');
 }
 function engineChildEnv() {
     const extra = {};
     const parent = parentSessionId();
-    if (!process.env.HQ_PARENT_SESSION_ID && parent)
+    if (parent && parent !== process.env.HQ_PARENT_SESSION_ID)
         extra.HQ_PARENT_SESSION_ID = parent;
     if (!process.env.HQ_SPAWN_COMPANY) {
         const capability = readSessionCompanyCapability(parent);

package/dist/commands/fingerprint.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/**
+ * The HQ root for `self`: HQ_ROOT, else the nearest ancestor of `cwd` (itself
+ * included) that holds `.claude` or `workers` and core/core.yaml. Null when
+ * there is none. Unlike findHqRoot it never falls back to `cwd`, so a commit
+ * in an unrelated repo does not create `.hq/` or session files there.
+ */
+export declare function findSelfHqRoot(env?: NodeJS.ProcessEnv, cwd?: string, existsSync?: (candidate: string) => boolean): string | null;
+export declare function registerFingerprintCommand(program: Command): void;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/commands/fingerprint.js

@@ -0,0 +1,191 @@
+/**
+ * hq fingerprint - print or resolve HQ session fingerprints.
+ *
+ *   hq fingerprint self [--json] [--offline] [--no-register]
+ *   hq fingerprint <value> [--json]
+ *
+ * `self` records the fingerprint with the hq-pro registry once per session
+ * after printing it (skipped with --no-register, --offline, and
+ * HQ_FINGERPRINT_OFFLINE=1). `<value>` checks local session records first and
+ * asks the registry only when none matches.
+ *
+ * Exit codes for `hq fingerprint <value>`: 0 found, 1 no fingerprint record,
+ * 2 not an HQ fingerprint. `self` exits 0 whether or not a value is built or
+ * registered.
+ *
+ * Outside an HQ tree (no HQ_ROOT and no ancestor with `.claude` or `workers`
+ * plus core/core.yaml) `self` prints a fingerprint with machine `-`, writes
+ * nothing, skips registration, and reports `reason: "no HQ root"` in --json.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isFingerprint } from "../lib/fingerprint/format.js";
+import { resolveLocalFingerprint } from "../lib/fingerprint/resolve-local.js";
+import { buildSelfFingerprint, registerSelfFingerprint } from "../lib/fingerprint/self.js";
+import { findHqRoot } from "../utils/manifest.js";
+function hqRootFromEnv() {
+    return process.env.HQ_ROOT || findHqRoot();
+}
+/**
+ * The HQ root for `self`: HQ_ROOT, else the nearest ancestor of `cwd` (itself
+ * included) that holds `.claude` or `workers` and core/core.yaml. Null when
+ * there is none. Unlike findHqRoot it never falls back to `cwd`, so a commit
+ * in an unrelated repo does not create `.hq/` or session files there.
+ */
+export function findSelfHqRoot(env = process.env, cwd = process.cwd(), existsSync = fs.existsSync) {
+    const fromEnv = env.HQ_ROOT?.trim();
+    if (fromEnv)
+        return fromEnv;
+    let dir = path.resolve(cwd);
+    while (true) {
+        const marked = existsSync(path.join(dir, ".claude")) || existsSync(path.join(dir, "workers"));
+        if (marked && existsSync(path.join(dir, "core", "core.yaml")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+async function loadIdToken() {
+    const { loadCachedTokens } = await import("../utils/cognito-session.js");
+    return loadCachedTokens()?.idToken ?? null;
+}
+/** Asks the registry about a fingerprint with no local record. Never throws. */
+async function lookupRegistry(value) {
+    // Loaded here so a local hit never loads the registry client.
+    const registry = await import("../lib/fingerprint/registry-client.js");
+    let token;
+    try {
+        token = await loadIdToken();
+    }
+    catch (err) {
+        registry.appendFingerprintLog("lookup", `failed: could not read the cached token: ${err.name}`);
+        return null;
+    }
+    if (!token)
+        return null;
+    const result = await registry.lookupFingerprint(value, token);
+    if (!result.ok) {
+        registry.appendFingerprintLog("lookup", `failed: ${registry.describeFailure(result)} fingerprint=${value}`);
+        return null;
+    }
+    return result.found ? result.record : null;
+}
+export function registerFingerprintCommand(program) {
+    const fingerprint = program
+        .command("fingerprint")
+        .description("Print this session's HQ fingerprint, or resolve a fingerprint to its session")
+        .argument("[value]", "fingerprint value to resolve (hqfp1:...)")
+        .option("--json", "output JSON")
+        .action(async (value, opts) => {
+        if (!value) {
+            fingerprint.help();
+            return;
+        }
+        if (!isFingerprint(value)) {
+            process.stderr.write("not an HQ fingerprint\n");
+            process.exitCode = 2;
+            return;
+        }
+        const record = resolveLocalFingerprint(hqRootFromEnv(), value);
+        if (record) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify({ ...record, found: true })}\n`);
+                return;
+            }
+            const lines = [
+                `fingerprint: ${record.fingerprint}`,
+                `identity:    ${record.identityUid ?? "-"} (${record.identityKind ?? "unknown"})`,
+                `machine:     ${record.machineId ?? "-"} (${record.hostKind ?? "unknown"})`,
+                `session:     ${record.sessionId ?? "-"}`,
+                `company:     ${record.company ?? "-"}`,
+                `source:      ${record.source}`,
+            ];
+            process.stdout.write(`${lines.join("\n")}\n`);
+            return;
+        }
+        let remote = null;
+        try {
+            remote = await lookupRegistry(value);
+        }
+        catch (err) {
+            // lookupRegistry already turns request failures into null; this is a
+            // failure to load the client itself.
+            process.stderr.write(`hq fingerprint: registry lookup failed: ${err.message}\n`);
+        }
+        if (!remote) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify({ fingerprint: value, found: false })}\n`);
+            }
+            process.stderr.write("no fingerprint record\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({
+                fingerprint: value,
+                ...remote,
+                source: "registry",
+                label: remote.machineLabel,
+                firstSeenAt: remote.firstSeenAt,
+                found: true,
+            })}\n`);
+            return;
+        }
+        const identityName = remote.identityName ? `${remote.identityName} ` : "";
+        const machineLabel = remote.machineLabel ? `${remote.machineLabel} ` : "";
+        const lines = [
+            `fingerprint: ${value}`,
+            `identity:    ${identityName}(${remote.identityUid}, ${remote.identityKind})`,
+            `machine:     ${machineLabel}(${remote.hostKind})`,
+            `session:     ${remote.sessionId}`,
+            `company:     ${remote.companySlug}`,
+            `first seen:  ${remote.firstSeenAt}`,
+            `source:      registry`,
+        ];
+        process.stdout.write(`${lines.join("\n")}\n`);
+    });
+    fingerprint
+        .command("self")
+        .description("Print the fingerprint for the current HQ session")
+        .option("--json", "output JSON")
+        .option("--offline", "never make a network call (identity lookup or registration)")
+        .option("--no-register", "do not record this fingerprint with the HQ registry")
+        .action(async (_opts, cmd) => {
+        // The parent also defines --json and commander hands it to the parent,
+        // so read the merged options.
+        const opts = cmd.optsWithGlobals();
+        const offline = opts.offline === true || process.env.HQ_FINGERPRINT_OFFLINE === "1";
+        const foundRoot = findSelfHqRoot();
+        const noRoot = foundRoot === null;
+        const hqRoot = foundRoot ?? process.cwd();
+        // The commit-msg hook calls this on every commit, so it never throws
+        // and always exits 0.
+        let result;
+        let built = null;
+        try {
+            built = await buildSelfFingerprint({ hqRoot, offline, noRoot });
+            result = built;
+        }
+        catch (err) {
+            process.stderr.write(`hq fingerprint: ${err.message}\n`);
+            result = { fingerprint: null, reason: `could not build fingerprint: ${err.message}` };
+        }
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+        }
+        else if (result.fingerprint) {
+            process.stdout.write(`${result.fingerprint}\n`);
+        }
+        else {
+            process.stdout.write(`no fingerprint: ${result.reason ?? "unknown"}\n`);
+        }
+        // Registration runs after the output is written and reports only to
+        // ~/.hq/fingerprint.log; registerSelfFingerprint does not throw.
+        if (built?.fingerprint && !noRoot) {
+            await registerSelfFingerprint(built, { hqRoot, offline, register: opts.register !== false });
+        }
+    });
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/commands/lanes.js

@@ -2432,11 +2432,18 @@ function autopilotWorkerStarter(ctx) {
         return { lane_id: started.lane_id };
     };
 }
+/**
+ * The senior for a lane created without `--senior`. Inside a lane worker
+ * (HQ_LANE_ID set) the worker's own session wins, because HQ_PARENT_SESSION_ID
+ * there names the session that started the worker, one level too high.
+ */
 function defaultSenior(ctx) {
+    const sessionId = sessionIdFromEnv(ctx.env);
+    if (ctx.env.HQ_LANE_ID?.trim() && sessionId)
+        return { kind: "session", id: sessionId };
     const parent = ctx.env.HQ_PARENT_SESSION_ID?.trim();
     if (parent)
         return { kind: "session", id: parent };
-    const sessionId = sessionIdFromEnv(ctx.env);
     if (sessionId)
         return { kind: "session", id: sessionId };
     return { kind: "user" };
@@ -6305,6 +6312,7 @@ async function runShow(ctx, laneId, hasPendingQuestionForLane, resolveLaneTarget
         ...(showRefresh.remoteRefresh === undefined ? {} : { remote_refresh: showRefresh.remoteRefresh }),
         provider_session_id: lane.provider_session_id ?? null,
         provider_session_id_absent: lane.provider_session_id_absent ?? null,
+        fingerprint: lane.fingerprint ?? null,
         envelope_repair_mode: lane.envelope_repair?.mode ?? null,
         envelope_validation_errors: lane.envelope_validation_errors ?? [],
         last_resume: lane.last_resume ?? null,

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