balladeer 1.0.13 → 1.0.15

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.13";
+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.13";
+/** 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.13";
+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.13",
+  "version": "1.0.15",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,