premanmcp 1.1.7 → 1.1.9

package/bin/eval_entry.js

@@ -0,0 +1,762 @@
+/**
+ * Find the code that runs this repository's agent, and make it callable.
+ *
+ * An eval is about somebody's agent. Until now the CLI found that agent by
+ * sweeping localhost for an HTTP service, which could only ever match PreMan's
+ * own backend -- so in a customer's repository it measured the wrong process
+ * and reported the score as if it were theirs. The fix is not a better sweep.
+ * It is to read the repository and call the agent directly, which is both more
+ * accurate and impossible to confuse with a neighbouring service.
+ *
+ * The output is a small Python file, `.preman/preman_agent_entry.py`, wrapping
+ * whatever shape the real entry point has in the one signature assert-ai calls.
+ * A model writes it; a person approves it. That review is the only real control
+ * here, and the code says so where it matters -- everything else (refusing to
+ * write outside `.preman/`, compiling it, calling it once) is hygiene that
+ * catches mistakes, not a sandbox that contains a hostile file.
+ *
+ * Nothing in this module runs unattended. A daemon or a CI job that reaches
+ * discovery without an approved entry point is told to run `preman eval target`
+ * rather than having one written for it.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+
+import { callBackendJson, cliInvocation, resolveApiKey } from "./shared.js";
+import { REPO_CONFIG, findConfigRoot, findRepoRoot, saveEntry } from "./target.js";
+import { TargetError, verifyEntry } from "./eval_target.js";
+import { SHAPES, TemplateError, buildFreeform, buildWrapper } from "./eval_templates.js";
+
+/** The one importable name a device eval may use. The backend pins it too. */
+export const ENTRY_MODULE = "preman_agent_entry";
+export const ENTRY_SYMBOL = "chat";
+export const ENTRY_REF = `${ENTRY_MODULE}:${ENTRY_SYMBOL}`;
+
+/**
+ * `.preman`, not `.preman.py`, and the module is the bare name.
+ *
+ * A leading dot makes `importlib` read the name as a relative import, so the
+ * directory can never be a dotted module segment. Putting the directory on the
+ * import path instead and importing the bare name is what makes a hidden
+ * directory usable at all; the `preman_` prefix is what stops the bare name
+ * colliding with something already on the customer's path.
+ */
+export const ENTRY_DIR = ".preman";
+export const ENTRY_FILE = `${ENTRY_MODULE}.py`;
+
+/** The node half of a `node_bridge` target, beside the wrapper that spawns it. */
+export const BRIDGE_FILE = "agent_bridge.mjs";
+
+const SEARCH_TIMEOUT_MS = 120_000;
+const PROBE_TIMEOUT_MS = 60_000;
+const MAX_TREE_PATHS = 4_000;
+const MAX_TREE_BYTES = 120_000;
+const MAX_SHORTLIST = 12;
+const MAX_HEAD_LINES = 400;
+const MAX_HEAD_BYTES = 16_000;
+const MIN_CONFIDENCE = 0.6;
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".venv", "venv", ".git", "dist", "build", "__pycache__",
+  ".next", ".turbo", "target", ".mypy_cache", ".pytest_cache", ".preman",
+]);
+
+/** Filenames that tend to hold an agent's entry point. */
+const NAME_HINTS = /(agent|chat|graph|assistant|bot|server|main|app|workflow|crew)/i;
+
+/**
+ * Paths that cannot be an entry point however well they score.
+ *
+ * Measured, not guessed: against a large Rust repository the twelve shortlist
+ * slots filled with `app-server/tests/suite/v2/*.rs` and generated TypeScript
+ * schema definitions, because `NAME_HINTS` matches "app", "server" and "Agent"
+ * in a filename and says nothing about whether a file is code somebody calls. A
+ * test for an agent and a generated type describing one both look exactly like
+ * an agent to a filename.
+ */
+const NOT_ENTRY = [
+  /(^|\/)(tests?|__tests__|spec|e2e|fixtures?|examples?|benches|testdata)(\/|$)/i,
+  /(^|\/)[^/]*[._-](test|spec|bench)\.[^/]+$/i,
+  /(^|\/)(schema|schemas|generated|gen|proto|migrations)(\/)/i,
+  /\.d\.ts$/i,
+];
+
+/** Imports that say "this file is where an agent is built". */
+const FRAMEWORK_MARKERS = [
+  "StateGraph", "langgraph", "langchain", "AgentExecutor", "crewai", "autogen",
+  "llama_index", "litellm", "anthropic", "openai", "@ai-sdk", "mastra",
+  "pydantic_ai", "semantic_kernel", "smolagents",
+];
+
+// Python and JS/TS are imported or bridged; the rest are reachable only as a
+// `cli_subprocess`, and are listed so the model can see an agent written in them
+// at all. An extension here is not a promise that a shape exists for it -- the
+// shape table is the other half, and adding one without the other shows the
+// model code it has no way to invoke.
+const SOURCE_EXT = new Set([
+  ".py", ".ts", ".tsx", ".js", ".mjs", ".cjs",
+  ".rs", ".go", ".java", ".kt", ".rb", ".cs", ".ex", ".exs", ".php", ".swift",
+]);
+
+// Manifests that declare a runnable command. For a compiled agent the entry
+// point is not a source file at all -- it is a binary named in one of these,
+// which is a fact rather than an inference.
+const MANIFESTS = [
+  "Cargo.toml", "go.mod", "pom.xml", "build.gradle", "build.gradle.kts",
+  "Gemfile", "mix.exs", "composer.json", "Package.swift", "Makefile",
+];
+
+/**
+ * The credential this search runs on, or a refusal naming the fixes.
+ *
+ * Asked before the repository is walked. Without it the walk is wasted work
+ * ending in a 401 that names no remedy -- which is exactly what it did.
+ */
+function requireKey(args) {
+  const key = resolveApiKey(args);
+  if (key) return key;
+  throw new TargetError(
+    `no PreMan API key on this machine, so there is no account to read this ` +
+      `repository on behalf of. Run \`${cliInvocation()} login\`, or set ` +
+      `PREMAN_API_KEY. You can also point at a running agent with --target <url>.`
+  );
+}
+
+// ── Reading the repository ──────────────────────────────────────────────
+
+/**
+ * Every source path worth showing, cheapest way first.
+ *
+ * `git ls-files` is preferred because it already honours `.gitignore`, which is
+ * the repository's own statement about what is not its code. The walk is the
+ * fallback for a directory that is not a checkout, and it has to reproduce the
+ * exclusions by hand.
+ */
+export function repoTree(root) {
+  // `--others --exclude-standard` alongside `--cached`, because a plain
+  // `ls-files` lists only *tracked* files -- so a fresh checkout, a scratch
+  // repository, or simply an agent added since the last commit would read as
+  // "there is no code here". `--exclude-standard` keeps `.gitignore` honoured,
+  // which is the reason to prefer git over a hand-rolled walk at all.
+  const tracked = spawnSync(
+    "git",
+    ["-C", root, "ls-files", "--cached", "--others", "--exclude-standard"],
+    { encoding: "utf8" }
+  );
+  let paths;
+  if (tracked.status === 0) {
+    paths = tracked.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  } else {
+    paths = [];
+    const walk = (dir, depth) => {
+      if (depth > 8 || paths.length > MAX_TREE_PATHS) return;
+      let entries = [];
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".preman") continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRS.has(entry.name)) walk(full, depth + 1);
+        } else {
+          paths.push(path.relative(root, full).split(path.sep).join("/"));
+        }
+      }
+    };
+    walk(root, 0);
+  }
+
+  const kept = [];
+  let bytes = 0;
+  for (const rel of paths) {
+    if (rel.split("/").some((segment) => SKIP_DIRS.has(segment))) continue;
+    if (bytes + rel.length > MAX_TREE_BYTES || kept.length >= MAX_TREE_PATHS) break;
+    kept.push(rel);
+    bytes += rel.length + 1;
+  }
+  return kept;
+}
+
+/** The files most likely to hold the entry point, with their opening lines. */
+export function shortlist(root, tree) {
+  const scored = [];
+  for (const rel of tree) {
+    if (!SOURCE_EXT.has(path.extname(rel))) continue;
+    if (NOT_ENTRY.some((pattern) => pattern.test(rel))) continue;
+    const full = path.join(root, rel);
+    let head = "";
+    try {
+      if (statSync(full).size > 1_000_000) continue;
+      head = readFileSync(full, "utf8");
+    } catch {
+      continue;
+    }
+
+    let score = 0;
+    if (NAME_HINTS.test(path.basename(rel))) score += 3;
+    // A file at the top of the tree is likelier to be an entry point than one
+    // buried in a package, so shallower paths break ties upward.
+    score += Math.max(0, 3 - rel.split("/").length);
+    for (const marker of FRAMEWORK_MARKERS) if (head.includes(marker)) score += 2;
+    if (score <= 0) continue;
+
+    const lines = head.split("\n").slice(0, MAX_HEAD_LINES).join("\n");
+    scored.push({ path: rel, score, head: lines.slice(0, MAX_HEAD_BYTES) });
+  }
+  const best = scored.sort((a, b) => b.score - a.score).slice(0, MAX_SHORTLIST);
+
+  // Manifests are appended rather than scored: they are short, they are the
+  // only place a binary's name is stated outright, and a compiled agent has no
+  // source file that could win a score.
+  for (const rel of tree) {
+    if (!MANIFESTS.includes(path.basename(rel))) continue;
+    if (best.some((entry) => entry.path === rel)) continue;
+    try {
+      const head = readFileSync(path.join(root, rel), "utf8");
+      best.push({ path: rel, score: 1, head: head.slice(0, 4_000) });
+    } catch {
+      continue;
+    }
+    if (best.length >= MAX_SHORTLIST + 4) break;
+  }
+  return best;
+}
+
+// ── Asking ──────────────────────────────────────────────────────────────
+
+/**
+ * One bounded call, not a conversation.
+ *
+ * `/cli/agent-entry` exists rather than the workbench agent because this wants
+ * a parser, not a chatbot: the workbench agent carries the product's system
+ * prompt and its whole tool set, and asked for a JSON object about a pasted
+ * file tree it will argue with that prompt and sometimes call a tool. One
+ * request with a response schema and a cost ceiling is the same model from the
+ * customer's seat and a far more predictable answer.
+ */
+async function askForEntry(args, { root, tree, files, namedSymbol = "", log }) {
+  const key = requireKey(args);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
+  try {
+    log("Reading this repository to find the code that runs your agent…");
+    const found = await callBackendJson(args, "POST", "/cli/agent-entry", {
+      token: key,
+      json: {
+        project_name: path.basename(root),
+        tree,
+        files: files.map((f) => ({ path: f.path, head: f.head })),
+        entry_module: ENTRY_MODULE,
+        entry_symbol: ENTRY_SYMBOL,
+        named_symbol: namedSymbol,
+      },
+      signal: controller.signal,
+    });
+    if (!found.ok) {
+      // 404 is the one worth naming: it means the deployment predates this
+      // command, which is a version problem rather than a repository problem
+      // and has a different fix.
+      if (found.status_code === 404) {
+        throw new TargetError(
+          `This PreMan deployment cannot search a repository yet. Name the entry point ` +
+            `yourself with --entry <file>:<symbol>, or point at a running agent with --target <url>.`
+        );
+      }
+      throw new TargetError(
+        `PreMan could not read this repository (${found.status_code}): ` +
+          `${found.detail || found.raw || "no reason given"}`
+      );
+    }
+    return found;
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new TargetError(
+        `PreMan took longer than ${SEARCH_TIMEOUT_MS / 1000}s to read this repository. ` +
+          `Name the entry point yourself with --entry <file>:<symbol>.`
+      );
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Whether an answer is good enough to put in front of somebody.
+ *
+ * Refusing is the useful failure. A wrong entry point does not announce itself
+ * -- it produces a run where every case fails for a reason that reads like the
+ * agent misbehaving -- so a low-confidence guess costs more than no answer.
+ */
+export function rejectionFor(found, tree) {
+  if (!found || found.found === false) return "it could not find an agent entry point here";
+  // A shape is what makes the answer usable now, not a returned file: the
+  // caller builds the wrapper, and `other` is the only shape that still needs
+  // code from the model.
+  const shape = String(found.shape || "");
+  if (shape === "other" || !shape) {
+    const source = found.turn_source || found.shim_source;
+    if (!source || typeof source !== "string") {
+      return "it could not say how to call the agent";
+    }
+  }
+  // `cli_subprocess` names a command rather than a file, so a file check would
+  // refuse every compiled agent.
+  if (shape !== "cli_subprocess") {
+    if (!found.entry_file || !tree.includes(found.entry_file)) {
+      return `it named ${found.entry_file || "a file"}, which is not in this repository`;
+    }
+  } else if (!Array.isArray(found.command) || !found.command.length) {
+    return "it said the agent is a program to run but did not say how to run it";
+  }
+  if (typeof found.confidence === "number" && found.confidence < MIN_CONFIDENCE) {
+    return `it was only ${Math.round(found.confidence * 100)}% sure`;
+  }
+  const others = Array.isArray(found.alternatives) ? found.alternatives : [];
+  if (others.length && typeof found.confidence === "number" && found.confidence < 0.8) {
+    return "several files could be the entry point and none of them stood out";
+  }
+  return "";
+}
+
+// ── Checking, before a person is asked to read it ───────────────────────
+
+function entryPaths(projectPath) {
+  // An approved `.preman.json` wins, then the repository, then where we stand.
+  // The middle step is what makes `--entry src/agent.py` work from a
+  // subdirectory on a first run, when there is no config to find yet.
+  const root = findConfigRoot(projectPath) || findRepoRoot(projectPath) || projectPath;
+  const dir = path.join(root, ENTRY_DIR);
+  return { root, dir, file: path.join(dir, ENTRY_FILE) };
+}
+
+/**
+ * Compile it, import it, and make it answer once.
+ *
+ * These are the checks the server used to run before a callable target was
+ * allowed, moved to the machine that has the code. The server cannot do them
+ * for a file on somebody's laptop, and skipping them would mean discovering a
+ * broken wrapper eighteen turns into a paid run.
+ */
+export async function validateShim(file, { projectPath, log }) {
+  const { dir } = entryPaths(projectPath);
+  const resolved = path.resolve(file);
+  if (path.relative(dir, resolved).startsWith("..")) {
+    return { ok: false, why: `it would write outside ${ENTRY_DIR}/` };
+  }
+
+  const { resolveInterpreter } = await import("./eval.js");
+  let python;
+  try {
+    python = resolveInterpreter({ projectPath, log: () => {} });
+  } catch (error) {
+    return { ok: false, why: error.message };
+  }
+
+  const compiled = spawnSync(python.command, [...python.argv, "-m", "py_compile", resolved], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+  });
+  if (compiled.status !== 0) {
+    return { ok: false, why: `it does not compile: ${(compiled.stderr || "").trim().slice(-400)}` };
+  }
+
+  // Imported the way assert-ai imports it -- bare module name off the import
+  // root -- so a wrapper that only works when run as a script fails here
+  // rather than inside the harness.
+  const probe = [
+    "import inspect, json, sys",
+    `sys.path.insert(0, ${JSON.stringify(dir)})`,
+    `import ${ENTRY_MODULE} as m`,
+    `fn = getattr(m, ${JSON.stringify(ENTRY_SYMBOL)})`,
+    'if "history" not in inspect.signature(fn).parameters:',
+    '    print("PREMAN_PROBE:" + json.dumps({"ok": False, "why": "the wrapper takes no `history` argument, which assert-ai needs to pass a conversation"}));'
+      + ' sys.exit(0)',
+    'out = fn("Hello", history=[])',
+    'text = out.get("response") if isinstance(out, dict) else out',
+    'ok = isinstance(text, str) and bool(text.strip())',
+    'print("PREMAN_PROBE:" + json.dumps({"ok": ok, "reply": (text if isinstance(text, str) else repr(out))[:400],'
+      + ' "why": "" if ok else "it ran but returned no text"}))',
+  ].join("\n");
+
+  const ran = spawnSync(python.command, [...python.argv, "-c", probe], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+    cwd: projectPath,
+  });
+  if (ran.error?.code === "ETIMEDOUT") {
+    return { ok: false, why: "it did not answer within 60 seconds" };
+  }
+  const line = String(ran.stdout || "")
+    .split("\n")
+    .find((value) => value.startsWith("PREMAN_PROBE:"));
+  if (!line) {
+    return { ok: false, why: `it failed to run: ${(ran.stderr || "").trim().slice(-400)}` };
+  }
+  const verdict = JSON.parse(line.slice("PREMAN_PROBE:".length));
+  return verdict.ok ? { ok: true, reply: verdict.reply } : { ok: false, why: verdict.why };
+}
+
+// ── The review ──────────────────────────────────────────────────────────
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => {
+    rl.close();
+    resolve(String(answer || "").trim().toLowerCase());
+  }));
+}
+
+/**
+ * Case preserved, unlike `ask`.
+ *
+ * A yes/no answer can be lowercased; a command line cannot -- paths, flags and
+ * binary names are case-sensitive, and `ask` would quietly turn `MyTool -X`
+ * into something that does not exist.
+ */
+function askRaw(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => {
+    rl.close();
+    resolve(String(answer || "").trim());
+  }));
+}
+
+/**
+ * A typed command line, as argv.
+ *
+ * Quotes are honoured so a path with a space survives; nothing else about a
+ * shell is interpreted. Deliberately not handed to a shell at all -- the
+ * wrapper spawns argv directly, so `&&`, redirects and globs are not available
+ * and cannot be smuggled in either.
+ */
+export function splitCommand(text) {
+  const parts = [];
+  const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let match;
+  while ((match = pattern.exec(String(text || ""))) !== null) {
+    parts.push(match[1] ?? match[2] ?? match[3]);
+  }
+  return parts.filter((part) => part.length);
+}
+
+/**
+ * How the agent is run, for a target that is a program rather than a module.
+ *
+ * A manifest names the binary and never its calling convention: `Cargo.toml`
+ * says the binary is `codex`, and nothing in the repository says a turn is
+ * `codex exec --json -`. So this is asked rather than inferred, once, and then
+ * lives in the wrapper that `.preman.json` records -- which is what stops it
+ * being asked again.
+ *
+ * The model's own suggestion is kept when it made one. It is shown in the
+ * wrapper at review time and exercised by the probe, so a wrong guess is
+ * caught before anything is approved rather than trusted here.
+ */
+async function ensureCommand(found, { args, log }) {
+  if (String(found.shape || "") !== "cli_subprocess") return found;
+
+  const named = splitCommand(args.value("--command", ""));
+  if (named.length) return { ...found, command: named };
+  if (Array.isArray(found.command) && found.command.length) return found;
+
+  const headless =
+    !process.stdout.isTTY || args.has("--headless") || args.has("--no-wait");
+  if (headless) {
+    throw new TargetError(
+      `${found.entry_file || "This repository"} looks like an agent that is run as a ` +
+        `program rather than imported, and PreMan could not tell how to run it. ` +
+        `Re-run with --command "<how one turn is run>", for example ` +
+        `--command "mytool exec --json -".`
+    );
+  }
+
+  log("");
+  log(`This agent is a program rather than a module${found.framework ? ` (${found.framework})` : ""}.`);
+  log("PreMan needs the command that runs ONE turn, reading the prompt on stdin.");
+  log('  for example:  codex exec --json -');
+  const typed = await askRaw("  command: ");
+  const command = splitCommand(typed);
+  if (!command.length) {
+    throw new TargetError(
+      `No command given, so nothing was written. Re-run and name it, or use ` +
+        `--command "<how one turn is run>".`
+    );
+  }
+  return { ...found, command };
+}
+
+async function review(found, source, reply, { log }) {
+  const numbered = source
+    .split("\n")
+    .map((line, index) => `  ${String(index + 1).padStart(3)} │ ${line}`)
+    .join("\n");
+
+  log("");
+  log(`PreMan thinks your agent is ${found.entry_file}${found.entry_symbol ? `:${found.entry_symbol}` : ""}` +
+    `${found.framework ? ` (${found.framework})` : ""}.`);
+  if (found.reasoning) log(`  ${found.reasoning}`);
+  log("");
+  log(`It wrote this wrapper, which is what the eval will call:`);
+  log("");
+  log(numbered);
+  log("");
+  log(`Asked "Hello", it answered: ${JSON.stringify(reply)}`);
+  log("");
+
+  const answer = await ask("Use this? [y]es / [n]o / [e]dit it first: ");
+  return answer.startsWith("y") ? "yes" : answer.startsWith("e") ? "edit" : "no";
+}
+
+// ── Writing it down ─────────────────────────────────────────────────────
+
+function writeShim(projectPath, source) {
+  const { root, dir, file } = entryPaths(projectPath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, source.endsWith("\n") ? source : `${source}\n`, "utf8");
+  ignoreEntryDir(root);
+  return { root, dir, file };
+}
+
+/**
+ * Keep the wrapper out of version control.
+ *
+ * It names absolute-ish local facts (which interpreter, which framework build)
+ * and it is regenerated per machine, so committing it would put one developer's
+ * environment in everybody's checkout. `.preman.json` is the part that travels.
+ */
+function ignoreEntryDir(root) {
+  const file = path.join(root, ".gitignore");
+  const line = `${ENTRY_DIR}/`;
+  let body = "";
+  try {
+    body = readFileSync(file, "utf8");
+  } catch {
+    body = "";
+  }
+  if (body.split("\n").some((value) => value.trim() === line)) return false;
+  writeFileSync(file, `${body}${body && !body.endsWith("\n") ? "\n" : ""}${line}\n`, "utf8");
+  return true;
+}
+
+function record(found, file, root, source, { language, alsoWrote = [] }) {
+  const sha256 = createHash("sha256").update(source).digest("hex");
+  // Hashed from disk rather than from what was generated: the point of the
+  // record is to notice a later edit, and a person offered `[e]dit it first`
+  // may have changed either file between generation and approval.
+  const files = [];
+  for (const extra of alsoWrote) {
+    if (!existsSync(extra)) continue;
+    files.push({
+      path: path.relative(root, extra).split(path.sep).join("/"),
+      sha256: createHash("sha256").update(readFileSync(extra, "utf8")).digest("hex"),
+    });
+  }
+  const entry = {
+    file: path.relative(root, file).split(path.sep).join("/"),
+    ref: ENTRY_REF,
+    sysPath: ENTRY_DIR,
+    sha256,
+    files,
+    // How the wrapper was built. Recorded because it is the one fact that
+    // explains the file's contents later: "this came from the langgraph
+    // template" is a different thing to debug than "a model wrote this".
+    shape: String(found.shape || "other"),
+    language,
+    framework: String(found.framework || ""),
+    entryFile: String(found.entry_file || ""),
+    approvedAt: new Date().toISOString(),
+  };
+  saveEntry(entry, root);
+  return entry;
+}
+
+// ── The two ways in ─────────────────────────────────────────────────────
+
+/**
+ * Search, review, write, remember.
+ *
+ * Returns a discovery target so a caller can go straight on to the run. The
+ * order matters: nothing is written until the wrapper has compiled and answered,
+ * and nothing is recorded until a person has said yes.
+ */
+export async function searchForEntry({ projectPath, args, log = () => {} }) {
+  requireKey(args);
+  const { root } = entryPaths(projectPath);
+  const tree = repoTree(root);
+  if (!tree.length) {
+    throw new TargetError(`There are no source files under ${root} to read.`);
+  }
+  const files = shortlist(root, tree);
+
+  let found = await askForEntry(args, { root, tree, files, log });
+  found = await ensureCommand(found, { args, log });
+  const rejection = rejectionFor(found, tree);
+  if (rejection) {
+    throw new TargetError(
+      `PreMan read this repository and ${rejection}, so nothing was written. ` +
+        `The files it considered were: ${files.slice(0, 5).map((f) => f.path).join(", ")}. ` +
+        `Name the entry point yourself with --entry <file>:<symbol>, or point at a running ` +
+        `agent with --target <url>.` +
+        (found?.reasoning ? `\n\nIt said: ${found.reasoning}` : "")
+    );
+  }
+
+  return installShim(found, wrapperFor(found, tree), { projectPath, args, log });
+}
+
+/**
+ * `--entry src/agent.py:graph`: skip the search, keep the review.
+ *
+ * The caller has answered the expensive question -- which file -- but the
+ * wrapper still has to be written and it still has to be right, so it goes
+ * through the same generation and the same gate. What is saved is the model
+ * reading the whole tree to find something already known.
+ */
+export async function entryFromNamedSymbol(named, { projectPath, args, log = () => {} }) {
+  // No key check here. A malformed `--entry`, or one naming a file that is not
+  // there, is wrong whoever you are -- reporting it as an auth problem would
+  // send somebody looking for the wrong fix. `askForEntry` asks for the
+  // credential at the point it actually needs one.
+  // `--entry src/agent.py` and `--entry src/agent.py:graph` are both accepted.
+  // The symbol is a preference passed to the search, not a requirement, so
+  // demanding it asked for a fact that was then discarded. A colon only starts
+  // a symbol when what follows is an identifier -- otherwise `C:/repo/agent.py`
+  // parses as the file `C` with the symbol `/repo/agent.py`.
+  const at = named.lastIndexOf(":");
+  const tail = at > 0 ? named.slice(at + 1) : "";
+  const hasSymbol = /^[A-Za-z_][A-Za-z0-9_]*$/.test(tail);
+  const file = hasSymbol ? named.slice(0, at) : named;
+  const symbol = hasSymbol ? tail : "";
+  if (!file) {
+    throw new TargetError(
+      `--entry wants <file> or <file>:<symbol>, for example --entry src/agent.py:graph`
+    );
+  }
+  const { root } = entryPaths(projectPath);
+  // An absolute path is a perfectly natural thing to paste, and `path.join`
+  // silently mangles one into `<root>/mnt/c/...` -- which then reports as "does
+  // not exist" and sends somebody looking for a missing file rather than a
+  // mishandled argument.
+  const full = path.isAbsolute(file) ? file : path.join(root, file);
+  if (!existsSync(full)) {
+    throw new TargetError(`--entry names ${file}, which does not exist under ${root}.`);
+  }
+  // The model is shown, and later asked about, the repository-relative form:
+  // `rejectionFor` checks the answer's `entry_file` against the tree it was
+  // given, and that tree is always relative.
+  const rel = path.relative(root, full).split(path.sep).join("/");
+  if (rel.startsWith("..")) {
+    throw new TargetError(
+      `--entry names ${file}, which is outside ${root}. An eval measures the ` +
+        `agent in this repository, so the entry point has to be in it.`
+    );
+  }
+
+  const head = readFileSync(full, "utf8").split("\n").slice(0, MAX_HEAD_LINES).join("\n");
+  let found = await askForEntry(args, {
+    root,
+    tree: [rel],
+    files: [{ path: rel, head: head.slice(0, MAX_HEAD_BYTES) }],
+    namedSymbol: symbol,
+    log,
+  });
+  found = await ensureCommand(found, { args, log });
+  const rejection = rejectionFor(found, [rel]);
+  if (rejection) {
+    throw new TargetError(
+      `PreMan could not write a wrapper for ${symbol ? `${file}:${symbol}` : file} -- ${rejection}.` +
+        (found?.reasoning ? `\n\nIt said: ${found.reasoning}` : "")
+    );
+  }
+  return installShim(found, wrapperFor(found, [rel]), { projectPath, args, log });
+}
+
+/**
+ * The wrapper for this answer: from the template, or from the model for `other`.
+ *
+ * The template path writes no model-authored code at all, which is what makes
+ * the output byte-identical between runs on the same repository. The `other`
+ * path is the escape hatch, and it is the only one where a returned string
+ * becomes executable -- so it stays behind the same review gate it always was.
+ */
+function wrapperFor(found, tree) {
+  const shape = String(found.shape || "");
+  if (SHAPES.has(shape)) {
+    try {
+      return buildWrapper(found, { tree });
+    } catch (error) {
+      if (error instanceof TemplateError) {
+        throw new TargetError(`PreMan could not build a wrapper: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+  // An answer from a deployment that predates shapes still carries a whole
+  // file. Honoured rather than refused: a CLI newer than its backend is the
+  // normal direction of skew, and refusing would make an upgrade break a
+  // working install.
+  if (found.shim_source) {
+    return { shim: String(found.shim_source), bridge: String(found.bridge_source || "") };
+  }
+  const body = String(found.turn_source || "")
+    .split("\n")
+    .map((line) => (line.trim() ? `    ${line.replace(/^\s{0,4}/, "")}` : line))
+    .join("\n");
+  try {
+    return buildFreeform(found, { tree, turnSource: body });
+  } catch (error) {
+    if (error instanceof TemplateError) {
+      throw new TargetError(`PreMan could not build a wrapper: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+async function installShim(found, built, { projectPath, args, log }) {
+  const { root, dir, file } = writeShim(projectPath, built.shim);
+  const alsoWrote = [];
+  if (built.bridge) {
+    // Beside the wrapper, inside `.preman/`, so the same digest check and the
+    // same gitignore cover both halves of a two-file target.
+    const bridge = path.join(dir, BRIDGE_FILE);
+    writeFileSync(bridge, built.bridge, "utf8");
+    alsoWrote.push(bridge);
+  }
+  const checked = await validateShim(file, { projectPath, log });
+  if (!checked.ok) {
+    throw new TargetError(
+      `PreMan wrote ${path.relative(root, file)} but ${checked.why}. It has been left in ` +
+        `place so you can read it. Fix it and re-run, or name a different entry point with ` +
+        `--entry <file>:<symbol>.`
+    );
+  }
+
+  const verdict = await review(found, readFileSync(file, "utf8"), checked.reply, { log });
+  if (verdict === "edit") {
+    throw new TargetError(
+      `Left ${path.relative(root, file)} in place for you to edit. Re-run when it is ready ` +
+        `and it will be checked again.`
+    );
+  }
+  if (verdict !== "yes") {
+    throw new TargetError(
+      `Not used. ${path.relative(root, file)} is still there if you want to look at it; ` +
+        `delete it, or name a different entry point with --entry <file>:<symbol>.`
+    );
+  }
+
+  const finalSource = readFileSync(file, "utf8");
+  const language = String(found.language || "python").toLowerCase() === "node" ? "node" : "python";
+  const entry = record(found, file, root, finalSource, { language, alsoWrote });
+  log(`Approved. ${REPO_CONFIG} remembers it, so this will not be asked again.`);
+
+  return verifyEntry({ ...entry, root });
+}