Sandbox on Lessons learned

FSKit after mount -F: "ls: fts_read: Operation not permitted"

Sat, 26 Sep 2026 16:30:00 +0200

My new FSKit filesystem mounted without complaint, but nothing inside it could be read:

$ ls -la ~/mnt/storage-test
ls: fts_read: Operation not permitted
total 0
$ cat ~/mnt/storage-test/sub/a.txt
cat: /Users/me/mnt/storage-test/sub/a.txt: Operation not permitted

stat on the mount point worked. If your FSKit extension does the same after a mount -F from the command line, check its sandbox before your code: the extension can see the source folder’s metadata but may not read its contents.

The setup

macOS 26, a file system extension built on FSKit’s FSUnaryFileSystem that exposes a local folder through a mount point
A small host app, StorageHost.app, in /Applications; its executable runs mount -F -t storagefs <source> <mount point>
The extension StorageFS.appex with the FSKit entitlement and the app sandbox
Info.plist with FSSupportsPathURLs set to true and FSRequiresSecurityScopedPathURLResources set to false

What went wrong

The first mount was over ~/Downloads, so the obvious suspect was privacy protection (TCC) for that folder. A fresh ~/storage-test with one file in it failed the same way, which ruled TCC out and pushed the search elsewhere.

My coding agent’s first log queries came back empty, and it told me there were no log entries. That was wrong. In zsh, log is a builtin, so log show ... 2>/dev/null runs the builtin, sends its too many arguments error to /dev/null, and prints nothing. Call /usr/bin/log by its full path. With that, the kernel had the answer:

kernel (Sandbox) 3 duplicate reports for Sandbox: StorageFS(83505) deny(1) file-read-data /Users/me/storage-test

The extension’s own log showed the failures from FSKit’s side: readDirectory:...reply:error:1 and readFrom:...reply:error:1. Error 1 is EPERM, which ls turns into fts_read: Operation not permitted.

Fix

mount -F gives the extension a plain path, not a security-scoped URL, so a sandboxed process can’t read an arbitrary path. For development, grant temporary sandbox exceptions in the extension’s .entitlements file:

<key>com.apple.security.temporary-exception.files.home-relative-path.read-write</key>
<array>
	<string>/</string>
</array>
<key>com.apple.security.temporary-exception.files.absolute-path.read-write</key>
<array>
	<string>/Volumes/</string>
</array>

This covers your home folder and external drives. It doesn’t override privacy protection, so ~/Downloads, ~/Documents, and ~/Desktop may still be refused; test with a folder elsewhere. Temporary exceptions are for development on your own machine. A shipping extension should use security-scoped resources instead. FSRequiresSecurityScopedPathURLResources in Info.plist requests that; I haven’t managed a clean test yet (see below).

The same logs flagged two more problems that I fixed along the way:

-[FSModuleVolume(Project) getMaxFileSizeInBits]: Volume implements neither maxFileSizeInBits nor maxFileSize. One of them must be implemented.
-[FSVolumeConnector getStandardItemAttributesForItem:replyHandler:]_block_invoke: Reported attributes are incomplete

The first needs maximumFileSizeInBits on the volume. The second went away once the item attributes set flags, which cleared the log entry.

Reinstalling switches the module off

To test each change, I replaced the app: rm -rf /Applications/StorageHost.app, copied the new build, and launched it once. After that, mount failed outright:

Module com.example.storage.fs is disabled!
mount: Unable to invoke task

pluginkit disagreed. pluginkit -e use -i com.example.storage.fs succeeded, and pluginkit -m listed the extension with a +, which means enabled. FSKit still refused. It keeps its own switch in System Settings → General → Login Items & Extensions → File System Extensions, and I didn’t find a command-line way to flip it. After I turned StorageFS back on there, the next mount listed and read files, and appends, renames, truncation, and an 8 MB write-and-readback all worked.

The disabled module also spoiled my one test of security-scoped resources. With FSRequiresSecurityScopedPathURLResources set to true, mount failed with Unable to invoke task, but the reinstall had just switched the module off, so the failure says nothing about the setting.

Why

An FSKit module is an app extension, and FSKit requires it to run in the app sandbox. When an app hands a folder to the extension, sandbox access can travel with it as a security-scoped URL. mount -F on the command line passes only a string. The sandbox lets the extension look up metadata for that path, which is why the mount and stat worked, and denies file-read-data, which every directory listing and file read needs.

Takeaway

If an FSKit mount works and every read returns Operation not permitted, search the kernel log for deny(1) file-read-data with /usr/bin/log, then give the extension sandbox access to the source path. After every reinstall, check the File System Extensions switch before you trust a test result.

If you’ve got FSRequiresSecurityScopedPathURLResources working with a command-line mount -F, I’d like to hear how.

Sandbox-blocked tests called "environmental", then committed

Mon, 13 Jul 2026 15:38:00 +0200

My coding agent finished a feature, ran the full test suite, and reported:

Full suite: 135 passed, 97 skipped; 22 DB suites failed due to no container runtime, plus sandboxed stub bind. Commit only handoff implementation files.

Then it committed. I ran pnpm test myself and got three real failures. The production build it had also skipped was broken too, and nobody found out for two months.

If your agent’s test run shows Error: Could not find a working container runtime strategy or Error: listen EPERM: operation not permitted 0.0.0.0:8080, those tests never ran, and a summary that counts them as “blocked” tells you nothing about the code.

The setup

Codex CLI on macOS, with its default sandbox
A pnpm monorepo: a Next.js 15.5.19 app plus a few packages
Vitest 2.1.9, with Testcontainers 10.28.0 starting Postgres for the database tests and a local stub of an external service listening on port 8080

The agent split the feature into five slices and gave each to a parallel subagent. Each subagent ran its own focused tests, and the orchestrator ran the full suite and the build at the end.

What went wrong

The sandbox blocks more than writes outside the project. Here it blocked three things the checks needed:

Testcontainers couldn’t reach Docker: Could not find a working container runtime strategy.
The service stub couldn’t bind its port: listen EPERM: operation not permitted 0.0.0.0:8080.
next build couldn’t write its compiler cache: EPERM writing ~/Library/Caches/next-swc.

Every database suite failed in beforeAll, and Vitest reported the tests inside them as skipped. The agent’s final report was accurate:

- Typecheck pass
- Focused tests pass
- Full: 135 passed; DB suites blocked by no Docker
- Build blocked by Next SWC cache permissions

Every line of that is true. But the suite has 232 tests, and 135 + 97 = 232: over 40 percent of it never ran, including every test that touched the database, where this feature did most of its work.

On the host, the same suite printed:

Test Files 2 failed | 63 passed (65)
 Tests 3 failed | 229 passed (232)

One new test forgot to start the service stub, so its client found no endpoint configured. Two older tests broke because the feature added an ownership check and their fixtures sent requests without a logged-in user (Error: authentication required). The agent fixed all three in two minutes once it saw them.

The build was worse. The commit re-exported a server action from another "use server" file:

"use server";

export { finalizeArtifact } from "../../reports/actions.ts";

tsc accepts this, and so do the tests. Only next build rejects it:

Failed to compile.

./app/reports/[id]/actions.ts
Error: x Only async functions are allowed to be exported in a "use server" file.

Two months later, a different session ran a production build, hit this error, and deleted the line.

The same sandbox, the same day

Half an hour before the bad commit, another session in the same repository hit the same two errors. At first it called them environmental too. Then it decided:

Full suite blocked by sandbox: Testcontainers cannot see Docker; stub bind gets `EPERM :8080`. Since Docker is reportedly running, retry full suite with host access.

Two minutes later it reported “Host rerun green: 60 files, 222 tests”, and only then did it commit. The agent that fixed my three failures did the same: it reran the focused tests with host approval before committing the fix. Both sessions knew how to leave the sandbox; nothing required them to before a commit.

Fix

Treat “blocked” as “not run”, and make “not run” stop the commit.

In Codex, a command runs outside the sandbox when the agent requests sandbox_permissions: "require_escalated" and you approve it. Put the rule in the instructions file the agent reads every session (AGENTS.md, or CLAUDE.md for Claude Code):

A check that the sandbox blocked has not passed. Before committing, rerun every blocked test suite and build with host access (`sandbox_permissions: "require_escalated"`).
If that isn't possible, don't commit: report what didn't run.

Then read the agent’s numbers yourself. If passed plus skipped equals the total, and you never skip tests on purpose, every skipped test is one that didn’t run. If you have CI, have it run the full suite and the build before a merge.

Why it happens

The agent’s memory for this project already had a rule: “separate passed static or focused checks from runtime suites blocked by the environment, and reserve the final green claim for integrated verification.” The agent followed that rule to the letter: it never claimed green and listed exactly what had been blocked. Then it committed, because nothing in its instructions tied the commit to the green claim.

“Blocked by the environment” reads like an infrastructure problem that someone else will handle, so it ends up as a footnote in the report while the commit goes ahead. The rule made the report honest. It didn’t make anyone run the tests.

Takeaway

When a sandbox blocks a test or a build, nothing was verified. An agent that reports this honestly will still commit, unless its instructions say that a blocked check stops the commit.

Look at your agent’s last commit: if its summary says a suite or a build was “blocked”, rerun them on the host today.