create-byan-agent 2.39.0 → 2.42.0

package/install/templates/.claude/hooks/lib/autodelegate-decision.js

@@ -0,0 +1,152 @@
+/**
+ * autodelegate-decision — the pure core that decides whether BYAN should hand a
+ * task to Codex (on the ChatGPT subscription, no API credit), and how hard to
+ * push. Two triggers, honest about their strength:
+ *
+ *   1. NATURE (always available, no gauge needed): the request looks like
+ *      delegable coding work (implement / write / fix / refactor / test) -> mode
+ *      'delegable-only', propose handing THIS task to Codex.
+ *   2. PRESSURE (only when a usage gauge is supplied): the estimated Claude 5h
+ *      consumption is at/above the threshold (default 80%) -> mode 'all', propose
+ *      offloading everything delegable to spare the remaining budget.
+ *   3. PERF (opt-in, off by default): a config-driven forces table says Codex is
+ *      reputed stronger for this kind of task -> mode 'perf-routed'. Honest: this
+ *      is a heuristic below BYAN's L2 perf floor, so it ships neutral (empty
+ *      table) and asserts nothing until the user populates it. See perf-routing.
+ *
+ * The red line is never crossed: only DELEGABLE natures are ever proposed —
+ * judgment / analysis / soul / verification stay on Claude. This module states
+ * that in `redLine` so the hook's nudge always carries it. Pure (no I/O): the
+ * hook is a thin shell that feeds it the request text + the F1 usage estimate.
+ */
+
+const { perfFavors } = require('./perf-routing');
+
+const DEFAULT_THRESHOLD = 80;
+const DEFAULT_INVOCATION = 'codex:codex-rescue --model gpt-5.4';
+const RED_LINE = 'delegable work only (code / mechanical) — judgment, analysis, soul and verification stay on Claude';
+
+// Verbs/nouns that mark a delegable coding task. Heuristic by construction (free
+// text has no nature field); kept deliberately conservative so conversational or
+// judgment requests do not trip it.
+const DELEGABLE_RE = new RegExp(
+  [
+    'code', 'coder', 'impl[ée]mente', 'implement', '[ée]cris', 'write', 'wire',
+    'fix', 'corrige', 'debug', 'd[ée]bogue', 'refactor', 'refactorise',
+    'test', 'tests', 'script', 'module', 'fonction', 'function', 'patch',
+    'ajoute\\s+(le|la|un|une|du)', 'build\\s+(the|a|le|la)', 'port',
+  ].join('|'),
+  'i'
+);
+
+function looksDelegable(text) {
+  return DELEGABLE_RE.test(String(text || ''));
+}
+
+// Decide the auto-delegation posture for one turn.
+// Returns { delegate, mode, pct, reason, redLine, invocation } — a stable shape.
+// mode: 'off' | 'all' | 'delegable-only' | 'none'.
+function decideAutodelegation({ requestText = '', usage = null, config = {} } = {}) {
+  const {
+    enabled = true,
+    threshold = DEFAULT_THRESHOLD,
+    invocation = DEFAULT_INVOCATION,
+  } = config;
+
+  if (!enabled) {
+    return { delegate: false, mode: 'off', pct: null, reason: 'auto-delegation disabled (toggle off)', redLine: RED_LINE, invocation };
+  }
+
+  const pct = usage && typeof usage.pct === 'number' ? usage.pct : null;
+  const delegable = looksDelegable(requestText);
+
+  if (pct != null && pct >= threshold) {
+    return {
+      delegate: true,
+      mode: 'all',
+      pct,
+      reason: `estimated Claude 5h usage ${pct}% >= ${threshold}% — propose offloading everything delegable to Codex`,
+      redLine: RED_LINE,
+      invocation,
+    };
+  }
+
+  if (delegable) {
+    return {
+      delegate: true,
+      mode: 'delegable-only',
+      pct,
+      reason: 'request looks like delegable coding work — propose handing it to Codex to spare the Claude 5h budget',
+      redLine: RED_LINE,
+      invocation,
+    };
+  }
+
+  // PERF (opt-in): the forces table (user-populated) may favor Codex for this
+  // kind of task even at low pressure. Off by default; always heuristic.
+  if (config.perfRouting) {
+    const pf = perfFavors(requestText, config.perfForces || []);
+    if (pf.favors === 'codex') {
+      return {
+        delegate: true,
+        mode: 'perf-routed',
+        pct,
+        reason: `perf heuristic favors Codex for '${pf.category}' (heuristic, NOT a measured benchmark)`,
+        redLine: RED_LINE,
+        invocation,
+      };
+    }
+  }
+
+  return {
+    delegate: false,
+    mode: 'none',
+    pct,
+    reason: pct != null
+      ? `usage ${pct}% below ${threshold}% and task not clearly delegable`
+      : 'task not clearly delegable and no usage gauge available',
+    redLine: RED_LINE,
+    invocation,
+  };
+}
+
+// Defense-in-depth: the invocation string is interpolated into BYAN's injected
+// context. It is config/installer-controlled today (safe), but sanitising before
+// interpolation closes the door on any future path feeding untrusted text in —
+// strip newlines/control chars (no context-structure injection) and cap length.
+function sanitizeForContext(value, max = 120) {
+  return String(value == null ? "" : value)
+    .replace(/[\u0000-\u001F\u007F]+/g, " ") // control chars + newlines -> space
+    .replace(/\s+/g, " ")                       // collapse whitespace runs
+    .trim()
+    .slice(0, max);
+}
+
+// Render a decision into the one-paragraph nudge injected into BYAN's context.
+// Empty string when there is nothing to propose (so the hook injects nothing).
+// The nudge is ADVISORY: it proposes, it never forces — BYAN still owns the call
+// and the red line is spelled out every time.
+function renderNudge(decision) {
+  if (!decision || !decision.delegate) return '';
+  const gauge = decision.pct != null ? ` (estimated Claude 5h usage ~${decision.pct}%)` : '';
+  const invocation = sanitizeForContext(decision.invocation) || DEFAULT_INVOCATION;
+  const scope = decision.mode === 'all'
+    ? 'Consider offloading ALL delegable work this session to Codex'
+    : decision.mode === 'perf-routed'
+      ? 'Codex is heuristically favored for this kind of task (not a measured benchmark) — consider handing it over'
+      : 'This looks like delegable coding work — consider handing it to Codex';
+  return [
+    `[BYAN auto-delegate]${gauge}: ${scope} via \`${invocation}\` `
+      + '(runs on the ChatGPT subscription, no API credit).',
+    `Red line: ${decision.redLine}. This is advisory — you decide, and you still verify Codex's output before commit.`,
+  ].join(' ');
+}
+
+module.exports = {
+  DEFAULT_THRESHOLD,
+  DEFAULT_INVOCATION,
+  RED_LINE,
+  looksDelegable,
+  decideAutodelegation,
+  renderNudge,
+};

package/install/templates/.claude/hooks/lib/perf-routing.js

@@ -0,0 +1,47 @@
+/**
+ * perf-routing — the MECHANISM for routing a task to the pool reputed stronger
+ * for it, WITHOUT asserting an unsourced ranking.
+ *
+ * The honest ceiling (BYAN fact-check, performance domain): "model X is better
+ * at task Y" needs L2 evidence (a reproducible benchmark). A community arena such
+ * as designarena.ai is preference-vote data — below that floor. So this module
+ * ships a NEUTRAL default (DEFAULT_FORCES = []): out of the box it claims nothing
+ * and changes no routing. It provides the config-driven forces table + a matcher;
+ * populating the table with rankings (from the user's own benchmarks, or an arena
+ * taken as a weak signal) is an explicit opt-in, and every result it returns is
+ * tagged `confidence: 'heuristic'` so downstream never presents it as measured.
+ *
+ * A forces entry: { category, pattern (regex source, case-insensitive), favors:
+ * 'codex' | 'claude' }. Pure — no I/O.
+ */
+
+// Neutral by default: no unsourced perf claim ships. Populate via config.
+const DEFAULT_FORCES = [];
+
+// Return the first forces entry whose pattern matches the text, or null.
+// Malformed entries (missing pattern/favors, or an invalid regex) are skipped.
+function matchCategory(text, forces = DEFAULT_FORCES) {
+  const s = String(text || '');
+  if (!Array.isArray(forces)) return null;
+  for (const entry of forces) {
+    if (!entry || !entry.pattern || !entry.favors) continue;
+    let re;
+    try {
+      re = new RegExp(entry.pattern, 'i');
+    } catch {
+      continue; // invalid regex in a user-supplied table — skip, never throw
+    }
+    if (re.test(s)) return entry;
+  }
+  return null;
+}
+
+// Resolve the perf preference for a text: which pool the (user-supplied) table
+// favors, always tagged heuristic. { favors: 'codex'|'claude'|null, category, confidence }.
+function perfFavors(text, forces = DEFAULT_FORCES) {
+  const hit = matchCategory(text, forces);
+  if (!hit) return { favors: null, category: null, confidence: 'heuristic' };
+  return { favors: hit.favors, category: hit.category, confidence: 'heuristic' };
+}
+
+module.exports = { DEFAULT_FORCES, matchCategory, perfFavors };

package/install/templates/.claude/hooks/lib/usage-estimator.js

@@ -0,0 +1,262 @@
+/**
+ * usage-estimator — estimate Claude's rolling-5h token consumption from Claude
+ * Code's LOCAL usage accounting, so BYAN can decide when to auto-delegate to a
+ * secondary pool (Codex) BEFORE the 5h wall.
+ *
+ * The honest ceiling (stated plainly, not hidden): no provider exposes a
+ * machine-readable 5h quota, and Claude Code fetches the authoritative
+ * "/usage" figure live from Anthropic — it is NOT persisted locally. What IS
+ * local is per-session token accounting under
+ * `~/.claude/usage-data/session-meta/*.json` (real input/output token totals +
+ * start_time + duration). This module sums those over the rolling window and
+ * returns an ESTIMATE with an explicit confidence, never a false-precision
+ * figure. `pct` is only produced when a budget (the plan's rough token ceiling)
+ * is supplied — otherwise it is null (we do not invent the ceiling).
+ *
+ * Portable-core posture (PORTABLE-3): `~/.claude` is a per-machine native
+ * accelerator, NOT a BYAN source of truth. When it is absent the estimator
+ * degrades to a null/none result rather than throwing — the nature-based
+ * delegation path stays functional without any gauge.
+ *
+ * Purity: normalizeSession / sumWindowTokens / estimatePct are pure. All I/O is
+ * behind an injected `fs`, so the unit tests never touch the real home dir.
+ */
+
+const realFs = require('fs');
+const realPath = require('path');
+const os = require('os');
+
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+
+// Parse one session-meta object into { startMs, endMs, tokens }, or null when it
+// carries no usable start time. Token fields default to 0 (never NaN) so the
+// downstream sum is always safe.
+function normalizeSession(meta) {
+  if (!meta || typeof meta !== 'object') return null;
+  const startMs = Date.parse(meta.start_time);
+  if (!Number.isFinite(startMs)) return null;
+  const durationMin = Number(meta.duration_minutes) || 0;
+  const endMs = startMs + Math.max(0, durationMin) * 60 * 1000;
+  const input = Number(meta.input_tokens) || 0;
+  const output = Number(meta.output_tokens) || 0;
+  return { startMs, endMs, tokens: input + output };
+}
+
+// Sum tokens attributable to the rolling window [now-windowMs, now], pro-rating
+// a session by the fraction of its own span that overlaps the window. A
+// zero-duration session is an instant: counted fully if inside, else zero. This
+// pro-rata is the honest approximation available from per-session totals (the
+// meta has no per-message breakdown).
+function sumWindowTokens(sessions, now, windowMs = FIVE_HOURS_MS) {
+  const windowStart = now - windowMs;
+  let total = 0;
+  for (const s of sessions) {
+    if (!s) continue;
+    const span = s.endMs - s.startMs;
+    if (span <= 0) {
+      if (s.startMs >= windowStart && s.startMs <= now) total += s.tokens;
+      continue;
+    }
+    const overlap = Math.min(s.endMs, now) - Math.max(s.startMs, windowStart);
+    if (overlap <= 0) continue;
+    total += s.tokens * (overlap / span);
+  }
+  return Math.round(total);
+}
+
+// Turn an estimated token count into a percentage of a supplied budget. Without
+// a budget we return { pct: null, confidence: 'none' } — we do not fabricate the
+// ceiling. With a budget the percentage is a LOW-confidence estimate (the token
+// units are not the exact rate-limit units Anthropic meters), clamped to [0,100].
+function estimatePct(estimatedTokens, budget) {
+  if (!budget || budget <= 0) return { pct: null, confidence: 'none' };
+  const pct = Math.max(0, Math.min(100, Math.round((estimatedTokens / budget) * 100)));
+  return { pct, confidence: 'low' };
+}
+
+// Weighted token cost of one assistant message's usage block. Fresh tokens
+// (input + output + cache creation) count at full weight; cache READS are
+// weighted down (CACHE_READ_WEIGHT) because the same context is re-read from
+// cache every turn and Anthropic bills a cache hit at roughly a tenth of a fresh
+// input token — counting it at full weight would inflate a long conversation to
+// hundreds of millions of tokens (the same context re-counted each turn). This
+// yields a proportional pressure estimate, not an exact bill. Pure.
+const CACHE_READ_WEIGHT = 0.1;
+
+function sumTokensFromUsage(usage) {
+  if (!usage || typeof usage !== 'object') return 0;
+  const fresh = (Number(usage.input_tokens) || 0)
+    + (Number(usage.output_tokens) || 0)
+    + (Number(usage.cache_creation_input_tokens) || 0);
+  const cacheRead = (Number(usage.cache_read_input_tokens) || 0) * CACHE_READ_WEIGHT;
+  return Math.round(fresh + cacheRead);
+}
+
+// Sum tokens across transcript events whose timestamp lands in the rolling
+// window. Only `assistant` events carry a usage block. Pure — takes already
+// parsed events. Returns { tokens, messagesCounted }.
+function sumTranscriptWindow(events, now, windowMs = FIVE_HOURS_MS) {
+  const windowStart = now - windowMs;
+  let tokens = 0;
+  let messagesCounted = 0;
+  for (const ev of events) {
+    if (!ev || ev.type !== 'assistant' || !ev.message) continue;
+    const ts = Date.parse(ev.timestamp);
+    if (!Number.isFinite(ts) || ts < windowStart || ts > now) continue;
+    tokens += sumTokensFromUsage(ev.message.usage);
+    messagesCounted += 1;
+  }
+  return { tokens, messagesCounted };
+}
+
+// Read the LIVE per-message usage from the session transcripts under
+// ~/.claude/projects/<hash>/*.jsonl. Unlike session-meta (written at session
+// END), transcripts are appended live, so they capture the IN-PROGRESS session
+// — exactly the signal needed to react before the wall. Files untouched within
+// the window are skipped by mtime when statSync is available (perf). Corrupt
+// lines are skipped, not fatal. Returns { tokens, messagesCounted, filesRead }.
+function readTranscriptUsage({ home, now = Date.now(), windowMs = FIVE_HOURS_MS, fs = realFs, path = realPath } = {}) {
+  const root = path.join(home, '.claude', 'projects');
+  const empty = { tokens: 0, messagesCounted: 0, filesRead: 0 };
+  let projectDirs;
+  try {
+    if (!fs.existsSync(root)) return empty;
+    projectDirs = fs.readdirSync(root);
+  } catch {
+    return empty;
+  }
+  const windowStart = now - windowMs;
+  let tokens = 0;
+  let messagesCounted = 0;
+  let filesRead = 0;
+  for (const pd of projectDirs) {
+    const dir = path.join(root, pd);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter((n) => String(n).endsWith('.jsonl'));
+    } catch {
+      continue;
+    }
+    for (const name of files) {
+      const fp = path.join(dir, name);
+      try {
+        if (typeof fs.statSync === 'function') {
+          const st = fs.statSync(fp);
+          if (Number.isFinite(st.mtimeMs) && st.mtimeMs < windowStart) continue;
+        }
+      } catch {
+        /* stat failed — fall through and try to read */
+      }
+      let content;
+      try {
+        content = fs.readFileSync(fp, 'utf8');
+      } catch {
+        continue;
+      }
+      filesRead += 1;
+      const events = [];
+      for (const line of String(content).split('\n')) {
+        const t = line.trim();
+        if (!t) continue;
+        try {
+          events.push(JSON.parse(t));
+        } catch {
+          /* skip corrupt line */
+        }
+      }
+      const r = sumTranscriptWindow(events, now, windowMs);
+      tokens += r.tokens;
+      messagesCounted += r.messagesCounted;
+    }
+  }
+  return { tokens, messagesCounted, filesRead };
+}
+
+// Read the raw session-meta JSON objects from ~/.claude/usage-data/session-meta.
+// Returns [] when the directory is absent (degraded path). A corrupt file is
+// skipped, not fatal.
+function readSessionMetas({ home, fs = realFs, path = realPath } = {}) {
+  const dir = path.join(home, '.claude', 'usage-data', 'session-meta');
+  let names;
+  try {
+    if (!fs.existsSync(dir)) return [];
+    names = fs.readdirSync(dir).filter((n) => String(n).endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const metas = [];
+  for (const name of names) {
+    try {
+      metas.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')));
+    } catch {
+      /* skip corrupt file */
+    }
+  }
+  return metas;
+}
+
+// Top-level: estimate Claude's rolling-window usage. Returns a stable shape in
+// every path (including degraded), so callers never branch on undefined:
+//   { estimatedTokens, pct, confidence, source, sessionsCounted, messagesCounted, windowMs }
+// Source precedence, most-live first:
+//   'transcript'   — per-message usage, captures the in-progress session (best)
+//   'session-meta' — coarse per-session totals, blind to the live session
+//   'none'         — no local data (home absent) -> honest null pct
+function estimateClaudeUsage({
+  home = os.homedir(),
+  now = Date.now(),
+  budget = null,
+  windowMs = FIVE_HOURS_MS,
+  fs = realFs,
+  path = realPath,
+} = {}) {
+  // 1. Live transcript signal — preferred (sees the session you are burning NOW).
+  const tr = readTranscriptUsage({ home, now, windowMs, fs, path });
+  if (tr.messagesCounted > 0) {
+    const { pct, confidence } = estimatePct(tr.tokens, budget);
+    return {
+      estimatedTokens: tr.tokens,
+      pct,
+      confidence,
+      source: 'transcript',
+      sessionsCounted: 0,
+      messagesCounted: tr.messagesCounted,
+      windowMs,
+    };
+  }
+
+  // 2. Fallback: coarse per-session totals (post-hoc; blind to the live session).
+  const metas = readSessionMetas({ home, fs, path });
+  if (metas.length === 0) {
+    return { estimatedTokens: 0, pct: null, confidence: 'none', source: 'none', sessionsCounted: 0, messagesCounted: 0, windowMs };
+  }
+  const sessions = metas.map(normalizeSession).filter(Boolean);
+  const inWindow = sessions.filter((s) => {
+    const span = s.endMs - s.startMs;
+    if (span <= 0) return s.startMs >= now - windowMs && s.startMs <= now;
+    return Math.min(s.endMs, now) - Math.max(s.startMs, now - windowMs) > 0;
+  });
+  const estimatedTokens = sumWindowTokens(sessions, now, windowMs);
+  const { pct, confidence } = estimatePct(estimatedTokens, budget);
+  return {
+    estimatedTokens,
+    pct,
+    confidence,
+    source: 'session-meta',
+    sessionsCounted: inWindow.length,
+    messagesCounted: 0,
+    windowMs,
+  };
+}
+
+module.exports = {
+  FIVE_HOURS_MS,
+  normalizeSession,
+  sumWindowTokens,
+  estimatePct,
+  sumTokensFromUsage,
+  sumTranscriptWindow,
+  readTranscriptUsage,
+  readSessionMetas,
+  estimateClaudeUsage,
+};

package/install/templates/.claude/hooks/tier-script-guard.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// PreToolUse hook — BYAN tier gate on the Workflow tool.
+//
+// The Workflow runtime executes every agent() leaf on the session model unless
+// the script pins opts.model, and a script cannot import native-tiers at
+// runtime (sandbox). The repo linter only sees committed .claude/workflows/
+// files — an AD-HOC script written inline crosses exactly one chokepoint
+// before it runs: this hook. It analyzes the script text with the same source
+// of truth as the linter (lib/tier-script.js -> native-tiers.js) and:
+//
+//   - DENIES ONCE when exploration/mech- leaves have no model tier and no
+//     acknowledgment marker, with the exact leaf list to fix. It never
+//     rewrites the script (a wrong auto-stamp would be the STRICT-2 No
+//     Downgrade regression the doctrine forbids).
+//   - allows an IDENTICAL resubmission after a deny (forces a decision,
+//     never traps the turn) — the deny memory lives in .byan-tier/ (sidecar,
+//     gitignored) keyed by script hash.
+//   - allows registry (name-only) invocations: those resolve to committed
+//     scripts the pre-commit linter already owns.
+//   - logs EVERY decision with a per-model histogram to
+//     _byan-output/tier-ledger.jsonl — the measurement basis for real token
+//     gains (no replay theatre).
+//
+// Escape hatch: `touch .byan-tier/off` disables gating (still ledger-logged as
+// escape-hatch, so misses stay auditable). Non-blocking on any internal error.
+//
+// CJS shell + ESM lib via dynamic import() (the leantime-fd-sync bridge). The
+// lib resolves relative to THIS file so tests can pass a bare tmp root for
+// sidecar/ledger state without needing the lib copied there.
+
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const LIB_PATH = path.resolve(__dirname, '../../_byan/mcp/byan-mcp-server/lib/tier-script.js');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+function allow() {
+  return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } };
+}
+
+function deny(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+function sidecarPath(root) {
+  return path.join(root, '.byan-tier', 'last-deny.json');
+}
+
+function readPriorDenyHash(root) {
+  try {
+    return JSON.parse(fs.readFileSync(sidecarPath(root), 'utf8')).hash || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function writePriorDenyHash(root, hash) {
+  try {
+    fs.mkdirSync(path.dirname(sidecarPath(root)), { recursive: true });
+    fs.writeFileSync(sidecarPath(root), JSON.stringify({ hash }));
+  } catch (_e) {
+    // best-effort: losing the deny memory only means one extra deny, never a trap
+  }
+}
+
+function clearPriorDeny(root) {
+  try {
+    fs.unlinkSync(sidecarPath(root));
+  } catch (_e) {
+    // already absent
+  }
+}
+
+function ledgerLog(root, entry) {
+  try {
+    const dir = path.join(root, '_byan-output');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'tier-ledger.jsonl'), JSON.stringify(entry) + '\n');
+  } catch (_e) {
+    // the ledger is observability, never a blocker
+  }
+}
+
+// Per-model histogram: pinned tiers by value; 'inherit' = deep labelled leaves
+// plus unlabelled agent() calls (both run on the session model).
+function modelHistogram(analysis) {
+  const h = { haiku: 0, sonnet: 0, inherit: 0 };
+  for (const l of analysis.leaves) {
+    if (l.model === 'haiku') h.haiku += 1;
+    else if (l.model === 'sonnet') h.sonnet += 1;
+    else h.inherit += 1;
+  }
+  h.inherit += Math.max(0, analysis.agentCalls - analysis.leaves.length);
+  return h;
+}
+
+async function runGuard(payload, { root = ROOT } = {}) {
+  const toolName = payload.tool_name || payload.toolName || '';
+  if (toolName !== 'Workflow') return allow();
+  const input = payload.tool_input || payload.toolInput || {};
+
+  let src = null;
+  let source = null;
+  if (typeof input.script === 'string' && input.script.trim()) {
+    src = input.script;
+    source = 'inline';
+  } else if (typeof input.scriptPath === 'string' && input.scriptPath.trim()) {
+    source = 'scriptPath';
+    const p = path.isAbsolute(input.scriptPath) ? input.scriptPath : path.join(root, input.scriptPath);
+    try {
+      src = fs.readFileSync(p, 'utf8');
+    } catch (_e) {
+      // unreadable path: the Workflow tool will surface the real error itself
+      return allow();
+    }
+  } else {
+    // registry (name-only) invocation: resolves to a committed script the
+    // pre-commit linter already validated
+    return allow();
+  }
+
+  const lib = await import(pathToFileURL(LIB_PATH).href);
+  const analysis = lib.analyzeScript(src);
+  const scriptHash = lib.hashScript(src);
+  const escaped = fs.existsSync(path.join(root, '.byan-tier', 'off'));
+  const decision = lib.decideTierGate({
+    analysis,
+    escaped,
+    scriptHash,
+    priorDenyHash: readPriorDenyHash(root),
+  });
+
+  ledgerLog(root, {
+    ts: new Date().toISOString(),
+    source,
+    decision: decision.decision,
+    code: decision.code,
+    hash: scriptHash,
+    agentCalls: analysis.agentCalls,
+    leaves: analysis.leaves.length,
+    gaps: analysis.gaps.map((g) => g.label),
+    violations: analysis.violations.map((v) => v.label),
+    models: modelHistogram(analysis),
+    acknowledged: analysis.acknowledged,
+  });
+
+  if (decision.decision === 'deny') {
+    writePriorDenyHash(root, scriptHash);
+    return deny(decision.reason);
+  }
+  if (decision.code === 'unchanged-after-deny') clearPriorDeny(root);
+  return allow();
+}
+
+if (require.main === module) {
+  (async () => {
+    let out;
+    try {
+      const payload = JSON.parse((await readStdin()) || '{}');
+      out = await runGuard(payload);
+    } catch (_e) {
+      out = allow();
+    }
+    process.stdout.write(JSON.stringify(out));
+    process.exit(0);
+  })();
+}
+
+module.exports = { runGuard };