@bli-cockpit/cli 0.2.57 → 0.2.59

package/dist/commands/setup-receipt.js

@@ -0,0 +1,241 @@
+/**
+ * "Is this machine actually connected?" — computed here, on the machine
+ * (BLI-3731).
+ *
+ * Seven words, every one of them READ BACK off this host rather than
+ * remembered from what we wrote. That rule is BLI-2541's, and it is the whole
+ * value of this module: `cockpit autostart` once registered a correct Windows
+ * task and then rejected it on every machine for months because it compared
+ * the readback against the strings Cockpit itself had sent.
+ *
+ * Where each word comes from:
+ *
+ *   browser              the device session on disk names a person. A device
+ *                        token exists ONLY because somebody signed a browser
+ *                        in, so the session file is the evidence — there is no
+ *                        second thing to ask.
+ *   device               that same session, still unexpired.
+ *   collector.autostart  `autostartStatus`, which asks launchd or Task
+ *                        Scheduler what it actually has registered.
+ *
+ * The five AGENT-HOST words in the printed block are NOT computed here. They
+ * are BLI-3729's `MemoryInstallReceipt`, already read back off
+ * `~/.claude.json`, `~/.claude/settings.json` and `~/.codex/config.toml`,
+ * already cached beside this one and already carried on the heartbeat as
+ * `memory_install`. This module reads that cache and hands both halves to the
+ * renderer. A second computation of the same five words would be a second
+ * place for them to be wrong.
+ *
+ * A piece this run did not inspect is `unknown`, never `missing`. The two are
+ * different facts and only one of them is somebody's problem.
+ *
+ * The SHAPE lives in `@bli-cockpit/telemetry-core` so the CLI and the
+ * dashboard word the same machine the same way; `memory-install-contract.ts`
+ * owns the target vocabulary this translates from.
+ */
+import os from "node:os";
+import { SETUP_RECEIPT_SCHEMA_VERSION, setupReceiptGaps, setupReceiptLine, } from "@bli-cockpit/telemetry-core";
+import { readHeartbeatMemoryReceipt } from "./heartbeat.js";
+import { autostartStatus } from "../autostart.js";
+import { readLocalSessionReference } from "../local-state.js";
+import { getCollectorRuntimePaths } from "../local-state-paths.js";
+import { readJsonFile, writeJsonFile } from "../local-state-files.js";
+const TAG = "[setup receipt]";
+/** Where the last computed receipt is cached, so a heartbeat need not re-probe. */
+export const SETUP_RECEIPT_CACHE_FILE = "setup-receipt.json";
+/**
+ * How stale a cached receipt may be before the heartbeat stops sending it.
+ * Seven days: these facts change about monthly, and re-probing them costs five
+ * file reads and a `--print-config` spawn that a 15-minute tick must not pay.
+ */
+export const SETUP_RECEIPT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export async function buildSetupReceipt(io, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const checkedAt = (options.now ?? new Date()).toISOString();
+    const probes = withDefaultProbes(io, homeDir, options);
+    const memory = await probes.memory().catch((error) => {
+        console.error(`${TAG} the memory receipt could not be read`, JSON.stringify({ reason: "memory_receipt_read_failed", error_name: errorName(error) }));
+        return null;
+    });
+    const session = await probes.session().catch((error) => {
+        console.error(`${TAG} device session could not be read`, JSON.stringify({ reason: "session_probe_failed", error_name: errorName(error) }));
+        return null;
+    });
+    const autostart = await probes.autostart().catch((error) => {
+        console.error(`${TAG} scheduler could not be read`, JSON.stringify({ reason: "autostart_probe_failed", error_name: errorName(error) }));
+        return { status: "unreadable" };
+    });
+    const receipt = {
+        schema_version: SETUP_RECEIPT_SCHEMA_VERSION,
+        checked_at: checkedAt,
+        browser: browserPiece(session),
+        device: devicePiece(session),
+        collector: { autostart: autostartPiece(autostart) },
+    };
+    const gaps = setupReceiptGaps(receipt, memory);
+    console.error(`${TAG} read back`, JSON.stringify({
+        reason: gaps.length === 0 ? "everything_connected" : "gaps_found",
+        gap_count: gaps.length,
+        gaps,
+        memory_receipt: memory ? "read" : "absent",
+    }));
+    return { receipt, memory };
+}
+function withDefaultProbes(io, homeDir, options) {
+    return {
+        memory: options.probes?.memory ??
+            (async () => (await readHeartbeatMemoryReceipt({
+                homeDir,
+                ...(options.now ? { now: options.now } : {}),
+            })).receipt),
+        session: options.probes?.session ??
+            (async () => {
+                const reference = await readLocalSessionReference(getCollectorRuntimePaths(homeDir));
+                return {
+                    state: reference.session_state,
+                    ...(reference.email ? { email: reference.email } : {}),
+                };
+            }),
+        autostart: options.probes?.autostart ??
+            (async () => {
+                // The scheduler can only be READ through a process runner; a machine
+                // whose io carries none is unknown, never "absent" (BLI-2541: never
+                // report a state you did not observe).
+                const exec = io.exec;
+                if (!exec)
+                    return { status: "unreadable", message: "runner_unavailable" };
+                const result = await autostartStatus({ homeDir, exec });
+                return {
+                    status: result.status,
+                    ...(result.message ? { message: result.message } : {}),
+                };
+            }),
+    };
+}
+/**
+ * A device token exists only because a person signed a browser in and claimed
+ * this machine, so a session that names an email IS the browser receipt. A
+ * session with no email came from the manual admin-approval path, which is a
+ * real way to pair and not a browser sign-in — it says so rather than claiming
+ * a click nobody made.
+ */
+function browserPiece(session) {
+    if (!session)
+        return { status: "unknown", reason: "session_unreadable" };
+    if (session.state !== "valid") {
+        return { status: "missing", reason: "never_signed_in" };
+    }
+    return session.email
+        ? { status: "ok", reason: "signed_in" }
+        : { status: "ok", reason: "paired_without_email" };
+}
+function devicePiece(session) {
+    if (!session)
+        return { status: "unknown", reason: "session_unreadable" };
+    if (session.state === "valid")
+        return { status: "ok", reason: "session_valid" };
+    if (session.state === "expired") {
+        return { status: "missing", reason: "session_expired" };
+    }
+    return { status: "missing", reason: `session_${session.state}` };
+}
+/**
+ * The scheduler is `ok` only when the host says it is registered AND loaded.
+ * `installed` on macOS means the plist is on disk; `loaded` means launchd has
+ * it. A plist nobody loaded runs nothing, which is exactly the failure that
+ * looks fine from the outside.
+ */
+function autostartPiece(result) {
+    if (result.status === "loaded" || result.status === "installed") {
+        return { status: "ok", reason: `autostart_${result.status}` };
+    }
+    if (result.status === "not_loaded") {
+        return { status: "missing", reason: "autostart_not_loaded" };
+    }
+    if (result.status === "absent" || result.status === "uninstalled") {
+        return { status: "missing", reason: "autostart_absent" };
+    }
+    if (result.status === "unsupported") {
+        return { status: "skipped", reason: "platform_unsupported" };
+    }
+    return { status: "unknown", reason: normalizeReason(result.status) };
+}
+/** Reason labels are `[a-z0-9_:.-]` by schema; anything else becomes one word. */
+function normalizeReason(value) {
+    const cleaned = value.trim().toLowerCase().replace(/[^a-z0-9_:.-]+/gu, "_");
+    return cleaned.slice(0, 120) || "unlabelled";
+}
+function errorName(error) {
+    return error instanceof Error ? error.name : typeof error;
+}
+// ---------------------------------------------------------------------------
+// The cache — so a 15-minute tick does not re-probe a monthly fact
+// ---------------------------------------------------------------------------
+export function setupReceiptCachePath(homeDir) {
+    const paths = getCollectorRuntimePaths(homeDir ?? os.homedir());
+    return `${paths.state_dir}/${SETUP_RECEIPT_CACHE_FILE}`;
+}
+/** Never fails a caller: a cache that could not be written names itself and moves on. */
+export async function cacheSetupReceipt(receipt, homeDir) {
+    try {
+        await writeJsonFile(setupReceiptCachePath(homeDir), receipt);
+    }
+    catch (error) {
+        console.error(`${TAG} cache not written`, JSON.stringify({ reason: "cache_write_failed", error_name: errorName(error) }));
+    }
+}
+/**
+ * The cached receipt, or null with a named reason. A receipt older than
+ * `SETUP_RECEIPT_MAX_AGE_MS` is refused rather than sent: a stale word is
+ * worse than an absent one, because absence asks and staleness answers.
+ */
+export async function readCachedSetupReceipt(homeDir, now = new Date()) {
+    let raw;
+    try {
+        raw = await readJsonFile(setupReceiptCachePath(homeDir));
+    }
+    catch {
+        // Absent on a machine that has never run the install. Not an error, and
+        // the caller logs the absence with its own reason.
+        return null;
+    }
+    const parsed = safeParseReceipt(raw);
+    if (!parsed) {
+        console.error(`${TAG} cache unusable`, JSON.stringify({ reason: "cache_not_a_receipt" }));
+        return null;
+    }
+    const age = now.getTime() - Date.parse(parsed.checked_at);
+    if (!Number.isFinite(age) || age > SETUP_RECEIPT_MAX_AGE_MS) {
+        console.error(`${TAG} cache too old to send`, JSON.stringify({ reason: "cache_stale", age_days: Math.round(age / 86_400_000) }));
+        return null;
+    }
+    return parsed;
+}
+function safeParseReceipt(raw) {
+    const record = raw;
+    if (!record || record.schema_version !== SETUP_RECEIPT_SCHEMA_VERSION)
+        return null;
+    return raw;
+}
+/** The one line, plus the one fix per gap. Rendering lives in `setup-receipt-lines.ts`. */
+export { setupReceiptLine };
+/**
+ * Read the machine, cache what it said, and hand it back. The ONE entry point
+ * for every surface that shows the receipt (`status`, `doctor`, `onboard`,
+ * `memory install`) — so the block a person reads in a terminal and the block
+ * the ops board renders are always the same reading, not two.
+ *
+ * Never throws: a receipt that could not be computed is `null` with a named
+ * reason, and the caller prints nothing rather than a wrong reassurance.
+ */
+export async function refreshSetupReceipt(io, options = {}) {
+    try {
+        const reading = await buildSetupReceipt(io, options);
+        await cacheSetupReceipt(reading.receipt, options.homeDir);
+        return reading;
+    }
+    catch (error) {
+        console.error(`${TAG} could not be computed`, JSON.stringify({ reason: "receipt_build_failed", error_name: errorName(error) }));
+        return null;
+    }
+}

package/dist/commands/status.js

@@ -15,6 +15,8 @@ import path from "node:path";
 import { writeLine } from "./cli-io.js";
 import { displayTicketId, displayWorkLabel, shortSha, stuckEvidenceLine, } from "./collection-report.js";
 import { discoverCommandWorktrees } from "./local-discovery.js";
+import { refreshSetupReceipt } from "./setup-receipt.js";
+import { setupReceiptBlock } from "./setup-receipt-lines.js";
 import { defaultCodexSessionDirs } from "../adapters/codex-attribution.js";
 import { describeError } from "../health-detail.js";
 import { backfillCompletionCovers, emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
@@ -43,8 +45,19 @@ export async function runStatus(command, io) {
         return 0;
     }
     const status = await inspectLocalCollectorStatus(command);
+    // BLI-3731: "is this machine actually connected?" belongs beside "is it
+    // collecting?", and it is read back off the host rather than remembered.
+    // Refreshing here also keeps the heartbeat's cache warm without the 15-minute
+    // tick paying for the probe.
+    const setupReceipt = await refreshSetupReceipt(io, {
+        ...(command.homeDir ? { homeDir: command.homeDir } : {}),
+    });
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify({ ...status, backfill_cursor: backfillCursor }, null, 2));
+        writeLine(io.stdout, JSON.stringify({
+            ...status,
+            backfill_cursor: backfillCursor,
+            setup_receipt: setupReceipt?.receipt ?? null,
+        }, null, 2));
         return 0;
     }
     writeLine(io.stdout, "Tower status");
@@ -69,6 +82,12 @@ export async function runStatus(command, io) {
     writeLine(io.stdout, `Stuck files: ${stuckEvidenceLine(status)}`);
     for (const detail of status.details)
         writeLine(io.stdout, `- ${detail}`);
+    writeLine(io.stdout, "Connected:");
+    for (const line of setupReceipt
+        ? setupReceiptBlock(setupReceipt, { indent: "  " })
+        : ["  unknown — run `cockpit doctor` to read this machine."]) {
+        writeLine(io.stdout, line);
+    }
     return 0;
 }
 /**

package/dist/local-state-pairing-code.js

@@ -0,0 +1,200 @@
+import { LocalCollectorSessionFileSchema, } from "@bli-cockpit/telemetry-core";
+import os from "node:os";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { writeJsonFile } from "./local-state-files.js";
+import { DEFAULT_DASHBOARD_URL, defaultDeviceName, LOCAL_COLLECTOR_VERSION, normalizeDashboardUrl, normalizeDeviceName, readLocalCollectorConfig, } from "./local-state-config.js";
+import { toSessionReference } from "./local-state-session.js";
+/** Everything that can go wrong, with the same name on both sides of the wire. */
+export class PairingCodeError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "PairingCodeError";
+        this.reason = reason;
+    }
+}
+const TAG = "[pair link]";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+export async function pairLocalCollectorViaLink(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const dashboardUrl = normalizeDashboardUrl(options.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL);
+    const deviceId = config?.device_id;
+    if (!deviceId) {
+        throw new PairingCodeError("config_missing_device_id", "Local config has no device id. Run `cockpit onboard` (or `cockpit install`) first.");
+    }
+    const deviceName = normalizeDeviceName(options.deviceName) ??
+        config?.device_name ??
+        defaultDeviceName();
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new PairingCodeError("fetch_unavailable", "global fetch is unavailable; use Node.js 20 or newer.");
+    }
+    const minted = options.pairCode
+        ? null
+        : await mintPairingCode(fetchImpl, dashboardUrl, {
+            device_id: deviceId,
+            device_name: deviceName,
+            claimed_owner_email: options.claimedOwnerEmail,
+            collector_version: LOCAL_COLLECTOR_VERSION,
+        });
+    if (minted) {
+        options.onLinkReady?.({
+            connect_url: minted.connect_url,
+            expires_at: minted.expires_at,
+        });
+    }
+    const session = await pollExchange(fetchImpl, dashboardUrl, {
+        paths,
+        code: options.pairCode ?? minted?.code ?? "",
+        clientSecret: minted?.client_secret,
+        deviceId,
+        deviceName,
+        pollIntervalMs: options.pollIntervalMs ?? minted?.poll_after_ms,
+        timeoutMs: options.timeoutMs,
+        sleep: options.sleep,
+        now: options.now,
+    });
+    return {
+        status: "paired",
+        session: toSessionReference(session),
+        session_file: paths.session_file,
+        dashboard_url: dashboardUrl,
+        ...(minted ? { connect_url: minted.connect_url } : {}),
+        direction: minted ? "cli_first" : "browser_first",
+    };
+}
+async function mintPairingCode(fetchImpl, dashboardUrl, body) {
+    const response = await fetchImpl(`${dashboardUrl}/api/devices/pair/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const parsed = await readResponseJson(response, "mint");
+    if (!response.ok) {
+        throw refusalFrom("pair_code_mint_refused", response, parsed);
+    }
+    const record = asRecord(parsed);
+    const code = readString(record, "code");
+    const connectUrl = readString(record, "connect_url");
+    const expiresAt = readString(record, "expires_at");
+    if (!code || !connectUrl || !expiresAt) {
+        throw new PairingCodeError("pair_code_mint_malformed", "The dashboard did not return a usable pairing code.");
+    }
+    return {
+        code,
+        client_secret: readString(record, "client_secret") ?? undefined,
+        connect_url: connectUrl,
+        expires_at: expiresAt,
+        poll_after_ms: readNumber(record, "poll_after_ms") ?? 2_000,
+        direction: readString(record, "direction") === "browser_first"
+            ? "browser_first"
+            : "cli_first",
+    };
+}
+async function pollExchange(fetchImpl, dashboardUrl, options) {
+    if (!options.code) {
+        throw new PairingCodeError("pair_code_missing", "No pairing code to exchange.");
+    }
+    const pollIntervalMs = Math.max(250, options.pollIntervalMs ?? 2_000);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const sleepImpl = options.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const startedAt = options.now?.getTime() ?? Date.now();
+    const deadline = startedAt + timeoutMs;
+    let attempts = 0;
+    while (Date.now() <= deadline) {
+        attempts += 1;
+        const response = await fetchImpl(`${dashboardUrl}/api/devices/pair/exchange`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                code: options.code,
+                ...(options.clientSecret ? { client_secret: options.clientSecret } : {}),
+                device_id: options.deviceId,
+                device_name: options.deviceName,
+                collector_version: LOCAL_COLLECTOR_VERSION,
+            }),
+        });
+        const parsed = await readResponseJson(response, "exchange");
+        const record = asRecord(parsed);
+        const status = readString(record, "status");
+        if (!response.ok) {
+            throw refusalFrom(readString(record, "reason") ?? "pair_exchange_refused", response, parsed);
+        }
+        if (status === "paired") {
+            const session = parseExchangedSession(record, options.paths.session_file);
+            await writeJsonFile(options.paths.session_file, session);
+            console.error(`${TAG} paired`, JSON.stringify({ reason: "exchange_ok", attempts }));
+            return session;
+        }
+        if (status === "refused") {
+            throw new PairingCodeError(readString(record, "reason") ?? "pair_exchange_refused", readString(record, "message") ?? "Pairing was refused.");
+        }
+        if (status !== "pending_claim") {
+            throw new PairingCodeError("pair_exchange_unexpected_status", `Unexpected pairing status: ${status ?? "none"}`);
+        }
+        await sleepImpl(pollIntervalMs);
+    }
+    console.error(`${TAG} gave up waiting`, JSON.stringify({ reason: "pair_exchange_timeout", attempts }));
+    throw new PairingCodeError("pair_exchange_timeout", "Timed out waiting for the browser sign-in. Run `cockpit login` again.");
+}
+function parseExchangedSession(record, sessionFilePath) {
+    const session = record?.["session"];
+    if (!session || typeof session !== "object") {
+        throw new PairingCodeError("pair_exchange_no_session", "Pairing succeeded but the dashboard returned no session.");
+    }
+    return LocalCollectorSessionFileSchema.parse({
+        ...session,
+        session_file_path: sessionFilePath,
+    });
+}
+/**
+ * The server's own words first, then the status, so a captive portal, a wrong
+ * dashboard URL and a real refusal never read the same. Logged as well as
+ * thrown: pairing runs on a machine that is not collecting yet, so the
+ * terminal is the only receipt there is.
+ */
+function refusalFrom(reason, response, body) {
+    const record = asRecord(body);
+    const words = readString(record, "message") ??
+        readString(record, "error") ??
+        "Pairing request failed";
+    console.error(`${TAG} refused`, JSON.stringify({ reason, http_status: response.status }));
+    return new PairingCodeError(reason, `${words} (HTTP ${response.status})`);
+}
+async function readResponseJson(response, stage) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // A captive portal or a proxy answering with HTML is the classic reason a
+        // new machine cannot pair. The body is never logged; its shape is.
+        console.error(`${TAG} reply was not JSON`, JSON.stringify({
+            reason: "response_body_not_json",
+            stage,
+            http_status: response.status,
+            byte_size: text.length,
+            content_type: response.headers.get("content-type") ?? "none",
+        }));
+        return { message: text.slice(0, 200) };
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object"
+        ? value
+        : null;
+}
+function readString(record, field) {
+    const value = record?.[field];
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function readNumber(record, field) {
+    const value = record?.[field];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}

package/dist/local-state.js

@@ -18,6 +18,11 @@
  * - `local-state-pairing.ts` — `cockpit login` and `cockpit logout`: the two
  *   operations that make and unmake that session file, plus the pair
  *   start/poll HTTP client and its refusal message.
+ * - `local-state-pairing-code.ts` — the ONE-SIGN-IN ceremony (BLI-3731): mint
+ *   a pairing code, print and open `<dashboard>/connect?pair=…`, and poll the
+ *   exchange until the browser's single magic link has claimed it. Writes the
+ *   same session file its older sibling does, because the server issues it
+ *   from the same `pollDevicePairRequest`.
  * - `local-state-identity.ts` — which repo and worktree a folder is, with the
  *   path-derived fallback that keeps a non-git folder collectable.
  * - `local-state-attributed-target.ts` — re-derives a caller-supplied identity
@@ -34,6 +39,7 @@ export { getCollectorRuntimePaths } from "./local-state-paths.js";
 export { DEFAULT_DASHBOARD_URL, ensureLocalCollectorConfig, installLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
 export { readLocalCollectorSessionFile, readLocalSessionReference, } from "./local-state-session.js";
 export { logoutLocalCollector, pairLocalCollector, } from "./local-state-pairing.js";
+export { PairingCodeError, pairLocalCollectorViaLink, } from "./local-state-pairing-code.js";
 export { resolveGitBranch } from "./local-state-identity.js";
 export { readLocalWorkContext, readLocalWorkContextForRepo, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "./local-state-work-context.js";
 export { classifyCollectorFreshness, inspectLocalCollectorStatus, } from "./local-state-status.js";

package/dist/repo-identity-fingerprint.js

@@ -0,0 +1,88 @@
+/**
+ * Turning a filesystem path or a git origin URL into the stable ids this
+ * package hands out (`repo_fingerprint`, `worktree_fingerprint`, the label),
+ * plus the collection-root canonicalization built on the same realpath call.
+ * Sibling of `repo-identity.ts`, named in its header.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function stableWorktreeRoot(repoRoot) {
+    const resolvedRoot = path.resolve(repoRoot);
+    return fs.realpath(resolvedRoot).catch(() => resolvedRoot);
+}
+/**
+ * Canonicalizes existing collection roots through the filesystem so transcript
+ * paths and consent roots use the same spelling (for example `/private/var`
+ * versus the `/var` symlink on macOS). Missing roots remain resolved as typed.
+ */
+export async function canonicalizeCollectionRootPaths(roots) {
+    const canonical = await Promise.all(roots.map(stableWorktreeRoot));
+    return [...new Set(canonical)];
+}
+/**
+ * Returns the operator-entered resolved paths plus filesystem-canonical aliases.
+ * Both are needed for absent child repos because the child itself cannot be
+ * realpathed after deletion, while its transcript may retain either spelling.
+ */
+export async function collectionRootPathAliases(roots) {
+    const resolved = roots.map((root) => path.resolve(root));
+    const canonical = await canonicalizeCollectionRootPaths(resolved);
+    return [...new Set([...resolved, ...canonical])];
+}
+function normalizeFingerprintPath(repoRoot, pathApi = path) {
+    const resolved = pathApi.resolve(repoRoot);
+    return pathApi.sep === "\\" ? resolved.toLowerCase() : resolved;
+}
+export function stableWorktreeFingerprint(repoRoot, pathApi = path) {
+    return `wt-${sha256(`worktree:${normalizeFingerprintPath(repoRoot, pathApi)}`).slice(0, 24)}`;
+}
+export function repoFingerprintFromLocalRoot(root, pathApi = path) {
+    return `repo-${sha256(`local:${normalizeFingerprintPath(root, pathApi)}`).slice(0, 24)}`;
+}
+export function repoFingerprintFromOrigin(origin) {
+    const normalizedOrigin = normalizeGitOrigin(origin);
+    return `repo-${sha256(`origin:${normalizedOrigin}`).slice(0, 24)}`;
+}
+export function normalizeGitOrigin(rawOrigin) {
+    const trimmed = rawOrigin.trim();
+    if (!trimmed)
+        return "";
+    const scpLike = trimmed.match(/^(?:[^@]+@)?([^:]+):(.+)$/);
+    if (scpLike && !trimmed.includes("://")) {
+        return normalizeOriginParts(scpLike[1] ?? "", scpLike[2] ?? "");
+    }
+    try {
+        const url = new URL(trimmed);
+        return normalizeOriginParts(url.hostname, url.pathname);
+    }
+    catch {
+        // Deliberately silent (BLI-3238). `new URL` is being used as the test for
+        // "is this origin URL-shaped?", and a plain path or an unusual remote form
+        // failing to parse IS the answer — the fallback below is the intended
+        // normalization for exactly that case, not a degradation.
+        return trimmed
+            .replace(/\.git$/i, "")
+            .replace(/^\/+|\/+$/g, "")
+            .toLowerCase();
+    }
+}
+export function repoLabelFromOrigin(origin) {
+    const segments = origin.split("/").filter(Boolean);
+    return segments.at(-1) ?? origin;
+}
+function normalizeOriginParts(host, repoPath) {
+    return [
+        host.trim().toLowerCase(),
+        repoPath
+            .trim()
+            .replace(/\.git$/i, "")
+            .replace(/^\/+|\/+$/g, "")
+            .toLowerCase(),
+    ]
+        .filter(Boolean)
+        .join("/");
+}
+export function sha256(value) {
+    return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}

package/dist/repo-identity-git.js

@@ -0,0 +1,76 @@
+/**
+ * Every place this package shells out to `git`, plus the two ways a branch
+ * is read when git itself cannot be asked (a `.git` file's HEAD, for a
+ * linked worktree whose git process is unavailable). Sibling of
+ * `repo-identity.ts`, named in its header.
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+const execFileAsync = promisify(execFile);
+export async function runGit(args, cwd) {
+    const { stdout } = await execFileAsync("git", args, {
+        cwd,
+        timeout: 2_000,
+        maxBuffer: 1024 * 1024,
+    });
+    return stdout;
+}
+export async function hasGitMarker(dir) {
+    return fs.stat(path.join(dir, ".git")).then((stat) => stat.isDirectory() || stat.isFile(), () => false);
+}
+export async function resolveGitBranchWithGit(repoRoot) {
+    const branch = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot).then((value) => value.trim(), () => "");
+    if (branch && branch !== "HEAD")
+        return branch;
+    const head = await runGit(["rev-parse", "--short=12", "HEAD"], repoRoot).then((value) => value.trim(), () => "");
+    return head ? `detached:${head}` : "unknown";
+}
+export async function resolveBranchFromHead(repoRoot) {
+    try {
+        const gitPath = path.join(repoRoot, ".git");
+        const stat = await fs.stat(gitPath);
+        const headPath = stat.isFile()
+            ? path.join(await resolveLinkedGitDir(gitPath), "HEAD")
+            : path.join(gitPath, "HEAD");
+        const head = (await fs.readFile(headPath, "utf8")).trim();
+        if (head.startsWith("ref: refs/heads/")) {
+            return head.slice("ref: refs/heads/".length);
+        }
+        return head ? `detached:${head.slice(0, 12)}` : "unknown";
+    }
+    catch (error) {
+        // Not a repo → quiet, that is an ordinary approved folder. A `.git` that
+        // exists and will not read → every session from this worktree is labelled
+        // branch `unknown` and, until BLI-3238, nothing said why.
+        if (!isMissingFileFailure(error)) {
+            console.error("[repo-identity] could not read HEAD, branch recorded as unknown", JSON.stringify({
+                reason: "git_head_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return "unknown";
+    }
+}
+async function resolveLinkedGitDir(gitFile) {
+    const raw = await fs.readFile(gitFile, "utf8");
+    const match = raw.match(/^gitdir:\s*(.+)$/m);
+    if (!match)
+        return path.dirname(gitFile);
+    const gitDir = match[1].trim();
+    return path.isAbsolute(gitDir) ? gitDir : path.resolve(path.dirname(gitFile), gitDir);
+}
+export async function listLinkedWorktreePaths(repoRoot) {
+    const porcelain = await runGit(["worktree", "list", "--porcelain"], repoRoot).catch(() => "");
+    const paths = [];
+    for (const line of porcelain.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            const value = line.slice("worktree ".length).trim();
+            if (value)
+                paths.push(value);
+        }
+    }
+    return paths;
+}