@everystack/mcp 0.2.2 → 0.3.0

package/src/gates/detectors/embedded-data-bundle.ts

@@ -0,0 +1,58 @@
+/**
+ * Cheat: bundling a large data file into the app (the 180MB-JSON failure).
+ *
+ * Data belongs in PostgreSQL, served through the API — not shipped as a static
+ * asset or imported blob. This catches the file *as it lands*: a Write of a data
+ * file whose content exceeds the budget. The authoritative gate-to-prod check is
+ * `bundle:audit`'s weight dimension; this is the cheap authoring-time nudge.
+ *
+ * Pure: size is measured from the proposed content, no filesystem read.
+ */
+
+import { basename, relative } from 'path';
+import type { CheatGate, ToolCallContext } from '../types.js';
+
+/** Files over this many bytes of bundled data are almost certainly DB-shaped data. */
+const DATA_BYTE_BUDGET = 512 * 1024; // 0.5 MB
+
+const DATA_EXT = /\.(json|csv|tsv|geojson|ndjson|xml)$/i;
+/** Config/lockfiles that are legitimately data-shaped — never flagged. */
+const EXEMPT = /^(package(-lock)?\.json|tsconfig.*\.json|app\.json|app\.config\.json|eas\.json|.*\.config\.json|manifest\.json|tsconfig\.json)$/i;
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let i = -1;
+  do {
+    n /= 1024;
+    i++;
+  } while (n >= 1024 && i < units.length - 1);
+  return `${n.toFixed(1)} ${units[i]}`;
+}
+
+function rel(ctx: ToolCallContext, p: string): string {
+  try {
+    return relative(ctx.cwd, p) || p;
+  } catch {
+    return p;
+  }
+}
+
+export const embeddedDataBundle: CheatGate = {
+  id: 'embedded-data-bundle',
+  tier: 'framework',
+  severity: 'deny',
+  guide:
+    'Data belongs in PostgreSQL, served through the API — model it and load it (or render an empty state if it does not exist yet). Never bundle large data into the app.',
+  conform: 'define a Model + everystack db:generate + an API hook (or the ingest pipeline)',
+  verify: 'everystack bundle:audit stays under the weight budget',
+  detect(ctx: ToolCallContext): string | null {
+    if (ctx.tool !== 'Write') return null; // Write lands the whole file; Edit content is partial
+    const p = ctx.filePath;
+    if (!p || !DATA_EXT.test(p)) return null;
+    if (EXEMPT.test(basename(p))) return null;
+    const bytes = Buffer.byteLength(ctx.content ?? '', 'utf8');
+    if (bytes < DATA_BYTE_BUDGET) return null;
+    return `${rel(ctx, p)} is ${formatBytes(bytes)} of data bundled into the app`;
+  },
+};

package/src/gates/detectors/hand-written-migration.ts

@@ -0,0 +1,42 @@
+/**
+ * Cheat: hand-writing a migration or editing the generated schema.
+ *
+ * In v3 the schema and its migrations are *generated* from the Models
+ * (`db:generate`). A hand-written `.sql` migration or a hand-edit to the generated
+ * `db/schema.ts` drifts the database from the Models — the migration the CLI would
+ * write next is no longer a clean no-op. Pure path check; no IO.
+ */
+
+import { relative } from 'path';
+import type { CheatGate, ToolCallContext } from '../types.js';
+
+/** A `.sql` file under a migrations/drizzle directory — these are generated, never authored. */
+const MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
+/** The generated Drizzle schema mirror. */
+const GENERATED_SCHEMA = /(?:^|\/)(?:db|drizzle)\/schema\.ts$/;
+
+function rel(ctx: ToolCallContext, p: string): string {
+  try {
+    return relative(ctx.cwd, p) || p;
+  } catch {
+    return p;
+  }
+}
+
+export const handWrittenMigration: CheatGate = {
+  id: 'hand-written-migration',
+  tier: 'framework',
+  severity: 'deny',
+  guide:
+    'Schema and migrations are generated from your Models — edit the Model and run db:generate, never hand-write SQL migrations or edit the generated schema.',
+  conform: 'everystack db:generate',
+  verify: 'everystack db:generate produces no diff (a clean no-op)',
+  detect(ctx: ToolCallContext): string | null {
+    if (ctx.tool !== 'Write' && ctx.tool !== 'Edit') return null;
+    const p = ctx.filePath;
+    if (!p) return null;
+    if (MIGRATION_SQL.test(p)) return `${rel(ctx, p)} is a SQL migration being written by hand`;
+    if (GENERATED_SCHEMA.test(p)) return `${rel(ctx, p)} is generated from your Models`;
+    return null;
+  },
+};

package/src/gates/detectors/secret-in-public-env.ts

@@ -0,0 +1,41 @@
+/**
+ * Cheat: a secret value behind an EXPO_PUBLIC_* name.
+ *
+ * Metro compiles EXPO_PUBLIC_* env vars into the client bundle — public, forever.
+ * A DB URL / API key / token behind one of those names is leaked the moment it
+ * ships. Reuses the canonical secret-shape patterns from `@everystack/cli/audit`
+ * (no duplicated, drift-prone pattern list), loaded lazily behind a cheap
+ * pre-filter so the common tool call never pulls the audit graph.
+ */
+
+import type { CheatGate, ToolCallContext } from '../types.js';
+
+const PUBLIC_KEY = /\b(EXPO_PUBLIC_[A-Z0-9_]+)\b/;
+
+export const secretInPublicEnv: CheatGate = {
+  id: 'secret-in-public-env',
+  tier: 'framework',
+  severity: 'deny',
+  guide:
+    'EXPO_PUBLIC_* is compiled into the client bundle forever — never put a secret behind it. Keep secrets server-side and reference them only on the server.',
+  conform: 'everystack secrets set (SSM) / an SST secret, referenced server-side only',
+  verify: 'everystack bundle:audit (leak scan) finds no leaked secret',
+  async detect(ctx: ToolCallContext): Promise<string | null> {
+    if (ctx.tool !== 'Write' && ctx.tool !== 'Edit') return null;
+    const text = ctx.content;
+    // Cheap sync pre-filter: only env-ish writes pay for the canonical scanner.
+    if (!text || !text.includes('EXPO_PUBLIC_')) return null;
+
+    const { SECRET_PATTERNS, isPublicEnvKey } = await import('@everystack/cli/audit');
+    for (const line of text.split('\n')) {
+      const m = line.match(PUBLIC_KEY);
+      if (!m || !isPublicEnvKey(m[1])) continue;
+      for (const { name, re } of SECRET_PATTERNS) {
+        if (re.test(line)) {
+          return `${m[1]} carries a ${name} — a secret value compiled into the client bundle`;
+        }
+      }
+    }
+    return null;
+  },
+};

package/src/gates/engine.ts

@@ -0,0 +1,80 @@
+/**
+ * Engine — run a set of cheat gates against a tool-call context.
+ *
+ * Pure evaluation (no IO): `evaluateGates` returns findings; `decide` collapses
+ * them to an allow/deny decision (deny wins if any `deny`-tier gate hit). The
+ * caller (governance/cli.ts) records telemetry and renders the hook payload —
+ * keeping detection pure and side effects at the boundary.
+ *
+ * Fail-OPEN: a detector that throws is skipped, never propagated — a governance
+ * bug must not brick tool use.
+ */
+
+import type { CheatGate, GateFinding, ToolCallContext } from './types.js';
+
+/**
+ * Run every gate's detector against the context; collect findings. Detectors that
+ * throw are skipped (fail-open). `detect` may be sync or async — async lets a gate
+ * lazy-load a heavier scanner only after a cheap sync pre-filter matches, so the
+ * common tool call pays nothing.
+ */
+export async function evaluateGates(ctx: ToolCallContext, gates: CheatGate[]): Promise<GateFinding[]> {
+  const findings: GateFinding[] = [];
+  for (const g of gates) {
+    let detail: string | null = null;
+    try {
+      detail = await g.detect(ctx);
+    } catch {
+      detail = null; // fail open on a buggy detector
+    }
+    if (detail == null) continue;
+    findings.push({
+      id: g.id,
+      tier: g.tier,
+      severity: g.severity,
+      guide: g.guide,
+      conform: g.conform,
+      verify: g.verify,
+      detail,
+      file: ctx.filePath,
+    });
+  }
+  return findings;
+}
+
+export interface GateDecision {
+  decision: 'allow' | 'deny';
+  findings: GateFinding[];
+}
+
+/** Collapse findings to a decision: deny if any deny-tier finding, else allow. */
+export function decide(findings: GateFinding[]): GateDecision {
+  const decision = findings.some((f) => f.severity === 'deny') ? 'deny' : 'allow';
+  return { decision, findings };
+}
+
+/** The PreToolUse deny/warn reason: each finding as Guide → Conform → Verify. */
+export function findingsReason(findings: GateFinding[]): string {
+  const lines: string[] = [];
+  const denies = findings.filter((f) => f.severity === 'deny');
+  const warns = findings.filter((f) => f.severity === 'warn');
+  if (denies.length) {
+    lines.push('OFF-SCRIPT — this cheats the everystack architecture:');
+    for (const f of denies) lines.push(...renderFinding(f));
+  }
+  if (warns.length) {
+    if (denies.length) lines.push('');
+    lines.push('Heads up (advisory):');
+    for (const f of warns) lines.push(...renderFinding(f));
+  }
+  return lines.join('\n');
+}
+
+function renderFinding(f: GateFinding): string[] {
+  return [
+    `  • [${f.id}] ${f.detail}`,
+    `      do this:  ${f.guide}`,
+    `      with:     ${f.conform}`,
+    `      verify:   ${f.verify}`,
+  ];
+}

package/src/gates/registry.ts

@@ -0,0 +1,25 @@
+/**
+ * The cheat-gate registry.
+ *
+ * Framework tier: on by default for any everystack project — the gates whose
+ * Detect is local and whose Verify already ships (db:generate, bundle:audit).
+ * Project tier (declared per project via a recipe manifest) lands in a later
+ * brick; `gatesFor` is the seam where that composition will happen.
+ */
+
+import type { CheatGate } from './types.js';
+import { handWrittenMigration } from './detectors/hand-written-migration.js';
+import { embeddedDataBundle } from './detectors/embedded-data-bundle.js';
+import { secretInPublicEnv } from './detectors/secret-in-public-env.js';
+
+/** Framework-tier gates, on by default. */
+export const FRAMEWORK_GATES: CheatGate[] = [
+  handWrittenMigration,
+  embeddedDataBundle,
+  secretInPublicEnv,
+];
+
+/** The gates that apply to a working directory. Project-tier composition is added later. */
+export function gatesFor(_cwd: string): CheatGate[] {
+  return FRAMEWORK_GATES;
+}

package/src/gates/telemetry.ts

@@ -0,0 +1,143 @@
+/**
+ * Telemetry — the gate is also the sensor.
+ *
+ * Every cheat finding is appended to a per-session JSONL under
+ * ~/.everystack/governance/<session>.jsonl. Pointed at real testers, this file is
+ * the off-rails dataset: which cheats the agent attempts, how often, what gets
+ * denied vs warned. `report` summarises it (the empirical loop that ranks which
+ * gates and generators matter next).
+ *
+ * Privacy: record rule + path + severity only — never file contents.
+ * Fail-OPEN: a telemetry write must never throw into the hook path.
+ */
+
+import { mkdirSync, appendFileSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { GateFinding } from './types.js';
+
+function home(): string {
+  return process.env.HOME || homedir();
+}
+
+/** The telemetry directory: ~/.everystack/governance. */
+export function telemetryDir(): string {
+  return join(home(), '.everystack', 'governance');
+}
+
+function safeId(sessionId: string): string {
+  return (sessionId || 'nosession').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+
+export interface TelemetryEvent {
+  ts: string;
+  session: string;
+  cwd: string;
+  rule: string;
+  tier: string;
+  severity: string;
+  tool: string;
+  file?: string;
+}
+
+/**
+ * Append one telemetry line per finding. Decision (deny vs warn) is implicit in
+ * `severity`. Never throws.
+ */
+export function recordFindings(
+  sessionId: string,
+  ctx: { cwd: string; tool: string },
+  findings: GateFinding[]
+): void {
+  if (findings.length === 0) return;
+  try {
+    mkdirSync(telemetryDir(), { recursive: true });
+    const path = join(telemetryDir(), `${safeId(sessionId)}.jsonl`);
+    const ts = new Date().toISOString();
+    const lines = findings
+      .map((f) => {
+        const ev: TelemetryEvent = {
+          ts,
+          session: safeId(sessionId),
+          cwd: ctx.cwd,
+          rule: f.id,
+          tier: f.tier,
+          severity: f.severity,
+          tool: ctx.tool,
+          file: f.file,
+        };
+        return JSON.stringify(ev);
+      })
+      .join('\n');
+    appendFileSync(path, lines + '\n');
+  } catch {
+    /* fail open: telemetry never bricks the hook */
+  }
+}
+
+/** Read all events for one session, or every session when sessionId is omitted. */
+export function readEvents(sessionId?: string): TelemetryEvent[] {
+  const events: TelemetryEvent[] = [];
+  let files: string[];
+  try {
+    files = readdirSync(telemetryDir()).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return events;
+  }
+  const wanted = sessionId ? `${safeId(sessionId)}.jsonl` : null;
+  for (const f of files) {
+    if (wanted && f !== wanted) continue;
+    try {
+      const text = readFileSync(join(telemetryDir(), f), 'utf-8');
+      for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (!t) continue;
+        try {
+          events.push(JSON.parse(t) as TelemetryEvent);
+        } catch {
+          /* skip a malformed line, keep the rest */
+        }
+      }
+    } catch {
+      /* skip an unreadable file */
+    }
+  }
+  return events;
+}
+
+export interface TelemetrySummary {
+  total: number;
+  denies: number;
+  warns: number;
+  byRule: Record<string, number>;
+  sessions: number;
+}
+
+/** Tally events into a summary (the `report` payload). */
+export function summarize(sessionId?: string): TelemetrySummary {
+  const events = readEvents(sessionId);
+  const byRule: Record<string, number> = {};
+  const sessions = new Set<string>();
+  let denies = 0;
+  let warns = 0;
+  for (const e of events) {
+    byRule[e.rule] = (byRule[e.rule] ?? 0) + 1;
+    sessions.add(e.session);
+    if (e.severity === 'deny') denies++;
+    else if (e.severity === 'warn') warns++;
+  }
+  return { total: events.length, denies, warns, byRule, sessions: sessions.size };
+}
+
+/** Human-readable rendering of the summary (the `report` stdout). */
+export function renderSummary(s: TelemetrySummary): string {
+  const lines: string[] = [];
+  lines.push(`governance telemetry — ${s.total} findings across ${s.sessions} session(s)`);
+  lines.push(`  ${s.denies} deny · ${s.warns} warn`);
+  const ranked = Object.entries(s.byRule).sort((a, b) => b[1] - a[1]);
+  if (ranked.length) {
+    lines.push('  by rule (most-tripped first):');
+    for (const [rule, n] of ranked) lines.push(`    ${n.toString().padStart(4)}  ${rule}`);
+  }
+  return lines.join('\n');
+}

package/src/gates/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Cheat-gate types — the atomic unit of governance.
+ *
+ * A cheat gate catches the agent *cheating the architecture*: taking the
+ * training-consensus shortcut (bundle the JSON, hand-write the migration, leak a
+ * secret) that the maintainer would veto on sight. Anatomy, fixed:
+ *
+ *   Detect → Block → Guide → Conform → Verify
+ *
+ * Governing rule (see docs/plans/everystack-cheat-gates.md): no gate ships without
+ * Guide + Conform + Verify. If you can't name what to do instead, the tool that
+ * does it, and the check that proves it, the rule is grounding — not a gate.
+ */
+
+export type GateSeverity = 'deny' | 'warn';
+export type GateTier = 'framework' | 'project';
+
+/**
+ * What a detector inspects at the tool-call boundary, normalised from hook JSON
+ * (PreToolUse/PostToolUse) or synthesised for a tree scan. Pure data.
+ */
+export interface ToolCallContext {
+  /** The tool about to run / that ran: 'Write' | 'Edit' | 'Bash' | 'Read' | … */
+  tool: string;
+  /** Target path for Write/Edit/Read. */
+  filePath?: string;
+  /** Proposed file content (Write) or the new text (Edit) — what is about to land. */
+  content?: string;
+  /** Command line for Bash. */
+  command?: string;
+  /** Working directory of the session. */
+  cwd: string;
+}
+
+/** A single cheat detected — carries its own remediation and proof. */
+export interface GateFinding {
+  id: string;
+  tier: GateTier;
+  severity: GateSeverity;
+  /** One imperative sentence: what to do instead. */
+  guide: string;
+  /** The sanctioned tool/command/generator that does it right. */
+  conform: string;
+  /** The runnable check that proves the result is clean. */
+  verify: string;
+  /** Specifics of this hit (e.g. "assets/data.json is 184.0 MB"). */
+  detail: string;
+  /** The file the cheat lives in, when applicable. */
+  file?: string;
+}
+
+/**
+ * A cheat gate. `detect` is pure + synchronous: it returns a detail string when
+ * the cheat is present in the given context, or null when the context is clean.
+ * The Guide/Conform/Verify fields are static metadata copied onto every finding.
+ */
+export interface CheatGate {
+  id: string;
+  tier: GateTier;
+  severity: GateSeverity;
+  guide: string;
+  conform: string;
+  verify: string;
+  /**
+   * Returns a detail string when the cheat is present, else null. May be sync or
+   * async — keep the common path sync and cheap; use async only to lazy-load a
+   * heavier scanner *after* a cheap pre-filter matches.
+   */
+  detect(ctx: ToolCallContext): string | null | Promise<string | null>;
+}

package/src/governance/cli.ts

@@ -0,0 +1,193 @@
+/**
+ * governance/cli — the hook-shim entry for `everystack-mcp <subcommand>`.
+ *
+ * Claude Code hooks pipe their JSON event on stdin to one of these subcommands;
+ * the hook config itself carries no logic (the local-agent grounding-gate shape).
+ * The handlers are exported so the same logic is unit-testable and so the operator
+ * CLI can self-gate on it later — no drift between what the hook blocks and what
+ * the gate-to-prod refuses.
+ *
+ * This module stays LIGHT to import: it pulls only grounding + the pure engine +
+ * telemetry. The one heavy dependency (the canonical secret scanner) is lazy-loaded
+ * inside its detector behind a cheap pre-filter, so the common tool call is fast.
+ *
+ * Fail-OPEN on any internal error or unknown input — a governance bug must never
+ * brick tool use globally. Only the explicit "ungrounded" / "off-script deny"
+ * conditions fail closed.
+ */
+
+import { context, gate, mark, denyReason } from './grounding.js';
+import { evaluateGates, decide, findingsReason } from '../gates/engine.js';
+import { gatesFor } from '../gates/registry.js';
+import { recordFindings, summarize, renderSummary } from '../gates/telemetry.js';
+import type { ToolCallContext } from '../gates/types.js';
+
+export const GOVERNANCE_COMMANDS = [
+  'context', // SessionStart: inject the grounding contract
+  'gate', // PreToolUse: allow/deny (grounding + cheat gates)
+  'mark', // PostToolUse(Read): record a required-file read
+  'validate', // PostToolUse(Write|Edit): surface any cheat the write landed
+  'report', // summarize the per-session telemetry (the sensor)
+] as const;
+
+export type GovernanceCommand = (typeof GOVERNANCE_COMMANDS)[number];
+
+interface HookInput {
+  session_id?: string;
+  cwd?: string;
+  source?: string;
+  tool_name?: string;
+  tool_input?: {
+    file_path?: string;
+    content?: string;
+    new_string?: string;
+    old_string?: string;
+    command?: string;
+    offset?: number;
+    limit?: number;
+  };
+}
+
+/** Deny payload for PreToolUse. */
+function denyPayload(reason: string): unknown {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/** Non-blocking advisory payload for PostToolUse. */
+function contextPayload(text: string): unknown {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: text,
+    },
+  };
+}
+
+function toToolContext(input: HookInput): ToolCallContext {
+  const ti = input.tool_input ?? {};
+  return {
+    tool: input.tool_name ?? '',
+    filePath: ti.file_path,
+    // Write carries `content`; Edit carries `new_string` (what is about to land).
+    content: ti.content ?? ti.new_string,
+    command: ti.command,
+    cwd: input.cwd ?? process.cwd(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Handlers (exported for tests; pure-ish — telemetry is the only side effect)
+// ---------------------------------------------------------------------------
+
+/** SessionStart: the grounding contract text. */
+export function handleContext(input: HookInput): string {
+  const sid = input.session_id ?? 'nosession';
+  const cwd = input.cwd ?? process.cwd();
+  return context(sid, cwd, input.source ?? 'startup');
+}
+
+/**
+ * PreToolUse: grounding first (the contract must be read), then cheat gates. Returns
+ * a deny payload object to emit, or null to allow. Telemetry is recorded for any
+ * cheat findings at this boundary (the authoritative "attempt" event).
+ */
+export async function handleGate(input: HookInput): Promise<unknown | null> {
+  const sid = input.session_id ?? 'nosession';
+  const cwd = input.cwd ?? process.cwd();
+  const tool = input.tool_name ?? '';
+
+  // 1) Grounding: until the contract is read, every non-Read tool is denied.
+  const g = gate(sid, cwd, tool);
+  if (g.decision === 'deny') return denyPayload(denyReason(g.unread));
+
+  // 2) Cheat gates.
+  const ctx = toToolContext(input);
+  const findings = await evaluateGates(ctx, gatesFor(cwd));
+  if (findings.length) recordFindings(sid, { cwd, tool }, findings);
+  if (decide(findings).decision === 'deny') return denyPayload(findingsReason(findings));
+  return null; // allow (any warn-tier findings are recorded, not blocked)
+}
+
+/**
+ * PostToolUse(Write|Edit): re-scan after the write and surface anything (a backstop
+ * for what a pre-write check couldn't see). Non-blocking. Does NOT re-record — the
+ * attempt was already counted at the gate — it only surfaces guidance.
+ */
+export async function handleValidate(input: HookInput): Promise<unknown | null> {
+  const cwd = input.cwd ?? process.cwd();
+  const ctx = toToolContext(input);
+  const findings = await evaluateGates(ctx, gatesFor(cwd));
+  if (!findings.length) return null;
+  return contextPayload(findingsReason(findings));
+}
+
+/** PostToolUse(Read): mark a required-file read toward grounding. */
+export function handleMark(input: HookInput): void {
+  const sid = input.session_id ?? 'nosession';
+  const cwd = input.cwd ?? process.cwd();
+  const ti = input.tool_input ?? {};
+  if (!ti.file_path) return;
+  const partial = ti.offset !== undefined || ti.limit !== undefined;
+  mark(sid, cwd, ti.file_path, partial);
+}
+
+// ---------------------------------------------------------------------------
+// stdin / dispatch
+// ---------------------------------------------------------------------------
+
+function readStdin(): Promise<string> {
+  return new Promise((res) => {
+    let data = '';
+    if (process.stdin.isTTY) {
+      res('');
+      return;
+    }
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => res(data));
+    process.stdin.on('error', () => res(data));
+  });
+}
+
+/**
+ * Dispatch a governance subcommand from hook JSON on stdin. `report` reads
+ * telemetry instead of stdin and prints a summary. Always fails open.
+ */
+export async function runGovernanceCli(argv: string[]): Promise<void> {
+  const mode = argv[0] as GovernanceCommand | undefined;
+  if (!mode || !(GOVERNANCE_COMMANDS as readonly string[]).includes(mode)) return;
+
+  try {
+    if (mode === 'report') {
+      process.stdout.write(renderSummary(summarize(argv[1])) + '\n');
+      return;
+    }
+
+    let input: HookInput = {};
+    try {
+      input = JSON.parse((await readStdin()) || '{}');
+    } catch {
+      return; // fail open on malformed input
+    }
+
+    if (mode === 'context') {
+      process.stdout.write(handleContext(input) + '\n');
+    } else if (mode === 'gate') {
+      const payload = await handleGate(input);
+      if (payload) process.stdout.write(JSON.stringify(payload));
+    } else if (mode === 'mark') {
+      handleMark(input);
+    } else if (mode === 'validate') {
+      const payload = await handleValidate(input);
+      if (payload) process.stdout.write(JSON.stringify(payload));
+    }
+  } catch {
+    /* fail open: stay silent, exit 0 */
+  }
+}