balladeer 1.0.8 → 1.0.11

package/dist/commands/setup.js

@@ -12,10 +12,12 @@ import { MCP_CONFIG_FILE, currentEntry, entryRepositoryId, isOurEntry, mergeMcpC
 import { DESKTOP_CONFIG_FILE, desktopConfigLocation, desktopServerKey, desktopStdioEntry, mergeDesktopConfig, } from "../desktop-config.js";
 import { selectAgent } from "../agent.js";
 import { installGuidanceLoader } from "../guidance-install.js";
-import { findLegacyInstall, legacyMessage } from "../legacy.js";
+import { openInBrowser } from "../open-browser.js";
+import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "../remove-earlier.js";
+import { userHome } from "../user-scope.js";
 import { formatInstant } from "../local-time.js";
 import { checkoutEntryPath, commandLine, runningFromRegistryInstall } from "../release.js";
-import { hostHint, repositoryHint } from "../repository.js";
+import { hostHint, repositoryHint, repositoryHints } from "../repository.js";
 import { StoreError, assertStoreWritable, credentialsPath, dropPendingPairing, findPendingPairing, findSession, putAgent, putPendingPairing, putSession, readCredentials, writeCredentials, } from "../store.js";
 import { CLI_VERSION, DELEGATED_SCOPES, } from "../wire.js";
 import { explainText } from "./explain.js";
@@ -143,13 +145,15 @@ function pairedLines(session) {
  * scrolled, or an agent whose context was compacted, is told to approve in the
  * browser, and no other command in this release can produce that URL again.
  */
-function pendingLines(pending, repository, host, waiting, approvalUri) {
+function pendingLines(pending, repository, host, waiting, approvalUri, opened) {
     const opening = waiting
         ? ["Step 1 of 5  Waiting for approval", `  Nobody has approved ${pending.userCode} yet.`]
         : ["Step 1 of 5  Sign in and approve this session"];
     return [
         ...opening,
-        `  Open: ${approvalUri}`,
+        opened
+            ? `  Opened in your browser: ${approvalUri}  (if no page appeared, open that link yourself)`
+            : `  Open: ${approvalUri}`,
         `  The page will show this code: ${pending.userCode}`,
         // A person who belongs to two workspaces approves into whichever one their
         // browser is signed into, and twice that was not the one they meant: the
@@ -159,7 +163,9 @@ function pendingLines(pending, repository, host, waiting, approvalUri) {
         `  ${APPROVE_IN_THE_RIGHT_WORKSPACE}`,
         `  Sent to Balladeer so far: a random code, the name "${repository}", and the hostname "${host}". Nothing else.`,
         `  This pairing expires at ${formatInstant(pending.expiresAt)}.`,
-        "  Approve in the browser, then run this command again to finish.",
+        opened
+            ? "  Approve in the browser; this command waits here and finishes on its own."
+            : "  Approve in the browser, then run this command again to finish.",
         "",
         // Printed on the pairing step and nowhere else, because this is the one
         // moment the answer matters: the person is standing in front of a page that
@@ -259,11 +265,29 @@ export async function runSetup(options) {
     // that still carries the July client gets one instruction and this run stops.
     // Refresh is inside the check rather than outside it, because a repair writes
     // the same two files a first setup writes.
-    const legacy = options.force === true
-        ? undefined
-        : findLegacyInstall(options.environment, options.controlPlane);
-    if (legacy !== undefined) {
-        return fail(options, "legacy_balladeer_present", legacyMessage(legacy), 6);
+    // The earlier Balladeer, still on this machine, is taken off first: both
+    // products answer to the name `balladeer`, and while the older entry stands
+    // the host shows its server and refuses ours. Every file changed is copied
+    // beside itself first and the copies are named. `--force` sets up alongside
+    // it instead, for whoever has decided to run both.
+    if (options.force !== true) {
+        const earlier = findEarlier({
+            home: userHome(options.environment),
+            controlPlane: options.controlPlane,
+            environment: options.environment,
+            cwd: options.cwd,
+        });
+        if (earlier.length > 0) {
+            say(options, "An earlier Balladeer is on this machine:");
+            for (const line of describeEarlier(earlier))
+                say(options, line);
+            const report = removeEarlier(earlier);
+            for (const line of describeRemoval(report))
+                say(options, line);
+            emit(options, { step: "earlier", removed: report.removed, failed: report.failed });
+            if (report.failed.length > 0)
+                return fail(options, "earlier_balladeer_remains", `${report.failed.length} of the earlier Balladeer's entries could not be removed; see above. Fix those by hand, or run this command again with --force to set up alongside it.`, 6);
+        }
     }
     if (options.refresh === true)
         return runRefresh(options);
@@ -371,7 +395,8 @@ export async function runSetup(options) {
             return outcome.exitCode;
         // Printed before the wait as well as instead of it: a run that blocks for ten
         // minutes without ever naming the link is the run whose person cannot act.
-        for (const line of pendingLines(pending, repository, host, true, approvalLink(options, pending.verificationUri)))
+        const opened = openForPerson(options, approvalLink(options, pending.verificationUri));
+        for (const line of pendingLines(pending, repository, host, true, approvalLink(options, pending.verificationUri), opened))
             say(options, line);
         emit(options, {
             step: "pair",
@@ -380,7 +405,7 @@ export async function runSetup(options) {
             verificationUri: approvalLink(options, pending.verificationUri),
             expiresAt: pending.expiresAt,
         });
-        if (!options.wait) {
+        if (!options.wait && !opened) {
             pairingOnlyReceipt(options, "Nothing yet: this pairing is still waiting for someone to approve it.");
             return 0;
         }
@@ -422,7 +447,8 @@ export async function runSetup(options) {
             expiresAt: lapsed.expiresAt,
         });
     }
-    for (const line of pendingLines(pending, repository, host, false, approvalLink(options, pending.verificationUri)))
+    const opened = openForPerson(options, approvalLink(options, pending.verificationUri));
+    for (const line of pendingLines(pending, repository, host, false, approvalLink(options, pending.verificationUri), opened))
         say(options, line);
     emit(options, {
         step: "pair",
@@ -431,7 +457,7 @@ export async function runSetup(options) {
         verificationUri: approvalLink(options, pending.verificationUri),
         expiresAt: pending.expiresAt,
     });
-    if (options.wait) {
+    if (options.wait || opened) {
         return waitForApproval(options, credentials, pending, started.pollIntervalSeconds);
     }
     pairingOnlyReceipt(options, "Started a pairing and printed the link. Nobody has approved it yet.");
@@ -564,6 +590,16 @@ function terminalRefusal(pending, code) {
     }
     return undefined;
 }
+/**
+ * The link, opened for a person at the terminal and for nobody else. Whether a
+ * browser appeared is not known here; the line beside the link says what to do
+ * if none did.
+ */
+export function openForPerson(options, url) {
+    if (options.interactive !== true || options.json)
+        return false;
+    return (options.openLink ?? openInBrowser)(url);
+}
 async function waitForApproval(options, credentials, pending, pollIntervalSeconds) {
     const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
     const now = options.now ?? (() => new Date());
@@ -1676,7 +1712,7 @@ async function runRefresh(input) {
     let storedName;
     try {
         const credentials = readCredentials(options.environment);
-        const selection = selectAgent(credentials.agents, options.controlPlane, undefined, repositoryHint(options.cwd));
+        const selection = selectAgent(credentials.agents, options.controlPlane, undefined, repositoryHints(options.cwd));
         if (selection.kind === "agent") {
             stored = selection.agent.repositoryId;
             storedName = selection.agent.repository;

package/dist/commands/status.js

@@ -4,7 +4,7 @@ import { repositoryRoot } from "../git.js";
 import { MARKER_OBSERVATION_LIMITS, observeMissingMarkers, staleMarkerRow, } from "../markers.js";
 import { formatInstant } from "../local-time.js";
 import { commandLine } from "../release.js";
-import { repositoryHint } from "../repository.js";
+import { repositoryHint, repositoryHints } from "../repository.js";
 import { SEALED_PATHS_SHOWN, sealedPromises } from "../seals.js";
 import { StoreError, findSession, readCredentials } from "../store.js";
 import { CLI_INVOCATION } from "../wire.js";
@@ -103,7 +103,7 @@ async function reportBalladeer(options) {
         return fail(error instanceof StoreError ? error.code : "credential_store_unusable", error instanceof StoreError ? error.message : String(error), 4);
     }
     const here = options.repo ?? repositoryHint(options.cwd);
-    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, here);
+    const selection = selectAgent(credentials.agents, options.controlPlane, options.repository, options.repo ?? repositoryHints(options.cwd));
     const storedSession = findSession(credentials, options.controlPlane);
     const repositoryScoped = options.repo !== undefined ||
         options.repository !== undefined ||

package/dist/currency.d.ts

@@ -27,5 +27,8 @@ export declare const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
 export declare function noteServerVersion(headers: Headers): void;
 /** The one line this run prints about itself, or nothing when it is current. */
 export declare function updateNotice(): string | undefined;
+/** The newer version the server named, when it named one; nothing when this
+ * copy is current or no server has answered yet. */
+export declare function newerVersionPublished(): string | undefined;
 /** For tests, and for a process that runs more than one command. */
 export declare function resetUpdateNotice(): void;

package/dist/currency.js

@@ -24,6 +24,7 @@ export const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
 const ADVICE_LIMIT = 300;
 const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
 let notice;
+let newestSeen;
 function older(left, right) {
     const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
     for (let index = 0; index < 3; index += 1) {
@@ -55,6 +56,7 @@ export function noteServerVersion(headers) {
         return;
     if (!older(CLI_VERSION, newest))
         return;
+    newestSeen = newest;
     const advice = headers.get(CLI_ADVICE_HEADER);
     const line = advice === null ? "" : bounded(advice);
     notice =
@@ -66,7 +68,13 @@ export function noteServerVersion(headers) {
 export function updateNotice() {
     return notice;
 }
+/** The newer version the server named, when it named one; nothing when this
+ * copy is current or no server has answered yet. */
+export function newerVersionPublished() {
+    return newestSeen;
+}
 /** For tests, and for a process that runs more than one command. */
 export function resetUpdateNotice() {
     notice = undefined;
+    newestSeen = undefined;
 }

package/dist/guidance-hook.mjs

@@ -2027,7 +2027,7 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.8";
+var CLI_VERSION = "1.0.11";
 var CLIENT_HEADER = "x-balladeer-client";
 var CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 var DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
@@ -2119,6 +2119,37 @@ function readCredentials(environment = process.env) {
   }
 }
 
+// src/currency.ts
+var CLI_NEWEST_HEADER = "x-balladeer-cli-newest";
+var CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
+var ADVICE_LIMIT = 300;
+var VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
+var notice;
+var newestSeen;
+function older(left, right) {
+  const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
+  for (let index = 0; index < 3; index += 1) {
+    const difference = a[index] - b[index];
+    if (difference !== 0) return difference < 0;
+  }
+  return false;
+}
+function bounded(value) {
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, ADVICE_LIMIT);
+}
+function noteServerVersion(headers) {
+  const newest = headers.get(CLI_NEWEST_HEADER)?.trim();
+  if (newest === void 0 || !VERSION.test(newest)) return;
+  if (!older(CLI_VERSION, newest)) return;
+  newestSeen = newest;
+  const advice = headers.get(CLI_ADVICE_HEADER);
+  const line = advice === null ? "" : bounded(advice);
+  notice = line === "" ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). Run npx -y balladeer@latest setup --refresh to update the command and instructions, then restart this session.` : line;
+}
+function newerVersionPublished() {
+  return newestSeen;
+}
+
 // src/guidance.ts
 import { createHash, randomBytes } from "node:crypto";
 import {
@@ -2275,6 +2306,7 @@ async function loadGuidance(input) {
           ...previous ? { "if-none-match": previous.etag } : {}
         }
       });
+      noteServerVersion(response.headers);
       if (response.status === 304) {
         if (!previous || response.headers.get("etag") !== previous.etag || response.headers.get("x-balladeer-guidance-revision") !== previous.document.revision) {
           throw new Error("invalid_guidance_revalidation");
@@ -2413,7 +2445,7 @@ import {
 import { basename, dirname as dirname2, isAbsolute, join as join3 } from "node:path";
 
 // src/release.ts
-var PUBLISHED_SPECIFIER = "balladeer@latest";
+var HOOK_SPECIFIER = "balladeer@1";
 
 // src/mcp-config.ts
 var MCP_CONFIG_FILE = ".mcp.json";
@@ -2874,6 +2906,16 @@ function validateProjectGuidanceScope(options) {
 var REPOSITORY_NAME = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
 function selectAgent(agents, controlPlane, repositoryId, currentRepository) {
   const here = agents.filter((agent) => agent.controlPlane === controlPlane);
+  if (typeof currentRepository !== "string") {
+    const candidates = currentRepository.filter(
+      (name) => REPOSITORY_NAME.test(name) && name !== "unknown/unknown"
+    );
+    for (const name of candidates) {
+      const found = selectAgent(agents, controlPlane, repositoryId, name);
+      if (found.kind !== "refused") return found;
+    }
+    return selectAgent(agents, controlPlane, repositoryId, candidates[0] ?? "unknown/unknown");
+  }
   if (repositoryId !== void 0) {
     const named = here.find(
       (agent) => agent.repositoryId === repositoryId || agent.repository?.toLowerCase() === repositoryId.toLowerCase()
@@ -2926,73 +2968,80 @@ function withSafeEndpoint(agent) {
 // src/repository.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
 var REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
-function repositoryHint(cwd = process.cwd()) {
-  let remote;
+function git(cwd, args) {
   try {
-    remote = execFileSync2("git", ["-C", cwd, "remote", "get-url", "origin"], {
+    return execFileSync2("git", ["-C", cwd, ...args], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
   } catch {
-    return "unknown/unknown";
+    return void 0;
   }
+}
+function ownerName(remote) {
   const match = /github\.com[:/]+([A-Za-z0-9._-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(
     remote
   );
-  if (!match) return "unknown/unknown";
+  if (!match) return void 0;
   const hint = `${match[1]}/${match[2]}`;
-  return REPOSITORY_HINT_PATTERN.test(hint) ? hint : "unknown/unknown";
+  return REPOSITORY_HINT_PATTERN.test(hint) ? hint : void 0;
+}
+function repositoryHints(cwd = process.cwd()) {
+  const names = git(cwd, ["remote"])?.split("\n").filter((name) => name.length > 0) ?? [];
+  const ordered = ["origin", ...names.filter((name) => name !== "origin")];
+  const hints = [];
+  for (const name of ordered) {
+    const url = git(cwd, ["remote", "get-url", name]);
+    const hint = url === void 0 ? void 0 : ownerName(url);
+    if (hint !== void 0 && !hints.some((h) => h.toLowerCase() === hint.toLowerCase()))
+      hints.push(hint);
+  }
+  return hints;
 }
 
-// src/quiet.ts
-import { execFileSync as execFileSync3 } from "node:child_process";
-import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync6, realpathSync } from "node:fs";
+// src/self-update.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "node:fs";
 import { join as join6 } from "node:path";
-var EMPTY2 = { schemaVersion: 1, folders: [], remotes: [] };
-function quietPath(environment = process.env) {
-  return join6(configHome(environment), "quiet.json");
+var STAMP = "self-update.json";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function stampPath(environment) {
+  return join6(configHome(environment), STAMP);
 }
-function readQuiet(environment = process.env) {
-  const path = quietPath(environment);
-  if (!existsSync3(path)) return EMPTY2;
+function lastStarted(environment) {
+  const path = stampPath(environment);
+  if (!existsSync3(path)) return 0;
   try {
     const parsed = JSON.parse(readFileSync6(path, "utf8"));
-    if (parsed.schemaVersion !== 1) return EMPTY2;
-    return {
-      schemaVersion: 1,
-      folders: Array.isArray(parsed.folders) ? parsed.folders.filter(isString) : [],
-      remotes: Array.isArray(parsed.remotes) ? parsed.remotes.filter(isString) : []
-    };
+    return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
   } catch {
-    return EMPTY2;
+    return 0;
   }
 }
-var isString = (value) => typeof value === "string";
-function folderKey(cwd) {
+function detached(command, args) {
+  const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+  child.on("error", () => void 0);
+  child.unref();
+}
+function startSelfUpdateIfDue(newer, deps) {
+  if (newer === void 0) return false;
+  const now = deps.now ?? Date.now;
+  if (now() - lastStarted(deps.environment) < DAY_MS) return false;
   try {
-    return realpathSync(
-      execFileSync3("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-        timeout: 1e3
-      }).trim()
+    mkdirSync5(configHome(deps.environment), { recursive: true, mode: 448 });
+    writeFileSync3(
+      stampPath(deps.environment),
+      JSON.stringify({ startedAt: now(), toward: newer }) + "\n",
+      { mode: 384 }
     );
+    (deps.run ?? detached)("npx", ["-y", HOOK_SPECIFIER, "install", "--json"]);
+    return true;
   } catch {
-    return realpathSync(cwd);
+    return false;
   }
 }
-function isQuiet(cwd, environment = process.env) {
-  const list = readQuiet(environment);
-  const folder = folderKey(cwd);
-  const remote = repositoryHint(cwd);
-  return list.folders.includes(folder) || remote !== "unknown/unknown" && list.remotes.some((r) => r.toLowerCase() === remote.toLowerCase());
-}
 
 // src/commands/guidance.ts
-function untrackedLine(remote) {
-  const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
-  return `${here} isn't tracked by Balladeer, so promises can't be tracked from here. To track it, run \`npx -y ${PUBLISHED_SPECIFIER} setup\` in this folder. To stop this message here, run \`npx -y ${PUBLISHED_SPECIFIER} quiet\` (or \`quiet --repo\` for the whole repository).`;
-}
 function readInput(stream) {
   return new Promise((resolve2, reject) => {
     let bytes = 0;
@@ -3065,14 +3114,12 @@ async function runGuidance(options) {
         credentials,
         options.controlPlane,
         void 0,
-        repositoryHint(options.cwd)
+        repositoryHints(options.cwd)
       );
       return selection.kind === "refused" ? [] : [selection.agent];
     })();
     if (agents.length !== 1 || !agents[0]) {
       if (projectScoped) throw new Error("guidance_connection_unavailable");
-      if (event === "SessionStart" && !isQuiet(options.cwd, options.environment))
-        emit(untrackedLine(repositoryHint(options.cwd)));
       return 0;
     }
     const loaded = await loadGuidance({
@@ -3081,6 +3128,12 @@ async function runGuidance(options) {
       timeoutMs: 750,
       ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
     });
+    if (event === "SessionStart")
+      startSelfUpdateIfDue(newerVersionPublished(), {
+        environment: options.environment,
+        ...options.startUpdate ? { run: options.startUpdate } : {},
+        ...options.now ? { now: options.now } : {}
+      });
     const sessionId = identifier(record.session_id);
     const agentId = identifier(record.agent_id);
     recordGuidanceContext(

package/dist/guidance.js

@@ -1,3 +1,4 @@
+import { noteServerVersion } from "./currency.js";
 import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
 import { createHash, randomBytes } from "node:crypto";
 import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
@@ -182,6 +183,9 @@ export async function loadGuidance(input) {
                     ...(previous ? { "if-none-match": previous.etag } : {}),
                 },
             });
+            // The server names the newest published release on every answer; the
+            // hook is where a laptop learns it is behind, and never where it waits.
+            noteServerVersion(response.headers);
             if (response.status === 304) {
                 if (!previous ||
                     response.headers.get("etag") !== previous.etag ||

package/dist/install.d.ts

@@ -21,5 +21,7 @@ export declare function runInstall(options: InstallOptions & {
     allowPartial?: boolean;
     /** Carried into the one JSON object this prints, never as a second line. */
     extra?: Record<string, unknown>;
+    /** Told the durable command's path once it is installed, before the report. */
+    onInstalled?: (result: InstallResult) => Record<string, unknown> | undefined;
 }): number;
 export {};

package/dist/install.js

@@ -333,6 +333,7 @@ export function ensureInstalled(options) {
 export function runInstall(options) {
     try {
         const result = ensureInstalled(options);
+        const more = options.onInstalled?.(result) ?? {};
         const message = result.manualPathRequired
             ? `Balladeer is installed at ${result.command}. Add ${dirname(result.command)} to your shell PATH and reopen the terminal/coding agent. Automatic PATH editing is unavailable for this shell; this setup process can use the command now.`
             : result.restartRequired
@@ -345,6 +346,7 @@ export function runInstall(options) {
                 status: result.manualPathRequired ? "path_pending" : result.status,
                 message,
                 ...(options.extra ?? {}),
+                ...more,
             }) + "\n"
             : message + "\n");
         return result.manualPathRequired && !options.allowPartial ? 4 : 0;

package/dist/open-browser.d.ts

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+/**
+ * Open a page in the person's default browser, and say whether it was asked.
+ *
+ * Setup's one link used to be copied by hand from the terminal into a browser,
+ * which is the step a person at a keyboard does not want and an agent shell
+ * cannot do at all. So this runs only when a person is there (the caller
+ * checks the terminal), hands the URL to the operating system's own opener,
+ * and does not wait for it: a browser that never appears is reported by the
+ * link staying on screen, never by this command hanging. Nothing here reads
+ * the page or learns what happened in it.
+ */
+export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: typeof spawn): boolean;

package/dist/open-browser.js

@@ -0,0 +1,30 @@
+import { spawn } from "node:child_process";
+/**
+ * Open a page in the person's default browser, and say whether it was asked.
+ *
+ * Setup's one link used to be copied by hand from the terminal into a browser,
+ * which is the step a person at a keyboard does not want and an agent shell
+ * cannot do at all. So this runs only when a person is there (the caller
+ * checks the terminal), hands the URL to the operating system's own opener,
+ * and does not wait for it: a browser that never appears is reported by the
+ * link staying on screen, never by this command hanging. Nothing here reads
+ * the page or learns what happened in it.
+ */
+export function openInBrowser(url, platform = process.platform, run = spawn) {
+    if (!/^https:\/\//.test(url))
+        return false;
+    const [command, args] = platform === "darwin"
+        ? ["open", [url]]
+        : platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = run(command, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/release.d.ts

@@ -8,6 +8,12 @@
 export declare const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";
 /** The specifier every published surface names, which is a tag and never a pin. */
 export declare const PUBLISHED_SPECIFIER = "balladeer@latest";
+/**
+ * What a hook or MCP entry runs when no durable command is installed: the
+ * current major, so a 2.x is a choice a person makes and never a surprise at
+ * session start. The typed first command stays `@latest`.
+ */
+export declare const HOOK_SPECIFIER = "balladeer@1";
 /**
  * How to invoke this command, with no subcommand attached.
  *

package/dist/release.js

@@ -10,6 +10,12 @@ import { fileURLToPath } from "node:url";
 export const CHECKOUT_COMMAND = "node packages/cli/dist/cli.js";
 /** The specifier every published surface names, which is a tag and never a pin. */
 export const PUBLISHED_SPECIFIER = "balladeer@latest";
+/**
+ * What a hook or MCP entry runs when no durable command is installed: the
+ * current major, so a 2.x is a choice a person makes and never a surprise at
+ * session start. The typed first command stays `@latest`.
+ */
+export const HOOK_SPECIFIER = "balladeer@1";
 /**
  * How to invoke this command, with no subcommand attached.
  *

package/dist/remove-earlier.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Taking the earlier Balladeer off a laptop, so one server answers to the name.
+ *
+ * The July client registered a hosted MCP connector under the same name this
+ * product uses, `balladeer`, at the host's user scope; it installed a capture
+ * hook and a status line, wrote a fenced guidance block into the person's own
+ * CLAUDE.md and Codex AGENTS.md, dropped a managed BALLADEER.md beside them, and
+ * put a 0.x `balladeer` binary on PATH through Volta. Left in place, `/mcp`
+ * shows the old server with its 22 tools and this product's user-scope install
+ * refuses to write over a `balladeer` entry that is not its own, so the person
+ * sees the old Balladeer and never the new one.
+ *
+ * Every removal here proves ownership from the entry itself, the way the older
+ * client's own uninstall did: an HTTP connector under the reserved key, a hook
+ * that runs its capture script, a status line that names balladeer, the fence
+ * markers it wrote, the managed-by header. Anything else in those files is not
+ * touched. Each file is copied beside itself before it is changed, and the
+ * copy's path is reported, so the whole thing reverses by hand in a minute.
+ * The old binary is removed only through Volta, which is how it was installed,
+ * and only when the shim reports a version before 1.0.0.
+ */
+export type EarlierItem = Readonly<{
+    /** The file, in the form a person can go and open. */
+    path: string;
+    /** What was found there, bounded. */
+    found: string;
+    /** Takes it off. Returns the backup path when a file was changed. */
+    remove: () => string | undefined;
+}>;
+/** The git top level of a folder, or nothing when it is not inside a repository. */
+export declare function repositoryRootOf(cwd: string): string | undefined;
+/**
+ * The sentence the terminal and the day-one documents share about the earlier
+ * client, so a person who read ahead and a person who hits it are told one thing.
+ */
+export declare const EARLIER_INSTRUCTION = "If you used the earlier Balladeer on this machine, setup finds it, copies each file it changes beside itself, and removes the old server, hooks and guidance blocks (under your home and in this repository's own CLAUDE.md or AGENTS.md, where you commit the change) before pairing; `balladeer remove-earlier` does the same on its own.";
+/**
+ * What the older client left in the repository the person is standing in: a
+ * fence in its CLAUDE.md or AGENTS.md, a managed BALLADEER.md, or its Cursor
+ * rule. Committed once, these reach every clone and every teammate, which is
+ * why the home directory alone is not enough.
+ */
+export declare function findEarlierInRepository(root: string, now?: () => Date): EarlierItem[];
+export declare function findEarlier(options: {
+    home: string;
+    controlPlane: string;
+    environment: NodeJS.ProcessEnv;
+    /** The folder the command runs in; its repository is searched too. */
+    cwd?: string;
+    now?: () => Date;
+}): EarlierItem[];
+export type RemovalReport = Readonly<{
+    removed: readonly {
+        path: string;
+        found: string;
+        backup?: string;
+    }[];
+    failed: readonly {
+        path: string;
+        found: string;
+        reason: string;
+    }[];
+}>;
+/** Takes everything found off, one item at a time, and says what happened to each. */
+export declare function removeEarlier(items: readonly EarlierItem[]): RemovalReport;
+/** What a person reads, before and after. */
+export declare function describeEarlier(items: readonly EarlierItem[]): string[];
+export declare function describeRemoval(report: RemovalReport): string[];