balladeer 1.0.0 → 1.0.1

package/dist/desktop-config.js

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { entryRepositoryId, isOurEntry, writeJsonAtomically, } from "./mcp-config.js";
+import { checkoutEntryPath } from "./release.js";
+import { configHome } from "./store.js";
+import { DEFAULT_CONTROL_PLANE } from "./wire.js";
+/** The file the Claude desktop app reads its stdio servers out of, on every platform that has one. */
+export const DESKTOP_CONFIG_FILE = "claude_desktop_config.json";
+export function desktopConfigLocation(environment = process.env, platform = process.platform) {
+    const override = environment.BALLADEER_CLAUDE_DESKTOP_CONFIG?.trim();
+    if (override !== undefined && override.length > 0) {
+        // An override that is not absolute would be resolved against whatever
+        // directory this command happens to have been started in, which is never
+        // the directory the person meant.
+        return isAbsolute(override)
+            ? { kind: "path", path: override, directory: parentOf(override) }
+            : {
+                kind: "unsupported",
+                platform,
+                reason: `BALLADEER_CLAUDE_DESKTOP_CONFIG is set to ${override}, which is not an absolute path, so I did not guess what it meant.`,
+            };
+    }
+    const home = homeOf(environment);
+    if (platform === "darwin") {
+        if (home === undefined)
+            return noHome(platform);
+        const directory = join(home, "Library", "Application Support", "Claude");
+        return { kind: "path", path: join(directory, DESKTOP_CONFIG_FILE), directory };
+    }
+    if (platform === "win32") {
+        const appData = environment.APPDATA?.trim();
+        const roaming = appData !== undefined && appData.length > 0
+            ? appData
+            : home === undefined
+                ? undefined
+                : join(home, "AppData", "Roaming");
+        if (roaming === undefined)
+            return noHome(platform);
+        const directory = join(roaming, "Claude");
+        return { kind: "path", path: join(directory, DESKTOP_CONFIG_FILE), directory };
+    }
+    return {
+        kind: "unsupported",
+        platform,
+        reason: `Claude desktop is published for macOS and Windows, and this machine reports ${platform}, so there is no ${DESKTOP_CONFIG_FILE} here to write. If you run an unofficial build, set BALLADEER_CLAUDE_DESKTOP_CONFIG to the absolute path of its ${DESKTOP_CONFIG_FILE} and run this again.`,
+    };
+}
+/**
+ * The home directory this environment names, and never the one the operating
+ * system would name instead.
+ *
+ * Asking the OS whose home this is would be a second source, and it answers for
+ * the account the process runs under rather than for the environment it was
+ * handed. A command given a bounded environment on purpose, which is what the
+ * tests hand it and what a service account hands it, would reach past that
+ * environment and write into a real person's chat client. So an environment that
+ * names no home is an answer: this run cannot tell where Claude desktop's
+ * configuration is, and it says so rather than guessing.
+ */
+function homeOf(environment) {
+    for (const value of [environment.HOME, environment.USERPROFILE]) {
+        const trimmed = value?.trim();
+        if (trimmed !== undefined && trimmed.length > 0)
+            return trimmed;
+    }
+    return undefined;
+}
+function noHome(platform) {
+    return {
+        kind: "unsupported",
+        platform,
+        reason: `This process was given no HOME, so I could not tell where Claude desktop keeps ${DESKTOP_CONFIG_FILE} and did not guess. Set BALLADEER_CLAUDE_DESKTOP_CONFIG to its absolute path, or run this from a shell that sets HOME.`,
+    };
+}
+function parentOf(path) {
+    const at = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+    return at <= 0 ? path : path.slice(0, at);
+}
+/**
+ * One key per repository, named after the repository.
+ *
+ * The desktop app has no notion of a project: every server in that file is
+ * loaded into every chat. A person who plans work in two repositories therefore
+ * has two of our servers running at once, and the only thing that tells them
+ * apart in the app's own connector list is the key. `balladeer-owner-name` is
+ * that name. A directory whose GitHub origin this command could not read has no
+ * name to use, so the key falls back to the repository's own id, which is unique
+ * by construction and still tells two entries apart.
+ */
+export function desktopServerKey(repositoryName, repositoryId) {
+    const cleaned = repositoryName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const usable = cleaned.length > 0 && cleaned !== "unknown-unknown" ? cleaned : repositoryId.toLowerCase();
+    return `balladeer-${usable}`.slice(0, 100).replace(/-+$/, "");
+}
+/**
+ * The entry the desktop app can actually start, which is not the one a coding
+ * agent gets.
+ *
+ * Claude desktop launches a stdio server from the application rather than from a
+ * login shell, with a minimal PATH carrying none of the places a developer's
+ * node lives: nvm, volta, asdf, Homebrew, fnm. So `node` and `npx` both resolve
+ * to nothing there, and what a person gets instead of a server is a line in a
+ * log file nobody opens. This names the interpreter running setup by its
+ * absolute path and this command's own entry point by its absolute path, so the
+ * entry needs no PATH at all.
+ *
+ * The environment is written for the same reason. The forwarder reads the bearer
+ * out of this machine's credential store, and where that store is depends on a
+ * variable the desktop app never inherits, so the resolved directory goes into
+ * the entry rather than being left to a shell that is not there. It is a path
+ * and never a secret: the credential itself stays in the store, mode 600.
+ */
+export function desktopStdioEntry(repositoryId, environment = process.env, controlPlane, nodePath = process.execPath, entryPath = checkoutEntryPath()) {
+    const env = { BALLADEER_CONFIG_HOME: configHome(environment) };
+    // Only when it is not the default. A deployment nobody named is the one the
+    // forwarder already reaches on its own, and writing it down would pin an
+    // address that a later release moves.
+    if (controlPlane !== undefined && controlPlane !== DEFAULT_CONTROL_PLANE) {
+        env.BALLADEER_CONTROL_PLANE = controlPlane;
+    }
+    return { command: nodePath, args: [entryPath, "mcp", "--repository", repositoryId], env };
+}
+export function desktopBlock(key, entry) {
+    return JSON.stringify({ mcpServers: { [key]: entry } }, null, 2);
+}
+/**
+ * Merges our entry into the desktop app's configuration, or refuses.
+ *
+ * Everything already in that file stays in it. Other people's servers are other
+ * people's servers, and so is every top-level key beside `mcpServers`, which is
+ * where the app keeps settings this command knows nothing about. An unparseable
+ * file is never overwritten, and a key of ours holding somebody else's server is
+ * never replaced: the block is printed and a person decides.
+ *
+ * The key is found by what the entry says rather than by what it is called. An
+ * entry of ours already bound to this repository is rewritten where it sits,
+ * whatever it was named, so a repository renamed on GitHub does not quietly
+ * acquire a second server that starts alongside the first.
+ */
+export function mergeDesktopConfig(location, key, entry, repositoryId, controlPlane) {
+    const block = desktopBlock(key, entry);
+    if (location.kind === "unsupported") {
+        return { kind: "refused", reason: location.reason, block };
+    }
+    // The app creates its own directory the first time it runs. Creating one it
+    // never made would leave a configuration file behind for an application that
+    // is not installed, and the person would read "connected" about a chat client
+    // they do not have.
+    if (!existsSync(location.directory)) {
+        return {
+            kind: "absent",
+            directory: location.directory,
+            reason: `Claude desktop was not found on this machine: ${location.directory} does not exist, so I wrote no ${DESKTOP_CONFIG_FILE}. Install Claude desktop and open it once, then run this again.`,
+        };
+    }
+    let existing = "";
+    try {
+        existing = readFileSync(location.path, "utf8");
+    }
+    catch {
+        writeJsonAtomically(location.path, `${block}\n`);
+        return { kind: "written", changed: true, path: location.path, key };
+    }
+    let parsed;
+    try {
+        const value = JSON.parse(existing);
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error("not an object");
+        }
+        parsed = value;
+    }
+    catch {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} could not be parsed; I did not change it.`,
+            block,
+        };
+    }
+    const raw = parsed.mcpServers;
+    if (raw !== undefined && (raw === null || typeof raw !== "object" || Array.isArray(raw))) {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} has an mcpServers value that is not a set of servers; I did not change it.`,
+            block,
+        };
+    }
+    const servers = raw === undefined ? {} : { ...raw };
+    const target = ourKeyFor(servers, repositoryId, controlPlane) ?? key;
+    const current = servers[target];
+    if (current !== undefined && !isOurEntry(current, controlPlane)) {
+        return {
+            kind: "refused",
+            reason: `Claude desktop's ${DESKTOP_CONFIG_FILE} already has an entry named ${target} that is not this workspace's server; I did not change it.`,
+            block: desktopBlock(target, entry),
+        };
+    }
+    servers[target] = entry;
+    const next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
+    if (next === existing) {
+        return { kind: "written", changed: false, path: location.path, key: target };
+    }
+    writeJsonAtomically(location.path, next);
+    return { kind: "written", changed: true, path: location.path, key: target };
+}
+/** The key already carrying our server for this repository, whatever it is called. */
+function ourKeyFor(servers, repositoryId, controlPlane) {
+    for (const [name, value] of Object.entries(servers)) {
+        if (!isOurEntry(value, controlPlane))
+            continue;
+        if (entryRepositoryId(value) === repositoryId)
+            return name;
+    }
+    return undefined;
+}

package/dist/git.d.ts

@@ -1,5 +1,20 @@
 export declare const CI_BRANCH = "balladeer/connect-ci";
 export declare function repositoryRoot(cwd: string): Promise<string | undefined>;
+/**
+ * The commit at HEAD, and the whole of its message.
+ *
+ * Both are read here, on the customer's machine, and only the pair of a SHA and
+ * a session id ever leaves it. That is the boundary this feature turns on:
+ * Balladeer receives commit SHAs from CI and never a commit message, so the
+ * trailer has to be read where the text already is.
+ *
+ * Absent on a repository with no commits, or on a directory that is not a
+ * checkout, which is an answer rather than a fault.
+ */
+export declare function headCommit(cwd: string): Promise<Readonly<{
+    sha: string;
+    message: string;
+}> | undefined>;
 /**
  * A repository in the middle of a merge or a rebase is not a repository to open
  * a pull request from. The person is mid-operation, and anything this command

package/dist/git.js

@@ -8,6 +8,29 @@ export async function repositoryRoot(cwd) {
     const answer = await runCommand("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
     return answer.ok ? answer.stdout.trim() : undefined;
 }
+/**
+ * The commit at HEAD, and the whole of its message.
+ *
+ * Both are read here, on the customer's machine, and only the pair of a SHA and
+ * a session id ever leaves it. That is the boundary this feature turns on:
+ * Balladeer receives commit SHAs from CI and never a commit message, so the
+ * trailer has to be read where the text already is.
+ *
+ * Absent on a repository with no commits, or on a directory that is not a
+ * checkout, which is an answer rather than a fault.
+ */
+export async function headCommit(cwd) {
+    const sha = await runCommand("git", ["-C", cwd, "rev-parse", "HEAD"]);
+    if (!sha.ok)
+        return undefined;
+    const trimmed = sha.stdout.trim();
+    if (!/^[0-9a-f]{40}$/.test(trimmed))
+        return undefined;
+    const message = await runCommand("git", ["-C", cwd, "log", "-1", "--pretty=%B", trimmed]);
+    if (!message.ok)
+        return undefined;
+    return { sha: trimmed, message: message.stdout };
+}
 async function gitDirectory(root) {
     const answer = await runCommand("git", ["-C", root, "rev-parse", "--absolute-git-dir"]);
     return answer.ok ? answer.stdout.trim() : undefined;

package/dist/legacy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The earlier Balladeer, still installed, found before this one writes anything.
+ *
+ * A team that used the July client has a program on their machine that this one
+ * knows nothing about: it updates itself from its own server rather than from
+ * npm, it registers an MCP server named `balladeer` for the whole machine, and
+ * it installs a session hook and a conventions block of its own. This product
+ * registers an MCP server under the same name, per repository. Nothing breaks
+ * loudly when both are present, which is the problem: the older session hook
+ * keeps firing inside the repository somebody enrolled today, one file ends up
+ * carrying two conventions blocks, and the person reads the result as this
+ * product misbehaving.
+ *
+ * The older client can take itself off, reversibly, with `balladeer uninstall`
+ * followed by the removal command it prints. So this is a warning that stops
+ * rather than a refusal that stands: the sentence names the one thing to do,
+ * and `--force` is there for whoever has decided to run both anyway.
+ */
+export type LegacyInstall = Readonly<{
+    /** Which file said so, in the form a person can go and open. */
+    where: string;
+    /** What was found there, bounded, so a config file cannot become an essay. */
+    detail: string;
+}>;
+/**
+ * The instruction, in the same words `docs/didero-day-one.md` and
+ * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
+ * and a person who read the document ahead of time are told to do the same
+ * thing, by the same sentence.
+ */
+export declare const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
+/**
+ * The older install this machine still carries, or nothing.
+ *
+ * Two places, because those are the two the older client owns that reach into a
+ * session in a repository enrolled today: the machine-wide MCP entry under our
+ * own name, and the hook that fires at session start.
+ */
+export declare function findLegacyInstall(environment: NodeJS.ProcessEnv, controlPlane: string): LegacyInstall | undefined;
+/** What the person reads, whichever of the two files said so. */
+export declare function legacyMessage(found: LegacyInstall): string;

package/dist/legacy.js

@@ -0,0 +1,143 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isOurEntry } from "./mcp-config.js";
+/**
+ * The instruction, in the same words `docs/didero-day-one.md` and
+ * `docs/didero-mcp-walkthrough.md` print. A person who hits this in the terminal
+ * and a person who read the document ahead of time are told to do the same
+ * thing, by the same sentence.
+ */
+export const UNINSTALL_INSTRUCTION = "If you used the earlier Balladeer on this machine: run `balladeer uninstall`, then the removal command it prints, then continue.";
+/** How much of a foreign command line is worth printing back. */
+const DETAIL_LIMIT = 120;
+/**
+ * Where the agent host keeps its configuration, read from the environment this
+ * command was handed and never from the ambient process.
+ *
+ * Every command in this package takes its configuration as a parameter, which is
+ * what lets a test plant a whole home directory. When the environment names no
+ * home there is nothing to read, and a check that cannot read cannot warn: it
+ * stays silent rather than guessing at a path.
+ */
+function agentHome(environment) {
+    const home = environment.HOME?.trim() || environment.USERPROFILE?.trim() || "";
+    return home.length > 0 ? home : undefined;
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        // Absent, unreadable, or somebody's hand-edited file mid-save. None of those
+        // is evidence of an older install, and none of them is this command's to fix.
+        return undefined;
+    }
+}
+function bounded(text) {
+    const flattened = text.replace(/\s+/g, " ").trim();
+    return flattened.length > DETAIL_LIMIT ? `${flattened.slice(0, DETAIL_LIMIT)}...` : flattened;
+}
+/** The command line an MCP entry runs, in the shape a person would recognise. */
+function describeEntry(entry) {
+    const record = entry;
+    if (record !== null && typeof record?.url === "string")
+        return bounded(record.url);
+    const command = typeof record?.command === "string" ? record.command : "";
+    const args = Array.isArray(record?.args)
+        ? record.args.filter((value) => typeof value === "string")
+        : [];
+    const line = [command, ...args].join(" ").trim();
+    return line.length > 0 ? bounded(line) : "a command this copy does not recognise";
+}
+/**
+ * Whether a hook's command line is one of ours.
+ *
+ * This product installs no agent-host hook at all, so in practice every hook
+ * naming `balladeer` belongs to the older client. The exception is written down
+ * anyway: a team that wired one of our own published or checkout invocations
+ * into a hook of their own must not be told their own line is somebody else's
+ * program.
+ */
+function isOurCommandLine(command) {
+    if (/balladeer@(?:latest|\d+\.\d+\.\d+)\b/.test(command))
+        return true;
+    return /\bnode\b[^\n]*\bpackages[/\\]cli[/\\]dist[/\\]cli\.js\b/.test(command);
+}
+/** Every `command` string anywhere under an agent host's `hooks` setting. */
+function hookCommands(value, found = []) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            hookCommands(item, found);
+        return found;
+    }
+    if (value === null || typeof value !== "object")
+        return found;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "command" && typeof child === "string")
+            found.push(child);
+        else
+            hookCommands(child, found);
+    }
+    return found;
+}
+/**
+ * The older Balladeer's own MCP entry, if the agent host still carries one.
+ *
+ * Only the machine-wide block counts. This product writes its entry into the
+ * repository's `.mcp.json`, and a host that also records a per-project entry
+ * under `projects` records ours there: reading those as foreign would stop
+ * setup on the very install it just performed. Under the machine-wide key, an
+ * entry named `balladeer` that is not one of our recognised shapes is the older
+ * client, because nothing else has reason to claim that name.
+ */
+function legacyMcpEntry(home, controlPlane) {
+    const parsed = readJson(join(home, ".claude.json"));
+    const servers = parsed?.mcpServers;
+    if (servers === null || typeof servers !== "object")
+        return undefined;
+    const entry = servers.balladeer;
+    if (entry === undefined || entry === null)
+        return undefined;
+    if (isOurEntry(entry, controlPlane))
+        return undefined;
+    return {
+        where: join(home, ".claude.json"),
+        detail: `an MCP server named balladeer, registered for the whole machine, running ${describeEntry(entry)}`,
+    };
+}
+/** The older Balladeer's session hook, if the agent host still runs one. */
+function legacyHook(home) {
+    const parsed = readJson(join(home, ".claude", "settings.json"));
+    const hooks = parsed?.hooks;
+    if (hooks === undefined)
+        return undefined;
+    const command = hookCommands(hooks).find((line) => /balladeer/i.test(line) && !isOurCommandLine(line));
+    if (command === undefined)
+        return undefined;
+    return {
+        where: join(home, ".claude", "settings.json"),
+        detail: `a hook that runs ${bounded(command)}`,
+    };
+}
+/**
+ * The older install this machine still carries, or nothing.
+ *
+ * Two places, because those are the two the older client owns that reach into a
+ * session in a repository enrolled today: the machine-wide MCP entry under our
+ * own name, and the hook that fires at session start.
+ */
+export function findLegacyInstall(environment, controlPlane) {
+    const home = agentHome(environment);
+    if (home === undefined)
+        return undefined;
+    return legacyMcpEntry(home, controlPlane) ?? legacyHook(home);
+}
+/** What the person reads, whichever of the two files said so. */
+export function legacyMessage(found) {
+    return [
+        `An earlier Balladeer is still installed on this machine: ${found.where} carries ${found.detail}.`,
+        "Both products register an MCP server named balladeer and the earlier one keeps firing its own session hook, so leaving it in place puts two Balladeers in the sessions you open in this repository.",
+        UNINSTALL_INSTRUCTION,
+        "Nothing was changed. Run this command again with --force to set up anyway.",
+    ].join("\n");
+}

package/dist/local-time.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Every absolute time this command prints for a person, on the clock they read.
+ *
+ * Robert approved a pairing code that had already lapsed. The screen said the
+ * code stopped being approvable at a time four hours ahead of the one on his
+ * wall, and named no zone, so he read a moment that had gone as a moment still
+ * to come. `apps/control-plane/lib/local-time.ts` fixed that on the web pages
+ * and says why: an unlabelled time is not a shorter time, it is a different one.
+ *
+ * The terminal had no equivalent, and it prints the same deadlines: the pairing
+ * code, the setup session, the invitation, when a map was measured, when a run
+ * observed a failure. Every one of them was a UTC instant in a sentence a person
+ * reads. So nothing here formats an instant without saying which clock it is on.
+ *
+ * Unlike a server render, this one always knows: the command runs on the
+ * reader's own machine, so there is a single shape rather than the web's pair of
+ * them, and it is the shape the web already shows a signed-in viewer, so a
+ * person who reads a deadline in the terminal and again on the promise page
+ * reads it written the same way both times.
+ *
+ * It is a copy of the control plane's formatter rather than an import of it.
+ * This package is published to npm on its own and must not carry the web
+ * application behind it; the rule the two share is the one in the guard tests,
+ * which hold both surfaces to the same sentence.
+ *
+ * Machine-readable output is not this module's business. `--json` steps carry
+ * the ISO instant exactly as Balladeer sent it, because the reader there is a
+ * program with its own clock and its own zone.
+ */
+/** What a stored value that is not a time says, rather than "Invalid Date". */
+export declare const UNREADABLE_TIME = "an unrecorded time";
+/**
+ * The zone this machine is set to.
+ *
+ * Every reach for `Intl` in the command is in this one file, which is what lets
+ * the guard test state the rule as a scan rather than as a list of sentences
+ * somebody has to remember to extend.
+ */
+export declare function machineTimeZone(): string;
+/**
+ * One instant, in the reader's own zone, with the zone named beside it.
+ *
+ * `timeZoneName: "short"` is the load-bearing option. Remove it and every
+ * sentence below silently goes back to printing a bare wall clock, which is the
+ * bug this module exists for, so the guard test asserts a zone token on the end
+ * of the output in every zone it checks.
+ *
+ * The zone is a parameter so the tests can read one instant on several clocks.
+ * No caller passes one: the machine's own zone is the answer for a command that
+ * runs on the reader's machine.
+ */
+export declare function formatInstant(value: string, timeZone?: string): string;
+/**
+ * A sentence Balladeer wrote, with the instants in it moved onto the reader's
+ * clock.
+ *
+ * Some refusals are relayed to the terminal word for word, on purpose: the
+ * server's sentence names what to do next, and rewriting it here would lose the
+ * part the person has to act on. But the server has no idea where the reader is
+ * sitting, so it writes UTC, and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reaches somebody whose clock says 2:05 in the
+ * afternoon. This moves the instants and leaves every other word alone, so what
+ * an agent is told over the tool call and what a person is told at a terminal
+ * stay the same sentence.
+ */
+export declare function inReadersZone(text: string, timeZone?: string): string;

package/dist/local-time.js

@@ -0,0 +1,84 @@
+/**
+ * Every absolute time this command prints for a person, on the clock they read.
+ *
+ * Robert approved a pairing code that had already lapsed. The screen said the
+ * code stopped being approvable at a time four hours ahead of the one on his
+ * wall, and named no zone, so he read a moment that had gone as a moment still
+ * to come. `apps/control-plane/lib/local-time.ts` fixed that on the web pages
+ * and says why: an unlabelled time is not a shorter time, it is a different one.
+ *
+ * The terminal had no equivalent, and it prints the same deadlines: the pairing
+ * code, the setup session, the invitation, when a map was measured, when a run
+ * observed a failure. Every one of them was a UTC instant in a sentence a person
+ * reads. So nothing here formats an instant without saying which clock it is on.
+ *
+ * Unlike a server render, this one always knows: the command runs on the
+ * reader's own machine, so there is a single shape rather than the web's pair of
+ * them, and it is the shape the web already shows a signed-in viewer, so a
+ * person who reads a deadline in the terminal and again on the promise page
+ * reads it written the same way both times.
+ *
+ * It is a copy of the control plane's formatter rather than an import of it.
+ * This package is published to npm on its own and must not carry the web
+ * application behind it; the rule the two share is the one in the guard tests,
+ * which hold both surfaces to the same sentence.
+ *
+ * Machine-readable output is not this module's business. `--json` steps carry
+ * the ISO instant exactly as Balladeer sent it, because the reader there is a
+ * program with its own clock and its own zone.
+ */
+/** What a stored value that is not a time says, rather than "Invalid Date". */
+export const UNREADABLE_TIME = "an unrecorded time";
+/**
+ * The zone this machine is set to.
+ *
+ * Every reach for `Intl` in the command is in this one file, which is what lets
+ * the guard test state the rule as a scan rather than as a list of sentences
+ * somebody has to remember to extend.
+ */
+export function machineTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+/**
+ * One instant, in the reader's own zone, with the zone named beside it.
+ *
+ * `timeZoneName: "short"` is the load-bearing option. Remove it and every
+ * sentence below silently goes back to printing a bare wall clock, which is the
+ * bug this module exists for, so the guard test asserts a zone token on the end
+ * of the output in every zone it checks.
+ *
+ * The zone is a parameter so the tests can read one instant on several clocks.
+ * No caller passes one: the machine's own zone is the answer for a command that
+ * runs on the reader's machine.
+ */
+export function formatInstant(value, timeZone = machineTimeZone()) {
+    const when = new Date(value);
+    if (Number.isNaN(when.valueOf()))
+        return UNREADABLE_TIME;
+    return new Intl.DateTimeFormat("en-US", {
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        timeZone,
+        timeZoneName: "short",
+    }).format(when);
+}
+/** An instant as Balladeer writes one: ISO 8601, UTC, to the millisecond. */
+const ISO_INSTANT = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
+/**
+ * A sentence Balladeer wrote, with the instants in it moved onto the reader's
+ * clock.
+ *
+ * Some refusals are relayed to the terminal word for word, on purpose: the
+ * server's sentence names what to do next, and rewriting it here would lose the
+ * part the person has to act on. But the server has no idea where the reader is
+ * sitting, so it writes UTC, and "already prepared by Robert Clark on
+ * 2026-09-07T18:05:10.698Z" reaches somebody whose clock says 2:05 in the
+ * afternoon. This moves the instants and leaves every other word alone, so what
+ * an agent is told over the tool call and what a person is told at a terminal
+ * stay the same sentence.
+ */
+export function inReadersZone(text, timeZone = machineTimeZone()) {
+    return text.replace(ISO_INSTANT, (instant) => formatInstant(instant, timeZone));
+}

package/dist/mcp-config.d.ts

@@ -75,6 +75,16 @@ export declare function stdioEntry(repositoryId: string, publishedVersion: strin
  * Balladeer entry is foreign.
  */
 export declare function isOurEntry(entry: unknown, controlPlane: string): boolean;
+/**
+ * Atomic, and never through a path something could have pre-planted: the
+ * temporary file is opened with `wx` under a random name in the same directory,
+ * flushed, and renamed over the target.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
+ */
+export declare function writeJsonAtomically(path: string, contents: string): void;
 /**
  * Merges our entry into the repository's `.mcp.json`, or refuses.
  *

package/dist/mcp-config.js

@@ -112,9 +112,13 @@ function renderBlock(entry) {
  * Atomic, and never through a path something could have pre-planted: the
  * temporary file is opened with `wx` under a random name in the same directory,
  * flushed, and renamed over the target.
+ *
+ * Exported because the Claude desktop configuration is written under the same
+ * rule and for a stronger reason: that file belongs to a running application,
+ * and a half-written one is a chat client that starts with no servers at all.
  */
-function writeAtomically(path, contents) {
-    const temporary = join(dirname(path), `.mcp.${randomBytes(8).toString("hex")}.tmp`);
+export function writeJsonAtomically(path, contents) {
+    const temporary = join(dirname(path), `.balladeer.${randomBytes(8).toString("hex")}.tmp`);
     let descriptor;
     try {
         descriptor = openSync(temporary, "wx", 0o644);
@@ -157,7 +161,7 @@ export function mergeMcpConfig(repositoryRoot, entry, controlPlane) {
         existing = readFileSync(path, "utf8");
     }
     catch {
-        writeAtomically(path, `${JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2)}\n`);
+        writeJsonAtomically(path, `${JSON.stringify({ mcpServers: { balladeer: entry } }, null, 2)}\n`);
         return { kind: "written", changed: true };
     }
     let parsed;
@@ -192,7 +196,7 @@ export function mergeMcpConfig(repositoryRoot, entry, controlPlane) {
     const next = `${JSON.stringify({ ...parsed, mcpServers: servers }, null, 2)}\n`;
     if (next === existing)
         return { kind: "written", changed: false };
-    writeAtomically(path, next);
+    writeJsonAtomically(path, next);
     return { kind: "written", changed: true };
 }
 /**