@foldrun/core 0.2.0

package/src/tar.ts

@@ -0,0 +1,124 @@
+// Reading a .tar.gz, so a deploy can come from a GitHub tarball.
+//
+// `GET /repos/{owner}/{repo}/tarball/{sha}` is one HTTP call and needs no git
+// binary, no clone, and no working copy on the server — which is the whole
+// reason a markdown workspace can deploy from a webhook in a few hundred
+// milliseconds. What it returns is a tar.gz, and Node has gzip but not tar.
+//
+// Deliberately dependency-free, for the same reason the cron parser is: tar is
+// 512-byte blocks with an octal size field, and a reader is shorter than the
+// argument about which library to add.
+
+import zlib from "node:zlib";
+
+const BLOCK = 512;
+
+export interface TarEntry {
+  path: string;
+  content: Buffer;
+}
+
+const str = (b: Buffer, off: number, len: number) => {
+  const raw = b.subarray(off, off + len);
+  const end = raw.indexOf(0);
+  return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+};
+
+// Sizes are octal, space- or NUL-padded. GNU also writes base-256 for large
+// files, flagged by the high bit — irrelevant for markdown, but a silent
+// misparse would be worse than a clear refusal.
+function size(b: Buffer, off: number): number {
+  if (b[off] & 0x80) throw new Error("tar: base-256 size field is not supported");
+  const raw = str(b, off, 12).trim();
+  return raw ? parseInt(raw, 8) : 0;
+}
+
+/**
+ * Every regular file in a gzipped tarball.
+ *
+ * Directories, symlinks, and pax/global headers are skipped: a workspace is
+ * files, and following a link out of the archive is exactly the thing a deploy
+ * from an untrusted repository must not do.
+ */
+export function readTarGz(gz: Buffer): TarEntry[] {
+  const buf = zlib.gunzipSync(gz);
+  const out: TarEntry[] = [];
+  let longName: string | null = null;
+
+  for (let off = 0; off + BLOCK <= buf.length; ) {
+    const header = buf.subarray(off, off + BLOCK);
+    // Two consecutive zero blocks end the archive; one is enough to stop.
+    if (header.every((b) => b === 0)) break;
+
+    const name = str(header, 0, 100);
+    const bytes = size(header, 124);
+    const type = String.fromCharCode(header[156]) || "0";
+    const prefix = str(header, 345, 155);
+    off += BLOCK;
+
+    const body = buf.subarray(off, off + bytes);
+    off += Math.ceil(bytes / BLOCK) * BLOCK;
+
+    // GNU long name: the next header's name lives in this entry's body.
+    if (type === "L") {
+      longName = body.toString("utf8").replace(/\0+$/, "");
+      continue;
+    }
+    if (type !== "0" && type !== "\0") {
+      longName = null;
+      continue;
+    }
+
+    const full = longName ?? (prefix ? `${prefix}/${name}` : name);
+    longName = null;
+    if (full) out.push({ path: full, content: Buffer.from(body) });
+  }
+
+  return out;
+}
+
+/**
+ * Drop the single wrapper directory an archive is rooted at.
+ *
+ * GitHub tarballs are rooted at `owner-repo-<sha>/`, which is not part of
+ * anyone's workspace. Stripped only when *every* entry shares one first
+ * segment, so an archive that is already flat is left alone.
+ */
+export function stripRoot(entries: TarEntry[]): TarEntry[] {
+  if (entries.length === 0) return entries;
+  const first = entries[0].path.split("/")[0];
+  if (!entries.every((e) => e.path.split("/")[0] === first && e.path.includes("/"))) {
+    return entries;
+  }
+  return entries.map((e) => ({ ...e, path: e.path.slice(first.length + 1) }));
+}
+
+/**
+ * Read a tarball as the file list a deploy ships.
+ *
+ * `subdir` picks a workspace living inside a larger repository — the common
+ * case, since a repo usually holds more than one thing.
+ */
+export function filesFromTarball(gz: Buffer, subdir = ""): { path: string; content: string }[] {
+  const prefix = subdir.replace(/^\/+|\/+$/g, "");
+  const out: { path: string; content: string }[] = [];
+
+  for (const entry of stripRoot(readTarGz(gz))) {
+    let rel = entry.path;
+    if (prefix) {
+      if (!rel.startsWith(`${prefix}/`)) continue;
+      rel = rel.slice(prefix.length + 1);
+    }
+    // A tarball is untrusted input: an entry can name anything at all, and
+    // `../` in an archive is the oldest way to write outside the destination.
+    if (rel.split("/").includes("..") || rel.startsWith("/")) continue;
+    // AppleDouble sidecars. macOS `tar` writes a `._name` beside every file to
+    // carry metadata no other system wants; they are not part of anyone's
+    // workspace, and letting one through means a deploy rejected for shipping
+    // a file the author never wrote.
+    if ((rel.split("/").pop() ?? "").startsWith("._")) continue;
+    out.push({ path: rel, content: entry.content.toString("utf8") });
+  }
+
+  return out;
+}

package/src/tool-names.ts

@@ -0,0 +1,91 @@
+// The one place that knows which names are the runtime's and which are the
+// author's.
+//
+// `tools:` is Claude Code's field, kept compatible, and grants anything: a
+// built-in group, an exact SDK tool name, or a tool this workspace or account
+// defines. There used to be a second spelling, `use:`, that meant only the
+// author's own tools. It is gone: two keys for one grant meant two places to
+// look for an agent's blast radius, and three readers — the container's
+// egress flag, the library's used-by list, Tool Test's agent picker — read
+// one and forgot the other. A file that still says `use:` gets an error
+// naming the rewrite, and scripts/migrate-use-to-tools.mjs makes it.
+
+import { refList, refNames, type Ref } from "./refs.ts";
+
+/** Groups: one word an author can hold in their head, expanded to SDK names. */
+export const TOOL_MAP: Record<string, string[]> = {
+  // `web` includes Anthropic's server-side WebSearch, the one built-in tool
+  // that runs off the box and bills per call. `fetch` is the local half only:
+  // an agent that searches through the account's own `websearch` tool and
+  // reads pages with WebFetch never leaves the box for anything but tokens.
+  web: ["WebSearch", "WebFetch"],
+  fetch: ["WebFetch"],
+  // `read` is deliberately separate from `files`: an agent that may inspect a
+  // repository but must never modify it is a real and common design.
+  read: ["Read", "Glob", "Grep"],
+  files: ["Read", "Write", "Edit", "Glob", "Grep"],
+  bash: ["Bash"],
+};
+
+/** Exact SDK tool names, accepted alongside the group aliases so a Claude Code
+ *  subagent's `tools: Read, Grep` works unchanged. The aliases exist because
+ *  vendors rename tools; `web` survives a rename that `WebSearch` would not. */
+export const BUILTIN_TOOLS = new Set([
+  "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
+  "WebSearch", "WebFetch", "NotebookEdit", "TodoWrite",
+]);
+
+/** The platform's own groups, served in-process rather than by the SDK. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks"]);
+
+/** Would this name resolve to something the runtime provides? Built-ins win a
+ *  clash, so a tool file of the same name is shadowed rather than granted. */
+export function isRuntimeTool(name: string): boolean {
+  return Boolean(TOOL_MAP[name]) || PLATFORM_GROUPS.has(name) || BUILTIN_TOOLS.has(name);
+}
+
+/** The name an entry grants. `tools:` also takes the map form for approval
+ *  mode — `{Bash: ask}` — where the key is the tool and the value the mode. */
+export function toolEntryName(entry: unknown): string {
+  return refList([entry])[0]?.name ?? "";
+}
+
+type ToolFrontmatter = { tools?: unknown; use?: unknown };
+
+/** Every entry of `tools:`, with whether it was written as a `[[link]]`. */
+export function toolRefs(front: ToolFrontmatter): Ref[] {
+  return refList(front.tools);
+}
+
+/** Is this entry one of the author's own tools? A `[[link]]` always is —
+ *  the brackets say "my file", so `[[search]]` is yours even though `search`
+ *  is a runtime group. A bare name is the author's only when no built-in
+ *  claims it. */
+export function isOwnToolRef(ref: Ref): boolean {
+  return ref.linked || !isRuntimeTool(ref.name);
+}
+
+/**
+ * Every name in `tools:` that can only mean one of the author's own tools.
+ * Deduped, order preserved. Names that resolve to nothing are still
+ * returned: the caller reports them, and "you asked for a tool that isn't
+ * there" is a better error than silence.
+ */
+export function ownToolNames(front: ToolFrontmatter): string[] {
+  const out: string[] = [];
+  for (const ref of toolRefs(front)) {
+    if (isOwnToolRef(ref) && !out.includes(ref.name)) out.push(ref.name);
+  }
+  return out;
+}
+
+/** What a file still says under the removed `use:` key — nothing is granted
+ *  for these; they exist so the error can quote the exact `tools:` line. */
+export function legacyUseNames(front: ToolFrontmatter): string[] {
+  return refNames(front.use);
+}
+
+/** The one sentence every reader of a `use:` key says. */
+export function legacyUseError(names: string[]): string {
+  return `\`use:\` is no longer read — write \`tools: [${names.join(", ")}]\` instead (scripts/migrate-use-to-tools.mjs rewrites every agent). Nothing was granted for it.`;
+}

package/src/tool-programs.ts

@@ -0,0 +1,65 @@
+// Does a script tool's `run:` actually point at a program?
+//
+// The failure this exists for is the quietest one the format has. A script
+// tool whose `run:` resolves to nothing does not raise an error at load: the
+// definition parses, the tool is counted, the agent is told it has the
+// capability — and then the call fails inside a turn as a tool error the
+// model paraphrases into something plausible. `foldrun check` counted such a
+// tool among the workspace's tools and printed "no problems", which is the
+// one report that makes a typo invisible.
+//
+// The resolution here is the runtime's, not a second copy of it. That matters
+// more than it looks: `run:` has six accepted spellings across three scopes,
+// and a checker that reimplemented them would eventually disagree with the
+// runner — passing a tool that cannot run, or failing one that can.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { workspaceDir, workspaceTools, type ToolDef } from "./store.ts";
+import { libraryDir, libraryTools } from "./library.ts";
+import { resolveRunPath } from "./script-tools.ts";
+
+export interface MissingProgram {
+  /** The tool's name, as an agent would write it in `tools:`. */
+  name: string;
+  /** Which shelf it came off — the two resolve differently. */
+  scope: "workspace" | "account";
+  /** The `run:` as the definition spells it, after folder qualification. */
+  run: string;
+  /** The absolute path that was looked for, so the message can be acted on. */
+  looked: string;
+}
+
+/**
+ * Every script tool an agent here could call whose program is not on disk.
+ *
+ * Both shelves, because a grant reaches both and the runtime resolves
+ * nearest-wins across them — a checker that only read the workspace would
+ * call a working account tool broken.
+ */
+export function missingToolPrograms(tenant: string, workspace: string): MissingProgram[] {
+  const dir = workspaceDir(tenant, workspace);
+  // Tools are workspace- or account-scoped, so resolve as if from an agent
+  // directory one level down — the same base the runtime and the tool tester
+  // both use.
+  const from = path.join(dir, "agents", "_probe");
+  const libScripts = libraryDir(tenant, "scripts");
+
+  const out: MissingProgram[] = [];
+  const scan = (defs: Record<string, ToolDef>, scope: "workspace" | "account") => {
+    for (const [name, def] of Object.entries(defs)) {
+      if (def.kind !== "script") continue;
+      const run = String((def.spec as { run?: unknown }).run ?? "");
+      // A single-file tool carries its program in the body and has no path to
+      // resolve. It is a shape we still accept, not a missing program.
+      if (!run) continue;
+      const looked = resolveRunPath(from, run, libScripts);
+      if (!fs.existsSync(looked)) out.push({ name, scope, run, looked });
+    }
+  };
+
+  scan(libraryTools(tenant), "account");
+  scan(workspaceTools(tenant, workspace), "workspace");
+  return out;
+}

package/src/tool-test.ts

@@ -0,0 +1,401 @@
+// Call a tool once, now, and say what happened.
+//
+// Without this, the first time anyone finds out a tool is misconfigured is
+// mid-flow, inside an agent's turn, as a tool error the model paraphrases into
+// something vague. A wrong `base:`, a secret that was never set, a script path
+// with a typo — all of them look identical from the outside: the agent just
+// doesn't use the tool and says something plausible instead.
+//
+// So each transport gets a real exercise, not a syntax check:
+//
+//   http    an actual request to the declared base URL
+//   script  actually runs it, with the workspace's secrets in the environment
+//   mcp     actually starts the server and completes an MCP handshake
+//
+// Nothing here returns a secret value. Missing secrets are reported by *name*,
+// because "which one didn't you set" is the useful half and the value is not.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+import { resolveSecrets } from "./secrets.ts";
+import { listAgents, workspaceDir, type ToolDef } from "./store.ts";
+import { libraryDir } from "./library.ts";
+import { secretsUsedByApi } from "./api-tools.ts";
+import { commandFor, resolveRunPath } from "./script-tools.ts";
+import { parseRuntime, prepareRuntime } from "./runtime.ts";
+
+export interface ToolTestResult {
+  ok: boolean;
+  transport: "http" | "script" | "mcp";
+  /** One line, safe to show next to the button. */
+  summary: string;
+  /** The response body, stdout, or the server's tool list. Truncated. */
+  detail: string;
+  ms: number;
+  /** Names only — never values. */
+  missingSecrets: string[];
+}
+
+const MAX_DETAIL = 4000;
+const TIMEOUT_MS = 15_000;
+
+// A tool test runs tenant-authored code directly on the host — real runs are
+// containerized, this is not — so it must NOT inherit the dashboard's full
+// process.env. That env holds FOLDRUN_SECRET_KEY (the global install key that
+// signs every tenant's webhook tokens and git-push secrets), plus the S3/DB/
+// Stripe/GitHub credentials: handing them to a `console.log(process.env)`
+// script tool is cross-tenant compromise. The child instead starts from a
+// minimal host base — only enough for an interpreter to be found and run —
+// and gets the tool's own declared secrets layered on top by the callers.
+const HOST_BASE_ENV_KEYS = [
+  "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
+  "LC_ALL", "LC_CTYPE", "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+  "NODE_ENV", // not a secret; some interpreters/tools read it.
+  // Windows equivalents, harmless elsewhere.
+  "SYSTEMROOT", "COMSPEC", "PATHEXT", "WINDIR",
+];
+function hostSafeBaseEnv(): NodeJS.ProcessEnv {
+  const base: Record<string, string> = {};
+  for (const k of HOST_BASE_ENV_KEYS) {
+    const v = process.env[k];
+    if (v !== undefined) base[k] = v;
+  }
+  return base as NodeJS.ProcessEnv;
+}
+
+const clip = (s: string) =>
+  s.length > MAX_DETAIL ? `${s.slice(0, MAX_DETAIL)}\n… truncated` : s;
+
+/** `${NAME}` → value, for headers and query. Same rule the runtime uses. */
+const substitute = (v: string, env: Record<string, string>) =>
+  v.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => env[k] ?? "");
+
+export interface ToolTestInput {
+  /** http: the path to try, appended to `base:`. */
+  path?: string;
+  /** script: values for the tool's declared `args:`. */
+  args?: Record<string, string>;
+}
+
+export async function testTool(
+  tenant: string,
+  workspace: string,
+  def: ToolDef,
+  input: ToolTestInput = {},
+): Promise<ToolTestResult> {
+  const probePath = input.path ?? "";
+  const started = Date.now();
+  const done = (r: Omit<ToolTestResult, "ms">): ToolTestResult => ({ ...r, ms: Date.now() - started });
+
+  if (def.kind === "http") {
+    const api = def.spec;
+    const needed = secretsUsedByApi(api);
+    const { env, missing } = resolveSecrets(tenant, needed, workspace);
+
+    try {
+      const rel = probePath.startsWith("/") || probePath === "" ? probePath : `/${probePath}`;
+      const url = new URL(api.base + rel);
+      // Same confinement the agent gets: a probe can't reach another host.
+      if (!url.href.startsWith(api.base)) {
+        return done({
+          ok: false, transport: "http", missingSecrets: missing,
+          summary: "that path escapes the declared base URL",
+          detail: `base: ${api.base}\npath: ${probePath}`,
+        });
+      }
+      for (const [k, v] of Object.entries(api.query)) url.searchParams.set(k, substitute(v, env));
+
+      const headers: Record<string, string> = {};
+      for (const [k, v] of Object.entries(api.headers)) headers[k] = substitute(v, env);
+
+      const method = api.methods.includes("GET") ? "GET" : api.methods[0];
+      const res = await fetch(url, {
+        method,
+        headers,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      const body = await res.text();
+
+      // An unset secret means the tool cannot authenticate, so it is not
+      // working — whatever a permissive endpoint chose to return. Reporting
+      // ok on a request that went out with no credentials is how you ship a
+      // tool that 401s the first time it meets the real API.
+      return done({
+        ok: res.ok && missing.length === 0,
+        transport: "http",
+        missingSecrets: missing,
+        summary:
+          missing.length > 0
+            ? `${method} ${url.pathname} → ${res.status}, but sent without ${missing.join(", ")}`
+            : `${method} ${url.pathname} → ${res.status} ${res.statusText}`,
+        detail: clip(body),
+      });
+    } catch (err) {
+      return done({
+        ok: false, transport: "http", missingSecrets: missing,
+        summary: err instanceof Error ? err.message : String(err),
+        // A missing secret usually surfaces as a 401 rather than an error, so
+        // say it here too — it is the likeliest cause of both.
+        detail: missing.length ? `unset secrets: ${missing.join(", ")}` : "",
+      });
+    }
+  }
+
+  if (def.kind === "script") {
+    const run = String(def.spec.run ?? "");
+    // A run's working directory is the calling AGENT's folder, not the
+    // workspace root — and scripts rely on that. `path.resolve(cwd, "..",
+    // "..", "state", f)` is the ordinary way to reach workspace state, and
+    // testing one directory too high sent it to <data>/<tenant>/state: a
+    // real file read from the wrong place, reported as an empty result
+    // rather than an error. The tester now stands where a run stands.
+    //
+    // Which agent: one that granted this tool, so the test is the call that
+    // would actually happen; any agent otherwise, since only the DEPTH
+    // changes what a relative path resolves to.
+    const dir = workspaceDir(tenant, workspace);
+    const agents = listAgents(tenant, workspace);
+    const caller =
+      agents.find((a) => a.ownTools.includes(def.name)) ?? agents[0] ?? null;
+    // With no agents at all there is nothing at that depth to stand in; the
+    // workspace root is wrong but it exists, and the note says so rather
+    // than failing a test over a workspace that cannot run anything yet.
+    const cwd = caller ? path.join(dir, "agents", caller.name) : dir;
+    const file = resolveRunPath(path.join(dir, "agents", "_probe"), run, libraryDir(tenant, "scripts"));
+
+    if (!fs.existsSync(file)) {
+      return done({
+        ok: false, transport: "script", missingSecrets: [],
+        summary: `no such script: ${run}`,
+        detail: `looked for ${file}\n\nThis is the commonest way to get a tool that silently never loads.`,
+      });
+    }
+
+    const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+    const { env, missing } = resolveSecrets(tenant, names, workspace);
+    // The runtime's own choice of interpreter, not a second table beside it.
+    const interpreter =
+      typeof def.spec.interpreter === "string" ? def.spec.interpreter : undefined;
+
+    // Declared args become long flags, exactly as the runtime passes them.
+    const declared = def.spec.args && typeof def.spec.args === "object"
+      ? Object.keys(def.spec.args as Record<string, unknown>)
+      : [];
+    const flags: string[] = [];
+    for (const [k, v] of Object.entries(input.args ?? {})) {
+      if (v !== "" && /^[a-z][a-z0-9_]*$/i.test(k)) flags.push(`--${k}`, v);
+    }
+
+    // The tool's own dependencies, built (or reused) the way a run builds
+    // them. Without this a tool declaring `runtime: { packages: [requests] }`
+    // ran fine in a flow and failed the Test button with "no module named
+    // requests" — the one place a developer goes to find out if it works.
+    const toolRuntime = prepareRuntime(tenant, parseRuntime(def.spec.runtime));
+    if (toolRuntime.error) {
+      return done({
+        ok: false, transport: "script", missingSecrets: missing,
+        summary: "its runtime could not be built",
+        detail: [toolRuntime.error, ...toolRuntime.log].join("\n"),
+      });
+    }
+    const { cmd, args } = commandFor(
+      { interpreter, run: run, name: "", description: "", args: {} },
+      file,
+      toolRuntime.interpreters,
+    );
+    const { code, out } = await runOnce(cmd, [...args, ...flags], cwd, {
+      ...hostSafeBaseEnv(),
+      ...toolRuntime.env,
+      ...env,
+    });
+
+    // A script that needs arguments and got none has not failed — it has not
+    // been tested. Saying "exited 2" would send someone looking for a bug.
+    const untested = code !== 0 && declared.length > 0 && flags.length === 0;
+
+    return done({
+      ok: code === 0,
+      transport: "script",
+      missingSecrets: missing,
+      summary: untested
+        ? `needs ${declared.map((a) => `--${a}`).join(", ")} — fill them in and test again`
+        : code === 0 ? "exited 0" : `exited ${code ?? "with an error"}`,
+      detail: clip(
+        (caller
+          ? `ran from agents/${caller.name}/, where a run runs\n\n`
+          : `ran from the workspace root — there is no agent to stand in for, so a script that reaches ../../ will look one level too high\n\n`) +
+          (out || "(no output)"),
+      ),
+    });
+  }
+
+  // ---- mcp: start the server and complete a handshake ----
+  const spec = def.spec;
+  if (spec.url) {
+    // A remote server: the honest check we can make without a full client is
+    // that the endpoint answers.
+    try {
+      const res = await fetch(spec.url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+      return done({
+        ok: res.ok,
+        transport: "mcp",
+        missingSecrets: [],
+        summary: `${spec.url} → ${res.status} ${res.statusText}`,
+        detail: "Endpoint reachable. This does not verify the MCP handshake — only a local (command) server is started and spoken to.",
+      });
+    } catch (err) {
+      return done({
+        ok: false, transport: "mcp", missingSecrets: [],
+        summary: err instanceof Error ? err.message : String(err),
+        detail: "",
+      });
+    }
+  }
+
+  if (!spec.command) {
+    return done({
+      ok: false, transport: "mcp", missingSecrets: [],
+      summary: "no command: or url: — this tool cannot load",
+      detail: "",
+    });
+  }
+
+  const named = Object.entries(spec.env ?? {})
+    .map(([, v]) => String(v).match(/^\$\{([A-Z0-9_]+)\}$/)?.[1])
+    .filter((n): n is string => Boolean(n));
+  const { env, missing } = resolveSecrets(tenant, named, workspace);
+  const childEnv: NodeJS.ProcessEnv = { ...hostSafeBaseEnv() };
+  for (const [k, v] of Object.entries(spec.env ?? {})) childEnv[k] = substitute(String(v), env);
+
+  const handshake = await mcpHandshake(spec.command, spec.args ?? [], childEnv);
+  return done({
+    ok: handshake.ok,
+    transport: "mcp",
+    missingSecrets: missing,
+    summary: handshake.summary,
+    detail: clip(handshake.detail),
+  });
+}
+
+/** Run a command to completion, capturing both streams together. */
+function runOnce(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ code: number | null; out: string }> {
+  return new Promise((resolve) => {
+    let out = "";
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(cmd, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ code: null, out: err instanceof Error ? err.message : String(err) });
+      return;
+    }
+    const timer = setTimeout(() => child.kill("SIGKILL"), TIMEOUT_MS);
+    child.stdout?.on("data", (d) => (out += d));
+    child.stderr?.on("data", (d) => (out += d));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: null, out: `${out}${err.message}` });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, out });
+    });
+  });
+}
+
+/**
+ * Start a stdio MCP server and complete `initialize` + `tools/list`.
+ *
+ * This is the whole point of testing an MCP tool: "the binary exists" tells you
+ * nothing, and the failure people actually hit is a server that starts and then
+ * exposes nothing useful.
+ */
+function mcpHandshake(
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<{ ok: boolean; summary: string; detail: string }> {
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(command, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ ok: false, summary: `could not start ${command}`, detail: String(err), });
+      return;
+    }
+
+    let buf = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (r: { ok: boolean; summary: string; detail: string }) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill("SIGKILL");
+      resolve(r);
+    };
+
+    const timer = setTimeout(
+      () => finish({
+        ok: false,
+        summary: "the server did not answer in time",
+        detail: stderr || "No response to initialize within 15s.",
+      }),
+      TIMEOUT_MS,
+    );
+
+    const send = (msg: unknown) => child.stdin?.write(`${JSON.stringify(msg)}\n`);
+
+    child.on("error", (err) =>
+      finish({ ok: false, summary: `could not start ${command}`, detail: err.message }));
+    child.stderr?.on("data", (d) => (stderr += d));
+
+    child.stdout?.on("data", (d) => {
+      buf += d;
+      // One JSON-RPC message per line.
+      for (const line of buf.split("\n").slice(0, -1)) {
+        if (!line.trim()) continue;
+        let msg: { id?: number; result?: { tools?: { name: string }[] }; error?: { message?: string } };
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (msg.error) {
+          finish({ ok: false, summary: msg.error.message ?? "the server returned an error", detail: line });
+          return;
+        }
+        if (msg.id === 1) {
+          send({ jsonrpc: "2.0", method: "notifications/initialized" });
+          send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+        } else if (msg.id === 2) {
+          const tools = msg.result?.tools ?? [];
+          finish({
+            ok: true,
+            summary: `connected — ${tools.length} tool${tools.length === 1 ? "" : "s"}`,
+            detail: tools.map((t) => `• ${t.name}`).join("\n") || "The server exposes no tools.",
+          });
+          return;
+        }
+      }
+      buf = buf.slice(buf.lastIndexOf("\n") + 1);
+    });
+
+    send({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "foldrun-tool-test", version: "0.1.0" },
+      },
+    });
+  });
+}