@fungi.computer/truffle 0.1.1 → 0.2.1

package/dist/private-invocation-computer.js

@@ -1,5 +1,4 @@
 import { realpath } from "node:fs/promises";
-import { homedir } from "node:os";
 import { relative, resolve, sep } from "node:path";
 import process from "node:process";
 import * as ChildProcess from "effect/process/ChildProcess";
@@ -18,7 +17,12 @@ import { z } from "zod";
 import { backgroundExecInput, backgroundExecOutput, callBackgroundExec, } from "./private-local-computer-processes.js";
 import { capturePrivateLocalExecPath, parsePrivateLocalExecPath, } from "./private-local-exec-path.js";
 import { combinedArgvBytes, launchCwdSchema, launchStdinSchema, maximumLaunchTextLength, } from "./private-local-exec-launch.js";
+import { privateLocalExecEnvironment } from "./private-local-exec-environment.js";
+import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
 const maximumStreamBytes = 64 * 1_024;
+/** Room inside the stream cap for the visible truncation marker. */
+const truncationMarkerReserveBytes = 256;
+const keptStreamBytes = maximumStreamBytes - truncationMarkerReserveBytes;
 const defaultCommandTimeoutMs = 180_000;
 /**
  * Keep in sync with the invocation deadline `private-local-runtime-host.ts`
@@ -78,11 +82,16 @@ const directRunInput = z
  * branch and the union is refused.
  */
 const execInput = z.union([shellRunInput, directRunInput]);
+const execTruncation = z.strictObject({
+    stream: z.enum(["stdout", "stderr"]),
+    keptBytes: z.number().int().nonnegative(),
+    totalBytes: z.number().int().positive(),
+});
 const commandOutputFields = {
     exitCode: z.number().int(),
     stdout: z.string(),
     stderr: z.string(),
-    truncated: z.boolean(),
+    truncated: z.union([z.literal(false), z.array(execTruncation).min(1)]),
 };
 const execOutput = z.discriminatedUnion("status", [
     z.strictObject({
@@ -105,14 +114,10 @@ function computerCapabilities(root, processes) {
             id: "exec",
             name: "exec",
             kind: "runtime",
-            // Kept terse: a long-rooted project (real test case: a nested nearly
-            // 200-byte root) plus this text must stay under Mycelium's 1000-char
-            // operation-description bound. Do not restate the full contract here;
-            // the JSON Schema parameters carry the exact shape.
-            description: `Shell, terminal, git, builds and checks. Computer root: ${root}. cwd must be absolute and remain inside this root; omission starts at the root. ~/$HOME use home. Or {executable,args}; stdin once, closed. exec stops its group, including nohup. timeoutMs default ${String(defaultCommandTimeoutMs)}, max ${String(maximumCommandTimeoutMs)} ms; invocation ${String(invocationDeadlineMs)} ms. Deadline returns partial output.${processes === undefined ? "" : ' Background start takes command or executable+args; {operation:"start",command} returns process.id; poll/wait: state, exitCode, output tail. wait <=60000 ms (default 10000); timedOut means wait expired. Cancelling wait keeps jobs alive. maxBytes <=64 KiB with offset/nextOffset; retain last 8 MiB (logStartOffset). kill stops group; list shows Session jobs. Delete/close stop jobs; restart drops IDs. Use wait, not sleep.'}`,
-            parameters: structuredClone(z.toJSONSchema(processes === undefined ? execInput : shellInput, {
-                io: "input",
-            })),
+            // A filesystem path has no place in the bounded discovery summary.
+            // Publish the exact root in the input schema, without truncating it.
+            description: `Shell, terminal, git, builds. cwd uses the root in the input schema. ~/$HOME use home. Or {executable,args}; stdin once, closed. exec kills its group at call end; nohup/& die. timeoutMs default ${String(defaultCommandTimeoutMs)}, max ${String(maximumCommandTimeoutMs)} ms; invocation ${String(invocationDeadlineMs)} ms; deadline returns partial output. Streams keep 64 KiB, then a [stdout|stderr truncated] line; redirect to a file or head/tail.${processes === undefined ? "" : ' Jobs: {operation:"start",command} or executable+args returns process.id; poll/wait: state, exitCode, tail. wait <=60000 ms; timedOut: wait expired. Cancelled wait keeps jobs. maxBytes <=64 KiB, offset/nextOffset; keeps last 8 MiB (logStartOffset). kill stops group; list: Session jobs. Delete/close stop jobs. Use wait, not sleep.'}`,
+            parameters: structuredClone(z.toJSONSchema((processes === undefined ? execInput : shellInput).describe(`Computer root: ${root}. cwd must be absolute and remain inside this root; omission starts at the root.`), { io: "input" })),
             output: structuredClone(z.toJSONSchema(processes === undefined ? execOutput : shellOutput)),
         },
     ]);
@@ -242,52 +247,70 @@ function nativeGroupFinalizer(process) {
     })));
 }
 function captureBoundedOutput(stream) {
-    const initial = {
-        chunks: [],
-        byteLength: 0,
-        truncated: false,
-    };
+    const initial = { chunks: [], byteLength: 0, totalBytes: 0 };
     return Stream.runFold(stream, () => initial, (captured, chunk) => {
-        if (captured.truncated)
-            return captured;
-        const remaining = maximumStreamBytes - captured.byteLength;
-        if (chunk.byteLength <= remaining) {
-            return {
-                chunks: [...captured.chunks, chunk],
-                byteLength: captured.byteLength + chunk.byteLength,
-                truncated: false,
-            };
-        }
+        const remaining = keptStreamBytes - captured.byteLength;
+        const totalBytes = captured.totalBytes + chunk.byteLength;
+        if (remaining <= 0)
+            return { ...captured, totalBytes };
+        const kept = chunk.byteLength <= remaining ? chunk : chunk.slice(0, remaining);
         return {
-            chunks: remaining === 0
-                ? captured.chunks
-                : [...captured.chunks, chunk.slice(0, remaining)],
-            byteLength: maximumStreamBytes,
-            truncated: true,
+            chunks: [...captured.chunks, kept],
+            byteLength: captured.byteLength + kept.byteLength,
+            totalBytes,
         };
     });
 }
-function textOutput(captured) {
+/** Length of the longest prefix that does not end inside a UTF-8 character. */
+function completeUtf8Length(bytes) {
+    let start = bytes.byteLength;
+    while (start > 0 && ((bytes[start - 1] ?? 0) & 0xc0) === 0x80)
+        start -= 1;
+    if (start === 0)
+        return 0;
+    const lead = bytes[start - 1] ?? 0;
+    const width = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+    return start - 1 + width <= bytes.byteLength ? bytes.byteLength : start - 1;
+}
+function kibibytes(bytes) {
+    return `${(bytes / 1_024).toFixed(1)} KiB`;
+}
+function textOutput(captured, stream) {
     const bytes = new Uint8Array(captured.byteLength);
     let offset = 0;
     for (const chunk of captured.chunks) {
         bytes.set(chunk, offset);
         offset += chunk.byteLength;
     }
+    if (captured.totalBytes <= captured.byteLength) {
+        return { text: new TextDecoder().decode(bytes), truncation: [] };
+    }
+    const keptBytes = completeUtf8Length(bytes);
+    const text = new TextDecoder().decode(bytes.subarray(0, keptBytes));
     return {
-        text: new TextDecoder().decode(bytes),
-        truncated: captured.truncated,
+        text: `${text}\n[fungi: ${stream} truncated: ${kibibytes(keptBytes)} of ${kibibytes(captured.totalBytes)} shown; redirect to a file or use head/tail]`,
+        truncation: [
+            {
+                stream,
+                keptBytes,
+                totalBytes: captured.totalBytes,
+            },
+        ],
     };
 }
+function truncationReport(...parts) {
+    const all = parts.flat();
+    return all.length === 0 ? false : all;
+}
 function commandResult(exitCode, stdout, stderr) {
-    const standardOutput = textOutput(stdout);
-    const standardError = textOutput(stderr);
+    const standardOutput = textOutput(stdout, "stdout");
+    const standardError = textOutput(stderr, "stderr");
     return {
         status: exitCode === 0 ? "completed" : "failed",
         exitCode,
         stdout: standardOutput.text,
         stderr: standardError.text,
-        truncated: standardOutput.truncated || standardError.truncated,
+        truncated: truncationReport(standardOutput.truncation, standardError.truncation),
     };
 }
 /**
@@ -308,8 +331,12 @@ function describeRunRequest(request) {
  * passes `executable`/`args` straight to `ChildProcess.make`, never through a
  * shell; only the intentional shell form interpolates into `sh -c`.
  */
-function buildRunCommand(request, cwd, executionPath) {
-    const env = { PATH: executionPath, HOME: process.env.HOME ?? homedir() };
+function buildRunCommand(request, cwd, executionPath, home, sandbox) {
+    const env = privateLocalExecEnvironment(executionPath, {
+        HOME: home,
+        XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
+        DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS,
+    });
     // Effect's own default stdin is an open "pipe" that nothing closes, so an
     // executable that reads stdin (`cat`, `python3 -`) would otherwise hang
     // for the full timeout. "ignore" gives it immediate EOF, matching the
@@ -317,19 +344,27 @@ function buildRunCommand(request, cwd, executionPath) {
     const stdin = request.stdin === undefined
         ? "ignore"
         : Stream.make(new TextEncoder().encode(request.stdin));
-    return "command" in request
-        ? ChildProcess.make("sh", ["-c", request.command], {
-            cwd,
-            env,
-            extendEnv: false,
-            stdin,
-        })
-        : ChildProcess.make(request.executable, request.args, {
-            cwd,
-            env,
-            extendEnv: false,
-            stdin,
-        });
+    const argv = "command" in request
+        ? ["sh", "-c", request.command]
+        : [request.executable, ...request.args];
+    // Admission happens before spawn and is never retried after an executable
+    // may have run. Folder validity and requireSandbox belong to the host.
+    const launch = sandbox?.(cwd, argv);
+    if (launch !== undefined) {
+        delete env.XDG_RUNTIME_DIR;
+        delete env.DBUS_SESSION_BUS_ADDRESS;
+    }
+    return ChildProcess.make(launch?.executable ?? argv[0], launch?.args ?? argv.slice(1), {
+        cwd,
+        env: { ...env, ...launch?.environment },
+        extendEnv: false,
+        stdin,
+        additionalFds: launch?.seccompFilter === undefined
+            ? undefined
+            : {
+                fd3: { type: "input", stream: Stream.make(launch.seccompFilter) },
+            },
+    });
 }
 /**
  * Only the direct form names an executable the host itself must locate and
@@ -341,8 +376,8 @@ function isMissingExecutableFailure(cause) {
         (cause.reason._tag === "NotFound" ||
             cause.reason._tag === "PermissionDenied"));
 }
-async function runCommandAtInvocationBoundary(request, cwd, executionPath, signal) {
-    const processCommand = buildRunCommand(request, cwd, executionPath);
+async function runCommandAtInvocationBoundary(request, cwd, executionPath, home, signal, sandbox) {
+    const processCommand = buildRunCommand(request, cwd, executionPath, home, sandbox);
     const timeoutMs = Math.min(request.timeoutMs, maximumCommandTimeoutMs);
     try {
         return await runPrivateInvocationProcess(processCommand, signal, timeoutMs, {
@@ -390,8 +425,8 @@ export function runPrivateInvocationProcess(processCommand, signal, timeoutMs, d
         if (timeoutMs === undefined)
             throw new Error("Missing command deadline");
         const elapsedMs = (yield* Clock.currentTimeMillis) - startedAt;
-        const standardOutput = textOutput(stdout);
-        const standardError = textOutput(stderr);
+        const standardOutput = textOutput(stdout, "stdout");
+        const standardError = textOutput(stderr, "stderr");
         return {
             status: "deadline_exceeded",
             timeoutMs,
@@ -406,23 +441,27 @@ export function runPrivateInvocationProcess(processCommand, signal, timeoutMs, d
                     timeoutMs,
                     requestedMs: describe.requestedMs ?? timeoutMs,
                 }),
-            truncated: standardOutput.truncated || standardError.truncated,
+            truncated: truncationReport(standardOutput.truncation, standardError.truncation),
         };
     })).pipe(Effect.provide(NodeServices.layer)), { signal });
 }
-async function execute(root, executionPath, request, context) {
+async function execute(root, executionPath, home, request, context, sandbox) {
     context.signal.throwIfAborted();
     const cwd = await resolveCwd(root, request.cwd);
     context.signal.throwIfAborted();
-    return runCommandAtInvocationBoundary(request, cwd, executionPath, context.signal);
+    return runCommandAtInvocationBoundary(request, cwd, executionPath, home, context.signal, sandbox);
 }
 /**
  * Construct one private invocation-root Computer: bounded shell exec, plus the
  * background-process operations of `processes` when the host supplies a scope.
  */
-export async function createPrivateInvocationComputer(invocationRoot, executionPath = capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd()), processes) {
-    const root = await realpath(resolve(invocationRoot));
+export async function createPrivateInvocationComputer(invocationRoot, executionPath = capturePrivateLocalExecPath(process.env.PATH ?? "/usr/bin:/bin", process.cwd()), processes, 
+/** Selected host home; standalone callers capture it before any await. */
+home = capturePrivateLocalConfigRoot().home, 
+/** Native Local always supplies its live per-Agent admission callback. */
+sandbox) {
     const path = parsePrivateLocalExecPath(executionPath);
+    const root = await realpath(resolve(invocationRoot));
     return Object.freeze({
         getCapabilities: () => Promise.resolve(computerCapabilities(root, processes)),
         call: async (capabilityId, input, context) => {
@@ -450,9 +489,9 @@ export async function createPrivateInvocationComputer(invocationRoot, executionP
                     },
                 });
             if (request.operation === "run")
-                return execute(root, path, request, context);
+                return execute(root, path, home, request, context, sandbox);
             if (processes !== undefined)
-                return jsonValueSchema.parse(await callBackgroundExec(processes, request, (requested) => resolveCwd(root, requested), path, context.signal));
+                return jsonValueSchema.parse(await callBackgroundExec(processes, request, (requested) => resolveCwd(root, requested), path, context.signal, sandbox));
             throw new Error(`Computer capability is unavailable: ${selected}`);
         },
     });

package/dist/private-invocation-files.d.ts

@@ -1,4 +1,19 @@
 import { type FilesPort } from "@fungi.computer/knapsack";
+import type { LocalSandboxLaunch } from "./private-invocation-computer.js";
+/** Same live authority as exec; the policy module owns protected-path checks. */
+export type LocalSandboxWrites = Readonly<{
+    assertWrite(path: string): void;
+    launch: LocalSandboxLaunch;
+}>;
+/**
+ * Hidden scan work for one glob or grep: directory entries admitted to the
+ * walk (gitignored and `.git` entries are never admitted) and file bytes read.
+ * The result limit counts returned results; these bound the work behind them.
+ */
+export type ScanBounds = Readonly<{
+    candidates: number;
+    bytes: number;
+}>;
 /** Safe Files path failures surfaced across the workerd binding boundary. */
 export declare class FilesPathError extends Error {
     readonly reason: "outside-root" | "not-found" | "not-file";
@@ -12,4 +27,4 @@ export declare class FilesPathError extends Error {
  * in-root symlinks. This is trusted same-user containment, not protection from
  * a same-user process racing pathname resolution.
  */
-export declare function createPrivateInvocationFilesPort(path: string): Promise<FilesPort>;
+export declare function createPrivateInvocationFilesPort(path: string, scanBounds?: ScanBounds, sandbox?: LocalSandboxWrites): Promise<FilesPort>;

package/dist/private-invocation-files.js

@@ -1,12 +1,17 @@
 import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
 import { isAbsolute, join, matchesGlob, normalize, relative, resolve, sep, } from "node:path";
 import { FilesEditError } from "@fungi.computer/knapsack";
+import { SearchVisibility } from "@fungi.computer/knapsack/files-search";
+import { imageReadResult, imageSniffBytes, imageTooLargeMessage, sniffImageMimeType, } from "@fungi.computer/knapsack/files-read";
 import { RE2JS } from "re2js";
 import { createPrivateFilesPatch } from "./private-files-patch.js";
+import { fitLocalImage, maximumLocalImageInputBytes, } from "./local-image-fit.js";
 import writeFileAtomic from "write-file-atomic";
 const maximumFileBytes = 128 * 1_024;
-const maximumScanBytes = maximumFileBytes;
-const maximumScanCandidates = 256;
+const defaultScanBounds = {
+    candidates: 50_000,
+    bytes: 64 * 1_024 * 1_024,
+};
 const utf8 = new TextEncoder();
 /** Safe Files path failures surfaced across the workerd binding boundary. */
 export class FilesPathError extends Error {
@@ -38,13 +43,17 @@ async function existingRealpath(candidate, requested) {
         throw cause;
     }
 }
-/** One maximum result page and one maximum read page bound hidden scan work. */
+/** One explicit bound on walked entries and one on bytes read. */
 class ScanBudget {
+    bounds;
     bytes = 0;
     candidates = 0;
     exhausted = false;
+    constructor(bounds) {
+        this.bounds = bounds;
+    }
     admitCandidate() {
-        if (this.candidates === maximumScanCandidates) {
+        if (this.candidates === this.bounds.candidates) {
             this.exhausted = true;
             return false;
         }
@@ -52,7 +61,7 @@ class ScanBudget {
         return true;
     }
     admitBytes(bytes) {
-        if (bytes > maximumScanBytes - this.bytes) {
+        if (bytes > this.bounds.bytes - this.bytes) {
             this.exhausted = true;
             return false;
         }
@@ -191,6 +200,18 @@ class InvocationRoot {
         throw new FilesPathError("outside-root", requested);
     }
 }
+async function readBytesAt(file, path, position, length, context) {
+    const buffer = Buffer.alloc(Math.min(length, file.size - position));
+    let bytesRead = 0;
+    while (bytesRead < buffer.byteLength) {
+        checkCancellation(context);
+        const next = await file.handle.read(buffer, bytesRead, buffer.byteLength - bytesRead, position + bytesRead);
+        if (next.bytesRead === 0)
+            throw new Error(`Files path changed during read: ${path.requested}`);
+        bytesRead += next.bytesRead;
+    }
+    return buffer;
+}
 async function readPage(path, offset, limit, context) {
     const file = await openRegularFile(path, context);
     try {
@@ -205,16 +226,19 @@ async function readPage(path, offset, limit, context) {
                 truncated: false,
             };
         }
-        const requestedBytes = Math.min(limit, file.size - offset);
-        const buffer = Buffer.alloc(requestedBytes);
-        let bytesRead = 0;
-        while (bytesRead < requestedBytes) {
-            checkCancellation(context);
-            const next = await file.handle.read(buffer, bytesRead, requestedBytes - bytesRead, offset + bytesRead);
-            if (next.bytesRead === 0)
-                throw new Error(`Files path changed during read: ${path.requested}`);
-            bytesRead += next.bytesRead;
+        if (offset === 0) {
+            const head = await readBytesAt(file, path, 0, imageSniffBytes, context);
+            const mimeType = sniffImageMimeType(head);
+            if (mimeType !== undefined) {
+                if (file.size > maximumLocalImageInputBytes)
+                    throw new Error(imageTooLargeMessage(path.requested, file.size, maximumLocalImageInputBytes));
+                // Every image is shrunk here, before it becomes an image part.
+                return imageReadResult(path.requested, "image/jpeg", await fitLocalImage(path.requested, await readBytesAt(file, path, 0, file.size, context), context.signal));
+            }
         }
+        const requestedBytes = Math.min(limit, file.size - offset);
+        const buffer = await readBytesAt(file, path, offset, requestedBytes, context);
+        const bytesRead = buffer.byteLength;
         const page = decodeUtf8(buffer, path.requested, offset + bytesRead < file.size);
         const nextOffset = offset + page.bytes;
         return {
@@ -265,7 +289,34 @@ async function readGrepCandidate(path, context) {
         return undefined;
     }
 }
-async function* walkFiles(root, base, budget, context) {
+function slashed(path) {
+    return path.split(sep).join("/");
+}
+async function readGitignore(root, directory, context) {
+    const candidate = join(directory, ".gitignore");
+    try {
+        await lstat(candidate);
+    }
+    catch (cause) {
+        if (missingPath(cause))
+            return undefined;
+        throw cause;
+    }
+    let resolved;
+    try {
+        resolved = await root.walked(candidate, candidate, context);
+    }
+    catch (cause) {
+        if (cause instanceof FilesPathError)
+            return undefined;
+        throw cause;
+    }
+    return await readGrepCandidate({ requested: candidate, resolved }, context);
+}
+function visiblePath(root, visibility, path, isDirectory) {
+    return visibility.visible(slashed(relative(root.canonicalPath, path)), isDirectory);
+}
+async function* walkFiles(root, base, budget, visibility, context) {
     async function* visit(directory, relativeParent, ancestors) {
         if (ancestors.has(directory))
             return;
@@ -274,10 +325,12 @@ async function* walkFiles(root, base, budget, context) {
         const handle = await opendir(directory);
         for await (const entry of handle) {
             checkCancellation(context);
+            const candidate = join(directory, entry.name);
+            if (!(await visiblePath(root, visibility, candidate, entry.isDirectory())))
+                continue;
             if (!budget.admitCandidate())
                 return;
             const relativePath = relativeParent === "" ? entry.name : join(relativeParent, entry.name);
-            const candidate = join(directory, entry.name);
             const resolvedPath = await root.walked(candidate, outputPath(base.requested, relativePath), context);
             checkCancellation(context);
             const metadata = await stat(resolvedPath);
@@ -298,58 +351,104 @@ async function* walkFiles(root, base, budget, context) {
     }
     yield* visit(base.resolved, "", new Set());
 }
-async function grepFile(target, input, matchesLine, context) {
+async function grepFile(target, input, context) {
     const matches = [];
     const content = await readBoundedText(target, context);
+    const limited = appendMatchingLines(matches, input.path, content, lineMatcher(input.pattern, input.regex, input.ignoreCase), input.limit, context);
     return {
         path: input.path,
-        matches,
-        truncated: appendMatchingLines(matches, input.path, content, matchesLine, input.limit, context),
+        results: matches,
+        truncated: limited ? "limit" : null,
     };
 }
-async function grepDirectory(root, target, input, matchesLine, context) {
-    const matches = [];
-    const budget = new ScanBudget();
-    let incomplete = false;
-    for await (const entry of walkFiles(root, target, budget, context)) {
-        if (entry.isDirectory)
-            continue;
-        if (!entry.isFile) {
-            incomplete = true;
+/** One directory level; the entries past the limit are only witnessed, not returned. */
+async function listLevel(root, directory, input, visibility, context) {
+    const handle = await opendir(directory.resolved);
+    const results = [];
+    for await (const entry of handle) {
+        checkCancellation(context);
+        if (!(await visiblePath(root, visibility, join(directory.resolved, entry.name), entry.isDirectory())))
             continue;
+        if (results.length === input.limit) {
+            return { path: input.path, results, truncated: "limit" };
         }
-        const logicalPath = outputPath(input.path, entry.relativePath);
-        if (entry.size > maximumFileBytes) {
-            incomplete = true;
+        const metadata = await lstat(join(directory.resolved, entry.name));
+        const path = outputPath(input.path, entry.name);
+        results.push({ path, type: entryType(metadata, path) });
+    }
+    return { path: input.path, results, truncated: null };
+}
+/** One bounded walk for a glob or content search with an optional include glob. */
+async function searchTree(root, directory, search, bounds, visibility, context) {
+    const { input } = search;
+    const pathPattern = search.kind === "glob" ? search.input.pattern : search.input.include;
+    const matchesLine = search.kind === "grep"
+        ? lineMatcher(search.input.pattern, search.input.regex, search.input.ignoreCase)
+        : undefined;
+    const results = [];
+    const budget = new ScanBudget(bounds);
+    for await (const entry of walkFiles(root, directory, budget, visibility, context)) {
+        checkCancellation(context);
+        if (pathPattern !== undefined &&
+            !matchesGlob(entry.relativePath, pathPattern))
+            continue;
+        const path = outputPath(input.path, entry.relativePath);
+        if (matchesLine === undefined) {
+            if (results.length === input.limit) {
+                return { path: input.path, results, truncated: "limit" };
+            }
+            results.push({
+                path,
+                type: entry.isDirectory ? "directory" : "file",
+            });
             continue;
         }
+        // Directories, special files, oversized files and non-text files hold no
+        // searchable lines; skipping them is not a cut of the scan.
+        if (!entry.isFile || entry.size > maximumFileBytes)
+            continue;
         if (!budget.admitBytes(entry.size))
             break;
-        const content = await readGrepCandidate({ requested: logicalPath, resolved: entry.resolvedPath }, context);
-        if (content === undefined) {
-            incomplete = true;
+        const content = await readGrepCandidate({ requested: path, resolved: entry.resolvedPath }, context);
+        if (content === undefined)
             continue;
-        }
-        if (appendMatchingLines(matches, logicalPath, content, matchesLine, input.limit, context)) {
-            return { path: input.path, matches, truncated: true };
+        if (appendMatchingLines(results, path, content, matchesLine, input.limit, context)) {
+            return { path: input.path, results, truncated: "limit" };
         }
     }
     return {
         path: input.path,
-        matches,
-        truncated: incomplete || budget.exhausted,
+        results,
+        truncated: budget.exhausted ? "scan" : null,
     };
 }
-async function grepPath(root, input, context) {
+async function searchPath(root, search, bounds, context) {
+    const { input } = search;
     const target = await root.existing(input.path, context);
     checkCancellation(context);
-    const targetMetadata = await stat(target.resolved);
-    const matchesLine = lineMatcher(input.pattern, input.regex, input.ignoreCase);
-    if (targetMetadata.isFile())
-        return await grepFile(target, input, matchesLine, context);
-    if (targetMetadata.isDirectory())
-        return await grepDirectory(root, target, input, matchesLine, context);
-    throw new Error(`Files path is not a file or directory: ${input.path}`);
+    const metadata = await stat(target.resolved);
+    const visibility = new SearchVisibility((directory) => readGitignore(root, join(root.canonicalPath, directory), context));
+    if (!(await visiblePath(root, visibility, target.resolved, metadata.isDirectory())))
+        return { path: input.path, results: [], truncated: null };
+    if (metadata.isFile()) {
+        if (search.kind === "glob")
+            throw new Error(`Files glob needs a directory path, not a file: ${input.path}`);
+        if (search.kind === "grep") {
+            if (search.input.include !== undefined)
+                throw new Error(`Files grep include needs a directory path, not a file: ${input.path}`);
+            return await grepFile(target, search.input, context);
+        }
+        return {
+            path: input.path,
+            results: [{ path: input.path, type: "file" }],
+            truncated: null,
+        };
+    }
+    if (!metadata.isDirectory())
+        throw new Error(`Files path is not a file or directory: ${input.path}`);
+    if (search.kind === "list")
+        return await listLevel(root, target, input, visibility, context);
+    return await searchTree(root, target, search, bounds, visibility, context);
 }
 function createWriteQueue() {
     let tail = Promise.resolve();
@@ -373,7 +472,7 @@ function createWriteQueue() {
  * in-root symlinks. This is trusted same-user containment, not protection from
  * a same-user process racing pathname resolution.
  */
-export async function createPrivateInvocationFilesPort(path) {
+export async function createPrivateInvocationFilesPort(path, scanBounds = defaultScanBounds, sandbox) {
     const root = await InvocationRoot.capture(path);
     const write = createWriteQueue();
     const port = {
@@ -381,44 +480,13 @@ export async function createPrivateInvocationFilesPort(path) {
             return await readPage(await root.existing(input.path, context), input.offset, input.limit, context);
         },
         async list(input, context) {
-            const directory = await root.existing(input.path, context);
-            checkCancellation(context);
-            const handle = await opendir(directory.resolved);
-            const entries = [];
-            for await (const entry of handle) {
-                checkCancellation(context);
-                if (entries.length === input.limit) {
-                    return { path: input.path, entries, truncated: true };
-                }
-                const metadata = await lstat(join(directory.resolved, entry.name));
-                const path = outputPath(input.path, entry.name);
-                entries.push({
-                    path,
-                    name: entry.name,
-                    type: entryType(metadata, path),
-                    size: metadata.size,
-                    modifiedAt: metadata.mtimeMs,
-                });
-            }
-            return { path: input.path, entries, truncated: false };
+            return await searchPath(root, { kind: "list", input }, scanBounds, context);
         },
         async glob(input, context) {
-            const directory = await root.existing(input.path, context);
-            const matches = [];
-            const budget = new ScanBudget();
-            for await (const entry of walkFiles(root, directory, budget, context)) {
-                checkCancellation(context);
-                if (!matchesGlob(entry.relativePath, input.pattern))
-                    continue;
-                if (matches.length === input.limit) {
-                    return { path: input.path, matches, truncated: true };
-                }
-                matches.push(outputPath(input.path, entry.relativePath));
-            }
-            return { path: input.path, matches, truncated: budget.exhausted };
+            return await searchPath(root, { kind: "glob", input }, scanBounds, context);
         },
         async grep(input, context) {
-            return await grepPath(root, input, context);
+            return await searchPath(root, { kind: "grep", input }, scanBounds, context);
         },
         async replace(input, context) {
             return await write(async () => {
@@ -432,6 +500,7 @@ export async function createPrivateInvocationFilesPort(path) {
                     throw new FilesEditError("file-too-large", input.path, `Result exceeds ${String(maximumFileBytes)} bytes; use files.patch for a small change`);
                 }
                 checkCancellation(context);
+                sandbox?.assertWrite(path.resolved);
                 await writeFileAtomic(path.resolved, input.content, {
                     encoding: "utf8",
                 });
@@ -439,7 +508,9 @@ export async function createPrivateInvocationFilesPort(path) {
             });
         },
     };
-    const patch = await createPrivateFilesPatch(root.canonicalPath, port.read);
+    // The native parser/patch engine still owns patch grammar. Its adapter must
+    // accept the launch callback too; never parse patch headers here.
+    const patch = await createPrivateFilesPatch(root.canonicalPath, port.read, sandbox?.launch);
     if (patch === undefined)
         return Object.freeze(port);
     return Object.freeze({