balladeer 1.0.18 → 1.0.19

package/dist/checkout-form.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Whether an install may take the older form out of the checkout it runs in:
+ * only when a person ran setup or install and the user-scope form is fully in
+ * place. The background update a session hook starts leaves the repository's
+ * files alone, because an edit to a file the team commits is a diff nobody
+ * asked for, and the user-scope hook already switches the older hook off from
+ * the laptop side (`retireCheckoutRuntime`), so nothing is lost.
+ */
+export declare function checkoutFormRemovalAllowed(environment: NodeJS.ProcessEnv, writes: readonly {
+    status: string;
+}[]): boolean;
 /**
  * Taking this product's own older, per-repository form out of a checkout once
  * the user-scope form is in place, so one hook speaks per session.

package/dist/checkout-form.js

@@ -2,6 +2,20 @@ import { execFileSync } from "node:child_process";
 import { copyFileSync, existsSync, lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isOurEntry, writeJsonAtomically } from "./mcp-config.js";
+import { SELF_UPDATE_ENVIRONMENT } from "./self-update.js";
+/**
+ * Whether an install may take the older form out of the checkout it runs in:
+ * only when a person ran setup or install and the user-scope form is fully in
+ * place. The background update a session hook starts leaves the repository's
+ * files alone, because an edit to a file the team commits is a diff nobody
+ * asked for, and the user-scope hook already switches the older hook off from
+ * the laptop side (`retireCheckoutRuntime`), so nothing is lost.
+ */
+export function checkoutFormRemovalAllowed(environment, writes) {
+    return (environment[SELF_UPDATE_ENVIRONMENT] !== "1" &&
+        writes.length > 0 &&
+        !writes.some((w) => w.status === "refused"));
+}
 const PROJECT_OWNER = "Balladeer current guidance (loader 1)";
 const CODEX_BLOCKS = [
     ["# balladeer:guidance:start", "# balladeer:guidance:end"],

package/dist/cli.js

@@ -31,7 +31,7 @@ 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 { checkoutFormRemovalAllowed, describeCheckoutFormRemoval, findCheckoutForm, removeCheckoutForm, } from "./checkout-form.js";
 import { StoreError, normalizeControlPlane } from "./store.js";
 import { CLI_INVOCATION, CLI_VERSION, DEFAULT_CONTROL_PLANE } from "./wire.js";
 const USAGE = `balladeer ${CLI_VERSION}
@@ -545,8 +545,9 @@ function installEverything(options) {
     }
     // 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.
-    if ((writes ?? []).length > 0 && !(writes ?? []).some((w) => w.status === "refused")) {
+    // a copy beside any file git does not already keep, and never from the
+    // background update (see `checkoutFormRemovalAllowed`).
+    if (checkoutFormRemovalAllowed(process.env, writes ?? [])) {
         const checkoutForm = findCheckoutForm({
             cwd: process.cwd(),
             controlPlane: options.controlPlane,

package/dist/commands/guidance.js

@@ -7,6 +7,7 @@ import { repositoryHints } from "../repository.js";
 import { newerVersionPublished } from "../currency.js";
 import { startSelfUpdateIfDue } from "../self-update.js";
 import { noteHookFired } from "../hook-trust.js";
+import { retireCheckoutRuntime } from "../guidance-runtime.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})`;
@@ -158,6 +159,18 @@ export async function runGuidance(options) {
         // trust are the ones this matters to.
         if (options.hook === "codex")
             noteHookFired(options.environment, "codex");
+        // This hook covers this checkout now, so the older per-repository hook
+        // here (releases before 1.0.8) only makes the session hear the guidance
+        // twice. Switch it off from the laptop side, once, before the fetch:
+        // nothing printed, no repository file touched, nobody asked to run a thing.
+        if (!projectScoped && event === "SessionStart")
+            retireCheckoutRuntime({
+                cwd: options.cwd,
+                host: options.hook,
+                repositoryId: agents[0].repositoryId,
+                controlPlane: agents[0].controlPlane,
+                environment: options.environment,
+            });
         const loaded = await loadGuidance({
             agent: agents[0],
             environment: options.environment,
@@ -165,14 +178,16 @@ export async function runGuidance(options) {
             hook: options.hook,
             ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         });
-        // Behind? Start the install in the background, once a day at most, and
-        // carry on serving this session from the copy that is here.
-        if (event === "SessionStart")
-            startSelfUpdateIfDue(newerVersionPublished(), {
-                environment: options.environment,
-                ...(options.startUpdate ? { run: options.startUpdate } : {}),
-                ...(options.now ? { now: options.now } : {}),
-            });
+        // Behind? Start the install in the background and carry on serving this
+        // session from the copy that is here. Any hook that loaded guidance may
+        // start it, not only a session start: sessions run for days, and a laptop
+        // whose sessions never restart would otherwise never update (Robert's own,
+        // 1 October 2026). The stamp keeps it to once a day per release.
+        startSelfUpdateIfDue(newerVersionPublished(), {
+            environment: options.environment,
+            ...(options.startUpdate ? { run: options.startUpdate } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
         const sessionId = identifier(record.session_id);
         const agentId = identifier(record.agent_id);
         recordGuidanceContext({

package/dist/commands/mcp.js

@@ -1,5 +1,4 @@
 import { createInterface } from "node:readline";
-import { installGuidanceLoader } from "../guidance-install.js";
 import { callAgentTool, forwarderHeaders, noAgentCredentialSentence, safeJson, selectAgent, structuredString, updateLine, } from "../agent.js";
 import { noteServerVersion, updateNotice } from "../currency.js";
 import { repositoryHint, repositoryHints } from "../repository.js";
@@ -189,15 +188,12 @@ export async function runMcp(options) {
             return 4;
         return serveUntracked(options, untrackedLine(repositoryHint(options.cwd)));
     }
+    // This forwarder used to install the per-repository guidance hook into any
+    // checkout whose project config named this repository. From 1.0.8 the hook
+    // lives at user scope, so doing that put a second hook beside it and every
+    // session heard the guidance twice; it also re-armed the older hook the
+    // user-scope hook had just switched off. It installs nothing now.
     const { agent } = selection;
-    const guidanceInstall = installGuidanceLoader({
-        environment: options.environment,
-        cwd: options.cwd,
-        repositoryId: agent.repositoryId,
-        controlPlane: agent.controlPlane,
-    });
-    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,

package/dist/commands/setup.js

@@ -11,7 +11,6 @@ import { CI_BRANCH, commitWorkflowOnBranch, repositoryRoot, workflowOnDefaultBra
 import { MCP_CONFIG_FILE, currentEntry, entryRepositoryId, isOurEntry, mergeMcpConfig, readMcpConfig, stdioEntry, } from "../mcp-config.js";
 import { DESKTOP_CONFIG_FILE, desktopConfigLocation, desktopServerKey, desktopStdioEntry, mergeDesktopConfig, } from "../desktop-config.js";
 import { selectAgent } from "../agent.js";
-import { installGuidanceLoader } from "../guidance-install.js";
 import { describeEarlier, describeRemoval, findEarlier, removeEarlier } from "../remove-earlier.js";
 import { userHome } from "../user-scope.js";
 import { formatInstant } from "../local-time.js";
@@ -1008,28 +1007,11 @@ function mergeHostConfig(options, root, repositoryId, published) {
         : mergeMcpConfig(root, entry, options.controlPlane);
 }
 function writeHostConventions(options, root) {
-    const result = writeConventions(root, options.client === "codex" ? { file: "AGENTS.md" } : {});
-    if (result.kind === "written") {
-        const entry = options.client === "codex" ? readCodexEntry(root) : currentEntry(readMcpConfig(root));
-        const repositoryId = entryRepositoryId(entry);
-        if (repositoryId !== undefined) {
-            const loader = installGuidanceLoader({
-                environment: options.environment,
-                cwd: root,
-                repositoryId,
-                controlPlane: options.controlPlane,
-                host: options.client === "codex" ? "codex" : "claude",
-            });
-            emit(options, { step: "guidance_loader", ...loader });
-            say(options, loader.status === "installed_needs_host_trust" ||
-                loader.status === "installed_trust_unverified"
-                ? "Project guidance loader installed. Review new hooks in your coding host once; future policy updates do not change that hook definition. A fresh session is needed to observe it."
-                : loader.status === "unavailable"
-                    ? `Project guidance loader needs repair (${loader.reason}). No active hook is claimed.`
-                    : "No matching project guidance integration was found. No guidance hook was installed or activated.");
-        }
-    }
-    return result;
+    // No per-repository guidance hook any more. The install step registers the
+    // hook at user scope, where it runs in every checkout; adding the older
+    // per-repository one here as well put a second hook in this checkout, and
+    // every session heard the guidance twice (Didero, September 2026).
+    return writeConventions(root, options.client === "codex" ? { file: "AGENTS.md" } : {});
 }
 function hostNextSteps(options) {
     if (options.client === "codex")

package/dist/currency.d.ts

@@ -15,6 +15,8 @@
 export declare const CLI_NEWEST_HEADER = "x-balladeer-cli-newest";
 export declare const CLI_FLOOR_HEADER = "x-balladeer-cli-minimum";
 export declare const CLI_ADVICE_HEADER = "x-balladeer-cli-advice";
+/** Whether `left` is an older release than `right` (both `x.y.z`). */
+export declare function older(left: string, right: string): boolean;
 /**
  * Reads the version signals off one response.
  *

package/dist/currency.js

@@ -25,7 +25,8 @@ const ADVICE_LIMIT = 300;
 const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
 let notice;
 let newestSeen;
-function older(left, right) {
+/** Whether `left` is an older release than `right` (both `x.y.z`). */
+export function older(left, right) {
     const [a, b] = [left.split(".").map(Number), right.split(".").map(Number)];
     for (let index = 0; index < 3; index += 1) {
         const difference = a[index] - b[index];

package/dist/guidance-hook.mjs

@@ -2152,13 +2152,31 @@ function relayHook(input, directory) {
 }
 
 // src/wire.ts
-var CLI_VERSION = "1.0.18";
+var CLI_VERSION = "1.0.19";
 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";
 
+// src/guidance-runtime.ts
+import { createHash as createHash3, randomBytes as randomBytes2 } from "node:crypto";
+import {
+  constants as constants2,
+  closeSync as closeSync3,
+  fstatSync as fstatSync2,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync5,
+  openSync as openSync3,
+  readFileSync as readFileSync5,
+  realpathSync,
+  renameSync as renameSync4,
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync4
+} from "node:fs";
+import { join as join5 } from "node:path";
+import { execFileSync } from "node:child_process";
+
 // src/store.ts
 import {
   closeSync,
@@ -2289,6 +2307,8 @@ var HOOK_SPECIFIER = "balladeer@1";
 var STAMP = "self-update.json";
 var STATE = "self-update-state.json";
 var DAY_MS = 24 * 60 * 60 * 1e3;
+var HOUR_MS = 60 * 60 * 1e3;
+var VERSION2 = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
 var SELF_UPDATE_ENVIRONMENT = "BALLADEER_SELF_UPDATE";
 var STATE_PATTERN = /^(?:started|unstartable|installed|failed):[A-Za-z0-9._-]{1,40}$/;
 function stampPath(environment) {
@@ -2297,16 +2317,23 @@ function stampPath(environment) {
 function statePath(environment) {
   return join3(configHome(environment), STATE);
 }
-function lastStarted(environment) {
+function lastAttempt(environment) {
   const path = stampPath(environment);
-  if (!existsSync(path)) return 0;
+  if (!existsSync(path)) return { startedAt: 0 };
   try {
     const parsed = JSON.parse(readFileSync3(path, "utf8"));
-    return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+    const startedAt = typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+    return typeof parsed.toward === "string" && VERSION2.test(parsed.toward) ? { startedAt, toward: parsed.toward } : { startedAt };
   } catch {
-    return 0;
+    return { startedAt: 0 };
   }
 }
+function due(newer, last, now) {
+  const since = now - last.startedAt;
+  if (since >= DAY_MS) return true;
+  const newerTarget = last.toward === void 0 || older(last.toward, newer);
+  return newerTarget && since >= HOUR_MS;
+}
 function writePrivate(path, value, environment) {
   mkdirSync3(configHome(environment), { recursive: true, mode: 448 });
   writeFileSync2(path, JSON.stringify(value) + "\n", { mode: 384 });
@@ -2349,7 +2376,7 @@ function detached(command, args, environment) {
 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;
+  if (!due(newer, lastAttempt(deps.environment), now())) return false;
   const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
   let started;
   try {
@@ -2628,52 +2655,124 @@ function recordGuidanceContext(input, write2) {
   return true;
 }
 
+// src/guidance-runtime.ts
+var OWNER = "balladeer-guidance-runtime/1";
+var sha2 = (value) => createHash3("sha256").update(value).digest("hex");
+function guidanceRuntimeKey(scope) {
+  return sha2(
+    JSON.stringify([
+      realpathSync(scope.root),
+      new URL(scope.controlPlane).origin,
+      scope.repositoryId,
+      scope.host
+    ])
+  );
+}
+function checkDirectory(path) {
+  const stat = lstatSync3(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 63) !== 0)
+    throw new Error("guidance_runtime_directory_unsafe");
+}
+function readPrivate(path, max) {
+  const fd = openSync3(path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
+  try {
+    const stat = fstatSync2(fd);
+    if (!stat.isFile() || stat.size > max || (stat.mode & 63) !== 0)
+      throw new Error("guidance_runtime_file_unsafe");
+    return readFileSync5(fd);
+  } finally {
+    closeSync3(fd);
+  }
+}
+function retireCheckoutRuntime(input) {
+  try {
+    const base = join5(configHome(input.environment), "guidance-runtime-v1");
+    try {
+      lstatSync3(base);
+    } catch {
+      return "absent";
+    }
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: input.cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500,
+      maxBuffer: 8192
+    }).trim();
+    if (root.length === 0) return "absent";
+    const key2 = guidanceRuntimeKey({
+      root,
+      host: input.host,
+      repositoryId: input.repositoryId,
+      controlPlane: input.controlPlane
+    });
+    const directory = join5(base, key2);
+    const manifestPath = join5(directory, "current.json");
+    try {
+      checkDirectory(directory);
+    } catch {
+      return "absent";
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(readPrivate(manifestPath, 4096).toString("utf8"));
+    } catch (error) {
+      return error.code === "ENOENT" ? "absent" : "kept";
+    }
+    if (manifest?.owner !== OWNER || manifest.scopeKey !== key2) return "kept";
+    renameSync4(manifestPath, join5(directory, "retired.json"));
+    return "retired";
+  } catch {
+    return "kept";
+  }
+}
+
 // src/guidance-install.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import {
-  constants as constants2,
-  closeSync as closeSync5,
-  fstatSync as fstatSync2,
-  openSync as openSync5,
+  constants as constants3,
+  closeSync as closeSync6,
+  fstatSync as fstatSync3,
+  openSync as openSync6,
   existsSync as existsSync3,
-  lstatSync as lstatSync4,
+  lstatSync as lstatSync5,
   linkSync,
-  mkdirSync as mkdirSync6,
-  readFileSync as readFileSync7,
-  renameSync as renameSync6,
-  unlinkSync as unlinkSync5,
-  writeFileSync as writeFileSync4
+  mkdirSync as mkdirSync7,
+  readFileSync as readFileSync8,
+  renameSync as renameSync7,
+  unlinkSync as unlinkSync6,
+  writeFileSync as writeFileSync5
 } from "node:fs";
 var import_toml2 = __toESM(require_toml(), 1);
-import { dirname as dirname4, join as join7, relative } from "node:path";
+import { dirname as dirname4, join as join8, relative } from "node:path";
 
 // src/codex-config.ts
 var import_toml = __toESM(require_toml(), 1);
 import {
-  closeSync as closeSync4,
+  closeSync as closeSync5,
   existsSync as existsSync2,
   fsyncSync as fsyncSync3,
-  lstatSync as lstatSync3,
-  mkdirSync as mkdirSync5,
-  openSync as openSync4,
-  readFileSync as readFileSync6,
-  renameSync as renameSync5,
-  unlinkSync as unlinkSync4,
+  lstatSync as lstatSync4,
+  mkdirSync as mkdirSync6,
+  openSync as openSync5,
+  readFileSync as readFileSync7,
+  renameSync as renameSync6,
+  unlinkSync as unlinkSync5,
   writeSync as writeSync3
 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/mcp-config.ts
 import {
-  closeSync as closeSync3,
+  closeSync as closeSync4,
   fsyncSync as fsyncSync2,
-  openSync as openSync3,
-  readFileSync as readFileSync5,
-  renameSync as renameSync4,
-  unlinkSync as unlinkSync3,
+  openSync as openSync4,
+  readFileSync as readFileSync6,
+  renameSync as renameSync5,
+  unlinkSync as unlinkSync4,
   writeSync as writeSync2
 } from "node:fs";
-import { basename, dirname as dirname3, isAbsolute, join as join5 } from "node:path";
+import { basename, dirname as dirname3, isAbsolute, join as join6 } from "node:path";
 var MCP_CONFIG_FILE = ".mcp.json";
 function sameOrigin(left, right) {
   try {
@@ -2716,7 +2815,7 @@ function currentEntry(parsed) {
 }
 function readMcpConfig(repositoryRoot) {
   try {
-    return JSON.parse(readFileSync5(join5(repositoryRoot, MCP_CONFIG_FILE), "utf8"));
+    return JSON.parse(readFileSync6(join6(repositoryRoot, MCP_CONFIG_FILE), "utf8"));
   } catch {
     return void 0;
   }
@@ -2726,7 +2825,7 @@ function readMcpConfig(repositoryRoot) {
 var CODEX_CONFIG_FILE = ".codex/config.toml";
 function readCodexEntry(root) {
   try {
-    const config = (0, import_toml.parse)(readFileSync6(join6(root, CODEX_CONFIG_FILE), "utf8"));
+    const config = (0, import_toml.parse)(readFileSync7(join7(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 {
@@ -2735,7 +2834,7 @@ function readCodexEntry(root) {
 }
 function hasManagedCodexEntry(root, controlPlane) {
   try {
-    const text = readFileSync6(join6(root, CODEX_CONFIG_FILE), "utf8");
+    const text = readFileSync7(join7(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)
@@ -3151,23 +3250,23 @@ var MAX_FILE = 262144;
 function readRegular(path, allowMissing = false, writable = true) {
   if (!existsSync3(path)) {
     try {
-      lstatSync4(path);
+      lstatSync5(path);
     } catch (e) {
       if (e.code === "ENOENT" && allowMissing) return void 0;
     }
     throw new Error("file_unavailable");
   }
-  const stat = lstatSync4(path);
+  const stat = lstatSync5(path);
   if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_FILE || writable && (stat.mode & 146) === 0)
     throw new Error("file_not_safely_writable");
-  return readFileSync7(path, "utf8");
+  return readFileSync8(path, "utf8");
 }
 function safeParent(root, path) {
   let at = dirname4(path);
   while (at !== root) {
     if (relative(root, at).startsWith("..")) throw new Error("outside_repository");
     try {
-      const stat = lstatSync4(at);
+      const stat = lstatSync5(at);
       if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("unsafe_directory");
     } catch (e) {
       if (e.code !== "ENOENT") throw e;
@@ -3177,12 +3276,12 @@ function safeParent(root, path) {
 }
 function validateProjectGuidanceScope(options) {
   try {
-    const root = execFileSync("git", ["-C", options.cwd, "rev-parse", "--show-toplevel"], {
+    const root = execFileSync2("git", ["-C", options.cwd, "rev-parse", "--show-toplevel"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 1e3
     }).trim();
-    const path = join7(root, options.hook === "codex" ? ".codex/config.toml" : ".mcp.json");
+    const path = join8(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));
@@ -3262,11 +3361,11 @@ function withSafeEndpoint(agent) {
 }
 
 // src/repository.ts
-import { execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync3 } from "node:child_process";
 var REPOSITORY_HINT_PATTERN = /^[A-Za-z0-9._-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
 function git(cwd, args) {
   try {
-    return execFileSync2("git", ["-C", cwd, ...args], {
+    return execFileSync3("git", ["-C", cwd, ...args], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
@@ -3296,21 +3395,21 @@ function repositoryHints(cwd = process.cwd()) {
 }
 
 // src/hook-trust.ts
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync8, rmSync, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join8 } from "node:path";
+import { mkdirSync as mkdirSync8, readFileSync as readFileSync9, rmSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { join as join9 } from "node:path";
 var HOSTS_REQUIRING_TRUST = ["codex"];
 var FILE = "hook-trust.json";
 var key = (host, set) => set === "guidance" ? host : `${host}:${set}`;
 function read(environment) {
   try {
-    const parsed = JSON.parse(readFileSync8(join8(configHome(environment), FILE), "utf8"));
+    const parsed = JSON.parse(readFileSync9(join9(configHome(environment), FILE), "utf8"));
     return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
   }
 }
 function pushCheckAwaitingFile(environment, host) {
-  return join8(configHome(environment), `${host}-push-check-awaiting-first-run`);
+  return join9(configHome(environment), `${host}-push-check-awaiting-first-run`);
 }
 function forget(path) {
   try {
@@ -3320,13 +3419,13 @@ function forget(path) {
 }
 function write(environment, marks) {
   try {
-    mkdirSync7(configHome(environment), { recursive: true, mode: 448 });
-    writeFileSync5(join8(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
+    mkdirSync8(configHome(environment), { recursive: true, mode: 448 });
+    writeFileSync6(join9(configHome(environment), FILE), JSON.stringify(marks) + "\n", {
       mode: 384
     });
     for (const host of HOSTS_REQUIRING_TRUST) {
       const file = pushCheckAwaitingFile(environment, host);
-      if (awaiting(marks[key(host, "push-check")])) writeFileSync5(file, "", { mode: 384 });
+      if (awaiting(marks[key(host, "push-check")])) writeFileSync6(file, "", { mode: 384 });
       else forget(file);
     }
   } catch {
@@ -3460,6 +3559,14 @@ async function runGuidance(options) {
       return 0;
     }
     if (options.hook === "codex") noteHookFired(options.environment, "codex");
+    if (!projectScoped && event === "SessionStart")
+      retireCheckoutRuntime({
+        cwd: options.cwd,
+        host: options.hook,
+        repositoryId: agents[0].repositoryId,
+        controlPlane: agents[0].controlPlane,
+        environment: options.environment
+      });
     const loaded = await loadGuidance({
       agent: agents[0],
       environment: options.environment,
@@ -3467,12 +3574,11 @@ async function runGuidance(options) {
       hook: options.hook,
       ...options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}
     });
-    if (event === "SessionStart")
-      startSelfUpdateIfDue(newerVersionPublished(), {
-        environment: options.environment,
-        ...options.startUpdate ? { run: options.startUpdate } : {},
-        ...options.now ? { now: options.now } : {}
-      });
+    startSelfUpdateIfDue(newerVersionPublished(), {
+      environment: options.environment,
+      ...options.startUpdate ? { run: options.startUpdate } : {},
+      ...options.now ? { now: options.now } : {}
+    });
     const sessionId = identifier(record.session_id);
     const agentId = identifier(record.agent_id);
     recordGuidanceContext(

package/dist/guidance-runtime.d.ts

@@ -10,6 +10,32 @@ export declare function installGuidanceRuntime(options: Scope & {
     /** Digest of the final, already-validated project MCP configuration. */
     configurationDigest: string;
 }): void;
+export type RetireOutcome = "retired" | "absent" | "kept";
+/**
+ * Switches off the older per-repository hook in one checkout, without touching
+ * any file in the repository.
+ *
+ * Releases before 1.0.8 put a hook in the checkout's `.claude/settings.json`
+ * or `.codex/config.toml` whose command is the wrapper below. That wrapper
+ * reads `current.json` from this checkout's runtime directory before anything
+ * else, outside its own try, and its outer catch swallows the failure: with
+ * the manifest gone it prints nothing and fetches nothing. So renaming the
+ * manifest aside silences it for every later session, while the tracked hook
+ * entry stays exactly as the team committed it.
+ *
+ * Called by the user-scope hook at session start, only once it has found this
+ * checkout's connection, so a checkout is switched off only where the
+ * user-scope hook is already serving the guidance. Only the directory for this
+ * checkout, connection and host is touched, and only when the manifest proves
+ * it is ours (owner and scope key). Never throws and never prints.
+ */
+export declare function retireCheckoutRuntime(input: {
+    cwd: string;
+    host: "codex" | "claude";
+    repositoryId: string;
+    controlPlane: string;
+    environment: NodeJS.ProcessEnv;
+}): RetireOutcome;
 /** Stable, dependency-free wrapper. Current policy exists only in the authenticated server response. */
 export declare function guidanceRuntimeCommand(host: "codex" | "claude", repositoryId: string, controlPlane: string): string;
 export {};

package/dist/guidance-runtime.js

@@ -2,7 +2,8 @@ import { createHash, randomBytes } from "node:crypto";
 import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ensureStoreDirectory } from "./store.js";
+import { execFileSync } from "node:child_process";
+import { configHome, ensureStoreDirectory } from "./store.js";
 import { GUIDANCE_UNAVAILABLE } from "./guidance.js";
 const OWNER = "balladeer-guidance-runtime/1";
 const HEX = /^[a-f0-9]{64}$/;
@@ -114,6 +115,75 @@ export function installGuidanceRuntime(options) {
         }
     }
 }
+/**
+ * Switches off the older per-repository hook in one checkout, without touching
+ * any file in the repository.
+ *
+ * Releases before 1.0.8 put a hook in the checkout's `.claude/settings.json`
+ * or `.codex/config.toml` whose command is the wrapper below. That wrapper
+ * reads `current.json` from this checkout's runtime directory before anything
+ * else, outside its own try, and its outer catch swallows the failure: with
+ * the manifest gone it prints nothing and fetches nothing. So renaming the
+ * manifest aside silences it for every later session, while the tracked hook
+ * entry stays exactly as the team committed it.
+ *
+ * Called by the user-scope hook at session start, only once it has found this
+ * checkout's connection, so a checkout is switched off only where the
+ * user-scope hook is already serving the guidance. Only the directory for this
+ * checkout, connection and host is touched, and only when the manifest proves
+ * it is ours (owner and scope key). Never throws and never prints.
+ */
+export function retireCheckoutRuntime(input) {
+    try {
+        const base = join(configHome(input.environment), "guidance-runtime-v1");
+        // Most laptops never had the older form: one stat and nothing else.
+        try {
+            lstatSync(base);
+        }
+        catch {
+            return "absent";
+        }
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            cwd: input.cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 500,
+            maxBuffer: 8192,
+        }).trim();
+        if (root.length === 0)
+            return "absent";
+        const key = guidanceRuntimeKey({
+            root,
+            host: input.host,
+            repositoryId: input.repositoryId,
+            controlPlane: input.controlPlane,
+        });
+        const directory = join(base, key);
+        const manifestPath = join(directory, "current.json");
+        try {
+            checkDirectory(directory);
+        }
+        catch {
+            return "absent";
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(readPrivate(manifestPath, 4096).toString("utf8"));
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? "absent" : "kept";
+        }
+        if (manifest?.owner !== OWNER || manifest.scopeKey !== key)
+            return "kept";
+        // Renamed, not deleted: the pinned runtime stays beside it, and an
+        // explicit install of the older form would simply write a new manifest.
+        renameSync(manifestPath, join(directory, "retired.json"));
+        return "retired";
+    }
+    catch {
+        return "kept";
+    }
+}
 /** Stable, dependency-free wrapper. Current policy exists only in the authenticated server response. */
 export function guidanceRuntimeCommand(host, repositoryId, controlPlane) {
     // Keep this readable: it is the exact code the host asks a person to trust once.

package/dist/self-update.d.ts

@@ -29,10 +29,10 @@ export declare function selfUpdateState(environment: NodeJS.ProcessEnv): SelfUpd
  */
 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
+ * Start the update when the server named a newer release and an attempt
+ * toward it is due (`due`). Answers whether one was started, for the caller's own
  * 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
+ * leaves no stamp, so the next hook fire 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,7 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
+import { older } from "./currency.js";
 import { HOOK_SPECIFIER } from "./release.js";
 import { configHome } from "./store.js";
 /**
@@ -24,10 +25,22 @@ import { configHome } from "./store.js";
  * 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.
+ *
+ * What changed on 1 October 2026, from Robert's own laptop: it stayed on
+ * 1.0.16 through two releases while in use all day. Two rules held it. Only a
+ * session start began an install, and his sessions run for days, so the hooks
+ * that did fire (a prompt, a subagent) never asked. And the day's stamp was
+ * one stamp for every version: an attempt toward 1.0.15 at 03:20 held back
+ * 1.0.17 until 03:20 the next day, though a manual update had already passed
+ * 1.0.15. Now any guidance hook fire can begin the install, and a release
+ * newer than the one the last attempt aimed at may begin one an hour after
+ * it, rather than a day.
  */
 const STAMP = "self-update.json";
 const STATE = "self-update-state.json";
 const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const VERSION = /^\d{1,4}\.\d{1,4}\.\d{1,4}$/;
 /** 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}$/;
@@ -37,18 +50,35 @@ function stampPath(environment) {
 function statePath(environment) {
     return join(configHome(environment), STATE);
 }
-function lastStarted(environment) {
+/** The last attempt: when it started and which release it aimed at, when it said. */
+function lastAttempt(environment) {
     const path = stampPath(environment);
     if (!existsSync(path))
-        return 0;
+        return { startedAt: 0 };
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        return typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+        const startedAt = typeof parsed.startedAt === "number" ? parsed.startedAt : 0;
+        return typeof parsed.toward === "string" && VERSION.test(parsed.toward)
+            ? { startedAt, toward: parsed.toward }
+            : { startedAt };
     }
     catch {
-        return 0;
+        return { startedAt: 0 };
     }
 }
+/**
+ * Whether an attempt toward `newer` may start now. Once a day toward the same
+ * release, so a laptop whose install keeps failing is not hammered; but a
+ * release newer than the last attempt's target is a new reason, and waits only
+ * an hour, so one stale attempt cannot hold back the next release for a day.
+ */
+function due(newer, last, now) {
+    const since = now - last.startedAt;
+    if (since >= DAY_MS)
+        return true;
+    const newerTarget = last.toward === undefined || older(last.toward, newer);
+    return newerTarget && since >= HOUR_MS;
+}
 function writePrivate(path, value, environment) {
     mkdirSync(configHome(environment), { recursive: true, mode: 0o700 });
     writeFileSync(path, JSON.stringify(value) + "\n", { mode: 0o600 });
@@ -109,17 +139,17 @@ function detached(command, args, environment) {
     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
+ * Start the update when the server named a newer release and an attempt
+ * toward it is due (`due`). Answers whether one was started, for the caller's own
  * 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
+ * leaves no stamp, so the next hook fire tries again rather than waiting
  * a day for the same failure.
  */
 export function startSelfUpdateIfDue(newer, deps) {
     if (newer === undefined)
         return false;
     const now = deps.now ?? Date.now;
-    if (now() - lastStarted(deps.environment) < DAY_MS)
+    if (!due(newer, lastAttempt(deps.environment), now()))
         return false;
     const launch = resolveLaunch(HOOK_SPECIFIER, deps.environment, deps.execPath, deps.exists);
     let started;

package/dist/wire.d.ts

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

package/dist/wire.js

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

package/package.json

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