balladeer 1.0.14 → 1.0.16

package/dist/risk/validate.js

@@ -0,0 +1,154 @@
+import { PROMISE_ID } from "../behavior-map-schema.js";
+import { BANDS, CHANGE_EXTRACTION_SCHEMA_VERSION, DELTA_KINDS, FILE_STATUSES, INTENT_SOURCES, LANGUAGES, RESOURCE_CHANGES, RESOURCE_KINDS, RISK_REPORT_SCHEMA_VERSION, SIGNALS, SYMBOL_CHANGES, SYMBOL_EXTRACTORS, SYMBOL_KINDS, } from "./contract.js";
+const string = (max = 20_000) => (value, at, errors) => {
+    if (typeof value === "string" && value.length <= max)
+        return true;
+    errors.push(`${at} must be a string of at most ${max} characters`);
+    return false;
+};
+const pattern = (regex, description) => (value, at, errors) => {
+    if (typeof value === "string" && regex.test(value))
+        return true;
+    errors.push(`${at} must be ${description}`);
+    return false;
+};
+const oneOf = (values) => (value, at, errors) => {
+    if (typeof value === "string" && values.includes(value))
+        return true;
+    errors.push(`${at} must be one of ${values.join(", ")}`);
+    return false;
+};
+const number = (min, max, integer = false) => (value, at, errors) => {
+    if (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= min &&
+        value <= max &&
+        (!integer || Number.isInteger(value)))
+        return true;
+    errors.push(`${at} must be ${integer ? "an integer" : "a number"} from ${min} to ${max}`);
+    return false;
+};
+const nullable = (check) => (value, at, errors) => value === null || check(value, at, errors);
+const boolean = (value, at, errors) => {
+    if (typeof value === "boolean")
+        return true;
+    errors.push(`${at} must be true or false`);
+    return false;
+};
+const listOf = (item) => (value, at, errors) => {
+    if (!Array.isArray(value)) {
+        errors.push(`${at} must be a list`);
+        return false;
+    }
+    let ok = true;
+    value.forEach((entry, index) => {
+        if (!item(entry, `${at}[${index}]`, errors))
+            ok = false;
+    });
+    return ok;
+};
+const record = (fields, optional = []) => (value, at, errors) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        errors.push(`${at} must be an object`);
+        return false;
+    }
+    const input = value;
+    const unknown = Object.keys(input).filter((key) => !(key in fields));
+    if (unknown.length > 0) {
+        errors.push(`${at} has fields the contract does not define: ${unknown.join(", ")}`);
+        return false;
+    }
+    let ok = true;
+    for (const [key, check] of Object.entries(fields)) {
+        if (!(key in input) || input[key] === undefined) {
+            if (optional.includes(key))
+                continue;
+            errors.push(`${at}.${key} is missing`);
+            ok = false;
+            continue;
+        }
+        if (!check(input[key], `${at}.${key}`, errors))
+            ok = false;
+    }
+    return ok;
+};
+const SHA = pattern(/^[0-9a-f]{40}$/, "a 40-character commit sha");
+const promiseId = pattern(PROMISE_ID, "a promise id");
+const count = number(0, Number.MAX_SAFE_INTEGER, true);
+const changedFile = record({
+    path: string(1024),
+    status: oneOf(FILE_STATUSES),
+    oldPath: nullable(string(1024)),
+    language: oneOf(LANGUAGES),
+    isTest: boolean,
+    hunks: listOf(record({ oldStart: count, oldLines: count, newStart: count, newLines: count })),
+    symbolsChanged: listOf(record({ name: string(512), kind: oneOf(SYMBOL_KINDS), change: oneOf(SYMBOL_CHANGES) })),
+    identifiersAdded: listOf(string(512)),
+    identifiersRemoved: listOf(string(512)),
+    resources: listOf(record({ kind: oneOf(RESOURCE_KINDS), name: string(600), change: oneOf(RESOURCE_CHANGES) })),
+    guardDeletions: listOf(record({ line: count, text: string(2000) })),
+    constantChanges: listOf(record({ name: string(512), from: string(2000), to: string(2000) })),
+    symbolExtractor: oneOf(SYMBOL_EXTRACTORS),
+}, ["symbolExtractor"]);
+const extraction = record({
+    schemaVersion: oneOf([CHANGE_EXTRACTION_SCHEMA_VERSION]),
+    base: SHA,
+    head: SHA,
+    files: listOf(changedFile),
+    deltas: listOf(record({ text: string(4000), files: listOf(string(1024)), kind: oneOf(DELTA_KINDS) })),
+    intent: record({ summary: string(), source: oneOf(INTENT_SOURCES) }),
+}, ["deltas", "intent"]);
+const unit = number(0, 1);
+const report = record({
+    schemaVersion: oneOf([RISK_REPORT_SCHEMA_VERSION]),
+    base: SHA,
+    head: SHA,
+    promises: listOf(record({
+        promiseId,
+        title: string(),
+        score: unit,
+        band: oneOf(BANDS),
+        reasons: listOf(record({
+            signal: oneOf(SIGNALS),
+            weight: unit,
+            evidence: record({
+                file: string(),
+                symbol: string(),
+                resource: string(),
+                delta: string(),
+                caseId: string(),
+                detail: string(),
+            }, ["caseId", "detail"]),
+        })),
+        features: record({
+            symbol_hit: unit,
+            graph_forward_distance: nullable(count),
+            graph_reverse_distance: nullable(count),
+            resource_overlap: unit,
+            linked_test_changed: unit,
+            sink_reach: unit,
+            delta_similarity: unit,
+            intent_clash: unit,
+            prior_break: count,
+            churn: unit,
+        }),
+    }, ["title"])),
+    baselines: record({
+        scope_only: listOf(promiseId),
+        import_closure: listOf(promiseId),
+        all: listOf(promiseId),
+        random: listOf(promiseId),
+    }),
+});
+function parse(check, value, name) {
+    const errors = [];
+    return check(value, name, errors) ? { ok: true, value: value } : { ok: false, errors };
+}
+/** A change extraction, checked against the contract. */
+export function parseChangeExtraction(value) {
+    return parse(extraction, value, "extraction");
+}
+/** A risk report, checked against the contract. */
+export function parseRiskReport(value) {
+    return parse(report, value, "report");
+}

package/dist/scratch-worktree.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Disposable checkouts of one commit, for an agent to read and run things in.
+ *
+ * A map builder and a judge each work in a detached `git worktree` of the
+ * commit they are about, made under the system temp directory and removed
+ * afterwards. Whatever the agent writes there, a scratch test, a build output,
+ * an edit it should not have made, goes with the directory, and the person's
+ * own checkout is never the one being changed. Nothing here fetches: the
+ * commit has to be in the repository already, which it is for a change being
+ * pushed.
+ */
+export type ScratchWorktree = Readonly<{
+    path: string;
+    sha: string;
+    remove: () => Promise<void>;
+}>;
+export declare function resolveCommit(root: string, ref: string): Promise<string | undefined>;
+export declare function addScratchWorktree(root: string, ref: string, label: string, scratch?: string): Promise<{
+    ok: true;
+    worktree: ScratchWorktree;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Synchronous, for a process that is being stopped: remove what this process made. */
+export declare function removeLiveWorktreesNow(): void;
+/**
+ * The installed dependencies a fresh worktree lacks, linked from the checkout.
+ *
+ * A new worktree holds only tracked files, so it has no `node_modules` and a
+ * test run in it fails before it reaches the behavior. Each `node_modules`
+ * beside a tracked `package.json` in the person's checkout, and a `.venv` at
+ * the top, is linked into the same place in the worktree. Linked, not copied:
+ * the link is removed with the worktree and the dependencies are never touched.
+ */
+export declare function shareDependencies(root: string, worktree: string): Promise<number>;
+export type CarriedFile = Readonly<{
+    path: string;
+    sha256: string;
+}>;
+/**
+ * Files an agent added in one worktree, so a command it wrote can run in another.
+ *
+ * A judge that proves a break usually writes a new test. Its reproduction is
+ * then run in a clean checkout of the base commit, where that test does not
+ * exist, so the new files travel with it: untracked, not ignored, regular, and
+ * small. Edits to tracked files do not travel, and the judge brief says to put
+ * a reproduction in a new file for that reason.
+ */
+export declare function newFiles(worktree: string): Promise<CarriedFile[]>;
+export declare function carryFiles(from: string, to: string, files: readonly CarriedFile[]): void;

package/dist/scratch-worktree.js

@@ -0,0 +1,153 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { runCommand } from "./gh.js";
+/** Every worktree this process made and has not removed, for a signal handler to clear. */
+const live = new Map();
+export async function resolveCommit(root, ref) {
+    const answer = await runCommand("git", ["-C", root, "rev-parse", "--verify", `${ref}^{commit}`]);
+    const sha = answer.stdout.trim();
+    return answer.ok && /^[0-9a-f]{40}$/.test(sha) ? sha : undefined;
+}
+export async function addScratchWorktree(root, ref, label, scratch) {
+    const sha = await resolveCommit(root, ref);
+    if (sha === undefined)
+        return { ok: false, reason: `${ref} is not a commit in this repository` };
+    const parent = realpathSync(mkdtempSync(join(scratch ?? tmpdir(), `balladeer-${label.replace(/[^A-Za-z0-9_-]/g, "-")}-`)));
+    const path = join(parent, "tree");
+    const added = await runCommand("git", ["-C", root, "worktree", "add", "--detach", "--quiet", path, sha], { timeoutMs: 120_000 });
+    if (!added.ok) {
+        rmSync(parent, { recursive: true, force: true });
+        return {
+            ok: false,
+            reason: `a scratch checkout of ${sha.slice(0, 12)} could not be made: ${added.stderr}`,
+        };
+    }
+    live.set(path, root);
+    return {
+        ok: true,
+        worktree: {
+            path,
+            sha,
+            remove: async () => {
+                await runCommand("git", ["-C", root, "worktree", "remove", "--force", path], {
+                    timeoutMs: 60_000,
+                });
+                rmSync(parent, { recursive: true, force: true });
+                await runCommand("git", ["-C", root, "worktree", "prune"]);
+                live.delete(path);
+            },
+        },
+    };
+}
+/** Synchronous, for a process that is being stopped: remove what this process made. */
+export function removeLiveWorktreesNow() {
+    for (const [path, root] of live) {
+        try {
+            execFileSync("git", ["-C", root, "worktree", "remove", "--force", path], {
+                stdio: "ignore",
+                timeout: 20_000,
+            });
+        }
+        catch {
+            /* The directory removal below still clears the files. */
+        }
+        rmSync(dirname(path), { recursive: true, force: true });
+        live.delete(path);
+    }
+}
+/**
+ * The installed dependencies a fresh worktree lacks, linked from the checkout.
+ *
+ * A new worktree holds only tracked files, so it has no `node_modules` and a
+ * test run in it fails before it reaches the behavior. Each `node_modules`
+ * beside a tracked `package.json` in the person's checkout, and a `.venv` at
+ * the top, is linked into the same place in the worktree. Linked, not copied:
+ * the link is removed with the worktree and the dependencies are never touched.
+ */
+export async function shareDependencies(root, worktree) {
+    const listed = await runCommand("git", [
+        "-C",
+        root,
+        "ls-files",
+        "--",
+        "package.json",
+        "*/package.json",
+        "*/*/package.json",
+    ]);
+    const directories = new Set(["."]);
+    if (listed.ok)
+        for (const line of listed.stdout.split("\n"))
+            if (line.trim())
+                directories.add(dirname(line.trim()));
+    let linked = 0;
+    const link = (relativePath) => {
+        const source = join(root, relativePath);
+        const target = join(worktree, relativePath);
+        if (!existsSync(source) || existsSync(target) || !existsSync(dirname(target)))
+            return;
+        try {
+            symlinkSync(source, target, "dir");
+            linked += 1;
+        }
+        catch {
+            /* A test that needs it will say so. */
+        }
+    };
+    for (const directory of directories)
+        link(join(directory, "node_modules"));
+    link(".venv");
+    return linked;
+}
+/**
+ * Files an agent added in one worktree, so a command it wrote can run in another.
+ *
+ * A judge that proves a break usually writes a new test. Its reproduction is
+ * then run in a clean checkout of the base commit, where that test does not
+ * exist, so the new files travel with it: untracked, not ignored, regular, and
+ * small. Edits to tracked files do not travel, and the judge brief says to put
+ * a reproduction in a new file for that reason.
+ */
+export async function newFiles(worktree) {
+    const listed = await runCommand("git", [
+        "-C",
+        worktree,
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+    ]);
+    if (!listed.ok)
+        return [];
+    const files = [];
+    for (const path of listed.stdout.split("\0")) {
+        if (!path || files.length >= 200)
+            continue;
+        const absolute = join(worktree, path);
+        try {
+            const stat = lstatSync(absolute);
+            if (!stat.isFile() || stat.size > 1024 * 1024)
+                continue;
+            files.push({
+                path,
+                sha256: createHash("sha256").update(readFileSync(absolute)).digest("hex"),
+            });
+        }
+        catch {
+            /* Gone between the listing and the read. */
+        }
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+export function carryFiles(from, to, files) {
+    for (const file of files) {
+        const target = resolve(to, file.path);
+        const inside = relative(to, target);
+        if (inside.startsWith("..") || inside === "")
+            continue;
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(join(from, file.path), target);
+    }
+}

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;
 }