@event4u/agent-config 14.21.0 → 14.22.0

package/dist/cli-delegate/check_update_banner.js

@@ -0,0 +1,923 @@
+#!/usr/bin/env tsx
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+
+// src/scripts/check_update_banner.ts
+import * as fs5 from "node:fs";
+import * as path5 from "node:path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+
+// src/scripts/_lib/agent_settings.ts
+import { createRequire } from "node:module";
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/scripts/_lib/user_global_paths.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+var EVENT4U_HOME_ENV = "EVENT4U_CONFIG_HOME";
+var DEFAULT_EVENT4U_ROOT_RELATIVE = path.join(".event4u", "agent-config");
+var LEGACY_XDG_ROOT_RELATIVE = path.join(".config", "agent-config");
+function expanduser(p) {
+  if (p === "~") {
+    return os.homedir();
+  }
+  if (p.startsWith("~/") || process.platform === "win32" && p.startsWith("~\\")) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+function is_absolute_like_python(p) {
+  if (process.platform === "win32") {
+    return /^[a-zA-Z]:[\\/]/.test(p) || /^([\\/]{2})[^\\/]+[\\/][^\\/]+/.test(p);
+  }
+  return p.startsWith("/");
+}
+function event4u_root(env) {
+  const env_map = env ?? process.env;
+  const override = env_map[EVENT4U_HOME_ENV];
+  if (override) {
+    return expanduser(override);
+  }
+  return path.join(os.homedir(), DEFAULT_EVENT4U_ROOT_RELATIVE);
+}
+function legacy_xdg_root() {
+  return path.join(os.homedir(), LEGACY_XDG_ROOT_RELATIVE);
+}
+function resolve_with_fallback(relative_name, options = {}) {
+  if (is_absolute_like_python(relative_name)) {
+    throw new Error(
+      `resolve_with_fallback expects a relative path, got '${relative_name}'`
+    );
+  }
+  const new_path = path.join(event4u_root(options.env ?? null), relative_name);
+  if (fs.existsSync(new_path)) {
+    return new_path;
+  }
+  const legacy_path = path.join(legacy_xdg_root(), relative_name);
+  if (fs.existsSync(legacy_path)) {
+    return legacy_path;
+  }
+  return null;
+}
+function write_target(relative_name, options = {}) {
+  if (is_absolute_like_python(relative_name)) {
+    throw new Error(`write_target expects a relative path, got '${relative_name}'`);
+  }
+  return path.join(event4u_root(options.env ?? null), relative_name);
+}
+
+// src/shared/settingsCarveOut.ts
+var SETTINGS_CARVE_OUT = [
+  {
+    key: "projection.mode",
+    reader: "src/scripts/install.ts:3409 _resolve_scoped_projection",
+    absentResolvesTo: "legacy-all",
+    reason: "The template fallback applies only when NO global settings file exists. Once a file exists, an absent key means legacy-all by documented contract, so an existing install is never silently narrowed on upgrade."
+  },
+  {
+    key: "projection.rule_workspaces",
+    reader: "src/install/rule_scope.ts:96 ruleScopeFromSettings",
+    absentResolvesTo: "null \u2014 LEGACY_ALL, i.e. every rule ships including maintainer-only ones",
+    reason: "Same upgrade contract as projection.mode, and the failure is louder: an absent list widens the projection instead of narrowing it."
+  },
+  {
+    key: "discipline_profile",
+    reader: "work_engine/_lib/agent_settings.ts:1263",
+    absentResolvesTo: "essential, unconditionally",
+    reason: "The template ships `auto`, which resolves to `off` on any measured-null model, any non-Claude host, and any host exposing no model id. Absent skips that resolution entirely and loads the essential tier everywhere."
+  },
+  {
+    key: "chat_history.frequency",
+    reader: "src/scripts/chat_history.ts:1140",
+    absentResolvesTo: "per_phase",
+    reason: "Canonical substitution is `per_turn`. Absent gives coarser capture than the shipped default \u2014 an audit-thinning change, which the class contract's own test 8 (what can the attacker HIDE) names as the severe direction."
+  },
+  {
+    key: "profile.id",
+    reader: "src/scripts/config/profiles.ts:221 resolve_profile",
+    absentResolvesTo: "the id `developer`, but a DEGRADED profile \u2014 packs: [], personas: [], hints: []",
+    reason: "Exactly the projection.mode shape: the template default is honoured only when no settings file exists. With a file present the id resolves but its profile body does not load, so the install silently loses every pack and persona."
+  },
+  {
+    key: "quality.local_auto_run",
+    reader: "src/scripts/lint_roadmap_ci_steps.ts:106",
+    absentResolvesTo: "true \u2014 which DISABLES the CI-step gate",
+    reason: "Inverted polarity, and the most dangerous row in the set: the template ships `false`, which ARMS the gate. Omitting the key would disarm a quality gate for every fresh install while the reference page says it is on."
+  },
+  {
+    key: "onboarding.onboarded",
+    reader: "src/scripts/onboarding_gate_hook.ts:99",
+    absentResolvesTo: "gate skipped, as if onboarding had already completed",
+    reason: "Absent behaves like `onboarded: true`, not like the template default `false`. Omitting it would skip the onboarding gate on precisely the fresh installs the gate exists for."
+  },
+  {
+    key: "chat_history.enabled",
+    reader: "src/scripts/chat_history.ts:1025 _read_chat_history_enabled",
+    absentResolvesTo: "false",
+    reason: "The reader falls back to false while the template ships true. This one is privacy-shaped: fixing the reader would start recording history for every install whose file lacks the key. Writing it explicitly keeps the decision visible in the file the user can read."
+  }
+];
+function carveOutKeys() {
+  return SETTINGS_CARVE_OUT.map((c) => c.key);
+}
+
+// src/scripts/_lib/agent_settings.ts
+var _require = createRequire(import.meta.url);
+var Logger = class {
+  name = "scripts._lib.agent_settings";
+  records = [];
+  info(message, ...args) {
+    this.records.push({ level: "INFO", message: _format(message, args) });
+  }
+  warning(message, ...args) {
+    this.records.push({ level: "WARNING", message: _format(message, args) });
+  }
+};
+function _format(template, args) {
+  let i = 0;
+  return template.replace(/%s/g, () => {
+    if (i < args.length) {
+      const value = args[i];
+      i += 1;
+      return _pystr(value);
+    }
+    return "%s";
+  });
+}
+function _pystr(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => _pyrepr(v)).join(", ")}]`;
+  }
+  return String(value);
+}
+function _pyrepr(value) {
+  if (typeof value === "string") {
+    return `'${value}'`;
+  }
+  return String(value);
+}
+var logger = new Logger();
+var DEFAULT_PROJECT_FILE = ".agent-settings.yml";
+var LOCAL_PROJECT_FILE = ".agent-settings.local.yml";
+var LOCAL_PROJECT_SUBDIR = ["agents", "settings"];
+function _local_settings_path(project_root) {
+  return path2.join(project_root, ...LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE);
+}
+function _canonical_settings_path(project_root) {
+  return path2.join(project_root, ...LOCAL_PROJECT_SUBDIR, DEFAULT_PROJECT_FILE);
+}
+var USER_GLOBAL_FILENAME = "agent-settings.yml";
+function DEFAULT_USER_GLOBAL_FILE() {
+  return write_target(USER_GLOBAL_FILENAME);
+}
+var USER_GLOBAL_CANONICAL_RELATIVE = "settings/.agent-settings.yml";
+function user_global_settings_paths() {
+  const paths = [];
+  const flat = resolve_with_fallback(USER_GLOBAL_FILENAME);
+  if (flat !== null) {
+    paths.push(flat);
+  }
+  const canonical = resolve_with_fallback(USER_GLOBAL_CANONICAL_RELATIVE);
+  if (canonical !== null) {
+    paths.push(canonical);
+  }
+  if (paths.length === 0) {
+    paths.push(DEFAULT_USER_GLOBAL_FILE());
+  }
+  return paths;
+}
+var MERGEABLE_KEYS = [
+  // `name`, `ide` and `personal.bot_icon` are the PRE-MIGRATION spellings.
+  // `install.ts` migrates `ide` → `personal.ide` and `pr_comment_bot_icon`
+  // into its `personal.` home, and this list was never moved with them — so
+  // the whitelist named keys the template does not have while the keys it
+  // does have were filtered out silently. A user setting either preference
+  // user-globally got no error, no warning, and no effect
+  // (road-to-capability-answerability 4.3, ADR-219).
+  //
+  // Both spellings are listed rather than replaced: a legacy file that still
+  // uses the old name keeps working, and nothing that resolved before
+  // resolves differently. `name` has no reader anywhere and no template key;
+  // it is kept only so this change stays purely additive.
+  "name",
+  "ide",
+  "personal.ide",
+  "rule_loading_tier",
+  "memory.cadence",
+  "personal.bot_icon",
+  "personal.pr_comment_bot_icon",
+  "personal.autonomy",
+  // Knowledge-card global cross-project sharing is a USER-GLOBAL setting
+  // (ADR-100 / road-to-structure-grounding-v2). Whitelisted so the
+  // ~/.event4u/agent-config/agent-settings.yml values are honoured.
+  "knowledge.global_sharing.enabled",
+  "knowledge.global_sharing.allowed_tiers",
+  "knowledge.global_sharing.redaction.enabled",
+  "knowledge.global_sharing.redaction.halt_on_trigger",
+  "knowledge.global_sharing.auto_promote_threshold",
+  "knowledge.global_sharing.freshness.hypothesis_after_days",
+  "knowledge.global_sharing.freshness.stale_after_days"
+];
+var TEMPLATE_RELATIVE = path2.join("src", "config", "agent-settings.template.yml");
+var _PACKAGE_ROOT = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+function default_template_path() {
+  return path2.join(_PACKAGE_ROOT, TEMPLATE_RELATIVE);
+}
+function _is_placeholder(value) {
+  return typeof value === "string" && /^__[A-Z0-9_]+__$/.test(value);
+}
+function _prune_template(tree, excluded, prefix = "") {
+  const out = {};
+  for (const [key, value] of Object.entries(tree)) {
+    const dotted = prefix === "" ? key : `${prefix}.${key}`;
+    if (excluded.has(dotted) || _is_placeholder(value)) {
+      continue;
+    }
+    if (_is_plain_dict(value)) {
+      const child = _prune_template(value, excluded, dotted);
+      if (Object.keys(child).length > 0) {
+        out[key] = child;
+      }
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}
+var _template_defaults_cache = null;
+function template_defaults(template_path) {
+  const use_cache = template_path === void 0;
+  if (use_cache && _template_defaults_cache !== null) {
+    return _deepcopy(_template_defaults_cache);
+  }
+  const parsed = _read_yaml(template_path ?? default_template_path()) ?? {};
+  const pruned = _prune_template(parsed, new Set(carveOutKeys()));
+  if (use_cache) {
+    _template_defaults_cache = pruned;
+  }
+  return _deepcopy(pruned);
+}
+var ANCHOR_AGENT_SETTINGS = "agent-settings";
+var ANCHOR_AGENTS_DIR = "agents-dir";
+var ANCHOR_GIT = "git";
+var _AGENTS_DIR_MARKERS = [
+  "roadmaps",
+  "settings/.ai-council.yml",
+  "roadmaps-progress.md",
+  // `overrides/` is the guaranteed minimal-consumer surface (ADR-020).
+  // Replaced the retired `.event4u-bridge.yml` marker (ADR-020 amendment
+  // 2026-07-13) so a bare consumer `agents/` dir stays anchorable.
+  "overrides"
+];
+var _LEGACY_ANCHOR_ENV = "AGENT_CONFIG_LEGACY_ANCHOR";
+function _exists(p) {
+  try {
+    fs2.lstatSync(p);
+    fs2.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function _is_dir(p) {
+  try {
+    return fs2.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function _is_file(p) {
+  try {
+    return fs2.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function _resolve(p) {
+  const absolute = path2.resolve(p);
+  try {
+    return fs2.realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+function _ancestor_chain(start) {
+  const chain = [];
+  let cursor = start;
+  for (; ; ) {
+    chain.push(cursor);
+    const parent = path2.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return chain;
+}
+function _boundary_anchor_at(dir) {
+  const agents_dir = path2.join(dir, "agents");
+  if (_is_dir(agents_dir)) {
+    for (const marker of _AGENTS_DIR_MARKERS) {
+      if (_exists(path2.join(agents_dir, marker))) {
+        return ANCHOR_AGENTS_DIR;
+      }
+    }
+  }
+  if (_exists(path2.join(dir, ".git"))) {
+    return ANCHOR_GIT;
+  }
+  return null;
+}
+function find_project_root_with_anchor(start) {
+  const current = _exists(start) ? _resolve(start) : start;
+  const legacy = process.env[_LEGACY_ANCHOR_ENV] === "1";
+  const chain = _ancestor_chain(current);
+  if (legacy) {
+    for (const candidate of chain) {
+      if (_exists(path2.join(candidate, ".git"))) {
+        return [candidate, ANCHOR_GIT];
+      }
+    }
+    return null;
+  }
+  for (const candidate of chain) {
+    const anchor = _boundary_anchor_at(candidate);
+    if (anchor !== null) {
+      return [candidate, anchor];
+    }
+  }
+  let outermost = null;
+  for (const candidate of chain) {
+    if (_exists(path2.join(candidate, DEFAULT_PROJECT_FILE))) {
+      outermost = candidate;
+    }
+  }
+  if (outermost !== null) {
+    return [outermost, ANCHOR_AGENT_SETTINGS];
+  }
+  return null;
+}
+function find_project_root(start) {
+  const result = find_project_root_with_anchor(start);
+  return result !== null ? result[0] : null;
+}
+function _resolve_cascade_paths(cwd, project_path) {
+  if (cwd === null) {
+    const legacy = project_path ? project_path : DEFAULT_PROJECT_FILE;
+    const parent = path2.dirname(legacy);
+    return [legacy, _canonical_settings_path(parent), _local_settings_path(parent)];
+  }
+  const root = find_project_root(cwd);
+  if (root === null) {
+    const legacy = project_path ? project_path : DEFAULT_PROJECT_FILE;
+    const parent = path2.dirname(legacy);
+    return [legacy, _canonical_settings_path(parent), _local_settings_path(parent)];
+  }
+  const cwd_resolved = _resolve(cwd);
+  const chain = [];
+  let cursor = cwd_resolved;
+  for (; ; ) {
+    chain.push(cursor);
+    if (cursor === root) {
+      break;
+    }
+    const parent = path2.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  chain.reverse();
+  return [
+    ...chain.map((d) => path2.join(d, DEFAULT_PROJECT_FILE)),
+    _canonical_settings_path(root),
+    _local_settings_path(root)
+  ];
+}
+function load_agent_settings(options = {}) {
+  const project_path = options.project_path ?? null;
+  const user_global_path = options.user_global_path ?? null;
+  const verbose = options.verbose ?? false;
+  const cwd = options.cwd ?? null;
+  const template_path = options.template_path ?? null;
+  const user_global_raw = {};
+  for (const p of user_global_path ? [user_global_path] : user_global_settings_paths()) {
+    _deep_merge(user_global_raw, _read_yaml(p) ?? {});
+  }
+  const [user_global_filtered, ignored] = _filter_whitelist(user_global_raw, MERGEABLE_KEYS);
+  if (verbose && ignored.length > 0) {
+    logger.info(
+      "agent_settings: ignored non-whitelisted user-global keys: %s",
+      [...ignored].sort()
+    );
+  }
+  const cascade = _resolve_cascade_paths(cwd, project_path);
+  const merged = template_defaults(template_path ?? void 0);
+  _deep_merge(merged, user_global_filtered);
+  for (const p of cascade) {
+    const layer = _read_yaml(p) ?? {};
+    if (Object.keys(layer).length > 0) {
+      _deep_merge(merged, layer);
+    }
+  }
+  _warn_removed_always_on_keys(merged);
+  return merged;
+}
+var REMOVED_KEYS = /* @__PURE__ */ new Map([
+  ["subagents.enabled", "always-on orchestration"],
+  ["subagents.auto", "always-on orchestration"],
+  ["subagents.host_capabilities", "always-on orchestration"],
+  ["subagents.budget_routing", "always-on orchestration"],
+  ["ai_team.enabled", "always-on orchestration"],
+  ["hooks.turn_end_gate.enabled", "the turn-end gate is always armed"],
+  ["hooks.turn_end_gate.promissory", "the turn-end gate is always armed"],
+  ["hooks.turn_end_gate.language", "the turn-end gate is always armed"],
+  ["hooks.turn_end_gate.verification", "the turn-end gate is always armed"],
+  ["telegraph.speak_scope", "the rule body states its own scope; compile_router gates on telegraph.speak alone"],
+  ["chat_history.max_size_kb", "the rotate command takes --max-kb from argv; session-count pruning bounds the file"],
+  ["chat_history.on_overflow", "the overflow mode comes from the rotate command --mode argv"],
+  ["quality.wait_for_remote_ci", "whether to poll follows from the push plus a detectable remote pipeline"],
+  ["legal_review_prep.consented_at", "the provenance sidecar settings:set writes and consentVerdict reads"],
+  ["worktrees.mode", "the user asking for a worktree in the chat; creation is instruction-only and hardcoded"]
+]);
+var _warnedRemovedKeys = /* @__PURE__ */ new Set();
+function _readDottedSettingsPath(root, dotted) {
+  let node = root;
+  for (const part of dotted.split(".")) {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      return void 0;
+    }
+    node = node[part];
+  }
+  return node;
+}
+function _warn_removed_always_on_keys(merged) {
+  for (const [key, reason] of REMOVED_KEYS) {
+    if (_warnedRemovedKeys.has(key)) {
+      continue;
+    }
+    if (_readDottedSettingsPath(merged, key) === void 0) {
+      continue;
+    }
+    _warnedRemovedKeys.add(key);
+    process.stderr.write(`${key} was removed (${reason}); ignored.
+`);
+  }
+}
+function _read_yaml(p) {
+  if (!_is_file(p)) {
+    return null;
+  }
+  let YAML;
+  try {
+    YAML = _require("yaml");
+  } catch {
+    return null;
+  }
+  let data;
+  try {
+    const text = fs2.readFileSync(p, "utf-8");
+    data = YAML.parse(text, { version: "1.1" });
+    if (data === null || data === void 0) {
+      data = {};
+    }
+  } catch (err) {
+    if (_is_yaml_error(err) || _is_os_error(err)) {
+      logger.warning("agent_settings: unreadable or malformed YAML at %s", p);
+      return null;
+    }
+    throw err;
+  }
+  return _is_plain_dict(data) ? data : null;
+}
+function _is_yaml_error(err) {
+  if (err instanceof Error) {
+    return err.name.startsWith("YAML") || err.name === "Error" || err.name === "TypeError";
+  }
+  return false;
+}
+function _is_os_error(err) {
+  return typeof err === "object" && err !== null && "code" in err && typeof err.code === "string";
+}
+function _filter_whitelist(raw, allowed) {
+  const filtered = {};
+  for (const dotted of allowed) {
+    const value = _get_dotted(raw, dotted);
+    if (value !== null && value !== void 0) {
+      _set_dotted(filtered, dotted, value);
+    }
+  }
+  const ignored = _leaf_paths(raw).filter((p) => !allowed.includes(p));
+  return [filtered, ignored];
+}
+function _get_dotted(data, dotted) {
+  let cursor = data;
+  for (const part of dotted.split(".")) {
+    if (!_is_plain_dict(cursor) || !(part in cursor)) {
+      return null;
+    }
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+function _set_dotted(target, dotted, value) {
+  const parts = dotted.split(".");
+  let cursor = target;
+  for (const part of parts.slice(0, -1)) {
+    let nxt = cursor[part];
+    if (nxt === void 0) {
+      nxt = {};
+      cursor[part] = nxt;
+    }
+    if (!_is_plain_dict(nxt)) {
+      nxt = {};
+      cursor[part] = nxt;
+    }
+    cursor = nxt;
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+function _leaf_paths(data, prefix = "") {
+  const paths = [];
+  for (const [key, value] of Object.entries(data)) {
+    const p = prefix ? `${prefix}.${key}` : key;
+    if (_is_plain_dict(value) && Object.keys(value).length > 0) {
+      paths.push(..._leaf_paths(value, p));
+    } else {
+      paths.push(p);
+    }
+  }
+  return paths;
+}
+function _deep_merge(dst, src) {
+  for (const [key, value] of Object.entries(src)) {
+    if (_is_plain_dict(value) && _is_plain_dict(dst[key])) {
+      _deep_merge(dst[key], value);
+    } else {
+      dst[key] = value;
+    }
+  }
+}
+function _deepcopy(value) {
+  if (Array.isArray(value)) {
+    return value.map((v) => _deepcopy(v));
+  }
+  if (_is_plain_dict(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = _deepcopy(v);
+    }
+    return out;
+  }
+  return value;
+}
+function _is_plain_dict(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/scripts/_lib/scan_scope.ts
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+var DeadScopeError = class extends Error {
+  gate;
+  constructor(gate, message) {
+    super(message);
+    this.name = "DeadScopeError";
+    this.gate = gate;
+  }
+};
+function assertWatchlistResolves(opts) {
+  const resolved = opts.candidates.filter((rel) => {
+    try {
+      return fs3.statSync(path3.join(opts.repoRoot, rel)).isFile();
+    } catch {
+      return false;
+    }
+  });
+  if (resolved.length === 0) {
+    throw new DeadScopeError(
+      opts.gate,
+      `${opts.gate}: none of its ${opts.candidates.length} guarded path(s) exist under ${opts.repoRoot} \u2014 the guard is watching phantoms and can never fire. Checked: ${opts.candidates.join(", ")}`
+    );
+  }
+  return resolved;
+}
+
+// src/scripts/_lib/update_check.ts
+import { randomBytes } from "node:crypto";
+import * as fs4 from "node:fs";
+import * as path4 from "node:path";
+var PACKAGE_NAME = "@event4u/agent-config";
+var NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+var FETCH_TIMEOUT_S = 1;
+var CHECK_WINDOW_MS = 24 * 60 * 60 * 1e3;
+var STATE_FILENAME = "update-check.json";
+var DEFAULT_STATE_PATH = write_target(STATE_FILENAME);
+function _resolve_state_path() {
+  const found = resolve_with_fallback(STATE_FILENAME);
+  if (found !== null) {
+    return found;
+  }
+  return DEFAULT_STATE_PATH;
+}
+async function fetch_latest_from_npm(options = {}) {
+  const timeout = options.timeout ?? FETCH_TIMEOUT_S;
+  const url = options.url ?? NPM_REGISTRY_URL;
+  const fetch_impl = options.fetch_impl ?? fetch;
+  try {
+    const resp = await fetch_impl(url, {
+      headers: {
+        Accept: "application/json",
+        "User-Agent": "agent-config-update-check"
+      },
+      signal: AbortSignal.timeout(timeout * 1e3)
+    });
+    const payload = await resp.json();
+    if (payload !== null && typeof payload === "object" && !Array.isArray(payload)) {
+      const version = payload.version;
+      if (typeof version === "string" && version.trim()) {
+        return version.trim();
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+function _read_state(state_path) {
+  try {
+    const raw = fs4.readFileSync(state_path, "utf-8");
+    const data = JSON.parse(raw);
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+      return data;
+    }
+  } catch {
+  }
+  return {};
+}
+function _write_state(state_path, payload) {
+  const parent = path4.dirname(state_path);
+  fs4.mkdirSync(parent, { recursive: true });
+  const tmp = path4.join(parent, `.update-check-${randomBytes(8).toString("hex")}`);
+  try {
+    const sorted = {};
+    for (const key of Object.keys(payload).sort()) {
+      sorted[key] = payload[key];
+    }
+    fs4.writeFileSync(tmp, JSON.stringify(sorted, null, 2), { encoding: "utf-8", mode: 384 });
+    fs4.chmodSync(tmp, 384);
+    fs4.renameSync(tmp, state_path);
+  } catch (err) {
+    try {
+      fs4.unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+function _should_check(state, now) {
+  const last = state.last_check_utc;
+  if (typeof last !== "string") {
+    return true;
+  }
+  let normalized = last.replace(/Z/g, "+00:00");
+  if (!/[+-]\d{2}:?\d{2}$/.test(normalized)) {
+    normalized = `${normalized}+00:00`;
+  }
+  const last_ms = Date.parse(normalized);
+  if (Number.isNaN(last_ms)) {
+    return true;
+  }
+  return now.getTime() - last_ms >= CHECK_WINDOW_MS;
+}
+function _format_banner(latest, installed) {
+  return `\u2139\uFE0F  agent-config ${latest} available (you have ${installed}).
+    Update: npx ${PACKAGE_NAME} update`;
+}
+function _int_or_zero(part) {
+  const trimmed = part.trim();
+  if (/^[+-]?\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+  return 0;
+}
+function _is_newer(latest, installed) {
+  const parse = (v) => {
+    const core = v.replace(/^v+/, "").split("-")[0] ?? "";
+    const parts = core.split(".");
+    const out = [];
+    for (const p of parts.slice(0, 3)) {
+      out.push(_int_or_zero(p));
+    }
+    while (out.length < 3) {
+      out.push(0);
+    }
+    return [out[0], out[1], out[2]];
+  };
+  const a = parse(latest);
+  const b = parse(installed);
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] > b[i]) {
+      return true;
+    }
+    if (a[i] < b[i]) {
+      return false;
+    }
+  }
+  return false;
+}
+function _format_utc(d) {
+  return d.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+async function check_for_update(installed_version, options = {}) {
+  const env = options.env ?? process.env;
+  if (env.AGENT_CONFIG_NO_UPDATE_CHECK === "1") {
+    return null;
+  }
+  if (env.CI === "1" || env.CI === "true" || env.GITHUB_ACTIONS === "true") {
+    return null;
+  }
+  const settings_enabled = options.settings_enabled ?? true;
+  if (!settings_enabled) {
+    return null;
+  }
+  let is_tty = options.is_tty ?? null;
+  if (is_tty === null) {
+    is_tty = Boolean(process.stdout.isTTY);
+  }
+  if (!is_tty) {
+    return null;
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const read_path = options.state_path ?? _resolve_state_path();
+  const write_path = options.state_path ?? DEFAULT_STATE_PATH;
+  const state = _read_state(read_path);
+  if (!_should_check(state, now)) {
+    const latest2 = state.last_seen_version;
+    if (typeof latest2 === "string" && _is_newer(latest2, installed_version)) {
+      return _format_banner(latest2, installed_version);
+    }
+    return null;
+  }
+  const fetcher = options.fetcher ?? (() => fetch_latest_from_npm());
+  const latest = await fetcher();
+  const fallback_seen = Object.prototype.hasOwnProperty.call(state, "last_seen_version") ? state.last_seen_version : "";
+  const payload = {
+    last_check_utc: _format_utc(now),
+    // Python: `latest or state.get("last_seen_version", "")`.
+    last_seen_version: latest ? latest : fallback_seen,
+    installed_version
+  };
+  try {
+    _write_state(write_path, payload);
+  } catch (err) {
+    const code = err.code;
+    if (typeof code !== "string") {
+      throw err;
+    }
+  }
+  if (!latest || !_is_newer(latest, installed_version)) {
+    return null;
+  }
+  return _format_banner(latest, installed_version);
+}
+
+// src/scripts/check_update_banner.ts
+var _HERE = fileURLToPath2(import.meta.url);
+var ROOT = path5.resolve(path5.dirname(_HERE), "..", "..");
+var DOC = `Thin CLI wrapper: emit the daily update-check banner to stderr.
+
+Invoked by the \`scripts/agent-config\` dispatcher **after** a
+subcommand finishes. Never raises, never exits non-zero \u2014 banner is
+best-effort. See \`scripts/_lib/update_check.ts\` for the decision
+logic.
+
+Usage:
+    ./scripts-run src/scripts/check_update_banner [--installed-version X.Y.Z]
+
+When \`--installed-version\` is omitted, reads \`package.json\` next to
+the package root (\`$PACKAGE_ROOT/package.json\`).`;
+function _read_installed_version(package_root) {
+  const candidate = path5.join(package_root, "package.json");
+  try {
+    const data = JSON.parse(fs5.readFileSync(candidate, "utf-8"));
+    const version = data["version"];
+    if (typeof version === "string" && version.trim()) {
+      return version.trim();
+    }
+  } catch {
+  }
+  return "";
+}
+function _read_settings_flag(cwd) {
+  let settings;
+  try {
+    settings = load_agent_settings({ cwd });
+  } catch {
+    return true;
+  }
+  const block = settings["update_check"];
+  if (block && typeof block === "object" && !Array.isArray(block)) {
+    if (block["enabled"] === false) {
+      return false;
+    }
+  }
+  return true;
+}
+function parse_args(argv) {
+  let installed_version = "";
+  let cwd = process.cwd();
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--installed-version") {
+      installed_version = argv[++i] ?? "";
+    } else if (arg.startsWith("--installed-version=")) {
+      installed_version = arg.slice("--installed-version=".length);
+    } else if (arg === "--cwd") {
+      cwd = argv[++i] ?? cwd;
+    } else if (arg.startsWith("--cwd=")) {
+      cwd = arg.slice("--cwd=".length);
+    } else if (arg === "--help" || arg === "-h") {
+      help = true;
+    }
+  }
+  return { installed_version, cwd, help };
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parse_args(argv);
+  if (args.help) {
+    process.stdout.write(DOC + "\n");
+    return 0;
+  }
+  if (!args.installed_version) {
+    try {
+      assertWatchlistResolves({
+        gate: "check_update_banner",
+        candidates: ["package.json"],
+        repoRoot: ROOT
+      });
+    } catch (err) {
+      if (err instanceof DeadScopeError) {
+        process.stderr.write(`\u274C  ${err.message}
+`);
+        return 0;
+      }
+      throw err;
+    }
+  }
+  const installed = args.installed_version || _read_installed_version(ROOT);
+  if (!installed) {
+    return 0;
+  }
+  let cwd;
+  try {
+    cwd = path5.resolve(args.cwd);
+  } catch {
+    cwd = ROOT;
+  }
+  const enabled = _read_settings_flag(cwd);
+  let banner;
+  try {
+    banner = await check_for_update(installed, { settings_enabled: enabled });
+  } catch {
+    return 0;
+  }
+  if (banner) {
+    process.stderr.write(banner + "\n");
+  }
+  return 0;
+}
+function _isCliEntry() {
+  if (process.argv[1] === void 0) {
+    return false;
+  }
+  if (true) {
+    if (path5.basename(process.argv[1], ".js") === "check_update_banner") {
+      return true;
+    }
+  }
+  const argvUrl = pathToFileURL(path5.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs5.realpathSync(fileURLToPath2(import.meta.url));
+    const argv = fs5.realpathSync(path5.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+if (_isCliEntry() || process.argv[1] === _HERE) {
+  void main().then((code) => process.exit(code));
+}
+export {
+  ROOT,
+  _read_installed_version,
+  _read_settings_flag,
+  main,
+  parse_args
+};