balladeer 1.0.13 → 1.0.15

package/dist/guidance-hook.mjs

@@ -2027,8 +2027,10 @@ var require_toml = __commonJS({
 });
 
 // src/wire.ts
-var CLI_VERSION = "1.0.13";
+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) {
@@ -3107,25 +3191,23 @@ async function runGuidance(options) {
     event = parsedEvent;
     const record = input;
     const credentials = readCredentials(options.environment).agents;
+    const repositories = projectScoped ? [] : repositoryHints(options.cwd);
     const agents = projectScoped ? credentials.filter(
       (agent) => agent.controlPlane === options.controlPlane && agent.repositoryId === options.repositoryId
     ) : (() => {
-      const selection = selectAgent(
-        credentials,
-        options.controlPlane,
-        void 0,
-        repositoryHints(options.cwd)
-      );
+      const selection = selectAgent(credentials, options.controlPlane, void 0, repositories);
       return selection.kind === "refused" ? [] : [selection.agent];
     })();
     if (agents.length !== 1 || !agents[0]) {
       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;