balladeer 1.0.20 → 1.0.21

package/dist/commands/mcp.d.ts

@@ -1,3 +1,4 @@
+import { type SelfUpdateDeps } from "../self-update.js";
 import { type StoredAgent } from "../store.js";
 export { forwarderHeaders, selectAgent, type AgentSelection } from "../agent.js";
 export type McpOptions = Readonly<{
@@ -15,6 +16,9 @@ export type McpOptions = Readonly<{
     stdin: NodeJS.ReadableStream;
     write: (text: string) => void;
     error: (text: string) => void;
+    now?: () => number;
+    /** Runs the background update; injected so tests never reach npm. */
+    startUpdate?: SelfUpdateDeps["run"];
 }>;
 export type ProbeResult = Readonly<{
     kind: "answered";

package/dist/commands/mcp.js

@@ -1,10 +1,11 @@
 import { createInterface } from "node:readline";
 import { callAgentTool, forwarderHeaders, noAgentCredentialSentence, safeJson, selectAgent, structuredString, updateLine, } from "../agent.js";
-import { noteServerVersion, updateNotice } from "../currency.js";
+import { newerVersionPublished, noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
 import { CLI_VERSION } from "../wire.js";
 import { untrackedLine } from "./guidance.js";
 import { hooksAwaitingTrust, hooksAwaitingTrustNotice, trustingHost } from "../hook-trust.js";
+import { startSelfUpdateIfDue } from "../self-update.js";
 import { StoreError, readCredentials } from "../store.js";
 // The three commands that use an agent connection select and address it through
 // one module. These are re-exported because this is where the forwarder's
@@ -12,6 +13,8 @@ import { StoreError, readCredentials } from "../store.js";
 export { forwarderHeaders, selectAgent } from "../agent.js";
 const MAX_REQUEST_BYTES = 1024 * 1024;
 const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** How often one long-running forwarder looks at whether an update is due. */
+const UPDATE_CHECK_MS = 60 * 60 * 1000;
 /**
  * One real call over the connection just issued, before anything claims it
  * works.
@@ -195,6 +198,8 @@ export async function runMcp(options) {
     // user-scope hook had just switched off. It installs nothing now.
     const { agent } = selection;
     let saidUpdate = false;
+    let updateCheckedAt = Number.NEGATIVE_INFINITY;
+    const clock = options.now ?? Date.now;
     // Which host this session belongs to is known from its hello; whether its
     // hooks are waiting for the person's trust is asked at the first tool call,
     // by which time a trusted session-start hook has certainly run.
@@ -230,6 +235,24 @@ export async function runMcp(options) {
             saidUpdate = true;
             options.error(`${notice}\n`);
         }
+        // The guidance hook is not the only way in. Codex skips a hook nobody has
+        // trusted, and a Codex-only laptop (Luke's, at Didero) then never started
+        // an update at all, while this forwarder ran every session. So the
+        // forwarder starts the same background install, under the same stamp,
+        // looking at most once an hour however many frames pass.
+        if (newerVersionPublished() !== undefined && clock() - updateCheckedAt >= UPDATE_CHECK_MS) {
+            updateCheckedAt = clock();
+            try {
+                startSelfUpdateIfDue(newerVersionPublished(), {
+                    environment: options.environment,
+                    now: clock,
+                    ...(options.startUpdate ? { run: options.startUpdate } : {}),
+                });
+            }
+            catch {
+                /* An update that cannot even be considered never costs the session its tools. */
+            }
+        }
         if (response.status === 401) {
             options.write(`${revokedConnectionFrame(frameId(line), options.controlPlane)}\n`);
             options.error("Balladeer refused this agent connection. Rotate it in Balladeer.\n");

package/dist/currency.js

@@ -60,10 +60,16 @@ export function noteServerVersion(headers) {
     newestSeen = newest;
     const advice = headers.get(CLI_ADVICE_HEADER);
     const line = advice === null ? "" : bounded(advice);
+    // On this copy's own major the background update installs it (it lands
+    // from 1.0.21), so there is nothing to tell anyone to run. Another major
+    // is a choice a person makes.
+    const sameMajor = newest.split(".")[0] === CLI_VERSION.split(".")[0];
     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;
+        line !== ""
+            ? line
+            : sameMajor
+                ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). It installs in the background; nothing needs to be run.`
+                : `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.`;
 }
 /** The one line this run prints about itself, or nothing when it is current. */
 export function updateNotice() {

package/dist/guidance-hook.mjs

@@ -2152,7 +2152,7 @@ function relayHook(input, directory) {
 }
 
 // src/wire.ts
-var CLI_VERSION = "1.0.20";
+var CLI_VERSION = "1.0.21";
 var CLIENT_HEADER = "x-balladeer-client";
 var UPDATE_STATE_HEADER = "x-balladeer-update-state";
 var HOOK_HOST_HEADER = "x-balladeer-hook";
@@ -2289,7 +2289,8 @@ function noteServerVersion(headers) {
   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;
+  const sameMajor = newest.split(".")[0] === CLI_VERSION.split(".")[0];
+  notice = line !== "" ? line : sameMajor ? `A newer Balladeer is available (${newest}; this is ${CLI_VERSION}). It installs in the background; nothing needs to be run.` : `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.`;
 }
 function newerVersionPublished() {
   return newestSeen;
@@ -2334,6 +2335,13 @@ function due(newer, last, now) {
   const newerTarget = last.toward === void 0 || older(last.toward, newer);
   return newerTarget && since >= HOUR_MS;
 }
+function updateSpecifier(newer) {
+  if (!VERSION2.test(newer)) return void 0;
+  const [name, major] = HOOK_SPECIFIER.split("@");
+  if (newer.split(".")[0] !== major) return void 0;
+  if (!older(CLI_VERSION, newer)) return void 0;
+  return `${name}@${newer}`;
+}
 function writePrivate(path, value, environment) {
   mkdirSync3(configHome(environment), { recursive: true, mode: 448 });
   writeFileSync2(path, JSON.stringify(value) + "\n", { mode: 384 });
@@ -2375,9 +2383,11 @@ function detached(command, args, environment) {
 }
 function startSelfUpdateIfDue(newer, deps) {
   if (newer === void 0) return false;
+  const specifier = updateSpecifier(newer);
+  if (specifier === void 0) return false;
   const now = deps.now ?? Date.now;
   if (!due(newer, lastAttempt(deps.environment), now())) return false;
-  const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
+  const launch = resolveLaunch(specifier, deps.environment, deps.execPath, deps.exists);
   let started;
   try {
     started = (deps.run ?? detached)(launch.command, launch.args, launch.environment) !== false;

package/dist/self-update.d.ts

@@ -16,6 +16,15 @@ export type SelfUpdateDeps = Readonly<{
 }>;
 /** A short, closed vocabulary: it travels in a header and lands in a column. */
 export type SelfUpdateState = `started:${string}` | `unstartable:${string}` | `installed:${string}` | `failed:${string}`;
+/**
+ * The exact release to ask npx for, or nothing when there is none to ask for.
+ *
+ * Exact, because a range is answered from whatever copy is already on the
+ * laptop (see above). Only a release on this copy's own major, so a 2.x stays a
+ * choice a person makes, and only one newer than this copy, so a server that
+ * names an older number cannot walk a laptop backwards.
+ */
+export declare function updateSpecifier(newer: string): string | undefined;
 /** What the last attempt came to, for the next hook fire to report. Never throws. */
 export declare function recordSelfUpdateState(environment: NodeJS.ProcessEnv, state: SelfUpdateState, at: number): void;
 /** The recorded state, or nothing when none was written or it is not one of ours. */

package/dist/self-update.js

@@ -4,6 +4,7 @@ import { delimiter, dirname, join } from "node:path";
 import { older } from "./currency.js";
 import { HOOK_SPECIFIER } from "./release.js";
 import { configHome } from "./store.js";
+import { CLI_VERSION } from "./wire.js";
 /**
  * Bringing the durable command current without the session ever waiting.
  *
@@ -35,6 +36,18 @@ import { configHome } from "./store.js";
  * 1.0.15. Now any guidance hook fire can begin the install, and a release
  * newer than the one the last attempt aimed at may begin one an hour after
  * it, rather than a day.
+ *
+ * What changed on 14 October 2026, from Didero's laptops and Robert's again:
+ * seven laptops sat on 1.0.12 to 1.0.14 for two weeks, and Robert's on 1.0.19
+ * with an attempt toward 1.0.20 "started" that morning. Every attempt had
+ * asked npx for `balladeer@1`, a range. npx runs any copy already on the
+ * laptop that satisfies a range without asking the registry: the durable
+ * command itself when it sits in npm's global folder, or whatever the first
+ * attempt left in npx's own cache. That copy's installer installs its own
+ * version and refuses to go down, so every attempt after the first changed
+ * nothing, silently, once a day. Now the attempt names the exact release the
+ * server announced, which npx cannot satisfy from an older copy, and the
+ * installer that runs is the one being installed.
  */
 const STAMP = "self-update.json";
 const STATE = "self-update-state.json";
@@ -79,6 +92,24 @@ function due(newer, last, now) {
     const newerTarget = last.toward === undefined || older(last.toward, newer);
     return newerTarget && since >= HOUR_MS;
 }
+/**
+ * The exact release to ask npx for, or nothing when there is none to ask for.
+ *
+ * Exact, because a range is answered from whatever copy is already on the
+ * laptop (see above). Only a release on this copy's own major, so a 2.x stays a
+ * choice a person makes, and only one newer than this copy, so a server that
+ * names an older number cannot walk a laptop backwards.
+ */
+export function updateSpecifier(newer) {
+    if (!VERSION.test(newer))
+        return undefined;
+    const [name, major] = HOOK_SPECIFIER.split("@");
+    if (newer.split(".")[0] !== major)
+        return undefined;
+    if (!older(CLI_VERSION, newer))
+        return undefined;
+    return `${name}@${newer}`;
+}
 function writePrivate(path, value, environment) {
     mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
     writeFileSync(path, JSON.stringify(value) + "\n", { mode: 0o600 });
@@ -148,10 +179,13 @@ function detached(command, args, environment) {
 export function startSelfUpdateIfDue(newer, deps) {
     if (newer === undefined)
         return false;
+    const specifier = updateSpecifier(newer);
+    if (specifier === undefined)
+        return false;
     const now = deps.now ?? Date.now;
     if (!due(newer, lastAttempt(deps.environment), now()))
         return false;
-    const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
+    const launch = resolveLaunch(specifier, deps.environment, deps.execPath, deps.exists);
     let started;
     try {
         started = (deps.run ?? detached)(launch.command, launch.args, launch.environment) !== false;

package/dist/wire.d.ts

@@ -5,14 +5,14 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.20";
+export declare const CLI_VERSION = "1.0.21";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
 /** What the last background update came to: `started:1.0.17`, `installed:1.0.17`, `failed:exit-1`, `unstartable:launcher`. */
 export declare const UPDATE_STATE_HEADER = "x-balladeer-update-state";
 /** Which host's hook made this guidance fetch: `claude` or `codex`. */
 export declare const HOOK_HOST_HEADER = "x-balladeer-hook";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.20";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.21";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.20";
+export const CLI_VERSION = "1.0.21";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 /** What the last background update came to: `started:1.0.17`, `installed:1.0.17`, `failed:exit-1`, `unstartable:launcher`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "balladeer",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,