balladeer 1.0.17 → 1.0.19

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.17";
+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 {
@@ -2403,6 +2430,9 @@ function parseGuidance(value, agent) {
   return value;
 }
 function guidanceEndpoint(agent) {
+  return agentEndpoint(agent, "/api/agent-guidance");
+}
+function agentEndpoint(agent, pathname) {
   const url = new URL(agent.mcpUrl);
   const expected = new URL(agent.controlPlane);
   if (url.origin !== expected.origin || url.protocol !== "https:" || url.pathname !== "/api/mcp" || url.username || url.password || url.hash || !UUID.test(agent.workspaceId) || !UUID.test(agent.repositoryId))
@@ -2415,7 +2445,7 @@ function guidanceEndpoint(agent) {
       throw new Error("invalid_guidance_scope");
     url.searchParams.set(key2, value);
   }
-  url.pathname = "/api/agent-guidance";
+  url.pathname = pathname;
   return url;
 }
 function readJson(path) {
@@ -2625,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 {
@@ -2713,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;
   }
@@ -2723,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 {
@@ -2732,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)
@@ -3148,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;
@@ -3174,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));
@@ -3259,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();
@@ -3293,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 {
@@ -3317,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 {
@@ -3457,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,
@@ -3464,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/guidance.d.ts

@@ -12,6 +12,13 @@ export type GuidanceEvent = "SessionStart" | "SubagentStart" | "UserPromptSubmit
 export declare const 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.";
 export declare function parseGuidance(value: unknown, agent: StoredAgent): GuidanceDocument;
 export declare function guidanceEndpoint(agent: StoredAgent): URL;
+/**
+ * A route of the server this repository's agent connection belongs to, scoped
+ * to its workspace and repository the way `/api/agent-guidance` is: same
+ * origin as the connection's MCP address, https only, and the scope in the
+ * query exactly once.
+ */
+export declare function agentEndpoint(agent: StoredAgent, pathname: string): URL;
 export declare function guidanceScopeKey(agent: StoredAgent): string;
 export type GuidanceLoad = Readonly<{
     status: "fresh" | "revalidated" | "unavailable";

package/dist/guidance.js

@@ -34,6 +34,15 @@ export function parseGuidance(value, agent) {
     return value;
 }
 export function guidanceEndpoint(agent) {
+    return agentEndpoint(agent, "/api/agent-guidance");
+}
+/**
+ * A route of the server this repository's agent connection belongs to, scoped
+ * to its workspace and repository the way `/api/agent-guidance` is: same
+ * origin as the connection's MCP address, https only, and the scope in the
+ * query exactly once.
+ */
+export function agentEndpoint(agent, pathname) {
     const url = new URL(agent.mcpUrl);
     const expected = new URL(agent.controlPlane);
     if (url.origin !== expected.origin ||
@@ -54,7 +63,7 @@ export function guidanceEndpoint(agent) {
             throw new Error("invalid_guidance_scope");
         url.searchParams.set(key, value);
     }
-    url.pathname = "/api/agent-guidance";
+    url.pathname = pathname;
     return url;
 }
 function readJson(path) {