balladeer 1.0.18 → 1.0.20

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.20";
 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/headless-agent.d.ts

@@ -133,6 +133,7 @@ export declare function verifyLogin(client: HeadlessClient, options: Readonly<{
     cwd: string;
     spawn?: SpawnLike;
     killGroup?: KillGroup;
+    deadline?: number;
 }>): Promise<LoginCheck>;
 /**
  * The client to run, or none. `auto` tries the hook's own client first, then
@@ -144,6 +145,7 @@ export declare function resolveClient(requested: HeadlessClient | "auto", option
     prefer?: HeadlessClient;
     spawn?: SpawnLike;
     killGroup?: KillGroup;
+    deadline?: number;
 }>): Promise<LoginCheck | undefined>;
 /**
  * The last JSON object in a piece of text.

package/dist/headless-agent.js

@@ -99,13 +99,15 @@ export function codexArguments(input) {
  * dropped, the same way the compatibility canary treats them.
  */
 export async function verifyLogin(client, options) {
+    if (options.deadline !== undefined && Date.now() >= options.deadline)
+        return { client, verified: false };
     const env = agentEnvironment(options.env);
     const run = await runOwnedProcess({
         command: clientBinary(client, options.env),
         args: client === "claude" ? ["auth", "status", "--json"] : ["login", "status"],
         cwd: options.cwd,
         env,
-        timeoutMs: 15_000,
+        timeoutMs: Math.max(1, Math.min(15_000, (options.deadline ?? Number.POSITIVE_INFINITY) - Date.now())),
         maxOutputBytes: 64 * 1024,
         ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
         ...(options.killGroup === undefined ? {} : { killGroup: options.killGroup }),
@@ -136,6 +138,8 @@ export async function resolveClient(requested, options) {
             ? ["codex", "claude"]
             : ["claude", "codex"];
     for (const client of order) {
+        if (options.deadline !== undefined && Date.now() >= options.deadline)
+            return undefined;
         const check = await verifyLogin(client, options);
         if (check.verified)
             return check;