heyspex 0.1.0

package/dist/cli/hs-check.mjs

@@ -0,0 +1,747 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-check.ts
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync as readFileSync4 } from "node:fs";
+import path2 from "node:path";
+import process2 from "node:process";
+
+// spex-console/src/lib/cli/checks-manifest.ts
+var EXIT = {
+  /** Every machine/property criterion passed (judgment-only criteria don't fail the run). */
+  OK: 0,
+  /** Usage error — unknown flag, missing target, or bad verb. */
+  USAGE: 1,
+  /** Manifest / target not found. */
+  NOT_FOUND: 10,
+  /** Manifest present but malformed. */
+  INVALID_MANIFEST: 11,
+  /** A check executor was required but unavailable (e.g. the command runner). */
+  RUNNER_MISSING: 12,
+  /** The manifest ran and at least one machine criterion failed (a real red). */
+  CHECKS_FAILED: 20
+};
+function parseCheckRunArgs(argv) {
+  const verbRaw = argv[0];
+  if (verbRaw === "--help" || verbRaw === "-h") return { help: true };
+  if (verbRaw !== "run") {
+    return { error: { code: EXIT.USAGE, message: `unknown verb: ${verbRaw ?? "(none)"}` } };
+  }
+  let target;
+  let json = false;
+  let report = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--report") report = true;
+    else if (arg === "--manifest" || arg.startsWith("--manifest=")) {
+      const value = arg.includes("=") ? arg.slice("--manifest=".length) : argv[++i];
+      if (value === void 0) {
+        return { error: { code: EXIT.USAGE, message: "--manifest requires a value" } };
+      }
+      target = value;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (target === void 0) {
+      target = arg;
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (!target) {
+    return { error: { code: EXIT.USAGE, message: "run requires a spec id or manifest path" } };
+  }
+  return { args: { verb: "run", target, json, report } };
+}
+function buildVerdict(report) {
+  return {
+    manifestPassed: report.passed,
+    source: report.frozenAt ? `hs check run @ ${report.frozenAt}` : "hs check run",
+    failed: report.failedCount,
+    judgmentOnly: report.judgmentOnlyCount
+  };
+}
+var KIND_ALIASES = {
+  tests: "test",
+  unit: "test",
+  grep: "command",
+  diff: "command",
+  live: "command"
+};
+function joinUnderRoot(root, rel) {
+  if (rel === "" || rel === ".") return root;
+  if (/^(?:[a-zA-Z]:[\\/]|[\\/])/.test(rel)) return rel;
+  const sep = root.includes("\\") && !root.includes("/") ? "\\" : "/";
+  return `${root.replace(/[\\/]+$/, "")}${sep}${rel.replace(/^[\\/]+/, "")}`;
+}
+function resolveCheckCwds(check, roots) {
+  if (typeof check.cwd === "string" && check.cwd.trim() !== "") {
+    return [joinUnderRoot(roots.repoRoot, check.cwd.trim())];
+  }
+  return roots.repoRoot === roots.consoleRoot ? [roots.repoRoot] : [roots.repoRoot, roots.consoleRoot];
+}
+var VALID_METHODS = /* @__PURE__ */ new Set([
+  "machine",
+  "property",
+  "human"
+]);
+var VALID_KINDS = /* @__PURE__ */ new Set([
+  "test",
+  "lint",
+  "types",
+  "command",
+  "guard"
+]);
+var VALID_EXPECTS = /* @__PURE__ */ new Set([
+  "exit-0",
+  "no-net-new",
+  "empty-output"
+]);
+function parseChecksManifest(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return {
+      error: `manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  if (typeof raw !== "object" || raw === null) {
+    return { error: "manifest must be an object" };
+  }
+  const rec = raw;
+  if (typeof rec.spec !== "string" || rec.spec.trim() === "") {
+    return { error: 'manifest is missing a non-empty "spec"' };
+  }
+  if (!Array.isArray(rec.criteria)) {
+    return { error: 'manifest must have a "criteria" array' };
+  }
+  const criteria = [];
+  for (let i = 0; i < rec.criteria.length; i++) {
+    const c = rec.criteria[i];
+    if (typeof c !== "object" || c === null) {
+      return { error: `criteria[${i}] must be an object` };
+    }
+    const cr = c;
+    const ac = typeof cr.ac === "number" ? cr.ac : i + 1;
+    const ctext = typeof cr.text === "string" ? cr.text : "";
+    const method = cr.method;
+    if (typeof method !== "string" || !VALID_METHODS.has(method)) {
+      return { error: `criteria[${i}].method must be one of machine|property|human` };
+    }
+    const rawChecks = cr.checks ?? [];
+    if (!Array.isArray(rawChecks)) {
+      return { error: `criteria[${i}].checks must be an array` };
+    }
+    if (method === "human" && rawChecks.length > 0) {
+      return {
+        error: `criteria[${i}] is method:human but has checks \u2014 judgment-only criteria carry none`
+      };
+    }
+    if (method !== "human" && rawChecks.length === 0) {
+      return { error: `criteria[${i}] is method:${method} but has no checks to run` };
+    }
+    const checks = [];
+    for (let j = 0; j < rawChecks.length; j++) {
+      const t = rawChecks[j];
+      if (typeof t !== "object" || t === null) {
+        return { error: `criteria[${i}].checks[${j}] must be an object` };
+      }
+      const tr = t;
+      if (typeof tr.kind !== "string") {
+        return {
+          error: `criteria[${i}].checks[${j}].kind must be one of test|lint|types|command|guard`
+        };
+      }
+      const kind = KIND_ALIASES[tr.kind] ?? tr.kind;
+      if (!VALID_KINDS.has(kind)) {
+        return {
+          error: `criteria[${i}].checks[${j}].kind must be one of test|lint|types|command|guard`
+        };
+      }
+      if (typeof tr.run !== "string" || tr.run.trim() === "") {
+        return { error: `criteria[${i}].checks[${j}] is missing a non-empty "run"` };
+      }
+      const expectRaw = tr.expect ?? "exit-0";
+      if (typeof expectRaw !== "string" || !VALID_EXPECTS.has(expectRaw)) {
+        return {
+          error: `criteria[${i}].checks[${j}].expect must be one of exit-0|no-net-new|empty-output`
+        };
+      }
+      const baseline = typeof tr.baseline === "number" && Number.isFinite(tr.baseline) ? tr.baseline : 0;
+      const cwd = typeof tr.cwd === "string" && tr.cwd.trim() !== "" ? tr.cwd.trim() : void 0;
+      checks.push({
+        kind,
+        run: tr.run,
+        expect: expectRaw,
+        baseline,
+        ...cwd ? { cwd } : {}
+      });
+    }
+    criteria.push({ ac, text: ctext, method, checks });
+  }
+  const frozenAt = rec.frozen_at ?? rec.frozenAt;
+  const authoredBy = rec.authored_by ?? rec.authoredBy;
+  return {
+    manifest: {
+      spec: rec.spec,
+      frozenAt: typeof frozenAt === "string" && frozenAt.trim() !== "" ? frozenAt : null,
+      authoredBy: typeof authoredBy === "string" && authoredBy.trim() !== "" ? authoredBy : null,
+      criteria
+    }
+  };
+}
+var ZERO_MATCH_RE = /Passed:\s*0\b|No test is available|No test files found|No test matches the given testcase filter/i;
+function detectZeroMatch(rawOutput) {
+  if (!rawOutput) return null;
+  const line = rawOutput.split(/\r?\n/).find((l) => ZERO_MATCH_RE.test(l));
+  return line ? line.trim() : null;
+}
+function evaluateCheck(check, outcome) {
+  if (detectZeroMatch(outcome.rawOutput) !== null) return false;
+  if (check.expect === "no-net-new") {
+    return (outcome.errorCount ?? 0) <= check.baseline;
+  }
+  if (check.expect === "empty-output") {
+    return outcome.exitCode === 0 && (outcome.stdout ?? "\0").trim() === "";
+  }
+  return outcome.exitCode === 0;
+}
+async function runChecksManifest(manifest, deps) {
+  const criteria = [];
+  let durationMs = 0;
+  for (const entry of manifest.criteria) {
+    if (entry.method === "human") {
+      criteria.push({
+        ac: entry.ac,
+        text: entry.text,
+        method: entry.method,
+        verdict: "judgment_only",
+        checks: []
+      });
+      continue;
+    }
+    const checkResults = [];
+    for (const check of entry.checks) {
+      let outcome;
+      try {
+        outcome = await deps.runCheck(check);
+      } catch (err) {
+        outcome = {
+          exitCode: -1,
+          durationMs: 0,
+          message: err instanceof Error ? err.message : String(err)
+        };
+      }
+      const passed = evaluateCheck(check, outcome);
+      durationMs += outcome.durationMs;
+      checkResults.push({
+        check,
+        passed,
+        durationMs: outcome.durationMs,
+        message: passed ? void 0 : outcome.message ?? failureMessage(check, outcome)
+      });
+    }
+    const verdict = checkResults.every((r) => r.passed) ? "pass" : "fail";
+    criteria.push({
+      ac: entry.ac,
+      text: entry.text,
+      method: entry.method,
+      verdict,
+      checks: checkResults
+    });
+  }
+  const passedCount = criteria.filter((c) => c.verdict === "pass").length;
+  const failedCount = criteria.filter((c) => c.verdict === "fail").length;
+  const judgmentOnlyCount = criteria.filter((c) => c.verdict === "judgment_only").length;
+  return {
+    spec: manifest.spec,
+    frozenAt: manifest.frozenAt,
+    authoredBy: manifest.authoredBy,
+    criteria,
+    passed: failedCount === 0,
+    total: criteria.length,
+    passedCount,
+    failedCount,
+    judgmentOnlyCount,
+    durationMs
+  };
+}
+function failureMessage(check, outcome) {
+  const zeroMatch = detectZeroMatch(outcome.rawOutput);
+  if (zeroMatch !== null) {
+    return `zero-match: the check's filter matched nothing to run \u2014 "${zeroMatch}"`;
+  }
+  if (check.expect === "no-net-new") {
+    return `${outcome.errorCount ?? "?"} errors exceeds baseline ${check.baseline}`;
+  }
+  return `command exited ${outcome.exitCode}`;
+}
+function reportExitCode(report) {
+  return report.passed ? EXIT.OK : EXIT.CHECKS_FAILED;
+}
+var VERDICT_MARK = {
+  pass: "PASS",
+  fail: "FAIL",
+  judgment_only: "JUDG"
+};
+function toText(report) {
+  if (report.total === 0) {
+    return "No criteria in manifest.";
+  }
+  const lines = [];
+  lines.push(`Verifying ${report.spec}` + (report.frozenAt ? ` (frozen ${report.frozenAt})` : ""));
+  for (const c of report.criteria) {
+    const head = `[${VERDICT_MARK[c.verdict]}] AC${c.ac} (${c.method}) \u2014 ${c.text}`;
+    lines.push(head);
+    if (c.verdict === "judgment_only") {
+      lines.push("       \u2192 judgment-only: no machine check; handed to the council.");
+    }
+    for (const r of c.checks) {
+      const m = r.passed ? "ok  " : "FAIL";
+      const detail = !r.passed && r.message ? ` \u2014 ${r.message}` : "";
+      lines.push(`       ${m} ${r.check.kind}: ${r.check.run} (${r.durationMs}ms)${detail}`);
+    }
+  }
+  const overall = report.passed ? "PASS" : "FAIL";
+  lines.push("");
+  lines.push(
+    `${overall}: ${report.passedCount} passed, ${report.failedCount} failed, ${report.judgmentOnlyCount} judgment-only of ${report.total} criteria (${report.durationMs}ms)`
+  );
+  return lines.join("\n");
+}
+function formatReport(report) {
+  return toText(report);
+}
+function reportToJson(report) {
+  return {
+    ok: report.passed,
+    spec: report.spec,
+    frozenAt: report.frozenAt,
+    authoredBy: report.authoredBy,
+    total: report.total,
+    passed: report.passedCount,
+    failed: report.failedCount,
+    judgmentOnly: report.judgmentOnlyCount,
+    durationMs: report.durationMs,
+    criteria: report.criteria.map((c) => ({
+      ac: c.ac,
+      method: c.method,
+      verdict: c.verdict,
+      checks: c.checks.map((r) => ({
+        kind: r.check.kind,
+        run: r.check.run,
+        passed: r.passed,
+        durationMs: r.durationMs,
+        ...r.passed ? {} : { message: r.message }
+      }))
+    }))
+  };
+}
+var HELP = [
+  "Usage:",
+  "  hs check run <spec-id|manifest.json> [--json]",
+  "",
+  "Verify a spec's acceptance criteria against its frozen checks manifest, and",
+  "report pass/fail PER CRITERION against the real working tree (HS-EPIC-DCEP).",
+  "Machine criteria run their checks; method:human criteria are reported",
+  "judgment-only and handed to the council \u2014 never silently auto-passed.",
+  "",
+  "Manifest shape (specs/checks/<spec-id>.checks.json):",
+  '  { "spec": "[[HS-EPIC-XYZ]]", "frozen_at": "...", "authored_by": "...",',
+  '    "criteria": [ { "ac": 1, "text": "...", "method": "machine",',
+  '                    "checks": [ { "kind": "types", "run": "npx tsc --noEmit",',
+  '                                  "expect": "no-net-new", "baseline": 60 } ] } ] }',
+  "",
+  "Arguments:",
+  "  <spec-id|manifest.json>  A manifest path, or a spec id resolved to",
+  "                           specs/checks/<id>.checks.json under the vault root.",
+  "",
+  "Flags:",
+  "  --manifest <p>   Manifest path (alias for the positional argument).",
+  "  --report         PATCH the verdict to the spec's active claim (the PCFL gate).",
+  "                   Requires a spec-id target (identifies the claim). The verify",
+  "                   exit code is unchanged; reporting is a side effect.",
+  "  --json           Emit a machine-readable JSON result (the gate's input shape).",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes:",
+  "  0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-manifest \xB7 12 runner-missing \xB7 20 checks-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/control-shared.ts
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var EXIT2 = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — unknown subcommand/flag, or a missing required argument. */
+  USAGE: 1,
+  /** Claim race lost — the spec is already claimed by another agent (409). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  FORBIDDEN: 15
+};
+function readPairedToken() {
+  try {
+    const raw = readFileSync(join(homedir(), ".heyspex", "credentials.yaml"), "utf-8");
+    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
+    return match?.[1];
+  } catch {
+    return void 0;
+  }
+}
+function bearerHeaderFor(consoleUrl) {
+  try {
+    const host = new URL(consoleUrl).hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1") {
+      return {};
+    }
+    const token = readPairedToken();
+    return token ? { authorization: `Bearer ${token}` } : {};
+  } catch {
+    return {};
+  }
+}
+async function controlRequest(deps, req) {
+  const url = `${deps.consoleUrl}${req.path}`;
+  let res;
+  try {
+    res = await deps.fetchImpl(url, {
+      method: req.method,
+      headers: {
+        "content-type": "application/json",
+        // A remote console (cloud vault write mode, [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]])
+        // authenticates every control call; loopback never asked, so the header
+        // is attached only when the target is non-loopback and a paired token
+        // exists. Same `hsmcp_` bearer the MCP server presents.
+        ...bearerHeaderFor(deps.consoleUrl)
+      },
+      ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {}
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: {
+        code: EXIT2.CONSOLE_UNREACHABLE,
+        message: `could not reach console at ${deps.consoleUrl}: ${message}
+  Start the dev server or set HEYSPEX_CONSOLE_URL.`,
+        payload: {
+          ok: false,
+          error: "console_unreachable",
+          url: deps.consoleUrl,
+          message
+        },
+        isError: true
+      }
+    };
+  }
+  let parsed = null;
+  try {
+    parsed = await res.json();
+  } catch {
+  }
+  if (res.status === 402) {
+    return {
+      ok: false,
+      error: {
+        code: EXIT2.NEON_REQUIRED,
+        message: "this command requires the Neon control plane, which is not configured (console returned 402).",
+        payload: {
+          ok: false,
+          error: "neon_required",
+          status: 402,
+          console_response: parsed
+        },
+        isError: true
+      }
+    };
+  }
+  return { ok: true, status: res.status, body: parsed };
+}
+
+// spex-console/src/lib/cli/defer.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// scripts/lib/console-url-resolver.mjs
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+
+// spex-console/src/lib/cli/defer.ts
+function resolveSpexConsoleUrl(vaultRoot, readDiscovery, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (raw && raw.length > 0) return raw.replace(/\/+$/, "");
+  try {
+    const homeDir = opts.homeDir ?? os.homedir();
+    const readFile = opts.readFile ?? ((p) => readFileSync3(p, "utf-8"));
+    const credentials = readFile(path.join(homeDir, ".heyspex", "credentials.yaml"));
+    const match = credentials.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    if (value && value.length > 0) return value.replace(/\/+$/, "");
+  } catch {
+  }
+  for (const name of ["console-url", "cockpit-url"]) {
+    try {
+      const discovery = readDiscovery(`${vaultRoot}/.heyspex/${name}`);
+      if (discovery && discovery.trim().length > 0) {
+        return discovery.trim().replace(/\/+$/, "");
+      }
+    } catch {
+    }
+  }
+  return DEFAULT_CONSOLE_URL;
+}
+var HELP2 = [
+  "Usage:",
+  "  hs defer <spec-id> [--until <when>] [--json] [--no-daemon]",
+  "  hs undefer <spec-id> [--json] [--no-daemon]",
+  "",
+  "Time-shift a spec via its `defer_until` frontmatter field. A deferred spec is",
+  "scheduler-invisible until the date passes, then auto-revives.",
+  "",
+  "Arguments:",
+  "  <spec-id>        The spec to defer/undefer (e.g. HS-TASK-EWL5).",
+  "",
+  "Flags:",
+  "  --until <when>   ISO date, or relative offset +Nd / +Nw / +Nm / +Ny.",
+  "                   Defaults to +1y (matches the console Defer button).",
+  "                   Ignored by `undefer` (which always clears the field).",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --no-daemon      Write straight to the vault (no console needed; CI path).",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/bin/hs-check.ts
+function manifestForSpecId(vaultRoot, specId) {
+  return path2.join(vaultRoot, "specs", "checks", `${specId}.checks.json`);
+}
+function resolveManifestPath(target, vaultRoot, invokedCwd) {
+  const literal = path2.resolve(invokedCwd, target);
+  if (existsSync(literal)) return literal;
+  if (target.endsWith(".json")) return null;
+  const byId = manifestForSpecId(vaultRoot, target);
+  return existsSync(byId) ? byId : null;
+}
+function countTscErrors(output) {
+  const matches = output.match(/error TS\d+/g);
+  return matches ? matches.length : 0;
+}
+var cachedPosixShell;
+function resolveWindowsPosixShell() {
+  if (cachedPosixShell !== void 0) return cachedPosixShell;
+  const candidates = [
+    process2.env.HEYSPEX_CHECK_SHELL,
+    "C:\\Program Files\\Git\\bin\\bash.exe"
+  ].filter((c) => typeof c === "string" && c.length > 0);
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return cachedPosixShell = candidate;
+  }
+  const where = spawnSync("where", ["bash"], { encoding: "utf8", windowsHide: true });
+  if (where.status === 0 && where.stdout) {
+    const hit = where.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).find((line) => !/\\system32\\/i.test(line));
+    if (hit && existsSync(hit)) return cachedPosixShell = hit;
+  }
+  return cachedPosixShell = null;
+}
+var MISSING_BINARY_RE = /command not found|is not recognized as an internal or external command/i;
+var warnedCmdFallback = false;
+function runCheckInDirectory(check, cwd) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const needsErrorCount = check.expect === "no-net-new";
+    const needsStdout = check.expect === "empty-output";
+    const stdio = ["ignore", "pipe", "pipe"];
+    const posixShell = process2.platform === "win32" ? resolveWindowsPosixShell() : null;
+    if (process2.platform === "win32" && !posixShell && !warnedCmdFallback) {
+      warnedCmdFallback = true;
+      process2.stderr.write(
+        "hs check: WARNING \u2014 no POSIX shell found (git-bash missing; set HEYSPEX_CHECK_SHELL to a bash.exe).\n  Falling back to cmd.exe: POSIX-authored checks (test/grep/find/globs) will MISREPORT \u2014 false-fails, and inverted checks can false-PASS (HS-FCW8).\n"
+      );
+    }
+    const child = posixShell ? spawn(posixShell, ["-lc", check.run], { cwd, stdio, windowsHide: true }) : spawn(check.run, { shell: true, cwd, stdio });
+    let captured = "";
+    let stdoutOnly = "";
+    child.stdout?.on("data", (chunk) => {
+      captured += chunk.toString();
+      stdoutOnly += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      captured += chunk.toString();
+    });
+    child.on("error", (err) => {
+      resolve({ exitCode: -1, durationMs: Date.now() - started, message: err.message });
+    });
+    child.on("close", (code) => {
+      const durationMs = Date.now() - started;
+      let exitCode = code ?? -1;
+      const missingBinary = exitCode === 0 && MISSING_BINARY_RE.test(captured);
+      if (missingBinary) exitCode = 127;
+      const outcome = { exitCode, durationMs, rawOutput: captured };
+      if (needsStdout) outcome.stdout = stdoutOnly;
+      if (needsErrorCount) {
+        outcome.errorCount = missingBinary ? check.baseline + 1 : countTscErrors(captured);
+      }
+      if (missingBinary) {
+        const line = captured.split("\n").find((l) => MISSING_BINARY_RE.test(l))?.trim();
+        outcome.message = `errored, not ok \u2014 shell reported a missing binary (${line ?? "command not found"})`;
+      } else if (exitCode !== 0 && check.expect === "exit-0") {
+        const trimmed = captured.trim();
+        outcome.message = trimmed.length > 0 ? trimmed.split("\n").slice(-3).join(" ") : `command exited ${exitCode}`;
+      }
+      resolve(outcome);
+    });
+  });
+}
+function makeRunCheck(vaultRoot) {
+  return async (check) => {
+    const cwds = resolveCheckCwds(check, {
+      repoRoot: vaultRoot,
+      consoleRoot: path2.join(vaultRoot, "spex-console")
+    });
+    let lastFailure = null;
+    for (const cwd of cwds) {
+      const outcome = await runCheckInDirectory(check, cwd);
+      if (evaluateCheck(check, outcome)) return outcome;
+      lastFailure = outcome;
+    }
+    if (!lastFailure) {
+      return { exitCode: -1, durationMs: 0, message: "no candidate cwd resolved for check" };
+    }
+    const zeroMatch = detectZeroMatch(lastFailure.rawOutput);
+    const detail = lastFailure.message ?? (zeroMatch !== null ? `zero-match: the check's filter matched nothing to run \u2014 "${zeroMatch}"` : check.expect === "no-net-new" && lastFailure.errorCount !== void 0 ? `${lastFailure.errorCount} errors exceeds baseline ${check.baseline}` : check.expect === "empty-output" ? `command printed output or exited ${lastFailure.exitCode}` : `command exited ${lastFailure.exitCode}`);
+    return {
+      ...lastFailure,
+      message: `all ${cwds.length} candidate cwd(s) tried \u2014 ${cwds.join(", ")}; last failure: ${detail}`
+    };
+  };
+}
+async function main() {
+  const vaultRoot = process2.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process2.stderr.write(
+      "hs check: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process2.exit(EXIT.USAGE);
+  }
+  const parsed = parseCheckRunArgs(process2.argv.slice(3));
+  if (parsed.help) {
+    process2.stdout.write(`${HELP}
+`);
+    process2.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs check: ${parsed.error.message}
+`);
+    process2.exit(parsed.error.code);
+  }
+  const args = parsed.args;
+  const invokedCwd = process2.env.HS_INVOKED_CWD?.trim() || process2.cwd();
+  const manifestPath = resolveManifestPath(args.target, vaultRoot, invokedCwd);
+  if (!manifestPath) {
+    process2.stderr.write(
+      `hs check: no manifest for "${args.target}".
+  Pass a manifest path, or create ${path2.join("specs", "checks", `${args.target}.checks.json`)} under the vault root.
+`
+    );
+    process2.exit(EXIT.NOT_FOUND);
+  }
+  const { manifest, error } = parseChecksManifest(readFileSync4(manifestPath, "utf-8"));
+  if (error) {
+    process2.stderr.write(`hs check: ${manifestPath}: ${error}
+`);
+    process2.exit(EXIT.INVALID_MANIFEST);
+  }
+  const report = await runChecksManifest(manifest, { runCheck: makeRunCheck(vaultRoot) });
+  const sink = report.passed ? process2.stdout : process2.stderr;
+  if (args.json) {
+    sink.write(`${JSON.stringify(reportToJson(report))}
+`);
+  } else {
+    sink.write(`${formatReport(report)}
+`);
+  }
+  if (args.report) {
+    await reportVerdict(args.target, report, vaultRoot);
+  }
+  process2.exit(reportExitCode(report));
+}
+async function reportVerdict(target, report, vaultRoot) {
+  if (existsSync(target) || target.endsWith(".json")) {
+    process2.stderr.write(
+      "hs check: --report needs a spec-id target (to identify the claim), not a manifest path.\n"
+    );
+    return;
+  }
+  const consoleUrl = resolveSpexConsoleUrl(vaultRoot, (p) => {
+    try {
+      return readFileSync4(p, "utf-8");
+    } catch {
+      return null;
+    }
+  });
+  const verdict = buildVerdict(report);
+  const res = await controlRequest(
+    { fetchImpl: fetch, consoleUrl },
+    {
+      method: "PATCH",
+      path: `/api/specs/${encodeURIComponent(target)}/claim/status`,
+      body: { status: "working", verification: verdict }
+    }
+  );
+  if (!res.ok) {
+    process2.stderr.write(`hs check: verdict not reported \u2014 ${res.error.message}
+`);
+    return;
+  }
+  if (res.status === 404) {
+    process2.stderr.write(
+      `hs check: no active claim for ${target} \u2014 verdict not reported (claim it first).
+`
+    );
+    return;
+  }
+  if (res.status !== 200) {
+    process2.stderr.write(`hs check: verdict not reported \u2014 console returned ${res.status}.
+`);
+    return;
+  }
+  const flipped = res.body?.autoShip;
+  const note = flipped && flipped.flipped !== false ? ` \u2192 gate flipped to ${flipped.effective_status}` : "";
+  process2.stderr.write(
+    `hs check: reported verdict (manifestPassed=${verdict.manifestPassed})${note}
+`
+  );
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process2.stderr.write(`hs check: unhandled: ${message}
+`);
+  process2.exit(EXIT.RUNNER_MISSING);
+});