@redue/cli 0.1.0-alpha.27 → 0.1.0-alpha.28

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.1.0-alpha.28 — 2026-11-02
+
+Test suites can run in the sandbox, so REDUE can reuse a passing test run
+for more projects, Python included.
+
+- **Sandboxed tests.** A root test script that the direct test recipe does
+  not take, and pytest in a Python project's `.venv`, can now use the
+  sandboxed recipe. `init` keeps it only when the run in the sandbox gives the
+  same exit status and test counts as a plain run. On top of what a
+  typecheck or lint gets, a test run gets:
+  - **Loopback only.** It may listen on any address and connect to the local
+    host and Unix sockets, never to a remote host. On macOS, Seatbelt
+    enforces that. On Linux, a seccomp filter refuses UDP and other non-TCP
+    sockets, TCP Fast Open and `io_uring`, and hands each `connect` to
+    REDUE's launcher. The launcher allows a local port nothing listens on or
+    one the run's own processes listen on, and refuses everything else,
+    including a service you started outside the run (a local database). If
+    the launcher cannot start or stops early, the result is UNVERIFIED.
+  - **A private `/tmp`.** Its `TMPDIR` is new for each run, and it may not
+    write elsewhere in `/tmp` or `/var/tmp`.
+  - **A fresh home** for each run, as on CI.
+  - **Ignored files hidden** when the trial agrees, else the whole checkout.
+- **Measured.** In the product census, test suites with a qualifying check
+  (alpha.27 in brackets): TypeScript on Linux 11 (2), on macOS 12 (2);
+  Python on Linux 17 (0), on macOS 14 (0). The strace cross-check found no
+  read outside the recorded inputs. The Linux connect supervisor added at
+  most 1.5% over the sandbox without it on suites with worker processes
+  (pytest-xdist, Jest, Vitest): apprise 233 s to 237 s, run-to-run spread
+  218-243 s. In a pilot with Claude Code on two pytest projects, the hook
+  skipped both "do the tests still pass?" reruns (19 s to 6 s and 28 s to
+  7 s), and plain reruns agreed with both skips.
+- **macOS hides contents only.** On macOS, a hidden file's contents and
+  execution are refused, but its metadata is not, as on Linux. A test that
+  writes into an ignored folder works.
+- Known limits: a suite that reads back ignored files it writes in the same
+  run (a coverage database, a build it starts) gets the whole checkout, and
+  one that writes tracked files or coverage data during the run ends
+  UNVERIFIED. On Linux, a test that needs a service started outside the run
+  fails in the sandbox, so `init` leaves it to a plain run.
+
 ## 0.1.0-alpha.27 — 2026-11-01
 
 A build or test run no longer makes a sandboxed typecheck or lint STALE,

package/README.md

@@ -65,26 +65,47 @@ on your machine.
 
 To undo everything setup did: `redue remove`.
 
+## Still CURRENT after your build and tests
+
+Running the project's build or tests writes files (`dist/`, `.next/`,
+coverage). REDUE leaves those out when the files are git-ignored, so a
+typecheck or lint that passed stays CURRENT. In the census, after each
+project's own build, tests, typecheck and lint ran, the share of sandboxed
+checks still CURRENT:
+
+| | alpha.26 | alpha.27 |
+|---|---|---|
+| TypeScript, Linux | 5 of 43 | 31 of 37 |
+| TypeScript, macOS | 5 of 38 | 24 of 34 |
+| Python, Linux | 24 of 37 | 31 of 38 |
+| Python, macOS | 20 of 33 | 28 of 34 |
+
+The rest changed for real: the build rewrote a tracked file (a sitemap, a
+feed, a generated source), added a file git doesn't ignore, or installed
+packages.
+
 ## What it covers today
 
 In a census of 120 active public TypeScript repositories (November 2026, REDUE
-at commit e264a67, before 0.1.0-alpha.27), each installed as its users would,
-with dependencies' install scripts on, 90 installed cleanly on a macOS runner.
+at commit a2401cc, before 0.1.0-alpha.28), each installed as its users would,
+with dependencies' install scripts on, 89 installed cleanly on a macOS runner.
 A check counts when two recorded runs on the same code both came out CURRENT
-on the same inputs. 35 repositories had at least one such check:
+on the same inputs. 38 repositories had at least one such check:
 
 | Check | Repositories | How |
 |---|---|---|
-| Typecheck | 22 | 16 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)), 15 of them with the files git ignores hidden; 5 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)); 1 by running the script with every Node process recorded ([general recipe](docs/user/node-script.md)) |
-| Lint | 24 | 21 sandboxed recipe (19 with ignored files hidden), 3 general recipe |
-| Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+| Typecheck | 20 | 14 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)), 13 of them with the files git ignores hidden; 5 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)); 1 by running the script with every Node process recorded ([general recipe](docs/user/node-script.md)) |
+| Lint | 22 | 19 sandboxed recipe (18 with ignored files hidden), 3 general recipe |
+| Tests | 12 | 10 sandboxed recipe, with ignored files hidden and loopback-only network; 2 Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+
+In alpha.27 the same census found 2 repositories with a qualifying test check
+on macOS and on Linux; now 12 on macOS and 11 on Linux.
 
 In a census of 120 Python repositories, 74 installed on a Linux runner
-and 23 had a qualifying check: typecheck (mypy, pyright, ty) 15, lint (ruff)
-22, all through the sandboxed recipe with ignored files hidden. A check whose
-git-ignored files are hidden stays CURRENT when a build or test run rewrites
-them: after each project's build and tests ran, 31 of 37 such TypeScript
-checks and 31 of 38 Python checks were still CURRENT on Linux. On Linux, every sandboxed run was traced
+and 31 had a qualifying check: typecheck (mypy, pyright, ty) 15, lint (ruff)
+22, tests (pytest) 17, all through the sandboxed recipe (14 of the test
+suites with ignored files hidden, 3 with the whole checkout). In alpha.27, no
+Python test suite qualified. On Linux, every sandboxed run was traced
 with strace: each file it read in the checkout was a recorded input, a cache
 or its own output.
 

package/bin/redue.mjs

@@ -381,7 +381,7 @@ const checks=publicConfig.checks.map(check=>{
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
   const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):
-    sandboxed?sandboxEnvironment(Boolean(pythonTool(check)),check.script?manager:null):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+    sandboxed?sandboxEnvironment(Boolean(pythonTool(check)),check.script?manager:null,check.kind):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],

package/docs/user/node-script.md

@@ -8,8 +8,8 @@ pnpm and Yarn TypeScript recipes, the [direct test recipe](tests-direct.md)
 and, on macOS and Linux, the [sandboxed recipe](sandbox.md) first. It uses
 the general recipe for a root typecheck or lint script none of them takes,
 and where the sandbox cannot run (at init, or at run time inside Claude
-Code's macOS sandbox). Test scripts use the direct test recipe; `init` does
-not propose the general recipe for them.
+Code's macOS sandbox). Test scripts use the direct test recipe or the
+sandboxed recipe; `init` does not propose the general recipe for them.
 
 It supports a project installed by npm, pnpm 9-12 (isolated or hoisted
 `node_modules`) or Yarn with the `node-modules` linker, with one lockfile kind

package/docs/user/sandbox.md

@@ -1,11 +1,11 @@
-# Sandboxed recipe (typecheck and lint, any language)
+# Sandboxed recipe (typecheck, lint and tests, any language)
 
-The sandboxed recipe runs a typecheck or lint command inside an operating
+The sandboxed recipe runs a typecheck, lint or test command inside an operating
 system sandbox and reports later whether that result still applies to the
 files you have. The sandbox holds for every process the command starts, so it
 covers programs REDUE cannot record: TypeScript 7's native compiler, esbuild,
 oxlint and tsgolint, biome, turbo, and Python tools such as mypy, pyright, ty
-and ruff.
+and ruff, and test runners such as pytest.
 
 **The claim.** A sandboxed result holds for a run that sees only the project's
 files that git doesn't ignore, its installed packages and the toolchain, the
@@ -19,6 +19,8 @@ and the toolchain. See [files git ignores](#files-git-ignores).
 
 ## Where it applies
 
+- **Tests:** a root `test` script the [direct test recipe](tests-direct.md)
+  does not take, and pytest in the project's `.venv`. See [tests](#tests).
 - **Node projects:** a root `typecheck` or `lint` script (npm, pnpm, or Yarn
   with the `node-modules` linker). `init` tries the
   [direct TypeScript recipe](direct-typescript.md) and the pnpm and Yarn
@@ -96,7 +98,8 @@ It may read and execute only beneath:
   `/System`, `/Library`, `/opt/homebrew` and the like on macOS);
 - a private home directory and a fresh temporary directory, in REDUE's state.
 
-It has no network: no TCP connection, loopback included. On macOS its only
+A typecheck or lint has no network: no TCP connection, loopback included
+(a test run gets loopback; see [tests](#tests)). On macOS its only
 Unix sockets are in its own temporary directory, which is new for each run.
 On Linux 6.12 and later it cannot reach an abstract Unix socket outside the
 run.
@@ -124,6 +127,41 @@ It gets a controlled environment, not yours:
 - `HOME`, `TMPDIR` and the XDG directories in its private directories;
   `VIRTUAL_ENV` for a Python check; Corepack's home where Corepack keeps it.
 
+## Tests
+
+A test run gets what a typecheck or lint gets, and also:
+
+- **Loopback, and no remote host.** It may listen on any address and accept
+  connections, and connect only to the local host (`127.0.0.0/8`, `::1`,
+  `0.0.0.0`, `::`) and Unix sockets.
+  - On macOS, Seatbelt enforces that.
+  - On Linux, Landlock cannot tell a loopback address from a remote one, so a
+    seccomp filter in the test's processes does instead. It refuses sockets
+    other than Unix, netlink and TCP when they are created (UDP included),
+    TCP Fast Open (`MSG_FASTOPEN`) and `io_uring`. It hands each `connect` to
+    REDUE's launcher. The launcher allows a local port no process listens on
+    (the test gets "connection refused") or one the run's own processes
+    listen on, and a Unix socket file in the checkout, the run's home or its
+    temporary directory. It refuses a service started outside the run (your
+    local database) and every remote host. Nothing else goes through the
+    launcher, so worker processes talk to each other as usual. If the
+    launcher's supervisor cannot start, or stops before the run ends, the
+    result is UNVERIFIED, never CURRENT.
+- **A fresh home.** Its home directory is new and empty for each run, as on
+  CI: what a test leaves there is not observed, so it must not reach a later
+  run.
+- **A private `/tmp`.** Its `TMPDIR` is its own, new for each run, and it may
+  not write in `/tmp` or `/var/tmp` outside it. A test that writes to a fixed
+  path there is refused.
+
+`init` compares a test run's exit status and the counts its summary prints
+(passed, failed, skipped), not every line: test runners print in the order
+their workers finish. Git-ignored files are hidden from a test run when the
+trial agrees, as for typecheck and lint. A suite that reads back git-ignored
+files it writes in the same run (a coverage database, a build it starts
+itself) gets the whole checkout. Files a hidden run writes beneath hidden
+folders, or new files git ignores, are not changes to its inputs.
+
 ## What REDUE claims
 
 CURRENT means the last sandboxed run's inputs are unchanged:
@@ -166,7 +204,7 @@ every failure twice to find out:
 
 ## The private home
 
-The run's home directory is kept between runs, per check, so caches tools
+A typecheck or lint's home directory is kept between runs, per check, so caches tools
 build there (font caches, a type checker's cache) are not rebuilt every run.
 It starts empty: your configuration files are not in it. What a run leaves
 there can change a later run, and REDUE trusts it like a runner cache. Remove
@@ -201,14 +239,25 @@ it with `redue remove-state`.
 - A script that changes files (`--fix`, `--write`) does not get this recipe:
   `init` would run it twice.
 - With `sandbox-v2`, a run cannot read a hidden file, but it can still see
-  that one exists. On macOS it sees the names of hidden files and folders at
-  the level where they start (`dist` in the checkout's root). On Linux it can
-  also list a hidden folder and see its files' sizes and times: Landlock
-  restricts neither beneath a folder the run may list. A tool that acts on
+  that one exists, its size and its times, and write beneath it. On Linux it
+  can also list a hidden folder; on macOS it cannot. A tool that acts on
   whether a git-ignored file exists, without reading it, is not covered: a
-  new or removed one does not make the result STALE. Typecheckers and
-  linters read what they act on; a test that skips itself when a built file
-  is missing does not, which is why hidden files are not used for tests yet.
+  new or removed one does not make the result STALE. In a census of 136
+  test suites with ignored files after their build, none did.
+- On Linux, a test run's UDP is refused, loopback included: the filter
+  decides when the socket is made, before its address is known. On macOS UDP
+  to loopback works. A test that needs it fails its trial and keeps another
+  recipe.
+- On macOS, a test run can connect to a service on loopback that it did not
+  start (a local database on `127.0.0.1:5432`), and that service's state is
+  not observed: a change to it does not make the result STALE. On Linux the
+  launcher refuses it.
+- On Linux, the launcher decides a `connect` from the address it reads in
+  the process's memory, and the kernel reads it again after. A process that
+  changes the address in between, from another thread, could reach another
+  host. Honest test code does not.
+- On Linux, a typecheck or lint can still connect to a Unix socket file
+  outside it (a local database's).
 - On Linux, a file a `sandbox-v2` run creates in a folder that holds hidden
   files (the checkout's root, when anything in it is hidden) cannot be read
   back in the same run. `init`'s trial and the rerun without hiding catch a

package/docs/user/supported-projects.md

@@ -19,13 +19,14 @@ build scripts. It prefers familiar script names (for typecheck: `typecheck`,
 `tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
 matches are reported as ambiguous rather than guessed. It never creates a new
 project script. Without `--recipe`, `init` tries the strict recipes below first, then,
-for a root typecheck or lint script, the [sandboxed recipe](sandbox.md) on
+for a root typecheck, lint or test script, the [sandboxed recipe](sandbox.md) on
 macOS and Linux (the script run inside an OS sandbox, with the files git
 ignores hidden when it gives the same result that way, else on the whole
-checkout), then the [general recipe](node-script.md): the script run
+checkout; a test run also gets loopback-only network and a private `/tmp`),
+then, for typecheck and lint, the [general recipe](node-script.md): the script run
 through the package manager with every Node process recorded and the whole
 checkout as its input. Python projects get the sandboxed recipe for mypy,
-pyright, ty and ruff in their `.venv`. `--recipe typescript-direct`,
+pyright, ty, ruff and pytest in their `.venv`. `--recipe typescript-direct`,
 `tests-direct`, `node-script` or `sandbox` selects one recipe alone. The direct TypeScript recipe supports
 a typecheck script of `tsc --noEmit` runs in any argument order, chained runs,
 or no typecheck script at all (a proposed `tsc --noEmit`; see
@@ -56,7 +57,9 @@ typechecks, Vitest/Jest, ESLint, and builds in workspace packages start
 recording-only unless a separately justified explicit contract is provided.
 For a single-package project whose test script runs Vitest 4/5 or Jest 29
 directly, `init` uses the direct test recipe, which records the run and guards
-its inputs; see [direct tests](tests-direct.md).
+its inputs; see [direct tests](tests-direct.md). Other root test scripts get
+the sandboxed recipe when its trial gives the same exit status and test counts
+as a plain run.
 In particular, test caches and build-generated inputs are not excluded to
 make evidence green.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/claude-hook.mjs

@@ -27,7 +27,7 @@ const general=check=>(check?.qualification==='node-script-v1'&&['typecheck','tes
   sandboxed(check))&&typeof check.script==='string';
 // A sandboxed check: a root package script, or a tool from the project's .venv.
 // sandbox.mjs's isSandboxed, written out: the hook does not load the sandbox module.
-const sandboxed=check=>['sandbox-v1','sandbox-v2'].includes(check?.qualification)&&['typecheck','lint'].includes(check.kind);
+const sandboxed=check=>['sandbox-v1','sandbox-v2'].includes(check?.qualification)&&['typecheck','lint','test'].includes(check.kind);
 const python=check=>sandboxed(check)&&Array.isArray(check.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')&&
   check.command.every(word=>typeof word==='string'&&safe.test(word));
 const eligibleCheck=check=>typecheck(check)||tests(check)||general(check)||python(check);

package/src/cli.mjs

@@ -8,7 +8,7 @@ import {patternMatcher} from './glob.mjs';
 import {observedBy} from './installed-observation.mjs';
 import {changedFiles,coverageReadable,gitIgnored,recordedEnvironment,testEnvironmentIssue,testGuardConfig,testRunGuard,testRunFacts,sharedInstalledFile,testsInterpretation,testsQualification} from './test-direct.mjs';
 import {childProgram,generalIssue,lookup,pnpmConfigFiles,scriptCaches,scriptInstalledPaths,scriptInterpretation,scriptQualification,scriptRunFacts,pnpmNameless,toolOutput,toolchainDirs} from './node-script.mjs';
-import {denialLine,endWithChild,hiddenEntries,hiddenQualification,hiddenRefusal,isSandboxed,runToEnd,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,
+import {denialLine,endWithChild,hiddenEntries,hiddenQualification,hiddenRefusal,isSandboxed,runToEnd,supervisorIssue,visibleChange,testRun as sandboxTestRun,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,
   sandboxInterpretation,sandboxInterpretationOf,sandboxPlaces,sandboxQualification,sandboxSupport,systemPlaces} from './sandbox.mjs';
 import path from 'node:path';
 import net from 'node:net';
@@ -331,12 +331,21 @@ async function execute() {
       if(support.issue)captureIssues.push(`the run was not sandboxed: ${support.issue}`);
       else{
         const dirs=sandboxDirs(state,name);
+        // A test run: loopback networking, supervised on Linux (the launcher
+        // reports in REDUE's state, outside what the test may touch), a
+        // private /tmp, and a fresh home each run: what a test leaves in its
+        // home is not observed, so it must not reach a later run.
+        const tests=sandboxTestRun(selected),stats=tests&&support.mode==='landlock'?path.join(state,`launcher-${runId}.json`):null;
+        if(tests){dirs.home=path.join(dirs.tmp,'home');fs.mkdirSync(dirs.home,{mode:0o700});}
         const reads=[root,dirs.home,dirs.tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
         // sandbox-v2 hides the checkout's git-ignored entries. Where git
         // cannot list them, nothing is hidden, and the receipt compares every file.
         const hidden=selected.qualification===hiddenQualification?hiddenEntries(root):null;
-        sandbox={mode:support.mode,dirs,reads,hidden,argv:sandboxArgv(support.mode,command,{reads,tmp:dirs.tmp,python:support.python,
-          hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,'')))}),
+        const options={reads,tmp:dirs.tmp,python:support.python,stats,
+          ...tests?{network:'loopback',writes:[root,dirs.home,dirs.tmp],
+            fault:process.env.VSTATE_TEST_FAULTS==='1'?process.env.VSTATE_TEST_SUPERVISOR||null:null}:{}};
+        sandbox={mode:support.mode,dirs,reads,hidden,options,stats,
+          argv:sandboxArgv(support.mode,command,{...options,hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,'')))}),
           env:sandboxEnv(selected,process.env,{root,...dirs})};
       }
     }
@@ -481,6 +490,17 @@ async function execute() {
       unexplained=touched.filter(file=>!ignored.has(file));
       if(!unexplained.length){eventsExplained=true;if(changed.length)outputs=changed;}
     }
+    // A run that hid git-ignored files: what it wrote beneath them (test
+    // output, coverage data) is not a change to its inputs (visibleChange);
+    // anything else is named.
+    let hiddenOnly=false;
+    if(sandbox?.hidden&&snap&&end&&snap.planId===end.planId&&snap.observationHealthy&&end.observationHealthy&&
+      (snap.inputEventSerial===end.inputEventSerial||end.inputEventPathsComplete===true)){
+      const before=snap.files||{},after=end.files||{},events=end.inputEventPaths||[];
+      // During the run a new file outside the hidden entries was readable: it counts.
+      const found=visibleChange(root,sandbox.hidden,before,after,[...Object.keys(before),...Object.keys(after),...events],{during:true});
+      if(found===null){eventsExplained=true;hiddenOnly=true;}else unexplained=[found];
+    }
     // The end certificate, recorded or probed, must cover what this compile received.
     // With no input event, gap or content change in between, it also holds at the start.
     // A run checked by full probes is compared with it too, for its run facts.
@@ -519,7 +539,7 @@ async function execute() {
         `: ${named.slice(0,5).join(', ')}${more>0?` and ${more} more`:''}`:'')+unrecorded);
     }
     // A recorded certificate changes only the probe part of the fingerprint.
-    if(!outputs&&(!snap||!end||snap.planId!==end.planId||(recording?snap.inputKey!==end.inputKey:snap.fingerprint!==end.fingerprint)||
+    if(!outputs&&!hiddenOnly&&(!snap||!end||snap.planId!==end.planId||(recording?snap.inputKey!==end.inputKey:snap.fingerprint!==end.fingerprint)||
       snap.revision!==end.revision))captureIssues.push('declared inputs changed or were not observed');
     // A run that hid git-ignored files and failed with a refusal that names
     // one runs again in the sandbox without hiding them: the check needs
@@ -530,7 +550,7 @@ async function execute() {
       const line=hiddenRefusal(output.head+'\n'+output.tail,sandbox.hidden);
       if(line){
         console.error(`redue: the sandboxed run failed with what looks like a refusal of a file git ignores (${line}); running it again in the sandbox without hiding them`);
-        const again=await runToEnd(sandboxArgv(sandbox.mode,command,{reads:sandbox.reads,tmp:sandbox.dirs.tmp,python:support.python}),
+        const again=await runToEnd(sandboxArgv(sandbox.mode,command,sandbox.options),
           {cwd:plan.cwd,env:sandbox.env,echo:true,started:child=>{activeChild=child;}});
         activeChild=null;
         hiddenRerun={line,exitCode:again.status,signal:again.signal||null,...again.error?{errorCode:again.error.code||again.error.name}:{}};
@@ -586,6 +606,8 @@ async function execute() {
         }
       }
     }
+    // A test run whose network was not supervised throughout is not reused.
+    if(sandbox?.stats){const issue=supervisorIssue(sandbox.stats);if(issue)captureIssues.push(issue);fs.rmSync(sandbox.stats,{force:true});}
     if(sandbox)fs.rmSync(sandbox.dirs.tmp,{recursive:true,force:true});
     const stable=captureIssues.length===0;
     // Two runs on the same inputs, environment and plan that disagree make the

package/src/daemon.mjs

@@ -25,7 +25,7 @@ import {npmCacheDir} from './npm-integrity.mjs';
 import {runFromArgv} from './typescript-invocation.mjs';
 import {buildInfoPath,recordedCertificate} from './direct-run-certificate.mjs';
 import {timing,mark,traceBase,traceContext,traceScope,traceEnvironment,traceId} from './decision-profile.mjs';
-import {ignoredNow,isSandboxed,sandboxChange,trackedBeneath} from './sandbox.mjs';
+import {isSandboxed,sandboxChange,visibleChange as sandboxVisibleChange} from './sandbox.mjs';
 
 const configFile=path.resolve(process.argv[2]);
 const config=JSON.parse(fs.readFileSync(configFile));
@@ -348,38 +348,15 @@ function describeChangedInput(plan,file) {
     .map(mapping=>mapping.logical).slice(0,2);
   return file+' changed'+(matches.length?` (installed via ${matches.join(', ')})`:'');
 }
-// A run that hid the checkout's git-ignored entries (sandbox@2) did not see
-// them. A changed file the run saw always counts. A file beneath a hidden
-// entry counts only once git tracks it, and a new file only when git does
-// not list it as ignored now, as the next run's hidden entries would not.
-// Installed trees count whatever git says. The first changed input that
-// counts, or null; once per receipt and pair of fingerprints. When git
-// cannot tell, every change counts.
+// A run that hid the checkout's git-ignored entries (sandbox@2): the first
+// changed input it could see (sandbox.mjs's visibleChange), or null; once
+// per receipt and pair of fingerprints.
 const hiddenRun=r=>Array.isArray(r?.sandbox?.hidden)&&Boolean(r.files);
 function visibleChange(row,r,name) {
   const key=(r.invocation?.runId||'')+'\0'+r.fingerprint+'\0'+combinedSummary(name).fingerprint;
-  if(row.visibleKey===key)return row.visibleChange;
-  const hidden=r.sandbox.hidden.map(entry=>entry.replace(/\/$/,''));
-  const beneath=file=>hidden.some(entry=>file===entry||file.startsWith(entry+'/'));
-  const current=combinedFiles(name);
-  const changed=[...new Set([...Object.keys(r.files),...Object.keys(current)])].filter(file=>r.files[file]!==current[file]).sort();
-  const seen=changed.filter(file=>file in r.files&&!beneath(file));
-  const covered=changed.filter(file=>beneath(file)),fresh=changed.filter(file=>!(file in r.files)&&!beneath(file));
-  let found=seen[0]??null;
-  if(!found&&covered.length){
-    const tracked=trackedBeneath(root,hidden.filter(entry=>covered.some(file=>file===entry||file.startsWith(entry+'/'))));
-    found=covered.find(file=>!tracked||tracked.has(file))??null;
-  }
-  if(!found&&fresh.length){
-    // Ask once per directory the run had no file in, then the files outside one.
-    const before=new Set(Object.keys(r.files).flatMap(file=>file.split('/').slice(0,-1).map((_,i,parts)=>parts.slice(0,i+1).join('/'))));
-    const newDir=file=>{const parts=file.split('/');for(let i=1;i<parts.length;i++){const dir=parts.slice(0,i).join('/');if(!before.has(dir))return dir+'/';}return null;};
-    const asked=[...new Set(fresh.filter(file=>!file.startsWith('external:')).map(file=>newDir(file)??file))];
-    const ignored=ignoredNow(root,asked);
-    found=fresh.find(file=>file.startsWith('external:')||!ignored||!ignored.has(file))??null;
-  }
-  row.visibleKey=key;row.visibleChange=found;
-  return found;
+  if(row.visibleKey!==key){const current=combinedFiles(name);
+    row.visibleKey=key;row.visibleChange=sandboxVisibleChange(root,r.sandbox.hidden,r.files,current,[...Object.keys(r.files),...Object.keys(current)]);}
+  return row.visibleChange;
 }
 function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=false) {
   if(!index)return [];
@@ -433,7 +410,7 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
       item.reason='target failure conflicts with outer invocation outcome';return item;}
     if(!r.stable){const issues=r.checkpoint?.issues?.length?` (${r.checkpoint.issues.join('; ')})`:'';
       // A sandboxed run that could not start, whose result the sandbox changed, or whose rerun outside it did not finish, says so alone.
-      const sandbox=r.checkpoint?.issues?.length&&r.checkpoint.issues.every(issue=>/^the (?:sandbox changed|run was not sandboxed|run outside the sandbox)/.test(issue));
+      const sandbox=r.checkpoint?.issues?.length&&r.checkpoint.issues.every(issue=>/^the (?:sandbox changed|run was not sandboxed|run outside the sandbox|network supervisor)/.test(issue));
       item.reason=sandbox?r.checkpoint.issues.join('; '):`inputs changed during execution or observation gap${issues}`;return item;}
     const names=[...(row.plan.environment.variables||[]),
       ...(row.plan.environment.prefixes||[]).map(prefix=>

package/src/landlock.py

@@ -6,13 +6,31 @@
 # connection to an abstract Unix socket outside the run. Writes are not
 # handled, so they are not restricted.
 #
+# --loopback (a test run) leaves TCP to a seccomp filter in the command's
+# process instead. Sockets other than Unix, netlink and inet TCP streams are
+# refused when they are created, and so are sendto, sendmsg and sendmmsg with
+# MSG_FASTOPEN (a connect without connect), io_uring_setup, and any foreign
+# architecture's or x32 system call. Every connect goes to the launcher
+# (seccomp user notification). It lets through AF_UNSPEC, an unnamed or
+# abstract Unix socket, a Unix socket file beneath a --write place, and the
+# local host (loopback, 0.0.0.0, ::) on a port no process listens on or one
+# of the run's own processes listens on: not a service started outside the
+# run. It refuses the rest. Nothing else goes through the launcher, so worker
+# processes' IPC is untouched; bind is allowed anywhere.
+#
+# --deny-write PATH (a test run's /tmp and /var/tmp) handles writes too: they
+# are allowed everywhere but beneath those paths, and beneath each --write
+# PATH (the run's own temporary directory).
+#
 # --hide PATH keeps the run from reading or executing beneath PATH, inside a
 # --read place. Landlock only grants, beneath a whole directory, so such a
 # place gets listing rights (beneath it all, hidden entries included) and
 # read and execute rights on each of its entries that is not hidden and
 # holds nothing hidden, descending into the ones that do. A hidden path can
 # still be listed and stat'ed. --stats FILE writes the rule count and the
-# time the rules took, as JSON.
+# time the rules took, as JSON; with --loopback, rewritten when the command
+# ends with `supervisor`: "ok" when it served the whole run, else what went
+# wrong. A missing or other value means the network was not supervised.
 #
 # The launcher stays as the command's parent and a child subreaper: when the
 # command exits, it stops every process the command left running, daemons
@@ -21,23 +39,240 @@
 # launcher gets is passed to that group once. The launcher then ends as the
 # command did: with its exit status, or by its signal.
 #
-#   landlock.py --read /usr --read /tmp ... [--hide P ...] [--stats F] [--no-tcp] -- cmd args...
+#   landlock.py --read /usr --read /tmp ... [--hide P ...] [--stats F] [--no-tcp | --loopback]
+#               [--deny-write P ... --write P ...] -- cmd args...
 #   landlock.py --probe     # prints {"abi": N} or {"abi": null, "errno": E}
 import ctypes
+import errno
 import json
 import os
+import select
 import signal
+import socket
 import sys
+import threading
 import time
 
 SYS_CREATE, SYS_ADD, SYS_RESTRICT = 444, 445, 446  # the same on x86_64 and aarch64
 EXECUTE, READ_FILE, READ_DIR = 1 << 0, 1 << 2, 1 << 3
+# Writing, making and removing files, renaming across directories (ABI 2), truncating (ABI 3).
+WRITE = sum(1 << bit for bit in (1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14))
 BIND_TCP, CONNECT_TCP = 1 << 0, 1 << 1
 SCOPE_ABSTRACT_UNIX_SOCKET = 1 << 0
 PR_SET_NO_NEW_PRIVS, PR_SET_CHILD_SUBREAPER = 38, 36
 
 libc = ctypes.CDLL(None, use_errno=True)
 libc.syscall.restype = ctypes.c_long
+libc.ioctl.argtypes = [ctypes.c_int, ctypes.c_ulong, ctypes.c_void_p]
+
+# The seccomp filter --loopback installs, per architecture: its audit value
+# and the system calls it looks at.
+ARCH = {'x86_64': (0xC000003E, {'socket': 41, 'connect': 42, 'sendto': 44, 'sendmsg': 46, 'sendmmsg': 307,
+                                'io_uring_setup': 425, 'seccomp': 317}),
+        'aarch64': (0xC00000B7, {'socket': 198, 'connect': 203, 'sendto': 206, 'sendmsg': 211, 'sendmmsg': 269,
+                                 'io_uring_setup': 425, 'seccomp': 277})}
+AF_UNSPEC, AF_UNIX, AF_INET, AF_INET6, AF_NETLINK = 0, 1, 2, 10, 16
+SOCK_STREAM, IPPROTO_TCP, IPPROTO_MPTCP, MSG_FASTOPEN = 1, 6, 262, 0x20000000
+RET_ALLOW, RET_NOTIFY, RET_ERRNO = 0x7fff0000, 0x7fc00000, 0x00050000
+LD, JEQ, JGE, JSET, AND, RET = 0x20, 0x15, 0x35, 0x45, 0x54, 0x06
+SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, SECCOMP_USER_NOTIF_FLAG_CONTINUE = 1, 1 << 3, 1
+NOTIF_RECV, NOTIF_SEND, NOTIF_ID_VALID, NOTIF_ID_VALID_OLD = 0xc0502100, 0xc0182101, 0x40082102, 0x80082102
+
+
+class SockFilter(ctypes.Structure):
+    _fields_ = [('code', ctypes.c_uint16), ('jt', ctypes.c_uint8), ('jf', ctypes.c_uint8), ('k', ctypes.c_uint32)]
+
+
+class SockFprog(ctypes.Structure):
+    _fields_ = [('len', ctypes.c_ushort), ('filter', ctypes.POINTER(SockFilter))]
+
+
+class SeccompData(ctypes.Structure):
+    _fields_ = [('nr', ctypes.c_int), ('arch', ctypes.c_uint32), ('ip', ctypes.c_uint64), ('args', ctypes.c_uint64 * 6)]
+
+
+class Notif(ctypes.Structure):
+    _fields_ = [('id', ctypes.c_uint64), ('pid', ctypes.c_uint32), ('flags', ctypes.c_uint32), ('data', SeccompData)]
+
+
+class NotifResp(ctypes.Structure):
+    _fields_ = [('id', ctypes.c_uint64), ('val', ctypes.c_int64), ('error', ctypes.c_int32), ('flags', ctypes.c_uint32)]
+
+
+def filter_program(machine):
+    # Little-endian: an argument's low 32 bits are at 16 + 8 * index.
+    audit, nr = ARCH[machine]
+    program, labels = [], {}
+    def op(code, k, jt=None, jf=None):
+        program.append([code, jt, jf, k])
+    def label(name):
+        labels[name] = len(program)
+    op(LD, 4); op(JEQ, audit, None, 'deny')
+    op(LD, 0)
+    if machine == 'x86_64':
+        op(JGE, 0x40000000, 'deny')
+    op(JEQ, nr['connect'], 'notify'); op(JEQ, nr['io_uring_setup'], 'deny'); op(JEQ, nr['socket'], 'socket')
+    op(JEQ, nr['sendto'], 'flags3'); op(JEQ, nr['sendmmsg'], 'flags3'); op(JEQ, nr['sendmsg'], 'flags2')
+    op(RET, RET_ALLOW)
+    # Unix and netlink sockets; inet only as TCP (or MPTCP) streams, which reach a host through connect alone.
+    label('socket'); op(LD, 16)
+    op(JEQ, AF_UNIX, 'allow'); op(JEQ, AF_NETLINK, 'allow'); op(JEQ, AF_INET, 'inet'); op(JEQ, AF_INET6, 'inet'); op(RET, RET_ERRNO | errno.EPERM)
+    label('inet'); op(LD, 24); op(AND, 0xf); op(JEQ, SOCK_STREAM, 'protocol', 'deny')
+    label('protocol'); op(LD, 32); op(JEQ, 0, 'allow'); op(JEQ, IPPROTO_TCP, 'allow'); op(JEQ, IPPROTO_MPTCP, 'allow', 'deny')
+    label('flags3'); op(LD, 16 + 8 * 3); op(JSET, MSG_FASTOPEN, 'deny', 'allow')
+    label('flags2'); op(LD, 16 + 8 * 2); op(JSET, MSG_FASTOPEN, 'deny', 'allow')
+    label('allow'); op(RET, RET_ALLOW)
+    label('notify'); op(RET, RET_NOTIFY)
+    label('deny'); op(RET, RET_ERRNO | errno.EPERM)
+    jump = lambda at, name: labels[name] - at - 1 if name else 0
+    return [SockFilter(code, jump(at, jt), jump(at, jf), k) for at, (code, jt, jf, k) in enumerate(program)]
+
+
+# In the command's process, before exec: the filter, and its listener for the launcher.
+def install_filter():
+    machine = os.uname().machine
+    if machine not in ARCH:
+        raise OSError(f'no seccomp filter for {machine}')
+    program = filter_program(machine)
+    buffer = (SockFilter * len(program))(*program)
+    fprog = SockFprog(len(program), ctypes.cast(buffer, ctypes.POINTER(SockFilter)))
+    fd = libc.syscall(ARCH[machine][1]['seccomp'], SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, ctypes.byref(fprog))
+    if fd < 0:
+        raise OSError(ctypes.get_errno(), f'seccomp: {os.strerror(ctypes.get_errno())}')
+    return fd
+
+
+# The run's processes: the launcher's descendants (it is their subreaper).
+def run_processes(launcher):
+    parents = {}
+    for entry in os.listdir('/proc'):
+        if entry.isdigit():
+            try:
+                with open(f'/proc/{entry}/stat') as f:
+                    stat = f.read()
+                parents[int(entry)] = int(stat[stat.rindex(')') + 2:].split()[1])
+            except (OSError, ValueError, IndexError):
+                pass
+    def descends(pid, seen=0):
+        while pid in parents and seen < 64:
+            pid, seen = parents[pid], seen + 1
+            if pid == launcher:
+                return True
+        return False
+    return [pid for pid in parents if descends(pid)]
+
+
+# Who listens on a local TCP port: None when nobody does, else whether one of
+# the run's processes does.
+def listener_in_run(port, launcher):
+    inodes = set()
+    for table in ('/proc/net/tcp', '/proc/net/tcp6'):
+        try:
+            with open(table) as f:
+                rows = f.read().splitlines()[1:]
+        except OSError:
+            continue
+        for row in rows:
+            fields = row.split()
+            if len(fields) > 9 and fields[3] == '0A' and int(fields[1].rsplit(':', 1)[1], 16) == port:
+                inodes.add(fields[9])
+    if not inodes:
+        return None
+    links = {f'socket:[{inode}]' for inode in inodes}
+    for pid in run_processes(launcher):
+        try:
+            for fd in os.listdir(f'/proc/{pid}/fd'):
+                try:
+                    if os.readlink(f'/proc/{pid}/fd/{fd}') in links:
+                        return True
+                except OSError:
+                    pass
+        except OSError:
+            pass
+    return False
+
+
+# Whether a process may connect to the address it names (see --loopback).
+def connect_allowed(pid, address, length, places, launcher, ports):
+    if not address or length < 2:
+        return False
+    try:
+        fd = os.open(f'/proc/{pid}/mem', os.O_RDONLY | os.O_CLOEXEC)
+        try:
+            raw = os.pread(fd, min(length, 128), address)
+        finally:
+            os.close(fd)
+    except OSError:
+        return False
+    family = int.from_bytes(raw[:2], sys.byteorder)
+    if family == AF_UNSPEC:
+        return True
+    if family == AF_UNIX:
+        name = raw[2:].split(b'\0', 1)[0] if len(raw) > 2 and raw[2] != 0 else b''
+        if not name:
+            return True
+        try:
+            target = os.path.realpath(os.path.join(os.readlink(f'/proc/{pid}/cwd'), os.fsdecode(name)))
+        except OSError:
+            return False
+        return any(target == place or target.startswith(place.rstrip('/') + '/') for place in places)
+    if family == AF_INET and len(raw) >= 8:
+        local = raw[4] == 127 or raw[4:8] == bytes(4)
+    elif family == AF_INET6 and len(raw) >= 24:
+        host = raw[8:24]
+        mapped = host[:12] == bytes(10) + b'\xff\xff'
+        local = host in (bytes(15) + b'\x01', bytes(16)) or mapped and (host[12] == 127 or host[12:] == bytes(4))
+    else:
+        return False
+    if not local:
+        return False
+    port = int.from_bytes(raw[2:4], 'big')
+    if port in ports:
+        return True
+    owner = listener_in_run(port, launcher)
+    if owner:
+        ports.add(port)
+    return owner is not False
+
+
+# The launcher's side: every connect the command's processes make, until none is left.
+def supervise(fd, state, places, die=False):
+    def valid(id):
+        value = ctypes.c_uint64(id)
+        if libc.ioctl(fd, NOTIF_ID_VALID, ctypes.byref(value)) == 0:
+            return True
+        return ctypes.get_errno() in (errno.EINVAL, errno.ENOTTY) and libc.ioctl(fd, NOTIF_ID_VALID_OLD, ctypes.byref(value)) == 0
+    launcher, ports = os.getpid(), set()
+    places = [os.path.realpath(place) for place in places]
+    try:
+        poller = select.poll()
+        poller.register(fd, select.POLLIN)
+        while True:
+            events = dict(poller.poll())
+            if events.get(fd, 0) & select.POLLIN == 0:
+                break
+            notif = Notif()
+            if libc.ioctl(fd, NOTIF_RECV, ctypes.byref(notif)) < 0:
+                if ctypes.get_errno() in (errno.EINTR, errno.ENOENT):
+                    continue
+                raise OSError(ctypes.get_errno(), 'receive')
+            if die:
+                raise RuntimeError('test fault')
+            allowed = connect_allowed(notif.pid, notif.data.args[1], notif.data.args[2], places, launcher, ports)
+            state['connects'] = state.get('connects', 0) + 1
+            if not valid(notif.id):
+                continue
+            response = NotifResp(notif.id, 0, 0 if allowed else -errno.EPERM, SECCOMP_USER_NOTIF_FLAG_CONTINUE if allowed else 0)
+            if libc.ioctl(fd, NOTIF_SEND, ctypes.byref(response)) < 0 and ctypes.get_errno() != errno.ENOENT:
+                raise OSError(ctypes.get_errno(), 'respond')
+        state['supervisor'] = 'ok'
+    except Exception as e:
+        state['supervisor'] = f'failed: {e}'
+        # A closed listener makes every later connect fail (ENOSYS).
+        try:
+            os.close(fd)
+        except OSError:
+            pass
 
 
 class RulesetAttr(ctypes.Structure):
@@ -61,10 +296,19 @@ def main(argv):
         v, err = abi()
         print(json.dumps({'abi': v, 'errno': err}))
         return 0
-    reads, hidden, stats, no_tcp = [], set(), None, False
+    reads, hidden, stats, no_tcp, loopback, deny_write, writes, fault = [], set(), None, False, False, set(), [], None
     while argv and argv[0] != '--':
         if argv[0] == '--read':
             reads.append(argv[1]); argv = argv[2:]
+        elif argv[0] == '--loopback':
+            loopback = True; argv = argv[1:]
+        elif argv[0] == '--deny-write':
+            deny_write.add(os.path.normpath(argv[1])); argv = argv[2:]
+        elif argv[0] == '--write':
+            writes.append(argv[1]); argv = argv[2:]
+        elif argv[0] == '--test-fault':
+            # Tests only: the supervisor cannot start (unavailable) or stops at the first connect (die).
+            fault = argv[1]; argv = argv[2:]
         elif argv[0] == '--hide':
             hidden.add(os.path.normpath(argv[1])); argv = argv[2:]
         elif argv[0] == '--stats':
@@ -77,9 +321,10 @@ def main(argv):
     version, err = abi()
     if version is None:
         sys.exit(f'landlock.py: Landlock unavailable (errno {err})')
-    handled = EXECUTE | READ_FILE | READ_DIR
+    reading = EXECUTE | READ_FILE | READ_DIR
+    handled = reading | (WRITE if deny_write else 0)
     attr = RulesetAttr(handled, (BIND_TCP | CONNECT_TCP) if no_tcp and version >= 4 else 0,
-                       SCOPE_ABSTRACT_UNIX_SOCKET if no_tcp and version >= 6 else 0)
+                       SCOPE_ABSTRACT_UNIX_SOCKET if (no_tcp or loopback) and version >= 6 else 0)
     size = 24 if attr.scoped else 16 if attr.net else 8
     ruleset = libc.syscall(SYS_CREATE, ctypes.byref(attr), ctypes.c_size_t(size), ctypes.c_uint32(0))
     if ruleset < 0:
@@ -93,50 +338,84 @@ def main(argv):
             return
         # A file takes file rights only.
         if rights is None:
-            rights = handled if os.path.isdir(place) else EXECUTE | READ_FILE
+            rights = reading if os.path.isdir(place) else EXECUTE | READ_FILE
+        if not os.path.isdir(place):
+            rights &= EXECUTE | READ_FILE | (1 << 1) | (1 << 14)
         rule = PathBeneath(rights, fd)
         if libc.syscall(SYS_ADD, ctypes.c_int(ruleset), ctypes.c_int(1), ctypes.byref(rule), ctypes.c_uint32(0)) < 0:
             sys.exit(f'landlock.py: add_rule {place} errno {ctypes.get_errno()}')
         os.close(fd)
         count += 1
-    # The directories that hold a hidden path, up to the root.
-    holders = set()
-    for path in hidden:
-        at = os.path.dirname(path)
-        while at not in holders and at != os.path.dirname(at):
-            holders.add(at); at = os.path.dirname(at)
-    def grant(directory):
+    # The directories that hold an excluded path, up to the root.
+    def holders_of(excluded):
+        holders = set()
+        for path in excluded:
+            at = os.path.dirname(path)
+            while at not in holders and at != os.path.dirname(at):
+                holders.add(at); at = os.path.dirname(at)
+        return holders
+    # `rights` on every entry beneath `directory` but the excluded ones.
+    def grant(directory, excluded, holders, rights):
         # Links are not followed: what they lead to is granted on its own or not at all.
         try:
             entries = list(os.scandir(directory))
         except OSError:
             return
         for entry in entries:
-            if entry.path in hidden or entry.is_symlink():
+            if entry.path in excluded or entry.is_symlink():
                 continue
             if entry.path in holders:
-                grant(entry.path)
+                grant(entry.path, excluded, holders, rights)
             else:
-                add(entry.path)
+                add(entry.path, rights)
+    holders = holders_of(hidden)
     for place in reads:
         place = os.path.normpath(place)
         if place in holders and os.path.isdir(place):
             add(place, READ_DIR)
-            grant(place)
+            grant(place, hidden, holders, reading)
         else:
             add(place)
-    if stats:
-        with open(stats, 'w') as f:
-            json.dump({'rules': count, 'ms': round((time.monotonic() - started) * 1000, 1)}, f)
+    if deny_write:
+        grant('/', deny_write, holders_of(deny_write), WRITE)
+        for place in writes:
+            add(place, WRITE)
+    state = {'rules': count, 'ms': round((time.monotonic() - started) * 1000, 1)}
+    # Opened before the ruleset applies, so a write rule cannot refuse it later; not inherited.
+    stats_fd = os.open(stats, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_CLOEXEC, 0o600) if stats else None
+    def report():
+        if stats_fd is not None:
+            data = json.dumps(state).encode()
+            os.ftruncate(stats_fd, 0)
+            os.pwrite(stats_fd, data, 0)
+    report()
     if libc.prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0:
         sys.exit(f'landlock.py: no_new_privs errno {ctypes.get_errno()}')
     if libc.syscall(SYS_RESTRICT, ctypes.c_int(ruleset), ctypes.c_uint32(0)) < 0:
         sys.exit(f'landlock.py: restrict_self errno {ctypes.get_errno()}')
     os.close(ruleset)
     libc.prctl(PR_SET_CHILD_SUBREAPER, 1, 0, 0, 0)
+    # The command's process sends its filter's listener back over this pair.
+    if loopback:
+        state['supervisor'] = 'not started'
+        report()
+        parent_end, child_end = socket.socketpair()
     pid = os.fork()
     if pid == 0:
         os.setpgid(0, 0)
+        if loopback:
+            parent_end.close()
+            try:
+                if fault == 'unavailable':
+                    raise OSError('test fault')
+                listener = install_filter()
+                socket.send_fds(child_end, [b'x'], [listener])
+                os.close(listener)
+                child_end.close()
+            except OSError as e:
+                # Never run the command unsupervised.
+                sys.stderr.write(f'landlock.py: network supervisor unavailable: {e}\n')
+                os._exit(125)
         try:
             os.execvp(cmd[0], cmd)
         except OSError as e:
@@ -154,8 +433,28 @@ def main(argv):
             pass
     for number in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
         signal.signal(number, forward)
+    supervisor = None
+    if loopback:
+        child_end.close()
+        try:
+            _, fds, _, _ = socket.recv_fds(parent_end, 1, 1)
+        except OSError:
+            fds = []
+        parent_end.close()
+        if fds:
+            state['supervisor'] = 'running'
+            supervisor = threading.Thread(target=supervise, args=(fds[0], state, writes, fault == 'die'), daemon=True)
+            supervisor.start()
+        else:
+            state['supervisor'] = 'unavailable'
     _, status = os.waitpid(pid, 0)
     stop_left()
+    # Every filtered process is gone: the supervisor sees its listener hang up.
+    if supervisor:
+        supervisor.join(5)
+        if supervisor.is_alive():
+            state['supervisor'] = 'did not end with the command'
+    report()
     code = os.waitstatus_to_exitcode(status)
     if code >= 0:
         return code

package/src/python-onboarding.mjs

@@ -1,10 +1,10 @@
-// Python projects for `redue init`: typecheck and lint checks that run mypy,
-// pyright, ty or ruff from the project's .venv under the sandboxed recipe
+// Python projects for `redue init`: typecheck, lint and test checks that run
+// mypy, pyright, ty, ruff or pytest from the project's .venv under the sandboxed recipe
 // (sandbox.mjs). A tool is proposed when it is installed in .venv/bin. Its
 // arguments are the ones the project runs it with, read from CI workflows,
 // the Makefile, tox, nox, a justfile and shell scripts; without one, the
-// tool's own default (`ruff check`, `ty check`, `pyright`, and `mypy` with
-// its configured files or `.`).
+// tool's own default (`ruff check`, `ty check`, `pyright`, `pytest`, and
+// `mypy` with its configured files or `.`).
 import fs from 'node:fs';
 import path from 'node:path';
 import {realObservedPath} from './path-identity.mjs';
@@ -15,7 +15,7 @@ const exists=file=>{try{fs.lstatSync(file);return true;}catch{return false;}};
 const executable=file=>{try{fs.accessSync(file,fs.constants.X_OK);return fs.statSync(file).isFile();}catch{return false;}};
 // Each tool, its kind, and the subcommand it runs as a check.
 export const pythonTools=[{tool:'mypy',kind:'typecheck',sub:[]},{tool:'pyright',kind:'typecheck',sub:[]},
-  {tool:'ty',kind:'typecheck',sub:['check']},{tool:'ruff',kind:'lint',sub:['check']}];
+  {tool:'ty',kind:'typecheck',sub:['check']},{tool:'ruff',kind:'lint',sub:['check']},{tool:'pytest',kind:'test',sub:[]}];
 // The text of a TOML or INI section, up to the next section header.
 const section=(text,header)=>{const at=text.split(/\r?\n/).findIndex(line=>line.trim()===header);
   if(at<0)return null;const rest=text.split(/\r?\n/).slice(at+1);const end=rest.findIndex(line=>/^\s*\[/.test(line));
@@ -27,7 +27,9 @@ const wrappers=[/^uv run(?: --(?:frozen|locked|no-sync|offline|quiet|all-extras|
   /^\$\{?[A-Za-z_]+\}?(?=[A-Za-z])/];
 // A tool's arguments in one line of a script or workflow, or null. The line
 // must run the tool and its subcommand plainly; arguments with shell syntax,
-// or ones that change files or install packages, are not taken.
+// ones that change files or install packages, and pytest's that run a set
+// chosen from its cache (--lf, --ff, --sw, --nf), show the cache, loop
+// (-f), rewrite snapshots or add to earlier coverage data, are not taken.
 export function toolArgs(line,{tool,sub}){
   let text=line.trim().replace(/^-\s+/,'').replace(/^run:\s*/,'').replace(/^[@-]+/,'');
   text=text.split(/\s(?:&&|\|\||;|\|)\s/)[0].replace(/\s+/g,' ').trim();
@@ -35,7 +37,7 @@ export function toolArgs(line,{tool,sub}){
   const words=text.split(' ');
   if(words[0]!==tool||JSON.stringify(words.slice(1,1+sub.length))!==JSON.stringify(sub))return null;
   const args=words.slice(1+sub.length);
-  if(args.some(arg=>!/^[A-Za-z0-9_./:=,@+%-]+$/.test(arg)||/^--(?:fix|unsafe-fixes|write|install-types|watch)(?:=|$)/.test(arg)||arg.startsWith('..')||arg.startsWith('/')))return null;
+  if(args.some(arg=>!/^[A-Za-z0-9_./:=,@+%-]+$/.test(arg)||/^--(?:fix|unsafe-fixes|write|install-types|watch|lf|last-failed|ff|failed-first|sw|sw-skip|sw-reset|stepwise|stepwise-skip|stepwise-reset|nf|new-first|cache-show|looponfail|snapshot-update|update-snapshots|inline-snapshot|cov-append)(?:=|$)/.test(arg)||arg==='-f'||arg.startsWith('..')||arg.startsWith('/')))return null;
   return args;
 }
 // The places a project writes how it runs its tools, in order of preference.

package/src/sandbox.mjs

@@ -31,7 +31,10 @@ export const hiddenInterpretation='sandbox@2';
 export const hiddenListIssue='git cannot list the ignored files';
 export const isSandboxed=qualification=>qualification===sandboxQualification||qualification===hiddenQualification;
 export const sandboxInterpretationOf=qualification=>qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation;
-export const sandboxKinds=['typecheck','lint'];
+export const sandboxKinds=['typecheck','lint','test'];
+// A test run gets loopback networking and a private /tmp (sandboxArgv's
+// `network` and `writes`); a typecheck or lint gets no network.
+export const testRun=check=>check?.kind==='test';
 const fail=code=>{throw Object.assign(Error(code),{code});};
 const digest=value=>createHash('sha256').update(value).digest('hex');
 const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
@@ -62,10 +65,12 @@ export const pythonTool=check=>Array.isArray(check?.command)&&/^\.venv\/bin\/[A-
 // script check names its package manager first among the executables, as the
 // general recipe does.
 const managers=['npm','pnpm','yarn','corepack'];
-export function sandboxEnvironment(python=false,manager=null){
+export function sandboxEnvironment(python=false,manager=null,kind=null){
   return {variables:['TZ','LANG','LANGUAGE','CI','USER','LOGNAME'],
     prefixes:['LC_','DYLD_','LD_',...python?['PYTHON','MYPY','RUFF_','PYRIGHT','TY_']:
-      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_']],
+      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_'],
+      // A test runner's own variables.
+      ...kind==='test'?python?['PYTEST_']:['VITEST_','JEST_']:[]],
     ...manager?{pathExecutables:['node',manager,...managers.filter(name=>name!==manager)]}:{}};
 }
 
@@ -273,6 +278,34 @@ export function trackedBeneath(root,entries){
     {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
   return r.status===0?new Set(r.stdout.split('\0').filter(Boolean)):null;
 }
+// For a run that hid `hidden` (relative entries), the first path of `paths`
+// that changes its inputs, between `before` and `current` ({rel: identity}),
+// or null. A file the run saw always counts. A file beneath a hidden entry
+// counts only once git tracks it, and a new file only when git does not list
+// it as ignored now, as the next run's hidden entries would not. When git
+// cannot tell, every change counts. `external:` paths always count. With
+// `during` (changes while the run ran), a new file outside the hidden
+// entries counts too: the run could read it.
+export function visibleChange(root,hidden,before,current,paths,{during=false}={}){
+  const entries=hidden.map(entry=>entry.replace(/\/$/,''));
+  const beneath=file=>entries.some(entry=>file===entry||file.startsWith(entry+'/'));
+  const changed=[...new Set(paths)].filter(file=>before[file]!==current[file]).sort();
+  const seen=changed.filter(file=>file in before&&!beneath(file));
+  if(seen.length)return seen[0];
+  const covered=changed.filter(beneath),fresh=changed.filter(file=>!(file in before)&&!beneath(file));
+  if(covered.length){
+    const tracked=trackedBeneath(root,entries.filter(entry=>covered.some(file=>file===entry||file.startsWith(entry+'/'))));
+    const found=covered.find(file=>!tracked||tracked.has(file));
+    if(found)return found;
+  }
+  if(!fresh.length)return null;
+  if(during)return fresh[0];
+  // Asked once per directory the run had no file in, then the files outside one.
+  const dirs=new Set(Object.keys(before).flatMap(file=>file.split('/').slice(0,-1).map((_,i,parts)=>parts.slice(0,i+1).join('/'))));
+  const newDir=file=>{const parts=file.split('/');for(let i=1;i<parts.length;i++){const dir=parts.slice(0,i).join('/');if(!dirs.has(dir))return dir+'/';}return null;};
+  const ignored=ignoredNow(root,[...new Set(fresh.filter(file=>!file.startsWith('external:')).map(file=>newDir(file)??file))]);
+  return fresh.find(file=>file.startsWith('external:')||!ignored||!ignored.has(file))??null;
+}
 // A refusal line that names a hidden entry (relative): a refusal by the
 // sandbox, or a missing file, which Linux tools report for an unreadable one.
 export function hiddenRefusal(text,hidden){
@@ -288,29 +321,59 @@ const ancestors=list=>[...new Set(list.flatMap(dir=>{const out=[];for(let at=pat
 // metadata of their parent directories, and no network but Unix sockets in
 // the run's own temporary directory (`own`), which is new for each run: a
 // daemon an earlier run left behind cannot answer a later one. `hidden`:
-// absolute paths it may not read at all, not even their metadata.
-export function seatbeltProfile(reads,own=null,hidden=[]){
+// absolute paths whose contents it may not read or execute.
+// A test run (`network` "loopback") may bind and accept anywhere and
+// connect to loopback only; with `writes`, it writes nothing beneath /tmp
+// and /var/tmp but beneath those places (its checkout, home and own
+// temporary directory).
+export function seatbeltProfile(reads,own=null,hidden=[],{network='none',writes=null}={}){
   const quote=value=>JSON.stringify(value);
+  const both=list=>[...new Set(list.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   const all=[...new Set(reads.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   return ['(version 1)','(allow default)','(deny file-read* process-exec*)',
     `(allow file-read* process-exec* ${all.map(dir=>`(subpath ${quote(dir)})`).join(' ')} (literal "/") (literal "/etc") (literal "/var") (literal "/tmp"))`,
     `(allow file-read-metadata ${ancestors(all).map(dir=>`(literal ${quote(dir)})`).join(' ')})`,
     // The entry's own path, by its directory's real path: a hidden link's target is not hidden.
-    ...hidden.length?[`(deny file-read* process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
+    // Its contents only, as on Linux: a run may still see that it exists, and write beneath it.
+    ...hidden.length?[`(deny file-read-data process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
       .map(file=>`(subpath ${quote(file)})`).join(' ')})`]:[],
-    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
+    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[],
+    ...network==='loopback'?['(allow network-bind)','(allow network-inbound)','(allow network-outbound (remote ip "localhost:*"))']:[],
+    ...writes?['(deny file-write* (subpath "/tmp") (subpath "/private/tmp") (subpath "/var/tmp") (subpath "/private/var/tmp"))',
+      `(allow file-write* ${both(writes).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
 }
 // The argv that runs `argv` sandboxed: reads beneath `reads`, no network but
 // Unix sockets beneath `tmp` on macOS, nothing beneath `hidden` (absolute).
 // On Linux a hidden directory can still be listed and its entries stat'ed:
 // Landlock restricts neither beneath a listable parent.
-export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null}){
-  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden),...argv];
+// `network` "loopback" and `writes`: a test run's (seatbeltProfile). On Linux
+// its network is supervised: `stats` then says whether the supervisor served
+// the whole run (supervisorIssue).
+export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null,network='none',writes=null,fault=null}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden,{network,writes}),...argv];
   // The launcher's own warnings would become the check's output.
   if(mode==='landlock')return [python,'-I','-W','ignore',landlockScript,...reads.flatMap(dir=>['--read',dir]),
-    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],'--no-tcp','--',...argv];
+    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],
+    ...network==='loopback'?['--loopback']:['--no-tcp'],
+    ...writes?['--deny-write','/tmp','--deny-write','/var/tmp',...writes.flatMap(dir=>['--write',dir])]:[],
+    ...fault?['--test-fault',fault]:[],'--',...argv];
   throw Error(`unknown sandbox ${mode}`);
 }
+// Why a supervised run's network was not supervised throughout, from the
+// launcher's stats file, or null when it was.
+export function supervisorIssue(stats){
+  let value=null;try{value=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
+  return value?.supervisor==='ok'?null:`the network supervisor ${value?.supervisor?`reported: ${value.supervisor}`:'left no report'}`;
+}
+// The counts a test runner's summary gives, the last of each: pytest, Vitest,
+// Jest, Mocha, node --test.
+const ansi=/\u001b\[[0-9;]*m/g;
+export function testCounts(text){
+  const plain=String(text).replace(ansi,'');
+  const last=(...patterns)=>{for(const re of patterns){let m,v=null;const g=new RegExp(re,'gim');while((m=g.exec(plain)))v=Number(m[1]);if(v!==null)return v;}return null;};
+  return {passed:last('(\\d+) (?:tests? )?(?:passed|passing)\\b','^(?:#|ℹ) pass (\\d+)'),failed:last('(\\d+) (?:tests? )?(?:failed|failing)\\b','^(?:#|ℹ) fail (\\d+)'),
+    skipped:last('(\\d+) (?:tests? )?(?:skipped|pending|todo)\\b','^(?:#|ℹ) (?:skip|skipped) (\\d+)')};
+}
 // A line of a failed run's output that looks like the sandbox refused
 // something: a refused read or write, or the network unreachable. Such a
 // failure is run again outside the sandbox to tell a denial from a real one.
@@ -463,18 +526,22 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
   if(supported.issue)return {issue:supported.issue};
   const python=Boolean(pythonTool(check));
   const command=python?check.command:[lookup(scriptProject(root,check.script).manager,process.env.PATH,root)||'npm','run',check.script];
-  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager)};
+  const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager,check.kind)};
+  const tests=testRun(check);
   const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),home=path.join(scratch,'home'),tmp=path.join(scratch,'tmp');
   fs.mkdirSync(home);fs.mkdirSync(tmp);
   try{
     const entries=hide?hiddenEntries(root):[];
     if(!entries)return {issue:hiddenListIssue};
-    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=hide&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
+    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=(hide||tests)&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
     const run=async(argv,env)=>{const started=Date.now(),r=await runToEnd(argv,{cwd:root,env,timeout});
       return {status:r.timedOut?'timeout':r.status??r.signal??r.error?.code,output:`${r.stdout}\n${r.stderr}`,ms:Date.now()-started};};
     const plain=earlier??await run(command,{...process.env,...python?{}:{npm_config_update_notifier:'false'}});
     const reads=[root,home,tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
-    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats,
+      ...tests?{network:'loopback',writes:[root,home,tmp]}:{}}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    // A test run's network was supervised throughout, on Linux.
+    const supervisor=tests&&stats?supervisorIssue(stats):null;
     // A failure both ways counts as the same only without a sign of a refusal.
     const denied=sandboxed.status===0?null:denialLine(sandboxed.output,entries);
     const realOf=dir=>{try{return fs.realpathSync(dir);}catch{return null;}},plainTmp=process.env.TMPDIR||os.tmpdir();
@@ -486,8 +553,14 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
     if(at<0&&b.length>a.length)at=a.length;
     const output=at<0?null:{plain:(a[at]??'(no more output)').slice(0,160),sandboxed:(b[at]??'(no more output)').slice(0,160)};
     let launcher=null;if(stats)try{launcher=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
-    return {same:plain.status===sandboxed.status&&!denied&&!output,plain:plain.status,sandboxed:sandboxed.status,output,plainRun:plain,
-      line:denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
+    // Tests print in an order their workers decide: the counts their summary
+    // gives are compared, not every line.
+    // When neither summary can be read, every line is compared, as for a typecheck.
+    const counts=tests?[plain,sandboxed].map(r=>testCounts(r.output)):null;
+    const read=counts?.some(c=>Object.values(c).some(value=>value!==null));
+    const differs=tests&&read?(JSON.stringify(counts[0])===JSON.stringify(counts[1])?null:{plain:JSON.stringify(counts[0]),sandboxed:JSON.stringify(counts[1])}):output;
+    return {same:plain.status===sandboxed.status&&!denied&&!differs&&!supervisor,plain:plain.status,sandboxed:sandboxed.status,output:differs,plainRun:plain,
+      line:supervisor||denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
       ...hide?{hidden:entries.length,entries,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
   }finally{fs.rmSync(scratch,{recursive:true,force:true});}
 }