@foldrun/core 0.3.0 → 0.5.0

package/dist/src/operator.d.ts

@@ -0,0 +1,201 @@
+import type { EventExtra } from "./step-exec.ts";
+import type { StepMessage, StepQuestion } from "./store.ts";
+/** What a trace event carries when a person was involved. */
+export type OperatorEvent = {
+    kind: "asked";
+    id: string;
+    question: string;
+    options?: string[];
+} | {
+    kind: "answered";
+    id: string;
+    answer: string;
+    by?: string | null;
+} | {
+    kind: "unanswered";
+    id: string;
+} | {
+    kind: "message";
+    text: string;
+    by?: string | null;
+    at: string;
+};
+export interface OperatorMessage {
+    text: string;
+    by?: string | null;
+    at: string;
+}
+/** The pod's side of the line. `null` when there is no proxy (the CLI, a
+ *  compose install without one): then nobody can answer or write in. */
+export interface OperatorChannel {
+    ask(question: string, options?: string[]): Promise<{
+        id: string;
+    }>;
+    /** Waits up to `maxMs` for this question's answer; null when none came. */
+    poll(id: string, maxMs: number): Promise<{
+        answer: string;
+        by?: string | null;
+    } | null>;
+    inbox(): Promise<OperatorMessage[]>;
+    /** Nobody will read this question's answer now (the wait timed out):
+     *  stop offering it to people. Best effort; optional for fakes. */
+    close?(id: string): Promise<void>;
+}
+export declare const QUESTION_MAX = 2000;
+export declare const OPTION_MAX = 200;
+export declare const OPTIONS_MAX = 10;
+export declare const ANSWER_MAX = 4000;
+export declare const MESSAGE_MAX = 4000;
+/** One long-poll round trip — under any proxy's idle cut-off. */
+export declare const POLL_MS = 25000;
+export declare const ASK_DEFAULT_SEC: number;
+export declare const ASK_MAX_SEC: number;
+/** `http://w:8090/e/<lease>` → the proxy's origin and the lease token. */
+export declare function operatorEndpoint(egress: string | undefined | null): {
+    base: string;
+    token: string;
+} | null;
+/** The channel over the egress proxy. `fetchImpl` is for tests. */
+export declare function httpChannel(egress: string | undefined | null, fetchImpl?: typeof fetch): OperatorChannel | null;
+/** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
+export declare function askTimeoutSec(front: Record<string, unknown>): number;
+/** "90s", "30m", "2h", "1d" or a number of seconds; null when unreadable. */
+export declare function parseDuration(raw: unknown): number | null;
+export declare const NO_ANSWER = "No one answered in time. Decide for yourself if the choice is safe and say what you chose and why; if it is not, stop and reply BLOCKED with the question.";
+type Emit = (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
+/** The in-sandbox `ask_person` tool. With no channel (no proxy), `local`
+ *  answers instead — the CLI prompts on a terminal — or nobody does. */
+export declare function buildAskTool(opts: {
+    channel: OperatorChannel | null;
+    timeoutSec: number;
+    emit: Emit;
+    local?: (question: string, options?: string[]) => Promise<string | null>;
+    now?: () => number;
+}): {
+    server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+    /** The tool's own function, for tests. */
+    call: (args: {
+        question: string;
+        options?: string[];
+    }) => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+    toolNames: string[];
+    promptLines: string[];
+};
+/** The granted name of the tool — the same on every path. */
+export declare const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+/** The line the system prompt gets for it. */
+export declare function askPromptLine(timeoutSec: number): string;
+/** Reads the run's inbox after tool calls and turns messages into context
+ *  for the model. At most one read every `minGapMs`; a failed read is
+ *  silent (the next tool call tries again). */
+export declare function inboxReader(channel: OperatorChannel | null, emit: Emit, minGapMs?: number, now?: () => number): () => Promise<string | null>;
+/** Fold one operator event into the step's record. Pure; the runner calls
+ *  it as events arrive, whichever sandbox sent them. */
+export declare function applyOperatorEvent(step: {
+    questions?: StepQuestion[];
+    messages?: StepMessage[];
+}, ev: OperatorEvent, at: string): void;
+/** The question a step is waiting on, if any. */
+export declare const openQuestion: (step: {
+    questions?: StepQuestion[];
+}) => StepQuestion | null;
+/** Is this — read off the sandbox's stdout, so untrusted — an operator
+ *  event of the right shape and size? Anything else is dropped. */
+export declare function isOperatorEvent(v: unknown): v is OperatorEvent;
+export {};

package/dist/src/operator.js

@@ -0,0 +1,251 @@
+// A person in the loop while a step runs: the agent asks, a person answers,
+// or a person says something the agent should hear.
+//
+// Until this, the only way a person reached a step was before it started —
+// `ask:`, an approval gate, `wait: event` — and the answer arrived as
+// prompt text. An agent that found, halfway through, that it needed a
+// decision had to fail or guess.
+//
+// Two things, one line out of the sandbox. A run pod has no ingress; the
+// only live door is the worker's egress proxy, reached at the per-step
+// lease address the pod already holds (FOLDRUN_EGRESS = http://<w>/e/<lease>).
+// The lease names the account and the run, so a step can only ever ask in,
+// or read the inbox of, its own run.
+//
+//   tools: [ask]   the agent gets `ask_person` — POST the question, then
+//                  long-poll for the answer; the step's sandbox is held
+//                  (and charged) while it waits, up to `ask: {timeout}`
+//   every step     after each tool call, its run's inbox is read and any
+//                  message is handed to the model as context
+//
+// Both leave a trace event with an `operator` field, which the runner turns
+// into step.questions / step.messages on the record.
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+export const QUESTION_MAX = 2_000;
+export const OPTION_MAX = 200;
+export const OPTIONS_MAX = 10;
+export const ANSWER_MAX = 4_000;
+export const MESSAGE_MAX = 4_000;
+/** One long-poll round trip — under any proxy's idle cut-off. */
+export const POLL_MS = 25_000;
+export const ASK_DEFAULT_SEC = 30 * 60;
+export const ASK_MAX_SEC = 24 * 60 * 60;
+/** `http://w:8090/e/<lease>` → the proxy's origin and the lease token. */
+export function operatorEndpoint(egress) {
+    if (!egress)
+        return null;
+    const m = egress.match(/^(https?:\/\/[^/]+)\/e\/([A-Za-z0-9_-]{16,})\/?$/);
+    return m ? { base: m[1], token: m[2] } : null;
+}
+/** The channel over the egress proxy. `fetchImpl` is for tests. */
+export function httpChannel(egress, fetchImpl = fetch) {
+    const ep = operatorEndpoint(egress);
+    if (!ep)
+        return null;
+    const json = async (res) => {
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(String(body.error?.message ?? `proxy answered ${res.status}`));
+        return body;
+    };
+    return {
+        async ask(question, options) {
+            const body = await json(await fetchImpl(`${ep.base}/ask/${ep.token}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ question, options }),
+                signal: AbortSignal.timeout(15_000),
+            }));
+            return { id: String(body.id) };
+        },
+        async poll(id, maxMs) {
+            const wait = Math.max(0, Math.min(maxMs, POLL_MS));
+            const body = await json(await fetchImpl(`${ep.base}/ask/${ep.token}/${encodeURIComponent(id)}?wait=${wait}`, {
+                signal: AbortSignal.timeout(wait + 15_000),
+            }));
+            return typeof body.answer === "string" ? { answer: body.answer, by: body.by ?? null } : null;
+        },
+        async inbox() {
+            const body = await json(await fetchImpl(`${ep.base}/inbox/${ep.token}`, { signal: AbortSignal.timeout(3_000) }));
+            return Array.isArray(body.messages) ? body.messages : [];
+        },
+        async close(id) {
+            await json(await fetchImpl(`${ep.base}/ask/${ep.token}/${encodeURIComponent(id)}`, {
+                method: "DELETE",
+                signal: AbortSignal.timeout(5_000),
+            }));
+        },
+    };
+}
+/** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
+export function askTimeoutSec(front) {
+    const raw = front.ask?.timeout;
+    const sec = parseDuration(raw);
+    return sec === null ? ASK_DEFAULT_SEC : Math.min(Math.max(sec, 30), ASK_MAX_SEC);
+}
+/** "90s", "30m", "2h", "1d" or a number of seconds; null when unreadable. */
+export function parseDuration(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        return raw;
+    if (typeof raw !== "string")
+        return null;
+    const m = raw.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)?$/i);
+    if (!m)
+        return null;
+    const mult = { s: 1, m: 60, h: 3600, d: 86400 }[(m[2] ?? "s").toLowerCase()];
+    return Math.round(Number(m[1]) * mult);
+}
+export const NO_ANSWER = "No one answered in time. Decide for yourself if the choice is safe and say what you chose and why; if it is not, stop and reply BLOCKED with the question.";
+/** The in-sandbox `ask_person` tool. With no channel (no proxy), `local`
+ *  answers instead — the CLI prompts on a terminal — or nobody does. */
+export function buildAskTool(opts) {
+    const now = opts.now ?? Date.now;
+    const ask = tool("ask_person", "Ask the person running this desk a question and wait for their answer. Use it for a decision you cannot make safely yourself — not for information you can look up. Give a short list of options when the answer is one of a few choices. Returns the answer, or says nobody answered in time.", {
+        question: z.string().describe("The complete, self-contained question — the person has not read your work"),
+        options: z.array(z.string()).optional().describe("Up to 10 short choices, when the answer is one of them"),
+    }, async ({ question, options }) => {
+        const q = String(question).trim().slice(0, QUESTION_MAX);
+        const opts2 = (options ?? []).map((o) => String(o).trim().slice(0, OPTION_MAX)).filter(Boolean).slice(0, OPTIONS_MAX);
+        const text = (t) => ({ content: [{ type: "text", text: t }] });
+        if (!q)
+            return { ...text("ask_person needs a question."), isError: true };
+        if (!opts.channel) {
+            const local = opts.local ? await opts.local(q, opts2.length ? opts2 : undefined) : null;
+            const id = "local";
+            opts.emit("info", `asked a person: ${q}`, { operator: { kind: "asked", id, question: q, ...(opts2.length ? { options: opts2 } : {}) } });
+            if (local === null || local.trim() === "") {
+                opts.emit("info", "no answer — nobody can answer here", { operator: { kind: "unanswered", id } });
+                return text(NO_ANSWER);
+            }
+            opts.emit("info", `answered: ${local}`, { operator: { kind: "answered", id, answer: local, by: "terminal" } });
+            return text(`The person answered: ${local}`);
+        }
+        let id;
+        try {
+            ({ id } = await opts.channel.ask(q, opts2.length ? opts2 : undefined));
+        }
+        catch (err) {
+            return { ...text(`Could not ask: ${err instanceof Error ? err.message : String(err)}. ${NO_ANSWER}`), isError: true };
+        }
+        opts.emit("info", `asked a person: ${q}`, { operator: { kind: "asked", id, question: q, ...(opts2.length ? { options: opts2 } : {}) } });
+        const deadline = now() + opts.timeoutSec * 1000;
+        while (now() < deadline) {
+            let got = null;
+            try {
+                got = await opts.channel.poll(id, deadline - now());
+            }
+            catch {
+                // A dropped long-poll is retried; the deadline is what ends it.
+                await new Promise((r) => setTimeout(r, 2_000));
+                continue;
+            }
+            if (got) {
+                const answer = got.answer.slice(0, ANSWER_MAX);
+                opts.emit("info", `answered${got.by ? ` by ${got.by}` : ""}: ${answer}`, { operator: { kind: "answered", id, answer, by: got.by ?? null } });
+                return text(`The person answered: ${answer}`);
+            }
+        }
+        // Close it on the proxy, so the dashboard stops offering a box whose
+        // answer nobody would read. Best effort: a failure changes nothing here.
+        try {
+            await opts.channel.close?.(id);
+        }
+        catch {
+            /* the proxy's TTL clears it eventually */
+        }
+        opts.emit("info", `no answer after ${Math.round(opts.timeoutSec / 60)} min`, { operator: { kind: "unanswered", id } });
+        return text(NO_ANSWER);
+    });
+    return {
+        server: createSdkMcpServer({ name: "foldrun_ask", version: "1.0.0", tools: [ask] }),
+        /** The tool's own function, for tests. */
+        call: (args) => ask.handler({ question: args.question, options: args.options }, {}),
+        toolNames: [ASK_TOOL],
+        promptLines: [askPromptLine(opts.timeoutSec)],
+    };
+}
+/** The granted name of the tool — the same on every path. */
+export const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+/** The line the system prompt gets for it. */
+export function askPromptLine(timeoutSec) {
+    return `\`ask_person\` asks the person running this desk and waits for the answer (up to ${fmtWait(timeoutSec)}). Use it for a decision you cannot make safely yourself — not for something you can look up. The step is held while you wait; if nobody answers, you are told so.`;
+}
+const fmtWait = (sec) => (sec >= 3600 ? `${Math.round(sec / 360) / 10} h` : `${Math.round(sec / 60)} min`);
+/** Reads the run's inbox after tool calls and turns messages into context
+ *  for the model. At most one read every `minGapMs`; a failed read is
+ *  silent (the next tool call tries again). */
+export function inboxReader(channel, emit, minGapMs = 1_500, now = Date.now) {
+    let last = Number.NEGATIVE_INFINITY;
+    return async () => {
+        if (!channel)
+            return null;
+        if (now() - last < minGapMs)
+            return null;
+        last = now();
+        let messages;
+        try {
+            messages = await channel.inbox();
+        }
+        catch {
+            return null;
+        }
+        if (!messages.length)
+            return null;
+        for (const m of messages) {
+            emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
+        }
+        return messages
+            .map((m) => `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`)
+            .join("\n\n");
+    };
+}
+/** Fold one operator event into the step's record. Pure; the runner calls
+ *  it as events arrive, whichever sandbox sent them. */
+export function applyOperatorEvent(step, ev, at) {
+    if (ev.kind === "asked") {
+        const qs = (step.questions ??= []);
+        if (!qs.some((q) => q.id === ev.id && ev.id !== "local")) {
+            qs.push({ id: ev.id, question: ev.question, ...(ev.options?.length ? { options: ev.options } : {}), askedAt: at });
+        }
+        return;
+    }
+    if (ev.kind === "answered" || ev.kind === "unanswered") {
+        const q = [...(step.questions ?? [])].reverse().find((x) => x.id === ev.id && x.answer === undefined && !x.unanswered);
+        if (!q)
+            return;
+        if (ev.kind === "answered") {
+            q.answer = ev.answer;
+            q.answeredAt = at;
+            q.by = ev.by ?? null;
+        }
+        else
+            q.unanswered = true;
+        return;
+    }
+    (step.messages ??= []).push({ text: ev.text, by: ev.by ?? null, at: ev.at, deliveredAt: at });
+}
+/** The question a step is waiting on, if any. */
+export const openQuestion = (step) => [...(step.questions ?? [])].reverse().find((q) => q.answer === undefined && !q.unanswered) ?? null;
+/** Is this — read off the sandbox's stdout, so untrusted — an operator
+ *  event of the right shape and size? Anything else is dropped. */
+export function isOperatorEvent(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    const str = (x, max) => typeof x === "string" && x.length <= max;
+    const id = str(o.id, 64);
+    switch (o.kind) {
+        case "asked":
+            return id && str(o.question, QUESTION_MAX) &&
+                (o.options === undefined || (Array.isArray(o.options) && o.options.length <= OPTIONS_MAX && o.options.every((x) => str(x, OPTION_MAX))));
+        case "answered":
+            return id && str(o.answer, ANSWER_MAX) && (o.by === undefined || o.by === null || str(o.by, 200));
+        case "unanswered":
+            return id;
+        case "message":
+            return str(o.text, MESSAGE_MAX) && str(o.at, 40) && (o.by === undefined || o.by === null || str(o.by, 200));
+        default:
+            return false;
+    }
+}

package/dist/src/paths.d.ts

@@ -31,3 +31,36 @@ export declare function dataRoot(): string;
  * no account and no tenant there, so the wrapper directories collapse away.
  */
 export declare function singleWorkspace(): string | null;
+/**
+ * The account scope in single-workspace mode: where `AGENTS.md` and
+ * `library/` live for the workspace this process is pinned to. Null in the
+ * multi-tenant layout, where the account is a tenant directory under the data
+ * root and nothing has to be inferred.
+ *
+ * It used to be, everywhere, `path.resolve(single, "..")`. That is right for a
+ * flat workspace and wrong for one inside an account folder, where the parent
+ * is `workspaces/` — a directory with no AGENTS.md and no library in it. Every
+ * `skills:`, `tools:` and `scripts:` that named something shared then resolved
+ * against an empty directory and came back missing. `accountRootFor` knows the
+ * difference; `FOLDRUN_ACCOUNT` overrides both, for an embedder that has
+ * already decided.
+ */
+export declare function singleAccountRoot(): string | null;
+/** Without leading and/or trailing slashes. */
+export declare function trimSlashes(s: string, where?: "start" | "end" | "both"): string;
+/** Without any of `chars` at the ends — the linear form of
+ *  `.replace(/^[chars]+/, "").replace(/[chars]+$/, "")`. */
+export declare function trimChars(s: string, chars: string): string;
+/** The largest file a person (or the gallery) writes into a workspace or the
+ *  library through the store: 512 KB. A folder tool's program is one file,
+ *  and the gallery browser's passed 256 KB on 2026-09-29. */
+export declare const MAX_EDITABLE_FILE: number;
+/**
+ * Every entry under `dir`, relative, like `fs.readdirSync(dir, { recursive:
+ * true })` — except that a link to a directory is listed and NOT entered.
+ * Node's recursive readdir follows directory links, so a link back up the
+ * tree (the `workspace` link a step holds in its agent folder, confine.ts)
+ * is walked about forty levels deep before the kernel stops it, each level
+ * a full copy of the workspace.
+ */
+export declare function entriesNoFollow(dir: string): string[];

package/dist/src/paths.js

@@ -21,6 +21,7 @@
 // caches: the whole point is that the answer can change between calls.
 import fs from "node:fs";
 import path from "node:path";
+import { accountRootFor } from "./layout.js";
 /**
  * The nearest enclosing project root, found by walking up from `from` looking
  * for a `.git` directory. Null when there is none — an installed package in
@@ -76,3 +77,89 @@ export function dataRoot() {
 export function singleWorkspace() {
     return process.env.FOLDRUN_WORKSPACE ?? null;
 }
+/**
+ * The account scope in single-workspace mode: where `AGENTS.md` and
+ * `library/` live for the workspace this process is pinned to. Null in the
+ * multi-tenant layout, where the account is a tenant directory under the data
+ * root and nothing has to be inferred.
+ *
+ * It used to be, everywhere, `path.resolve(single, "..")`. That is right for a
+ * flat workspace and wrong for one inside an account folder, where the parent
+ * is `workspaces/` — a directory with no AGENTS.md and no library in it. Every
+ * `skills:`, `tools:` and `scripts:` that named something shared then resolved
+ * against an empty directory and came back missing. `accountRootFor` knows the
+ * difference; `FOLDRUN_ACCOUNT` overrides both, for an embedder that has
+ * already decided.
+ */
+export function singleAccountRoot() {
+    const single = singleWorkspace();
+    if (!single)
+        return null;
+    if (process.env.FOLDRUN_ACCOUNT)
+        return path.resolve(process.env.FOLDRUN_ACCOUNT);
+    return accountRootFor(path.resolve(single));
+}
+// ------------------------------------------------------- linear trimming
+//
+// `s.replace(/\/+$/, "")` is the obvious way to drop trailing slashes and
+// it is quadratic: the engine tries `\/+` from every position and fails at
+// `$` each time, so a string of ten thousand slashes is fifty million
+// steps. Several of these strings come from a customer's own files — a
+// base_url, a tool's base, a storage prefix — which is exactly the input
+// that must not be able to stall a worker. A loop is linear and reads the
+// same.
+/** Without leading and/or trailing slashes. */
+export function trimSlashes(s, where = "end") {
+    let a = 0;
+    let b = s.length;
+    if (where !== "end")
+        while (a < b && s[a] === "/")
+            a++;
+    if (where !== "start")
+        while (b > a && s[b - 1] === "/")
+            b--;
+    return s.slice(a, b);
+}
+/** Without any of `chars` at the ends — the linear form of
+ *  `.replace(/^[chars]+/, "").replace(/[chars]+$/, "")`. */
+export function trimChars(s, chars) {
+    let a = 0;
+    let b = s.length;
+    while (a < b && chars.includes(s[a]))
+        a++;
+    while (b > a && chars.includes(s[b - 1]))
+        b--;
+    return s.slice(a, b);
+}
+/** The largest file a person (or the gallery) writes into a workspace or the
+ *  library through the store: 512 KB. A folder tool's program is one file,
+ *  and the gallery browser's passed 256 KB on 2026-09-29. */
+export const MAX_EDITABLE_FILE = 512 * 1024;
+/**
+ * Every entry under `dir`, relative, like `fs.readdirSync(dir, { recursive:
+ * true })` — except that a link to a directory is listed and NOT entered.
+ * Node's recursive readdir follows directory links, so a link back up the
+ * tree (the `workspace` link a step holds in its agent folder, confine.ts)
+ * is walked about forty levels deep before the kernel stops it, each level
+ * a full copy of the workspace.
+ */
+export function entriesNoFollow(dir) {
+    const out = [];
+    const walk = (abs, rel) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const r = rel ? path.join(rel, e.name) : e.name;
+            out.push(r);
+            if (e.isDirectory())
+                walk(path.join(abs, e.name), r);
+        }
+    };
+    walk(dir, "");
+    return out;
+}