@bli-cockpit/cli 0.2.56 → 0.2.57

package/dist/commands/tower-mcp-install.js

@@ -0,0 +1,75 @@
+/**
+ * `bli-tower`'s registration — the docs_* and msg_* MCP server, beside
+ * `bli-memory` (BLI-3706, "Agent-friendly is the definition of done").
+ *
+ * Rides `cockpit memory install`/`cockpit memory status` rather than a new
+ * verb: that command already runs unasked from `do-everything` and the daily
+ * sync tick (`memory-install.ts`'s own header), which is the ONLY way a
+ * registration reaches every intern machine without anyone typing anything.
+ * A second, un-invoked `cockpit mcp install` command would ship the feature
+ * and still leave every existing machine unregistered until someone learned
+ * to type the new verb.
+ *
+ * `no_bin_no_write` applies here too, for the identical reason
+ * `memory-install.ts` states it for `bli-memory-mcp`: a Claude Code entry
+ * pointing at a server that is not on this machine is a dead MCP connection
+ * on every startup, not a graceful absence.
+ */
+import os from "node:os";
+import { resolveMcpBin } from "./mcp-bin-resolve.js";
+import { installClaudeTowerIntegration, inspectClaudeTowerIntegration } from "./tower-mcp-claude.js";
+import { installCodexTowerIntegration, inspectCodexTowerIntegration } from "./tower-mcp-codex.js";
+import { builtinTowerInstallConfig, TOWER_MCP_BIN } from "./tower-mcp-contract.js";
+import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
+async function resolveTowerConfig(deps) {
+    const found = await resolveMcpBin({
+        binName: TOWER_MCP_BIN,
+        env: envWithNodeRuntimeOnPath(deps.env),
+        platform: deps.platform,
+        fileExists: deps.fileExists,
+        cliEntryPoint: deps.cliEntryPoint,
+        realpath: deps.realpath,
+    });
+    if (!found) {
+        return {
+            config: null,
+            binTarget: {
+                target: "tower_bin",
+                status: "skipped",
+                reason: "bin_missing",
+                detail: `${TOWER_MCP_BIN} is not installed beside this CLI or on PATH; nothing was written, and the next daily run will try again`,
+            },
+        };
+    }
+    return {
+        config: builtinTowerInstallConfig({ binPath: found.path, platform: deps.platform, dashboardUrl: deps.dashboardUrl }),
+        binTarget: { target: "tower_bin", status: "already", reason: "bin_present_template_used" },
+    };
+}
+export async function installTowerIntegration(deps, dryRun) {
+    const resolved = await resolveTowerConfig(deps);
+    const targets = [resolved.binTarget];
+    if (!resolved.config)
+        return targets;
+    targets.push(await installClaudeTowerIntegration({ homeDir: deps.homeDir, config: resolved.config, dryRun, io: deps.io }));
+    targets.push(await installCodexTowerIntegration({ homeDir: deps.homeDir, config: resolved.config, dryRun, io: deps.io }));
+    return targets;
+}
+export async function inspectTowerIntegration(deps) {
+    const resolved = await resolveTowerConfig(deps);
+    const targets = [resolved.binTarget];
+    if (!resolved.config)
+        return targets;
+    targets.push(await inspectClaudeTowerIntegration({ homeDir: deps.homeDir, config: resolved.config, io: deps.io }));
+    targets.push(await inspectCodexTowerIntegration({ homeDir: deps.homeDir, config: resolved.config, io: deps.io }));
+    return targets;
+}
+export function defaultTowerDeps(overrides) {
+    return {
+        platform: process.platform,
+        homeDir: os.homedir(),
+        dashboardUrl: overrides.dashboardUrl ?? "",
+        env: process.env,
+        ...overrides,
+    };
+}

package/dist/upload-envelope-build.js

@@ -0,0 +1,240 @@
+/**
+ * Is this machine ready to upload, and — if so — `buildLocalAmbientEnvelope`:
+ * five steps from a bare repo root to a validated envelope.
+ *
+ * - `readPairedCollector` — prove the collector is installed and paired, with
+ *   its own reason and retry command for each of the three ways a machine can
+ *   fail to be ready. "sync failed" with no next step is what turns a
+ *   five-second fix into a support thread.
+ * - `buildLocalAmbientEnvelope` — find the work context for this repo, run the
+ *   source collectors, sanitize what came back and assemble the one event
+ *   (`upload-envelope-event.ts`), then parse the envelope against its schema.
+ * - The work-context and provenance helpers (`makeUploadWorkContext`,
+ *   `makeCollectorProvenance`, `safeRepoLabel`) are also called directly by
+ *   `upload-session-reports.ts`, which builds its own provenance without a
+ *   full envelope.
+ */
+import { TelemetryIngestEnvelopeSchema, } from "@bli-cockpit/telemetry-core";
+import path from "node:path";
+import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.js";
+import { runLocalSourceCollectors } from "./adapters/local-sources.js";
+import { defaultCodexSessionDirs, } from "./adapters/codex-attribution.js";
+import { normalizeDashboardUrl } from "./upload-http.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+import { makeSourceScanCompletedEvent, sanitizeRiskFlag, sanitizeSessionReference, sanitizeSourceScanResults, selectedTicketBindingCandidate, } from "./upload-envelope-event.js";
+export class LocalUploadBlockedError extends Error {
+    blocker;
+    retry_hint;
+    constructor(blocker, message, retryHint) {
+        super(message);
+        this.name = "LocalUploadBlockedError";
+        this.blocker = blocker;
+        this.retry_hint = retryHint;
+    }
+}
+/**
+ * Is this machine installed, paired, and holding a session that has not lapsed?
+ */
+async function readPairedCollector(paths) {
+    const config = await readLocalCollectorConfig(paths).catch((error) => {
+        // `not_installed` tells the operator to reinstall the CLI. That is the
+        // wrong instruction for a config that exists and is corrupt, and there was
+        // no way to tell which one this machine hit.
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] collector config present but unreadable, reporting it as not installed", JSON.stringify({
+                reason: "not_installed",
+                ...describeError(error),
+            }));
+        }
+        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit do-everything` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit do-everything");
+    });
+    const sessionFile = await readLocalCollectorSessionFile(paths).catch((error) => {
+        // Same trap on the pairing half: `unpaired` sends the operator to
+        // `cockpit login`, which does not fix an unreadable session file.
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] session file present but unreadable, reporting the machine as unpaired", JSON.stringify({
+                reason: "unpaired",
+                ...describeError(error),
+            }));
+        }
+        throw new LocalUploadBlockedError("unpaired", "No paired collector session found. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
+    });
+    const session = await readLocalSessionReference(paths);
+    if (session.session_state !== "valid") {
+        throw new LocalUploadBlockedError("unpaired", session.session_state === "expired"
+            ? "Collector session expired. Run `cockpit login` or `cockpit pair` again before `cockpit sync`."
+            : "Collector is not paired. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
+    }
+    return { config, sessionFile, session };
+}
+export async function buildLocalAmbientEnvelope(options = {}) {
+    const now = options.now ?? new Date();
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const collector = await readPairedCollector(paths);
+    const { config, sessionFile, session } = collector;
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const activeContext = await readLocalWorkContextForRepo(paths, repoRoot).catch((error) => {
+        // The operator is told "run `cockpit start`", which is right when the file
+        // is simply absent and wrong when it exists and will not parse — the same
+        // advice, forever, on a machine that has already run it (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[upload-envelope] work context present but unreadable, reporting it as missing", JSON.stringify({
+                reason: "missing_context",
+                ...describeError(error),
+            }));
+        }
+        throw new LocalUploadBlockedError("missing_context", "Active work context missing. Run `cockpit start --workspace \"$PWD\"` before `cockpit sync`.", "cockpit start --workspace \"$PWD\"");
+    });
+    const repoLabel = safeRepoLabel(activeContext.repo_label ?? repoRoot);
+    const uploadContext = makeUploadWorkContext({
+        activeContext,
+        session,
+        repoLabel,
+        now,
+    });
+    const sourceCollection = await runLocalSourceCollectors({
+        repoRoot,
+        branch: uploadContext.branch,
+        operatorId: session.operator_id,
+        operatorLabel: session.email ?? session.auth_subject_id,
+        sessionId: session.session_id,
+        workContextId: uploadContext.work_context_id,
+        activeWorkContext: activeContext,
+        rawEvidenceStateDir: paths.state_dir,
+        rawEvidenceSessionsDirs: defaultCodexSessionDirs(paths.home_dir),
+        claudeProjectsDir: path.join(paths.home_dir, ".claude", "projects"),
+        rawEvidenceIncludeCodexJsonl: options.rawEvidenceIncludeCodexJsonl,
+        rawEvidenceIncludeClaudeJsonl: options.rawEvidenceIncludeClaudeJsonl,
+        rawEvidenceCodexSessionFiles: options.codexSessionFiles,
+        rawEvidenceCodexAttributionScan: options.codexAttributionScan,
+        rawEvidenceClaudeSessionFiles: options.claudeSessionFiles,
+        rawEvidenceClaudeAttributionScan: options.claudeAttributionScan,
+        rawEvidenceSkipContentHashes: reusableContentHashes(options, {
+            operatorId: session.operator_id,
+            workContextId: uploadContext.work_context_id,
+        }),
+        rawEvidenceByteBudget: options.rawEvidenceByteBudget,
+        rawEvidenceObjectBudget: options.rawEvidenceObjectBudget,
+        rawEvidenceBudget: options.rawEvidenceBudget,
+        rawEvidenceDeliveryMode: options.evidenceDeliveryMode,
+        now,
+    });
+    const binding = sourceCollection.binding;
+    const ticketBinding = selectedTicketBindingCandidate(binding);
+    const uploadWorkContext = {
+        ...uploadContext,
+        active_ticket_id: binding.selected_ticket_id ?? undefined,
+        ticket_binding_candidates: ticketBinding ? [ticketBinding] : binding.candidates,
+    };
+    const safeRiskFlags = sourceCollection.risk_flags.map((flag) => sanitizeRiskFlag(flag, repoLabel));
+    const events = [
+        makeSourceScanCompletedEvent({
+            context: uploadWorkContext,
+            generatedAt: now.toISOString(),
+            binding,
+            ticketBinding,
+            scans: sourceCollection.scans,
+            gitChangedFileCount: sourceCollection.facts.git?.changed_file_count ?? 0,
+            gitAddedLines: sourceCollection.facts.git?.added_lines ?? 0,
+            gitDeletedLines: sourceCollection.facts.git?.deleted_lines ?? 0,
+            carOpenTicketCount: sourceCollection.facts.car?.open_ticket_count ?? 0,
+            rawEvidenceFacts: sourceCollection.facts.raw_evidence,
+            riskFlags: safeRiskFlags,
+        }),
+    ];
+    const envelope = TelemetryIngestEnvelopeSchema.parse({
+        envelope_version: "telemetry-ingest.v1",
+        generated_at: now.toISOString(),
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        session_reference: sanitizeSessionReference(session),
+        work_context: uploadWorkContext,
+        worktree_inventory: options.worktreeInventory ?? [],
+        source_scan_results: sanitizeSourceScanResults(sourceCollection.scans, repoLabel),
+        events,
+    });
+    return {
+        envelope,
+        dashboard_url: normalizeDashboardUrl(options.dashboardUrl ?? sessionFile.dashboard_url ?? config.dashboard_url),
+        device_token: sessionFile.device_token,
+        ticket_id: binding.selected_ticket_id ?? null,
+        binding,
+        event_count: envelope.events.length,
+        source_scan_count: envelope.source_scan_results.length,
+        risk_flag_count: safeRiskFlags.length,
+        repo_label: repoLabel,
+        head_sha: uploadContext.head_sha ?? null,
+        raw_evidence_upload_files: sourceCollection.facts.raw_evidence?.upload_files ?? [],
+        raw_evidence_facts: sourceCollection.facts.raw_evidence,
+    };
+}
+/**
+ * Content hashes whose bytes are already durable and may be skipped this sync.
+ *
+ * Object keys embed the work context, so a cursor entry only counts as reuse
+ * when it was committed under THIS operator and context. The same bytes under a
+ * different context still need their own pointer and evidence ref.
+ */
+function reusableContentHashes(options, context) {
+    if (options.skipContentHashes)
+        return options.skipContentHashes;
+    return new Set(Object.entries(options.cursorObjects ?? {})
+        .filter(([, entry]) => rawEvidenceObjectKeyBelongsToWorkContext(entry.object_key, context))
+        .map(([hash]) => hash));
+}
+export function makeUploadWorkContext(options) {
+    const provenance = makeCollectorProvenance({
+        context: options.activeContext,
+        session: options.session,
+        repoLabel: options.repoLabel,
+    });
+    return {
+        ...options.activeContext,
+        repo: options.repoLabel,
+        repo_label: options.activeContext.repo_label ?? options.repoLabel,
+        repo_fingerprint: options.activeContext.repo_fingerprint,
+        repo_origin_url: options.activeContext.repo_origin_url,
+        head_sha: options.activeContext.head_sha,
+        worktree_label: options.activeContext.worktree_label,
+        worktree_fingerprint: options.activeContext.worktree_fingerprint,
+        worktree_is_primary: options.activeContext.worktree_is_primary,
+        operator_id: options.session.operator_id,
+        session_id: options.session.session_id,
+        updated_at: options.now.toISOString(),
+        provenance,
+    };
+}
+export function makeCollectorProvenance(options) {
+    return {
+        capture_source: "collector_runtime",
+        capture_adapter_version: LOCAL_COLLECTOR_VERSION,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        repo: options.repoLabel,
+        branch: options.context.branch,
+        repo_label: options.context.repo_label ?? options.repoLabel,
+        repo_fingerprint: options.context.repo_fingerprint,
+        repo_origin_url: options.context.repo_origin_url,
+        worktree_label: options.context.worktree_label,
+        worktree_fingerprint: options.context.worktree_fingerprint,
+        worktree_is_primary: options.context.worktree_is_primary,
+        operator_id: options.session.operator_id,
+        session_id: options.session.session_id,
+        work_context_id: options.context.work_context_id,
+    };
+}
+/** The basename of a repo root, never the path that led to it. */
+export function safeRepoLabel(repoRoot) {
+    const basename = path.basename(repoRoot.replace(/[\\/]+$/, ""));
+    return basename || "repo";
+}
+/**
+ * Does this durable object belong to the operator and work context now syncing?
+ *
+ * Two key shapes are live: the original `<operator>/<context>/...` prefix and
+ * the readable `operators/.../ids/<operator>/<context>/...` layout.
+ */
+function rawEvidenceObjectKeyBelongsToWorkContext(objectKey, context) {
+    const legacyPrefix = `${context.operatorId}/${context.workContextId}/`;
+    const readableIdGuard = `/ids/${context.operatorId}/${context.workContextId}/`;
+    return (objectKey.startsWith(legacyPrefix) ||
+        (objectKey.startsWith("operators/") && objectKey.includes(readableIdGuard)));
+}

package/dist/upload-envelope-event.js

@@ -0,0 +1,198 @@
+/**
+ * The `source_scan_completed` event: the single event every sync sends, and the
+ * sanitizers that keep local paths, long diagnostic strings and nested
+ * duplicate pointers out of the envelope before it leaves the machine.
+ *
+ * `upload-envelope-build.ts` calls `makeSourceScanCompletedEvent` once per
+ * sync and runs every scan result and risk flag through the sanitizers here
+ * before handing the envelope to the schema parser.
+ */
+import { TelemetryIngestEventDtoSchema, } from "@bli-cockpit/telemetry-core";
+/**
+ * The one event every sync sends.
+ *
+ * Its privacy story turns on a single question — did this sync produce raw
+ * evidence objects? If it did, the bytes went to durable storage separately and
+ * this event carries only references to them; if it did not, the event is pure
+ * metadata. Both the classification and the human-readable summary follow from
+ * that, so it is computed once here and threaded through.
+ */
+export function makeSourceScanCompletedEvent(options) {
+    if (!options.context.provenance) {
+        throw new Error("Upload work context is missing provenance.");
+    }
+    const rawEvidencePointers = options.rawEvidenceFacts?.pointers ?? [];
+    const hasRawEvidence = rawEvidencePointers.length > 0;
+    const eventPrivacyClassification = hasRawEvidence
+        ? "redacted_summary"
+        : "metadata";
+    return TelemetryIngestEventDtoSchema.parse({
+        event_id: `ambient-sync:${options.context.work_context_id}:${options.generatedAt}`,
+        event_type: "source_scan_completed",
+        occurred_at: options.generatedAt,
+        provenance: options.context.provenance,
+        privacy_classification: eventPrivacyClassification,
+        redaction: {
+            privacy_classification: eventPrivacyClassification,
+            redaction_status: hasRawEvidence
+                ? "raw_remote_durable"
+                : "metadata_only",
+            redacted_fields: [
+                "prompt_body",
+                "response_body",
+                "diff_body",
+                "transcript_body",
+                "git.changed_paths",
+                "local_file_paths",
+            ],
+            raw_evidence_pointer_ids: rawEvidencePointers.map((pointer) => pointer.raw_evidence_pointer_id),
+            redacted_summary: hasRawEvidence
+                ? "Collector uploaded raw evidence objects separately and sent only references, hashes, source scan, binding, and risk summaries to ingest."
+                : "Collector uploaded metadata-only local work, source scan, binding, and risk summaries.",
+        },
+        redacted_summary: hasRawEvidence
+            ? "Collector uploaded raw evidence objects separately, then sent evidence references and metadata summaries."
+            : "Collector uploaded metadata-only source scan, ticket binding, and risk summaries.",
+        metrics: sourceScanEventMetrics(options),
+        attributes: sourceScanEventAttributes(options, hasRawEvidence),
+        evidence_completeness: options.rawEvidenceFacts?.evidence_completeness,
+        ticket_binding: options.ticketBinding ?? undefined,
+        risk_flags: options.riskFlags,
+        raw_evidence_pointers: rawEvidencePointers,
+    });
+}
+/** Every number this sync counted, all of them safe to publish. */
+function sourceScanEventMetrics(options) {
+    const evidenceCompleteness = options.rawEvidenceFacts?.evidence_completeness;
+    return {
+        git_changed_file_count: options.gitChangedFileCount,
+        git_added_lines: options.gitAddedLines,
+        git_deleted_lines: options.gitDeletedLines,
+        car_open_ticket_count: options.carOpenTicketCount,
+        source_scan_count: options.scans.length,
+        risk_flag_count: options.riskFlags.length,
+        raw_evidence_file_count: options.rawEvidenceFacts?.file_count ?? 0,
+        raw_evidence_byte_size: options.rawEvidenceFacts?.byte_size ?? 0,
+        raw_evidence_skipped_count: options.rawEvidenceFacts?.skipped_count ?? 0,
+        raw_evidence_sanitized_count: options.rawEvidenceFacts?.sanitized_count ?? 0,
+        raw_evidence_reused_count: options.rawEvidenceFacts?.reused_count ?? 0,
+        evidence_scanned_count: evidenceCompleteness?.totals.scanned_count ?? 0,
+        evidence_included_count: evidenceCompleteness?.totals.included_count ?? 0,
+        evidence_skipped_count: evidenceCompleteness?.totals.skipped_count ?? 0,
+        evidence_truncated_count: evidenceCompleteness?.totals.truncated_count ?? 0,
+        evidence_deferred_count: evidenceCompleteness?.totals.deferred_count ?? 0,
+        evidence_reused_count: evidenceCompleteness?.totals.reused_count ?? 0,
+        evidence_failed_count: evidenceCompleteness?.totals.failed_count ?? 0,
+    };
+}
+/**
+ * Where and what this work was, plus the two claims a reader must be able to
+ * check without opening anything: nothing raw is in here, and here is how
+ * complete the evidence behind it actually is. Absent completeness reads as
+ * incomplete on purpose — silence is not a clean bill of health.
+ */
+function sourceScanEventAttributes(options, hasRawEvidence) {
+    const evidenceCompleteness = options.rawEvidenceFacts?.evidence_completeness;
+    return {
+        repo_label: options.context.repo,
+        repo_fingerprint: options.context.repo_fingerprint ?? "unknown",
+        worktree_label: options.context.worktree_label ?? "unknown",
+        worktree_fingerprint: options.context.worktree_fingerprint ?? "unknown",
+        worktree_is_primary: options.context.worktree_is_primary ?? false,
+        branch: options.context.branch,
+        ticket_binding_state: options.binding.state,
+        ticket_binding_source: options.binding.selected_source ?? "none",
+        ticket_id: options.binding.selected_ticket_id ?? "unbound",
+        source_adapters: options.scans.map((scan) => scan.adapter.adapter_name),
+        source_statuses: options.scans.map((scan) => `${scan.adapter.adapter_name}:${scan.status}`),
+        redaction_mode: hasRawEvidence
+            ? "remote_durable_raw_evidence"
+            : "metadata_only",
+        raw_payload_included: false,
+        evidence_completeness_schema_version: evidenceCompleteness?.schema_version ?? "evidence-completeness.v1",
+        evidence_completeness_status: evidenceCompleteness?.status ?? "unknown",
+        evidence_incomplete: evidenceCompleteness
+            ? evidenceCompleteness.status !== "complete"
+            : true,
+        ...(options.context.topic_label
+            ? { topic_label: options.context.topic_label }
+            : {}),
+        ...(options.context.topic_summary_redacted
+            ? { topic_summary_redacted: options.context.topic_summary_redacted }
+            : {}),
+        ...(options.context.work_intent
+            ? { work_intent: options.context.work_intent }
+            : {}),
+        ...(options.context.work_phase
+            ? { work_phase: options.context.work_phase }
+            : {}),
+        ...(options.context.intent_source
+            ? { intent_source: options.context.intent_source }
+            : {}),
+        ...(options.context.intent_confidence !== undefined
+            ? { intent_confidence: options.context.intent_confidence }
+            : {}),
+    };
+}
+export function sanitizeSessionReference(session) {
+    return {
+        ...session,
+        session_file_path: "local-session-file",
+    };
+}
+/**
+ * Scan results carry their own nested events, and those events must not smuggle
+ * evidence pointers into the envelope — the top-level event owns the pointers,
+ * and a duplicate ref here would be counted twice by the ingest receipt.
+ */
+export function sanitizeSourceScanResults(scans, repoLabel) {
+    return scans.map((scan) => ({
+        ...scan,
+        diagnostic_labels: scan.diagnostic_labels.map(sanitizeDiagnosticLabel),
+        events: scan.events.map((event) => ({
+            ...event,
+            raw_evidence_pointers: [],
+            redaction: {
+                ...event.redaction,
+                raw_evidence_pointer_ids: [],
+            },
+        })),
+        risk_flags: scan.risk_flags.map((flag) => sanitizeRiskFlag(flag, repoLabel)),
+    }));
+}
+/**
+ * A diagnostic label that carries a newline or a path separator is a local path
+ * or a stack trace wearing a label's clothes; keep the prefix, drop the rest.
+ */
+function sanitizeDiagnosticLabel(label) {
+    if (label.includes("\n") || label.includes("/") || label.includes("\\")) {
+        const prefix = label.split(":", 1)[0]?.trim();
+        return prefix ? `${prefix}:redacted` : "diagnostic_redacted";
+    }
+    return label.length > 160 ? `${label.slice(0, 157)}...` : label;
+}
+export function sanitizeRiskFlag(flag, repoLabel) {
+    return {
+        ...flag,
+        provenance: {
+            ...flag.provenance,
+            repo: repoLabel,
+        },
+    };
+}
+/**
+ * The candidate the binding actually selected, synthesised when the resolver
+ * chose a ticket that is not in its own candidate list (a `cockpit start`
+ * binding, for instance, which is a decision rather than a guess).
+ */
+export function selectedTicketBindingCandidate(binding) {
+    if (!binding.selected_ticket_id || !binding.selected_source)
+        return null;
+    return (binding.candidates.find((candidate) => candidate.ticket_id === binding.selected_ticket_id &&
+        candidate.binding_source === binding.selected_source) ?? {
+        ticket_id: binding.selected_ticket_id,
+        binding_source: binding.selected_source,
+        confidence: 1,
+        evidence_labels: [`bound_by:${binding.selected_source}`],
+    });
+}