balladeer 1.0.14 → 1.0.15

package/dist/cli.js

@@ -21,9 +21,11 @@ import { runWhoami } from "./commands/whoami.js";
 import { runInstall } from "./install.js";
 import { openInBrowser } from "./open-browser.js";
 import { PUBLISHED_SPECIFIER } from "./release.js";
-import { installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
+import { CODEX_HOOK_APPROVAL, installUserScope, runningFromCheckout, userHome, } from "./user-scope.js";
 import { updateNotice } from "./currency.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "./remove-earlier.js";
+import { recordSelfUpdateState, SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
+import { hooksAwaitingTrust } from "./hook-trust.js";
 import { describeCheckoutFormRemoval, findCheckoutForm, removeCheckoutForm, } from "./checkout-form.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
@@ -472,6 +474,19 @@ function installEverything(options) {
     for (const w of writes ?? [])
         if (!options.json)
             options.write(`${w.status === "refused" ? "Not changed" : w.status === "written" ? "Registered" : "Already current"}: ${w.path}${w.reason ? ` (${w.reason})` : ""}\n`);
+    // Codex runs a hook only once the person has trusted it, and trusts it by
+    // the hash of its definition, so a hook this command just wrote or changed
+    // is skipped until they do. Found 29 September 2026: Codex was the most
+    // common host at Didero and not one of its sessions had run the hook.
+    const codex = (writes ?? []).find((w) => w.host === "codex" && w.status !== "refused");
+    // Said whenever it is true, which is after any install that wrote or changed
+    // the hooks and until Codex has run one of them; silent once it has.
+    if (codex !== undefined && hooksAwaitingTrust(process.env, "codex")) {
+        if (options.json)
+            options.write(`${JSON.stringify({ step: "codex_hooks", approval: codex.status === "written" ? "required" : "check", command: "/hooks" })}\n`);
+        else
+            options.write(`${CODEX_HOOK_APPROVAL}\n`);
+    }
     // With the user-scope form in place, the older per-repository form in this
     // checkout only makes the session hear the guidance twice. Out it goes, with
     // a copy beside any file git does not already keep.
@@ -493,7 +508,12 @@ function installEverything(options) {
         options.write("Balladeer now runs in every Claude Code" +
             ((writes ?? []).some((w) => w.host === "codex") ? " and Codex" : "") +
             " session on this machine. In a folder of a connected repository it works as before; anywhere else it stays quiet, and `balladeer status` there says why.\n");
-    return (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
+    const outcome = (writes ?? []).some((w) => w.status === "refused") ? 4 : code;
+    // Started by the session hook's background update: leave how it ended where
+    // the next hook fire will find it and tell the server.
+    if (process.env[SELF_UPDATE_ENVIRONMENT] === "1")
+        recordSelfUpdateState(process.env, outcome === 0 ? `installed:${CLI_VERSION}` : `failed:exit-${outcome}`, Date.now());
+    return outcome;
 }
 async function dispatch(parsed, write) {
     switch (parsed.command) {

package/dist/commands/guidance.d.ts

@@ -15,7 +15,7 @@ export type GuidanceOptions = Readonly<{
     fetchImpl?: typeof fetch;
     now?: () => number;
     /** Runs the background update; injected so tests never reach npm. */
-    startUpdate?: (command: string, args: readonly string[]) => void;
+    startUpdate?: (command: string, args: readonly string[], environment: NodeJS.ProcessEnv) => boolean | void;
 }>;
 /** Hook stdout is bounded context only. Host prompts and transcript paths never leave this process. */
 export declare function runGuidance(options: GuidanceOptions): Promise<number>;

package/dist/commands/guidance.js

@@ -5,6 +5,7 @@ import { selectAgent } from "../agent.js";
 import { repositoryHints } from "../repository.js";
 import { newerVersionPublished } from "../currency.js";
 import { startSelfUpdateIfDue } from "../self-update.js";
+import { noteHookFired } from "../hook-trust.js";
 /** A repository-specific setup step for explicit status and empty-catalog responses. */
 export function untrackedLine(remote) {
     const here = remote === "unknown/unknown" ? "This folder" : `This folder (${remote})`;
@@ -98,10 +99,15 @@ export async function runGuidance(options) {
             // Unconnected folders stay silent. An explicit status request explains setup.
             return 0;
         }
+        // A hook that runs has been trusted by its host; hosts that ask for that
+        // trust are the ones this matters to.
+        if (options.hook === "codex")
+            noteHookFired(options.environment, "codex");
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
             timeoutMs: 750,
+            hook: options.hook,
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
         // Behind? Start the install in the background, once a day at most, and

package/dist/commands/mcp.d.ts

@@ -63,3 +63,9 @@ export declare function staleClientFrame(id: unknown, update: string): string;
  */
 export declare function revokedConnectionFrame(id: unknown, controlPlane: string): string;
 export declare function runMcp(options: McpOptions): Promise<number>;
+/**
+ * The tool's answer with one more text block at its end, or nothing when the
+ * answer is not a single tool result this can add to: a batch, an error frame,
+ * or anything it cannot parse is forwarded exactly as it came.
+ */
+export declare function withNotice(text: string, notice: string): string | undefined;

package/dist/commands/mcp.js

@@ -5,6 +5,7 @@ import { noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
 import { CLI_VERSION } from "../wire.js";
 import { untrackedLine } from "./guidance.js";
+import { HOOKS_AWAITING_TRUST_NOTICE, hooksAwaitingTrust, trustingHost } from "../hook-trust.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
@@ -198,6 +199,11 @@ export async function runMcp(options) {
     if (guidanceInstall.status !== "not_applicable")
         options.error(`Balladeer guidance loader: ${guidanceInstall.status}${guidanceInstall.reason ? ` (${guidanceInstall.reason})` : ""}. New project hooks may need host trust; no trust is assumed.\n`);
     let saidUpdate = false;
+    // 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.
+    let host;
+    let saidTrust = false;
     const lines = createInterface({ input: options.stdin, crlfDelay: Infinity });
     for await (const line of lines) {
         if (line.trim().length === 0)
@@ -247,7 +253,54 @@ export async function runMcp(options) {
             options.error("Balladeer refused a response frame larger than 4 MiB.\n");
             return 5;
         }
+        const request = frameOf(line);
+        if (request?.method === "initialize")
+            host = trustingHost(request.params?.clientInfo?.name);
+        if (!saidTrust &&
+            host !== undefined &&
+            request?.method === "tools/call" &&
+            hooksAwaitingTrust(options.environment, host)) {
+            const noted = withNotice(text, HOOKS_AWAITING_TRUST_NOTICE);
+            if (noted !== undefined) {
+                saidTrust = true;
+                options.write(`${noted}\n`);
+                continue;
+            }
+        }
         options.write(`${text.replace(/\n+$/, "")}\n`);
     }
     return 0;
 }
+function frameOf(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The tool's answer with one more text block at its end, or nothing when the
+ * answer is not a single tool result this can add to: a batch, an error frame,
+ * or anything it cannot parse is forwarded exactly as it came.
+ */
+export function withNotice(text, notice) {
+    try {
+        const frame = JSON.parse(text);
+        if (frame === null || typeof frame !== "object" || Array.isArray(frame))
+            return undefined;
+        const content = frame.result?.content;
+        if (!Array.isArray(content))
+            return undefined;
+        return JSON.stringify({
+            ...frame,
+            result: { ...frame.result, content: [...content, { type: "text", text: notice }] },
+        });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/guidance-hook.mjs

@@ -2027,8 +2027,10 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.14";
+var CLI_VERSION = "1.0.15";
 var CLIENT_HEADER = "x-balladeer-client";
+var UPDATE_STATE_HEADER = "x-balladeer-update-state";
+var HOOK_HOST_HEADER = "x-balladeer-hook";
 var CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 var DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 
@@ -2150,6 +2152,102 @@ function newerVersionPublished() {
   return newestSeen;
 }
 
+// src/self-update.ts
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { delimiter, dirname as dirname2, join as join2 } from "node:path";
+
+// src/release.ts
+var HOOK_SPECIFIER = "balladeer@1";
+
+// src/self-update.ts
+var STAMP = "self-update.json";
+var STATE = "self-update-state.json";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var SELF_UPDATE_ENVIRONMENT = "BALLADEER_SELF_UPDATE";
+var STATE_PATTERN = /^(?:started|unstartable|installed|failed):[A-Za-z0-9._-]{1,40}$/;
+function stampPath(environment) {
+  return join2(configHome(environment), STAMP);
+}
+function statePath(environment) {
+  return join2(configHome(environment), STATE);
+}
+function lastStarted(environment) {
+  const path = stampPath(environment);
+  if (!existsSync(path)) return 0;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+  } catch {
+    return 0;
+  }
+}
+function writePrivate(path, value, environment) {
+  mkdirSync2(configHome(environment), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(value) + "\n", { mode: 384 });
+}
+function recordSelfUpdateState(environment, state, at) {
+  if (!STATE_PATTERN.test(state)) return;
+  try {
+    writePrivate(statePath(environment), { state, at }, environment);
+  } catch {
+  }
+}
+function selfUpdateState(environment) {
+  try {
+    const parsed = JSON.parse(readFileSync2(statePath(environment), "utf8"));
+    return typeof parsed.state === "string" && STATE_PATTERN.test(parsed.state) ? parsed.state : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveLaunch(specifier, environment, execPath = process.execPath, exists = existsSync) {
+  const bin = dirname2(execPath);
+  const tail = ["-y", specifier, "install", "--json"];
+  const child = {
+    ...environment,
+    PATH: [bin, environment.PATH ?? ""].filter((part) => part.length > 0).join(delimiter),
+    [SELF_UPDATE_ENVIRONMENT]: "1"
+  };
+  const script = join2(bin, "..", "lib", "node_modules", "npm", "bin", "npx-cli.js");
+  if (exists(script)) return { command: execPath, args: [script, ...tail], environment: child };
+  const shim = join2(bin, process.platform === "win32" ? "npx.cmd" : "npx");
+  if (exists(shim)) return { command: shim, args: tail, environment: child };
+  return { command: "npx", args: tail, environment: child };
+}
+function detached(command, args, environment) {
+  const child = spawn(command, [...args], { detached: true, stdio: "ignore", env: environment });
+  child.on("error", () => void 0);
+  child.unref();
+  return child.pid !== void 0;
+}
+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;
+  const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
+  let started;
+  try {
+    started = (deps.run ?? detached)(launch.command, launch.args, launch.environment) !== false;
+  } catch {
+    started = false;
+  }
+  if (!started) {
+    recordSelfUpdateState(deps.environment, "unstartable:launcher", now());
+    return false;
+  }
+  try {
+    writePrivate(
+      stampPath(deps.environment),
+      { startedAt: now(), toward: newer },
+      deps.environment
+    );
+  } catch {
+  }
+  recordSelfUpdateState(deps.environment, `started:${newer}`, now());
+  return true;
+}
+
 // src/guidance.ts
 import { createHash, randomBytes } from "node:crypto";
 import {
@@ -2157,14 +2255,14 @@ import {
   closeSync as closeSync2,
   fstatSync,
   lstatSync as lstatSync2,
-  mkdirSync as mkdirSync2,
+  mkdirSync as mkdirSync3,
   openSync as openSync2,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   renameSync as renameSync2,
   unlinkSync as unlinkSync2,
-  writeFileSync
+  writeFileSync as writeFileSync2
 } from "node:fs";
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 var GUIDANCE_UNAVAILABLE = "Balladeer could not verify the current workspace guidance and capture mode. Continue the user's authorized work, but do not make unsolicited capture offers or file inferred promises. Do not reuse earlier Quiet/Thorough permission or cached instructions as current. An explicit request to record still requires current Balladeer tool checks and named-human agreement to meaning; never invent approval. Retry current guidance at the next hook boundary.";
 var HEX = /^[a-f0-9]{64}$/;
 var UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
@@ -2201,7 +2299,7 @@ function readJson(path) {
     fd = openSync2(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.size > MAX_BYTES || (stat.mode & 63) !== 0) return void 0;
-    return JSON.parse(readFileSync2(fd, "utf8"));
+    return JSON.parse(readFileSync3(fd, "utf8"));
   } catch {
     return void 0;
   } finally {
@@ -2210,7 +2308,7 @@ function readJson(path) {
 }
 function privateDirectory(path) {
   try {
-    mkdirSync2(path, { mode: 448 });
+    mkdirSync3(path, { mode: 448 });
   } catch {
   }
   const stat = lstatSync2(path);
@@ -2220,7 +2318,7 @@ function privateDirectory(path) {
 function atomicJson(path, value) {
   const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
   try {
-    writeFileSync(temporary, `${JSON.stringify(value)}
+    writeFileSync2(temporary, `${JSON.stringify(value)}
 `, { flag: "wx", mode: 384 });
     renameSync2(temporary, path);
   } finally {
@@ -2244,16 +2342,16 @@ function guidanceScopeKey(agent) {
 function cacheDirectory(environment) {
   const home = configHome(environment);
   privateDirectory(home);
-  const directory = join2(home, "guidance-v1");
+  const directory = join3(home, "guidance-v1");
   privateDirectory(directory);
   return directory;
 }
 function cached(directory, scopeKey, agent) {
   try {
-    const pointer = readJson(join2(directory, `${scopeKey}.current.json`));
+    const pointer = readJson(join3(directory, `${scopeKey}.current.json`));
     if (!object(pointer) || typeof pointer.key !== "string" || !HEX.test(pointer.key))
       return void 0;
-    const body = readJson(join2(directory, `${pointer.key}.body.json`));
+    const body = readJson(join3(directory, `${pointer.key}.body.json`));
     if (!object(body) || typeof body.etag !== "string" || !/^"[a-f0-9]{64}"$/.test(body.etag))
       return void 0;
     const document = parseGuidance(body.document, agent);
@@ -2291,6 +2389,7 @@ async function loadGuidance(input) {
   } catch {
   }
   const previous = directory ? cached(directory, scopeKey, input.agent) : void 0;
+  const updateState = selfUpdateState(input.environment);
   const abort = new AbortController();
   let timer;
   try {
@@ -2302,6 +2401,10 @@ async function loadGuidance(input) {
         headers: {
           authorization: `Bearer ${input.agent.token}`,
           [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+          // How the last background update ended, so a laptop that cannot
+          // update itself is seen on the scorecard rather than guessed at.
+          ...updateState === void 0 ? {} : { [UPDATE_STATE_HEADER]: updateState },
+          ...input.hook === void 0 ? {} : { [HOOK_HOST_HEADER]: input.hook },
           accept: "application/json",
           ...previous ? { "if-none-match": previous.etag } : {}
         }
@@ -2325,11 +2428,11 @@ async function loadGuidance(input) {
       if (directory) {
         try {
           const key = sha(JSON.stringify([scopeKey, document.revision]));
-          atomicJson(join2(directory, `${key}.body.json`), { document, etag });
-          atomicJson(join2(directory, `${scopeKey}.current.json`), { key });
+          atomicJson(join3(directory, `${key}.body.json`), { document, etag });
+          atomicJson(join3(directory, `${scopeKey}.current.json`), { key });
           if (previous && previous.key !== key) {
             try {
-              unlinkSync2(join2(directory, `${previous.key}.body.json`));
+              unlinkSync2(join3(directory, `${previous.key}.body.json`));
             } catch {
             }
           }
@@ -2357,7 +2460,7 @@ async function loadGuidance(input) {
     if (timer) clearTimeout(timer);
   }
 }
-function recordGuidanceContext(input, write) {
+function recordGuidanceContext(input, write2) {
   const always = input.event !== "UserPromptSubmit" || input.load.status === "unavailable" || !input.sessionId;
   const contextKey = sha(
     JSON.stringify([
@@ -2371,13 +2474,13 @@ function recordGuidanceContext(input, write) {
   let path;
   let emitted = true;
   try {
-    path = join2(cacheDirectory(input.environment), `${contextKey}.context.json`);
+    path = join3(cacheDirectory(input.environment), `${contextKey}.context.json`);
     const previous = readJson(path);
     emitted = always || !object(previous) || previous.status === "unavailable" || previous.digest !== document?.digest || previous.revision !== document?.revision || (previous.runtimeGeneration ?? null) !== (input.runtimeGeneration ?? null);
   } catch {
   }
   if (!emitted) return false;
-  write();
+  write2();
   if (path) {
     try {
       atomicJson(path, {
@@ -2404,50 +2507,45 @@ import {
   closeSync as closeSync5,
   fstatSync as fstatSync2,
   openSync as openSync5,
-  existsSync as existsSync2,
+  existsSync as existsSync3,
   lstatSync as lstatSync4,
   linkSync,
-  mkdirSync as mkdirSync4,
-  readFileSync as readFileSync5,
+  mkdirSync as mkdirSync5,
+  readFileSync as readFileSync6,
   renameSync as renameSync5,
   unlinkSync as unlinkSync5,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
 var import_toml2 = __toESM(require_toml(), 1);
-import { dirname as dirname3, join as join5, relative } from "node:path";
+import { dirname as dirname4, join as join6, relative } from "node:path";
 
 // src/codex-config.ts
 var import_toml = __toESM(require_toml(), 1);
 import {
   closeSync as closeSync4,
-  existsSync,
+  existsSync as existsSync2,
   fsyncSync as fsyncSync3,
   lstatSync as lstatSync3,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   openSync as openSync4,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   renameSync as renameSync4,
   unlinkSync as unlinkSync4,
   writeSync as writeSync3
 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 
 // src/mcp-config.ts
 import {
   closeSync as closeSync3,
   fsyncSync as fsyncSync2,
   openSync as openSync3,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   renameSync as renameSync3,
   unlinkSync as unlinkSync3,
   writeSync as writeSync2
 } from "node:fs";
-import { basename, dirname as dirname2, isAbsolute, join as join3 } from "node:path";
-
-// src/release.ts
-var HOOK_SPECIFIER = "balladeer@1";
-
-// src/mcp-config.ts
+import { basename, dirname as dirname3, isAbsolute, join as join4 } from "node:path";
 var MCP_CONFIG_FILE = ".mcp.json";
 function sameOrigin(left, right) {
   try {
@@ -2490,7 +2588,7 @@ function currentEntry(parsed) {
 }
 function readMcpConfig(repositoryRoot) {
   try {
-    return JSON.parse(readFileSync3(join3(repositoryRoot, MCP_CONFIG_FILE), "utf8"));
+    return JSON.parse(readFileSync4(join4(repositoryRoot, MCP_CONFIG_FILE), "utf8"));
   } catch {
     return void 0;
   }
@@ -2500,7 +2598,7 @@ function readMcpConfig(repositoryRoot) {
 var CODEX_CONFIG_FILE = ".codex/config.toml";
 function readCodexEntry(root) {
   try {
-    const config = (0, import_toml.parse)(readFileSync4(join4(root, CODEX_CONFIG_FILE), "utf8"));
+    const config = (0, import_toml.parse)(readFileSync5(join5(root, CODEX_CONFIG_FILE), "utf8"));
     const servers = config.mcp_servers;
     return servers && typeof servers === "object" && !Array.isArray(servers) && !(servers instanceof Date) ? servers.balladeer : void 0;
   } catch {
@@ -2509,7 +2607,7 @@ function readCodexEntry(root) {
 }
 function hasManagedCodexEntry(root, controlPlane) {
   try {
-    const text = readFileSync4(join4(root, CODEX_CONFIG_FILE), "utf8");
+    const text = readFileSync5(join5(root, CODEX_CONFIG_FILE), "utf8");
     const starts = [...text.matchAll(/^# balladeer:mcp:start\r?$/gm)];
     const ends = [...text.matchAll(/^# balladeer:mcp:end\r?$/gm)];
     if (starts.length !== 1 || ends.length !== 1 || !starts[0] || !ends[0] || starts[0].index >= ends[0].index)
@@ -2853,7 +2951,7 @@ in for them to read. The tool sends nothing itself: an administrator presses Sen
 // src/guidance-install.ts
 var MAX_FILE = 262144;
 function readRegular(path, allowMissing = false, writable = true) {
-  if (!existsSync2(path)) {
+  if (!existsSync3(path)) {
     try {
       lstatSync4(path);
     } catch (e) {
@@ -2864,10 +2962,10 @@ function readRegular(path, allowMissing = false, writable = true) {
   const stat = lstatSync4(path);
   if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE || writable && (stat.mode & 146) === 0)
     throw new Error("file_not_safely_writable");
-  return readFileSync5(path, "utf8");
+  return readFileSync6(path, "utf8");
 }
 function safeParent(root, path) {
-  let at = dirname3(path);
+  let at = dirname4(path);
   while (at !== root) {
     if (relative(root, at).startsWith("..")) throw new Error("outside_repository");
     try {
@@ -2876,7 +2974,7 @@ function safeParent(root, path) {
     } catch (e) {
       if (e.code !== "ENOENT") throw e;
     }
-    at = dirname3(at);
+    at = dirname4(at);
   }
 }
 function validateProjectGuidanceScope(options) {
@@ -2886,7 +2984,7 @@ function validateProjectGuidanceScope(options) {
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 1e3
     }).trim();
-    const path = join5(root, options.hook === "codex" ? ".codex/config.toml" : ".mcp.json");
+    const path = join6(root, options.hook === "codex" ? ".codex/config.toml" : ".mcp.json");
     safeParent(root, path);
     readRegular(path, false, false);
     const entry = options.hook === "codex" ? readCodexEntry(root) : currentEntry(readMcpConfig(root));
@@ -2999,47 +3097,33 @@ function repositoryHints(cwd = process.cwd()) {
   return hints;
 }
 
-// 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 STAMP = "self-update.json";
-var DAY_MS = 24 * 60 * 60 * 1e3;
-function stampPath(environment) {
-  return join6(configHome(environment), STAMP);
-}
-function lastStarted(environment) {
-  const path = stampPath(environment);
-  if (!existsSync3(path)) return 0;
+// src/hook-trust.ts
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { join as join7 } from "node:path";
+var FILE = "hook-trust.json";
+function read(environment) {
   try {
-    const parsed = JSON.parse(readFileSync6(path, "utf8"));
-    return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+    const parsed = JSON.parse(readFileSync7(join7(configHome(environment), FILE), "utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
-    return 0;
+    return {};
   }
 }
-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;
+function write(environment, marks) {
   try {
-    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;
+    mkdirSync6(configHome(environment), { recursive: true, mode: 448 });
+    writeFileSync4(join7(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
+      mode: 384
+    });
   } catch {
-    return false;
   }
 }
+function noteHookFired(environment, host, now = Date.now()) {
+  const marks = read(environment);
+  const mark = marks[host];
+  if (mark?.firedAt !== void 0 && mark.firedAt >= (mark.writtenAt ?? 0)) return;
+  write(environment, { ...marks, [host]: { ...mark, firedAt: now } });
+}
 
 // src/commands/guidance.ts
 function readInput(stream) {
@@ -3118,10 +3202,12 @@ async function runGuidance(options) {
       if (projectScoped) throw new Error("guidance_connection_unavailable");
       return 0;
     }
+    if (options.hook === "codex") noteHookFired(options.environment, "codex");
     const loaded = await loadGuidance({
       agent: agents[0],
       environment: options.environment,
       timeoutMs: 750,
+      hook: options.hook,
       ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
     });
     if (event === "SessionStart")

package/dist/guidance.d.ts

@@ -24,6 +24,8 @@ export declare function loadGuidance(input: {
     environment: NodeJS.ProcessEnv;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
+    /** The host whose hook is asking, so the server can tell a laptop where one host never asks. */
+    hook?: "codex" | "claude";
 }): Promise<GuidanceLoad>;
 /** Writes context first, then records emission metadata; this never claims model receipt. */
 export declare function recordGuidanceContext(input: {

package/dist/guidance.js

@@ -1,5 +1,6 @@
 import { noteServerVersion } from "./currency.js";
-import { CLIENT_HEADER, CLIENT_HEADER_VALUE } from "./wire.js";
+import { CLIENT_HEADER, CLIENT_HEADER_VALUE, HOOK_HOST_HEADER, UPDATE_STATE_HEADER, } from "./wire.js";
+import { selfUpdateState } from "./self-update.js";
 import { createHash, randomBytes } from "node:crypto";
 import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
@@ -168,6 +169,7 @@ export async function loadGuidance(input) {
         /* Cache is optional. */
     }
     const previous = directory ? cached(directory, scopeKey, input.agent) : undefined;
+    const updateState = selfUpdateState(input.environment);
     const abort = new AbortController();
     let timer;
     try {
@@ -179,6 +181,10 @@ export async function loadGuidance(input) {
                 headers: {
                     authorization: `Bearer ${input.agent.token}`,
                     [CLIENT_HEADER]: CLIENT_HEADER_VALUE,
+                    // How the last background update ended, so a laptop that cannot
+                    // update itself is seen on the scorecard rather than guessed at.
+                    ...(updateState === undefined ? {} : { [UPDATE_STATE_HEADER]: updateState }),
+                    ...(input.hook === undefined ? {} : { [HOOK_HOST_HEADER]: input.hook }),
                     accept: "application/json",
                     ...(previous ? { "if-none-match": previous.etag } : {}),
                 },

package/dist/hook-trust.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Knowing when a host has not run the hooks this command last wrote, so the
+ * person is told to approve them whenever that is true, not only at setup.
+ *
+ * Robert, 29 September 2026: hooks will change from release to release, and
+ * most releases arrive through the background update, which says nothing to
+ * anybody. Codex trusts a hook by the hash of its definition and skips a new
+ * or changed one until the person trusts it under /hooks, so a laptop can
+ * update itself into silence. Two small marks settle it without reading
+ * anything of the host's: when this command last wrote a host's hooks, and
+ * when one of that host's hooks last ran. Written after fired means the
+ * current hooks have never run, and the host's own session is where the
+ * person hears it.
+ */
+export type TrustingHost = "codex";
+/** Hosts that run a hook only after the person has approved it. */
+export declare const HOSTS_REQUIRING_TRUST: readonly TrustingHost[];
+/**
+ * This command wrote or changed the host's hooks, or found them in place with
+ * no record that it ever had: either way, from now the host has to have run
+ * them once before anybody assumes it does.
+ */
+export declare function noteHooksWritten(environment: NodeJS.ProcessEnv, host: TrustingHost, changed: boolean, now?: number): void;
+/** One of the host's hooks ran, which it does only once they are trusted. */
+export declare function noteHookFired(environment: NodeJS.ProcessEnv, host: TrustingHost, now?: number): void;
+/** True while the hooks last written for this host have never run in it. */
+export declare function hooksAwaitingTrust(environment: NodeJS.ProcessEnv, host: TrustingHost): boolean;
+/** The host a session belongs to, from the name it gave when it said hello. */
+export declare function trustingHost(clientName: unknown): TrustingHost | undefined;
+/** What the agent is asked to pass on, once, in the host where the approval happens. */
+export declare const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";

package/dist/hook-trust.js

@@ -0,0 +1,63 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configHome } from "./store.js";
+/** Hosts that run a hook only after the person has approved it. */
+export const HOSTS_REQUIRING_TRUST = ["codex"];
+const FILE = "hook-trust.json";
+function read(environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(configHome(environment), FILE), "utf8"));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function write(environment, marks) {
+    try {
+        mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
+        writeFileSync(join(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* A mark that cannot be written costs a notice, never a session. */
+    }
+}
+/**
+ * This command wrote or changed the host's hooks, or found them in place with
+ * no record that it ever had: either way, from now the host has to have run
+ * them once before anybody assumes it does.
+ */
+export function noteHooksWritten(environment, host, changed, now = Date.now()) {
+    const marks = read(environment);
+    if (!changed && marks[host]?.writtenAt !== undefined)
+        return;
+    write(environment, { ...marks, [host]: { ...marks[host], writtenAt: now } });
+}
+/** One of the host's hooks ran, which it does only once they are trusted. */
+export function noteHookFired(environment, host, now = Date.now()) {
+    const marks = read(environment);
+    const mark = marks[host];
+    // Nothing to settle, or already settled: no write on the session's path.
+    if (mark?.firedAt !== undefined && mark.firedAt >= (mark.writtenAt ?? 0))
+        return;
+    write(environment, { ...marks, [host]: { ...mark, firedAt: now } });
+}
+/** True while the hooks last written for this host have never run in it. */
+export function hooksAwaitingTrust(environment, host) {
+    const mark = read(environment)[host];
+    if (mark?.writtenAt === undefined)
+        return false;
+    return mark.firedAt === undefined || mark.firedAt < mark.writtenAt;
+}
+/** The host a session belongs to, from the name it gave when it said hello. */
+export function trustingHost(clientName) {
+    return typeof clientName === "string" && clientName.toLowerCase().startsWith("codex")
+        ? "codex"
+        : undefined;
+}
+/** What the agent is asked to pass on, once, in the host where the approval happens. */
+export const HOOKS_AWAITING_TRUST_NOTICE = "Note from Balladeer on this laptop, to pass on to the person once: Balladeer's hooks here were added or changed and Codex has not run them. Codex runs a hook only after the person trusts it. Ask them to type /hooks in Codex and trust Balladeer's three hooks; until then Codex has Balladeer's tools without its session-start guidance or its updates.";

package/dist/self-update.d.ts

@@ -1,11 +1,38 @@
+/** Set on the child so the install it runs can record how it ended. */
+export declare const SELF_UPDATE_ENVIRONMENT = "BALLADEER_SELF_UPDATE";
+export type Launch = Readonly<{
+    command: string;
+    args: readonly string[];
+    environment: NodeJS.ProcessEnv;
+}>;
 export type SelfUpdateDeps = Readonly<{
     environment: NodeJS.ProcessEnv;
     now?: () => number;
-    run?: (command: string, args: readonly string[]) => void;
+    /** Starts the child and answers whether one exists. Absent a return value, it started. */
+    run?: (command: string, args: readonly string[], environment: NodeJS.ProcessEnv) => boolean | void;
+    /** The node binary this process runs under; the launcher is found beside it. */
+    execPath?: string;
+    exists?: (path: string) => boolean;
 }>;
+/** 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}`;
+/** 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. */
+export declare function selfUpdateState(environment: NodeJS.ProcessEnv): SelfUpdateState | undefined;
+/**
+ * How to start the installer without trusting PATH. npm ships npx as a script
+ * beside the node it belongs to, so the node this hook runs under can run it
+ * directly; that node certainly exists, which is what makes the launch
+ * dependable. The shim beside node is second, and PATH is last, for the
+ * layouts that keep npm somewhere else.
+ */
+export declare function resolveLaunch(specifier: string, environment: NodeJS.ProcessEnv, execPath?: string, exists?: (path: string) => boolean): Launch;
 /**
  * Start the update when the server named a newer release and none was
  * started today. Answers whether one was started, for the caller's own
- * record; the session hears nothing either way.
+ * record; the session hears nothing either way. A launch that could not start
+ * leaves no stamp, so the next session start tries again rather than waiting
+ * a day for the same failure.
  */
 export declare function startSelfUpdateIfDue(newer: string | undefined, deps: SelfUpdateDeps): boolean;

package/dist/self-update.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { HOOK_SPECIFIER } from "./release.js";
 import { configHome } from "./store.js";
 /**
@@ -10,15 +10,33 @@ import { configHome } from "./store.js";
  * update must never hold the agent. So the hook, having served this session
  * from the copy it has, only starts the install: a detached child on the
  * current major, output discarded, at most once a day per laptop whatever it
- * reports. The next session runs whatever that child installed. A child that
- * fails changes nothing and is tried again the next day; `balladeer update`
- * is the manual path. Nothing here reads the session or writes to it.
+ * reports. The next session runs whatever that child installed. `balladeer
+ * update` is the manual path. Nothing here reads the session or writes to it.
+ *
+ * What changed on 29 September 2026, from what Didero's laptops showed: four
+ * of nine stayed on 1.0.12 through two releases while active every day. The
+ * hook reached for `npx` on whatever PATH its host gave it, wrote "tried
+ * today" before it knew whether anything had started, and swallowed the
+ * failure, so a laptop whose editor launches hooks without npm on PATH failed
+ * silently once a day, for ever. Now the installer is launched through the
+ * node binary this hook is already running under, with npm's own npx script
+ * beside it; the day's stamp is written only once a child actually exists;
+ * and what happened is kept in a small state file the next hook fire reports
+ * to the server, so a laptop that cannot update is visible on the scorecard
+ * instead of looking merely behind.
  */
 const STAMP = "self-update.json";
+const STATE = "self-update-state.json";
 const DAY_MS = 24 * 60 * 60 * 1000;
+/** Set on the child so the install it runs can record how it ended. */
+export const SELF_UPDATE_ENVIRONMENT = "BALLADEER_SELF_UPDATE";
+const STATE_PATTERN = /^(?:started|unstartable|installed|failed):[A-Za-z0-9._-]{1,40}$/;
 function stampPath(environment) {
     return join(configHome(environment), STAMP);
 }
+function statePath(environment) {
+    return join(configHome(environment), STATE);
+}
 function lastStarted(environment) {
     const path = stampPath(environment);
     if (!existsSync(path))
@@ -31,15 +49,71 @@ function lastStarted(environment) {
         return 0;
     }
 }
-function detached(command, args) {
-    const child = spawn(command, [...args], { detached: true, stdio: "ignore" });
+function writePrivate(path, value, environment) {
+    mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(value) + "\n", { mode: 0o600 });
+}
+/** What the last attempt came to, for the next hook fire to report. Never throws. */
+export function recordSelfUpdateState(environment, state, at) {
+    if (!STATE_PATTERN.test(state))
+        return;
+    try {
+        writePrivate(statePath(environment), { state, at }, environment);
+    }
+    catch {
+        /* A state that cannot be written is only a state nobody hears about. */
+    }
+}
+/** The recorded state, or nothing when none was written or it is not one of ours. */
+export function selfUpdateState(environment) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(environment), "utf8"));
+        return typeof parsed.state === "string" && STATE_PATTERN.test(parsed.state)
+            ? parsed.state
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * How to start the installer without trusting PATH. npm ships npx as a script
+ * beside the node it belongs to, so the node this hook runs under can run it
+ * directly; that node certainly exists, which is what makes the launch
+ * dependable. The shim beside node is second, and PATH is last, for the
+ * layouts that keep npm somewhere else.
+ */
+export function resolveLaunch(specifier, environment, execPath = process.execPath, exists = existsSync) {
+    const bin = dirname(execPath);
+    const tail = ["-y", specifier, "install", "--json"];
+    // The child's own children (npm's scripts) need to find node too.
+    const child = {
+        ...environment,
+        PATH: [bin, environment.PATH ?? ""].filter((part) => part.length > 0).join(delimiter),
+        [SELF_UPDATE_ENVIRONMENT]: "1",
+    };
+    const script = join(bin, "..", "lib", "node_modules", "npm", "bin", "npx-cli.js");
+    if (exists(script))
+        return { command: execPath, args: [script, ...tail], environment: child };
+    const shim = join(bin, process.platform === "win32" ? "npx.cmd" : "npx");
+    if (exists(shim))
+        return { command: shim, args: tail, environment: child };
+    return { command: "npx", args: tail, environment: child };
+}
+function detached(command, args, environment) {
+    const child = spawn(command, [...args], { detached: true, stdio: "ignore", env: environment });
     child.on("error", () => undefined);
     child.unref();
+    // A command that could not be found has no process id, and that is known
+    // before this function returns.
+    return child.pid !== undefined;
 }
 /**
  * Start the update when the server named a newer release and none was
  * started today. Answers whether one was started, for the caller's own
- * record; the session hears nothing either way.
+ * record; the session hears nothing either way. A launch that could not start
+ * leaves no stamp, so the next session start tries again rather than waiting
+ * a day for the same failure.
  */
 export function startSelfUpdateIfDue(newer, deps) {
     if (newer === undefined)
@@ -47,13 +121,24 @@ export function startSelfUpdateIfDue(newer, deps) {
     const now = deps.now ?? Date.now;
     if (now() - lastStarted(deps.environment) < DAY_MS)
         return false;
+    const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
+    let started;
     try {
-        mkdirSync(configHome(deps.environment), { recursive: true, mode: 0o700 });
-        writeFileSync(stampPath(deps.environment), JSON.stringify({ startedAt: now(), toward: newer }) + "\n", { mode: 0o600 });
-        (deps.run ?? detached)("npx", ["-y", HOOK_SPECIFIER, "install", "--json"]);
-        return true;
+        started = (deps.run ?? detached)(launch.command, launch.args, launch.environment) !== false;
     }
     catch {
+        started = false;
+    }
+    if (!started) {
+        recordSelfUpdateState(deps.environment, "unstartable:launcher", now());
         return false;
     }
+    try {
+        writePrivate(stampPath(deps.environment), { startedAt: now(), toward: newer }, deps.environment);
+    }
+    catch {
+        /* The child is running; an unwritten stamp costs one more attempt, not a missed one. */
+    }
+    recordSelfUpdateState(deps.environment, `started:${newer}`, now());
+    return true;
 }

package/dist/user-scope.d.ts

@@ -53,6 +53,8 @@ export declare function isOurUserEntry(entry: unknown): boolean;
 export declare function isInstalledCommandPath(command: string): boolean;
 /** `~/.claude/settings.json` carries user-scope hooks. */
 export declare function mergeClaudeUserHooks(home: string, published: boolean, installed?: string): UserScopeWrite;
+/** What a person has to do once in Codex, which no command can do for them. */
+export declare const CODEX_HOOK_APPROVAL = "Codex: type /hooks in a Codex session and trust Balladeer's three hooks. Codex skips a hook until you have trusted it, so until then Codex has Balladeer's tools and none of its session-start guidance or updates.";
 /** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
  * one fenced block this command owns end to end. */
 export declare function mergeCodexUserConfig(home: string, published: boolean, installed?: string): UserScopeWrite;

package/dist/user-scope.js

@@ -1,3 +1,4 @@
+import { noteHooksWritten } from "./hook-trust.js";
 import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
@@ -207,6 +208,21 @@ export function mergeClaudeUserHooks(home, published, installed) {
         return { host, path, status: "refused", reason: "permissions.allow is not a list" };
     const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
     const denied = deny.some((rule) => typeof rule === "string" && /^mcp__balladeer(__|$)/.test(rule));
+    // An event this release no longer hooks: its own entry there is deprecated
+    // and comes out. Robert, 29 September 2026: a hook that should no longer
+    // exist is removed, a new one is added, one that still belongs persists.
+    for (const [event, rows] of Object.entries(hooks)) {
+        if (CLAUDE_EVENTS.includes(event) || !Array.isArray(rows))
+            continue;
+        const kept = rows.filter((row) => !row?.hooks?.some((h) => h.statusMessage === USER_SCOPE_OWNER));
+        if (kept.length === rows.length)
+            continue;
+        if (kept.length === 0)
+            delete hooks[event];
+        else
+            hooks[event] = kept;
+        changed = true;
+    }
     if (!denied && !allow.some((rule) => rule === USER_SCOPE_ALLOW_RULE)) {
         permissions.allow = [...allow, USER_SCOPE_ALLOW_RULE];
         root.permissions = permissions;
@@ -219,6 +235,8 @@ export function mergeClaudeUserHooks(home, published, installed) {
     writeJsonAtomically(path, JSON.stringify(root, null, 2) + "\n");
     return { host, path, status: "written" };
 }
+/** What a person has to do once in Codex, which no command can do for them. */
+export const CODEX_HOOK_APPROVAL = "Codex: type /hooks in a Codex session and trust Balladeer's three hooks. Codex skips a hook until you have trusted it, so until then Codex has Balladeer's tools and none of its session-start guidance or updates.";
 const CODEX_START = "# balladeer:user:start";
 const CODEX_END = "# balladeer:user:end";
 /** `~/.codex/config.toml` carries both the server and the hooks for Codex, in
@@ -302,7 +320,13 @@ export function installUserScope(options) {
         mergeClaudeUserMcp(home, options.published, options.installed),
         mergeClaudeUserHooks(home, options.published, options.installed),
     ];
-    if (existsSync(join(home, ".codex")))
-        writes.push(mergeCodexUserConfig(home, options.published, options.installed));
+    if (existsSync(join(home, ".codex"))) {
+        const codex = mergeCodexUserConfig(home, options.published, options.installed);
+        writes.push(codex);
+        // Codex has to run these once before anybody assumes it does; the mark is
+        // what lets its own session say so after a silent background update.
+        if (codex.status !== "refused")
+            noteHooksWritten(options.environment, "codex", codex.status === "written");
+    }
     return writes;
 }

package/dist/wire.d.ts

@@ -5,10 +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.14";
+export declare const CLI_VERSION = "1.0.15";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.14";
+/** What the last background update came to: `started:1.0.15`, `installed:1.0.15`, `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.15";
 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,9 +5,13 @@
  * 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.14";
+export const CLI_VERSION = "1.0.15";
 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.15`, `installed:1.0.15`, `failed:exit-1`, `unstartable:launcher`. */
+export const UPDATE_STATE_HEADER = "x-balladeer-update-state";
+/** Which host's hook made this guidance fetch: `claude` or `codex`. */
+export const HOOK_HOST_HEADER = "x-balladeer-hook";
 export const CLIENT_HEADER_VALUE = `balladeer/${CLI_VERSION}`;
 export const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export const DELEGATED_SCOPES = [

package/package.json

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