balladeer 1.0.8 → 1.0.12

package/dist/commands/setup.js

@@ -12,16 +12,18 @@ 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 { 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";
 import { probeAgentConnection } from "./mcp.js";
 const REFUSAL_SENTENCE = "It may not agree to what a promise means, agree a change to what a promise means, grant an exception, transfer ownership, supersede, retire, or offboard anything.";
 const MAX_WAIT_MS = 10 * 60 * 1000;
+const AGENT_WAIT_MS = 90 * 1000;
 /** The bound the control plane's own name check holds, refused here so a name
  * nobody could create never costs a pairing code. */
 export const CREATE_WORKSPACE_MAX_LENGTH = 120;
@@ -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
+            ? `  FOR THE PERSON AT THIS LAPTOP: a browser tab has opened at ${approvalUri}. Click Approve there. If no tab appeared, open that link yourself.`
+            : `  FOR THE PERSON AT THIS LAPTOP: open ${approvalUri} in your browser and click Approve.`,
         `  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
+            ? "  This command waits here for the approval and finishes on its own; if it returns first, run it again to finish."
+            : "  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);
@@ -272,11 +296,23 @@ export async function runSetup(options) {
     say(options, `Balladeer setup, version ${CLI_VERSION}.\n`);
     say(options, `Agent client: ${options.client === "codex" ? "Codex" : "Claude"}. Use --client codex or --client claude to choose.`);
     emit(options, { step: "explain", version: CLI_VERSION });
-    say(options, explainText(controlPlane));
     const chosen = chooseRepositories(namedRepositories(options), options.cwd);
     if (chosen.kind === "mismatch") {
         return fail(options, "repository_mismatch", chosen.message, 4);
     }
+    // Where this run is, said before anything else. People paste this command
+    // into an agent whose shell may be in no repository at all; the run still
+    // pairs the laptop, and the first line says what it will and will not do.
+    const inCheckout = repositoryHint(options.cwd) !== "unknown/unknown";
+    if (!inCheckout && (options.repositories ?? []).length === 0)
+        say(options, "This folder isn't a repository checkout. This run pairs this laptop and installs Balladeer for every session; to connect a repository, run this same command inside a checkout of it afterwards.");
+    // The boundary explanation is for a person reading a terminal. An agent
+    // shell gets one line and `balladeer explain`, so the approval link is the
+    // first actionable thing it sees and relays.
+    if (options.interactive === true)
+        say(options, explainText(controlPlane));
+    else
+        say(options, "What Balladeer can and cannot see, and what this run does: `balladeer explain`.");
     // Before the pairing is started, not after: a name the control plane would
     // refuse must cost nobody a code they then have to abandon, and this run has
     // sent nothing yet.
@@ -371,7 +407,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 +417,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 +459,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 +469,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,11 +602,32 @@ 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) {
+    // An agent's shell is still on the person's laptop, so the page can open
+    // there too; only --json and --no-open keep it closed.
+    // Only an opener the entry point handed over is used: a test, or any
+    // caller that passed none, never reaches a browser and never waits.
+    if (options.json || !options.openLink)
+        return false;
+    return options.openLink(url);
+}
+/** How long a run waits for the click: a person at a terminal has ten
+ * minutes; an agent's shell, whose tool may cut the command at two, gets
+ * ninety seconds and the pairing is saved either way. */
+function waitBudgetMs(options) {
+    return options.interactive === true ? MAX_WAIT_MS : AGENT_WAIT_MS;
+}
 async function waitForApproval(options, credentials, pending, pollIntervalSeconds) {
     const sleep = options.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
     const now = options.now ?? (() => new Date());
-    const deadline = now().getTime() + MAX_WAIT_MS;
-    say(options, `  Waiting up to ${MAX_WAIT_MS / 60_000} minutes for someone to approve ${pending.userCode} at ${approvalLink(options, pending.verificationUri)}. Press Ctrl+C to stop; the pairing is saved either way, and the code stays approvable until ${formatInstant(pending.expiresAt)}.`);
+    const budget = waitBudgetMs(options);
+    const deadline = now().getTime() + budget;
+    say(options, `  Waiting up to ${budget >= 60_000 ? `${budget / 60_000} minutes` : `${budget / 1000} seconds`} for someone to approve ${pending.userCode} at ${approvalLink(options, pending.verificationUri)}. Press Ctrl+C to stop; the pairing is saved either way, and the code stays approvable until ${formatInstant(pending.expiresAt)}.`);
     let interval = pollIntervalSeconds;
     while (now().getTime() < deadline) {
         await sleep(Math.max(interval, 2) * 1000);
@@ -599,6 +658,15 @@ function refusalSentence(error) {
     return error instanceof Error ? error.message : String(error);
 }
 async function runRemainingSteps(options, credentials, session) {
+    // Said to a JSON reader here, after the pairing object, so the step order
+    // every caller relies on is unchanged; a person read it as the first line.
+    if (repositoryHint(options.cwd) === "unknown/unknown" &&
+        (options.repositories ?? []).length === 0)
+        emit(options, {
+            step: "warning",
+            code: "not_in_checkout",
+            message: "This folder isn't a repository checkout; this run paired the laptop and installed Balladeer for every session, and connects no repository.",
+        });
     let state;
     try {
         state = await request(options.controlPlane, {
@@ -1676,7 +1744,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.12";
 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, environment?: NodeJS.ProcessEnv): boolean;

package/dist/open-browser.js

@@ -0,0 +1,35 @@
+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, environment = process.env) {
+    if (!/^https:\/\//.test(url))
+        return false;
+    // A Linux box with no display (a CI runner, a server over SSH) has nowhere
+    // to open a page, and saying it opened one would make the run wait for a
+    // click that cannot come.
+    if (platform === "linux" && !environment.DISPLAY && !environment.WAYLAND_DISPLAY)
+        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.
  *