@bli-cockpit/cli 0.2.58 → 0.2.60

package/dist/commands/memory-install-receipt.js

@@ -0,0 +1,222 @@
+/**
+ * THE MEMORY RECEIPT (BLI-3729) — six words this machine can prove.
+ *
+ * `cockpit memory install` already knew, per target, what it had just done.
+ * What nobody could ask was the fleet question: "does Savina's machine have
+ * memory hooks?" This module turns the install's own per-target results into
+ * the small fixed shape that rides the heartbeat
+ * (`@bli-cockpit/telemetry-core`'s `MemoryInstallReceipt`) and that
+ * `lib/ops/fleet-liveness.ts` reads back on the board.
+ *
+ * **It is built from targets that were READ BACK, never from what was sent**
+ * (BLI-2541). Every target it consumes has already re-read and re-parsed the
+ * stored file the way the host will: `installed` means the bytes on disk parse
+ * back to what we wrote, `already` means they already did. This module adds no
+ * new claim; it names the six pieces and carries the reason each one is not
+ * `ok`.
+ *
+ * **One module, on purpose.** BLI-3731 folds this receipt into a one-login
+ * ceremony, so the shape has exactly one producer here and exactly one reader
+ * on the server. Anything that wants to know whether a machine has memory on
+ * calls `buildMemoryInstallReceipt` — it does not re-derive six words from a
+ * target list of its own.
+ *
+ * ## The one word that is not about a file
+ *
+ * `codex.hooks` can be `needs_trust`: installed correctly, and not running,
+ * because Codex requires a person to review and trust a non-managed command
+ * hook before it fires (`/hooks`; see `memory-install-codex-hooks.ts` for the
+ * citation). That state exists in no other piece and is the reason this is six
+ * words rather than a boolean.
+ */
+import { MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
+/**
+ * The one place the six words are decided.
+ *
+ * A target this run never produced (an older CLI, a half-run that threw) is
+ * `unknown`, never `missing`: "we did not look" and "it is not there" are
+ * different facts and the board acts on them differently.
+ */
+export function buildMemoryInstallReceipt(input) {
+    const reasons = {};
+    const piece = (id, key) => {
+        const target = input.targets.find((entry) => entry.target === id);
+        if (!target) {
+            reasons[key] = input.binFound ? "target_not_checked" : "bin_missing";
+            return "unknown";
+        }
+        const word = pieceFor(target.status);
+        if (word !== "ok")
+            reasons[key] = reasonLabel(target.reason);
+        return word;
+    };
+    const codexHooks = judgeCodexHooks(input, reasons);
+    const receipt = {
+        schema_version: MEMORY_INSTALL_RECEIPT_SCHEMA_VERSION,
+        checked_at: (input.now ?? new Date()).toISOString(),
+        claude: {
+            mcp: piece("claude_mcp", "claude.mcp"),
+            hooks: piece("claude_hooks", "claude.hooks"),
+        },
+        codex: {
+            mcp: piece("codex_mcp", "codex.mcp"),
+            skill: piece("codex_skills", "codex.skill"),
+            hooks: codexHooks,
+        },
+        bin_found: input.binFound,
+        ...(Object.keys(reasons).length > 0 ? { reasons } : {}),
+    };
+    return receipt;
+}
+/**
+ * `codex.hooks` is judged in three steps, in this order, and the order is the
+ * point:
+ *
+ *  1. A person who turned hooks OFF is `unsupported`. That is a decision, and
+ *     reporting it as a missing install would put a machine on somebody's
+ *     morning board for doing what its owner asked.
+ *  2. A file target that is not installed loses; there is nothing to trust.
+ *  3. Only then does trust decide, and it can only demote: a correctly written
+ *     hooks file with no trust rows is `needs_trust`, which is INSTALLED and
+ *     NOT RUNNING.
+ */
+function judgeCodexHooks(input, reasons) {
+    const key = "codex.hooks";
+    if (input.codexTrust.feature === "disabled") {
+        reasons[key] = "hooks_disabled_in_config";
+        return "unsupported";
+    }
+    const target = input.targets.find((entry) => entry.target === "codex_hooks");
+    if (!target) {
+        reasons[key] = input.binFound ? "target_not_checked" : "bin_missing";
+        return "unknown";
+    }
+    const word = pieceFor(target.status);
+    if (word !== "ok") {
+        reasons[key] = reasonLabel(target.reason);
+        return word;
+    }
+    if (input.codexTrust.feature === "config_unreadable") {
+        // The hooks are written and correct; whether Codex will run them could not
+        // be read. Say which half is unknown rather than claiming either.
+        reasons[key] = "trust_unreadable";
+        return "unknown";
+    }
+    if (input.codexTrust.trustedRows >= input.expectedTrustRows)
+        return "ok";
+    reasons[key] =
+        input.codexTrust.disabledRows > 0 ? "trust_rows_disabled" : "no_trust_rows";
+    return "needs_trust";
+}
+/**
+ * A target's status collapsed to one of the receipt's words.
+ *
+ * `would_install` (a dry run) is `unknown` on purpose: a dry run proves what
+ * WOULD happen and nothing about what is on disk, and a receipt that treated
+ * it as a reading would let `--dry-run` publish a state nobody wrote.
+ */
+function pieceFor(status) {
+    switch (status) {
+        case "installed":
+        case "already":
+            return "ok";
+        case "mismatch":
+            return "stale";
+        case "missing":
+            return "missing";
+        case "skipped":
+            // Nothing was written, on purpose — today only `bin_missing`. The config
+            // is untouched, so "missing" is the true reading of the file.
+            return "missing";
+        case "would_install":
+        case "failed":
+        default:
+            return "unknown";
+    }
+}
+/** The receipt's reason labels are charset-bounded; a stray reason is clipped. */
+function reasonLabel(reason) {
+    const cleaned = reason.trim().replace(/[^A-Za-z0-9_:.-]/gu, "_");
+    if (cleaned.length === 0)
+        return "unlabelled";
+    return cleaned.slice(0, 60);
+}
+/** `claude ✓ hooks ✓ · codex mcp ✓ skill ✓ hooks needs_trust` — one line. */
+export function memoryReceiptLine(receipt) {
+    const mark = (word) => (word === "ok" ? "✓" : word);
+    return (`claude mcp ${mark(receipt.claude.mcp)} hooks ${mark(receipt.claude.hooks)} · ` +
+        `codex mcp ${mark(receipt.codex.mcp)} skill ${mark(receipt.codex.skill)} ` +
+        `hooks ${mark(receipt.codex.hooks)}`);
+}
+// ---------------------------------------------------------------------------
+// Where the receipt lives between runs
+// ---------------------------------------------------------------------------
+/**
+ * The receipt is CACHED on disk, and the heartbeat reads the cache.
+ *
+ * The alternative — recomputing it inside the heartbeat — costs five file
+ * reads AND a `bli-memory-mcp --print-config` spawn every fifteen minutes on
+ * every machine, to re-prove a state that changes about once a month. The
+ * install and status paths already do that work; this is where they leave the
+ * answer. `checked_at` travels with it, so a stale reading says how stale it
+ * is rather than pretending to be now.
+ *
+ * A cache that cannot be written is logged and dropped: the install still
+ * happened, and a heartbeat with no receipt reads as "not reported", never as
+ * "not installed".
+ */
+export const MEMORY_RECEIPT_FILE = "memory-install-receipt.json";
+/** How old a cached receipt may be before the heartbeat stops sending it. */
+export const MEMORY_RECEIPT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export async function writeMemoryReceiptFile(options) {
+    const file = joinState(options.stateDir, MEMORY_RECEIPT_FILE);
+    try {
+        await options.io.mkdir(options.stateDir);
+        await options.io.writeFile(file, `${JSON.stringify(options.receipt, null, 2)}\n`);
+        return true;
+    }
+    catch (error) {
+        console.error("[memory-install] the memory receipt could not be cached for the heartbeat", JSON.stringify({
+            reason: "receipt_cache_write_failed",
+            error_name: error instanceof Error ? error.name : "unknown",
+        }));
+        return false;
+    }
+}
+/**
+ * The cached receipt, or a named reason there is none. Never throws: a
+ * heartbeat must not fail over a cache file.
+ */
+export async function readMemoryReceiptFile(options) {
+    let raw;
+    try {
+        raw = await options.readText(joinState(options.stateDir, MEMORY_RECEIPT_FILE));
+    }
+    catch {
+        return { receipt: null, reason: "receipt_absent" };
+    }
+    if (raw === null || !raw.trim())
+        return { receipt: null, reason: "receipt_absent" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { receipt: null, reason: "receipt_unparseable" };
+    }
+    const receipt = options.parse(parsed);
+    if (!receipt)
+        return { receipt: null, reason: "receipt_unparseable" };
+    const age = (options.now ?? new Date()).getTime() - Date.parse(receipt.checked_at);
+    // A reading a week old is not a reading. Better to send nothing and let the
+    // board say "not reported" than to publish a claim about a machine that has
+    // not been looked at since.
+    if (Number.isFinite(age) && age > MEMORY_RECEIPT_MAX_AGE_MS) {
+        return { receipt: null, reason: "receipt_expired" };
+    }
+    return { receipt, reason: "receipt_read" };
+}
+function joinState(stateDir, name) {
+    const separator = stateDir.includes("\\") && !stateDir.includes("/") ? "\\" : "/";
+    return stateDir.endsWith(separator) ? `${stateDir}${name}` : `${stateDir}${separator}${name}`;
+}

package/dist/commands/memory-install-report.js

@@ -1,3 +1,10 @@
+/**
+ * The dashboard URL to register against, aggregating per-target results into
+ * one outcome, and rendering that outcome for a log line or a terminal.
+ * Sibling of `memory-install.ts`, named in its header.
+ */
+import { memoryInstallGaps } from "@bli-cockpit/telemetry-core";
+import { memoryReceiptLine } from "./memory-install-receipt.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 export async function resolveDashboardUrl(command, deps) {
     if (command.dashboardUrl)
@@ -60,6 +67,13 @@ export function logMemoryOutcome(outcome, platform) {
         failed: outcome.targets
             .filter((target) => target.status === "failed")
             .map((target) => `${target.target}:${target.reason}`),
+        // BLI-3729: the six words, on the same line. `sync.err.log` is where a
+        // person looks when the board says their machine is missing a piece, and
+        // the log that only named per-target statuses could not answer "is memory
+        // ON here?" without the reader collapsing five rows in their head.
+        memory_on: memoryInstallGaps(outcome.receipt).length === 0,
+        memory_gaps: memoryInstallGaps(outcome.receipt),
+        codex_hooks: outcome.receipt.codex.hooks,
     };
     // stderr on both branches: launchd captures it to sync.err.log, and stdout is
     // reserved for `--json`.
@@ -79,7 +93,17 @@ export function memoryOutcomeLines(outcome) {
                     : outcome.status === "skipped"
                         ? "BLI Memory was not registered and nothing was written: the bli-memory-mcp server is not on this machine yet."
                         : `BLI Memory is not fully registered: ${outcome.reason}.`;
-    const lines = [headline];
+    const lines = [headline, `  ${memoryReceiptLine(outcome.receipt)}`];
+    // The trust step is the one thing a person has to do by hand, so it is said
+    // here in words rather than left as a status word they have to look up.
+    if (outcome.receipt.codex.hooks === "needs_trust") {
+        lines.push("  Codex will NOT run these hooks until you trust them: open Codex in any folder, " +
+            "run /hooks, and trust the three bli-memory entries. One time, per machine.");
+    }
+    if (outcome.receipt.codex.hooks === "unsupported") {
+        lines.push("  Codex hooks are turned off in your ~/.codex/config.toml ([features] hooks = false), " +
+            "so the hooks were written and will not run. That is your setting; nothing here changes it.");
+    }
     for (const target of outcome.targets) {
         const where = target.path ? ` ${target.path}` : "";
         const detail = target.detail ? ` — ${target.detail}` : "";

package/dist/commands/memory-install.js

@@ -40,6 +40,7 @@
  *
  * Every public name is still importable from this file.
  */
+import fs from "node:fs/promises";
 import os from "node:os";
 import { writeLine } from "./cli-io.js";
 import { installTowerIntegration, inspectTowerIntegration } from "./tower-mcp-install.js";
@@ -47,19 +48,42 @@ import { defaultMemoryFileIo, } from "./memory-install-files.js";
 import { installClaudeMemoryIntegration, inspectClaudeMemoryIntegration, } from "./memory-install-claude.js";
 import { installCodexMemoryIntegration, inspectCodexMemoryIntegration, } from "./memory-install-codex.js";
 import { resolveMemoryConfig } from "./memory-install-config.js";
+import { expectedCodexTrustRows, readCodexHookTrustFromDisk, } from "./memory-install-codex-hooks.js";
+import { buildMemoryInstallReceipt, writeMemoryReceiptFile, } from "./memory-install-receipt.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
 import { aggregate, logMemoryOutcome, memoryOutcomeLines, resolveDashboardUrl } from "./memory-install-report.js";
+import { refreshSetupReceipt } from "./setup-receipt.js";
+import { setupReceiptBlock } from "./setup-receipt-lines.js";
 export { resolveMemoryMcpBin } from "./memory-install-config.js";
 export { memoryOutcomeLines, resolveDashboardUrl } from "./memory-install-report.js";
+export { buildMemoryInstallReceipt, memoryReceiptLine, readMemoryReceiptFile, writeMemoryReceiptFile, MEMORY_RECEIPT_FILE, } from "./memory-install-receipt.js";
+export { codexHooksFile, readCodexHookTrust, } from "./memory-install-codex-hooks.js";
 export async function runMemoryInstall(command, io, deps = {}) {
     const outcome = command.action === "status"
         ? await inspectMemoryIntegration(command, io, deps)
         : await installMemoryIntegration(command, io, deps);
+    // BLI-3731. Read the WHOLE machine back after acting on part of it, so the
+    // heartbeat's cache is fresh and a person sees the same seven words here as
+    // on the ops board. A dry run reads nothing and caches nothing: `--dry-run`
+    // says what WOULD happen, which is not a reading of anything.
+    const receipt = command.dryRun
+        ? null
+        : await refreshSetupReceipt(io, {
+            ...(command.homeDir ? { homeDir: command.homeDir } : {}),
+            ...(command.dashboardUrl ? { dashboardUrl: command.dashboardUrl } : {}),
+        });
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify(outcome, null, 2));
+        writeLine(io.stdout, JSON.stringify({ ...outcome, setup_receipt: receipt?.receipt ?? null }, null, 2));
     }
     else {
         for (const line of memoryOutcomeLines(outcome))
             writeLine(io.stdout, line);
+        if (receipt) {
+            writeLine(io.stdout, "Connected:");
+            for (const line of setupReceiptBlock(receipt, { indent: "  " })) {
+                writeLine(io.stdout, line);
+            }
+        }
     }
     return outcome.status === "failed" ? 1 : 0;
 }
@@ -107,10 +131,49 @@ export async function installMemoryIntegration(command, io, deps = {}) {
         bin_found: resolved.config !== null,
         ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
         targets,
+        receipt: buildMemoryInstallReceipt({
+            targets,
+            binFound: resolved.config !== null,
+            codexTrust: await codexTrustFor(homeDir, fileIo),
+            expectedTrustRows: resolved.config ? expectedCodexTrustRows(resolved.config) : 0,
+        }),
     };
     logMemoryOutcome(outcome, platform);
+    // The heartbeat reads the cache, not the machine — see the receipt module's
+    // "Where the receipt lives between runs". A dry run caches nothing: it proves
+    // what WOULD happen and nothing about what is on disk.
+    if (!command.dryRun) {
+        await cacheReceipt(homeDir ?? command.homeDir, outcome.receipt);
+    }
     return outcome;
 }
+/**
+ * Reading the trust state never fails an install. A `config.toml` we cannot
+ * read is `config_unreadable`, which the receipt reports as `unknown` for
+ * `codex.hooks` rather than as an absent installation.
+ */
+async function codexTrustFor(homeDir, io) {
+    return readCodexHookTrustFromDisk({ homeDir, io }).catch(() => ({
+        feature: "config_unreadable",
+        trustedRows: 0,
+        disabledRows: 0,
+    }));
+}
+async function cacheReceipt(homeDir, receipt) {
+    const paths = getCollectorRuntimePaths(homeDir);
+    await writeMemoryReceiptFile({
+        stateDir: paths.state_dir,
+        receipt,
+        io: {
+            mkdir: async (dir) => {
+                await fs.mkdir(dir, { recursive: true });
+            },
+            writeFile: async (file, body) => {
+                await fs.writeFile(file, body, "utf8");
+            },
+        },
+    });
+}
 export async function inspectMemoryIntegration(command, io, deps = {}) {
     const homeDir = deps.homeDir ?? command.homeDir ?? os.homedir();
     const platform = deps.platform ?? process.platform;
@@ -143,12 +206,23 @@ export async function inspectMemoryIntegration(command, io, deps = {}) {
         cliEntryPoint: deps.cliEntryPoint,
         realpath: deps.realpath,
     })));
-    return {
+    const outcome = {
         action: "status",
         ...aggregate(targets),
         config_source: resolved.source,
         bin_found: resolved.config !== null,
         ...(resolved.bin_source ? { bin_source: resolved.bin_source } : {}),
         targets,
+        receipt: buildMemoryInstallReceipt({
+            targets,
+            binFound: resolved.config !== null,
+            codexTrust: await codexTrustFor(homeDir, fileIo),
+            expectedTrustRows: resolved.config ? expectedCodexTrustRows(resolved.config) : 0,
+        }),
     };
+    // `status` is a pure read and its reading is exactly as good as an install's
+    // — both re-parse the stored files — so it refreshes the cache too. A person
+    // who runs `cockpit memory status` has just made the fleet board fresher.
+    await cacheReceipt(homeDir ?? command.homeDir, outcome.receipt);
+    return outcome;
 }

package/dist/commands/msg.js

@@ -1,13 +1,19 @@
 /**
- * `cockpit msg` — channels and messages, typed (BLI-3706).
+ * `cockpit msg` — channels and messages, typed (BLI-3706, BLI-3749).
  *
- * Four verbs over `/api/msg/**` (BLI-3654 Wave 1a), which already accepts the
+ * Six verbs over `/api/msg/**` (BLI-3654 Wave 1a), which already accepts the
  * collector device token through `resolveCaller({ allowDeviceToken: true })`
  * on every route — no server-side door change was needed for this terminal.
  *
  * `<channel>` is a channel id, or its name with or without a leading `#`,
  * resolved locally against `GET /api/msg/channels` — exact match only, never
  * fuzzy, same discipline `docs.ts` uses for a slug.
+ *
+ * `create` and `dm` (BLI-3749) name PEOPLE by email and never by uuid: the
+ * door resolves each address exactly (`lib/msg/people.ts`), so the terminal
+ * carries no directory of its own and a typo is refused by name rather than
+ * silently adding a stranger. `dm` does not have to name the caller — the
+ * door unions them in.
  */
 import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor, } from "./agent-door.js";
 import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
@@ -26,6 +32,10 @@ export async function runMsg(command, io) {
             return sendMessage(command, door);
         case "thread":
             return readThread(command, door);
+        case "create":
+            return createChannel(command, door);
+        case "dm":
+            return openDm(command, door);
     }
 }
 async function fetchChannels(door) {
@@ -185,4 +195,77 @@ async function sendMessage(command, door) {
         return emitAgentDoor(door, { ok: true, message });
     writeLine(door.io.stdout, `Sent to ${ref} (${message?.id ?? "?"}).`);
     return 0;
+}
+async function createChannel(command, door) {
+    const name = command.channelName ?? "";
+    if (name === "")
+        return failAgentDoor(door, TAG, "invalid_body", "msg create needs a channel name.");
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/channels",
+        method: "POST",
+        label: "msg create",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: {
+            name,
+            is_private: command.isPrivate,
+            ...(command.description ? { description: command.description } : {}),
+            ...(command.memberEmails ? { member_emails: command.memberEmails } : {}),
+        },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const body = answer.body;
+    const channel = body.channel ?? null;
+    const membersAdded = body.members_added ?? [];
+    const membersFailed = body.members_failed ?? [];
+    const requestedMembers = command.memberEmails?.length ?? 0;
+    writeLine(door.io.stderr, `${TAG} created ${JSON.stringify({
+        channel_id: channel?.id ?? null,
+        is_private: command.isPrivate,
+        members_requested: requestedMembers,
+        members_added: membersAdded.length,
+        members_failed: membersFailed.length,
+    })}`);
+    if (door.json) {
+        return emitAgentDoor(door, { ok: true, channel, membersAdded, membersFailed });
+    }
+    writeLine(door.io.stdout, `Created #${channel?.name ?? name} (${channel?.id ?? "?"}).`);
+    if (membersAdded.length > 0) {
+        writeLine(door.io.stdout, `${membersAdded.length} member(s) added.`);
+    }
+    // A CLI newer than the deployment is a normal fleet state, and a Tower that
+    // predates BLI-3749 STRIPS `member_emails` rather than refusing it — the
+    // create succeeds and the members quietly never happen. Say so; a silent
+    // success is the failure mode this whole ticket exists to end.
+    if (requestedMembers > 0 && membersAdded.length === 0 && membersFailed.length === 0) {
+        writeLine(door.io.stdout, `Tower reported no members added, though ${requestedMembers} were asked for. It may be older than this CLI — add them from the channel, or retry after the next deploy.`);
+    }
+    // A member the channel could not take is said out loud, not left to a log:
+    // the channel exists, so this is the only place a person would learn it.
+    for (const failure of membersFailed) {
+        writeLine(door.io.stdout, `Not added (${failure.reason}): ${failure.userId}`);
+    }
+    return 0;
+}
+async function openDm(command, door) {
+    const email = command.dmEmail ?? "";
+    if (email === "")
+        return failAgentDoor(door, TAG, "invalid_body", "msg dm needs an email address.");
+    const answer = await askAgentDoor(door, {
+        path: "/api/msg/channels",
+        method: "POST",
+        label: "msg dm",
+        timeoutMs: WRITE_DEADLINE_MS,
+        body: { dm_participant_emails: [email] },
+    });
+    if (!answer.ok)
+        return failAgentDoor(door, TAG, answer.reason, answer.detail);
+    const channel = answer.body.channel ?? null;
+    writeLine(door.io.stderr, `${TAG} dm resolved ${JSON.stringify({ channel_id: channel?.id ?? null })}`);
+    if (door.json)
+        return emitAgentDoor(door, { ok: true, channel });
+    // Idempotent by contract (`get_or_create_dm`), so the wording says what is
+    // true either way rather than claiming a creation that may not have happened.
+    writeLine(door.io.stdout, `Direct message with ${email}: ${channel?.id ?? "?"}`);
+    return 0;
 }

package/dist/commands/onboard-completion.js

@@ -3,6 +3,9 @@ import { agentRuleHostLabel } from "./agent-rules-command.js";
 import { autostartLocationLine } from "./autostart-command.js";
 import { backfillRetryCommand, runBackfill, } from "./backfill.js";
 import { addInstallEvent, reportInstallEventsBestEffort } from "./install-receipts.js";
+import { installMemoryIntegration } from "./memory-install.js";
+import { refreshSetupReceipt } from "./setup-receipt.js";
+import { setupReceiptBlock } from "./setup-receipt-lines.js";
 import { addAutostartInstallEvent, addOnboardFailureEvent, classifyOnboardBlocker, onboardAutostartFailed, } from "./onboard-receipts.js";
 import { nextStepForOnboardBlocker, onboardAgentRulesInstallLine, onboardJsonPayload, writeOnboardJson, } from "./onboard-report.js";
 import { installAgentRules } from "../agent-rules.js";
@@ -91,7 +94,51 @@ async function refreshOnboardAutostart(command, roots, io) {
  * report always fires, pass or blocked — replaces a `finish` closure that used
  * to live inside `runOnboard` so the flow functions below can call it too.
  */
+/**
+ * BLI-3731. The last thing onboarding does: install the agent integrations
+ * unasked, read the whole machine back, and print ONE block saying what is
+ * connected and what is not. It runs on every exit path, success or blocked,
+ * because "what did I actually end up with?" is the question a person has
+ * either way — and a failure that also prints the receipt is a failure
+ * somebody can act on.
+ *
+ * Never throws and never changes the exit code: this is a report.
+ */
+async function reportOnboardSetupReceipt(command, io) {
+    try {
+        await installMemoryIntegration({
+            kind: "memory",
+            action: "install",
+            ...(command.homeDir ? { homeDir: command.homeDir } : {}),
+            ...(command.dashboardUrl ? { dashboardUrl: command.dashboardUrl } : {}),
+            dryRun: false,
+            json: true,
+        }, io, { ...(command.homeDir ? { homeDir: command.homeDir } : {}) });
+    }
+    catch (error) {
+        // The receipt below will read whatever is actually there, so a failed
+        // install is reported by the words rather than by stopping onboarding.
+        console.error("[onboard] agent integrations could not be installed", JSON.stringify({
+            reason: "memory_install_threw",
+            error_name: error instanceof Error ? error.name : typeof error,
+        }));
+    }
+    const receipt = await refreshSetupReceipt(io, {
+        ...(command.homeDir ? { homeDir: command.homeDir } : {}),
+        ...(command.dashboardUrl ? { dashboardUrl: command.dashboardUrl } : {}),
+    });
+    if (command.json)
+        return;
+    writeLine(io.stdout, "");
+    writeLine(io.stdout, "Connected:");
+    for (const line of receipt
+        ? setupReceiptBlock(receipt, { indent: "  " })
+        : ["  unknown — run `cockpit doctor` to read this machine."]) {
+        writeLine(io.stdout, line);
+    }
+}
 export async function finishOnboardRun(command, installEvents, io, code) {
+    await reportOnboardSetupReceipt(command, io);
     await reportInstallEventsBestEffort({
         homeDir: command.homeDir,
         dashboardUrl: command.dashboardUrl,

package/dist/commands/onboard-setup.js

@@ -1,9 +1,10 @@
-import { writeLine } from "./cli-io.js";
+import { openInBrowser } from "./browser-open.js";
+import { errorMessage, writeLine } from "./cli-io.js";
 import { collectionRootConsentAliases, persistOnboardingRootConfig, resolveOnboardingRootsForCommand, } from "./collection-roots.js";
 import { addInstallEvent } from "./install-receipts.js";
 import { canReuseOnboardSession, pairLocalCollectorWithAuthFallback, readOnboardSessionReuseCandidate, requestPairingAccessTokenDetailed, } from "./local-auth.js";
 import { writePairingInstructions } from "./onboard-report.js";
-import { inspectLocalCollectorStatus, logoutLocalCollector, } from "../local-state.js";
+import { inspectLocalCollectorStatus, logoutLocalCollector, pairLocalCollectorViaLink, } from "../local-state.js";
 /** Step 0: which folders are approved, and who claims to own this machine's uploads. */
 export async function prepareOnboardRoots(command, installEvents, io) {
     const resolvedRoots = await resolveOnboardingRootsForCommand(command, io);
@@ -72,6 +73,22 @@ export async function pairForOnboarding(command, input, installEvents, io) {
             writeLine(io.stdout, "2/5 Existing valid device session does not match requested owner or dashboard; pairing again.");
         }
     }
+    // BLI-3731: one sign-in first. The link both signs the browser in and
+    // finishes the pairing, so nobody reads a second email. Every other arm
+    // below is the fallback, and it runs unchanged when this one cannot finish.
+    if (!command.legacyPair) {
+        const linked = await tryOneLinkOnboardPairing(command, input, io);
+        if (linked) {
+            addInstallEvent(installEvents, "auth", "skipped", "one_link_pairing");
+            addInstallEvent(installEvents, "pair", "ok");
+            if (!command.json) {
+                writeLine(io.stdout, "2/5 Device paired from one sign-in.");
+                writeLine(io.stdout, `User: ${linked.session.email ?? linked.session.auth_subject_id}`);
+                writeLine(io.stdout, `Device: ${linked.session.device_name ?? linked.session.device_id ?? "unknown"}`);
+            }
+            return linked;
+        }
+    }
     const authResult = await requestPairingAccessTokenDetailed({
         dashboardUrl: command.dashboardUrl,
         email: input.claimedOwnerEmail,
@@ -99,4 +116,67 @@ export async function pairForOnboarding(command, input, installEvents, io) {
         writeLine(io.stdout, `Device: ${pair.session.device_name ?? pair.session.device_id ?? "unknown"}`);
     }
     return pair;
+}
+/**
+ * The one-sign-in ceremony, inside onboarding (BLI-3731).
+ *
+ * Returns null when it could not finish, having already said why — onboarding
+ * then runs the older email-code arm rather than stopping. A regression in the
+ * new door must never leave a machine unable to onboard at all.
+ *
+ * `PairViaLinkResult` is mapped onto `PairLocalCollectorResult` here because
+ * the session underneath is the same one: the server issues it from the same
+ * `pollDevicePairRequest` whichever ceremony asked. `approve_url` carries the
+ * connect link so the onboarding receipt still names the address a person
+ * opened.
+ */
+async function tryOneLinkOnboardPairing(command, input, io) {
+    try {
+        const linked = await pairLocalCollectorViaLink({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            deviceName: command.deviceName,
+            claimedOwnerEmail: input.claimedOwnerEmail,
+            pairCode: command.pairCode,
+            pollIntervalMs: command.pollIntervalMs,
+            timeoutMs: command.timeoutMs,
+            fetch: io.fetch,
+            onLinkReady: command.json
+                ? undefined
+                : (link) => announceOnboardLink(command, io, link),
+        });
+        return {
+            status: "paired",
+            session: linked.session,
+            session_file: linked.session_file,
+            dashboard_url: linked.dashboard_url,
+            approve_url: linked.connect_url ?? linked.dashboard_url,
+        };
+    }
+    catch (error) {
+        const reason = error && typeof error === "object" && "reason" in error
+            ? String(error.reason)
+            : "pair_link_failed";
+        console.error("[onboard] one-link pairing did not finish", JSON.stringify({ reason, falling_back: true }));
+        if (!command.json) {
+            writeLine(io.stderr, `Sign-in link did not finish: ${errorMessage(error)}`);
+            writeLine(io.stderr, "Falling back to the email-code sign-in.");
+        }
+        return null;
+    }
+}
+/** Print the link, then try to open it. Printing first is what makes the open optional. */
+function announceOnboardLink(command, io, link) {
+    writeLine(io.stdout, "2/5 Sign in to Tower once, and this machine is connected.");
+    writeLine(io.stdout, `Open: ${link.connect_url}`);
+    writeLine(io.stdout, "Waiting for that sign-in...");
+    if (command.noBrowser) {
+        console.error("[onboard] browser not opened", JSON.stringify({ reason: "no_browser_flag" }));
+        return;
+    }
+    const opened = openInBrowser(link.connect_url);
+    console.error("[onboard] browser open attempted", JSON.stringify(opened.ok ? { reason: opened.reason, program: opened.program } : { reason: opened.reason }));
+    if (!opened.ok) {
+        writeLine(io.stdout, `(${opened.detail} The link above still works.)`);
+    }
 }