@bli-cockpit/cli 0.2.57 → 0.2.59

package/dist/commands/memory-install.js

@@ -13,47 +13,77 @@
  *   memory-install-claude.ts   ~/.claude.json (user-scope MCP) + ~/.claude/settings.json (hooks, allow-list)
  *   memory-install-codex.ts    ~/.codex/config.toml (one table) + ~/.codex/skills/bli-memory/
  *
- * What this module owns is the decisions around them:
+ * What this module owns is the top-level decision sequence
+ * (BLI-3717 readability pass, 629 lines to a table of contents). Every other
+ * responsibility lives in a `memory-install-*.ts` sibling:
+ *
+ *  - `memory-install-config.ts` — finding `bli-memory-mcp` on this machine
+ *    (`resolveMemoryMcpBin`, over the shared `mcp-bin-resolve.ts` walk) and
+ *    deciding which config shape to write (`resolveMemoryConfig`). **No
+ *    server, no write.** If the bin does not resolve, not one file is opened
+ *    and the outcome is `skipped bin_missing` — see `no_bin_no_write` there
+ *    for why a written-but-inert registration is the worse option.
+ *    `--print-config --claude` wins when the bin answers it; the built-in
+ *    template of the same shape is the fallback for an older server, and it
+ *    is only ever used with a bin that actually resolved.
+ *  - `memory-install-report.ts` — the dashboard URL, aggregating per-target
+ *    results into one outcome, and rendering it for a log line or a
+ *    terminal.
+ *
+ * Two rules bind the whole sequence:
  *
- * - **Where the server is.** `bli-memory-mcp` ships as a DEPENDENCY of
- *   `@bli-cockpit/cli`, so the canonical lookup is the `node_modules/.bin` on
- *   the way up from THIS MODULE's own file — realpath-ed first, because a
- *   global `cockpit` is a symlink and walking up from the symlink finds
- *   nothing; PATH is the fallback. Nobody ever installs a second global
- *   package. See `resolveMemoryMcpBin`, which carries the receipt.
- * - **No server, no write.** If the bin does not resolve, not one file is
- *   opened and the outcome is `skipped bin_missing` — see `no_bin_no_write`
- *   below for why a written-but-inert registration is the worse option.
- * - **Which config shape.** `bli-memory-mcp --print-config --claude` wins when
- *   the bin answers it; the built-in template of the same shape is the
- *   fallback for an older server, and it is only ever used with a bin that
- *   actually resolved.
  * - **Never throw at the caller.** The sync tick calls this. A failure is a
  *   named receipt, never an exception that could cost a machine its
  *   collection tick.
  * - **Never claim an install it did not read back** (BLI-2541). Both halves
  *   re-read and re-parse; this module only aggregates what they proved.
+ *
+ * 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 { resolveMcpBin } from "./mcp-bin-resolve.js";
 import { installTowerIntegration, inspectTowerIntegration } from "./tower-mcp-install.js";
-import { builtinMemoryInstallConfig, isUnsafeBinPath, MEMORY_MCP_BIN, parsePrintedMemoryInstallConfig, withResolvedBinPath, } from "./memory-install-contract.js";
 import { defaultMemoryFileIo, } from "./memory-install-files.js";
 import { installClaudeMemoryIntegration, inspectClaudeMemoryIntegration, } from "./memory-install-claude.js";
 import { installCodexMemoryIntegration, inspectCodexMemoryIntegration, } from "./memory-install-codex.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
-import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.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;
 }
@@ -101,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;
@@ -137,269 +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,
-    };
-}
-/**
- * **`no_bin_no_write`.** When `bli-memory-mcp` cannot be resolved, this command
- * writes NOTHING — not the MCP entry, not the hooks, not the Codex table, not
- * the skills.
- *
- * An earlier revision wrote the registration anyway, on the reasoning that a
- * correct shape waiting for the package is better than nothing. It is not:
- * Claude Code RUNS a registered hook. Three hooks pointing at a binary that
- * does not exist would print a hook failure on every SessionStart, every
- * prompt and every Stop, on every intern machine, until the package shipped —
- * a self-inflicted outage in the one surface people look at all day.
- *
- * So an absent bin is `skipped bin_missing`: a receipt, not a write. The daily
- * self-heal retries tomorrow, and the first tick after the package lands does
- * the whole registration at once.
- */
-async function resolveMemoryConfig(command, io, platform, deps) {
-    const dashboardUrl = await resolveDashboardUrl(command, deps);
-    const found = await resolveMemoryMcpBin({
-        env: envWithNodeRuntimeOnPath(io.env ?? process.env),
-        platform,
-        fileExists: deps.fileExists,
-        cliEntryPoint: deps.cliEntryPoint,
-        realpath: deps.realpath,
-    });
-    if (!found) {
-        return {
-            config: null,
-            source: "none",
-            binTarget: {
-                target: "bin",
-                status: "skipped",
-                reason: "bin_missing",
-                detail: `${MEMORY_MCP_BIN} is not installed beside this CLI or on PATH; nothing was written, and the next daily run will try again`,
-            },
-        };
-    }
-    if (isUnsafeBinPath(found.path)) {
-        // A hook command is a shell string by the platform's design. A path that
-        // cannot be quoted safely is not escaped cleverly, and it is not swapped
-        // for a bare name that may resolve to something else either — the install
-        // refuses and says why.
-        return {
-            config: null,
-            source: "none",
-            binTarget: {
-                target: "bin",
-                status: "failed",
-                reason: "bin_path_unsafe",
-                detail: "the resolved bin path contains characters that cannot appear in a hook command; nothing was written",
-            },
-            bin_source: found.source,
-        };
-    }
-    const printed = await printedMemoryConfig(io, found.path);
-    if (printed) {
-        // The bin prints a BARE command name — it cannot know where it was
-        // installed, and it is nested inside the CLI's node_modules rather than on
-        // PATH. Path-qualifying it here is what makes the registration runnable at
-        // all; see `withResolvedBinPath`.
-        const qualified = withResolvedBinPath(printed, {
-            binPath: found.path,
-            platform,
-            dashboardUrl,
-        });
-        if (qualified) {
-            return {
-                config: qualified,
-                source: "bin",
-                binTarget: { target: "bin", status: "already", reason: "bin_printed_config" },
-                bin_source: found.source,
-            };
-        }
-        // A printed hook command this installer cannot re-point. The template is
-        // always path-qualified, so it is the safe answer — and the reason says
-        // which of the two fallbacks happened.
-        return {
-            config: builtinMemoryInstallConfig({ binPath: found.path, platform, dashboardUrl }),
-            source: "template",
-            binTarget: {
-                target: "bin",
-                status: "already",
-                reason: "bin_printed_config_unqualifiable",
-                detail: "the bin printed a hook command this installer could not re-point at the resolved path; the built-in shape was used",
-            },
-            bin_source: found.source,
-        };
-    }
-    return {
-        config: builtinMemoryInstallConfig({
-            binPath: found.path,
-            platform,
-            dashboardUrl,
+        receipt: buildMemoryInstallReceipt({
+            targets,
+            binFound: resolved.config !== null,
+            codexTrust: await codexTrustFor(homeDir, fileIo),
+            expectedTrustRows: resolved.config ? expectedCodexTrustRows(resolved.config) : 0,
         }),
-        source: "template",
-        binTarget: {
-            target: "bin",
-            status: "already",
-            reason: "bin_present_template_used",
-            detail: "the bin did not print a usable --print-config; the built-in shape was used",
-        },
-        bin_source: found.source,
-    };
-}
-/**
- * Asks the server for its own shape. Arguments go as an ARRAY — nothing is
- * interpolated into a command line — and on Windows the captured runner routes
- * a `.cmd` shim through ComSpec with its own escaping (process-runner.ts).
- */
-async function printedMemoryConfig(io, binPath) {
-    const exec = io.exec;
-    if (!exec)
-        return null;
-    try {
-        const result = await exec(binPath, ["--print-config", "--claude"]);
-        if (result.code !== 0)
-            return null;
-        return parsePrintedMemoryInstallConfig(result.stdout);
-    }
-    catch {
-        // Deliberately silent here: the caller reports
-        // `bin_present_template_used`, which is the same information with a name
-        // on it, and this path is reached on every machine that has an older bin.
-        return null;
-    }
-}
-/**
- * Two steps, in this order, and the first is the canonical one.
- *
- * **1. Beside the CLI that is running.** `bli-memory-mcp` ships as a DEPENDENCY
- * of `@bli-cockpit/cli`, so installing the CLI installs the server, and npm
- * links its bin into a `node_modules/.bin` on the path from this package up to
- * the install root — `…/@bli-cockpit/cli/node_modules/.bin` when it is nested,
- * `…/lib/node_modules/.bin` when npm hoists it. It is the ONLY lookup that
- * cannot find somebody else's `bli-memory-mcp`. Nobody ever runs `npm i -g` for
- * a second package.
- *
- * **2. PATH, as a fallback**, for a linked checkout or a hand-installed server.
- * Done in this process rather than through `which`/`where`: it spawns nothing,
- * behaves the same on both host families, and is testable without a fixture
- * binary. The npm global bin sits beside the running node binary in the
- * standard layouts, which is why the caller passes a PATH that already includes
- * it (`envWithNodeRuntimeOnPath`) — the launchd tick's PATH is otherwise
- * `/usr/bin:/bin:/usr/sbin:/sbin` and would find nothing.
- *
- * **What step 1 got wrong on the first real machine** (BLI-3580, CLI 0.2.50):
- * it walked up from `process.argv[1]`, resolved with `path.resolve` and no
- * symlink following. For a global install `argv[1]` is the SHIM — on Edward's
- * Mac `/opt/homebrew/bin/cockpit`, a symlink into
- * `/opt/homebrew/lib/node_modules/@bli-cockpit/cli/dist/cli.js`. The walk
- * therefore started in `/opt/homebrew/bin`, went up through `/opt` to `/`, and
- * never came within reach of the nested `.bin` that was sitting right there.
- * Every machine reported `skipped bin_missing` with the server installed.
- *
- * Two changes, both in `besideAnchors` / `resolveBesideCli`:
- *
- *  - The anchor is **this module's own file** first (`import.meta.url`), which
- *    is inside the installed package by construction and is never a shim. The
- *    entry point (injected, or `argv[1]`) stays as a second anchor for a build
- *    layout where this module has been bundled somewhere else.
- *  - Every anchor is **realpath-ed** before the walk, so a symlinked entry
- *    lands in the real tree. A path that will not resolve is used as given —
- *    the same bounded silence `container-tag.ts` uses, because a path that
- *    cannot be realpath-ed still identifies a directory well enough to look in.
- */
-export async function resolveMemoryMcpBin(options) {
-    return resolveMcpBin({ ...options, binName: MEMORY_MCP_BIN });
-}
-/** Exported for `tower-mcp-install.ts` (BLI-3706): the two registrations share this machine's one dashboard URL. */
-export async function resolveDashboardUrl(command, deps) {
-    if (command.dashboardUrl)
-        return command.dashboardUrl;
-    const paths = getCollectorRuntimePaths(deps.homeDir ?? command.homeDir);
-    const config = await readLocalCollectorConfig(paths).catch(() => null);
-    return config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
-}
-function aggregate(targets) {
-    const failed = targets.filter((target) => target.status === "failed");
-    if (failed.length > 0) {
-        return {
-            status: "failed",
-            // The first named reason, not a count: an operator needs the reason, and
-            // the per-target list beside it carries the rest.
-            reason: failed[0]?.reason ?? "unknown_failure",
-        };
-    }
-    if (targets.some((target) => target.status === "would_install")) {
-        return { status: "would_install", reason: "dry_run" };
-    }
-    if (targets.some((target) => target.status === "installed")) {
-        return { status: "installed", reason: "wrote_entry" };
-    }
-    if (targets.some((target) => target.status === "mismatch" || target.status === "missing")) {
-        return { status: "missing", reason: "entry_absent" };
-    }
-    // BLI-3706: checked BEFORE `skipped`, not after. `bli-tower` registering
-    // beside `bli-memory` on this same command means a machine can be fully
-    // "already" registered for one server while the other's bin is not here
-    // yet — that machine's OWN state must not read as "skipped" (nothing is
-    // happening) when something plainly already is. `skipped` only wins the
-    // whole outcome when NOTHING on this machine has ever reached "already"
-    // either — the original one-server case (a fresh machine, bin missing,
-    // nothing written at all) still returns "skipped" via the fallback below.
-    if (targets.some((target) => target.status === "already")) {
-        return { status: "already", reason: "already_current" };
-    }
-    const skipped = targets.find((target) => target.status === "skipped");
-    if (skipped) {
-        // Not a failure and not a success: nothing was written, on purpose, and
-        // the next daily run will try again. `bin_missing` is the only one today.
-        return { status: "skipped", reason: skipped.reason };
-    }
-    return { status: "already", reason: "already_current" };
-}
-/**
- * Both branches log, and neither carries a path — a home directory names a
- * person, and this line ends up in `sync.err.log` on every machine.
- */
-function logMemoryOutcome(outcome, platform) {
-    const fields = {
-        status: outcome.status,
-        reason: outcome.reason,
-        config_source: outcome.config_source,
-        bin_found: outcome.bin_found,
-        platform,
-        installed_count: outcome.targets.filter((target) => target.status === "installed").length,
-        already_count: outcome.targets.filter((target) => target.status === "already").length,
-        failed: outcome.targets
-            .filter((target) => target.status === "failed")
-            .map((target) => `${target.target}:${target.reason}`),
     };
-    // stderr on both branches: launchd captures it to sync.err.log, and stdout is
-    // reserved for `--json`.
-    console.error(outcome.status === "failed"
-        ? "[memory-install] BLI Memory is not fully registered on this machine"
-        : "[memory-install] BLI Memory registration converged", JSON.stringify(fields));
-}
-export function memoryOutcomeLines(outcome) {
-    const headline = outcome.status === "installed"
-        ? "BLI Memory registered on this machine."
-        : outcome.status === "already"
-            ? "BLI Memory is already registered on this machine."
-            : outcome.status === "would_install"
-                ? "BLI Memory would be registered (dry run; nothing was written)."
-                : outcome.status === "missing"
-                    ? "BLI Memory is not registered on this machine."
-                    : 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];
-    for (const target of outcome.targets) {
-        const where = target.path ? ` ${target.path}` : "";
-        const detail = target.detail ? ` — ${target.detail}` : "";
-        lines.push(`  ${target.target}: ${target.status} (${target.reason})${where}${detail}`);
-    }
-    return lines;
+    // `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/notes-door.js

@@ -0,0 +1,120 @@
+/**
+ * `cockpit notes` plumbing: one HTTP request through the paired session, and
+ * the shared answer/refusal shapes `notes-reads.ts` and `notes-writes.ts`
+ * both render. Sibling of `notes.ts`, named in its header.
+ */
+import { writeLine } from "./cli-io.js";
+import { towerFailureDetail, towerRequest } from "../tower-client.js";
+import { readResponseJson } from "../upload-http.js";
+export const TAG = "[notes cli]";
+/** Every read in this surface shares one timeout; every write earns its own
+ * (a paste or an upload can run far longer). */
+export const READ_DEADLINE_MS = 60_000;
+/**
+ * One request, and a refusal that keeps the ROUTE'S own words.
+ *
+ * `towerJsonRequest` maps a non-2xx through `responseErrorMessage`, which looks
+ * for `message` or `error` — the shape the ingest routes answer with. Every
+ * notes door answers in the browser's shape instead (`headline` plus `lines`,
+ * with a `reason` label beside them), because the same body is what the page
+ * renders. Reading it here rather than widening `responseErrorMessage` keeps one
+ * meaning per field: the sentence is written where the outcome is known, and the
+ * terminal relays it rather than inventing a second wording for the same thing.
+ */
+export async function ask(door, options) {
+    const result = await towerRequest({
+        dashboardUrl: door.dashboardUrl,
+        path: options.path,
+        deviceToken: door.deviceToken,
+        fetch: door.io.fetch,
+        method: options.method,
+        label: options.label,
+        timeoutMs: options.timeoutMs,
+        ...(options.body === undefined ? {} : { body: options.body }),
+        log: (line) => writeLine(door.io.stderr, line),
+    });
+    if (!result.ok) {
+        const failure = result;
+        return {
+            ok: false,
+            reason: failure.reason,
+            detail: towerFailureDetail(failure.reason, failure.detail),
+        };
+    }
+    const body = await readResponseJson(result.response);
+    if (!result.response.ok) {
+        const status = result.response.status;
+        return {
+            ok: false,
+            reason: refusalReason(body) ?? `http_${status}`,
+            detail: refusalSentence(body) ?? `Tower answered ${status} and said nothing about why.`,
+        };
+    }
+    return { ok: true, body };
+}
+function refusalReason(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    for (const key of ["reason", "error", "code"]) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return null;
+}
+function refusalSentence(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const headline = typeof record["headline"] === "string" ? record["headline"] : null;
+    const message = typeof record["message"] === "string" ? record["message"] : null;
+    const lines = Array.isArray(record["lines"])
+        ? record["lines"].filter((line) => typeof line === "string")
+        : [];
+    const said = [headline ?? message, ...lines].filter(Boolean);
+    return said.length > 0 ? said.join(" ") : null;
+}
+/** One machine-readable object on stdout, and nothing else on it. */
+export function emit(door, body, exitCode = 0) {
+    writeLine(door.io.stdout, JSON.stringify(body));
+    return exitCode;
+}
+export function fail(door, reason, detail) {
+    writeLine(door.io.stderr, `${TAG} refused ${JSON.stringify({ reason })}`);
+    if (door.json) {
+        writeLine(door.io.stdout, JSON.stringify({ ok: false, error: reason, detail }));
+    }
+    else {
+        writeLine(door.io.stderr, detail);
+    }
+    return 1;
+}
+/**
+ * The route's own words for what happened. Never rephrased here — the sentences
+ * are written where the outcome is known, and a second wording in the terminal
+ * would be a second thing to keep in step.
+ */
+export function sayUpload(door, body) {
+    writeLine(door.io.stdout, body.headline ?? "Tower answered without a sentence.");
+    for (const line of body.lines ?? [])
+        writeLine(door.io.stdout, line);
+    if (body.noteId)
+        writeLine(door.io.stdout, `Note id: ${body.noteId}`);
+}
+/**
+ * Says out loud when an answer is narrower than the one a browser would give.
+ *
+ * A degraded read is still a real answer and is never withheld — but a person
+ * who cannot see their own unshared note has to be told that is why, not left
+ * to conclude it was never stored.
+ */
+export function sayScope(door, body) {
+    if (!body.degradedBecause)
+        return;
+    writeLine(door.io.stderr, `${TAG} narrowed ${JSON.stringify({ scope: body.scope ?? null, reason: body.degradedBecause })}`);
+    writeLine(door.io.stderr, body.degradedNote ?? "This answer is narrower than the browser's.");
+}
+export function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}