@foldrun/core 0.5.0 → 0.7.0

package/src/browser-pod.ts

@@ -48,8 +48,9 @@ export const BROWSE_WRITE_ACTIONS = [
 ] as const;
 
 /** Call arguments of web action=browse that are writes whatever the actions:
- *  page script, a paid captcha solver, a confirmation of a credential step. */
-const BROWSE_WRITE_ARGS = ["js", "captcha", "captcha_solver", "confirm"];
+ *  page script (js=, or init= scripts run in every page), a paid captcha
+ *  solver, a confirmation of a credential step. */
+const BROWSE_WRITE_ARGS = ["js", "init", "captcha", "captcha_solver", "confirm"];
 
 /** Web actions that only read — when foldrun's own answers them. A paid
  *  provider answering one (FOLDRUN_WEB_<ACTION>_VIA) makes it a write: doing
@@ -72,24 +73,59 @@ export interface ClassifyContext {
   /** Web actions a paid provider answers this step — from the env's
    *  FOLDRUN_WEB_<ACTION>_VIA. */
   paidWeb?: Record<string, string>;
+  /** Page scripts the agent's web.browse block runs in every page — the
+   *  env's FOLDRUN_BROWSER_INIT. They make every browse call a write. */
+  browseInit?: string;
 }
 
-/** The browse actions a call asked for, nested `if` branches included. */
+/**
+ * The browse actions a call asked for, nested `if` branches included.
+ *
+ * Read the way the web tool reads them (platform gallery.ts, browse.mjs
+ * checkSteps): `actions` is an array of steps, a step's action is one of its
+ * OWN keys (the first the tool knows), and the only steps inside a step are
+ * an `if`'s `then` and `else`. Every own key of a step is returned — the
+ * caller keeps the ones it cares about, and a step holding a write key beside
+ * a read key counts as the write. What sits inside an option's value — an
+ * extract's `fields` (column names), a mock's `json` body, a webmcp `input` —
+ * is data, not an action: `{"fields": {"type": "td.kind"}}` is no typing.
+ *
+ * A shape the tool would refuse (an object where the array belongs, a step
+ * that is not an object, `then` that is not a list) is walked key by key at
+ * every depth, as before; nesting past MAX_DEPTH is unreadable, so a write
+ * buried deep is never taken for a read.
+ */
 export function browseActionNames(actions: unknown): string[] {
+  const UNREADABLE = "(unreadable actions)";
+  const MAX_DEPTH = 32;
   let steps: unknown = actions;
   if (typeof steps === "string") {
-    try { steps = JSON.parse(steps); } catch { return ["(unreadable actions)"]; }
+    try { steps = JSON.parse(steps); } catch { return [UNREADABLE]; }
   }
   const out: string[] = [];
-  const walk = (v: unknown, depth: number) => {
-    if (depth > 8 || v === null || typeof v !== "object") return;
-    if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+  // Unknown shapes: every key anywhere is a candidate action.
+  const walkAny = (v: unknown, depth: number) => {
+    if (v === null || typeof v !== "object") return;
+    if (depth > MAX_DEPTH) { out.push(UNREADABLE); return; }
+    if (Array.isArray(v)) { for (const x of v) walkAny(x, depth + 1); return; }
     for (const [k, x] of Object.entries(v as Record<string, unknown>)) {
       out.push(k);
-      walk(x, depth + 1);
+      walkAny(x, depth + 1);
+    }
+  };
+  const walkSteps = (v: unknown, depth: number) => {
+    if (v === null || v === undefined) return;
+    if (depth > MAX_DEPTH) { out.push(UNREADABLE); return; }
+    if (!Array.isArray(v)) { walkAny(v, depth); return; }
+    for (const step of v) {
+      if (step === null || typeof step !== "object" || Array.isArray(step)) { walkAny(step, depth + 1); continue; }
+      for (const [k, x] of Object.entries(step as Record<string, unknown>)) {
+        out.push(k);
+        if (k === "then" || k === "else") walkSteps(x, depth + 1);
+      }
     }
   };
-  walk(steps, 0);
+  walkSteps(steps, 0);
   return out;
 }
 
@@ -132,6 +168,7 @@ export function classifyCall(tool: string, input: Record<string, unknown> | unde
     if (action === "browse") {
       const w = browseWrites(args);
       if (w) return write(w);
+      if (ctx.browseInit) return write(`browse init scripts (${ctx.browseInit})`);
     }
     return { write: false };
   }

package/src/completions.ts

@@ -76,6 +76,7 @@ const TOOL_GROUPS: Completion[] = [
   { label: "code", hint: "Bash — runs anything in the sandbox" },
   { label: "web", hint: "search, fetch, browse, crawl, map, extract, answer, monitor — providers under web:" },
   { label: "ask", hint: "ask_person — ask the person running the desk mid-step, and wait for the answer" },
+  { label: "install", hint: "install apt, pip or npm packages mid-step — every agent has it; disallowedTools: [install] removes it" },
 ];
 
 const SDK_TOOL_NAMES: Completion[] = [

package/src/confine.ts

@@ -193,7 +193,7 @@ export function isWithin(root: string, abs: string): boolean {
 }
 
 /** Expand a virtual prefix to a real absolute path, or null if it has none. */
-export function expandVirtual(raw: string, roots: Roots): { abs: string; readOnly: boolean } | null {
+export function expandVirtual(raw: string, roots: Roots): { abs: string; readOnly: boolean; prefix: string } | null {
   // The SDK resolves a relative path against the cwd BEFORE canUseTool sees
   // it, so `workspace/storage/x.json` arrives as
   // `<agentDir>/workspace/storage/x.json` and never matched a prefix. The
@@ -205,12 +205,23 @@ export function expandVirtual(raw: string, roots: Roots): { abs: string; readOnl
   const candidate = rel !== null && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : raw;
   for (const v of VIRTUAL) {
     if (candidate.startsWith(v.prefix)) {
-      return { abs: path.resolve(v.root(roots), candidate.slice(v.prefix.length)), readOnly: v.readOnly };
+      return { abs: path.resolve(v.root(roots), candidate.slice(v.prefix.length)), readOnly: v.readOnly, prefix: v.prefix };
     }
   }
   return null;
 }
 
+/** Whether `<agentDir>/workspace` is the step's link to the workspace root
+ *  (linkWorkspace), so a `workspace/…` path opens the right file as written. */
+function linkedWorkspace(roots: Roots): boolean {
+  const link = path.join(roots.agentDir, "workspace");
+  try {
+    return fs.lstatSync(link).isSymbolicLink() && real(link) === real(path.resolve(roots.workspaceRoot));
+  } catch {
+    return false;
+  }
+}
+
 export function checkPaths(
   toolName: string,
   input: Record<string, unknown>,
@@ -312,8 +323,16 @@ export function checkPaths(
     }
 
     // Hand the real path back to the tool, so the virtual prefix the prompt
-    // advertises is one the agent can actually open.
-    if (virtual) rewritten = { ...(rewritten ?? input), [key]: abs };
+    // advertises is one the agent can actually open — unless the step's
+    // `workspace` link already opens it. Then the path is left as written,
+    // because the SDK remembers what was Read under the path the tool ran
+    // with but checks an Edit against the one the model wrote, before this
+    // hook sees it: Read workspace/x (rewritten) then Edit workspace/x was
+    // refused "File has not been read yet" on every try, and blog-desk's
+    // fact-checker spent a pass on it (run-muuhguk3-vhrg, 2026-10-05).
+    if (virtual && !(virtual.prefix === "workspace/" && linkedWorkspace(roots))) {
+      rewritten = { ...(rewritten ?? input), [key]: abs };
+    }
   }
 
   // Glob searches from `path` (the cwd when absent) and its PATTERN never
@@ -407,6 +426,17 @@ const PROTECTED_BASH: { re: RegExp; writeOnly: boolean; reason: string }[] = [
   },
 ];
 
+/**
+ * A web address, which names a place on a server rather than in the workspace.
+ *
+ * The protected-path patterns match a bare `runs/`, so an agent calling the
+ * platform's own API — `curl https://…/api/workspaces/x/runs/<id>` — was told
+ * it was reading the run journal. The weekly retros read their week through
+ * that API and were refused on 9 Oct 2026. Only http(s): a `file://` URL is a
+ * path, and stays checked.
+ */
+const WEB_URL = /\bhttps?:\/\/[^\s'"`)]+/gi;
+
 export function checkBash(command: string): ConfineVerdict {
   for (const re of BASH_ESCAPES) {
     if (re.test(command)) {
@@ -424,9 +454,10 @@ export function checkBash(command: string): ConfineVerdict {
   for (const segment of command.split(/[;|&]+|\n/)) {
     if (!segment.trim()) continue;
     const writes = WRITES_TO_A_FILE.test(segment);
+    const paths = segment.replace(WEB_URL, " ");
     for (const rule of PROTECTED_BASH) {
       if (rule.writeOnly && !writes) continue;
-      if (rule.re.test(segment)) return { ok: false, reason: `Bash was denied: ${rule.reason}` };
+      if (rule.re.test(paths)) return { ok: false, reason: `Bash was denied: ${rule.reason}` };
     }
   }
   return { ok: true };

package/src/container.ts

@@ -10,6 +10,7 @@
 // development keeps working with zero configuration.
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { dataRoot } from "./paths.ts";
 import { spawnSync, spawn } from "node:child_process";
@@ -131,6 +132,10 @@ export interface ContainerRunOptions {
   agentDir: string;
   /** Extra read-only mounts: host path → container path. */
   readOnly?: Record<string, string>;
+  /** Workspace paths a script was handed as `workspace/…`: copied in at
+   *  `container` before it runs, and what it created or changed under them
+   *  copied back to `host` after — the host's workspace link, as a copy. */
+  staged?: { host: string; container: string }[];
   image: string;
   argv: string[]; // command inside the container
   env: Record<string, string>;
@@ -181,15 +186,36 @@ export async function runInContainer(
   const cid = (created.stdout ?? "").trim();
 
   try {
-    // The agent's own directory becomes /workspace…
-    const copied = docker(["cp", `${opts.agentDir}/.`, `${cid}:/workspace`], 120_000);
-    if (copied.status !== 0) {
-      return { code: null, out: `copy in failed: ${(copied.stderr ?? "").slice(-300)}` };
-    }
+    // The agent's own directory becomes /workspace… — its entries staged
+    // like the workspace paths below (a scratch copy, opened up for the
+    // script's user, one tar), minus the step's `workspace` link. A step
+    // holds that link (→ ../..) so the shell can say workspace/…, and
+    // `docker cp` refuses a link that climbs out of what it copies
+    // ("invalid symlink"), so every Docker-run script failed before it
+    // started. And `docker cp` lands files as root while scripts run as
+    // `agent`, so a script could never write its own outputs/.
+    const own = fs
+      .readdirSync(opts.agentDir)
+      .filter((name) => {
+        if (name !== "workspace") return true;
+        try {
+          return !fs.lstatSync(path.join(opts.agentDir, name)).isSymbolicLink();
+        } catch {
+          return false;
+        }
+      })
+      .map((name) => ({ host: path.join(opts.agentDir, name), container: `/workspace/${name}` }));
+    const copiedIn = stageIn(CLI, cid, own, ["/workspace"]);
+    if (copiedIn) return { code: null, out: `copy in failed: ${copiedIn}` };
     // …and any shared directories land at their declared paths.
     for (const [host, mount] of Object.entries(opts.readOnly ?? {})) {
       if (fs.existsSync(host)) docker(["cp", `${host}/.`, `${cid}:${mount}`], 120_000);
     }
+    const staged = opts.staged ?? [];
+    if (staged.length) {
+      const failed = stageIn(CLI, cid, staged);
+      if (failed) return { code: null, out: `copy in failed: ${failed}` };
+    }
 
     const result = await new Promise<{ code: number | null; out: string }>((resolve) => {
       const child = spawn(CLI, ["start", "-a", cid], { timeout: opts.timeoutMs });
@@ -213,8 +239,89 @@ export async function runInContainer(
 
     // Bring deliverables back so outputs/ behaves the same either way.
     docker(["cp", `${cid}:/workspace/outputs/.`, path.join(opts.agentDir, "outputs")], 120_000);
+    for (const s of staged) stageBack(CLI, cid, s);
     return result;
   } finally {
     docker(["rm", "-f", cid], 30_000);
   }
 }
+
+/**
+ * Copy the staged workspace paths into a created container: one tar, built
+ * in a scratch directory that mirrors the container paths, extracted at /.
+ * A path that does not exist yet (an output the script is told to write)
+ * gets its parent directory, so the write has somewhere to land.
+ */
+function stageIn(cli: string, cid: string, staged: { host: string; container: string }[], dirs: string[] = []): string | null {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+  try {
+    for (const d of dirs) fs.mkdirSync(path.join(scratch, d), { recursive: true });
+    for (const { host, container } of staged) {
+      const dest = path.join(scratch, container);
+      if (fs.existsSync(host)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.cpSync(host, dest, { recursive: true, dereference: false });
+      } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+      }
+    }
+    // `docker cp` lands files as root and scripts run as `agent`: these are
+    // scratch copies, so open them up for the script to write into.
+    openUp(scratch);
+    const top = fs.readdirSync(scratch);
+    const r = spawnSync(
+      "sh",
+      ["-c", 'dir="$1"; cli="$2"; dest="$3"; shift 3; tar --no-xattrs -C "$dir" -cf - -- "$@" | "$cli" cp - "$dest"', "sh", scratch, cli, `${cid}:/`, ...top],
+      { encoding: "utf8", timeout: 120_000, env: { ...process.env, COPYFILE_DISABLE: "1" } },
+    );
+    return r.status === 0 ? null : (r.stderr ?? "").slice(-300);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Copy back what the script created or changed under one staged path. Files
+ * whose bytes did not change are left alone, so an input keeps its mtime —
+ * freshness checks read it.
+ */
+function stageBack(cli: string, cid: string, s: { host: string; container: string }): void {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+  try {
+    const out = path.join(scratch, "x");
+    const got = spawnSync(cli, ["cp", `${cid}:${s.container}`, out], { encoding: "utf8", timeout: 120_000 });
+    if (got.status !== 0 || !fs.existsSync(out)) return;
+    syncChanged(out, s.host);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/** Write `from` over `to` where the bytes differ; recurse into folders. */
+export function syncChanged(from: string, to: string): void {
+  const st = fs.lstatSync(from);
+  if (st.isSymbolicLink()) return;
+  if (st.isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const name of fs.readdirSync(from)) syncChanged(path.join(from, name), path.join(to, name));
+    return;
+  }
+  const next = fs.readFileSync(from);
+  if (fs.existsSync(to) && fs.statSync(to).isFile() && fs.readFileSync(to).equals(next)) return;
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.writeFileSync(to, next);
+}
+
+/** Directories 0777, files writable by all (exec bits kept): a scratch tree only. */
+function openUp(dir: string): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      fs.chmodSync(p, 0o777);
+      openUp(p);
+    } else {
+      fs.chmodSync(p, fs.statSync(p).mode | 0o666);
+    }
+  }
+}

package/src/context-tools.ts

@@ -32,7 +32,7 @@ import type { RunRecord } from "./store.ts";
 // ------------------------------------------------------------------ search
 
 export interface SearchRoot {
-  /** How the agent should name the place: "knowledge/", "../../memory/". */
+  /** How the agent should name the place: "knowledge/", "workspace/memory/". */
   label: string;
   /** The directory, absolute. */
   dir: string;

package/src/deploy.ts

@@ -208,6 +208,25 @@ export function readTree(dir: string): DeployFile[] {
  *  only the deployed files, so a library or gallery outward tool is not seen
  *  here — `foldrun check`, which resolves every scope, remains the real gate.
  *  Non-blocking by decision: the deploy proceeds and says so. */
+/**
+ * A frontmatter block that lost its opening `---`: `key: value` lines, then a
+ * lone `---`, with nothing above them. Nothing is read from it — the parser
+ * sees prose — so the agent runs with no tools and the default model, and a
+ * model told to call a tool it was never given writes the call out as text.
+ * seo-digest's editor did that every Sunday from 20 Sep to 5 Oct 2026.
+ * Returns the problem, or null.
+ */
+export function unopenedFrontmatter(raw: string): string | null {
+  const text = raw.replace(/^\uFEFF/, "");
+  if (/^---\r?\n/.test(text)) return null;
+  const lines = text.split(/\r?\n/);
+  const close = lines.findIndex((l) => l.trim() === "---");
+  if (close < 1) return null;
+  const above = lines.slice(0, close).filter((l) => l.trim() && !l.trim().startsWith("#"));
+  if (!above.length || !above.every((l) => /^[A-Za-z_][\w-]*:(\s|$)/.test(l) || /^\s+\S/.test(l))) return null;
+  return "the frontmatter has no opening `---`, so none of it is read: the agent runs with no tools and the default model. Add `---` as the first line.";
+}
+
 export function deployWarnings(files: DeployFile[]): DeployIssue[] {
   const front = (content: string): Record<string, unknown> => {
     try { return matter(content).data as Record<string, unknown>; } catch { return {}; }
@@ -227,6 +246,9 @@ export function deployWarnings(files: DeployFile[]): DeployIssue[] {
   const outwardAgents: string[] = [];
   const agentNames: string[] = [];
   const out: DeployIssue[] = [];
+  if (!files.some((f) => /^agents\/[^/]+\/agent\.md$/.test(f.path)) && !files.some((f) => /^\.(claude|agents)\/agents\/[^/]+\.md$/.test(f.path))) {
+    out.push({ where: "agents/", message: "no agents yet — add one (agents/<name>/agent.md), or import one from another workspace" });
+  }
   // The web: warnings check prints — the old session: key, and a pinned
   // user agent behind the runner image's Chrome, which the platform knows
   // from FOLDRUN_RUNNER_ENGINES (the deploy read it from the image).
@@ -284,6 +306,8 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
   // written, not discovered as a date that is a day out.
   for (const f of files) {
     if (!/^(AGENTS\.md|agents\/[^/]+\/agent\.md)$/.test(f.path)) continue;
+    const unopened = unopenedFrontmatter(f.content);
+    if (unopened) at(f.path, unopened);
     let front: Record<string, unknown> = {};
     try {
       front = matter(f.content).data as Record<string, unknown>;
@@ -306,9 +330,10 @@ export function deployIssues(files: DeployFile[]): DeployIssue[] {
     if (lang) at(f.path, lang);
     for (const w of localeProblems(front)) at(f.path, w);
   }
-  if (agents.size === 0) {
-    at("agents/", "no agents — a workspace needs at least one agents/<name>/agent.md");
-  }
+  // No agents is a workspace that has not started yet — "Create workspace"
+  // makes exactly that — and deploying it is harmless: a flow that names an
+  // agent this push lacks is refused below, step by step. deployWarnings says
+  // it, so the empty state is visible without blocking the first push.
 
   // Flows, parsed from the incoming text rather than from disk. A step naming
   // an agent that this push does not ship is the single most common way a

package/src/evals.ts

@@ -31,6 +31,8 @@
 // they pass — no point paying a model to grade output already known to be
 // wrong.
 
+import { accountModelEnv } from "./model-env.ts";
+import { sdkEnv } from "./step-exec.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { deployedCommit } from "./deploy.ts";
@@ -476,6 +478,7 @@ async function judge(
   output: string,
   model: string,
   effort: Effort | null,
+  env: Record<string, string | undefined>,
 ): Promise<AssertionResult["detail"] & string> {
   const prompt =
     `You are grading one piece of output against one criterion. Answer with exactly ` +
@@ -491,6 +494,8 @@ async function judge(
       tools: [],
       allowedTools: [],
       settingSources: [],
+      strictMcpConfig: true,
+      env,
       maxTurns: 1,
     },
   });
@@ -510,6 +515,7 @@ async function checkAssertion(
   agentDir: string,
   model: string,
   effort: Effort | null,
+  judgeEnv: () => Record<string, string | undefined> = () => sdkEnv(undefined),
 ): Promise<AssertionResult> {
   const hay = output.toLowerCase();
   switch (assertion.type) {
@@ -542,7 +548,15 @@ async function checkAssertion(
       return { assertion, passed: code === 0, detail: `exit ${code ?? "error"}${out ? ` — ${out.slice(0, 200)}` : ""}` };
     }
     case "judge": {
-      const verdict = await judge(assertion.value, output, model, effort);
+      // The judge runs on the account's own model key, never quietly on the
+      // platform's: a customer's eval is not the operator's bill.
+      let env: Record<string, string | undefined>;
+      try {
+        env = judgeEnv();
+      } catch (err) {
+        return { assertion, passed: false, detail: `judge not run — ${err instanceof Error ? err.message : String(err)}` };
+      }
+      const verdict = await judge(assertion.value, output, model, effort, env);
       const passed = /^\s*PASS\b/i.test(verdict);
       return { assertion, passed, detail: verdict.slice(0, 300) || "judge returned nothing" };
     }
@@ -625,7 +639,14 @@ export async function runEval(
       const judges = testCase.expect.filter((a) => a.type === "judge");
       for (const a of cheap) assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
       if (assertions.every((r) => r.passed)) {
-        for (const a of judges) assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort));
+        const judgeEnv = () => {
+          const m = accountModelEnv(tenant, workspace, () => sdkEnv(undefined));
+          if (m.format !== "anthropic") {
+            throw new Error(`this account's provider speaks ${m.format}; a judge needs an Anthropic-format provider`);
+          }
+          return m.env;
+        };
+        for (const a of judges) assertions.push(await checkAssertion(a, output, agentDir, info.model, info.effort, judgeEnv));
       } else {
         for (const a of judges) {
           assertions.push({ assertion: a, passed: false, detail: "not run — an earlier check failed" });

package/src/host-env.ts

@@ -20,6 +20,11 @@
 const EXACT = new Set([
   "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
   "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+  // Where Claude Code / the Agent SDK keeps its config and session
+  // transcripts — the same kind of thing as HOME (a path, not a secret), and
+  // without it an operator cannot keep them out of the host user's
+  // ~/.claude: the box's deploy tests set it to the job's temp (2026-10-02).
+  "CLAUDE_CONFIG_DIR",
   // The host's way to the network is the child's way to the network.
   "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
   "SSL_CERT_FILE", "SSL_CERT_DIR",
@@ -49,3 +54,30 @@ export function hostSafeEnv(from: NodeJS.ProcessEnv = process.env): NodeJS.Proce
   // every spawn. The value is the same either way.
   return out as NodeJS.ProcessEnv;
 }
+
+/**
+ * Where this install's own API answers, for a step to call: `FOLDRUN_API_URL`
+ * when the operator set it, else `FOLDRUN_PUBLIC_URL` + `/api`. Undefined on a
+ * laptop with neither.
+ *
+ * A desk that reads its own run history used to write the host into its
+ * files (`https://dev.foldrun.io/api`), so the same workspace pointed at the
+ * wrong server the day it moved. Now a script reads `$FOLDRUN_API_URL` and an
+ * `apis:` entry writes `base: ${FOLDRUN_API_URL}`.
+ */
+export function platformApiUrl(from: NodeJS.ProcessEnv = process.env): string | undefined {
+  const explicit = from.FOLDRUN_API_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  const origin = from.FOLDRUN_PUBLIC_URL?.trim();
+  return origin ? `${origin.replace(/\/+$/, "")}/api` : undefined;
+}
+
+/** The install's own addresses an `apis:` base may name. Not secrets: they
+ *  are printed in the prompt as the tool's base URL. */
+export function expandPlatformVars(value: string, from: NodeJS.ProcessEnv = process.env): string {
+  const vars: Record<string, string | undefined> = {
+    FOLDRUN_API_URL: platformApiUrl(from),
+    FOLDRUN_PUBLIC_URL: from.FOLDRUN_PUBLIC_URL?.trim().replace(/\/+$/, "") || undefined,
+  };
+  return value.replace(/\$\{(FOLDRUN_API_URL|FOLDRUN_PUBLIC_URL)\}/g, (whole, name: string) => vars[name] ?? whole);
+}

package/src/install-helper.ts

@@ -0,0 +1,143 @@
+// The root half of the `install` tool: a tiny server the run container's root
+// start-up leaves running before it drops to the agent user.
+//
+//   node install-helper.js <socket> <runtime cache dir>
+//
+// The agent never becomes root. It can only ask this process, over a unix
+// socket, to install Debian packages BY NAME — each name re-checked against
+// Debian's naming rule here, so nothing but a package name reaches apt, and
+// apt is driven by the same snippet the start-up uses (systemInstallSh): the
+// account's .deb cache and snapshots, so a package anyone installed before is
+// restored in about a second. Requests are served one at a time; the process
+// dies with the container.
+//
+// pip and npm need no root and are installed by the tool itself, as the agent.
+
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { DEB_PACKAGE, systemInstallSh, summarizeInstallFailure } from "./runtime.ts";
+
+export interface InstallRequest {
+  manager: "apt";
+  packages: string[];
+}
+
+export interface InstallReply {
+  ok: boolean;
+  /** "snapshot" | "apt" */
+  mode?: string;
+  seconds?: number;
+  error?: string;
+}
+
+/** Validate one request; null when it may run. Exported for the tests. */
+export function refuse(req: unknown): string | null {
+  const r = req as Partial<InstallRequest> | null;
+  if (!r || typeof r !== "object") return "not a request";
+  if (r.manager !== "apt") return "this helper installs Debian packages (manager: apt) only";
+  if (!Array.isArray(r.packages) || r.packages.length === 0) return "no packages named";
+  if (r.packages.length > 50) return "at most 50 packages per request";
+  const bad = r.packages.filter((p) => typeof p !== "string" || !DEB_PACKAGE.test(p));
+  if (bad.length) return `not Debian package names: ${bad.map(String).join(", ")}`;
+  return null;
+}
+
+/** Install one validated request with the start-up's own snippet. */
+export function installApt(packages: string[], cacheDir: string): Promise<InstallReply> {
+  const logDir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-install-"));
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-c", systemInstallSh(cacheDir, logDir)], {
+      env: { ...process.env, FOLDRUN_SYSTEM_PACKAGES: packages.join(" ") },
+      stdio: "ignore",
+    });
+    child.on("close", () => {
+      let status: { ok?: boolean; mode?: string; seconds?: number } = {};
+      try {
+        status = JSON.parse(fs.readFileSync(path.join(logDir, "system-install.json"), "utf8"));
+      } catch {
+        status = { ok: false };
+      }
+      let log = "";
+      try {
+        log = fs.readFileSync(path.join(logDir, "system-install.log"), "utf8");
+      } catch {
+        log = "";
+      }
+      fs.rmSync(logDir, { recursive: true, force: true });
+      resolve(
+        status.ok
+          ? { ok: true, mode: status.mode, seconds: status.seconds }
+          : { ok: false, error: summarizeInstallFailure("apt-get install", log || "no output") },
+      );
+    });
+    child.on("error", (err) => {
+      fs.rmSync(logDir, { recursive: true, force: true });
+      resolve({ ok: false, error: `could not run the installer: ${err.message}` });
+    });
+  });
+}
+
+export function serve(socket: string, cacheDir: string): net.Server {
+  try {
+    fs.rmSync(socket, { force: true });
+  } catch {
+    /* nothing there */
+  }
+  let queue: Promise<unknown> = Promise.resolve();
+  const server = net.createServer((conn) => {
+    let buf = "";
+    conn.on("data", (chunk) => {
+      buf += chunk.toString("utf8");
+      if (buf.length > 64_000) {
+        conn.end(JSON.stringify({ ok: false, error: "request too large" }) + "\n");
+        return;
+      }
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return;
+      const line = buf.slice(0, nl);
+      buf = "";
+      let req: unknown;
+      try {
+        req = JSON.parse(line);
+      } catch {
+        conn.end(JSON.stringify({ ok: false, error: "not JSON" }) + "\n");
+        return;
+      }
+      const why = refuse(req);
+      if (why) {
+        conn.end(JSON.stringify({ ok: false, error: why }) + "\n");
+        return;
+      }
+      // One install at a time: apt holds a lock, and two dpkg runs in one
+      // container would fight over it.
+      queue = queue.then(async () => {
+        const reply = await installApt((req as InstallRequest).packages, cacheDir);
+        conn.end(JSON.stringify(reply) + "\n");
+      });
+    });
+    conn.on("error", () => {
+      /* the client went away */
+    });
+  });
+  server.listen(socket, () => {
+    // The agent user must be able to connect; nothing else runs in here.
+    try {
+      fs.chmodSync(socket, 0o666);
+    } catch {
+      /* best effort */
+    }
+  });
+  return server;
+}
+
+if (process.argv[1] && /install-helper\.(js|ts|mjs)$/.test(process.argv[1])) {
+  const [socket, cacheDir] = process.argv.slice(2);
+  if (!socket || !cacheDir) {
+    console.error("usage: install-helper <socket> <runtime cache dir>");
+    process.exit(2);
+  }
+  serve(socket, cacheDir);
+}