balladeer 1.0.0 → 1.0.2

package/dist/copy.js

@@ -21,23 +21,35 @@ test output.
 The verify job in your CI runs your tests with your checkout and has no Balladeer credential. A
 separate publish job, with no checkout, sends only those outcomes and hashes.
 
-This setup creates two credentials, both of which you control. Approving in the browser lets this
-session act as you to add repositories, connect your coding agent, connect CI, and propose promises;
-it cannot approve, activate, or remove anything. That session lasts a day, each use buys it another
-day, and it is gone seven days after you approved it however much you used it. The coding agent's
-own connection has no expiry: it lets the agent read the promises your team has approved, propose
-new ones, and propose replacing, retiring, excepting, or reassigning one you already have; every one
-of those waits for a named person to decide it. It can also carry out one of those acts for you, and
-only this way: you open a Balladeer page in your own browser, read what the act is, sign it off
-there, and read back the one-time code that page gives you. That code covers that one act on that
-one thing, once, and Balladeer records you as the person who took it and the connection as the
-messenger. Without a code you signed, the connection cannot approve, activate, grant, transfer,
-retire, or delete anything. You can revoke either one at any time in Balladeer, and the setup
-session also ends on its own.
+Browser approval creates a temporary setup session limited by that person's workspace role. A
+contributor can connect this machine's coding agent to an already-enrolled repository and propose
+promises; an administrator can also add repositories, connect CI, and invite teammates. The session
+cannot approve, activate, rotate, revoke, or remove anything. It lasts a day, each use buys it
+another day, and it is gone seven days after approval however much it was used. When setup connects
+an enrolled repository it also issues that machine a coding-agent credential. That connection has no
+expiry: it lets the agent read the promises your team has approved, propose new ones, and propose
+replacing, retiring, excepting, or reassigning one you already have; every one of those waits for a
+named person to decide it. It can also carry out one of those acts for you, and only this way: you
+open a Balladeer page in your own browser, read what the act is, sign it off there, and read back
+the one-time code that page gives you. That code covers that one act on that one thing, once, and
+Balladeer records you as the person who took it and the connection as the messenger. Without a code
+you signed, the connection cannot approve, activate, grant, transfer, retire, or delete anything.
+You can revoke either one at any time in Balladeer, and the setup session also ends on its own.
 
 Adding the workflow puts a check on pull requests into your default branch. That check is advisory
 on Balladeer's side; whether it blocks a merge is your own branch protection.
 `;
+/**
+ * The one thing about approving that the terminal has to say.
+ *
+ * A person who belongs to two workspaces approves into whichever one their
+ * browser is signed into, and it is the browser that decides, not the terminal.
+ * Twice that was the wrong one: the repository was enrolled in a workspace
+ * nobody meant and an agent connection was minted there. The approval page now
+ * names the workspace above the button and offers the switch, and this line is
+ * what makes somebody look at it before they click.
+ */
+export const APPROVE_IN_THE_RIGHT_WORKSPACE = "Approve it while your browser is in the workspace you mean; the page names it.";
 /**
  * How a person gets a workspace to approve into, for an agent reading the
  * setup instructions.
@@ -55,12 +67,18 @@ on Balladeer's side; whether it blocks a merge is your own branch protection.
  * and the terminal it is reading cannot come to describe this differently.
  */
 export const JOIN_OR_CREATE = `The pairing page joins an existing workspace or makes a new one. Somebody whose team already has
-a Balladeer workspace signs in and approves the code from the terminal. Somebody who is the first
-person from their team signs in, names a workspace, and clicks Create, and only then is there
-anything to approve into.
+a Balladeer workspace accepts their email invitation, then runs \`npx -y balladeer@latest setup --existing\` in
+the checkout they mean to use. That teammate mode never adds a repository or changes CI. After they
+sign in and approve the code, onboarding continues even when the checkout is not in the workspace.
+If it is already enrolled, setup connects this machine's coding agent. If it is absent, the person
+can still use Balladeer in the browser; a red warning explains that enforcement cannot be tracked
+until an administrator connects a repository.
+
+Somebody who is the first person from their team signs in, names a workspace, and clicks Create, and
+only then is there anything to approve into.
 
 You can save them the typing, and nothing else. Ask what the workspace should be called, then run
-\`balladeer setup --create-workspace "<name>"\` with the name they gave you. The pairing link this
+\`npx -y balladeer@latest setup --create-workspace "<name>"\` with the name they gave you. The pairing link this
 command prints then carries \`?create=<name>\`, which pre-fills that name in the create form on the
 pairing page. It fills the box and no more than that: the person signs in and clicks Create, and
 until they do there is no workspace. An agent never creates one, and Balladeer refuses the attempt
@@ -135,7 +153,7 @@ seen everything.`;
  * plane's `/agent` page carries the same bytes under its own constant, and a
  * packaging test compares them.
  */
-export const SESSION_BEHAVIORS = `### Two things to offer without being asked
+export const SESSION_BEHAVIORS = `### Three things to offer without being asked
 
 At the start of any session in this repository, before you plan anything, ask list_promises for the
 promises nothing is checking yet that belong to the person you are working with: \`unverified\` true
@@ -159,7 +177,136 @@ true, the numbered cases that must keep working and the ones that must be caught
 you left open. Then offer to finish the agreement from here, by asking for a sign-off, giving them
 the page it returns and taking the one-time code that page shows them, so the browser is needed only
 for signing. Give them the review link in the same message too, because some people would rather
-read it there and edit it before they agree.`;
+read it there and edit it before they agree.
+A promise whose meaning is agreed and which nothing is checking yet is one you can finish. When
+somebody gives you a promise id, run \`npx -y balladeer@latest status <promise id>\`, or expand it with get_promise.
+If it comes back agreed with nothing checking it, say so in one line and offer to prepare and build
+its verifier now. Only if they say yes: \`prepare_qualification\` mints the one-time setup, or
+\`npx -y balladeer@latest prepare <promise id>\` mints it and writes it where the sealed run reads it. You need no
+sign-off for that and there is no code to ask anybody for, because agreeing the meaning was their
+act and building the check that proves it is yours. Then build the verifier, seal it, push, and tell
+them protection starts by itself when that run qualifies. The offer is the whole of it: never
+prepare one because nobody said no.`;
+/**
+ * The capture rules that do not change: when to say nothing, what a yes is
+ * worth, and the two promises Balladeer refuses.
+ *
+ * This block is written into the customer's own instructions file once, at
+ * setup, and is never refreshed afterwards. Changing it means opening a pull
+ * request against twelve Didero repositories, so only what will still be true
+ * in six months belongs here. Silence during an incident, a no that ends it, and
+ * nothing filed without a yes are that kind of rule. The words a question is
+ * asked in, the moment an offer is made, and the shape a proposal takes are not:
+ * they are read every week against what people actually agreed to, and they ride
+ * in `CAPTURE_BEHAVIOR`, which the server sends at the start of every session.
+ *
+ * Nothing here weakens the explicit-capture rule: the question is a question,
+ * and nothing is proposed until the answer is yes.
+ *
+ * The two refusals are here rather than only in the server because an agent that
+ * learns them only by being refused has already spent the person's attention on
+ * a proposal that could not be kept. The server refuses both as well, and the
+ * sentences are the same ones.
+ *
+ * Byte for byte the same text as `AGENT_INSTRUCTIONS_CAPTURE_SEAM` in the
+ * control plane, and contained byte for byte inside both server carriers. A
+ * packaging test holds all three together: the block written into a customer's
+ * repository, the instructions the MCP server sends on initialize, and the page
+ * an agent fetches cannot come to say different things about when to stay quiet.
+ */
+export const CAPTURE_SEAM = `### When to say nothing, and what a yes is worth
+
+Most rules are said in passing, in the middle of something else. Somebody saying one has not asked
+you to record anything, so propose nothing and start no interview. When you do ask, it is one line
+appended to the end of the reply you were already going to give, never a message of its own, never
+asked twice about the same rule, and nothing is proposed until they say yes. A no ends it, and that
+rule is not raised again for the rest of the conversation.
+
+Silence is per conversation rather than per message. Once a conversation is one of these, you ask
+nothing for the rest of it, however good the rule sounds:
+
+- A question, or working out how something already behaves. Nothing is filed and nothing is offered.
+- A refactor. Nobody predicts a promise from a rewrite. Offer the promises this area already carries
+  that nothing is checking yet, once, and then wait. Ask nothing about new ones.
+- A change to wording alone. Wording somebody may change again tomorrow is not a rule.
+- An incident, while it is still being fixed. Ask nothing at all until the fix is merged or they say
+  it is done, however good tonight's failing case would be.
+- Somebody still weighing options. A decision nobody has made yet is not a rule.
+- An exploration or spike. It ends in nothing or in a plan, and its sentences sound like rules and
+  are not.
+- Reading somebody else's change, while you are still reading it. Nothing is offered until they
+  give a verdict.
+
+The words to ask in, the moment to offer, and the shape a proposal takes are not in this file. The
+Balladeer server sends them at the start of every session, and its copy is the current one: read
+what it sent this session rather than what this file remembers.
+
+### Two promises Balladeer cannot keep
+
+A promise about speed needs three things before it is a promise at all: a number, a percentile, and
+where it is measured. "The quote page answers in under one second at p95, measured in production at
+peak load" is one Balladeer can keep. "The quote page has to be fast" is not. Say this, and ask for
+the part that is missing rather than filing it:
+
+"I can keep that once it has a number, a percentile, and a place it is measured. Without those it is
+a wish, not a promise."
+
+Balladeer refuses one without all three and names which of them is missing. When all three are
+there, write the measurement method into the promise, and tell them plainly that it reads agreed and
+unprotected until a test that actually measures it exists.
+
+A promise about how the team works is not something the software does, so no check can ever catch
+it. "We must provide a low-friction capture experience" is one of these. File nothing and say:
+
+"That is a promise about how we work, not something the software does that a check can fail.
+Balladeer only keeps promises a check can catch. If a customer would notice something when this
+slips, say that and I will keep that instead."
+
+Then take the customer-visible half if they give you one, and file that instead.`;
+/**
+ * How an agent describes one promise or proposal to a person, and how the two
+ * of them settle what is still open on it.
+ *
+ * The first proposal a founder was ever asked to settle carried four questions
+ * that were all true and none of them answerable: each named a hole in the
+ * world, and none said what answering it would decide or what the agent would
+ * do if nobody replied. So this says both halves of the same rule. When a
+ * person points at something by id, describe it and offer to work through what
+ * is open; and when you leave a question open, leave one that can be answered
+ * with a yes.
+ *
+ * Three carriers say it byte for byte: the block setup writes into the
+ * customer's own instructions file, the instructions the MCP server sends on
+ * initialize, and the page `/agent` serves. A packaging test holds them
+ * together.
+ */
+export const SETTLING_QUESTIONS = `### When somebody says "tell me about" one
+
+An id is how a person points at something here, and every promise page and every proposal page
+carries one. A promise id starts with prom_ and a proposal id starts with cand_: expand a promise
+with get_promise and a proposal with get_proposal, and read neither of them out as a list of fields.
+Say in four or five sentences what it is for, who it is for, when it applies and what must then be
+true. Then say where it stands: a promise is agreed, and either protected or not yet checked by
+anything; a proposal is agreed by nobody and waiting on the person it names.
+
+A proposal that still carries open questions is not finished, and settling them is usually why
+somebody asked. Offer to work through them, then take them one at a time in the order they come
+back. For each one, say what it decides in their words rather than in the question's; give your
+recommendation and the reason you hold it, drawn from this repository and from the promise itself;
+and stop there. When they answer, record what they said with resolve_question, in their own words
+where they gave you any, and where their answer changes the promise, follow it with update_proposal,
+add_case or remove_case and tell them what you changed. None of that agrees to anything: the named
+owner agrees, in their own browser or through a sign-off you carry, and the questions they answered
+stay on the proposal in their name.
+
+The same rule governs every question you leave open in the first place. A question that names a gap
+and stops is a note, and nobody can answer a note. Say what answering it decides, in the words a
+customer would use, and carry your own best guess with the reason behind it, so that the shortest
+true answer is yes. For example: "Decides: whether a worker that is running but reconciling nothing
+counts as an outage this promise covers. Best guess: yes, because the promise is about somebody
+hearing before a customer does, and a wedged worker is invisible to every check this repository has.
+Say yes, or tell me otherwise." Balladeer refuses a question filed without both halves and says
+which one is missing.`;
 /**
  * What a session may spend on reading, in three sentences.
  *
@@ -204,9 +351,9 @@ breaks the seal. A promise whose seal is broken stops being checked, and it stay
 named person qualifies it again, which is their afternoon rather than your commit. Nothing in there
 is ordinary source: keep it out of refactors, formatting runs and dependency upgrades.
 
-Find out which directories are sealed before you plan an edit, not after. balladeer status lists
+Find out which directories are sealed before you plan an edit, not after. npx -y balladeer@latest status lists
 them, and list_promises names a promise's sealed directory on its row once a verifier is bound to
-it. Then, before you push, run balladeer check-seals. It prints nothing and exits zero when your
+it. Then, before you push, run npx -y balladeer@latest check-seals. It prints nothing and exits zero when your
 change touches no seal, and names the promise, its owner and its page when your change would break
 one.
 
@@ -214,8 +361,8 @@ The one reason to edit a sealed file is to repair a verifier that can no longer
 imports moved, or the language it is written in changed under it. Never edit one to make a failing
 check pass. A check going red is the promise doing its job, and the repair for that belongs in the
 behavior it protects. A repair is not finished until the promise is sealed again with the runner
-this repository is pinned to. get_promise_setup carries that exact seal command, and balladeer
-check-seals prints it beside any promise it names.`;
+this repository is pinned to. get_promise_setup carries that exact seal command, and
+npx -y balladeer@latest check-seals prints it beside any promise it names.`;
 /**
  * Which promises a change touches, measured rather than guessed.
  *
@@ -232,19 +379,57 @@ check-seals prints it beside any promise it names.`;
  * Three carriers say it, byte for byte, and a packaging test holds them
  * together.
  */
-export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`balladeer affected
+export const TOUCH_MAP_GUIDANCE = `Prefer the measurement over the markers. Where this repository has a touch map, \`npx -y balladeer@latest affected
 <paths...>\` answers which promises ran the files in front of you, out of what each verifier actually
-executed the last time \`balladeer touch-map\` measured it. Both commands run on this machine and
+executed the last time \`npx -y balladeer@latest touch-map\` measured it. Both commands run on this machine and
 send Balladeer nothing, so you may name any path in the change.
 
 An answer marked stale was measured against a verifier that has changed since, so read it as the
-last thing anybody measured rather than as fact, and offer to run \`balladeer touch-map\` again.
+last thing anybody measured rather than as fact, and offer to run \`npx -y balladeer@latest touch-map\` again.
 Where there is no map, where it does not name your paths, or where it reports a promise it could not
 measure, fall back to the paths on the index rows. The map narrows which promises are worth
 fetching. It never widens what you may read: the catalog is still never enumerated, and the fetch
 budget is unchanged.
 
 When a retrieval receipt asks why you read a row, the answer for one the map named is \`touch\`.`;
+/**
+ * The one paragraph that turns retrieval from a thing we argue about into a
+ * thing we measure.
+ *
+ * Two facts are asked for and neither can be observed from this side. Which
+ * rows an agent actually used, because a promise expanded and then ignored is
+ * not a row the index earned. And which change the session went on to write,
+ * because a retrieval read happens before the commit exists and nothing joins
+ * the two afterwards: Balladeer receives commit SHAs from CI and never a commit
+ * message, so the agent is the only thing present at both ends.
+ *
+ * It is written as three instructions rather than as an explanation, because
+ * what an agent does with it is three specific acts, and a paragraph about
+ * measurement would be read and not acted on.
+ *
+ * Three carriers say it, byte for byte, and a packaging test holds them
+ * together.
+ */
+export const SESSION_STAMP = `Run \`npx -y balladeer@latest session\` when you start work here and pass the id it prints to every promise read
+you make, as \`session\`. It is the same id for the whole of one piece of work, and it costs nothing:
+a read without it is answered exactly the same way.
+
+If local file permissions refuse that session write, no session stamp was saved. Your saved
+connection is unchanged; this does not prove its current server authorization. Continue
+already-authorized MCP reads, coding and explicitly requested capture without the optional
+\`session\` field. Do not invent an ID, add a session trailer, or record an unsaved stamp. Do not
+broaden filesystem access or move credentials to retry this write. A missing credential or server
+authorization refusal is different: follow that refusal. Capture still needs the person's request
+or accepted offer, and human meaning approval is unchanged.
+
+If a session ID was saved, near the end of the work call \`mark_promise_used\` with the ids you actually cited
+or acted on. Naming none is a fine answer. It is the only way anybody finds out which rows were
+worth sending you, because reading a promise and then ignoring it is not the same as using it.
+
+If a session ID was saved, write \`Balladeer-Session: <the id>\` into the commit message or pull-request body you produce,
+and run \`npx -y balladeer@latest session --record\` once the commit exists. That is what lets a check that goes red
+next week be read back against what Balladeer told you before you started. Your commit message never
+leaves your machine: only the session id and the commit SHA are sent.`;
 /**
  * The conventions block written between markers into this repository's agent
  * instructions file. Fixed text, compared byte for byte by a test, because a
@@ -267,6 +452,10 @@ ${TOUCH_MAP_GUIDANCE}
 
 ${FETCH_BUDGET}
 
+${CAPTURE_SEAM}
+
+${SESSION_STAMP}
+
 ### When somebody asks you to protect a behavior
 
 Somebody has asked you to protect a behavior when they say what the software must do, or must never
@@ -319,6 +508,8 @@ especially: it is Balladeer's word for a proposal, so it reads as jargon whateve
 
 ${SESSION_BEHAVIORS}
 
+${SETTLING_QUESTIONS}
+
 ${SEALED_FILES}
 
 ### The rest of a promise's life
@@ -442,15 +633,21 @@ For each promise you propose:
   actually keeps and that you have described it as its source describes it. Nine promises from nine
   sources are not nine equally certain readings, and the person reading them is entitled to know
   which one you were least sure of. Never write 1 to get past the check.
+- One wrongOutcome sentence: what going wrong looks like, said as a must-not, in the source's own
+  words where it has them. "A second payment must not go out." "The buyer must not see a generic
+  error." Where no sentence of that shape can be written, no check with a known-bad control can be
+  written either, so leave the promise out rather than filing one nothing could ever fail.
+- One leastSure sentence, optional, naming the single thing you are least sure of and what you did
+  about it. The person reads that instead of the number.
 
 Write them all into one file, an object with a promises array, each entry shaped exactly as one
 proposal file:
 
-{"promises": [{"explicitIntent": "...", "teachBack": {"confidence": 0.9, "meaning": {"title": "..."}}}]}
+{"promises": [{"explicitIntent": "...", "teachBack": {"confidence": 0.9, "wrongOutcome": "...", "meaning": {"title": "..."}}}]}
 
 An entry carries explicitIntent and teachBack, and inside teachBack only meaning, confidence,
-unresolvedQuestions, and proposedOwnerId. Anything else is refused on this machine before the file
-leaves it, and one bad entry means not one of them is sent.
+wrongOutcome, leastSure, unresolvedQuestions, and proposedOwnerId. Anything else is refused on this
+machine before the file leaves it, and one bad entry means not one of them is sent.
 
 Every promise in the file is proposed as owned by whoever ran setup, and waits for that person. The
 command prints one link that opens all of them at once. Give the person that link and ask them to

package/dist/desktop-config.d.ts

@@ -0,0 +1,85 @@
+import { type StdioMcpEntry } from "./mcp-config.js";
+/** The file the Claude desktop app reads its stdio servers out of, on every platform that has one. */
+export declare const DESKTOP_CONFIG_FILE = "claude_desktop_config.json";
+/**
+ * Where that file lives, or why this machine has no such place.
+ *
+ * Two platforms are documented and both are handled: macOS keeps it under
+ * `Library/Application Support/Claude`, Windows under `%APPDATA%\Claude`.
+ * Claude desktop is published for those two and no others, so every other
+ * platform is told so by name rather than written to on a guess. A person
+ * running an unofficial build, or a Windows install whose packaging redirects
+ * that directory, points `BALLADEER_CLAUDE_DESKTOP_CONFIG` at the file itself
+ * and this writes exactly there.
+ */
+export type DesktopLocation = Readonly<{
+    kind: "path";
+    path: string;
+    directory: string;
+}> | Readonly<{
+    kind: "unsupported";
+    platform: string;
+    reason: string;
+}>;
+export declare function desktopConfigLocation(environment?: NodeJS.ProcessEnv, platform?: string): DesktopLocation;
+/**
+ * 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 declare function desktopServerKey(repositoryName: string, repositoryId: string): string;
+/**
+ * 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 declare function desktopStdioEntry(repositoryId: string, environment?: NodeJS.ProcessEnv, controlPlane?: string, nodePath?: string, entryPath?: string): StdioMcpEntry;
+export type DesktopMergeResult = Readonly<{
+    kind: "written";
+    changed: boolean;
+    path: string;
+    key: string;
+}> | Readonly<{
+    kind: "absent";
+    directory: string;
+    reason: string;
+}> | Readonly<{
+    kind: "refused";
+    reason: string;
+    block: string;
+}>;
+export declare function desktopBlock(key: string, entry: StdioMcpEntry): string;
+/**
+ * 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 declare function mergeDesktopConfig(location: DesktopLocation, key: string, entry: StdioMcpEntry, repositoryId: string, controlPlane: string): DesktopMergeResult;

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;
+}