@attalabs/vinaya 0.1.3 → 0.3.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync11 } from "node:fs";
+import { readFileSync as readFileSync12 } from "node:fs";
 import { dirname as dirname5, join as join15 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
@@ -1276,91 +1276,153 @@ function coreCheckRegistry() {
       name: "brief-shape",
       run: bin("check-brief-shape"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: { PR_BODY: { optional: true } }
     },
     {
       name: "doc-coverage",
       run: bin("check-doc-coverage"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BASE_SHA: { optional: true },
+        PR_BODY: { optional: true },
+        PR_BODY_FILE: { optional: true },
+        PR_LABELS: { optional: true },
+        WAIVER_LABEL_ACTOR: { optional: true }
+      }
     },
     {
       name: "coherence",
       run: bin("check-coherence"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "dispatch-readiness",
       run: bin("check-dispatch-readiness"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "closes-n",
       run: bin("check-closes-n"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BRANCH: { optional: true },
+        PR_BODY: { optional: true },
+        AEG_REPO: { optional: true }
+      }
     },
     {
       name: "single-plan-pr",
       run: bin("check-single-plan-pr"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        BASE_SHA: { optional: true },
+        PR_NUMBER: { optional: true }
+      }
     },
     {
       name: "test-plan",
       run: bin("check-test-plan"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        PR_BODY: { optional: true },
+        BRANCH: { optional: true }
+      }
     },
     {
       name: "no-disk-state",
       run: bin("check-no-disk-state"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: { BASE_SHA: { optional: true } }
     },
     {
       name: "registry-gates",
       run: bin("check-registry-gates"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: { AEG_REPO: { optional: true } }
     },
     {
       name: "review-gate",
       run: bin("check-review-gate"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        PR_NUMBER: { optional: true }
+      }
     },
     {
       name: "branch-topology",
       run: bin("check-branch-topology"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        AEG_REPO: { optional: true }
+      }
     },
     {
       name: "dead-branch-push",
       run: bin("check-dead-branch-push"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: { BRANCH: { optional: true } }
     },
     {
       name: "first-push-dispatch",
       run: bin("check-first-push-dispatch"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        BRANCH: { optional: true },
+        AEG_REPO: { optional: true },
+        GITHUB_TOKEN: { optional: true },
+        GH_TOKEN: { optional: true }
+      }
     },
     {
       name: "doc-coverage-push",
       run: bin("check-doc-coverage-push"),
       scope: "diff",
-      timeoutMs: 15000
+      timeoutMs: 15000,
+      env: {
+        OVERRIDE_DOCS: { optional: true },
+        BASE_SHA: { optional: true },
+        PR_BODY: { optional: true },
+        PR_BODY_FILE: { optional: true },
+        PR_LABELS: { optional: true },
+        WAIVER_LABEL_ACTOR: { optional: true }
+      }
     },
     {
       name: "issue-assignment",
       run: bin("check-issue-assignment"),
       scope: "full",
-      timeoutMs: 30000
+      timeoutMs: 30000,
+      env: {
+        AEG_REPO: { optional: true },
+        BRANCH: { optional: true }
+      }
     }
   ];
 }
@@ -1390,17 +1452,138 @@ function shouldSkip(spec, opts) {
   return !opts.changedFiles.some((f) => regexes.some((re) => re.test(f)));
 }
 var KILL_GRACE_MS = 2000;
-async function runOne(spec, timeoutMs) {
+var activeKillers = new Set;
+var signalForwardingInstalled = false;
+function installSignalForwarding() {
+  if (signalForwardingInstalled)
+    return;
+  signalForwardingInstalled = true;
+  const forward = (_signal, exitCode) => {
+    for (const kill of activeKillers)
+      kill("SIGTERM");
+    setTimeout(() => {
+      for (const kill of activeKillers)
+        kill("SIGKILL");
+      process.exit(exitCode);
+    }, KILL_GRACE_MS);
+  };
+  process.on("SIGINT", () => forward("SIGINT", 130));
+  process.on("SIGTERM", () => forward("SIGTERM", 143));
+}
+var ENV_BASELINE_KEYS = ["PATH", "LANG", "HOME", "HTTPS_PROXY", "HTTP_PROXY", "NO_PROXY", "TMPDIR"];
+function buildCheckEnv(env, callerEnv = process.env) {
+  const out = {};
+  for (const key of ENV_BASELINE_KEYS) {
+    const value = callerEnv[key];
+    if (value !== undefined)
+      out[key] = value;
+  }
+  if (!env)
+    return out;
+  for (const [key, decl] of Object.entries(env)) {
+    if (decl === true || typeof decl === "object" && "optional" in decl) {
+      const value = callerEnv[key];
+      if (value !== undefined)
+        out[key] = value;
+    } else if (typeof decl === "object" && "anyOf" in decl) {
+      for (const member of decl.anyOf) {
+        const value = callerEnv[member];
+        if (value !== undefined)
+          out[member] = value;
+      }
+    } else if (typeof decl === "string") {
+      out[key] = decl;
+    }
+  }
+  return out;
+}
+function missingEnvErrors(spec, callerEnv) {
+  if (!spec.env)
+    return [];
+  const errors = [];
+  for (const [key, decl] of Object.entries(spec.env)) {
+    if (decl === true) {
+      if (callerEnv[key] === undefined) {
+        errors.push({
+          schema: CHECK_SCHEMA_VERSION,
+          check: spec.name,
+          severity: "error",
+          message: `Could not run check "${spec.name}": required environment variable \`${key}\` is not set.`,
+          agent_recovery_prompt: `Set \`${key}\` in the environment before re-running \`vinaya check ${spec.name}\`, or relax its declaration to \`{ optional: true }\` in its \`env\` registration if the check can tolerate absence.`
+        });
+      }
+    } else if (typeof decl === "object" && decl !== null && "anyOf" in decl) {
+      const satisfied = decl.anyOf.some((member) => callerEnv[member] !== undefined);
+      if (!satisfied) {
+        errors.push({
+          schema: CHECK_SCHEMA_VERSION,
+          check: spec.name,
+          severity: "error",
+          message: `Could not run check "${spec.name}": none of its required environment variables (${decl.anyOf.join(", ")}) are set.`,
+          agent_recovery_prompt: `Set one of ${decl.anyOf.join(", ")} in the environment before re-running \`vinaya check ${spec.name}\`.`
+        });
+      }
+    }
+  }
+  return errors;
+}
+async function runOne(spec, timeoutMs, callerEnv) {
   const start = performance.now();
+  const envErrors = missingEnvErrors(spec, callerEnv);
+  if (envErrors.length > 0) {
+    return {
+      name: spec.name,
+      status: "error",
+      exitCode: null,
+      errors: envErrors,
+      durationMs: performance.now() - start
+    };
+  }
   const proc = spawn(spec.run, spec.args ?? [], {
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true,
+    env: buildCheckEnv(spec.env, callerEnv)
   });
+  function killTree(signal) {
+    const pid = proc.pid;
+    if (pid === undefined)
+      return;
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      try {
+        proc.kill(signal);
+      } catch {}
+    }
+  }
+  installSignalForwarding();
+  activeKillers.add(killTree);
+  function groupStillAlive(pid) {
+    try {
+      process.kill(-pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
   let timedOut = false;
-  let killTimer;
+  let escalationDone = Promise.resolve();
+  let cancelEscalation;
   const timer = setTimeout(() => {
     timedOut = true;
-    proc.kill("SIGTERM");
-    killTimer = setTimeout(() => proc.kill("SIGKILL"), KILL_GRACE_MS);
+    killTree("SIGTERM");
+    escalationDone = new Promise((resolve) => {
+      const graceTimer = setTimeout(() => {
+        const pid = proc.pid;
+        if (pid !== undefined && groupStillAlive(pid))
+          killTree("SIGKILL");
+        resolve();
+      }, KILL_GRACE_MS);
+      cancelEscalation = () => {
+        clearTimeout(graceTimer);
+        resolve();
+      };
+    });
   }, timeoutMs);
   let stderrText = "";
   proc.stderr.setEncoding("utf-8");
@@ -1417,7 +1600,13 @@ async function runOne(spec, timeoutMs) {
     });
   });
   clearTimeout(timer);
-  clearTimeout(killTimer);
+  if (timedOut) {
+    const pid = proc.pid;
+    if (pid === undefined || !groupStillAlive(pid))
+      cancelEscalation?.();
+    await escalationDone;
+  }
+  activeKillers.delete(killTree);
   const durationMs = performance.now() - start;
   if (timedOut) {
     return { name: spec.name, status: "timeout", exitCode: null, errors: [], durationMs };
@@ -1469,6 +1658,7 @@ async function runOne(spec, timeoutMs) {
   return { name: spec.name, status, exitCode, errors, durationMs };
 }
 async function runChecks(specs, opts) {
+  const callerEnv = opts.callerEnv ?? process.env;
   const results = new Array(specs.length);
   const toRun = [];
   for (let i = 0;i < specs.length; i++) {
@@ -1485,7 +1675,7 @@ async function runChecks(specs, opts) {
       const idx = toRun[cursor];
       cursor += 1;
       const spec = specs[idx];
-      results[idx] = await runOne(spec, spec.timeoutMs ?? opts.defaultTimeoutMs);
+      results[idx] = await runOne(spec, spec.timeoutMs ?? opts.defaultTimeoutMs, callerEnv);
     }
   };
   const workerCount = Math.max(1, Math.min(opts.parallel, toRun.length));
@@ -1498,13 +1688,70 @@ import { existsSync as existsSync4, mkdirSync, readFileSync, writeFileSync } fro
 import { homedir } from "node:os";
 import { dirname as dirname2, join as join4 } from "node:path";
 import { z } from "zod";
+var EnvEntrySchema = z.union([
+  z.literal(true),
+  z.object({ optional: z.literal(true) }),
+  z.object({ anyOf: z.array(z.string()).min(2) }),
+  z.string()
+]);
 var CheckEntrySchema = z.object({
   run: z.string(),
   scope: z.enum(["diff", "full"]),
   include: z.array(z.string()).optional(),
   args: z.array(z.string()).optional(),
-  timeoutMs: z.number().optional()
+  timeoutMs: z.number().optional(),
+  env: z.record(z.string(), EnvEntrySchema).optional()
+}).superRefine((entry2, ctx) => {
+  if (!entry2.env)
+    return;
+  for (const [key, value] of Object.entries(entry2.env)) {
+    if (typeof value !== "object" || value === null || !("anyOf" in value))
+      continue;
+    const members = value.anyOf;
+    if (new Set(members).size !== members.length) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `env.${key}.anyOf has duplicate members`,
+        path: ["env", key, "anyOf"]
+      });
+    }
+    if (!members.includes(key)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `env.${key}.anyOf must include "${key}" itself as a member`,
+        path: ["env", key, "anyOf"]
+      });
+    }
+  }
 });
+var HIGH_ENTROPY_MIN_LENGTH = 20;
+function looksHighEntropy(value) {
+  if (value.length < HIGH_ENTROPY_MIN_LENGTH)
+    return false;
+  if (/\s/.test(value))
+    return false;
+  const classes = [/[a-z]/.test(value), /[A-Z]/.test(value), /[0-9]/.test(value)].filter(Boolean).length;
+  return classes >= 2;
+}
+function lintEnvDeclarations(checks) {
+  const warnings = [];
+  if (!checks)
+    return warnings;
+  for (const [checkName, entry2] of Object.entries(checks)) {
+    if (!entry2.env)
+      continue;
+    for (const [key, value] of Object.entries(entry2.env)) {
+      if (typeof value !== "string")
+        continue;
+      if (value === "true" || value === "false") {
+        warnings.push(`check "${checkName}" env.${key} is the literal string "${value}" — did you mean the boolean form \`${key}: true\` (forward the caller's value) rather than a hardcoded literal?`);
+      } else if (looksHighEntropy(value)) {
+        warnings.push(`check "${checkName}" env.${key} looks like a high-entropy literal (possible secret committed to config) — env declarations should reference variable NAMES the caller sets, not literal secret values.`);
+      }
+    }
+  }
+  return warnings;
+}
 var BRIEF_BUILTINS = [
   "tier",
   "testPlan",
@@ -1902,7 +2149,7 @@ async function demoBreakCommand(args) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync7, readFileSync as readFileSync4, statSync } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync5, statSync } from "node:fs";
 import { join as join8 } from "node:path";
 
 // src/lib/artifacts.ts
@@ -2271,8 +2518,33 @@ function buildInitProductOps(name) {
   ];
 }
 
+// src/lib/env-lint.ts
+import { existsSync as existsSync6, readFileSync as readFileSync3 } from "node:fs";
+var ENV_READ_PATTERN = /\b(?:process\.env|Bun\.env|Deno\.env)\b/;
+function checksMissingEnvDeclaration(specs) {
+  const names = [];
+  for (const spec of specs) {
+    if (spec.env)
+      continue;
+    if (!existsSync6(spec.run))
+      continue;
+    let source;
+    try {
+      source = readFileSync3(spec.run, "utf8");
+    } catch {
+      continue;
+    }
+    if (ENV_READ_PATTERN.test(source))
+      names.push(spec.name);
+  }
+  return names;
+}
+function envDeclarationWarning(name) {
+  return `check "${name}" reads environment variables directly but declares no \`env\` — it will lose environment access at the next minor. Declare \`env\` for it (CheckSpec['env'] in src/checks/contract.ts, or vinaya.config.json's checks.<name>.env).`;
+}
+
 // src/lib/ops.ts
-import { chmodSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname3, join as join7, resolve, sep } from "node:path";
 var MARKER_NS = "vinaya:managed";
 function markerLines(marker, comment) {
@@ -2300,9 +2572,9 @@ function containedAbs(repoRoot, relPath) {
 }
 function fileContains(repoRoot, relPath, needle) {
   const p = abs(repoRoot, relPath);
-  if (!existsSync6(p))
+  if (!existsSync7(p))
     return false;
-  return readFileSync3(p, "utf-8").includes(needle);
+  return readFileSync4(p, "utf-8").includes(needle);
 }
 function planInstall(ops, repoRoot, ownedFiles = new Set) {
   const entries = [];
@@ -2310,7 +2582,7 @@ function planInstall(ops, repoRoot, ownedFiles = new Set) {
   for (const op of ops) {
     switch (op.kind) {
       case "create-file": {
-        const exists = existsSync6(abs(repoRoot, op.path));
+        const exists = existsSync7(abs(repoRoot, op.path));
         let action;
         if (!exists)
           action = "create";
@@ -2328,7 +2600,7 @@ function planInstall(ops, repoRoot, ownedFiles = new Set) {
         let action;
         if (fileContains(repoRoot, op.path, begin))
           action = "skip-present";
-        else if (existsSync6(abs(repoRoot, op.path)))
+        else if (existsSync7(abs(repoRoot, op.path)))
           action = "append";
         else
           action = "create-host";
@@ -2412,7 +2684,7 @@ function writeFileWithDirs(target, content, mode) {
 }
 function appendBlock(repoRoot, op) {
   const target = abs(repoRoot, op.path);
-  const existing = readFileSync3(target, "utf-8");
+  const existing = readFileSync4(target, "utf-8");
   const sep2 = existing.endsWith(`
 `) ? `
 ` : `
@@ -2523,7 +2795,7 @@ function planEject(manifest, repoRoot) {
       escapes.push(b.path);
       continue;
     }
-    if (!existsSync6(p)) {
+    if (!existsSync7(p)) {
       actions.push({
         kind: "strip-block",
         path: b.path,
@@ -2534,7 +2806,7 @@ function planEject(manifest, repoRoot) {
       });
       continue;
     }
-    const content = readFileSync3(p, "utf-8");
+    const content = readFileSync4(p, "utf-8");
     const stripped = stripBlockFromContent(content, b.marker, b.comment);
     const removesHost = stripped !== null && blockStripLeavesEmpty(stripped);
     actions.push({
@@ -2552,7 +2824,7 @@ function planEject(manifest, repoRoot) {
       escapes.push(f);
       continue;
     }
-    actions.push({ kind: "delete-file", path: f, present: existsSync6(p) });
+    actions.push({ kind: "delete-file", path: f, present: existsSync7(p) });
   }
   for (const name of manifest.labels) {
     actions.push({ kind: "report-label", name });
@@ -2586,7 +2858,7 @@ function applyEject(plan, repoRoot) {
       const p = containedAbs(repoRoot, a.path);
       if (p === null)
         continue;
-      const content = readFileSync3(p, "utf-8");
+      const content = readFileSync4(p, "utf-8");
       const stripped = stripBlockFromContent(content, a.marker, a.comment);
       if (stripped === null)
         continue;
@@ -2609,7 +2881,7 @@ function applyEject(plan, repoRoot) {
 
 // src/commands/doctor.ts
 function readVersion() {
-  const pkg = JSON.parse(readFileSync4(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync5(join8(packageRoot(import.meta.url), "package.json"), "utf-8"));
   return pkg.version;
 }
 function realDeps3() {
@@ -2629,11 +2901,11 @@ var warn = (check, message) => ({ check, severity: "warn", message });
 var error = (check, message) => ({ check, severity: "error", message });
 function readConfig(repoRoot) {
   const p = join8(repoRoot, CONFIG_PATH);
-  if (!existsSync7(p))
+  if (!existsSync8(p))
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync4(p, "utf-8"));
+    raw = JSON.parse(readFileSync5(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -2663,13 +2935,13 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
     if (op.kind === "create-file") {
       const check = labelForPath(op.path);
       const abs2 = join8(repoRoot, op.path);
-      const exists = existsSync7(abs2);
+      const exists = existsSync8(abs2);
       const owned = ownedFiles.has(op.path);
       if (!exists) {
         findings.push(owned ? error(check, `${op.path} is recorded as vinaya-managed but missing on disk — run \`vinaya upgrade\`.`) : error(check, `${op.path} is not installed — run \`vinaya init\`.`));
         continue;
       }
-      const content = readFileSync4(abs2, "utf-8");
+      const content = readFileSync5(abs2, "utf-8");
       if (!owned) {
         findings.push(content === op.content ? warn(check, `${op.path} has vinaya's own content but isn't recorded in the manifest.`) : info(check, `${op.path} exists but is foreign content — not vinaya-managed, left untouched.`));
         continue;
@@ -2688,11 +2960,11 @@ function diagnoseInstall(repoRoot, ctx, manifest) {
       const check = "hooks";
       const abs2 = join8(repoRoot, op.path);
       const owned = ownedBlocks.has(blockKey(op.path, op.marker));
-      if (!existsSync7(abs2)) {
+      if (!existsSync8(abs2)) {
         findings.push(owned ? error(check, `${op.path} is missing — likely a fresh clone (raw git hooks aren't tracked by git). Run \`vinaya upgrade\` to restore it.`) : info(check, `${op.path} is not installed.`));
         continue;
       }
-      const content = readFileSync4(abs2, "utf-8");
+      const content = readFileSync5(abs2, "utf-8");
       const { begin, end } = markerLines(op.marker, op.comment);
       const hasMarkers = content.includes(begin) && content.includes(end);
       if (!hasMarkers) {
@@ -2718,7 +2990,20 @@ function diagnoseCustomChecks(repoRoot, config) {
   const findings = [];
   for (const [name, entry2] of Object.entries(config.checks ?? {})) {
     const scriptAbs = join8(repoRoot, entry2.run);
-    findings.push(existsSync7(scriptAbs) ? ok("checks", `custom check '${name}' → ${entry2.run}`) : error("checks", `custom check '${name}' points at a missing script: ${entry2.run}`));
+    findings.push(existsSync8(scriptAbs) ? ok("checks", `custom check '${name}' → ${entry2.run}`) : error("checks", `custom check '${name}' points at a missing script: ${entry2.run}`));
+  }
+  return findings;
+}
+function diagnoseEnvDeclarations(repoRoot, config) {
+  const customSpecs = Object.entries(config?.checks ?? {}).map(([name, entry2]) => ({
+    name,
+    ...entry2,
+    run: join8(repoRoot, entry2.run)
+  }));
+  const missing = checksMissingEnvDeclaration([...coreCheckRegistry(), ...customSpecs]);
+  const findings = missing.map((name) => info("env", envDeclarationWarning(name)));
+  for (const message of lintEnvDeclarations(config?.checks)) {
+    findings.push(warn("env", message));
   }
   return findings;
 }
@@ -2791,6 +3076,7 @@ async function runDoctor(args, deps) {
     hasDrift = install.hasDrift;
     findings.push(...diagnoseCustomChecks(repo.repoRoot, configRead.config));
   }
+  findings.push(...diagnoseEnvDeclarations(repo.repoRoot, configRead.kind === "ok" ? configRead.config : null));
   findings.push(...await diagnoseEnvironment(deps, hasDrift));
   findings.push(await diagnoseBranchProtection(deps, repo.owner, repo.repo));
   const healthy = findings.every((f) => f.severity === "ok" || f.severity === "info");
@@ -2806,7 +3092,7 @@ async function doctorCommand(args) {
 }
 
 // src/commands/eject.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync6 } from "node:fs";
 import { join as join9 } from "node:path";
 
 // src/lib/prompt.ts
@@ -2889,11 +3175,11 @@ function parse(args) {
 }
 function readManifest(repoRoot) {
   const p = join9(repoRoot, CONFIG_PATH);
-  if (!existsSync8(p))
+  if (!existsSync9(p))
     return { kind: "none" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync5(p, "utf-8"));
+    raw = JSON.parse(readFileSync6(p, "utf-8"));
   } catch (err) {
     return { kind: "orphan", reason: `vinaya.config.json is not valid JSON: ${err.message}` };
   }
@@ -2976,7 +3262,7 @@ async function ejectCommand(args) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join10 } from "node:path";
 function realDeps5() {
   return {
@@ -2998,17 +3284,17 @@ function flags(args) {
 var PRODUCT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 function readManifest2(repoRoot) {
   const p = join10(repoRoot, CONFIG_PATH);
-  if (!existsSync9(p))
+  if (!existsSync10(p))
     return null;
   try {
-    return VinayaConfigSchema.parse(JSON.parse(readFileSync6(p, "utf-8"))).managed ?? null;
+    return VinayaConfigSchema.parse(JSON.parse(readFileSync7(p, "utf-8"))).managed ?? null;
   } catch {
     return null;
   }
 }
 function writeManifest(repoRoot, manifest) {
   const configAbs = join10(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync6(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync7(configAbs, "utf-8"));
   writeFileSync4(configAbs, `${JSON.stringify({ ...seed, managed: manifest }, null, 2)}
 `, "utf-8");
 }
@@ -3148,7 +3434,7 @@ import { execFileSync as execFileSync6 } from "node:child_process";
 
 // src/lib/forge-write.ts
 import { mkdtempSync, rmSync as rmSync3, writeFileSync as writeFileSync5 } from "node:fs";
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as join11 } from "node:path";
 class ForgeArgError extends Error {
@@ -3160,13 +3446,13 @@ function locateBody(args) {
       const p = args[i + 1];
       if (!p)
         throw new ForgeArgError("`--body-file` was given with no path.");
-      return { body: readFileSync7(p, "utf8"), source: { kind: "file", argIndex: i + 1, inlineForm: false } };
+      return { body: readFileSync8(p, "utf8"), source: { kind: "file", argIndex: i + 1, inlineForm: false } };
     }
     if (a.startsWith("--body-file=")) {
       const p = a.slice("--body-file=".length);
       if (!p)
         throw new ForgeArgError("`--body-file=` was given with no path.");
-      return { body: readFileSync7(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
+      return { body: readFileSync8(p, "utf8"), source: { kind: "file", argIndex: i, inlineForm: true } };
     }
     if (a === "--body" || a === "-b") {
       const v = args[i + 1];
@@ -3456,7 +3742,7 @@ function issueEditCommand(args) {
 }
 
 // src/commands/new-check.ts
-import { chmodSync as chmodSync2, existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join12 } from "node:path";
 var TEMPLATE_PATH = join12(packageRoot(import.meta.url), "templates", "custom-check.template.ts");
 var CHECKS_DIR = join12("scripts", "vinaya-checks");
@@ -3468,14 +3754,14 @@ function newCheckCommand(args) {
     process.exit(2);
   }
   const scriptsDir = join12(process.cwd(), CHECKS_DIR);
-  if (!existsSync10(scriptsDir))
+  if (!existsSync11(scriptsDir))
     mkdirSync3(scriptsDir, { recursive: true });
   const targetPath = join12(scriptsDir, `${name}.ts`);
-  if (existsSync10(targetPath)) {
+  if (existsSync11(targetPath)) {
     console.error(`Error: ${targetPath} already exists.`);
     process.exit(1);
   }
-  const template = readFileSync8(TEMPLATE_PATH, "utf-8");
+  const template = readFileSync9(TEMPLATE_PATH, "utf-8");
   const contents = template.split("{{CHECK_NAME}}").join(name);
   writeFileSync6(targetPath, contents, "utf-8");
   chmodSync2(targetPath, 493);
@@ -3639,16 +3925,16 @@ function prEditCommand(args) {
 
 // src/commands/studio.ts
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
 import { dirname as dirname4, join as join13 } from "node:path";
 function resolveStudioTarget(cwd) {
   let dir = cwd;
   for (;; ) {
     const webDir = join13(dir, "apps", "vinaya", "web");
     const pkgPath = join13(webDir, "package.json");
-    if (existsSync11(pkgPath)) {
+    if (existsSync12(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
         if (pkg.name === "@atta/vinaya-web") {
           return { kind: "workspace", webDir };
         }
@@ -3681,7 +3967,7 @@ async function runStudio(cwd, args) {
 }
 
 // src/commands/upgrade.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join14 } from "node:path";
 function realDeps6() {
   return {
@@ -3699,11 +3985,11 @@ function flags2(args) {
 }
 function readManifest3(repoRoot) {
   const p = join14(repoRoot, CONFIG_PATH);
-  if (!existsSync12(p))
+  if (!existsSync13(p))
     return { kind: "missing" };
   let raw;
   try {
-    raw = JSON.parse(readFileSync10(p, "utf-8"));
+    raw = JSON.parse(readFileSync11(p, "utf-8"));
   } catch (err) {
     return { kind: "invalid", error: `invalid JSON: ${err.message}` };
   }
@@ -3720,7 +4006,7 @@ function readManifest3(repoRoot) {
 }
 function writeManifestVersion(repoRoot, manifest) {
   const configAbs = join14(repoRoot, CONFIG_PATH);
-  const seed = JSON.parse(readFileSync10(configAbs, "utf-8"));
+  const seed = JSON.parse(readFileSync11(configAbs, "utf-8"));
   const updated = { ...manifest, version: MANAGED_MANIFEST_VERSION };
   writeFileSync7(configAbs, `${JSON.stringify({ ...seed, managed: updated }, null, 2)}
 `, "utf-8");
@@ -3734,7 +4020,7 @@ function planUpgrade(ops, repoRoot, manifest) {
   for (const op of ops) {
     if (op.kind === "create-file") {
       const abs2 = join14(repoRoot, op.path);
-      const exists = existsSync12(abs2);
+      const exists = existsSync13(abs2);
       const owned = ownedFiles.has(op.path);
       let action;
       if (op.path === CONFIG_PATH) {
@@ -3744,7 +4030,7 @@ function planUpgrade(ops, repoRoot, manifest) {
       } else if (!exists) {
         action = "recreate";
         hasChanges = true;
-      } else if (readFileSync10(abs2, "utf-8") !== op.content) {
+      } else if (readFileSync11(abs2, "utf-8") !== op.content) {
         action = "regenerate";
         hasChanges = true;
       } else {
@@ -3757,11 +4043,11 @@ function planUpgrade(ops, repoRoot, manifest) {
       let action;
       if (!owned) {
         action = "not-installed";
-      } else if (!existsSync12(abs2)) {
+      } else if (!existsSync13(abs2)) {
         action = "recreate-host";
         hasChanges = true;
       } else {
-        const content = readFileSync10(abs2, "utf-8");
+        const content = readFileSync11(abs2, "utf-8");
         const { begin, end } = markerLines(op.marker, op.comment);
         if (!(content.includes(begin) && content.includes(end))) {
           action = "recreate-append";
@@ -3838,7 +4124,7 @@ function renderUpgradeDiff(plan) {
 }
 function regenerateBlock(repoRoot, op) {
   const abs2 = join14(repoRoot, op.path);
-  const content = readFileSync10(abs2, "utf-8");
+  const content = readFileSync11(abs2, "utf-8");
   const stripped = stripBlockFromContent(content, op.marker, op.comment);
   if (stripped !== null) {
     writeFileSync7(abs2, stripped.endsWith(`
@@ -4079,6 +4365,9 @@ var COMMANDS = [
       { flag: "--diff-only", description: "Scope diff-declared checks to changed files" },
       { flag: "--parallel[=n]", description: "Concurrency cap (default: cpu-derived)" }
     ],
+    details: [
+      "Each spawned check's child process sees only a fixed baseline (`PATH`, `LANG`, `HOME`, `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `TMPDIR`) plus whatever its `CheckSpec['env']` declaration explicitly forwards — never the full parent environment. A required (`true`) or unsatisfied `anyOf` declaration missing from the caller's environment synthesizes a `CheckError` before the check ever spawns. Declare `env` (a core check's own registration, or `vinaya.config.json`'s `checks.<name>.env` for a custom one) for any check that reads `process.env`/`Bun.env`/`Deno.env` directly — `vinaya doctor` carries the permanent diagnostic for one that doesn't."
+    ],
     status: "shipped"
   },
   {
@@ -4148,6 +4437,9 @@ var COMMANDS = [
     name: "doctor",
     description: "Diagnose hook, workflow, and config health — report only, never mutates",
     flags: [{ flag: "--json", description: "Enveloped JSON output (schema: 1)" }],
+    details: [
+      'Carries the same env-declaration diagnostic `vinaya check` warns with — permanently, at `info` severity, not just ahead of the spawn-default flip — plus a `warn`-severity lint over suspicious `env` literal forms (a stray `"true"`/`"false"` string, or a high-entropy literal that reads like a leaked secret committed to config).'
+    ],
     status: "shipped"
   },
   {
@@ -4252,7 +4544,7 @@ function printHelp() {
 // src/index.ts
 var PACKAGE_ROOT = join15(dirname5(fileURLToPath2(import.meta.url)), "..");
 function readVersion2() {
-  const pkg = JSON.parse(readFileSync11(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync12(join15(PACKAGE_ROOT, "package.json"), "utf-8"));
   return pkg.version;
 }
 var [, , command, ...args] = process.argv;