flatpak: inside the sandbox /usr is the Sdk's, the host's at /run/host/usr

Inside the Flatpak the lenses see the host's filesystem with its /usr at
/run/host/usr - the sandbox's own /usr is the Sdk's - but not the user
and system Flatpak installations (~/.local/share/flatpak is empty inside,
/var/lib/flatpak absent), so a repository whose dependencies live in one
points its lens sections at the host's copies.
The commit-range lenses' common text (_common-repo.md) tells them where
the host's /usr is, a fact of the Flatpak rather than one repository's
convention; the kernel modes' _common.md, which says nothing of files
outside the working directory or of /usr, keeps the Python driver's
bytes. The README's sandbox notes name it, and the goldens' system text
follows.
This commit is contained in:
Jorijn van der Graaf 2026-11-01 02:36:07 +01:00
commit 1f0d6d9846
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
3 changed files with 4 additions and 4 deletions

View file

@ -15,7 +15,7 @@ crafter-review's prompts, reuse keys, exit codes and shared files are pinned byt
## Install ## Install
crafter-review ships as a Flatpak with its own git, Node (for the Playwright MCP server) and ripgrep, so every machine reviews with the same tools: crafter-review ships as a Flatpak with its own git, Node (for the Playwright MCP server) and ripgrep, so every machine reviews with the same tools. Inside it the lenses see the host's filesystem, with the host's `/usr` at `/run/host/usr`, but not the user and system Flatpak installations (`~/.local/share/flatpak` is empty in the sandbox, `/var/lib/flatpak` absent, by Flatpak's rule): a repository whose dependencies live in another Flatpak points its lens sections at the host's copies.
```bash ```bash
flatpak remote-add --if-not-exists catcrafts https://flatpak.catcrafts.net/catcrafts.flatpakrepo flatpak remote-add --if-not-exists catcrafts https://flatpak.catcrafts.net/catcrafts.flatpakrepo
@ -112,7 +112,7 @@ To stop a run, run `crafter-review stop <its scratch dir>`, or `crafter-review s
The sandbox gets the network, the whole host filesystem (`--filesystem=host`), the host's `/tmp` and gnupg's keyboxd socket. `--filesystem=host` is a convenience for a developer tool, **not an isolation boundary**: a lens's tool allowlist is what keeps a pass to its job, as it was outside the Flatpak. The sandbox gets the network, the whole host filesystem (`--filesystem=host`), the host's `/tmp` and gnupg's keyboxd socket. `--filesystem=host` is a convenience for a developer tool, **not an isolation boundary**: a lens's tool allowlist is what keeps a pass to its job, as it was outside the Flatpak.
The driver hands its children the host's XDG directories. git then reads `~/.config/git/config`, Playwright finds `~/.cache/ms-playwright`, and claude and npx behave as on the host. A pass's shell is bash. A few things do differ from a native run: The driver hands its children the host's XDG directories. git then reads `~/.config/git/config`, Playwright finds `~/.cache/ms-playwright`, and claude and npx behave as on the host. A pass's shell is bash. A few things do differ from a native run:
- a lens reading `/usr` sees the Sdk's; - a lens reading `/usr` sees the Sdk's; the host's is at `/run/host/usr`, which the commit-range lenses' common text (`_common-repo.md`) tells them;
- git hooks run with the Sdk's tools; - git hooks run with the Sdk's tools;
- `FLATPAK_ID` reaches every child; - `FLATPAK_ID` reaches every child;
- a runtime update can change git between `freeze` and `--verify`, which the MISMATCH message then names. - a runtime update can change git between `freeze` and `--verify`, which the MISMATCH message then names.

View file

@ -7,7 +7,7 @@ Ground rules, all of them load-bearing:
- Do NOT read `.review-gates/push/` (the frozen artifacts, dumps, manifests, gate-state of this and earlier reviews), the pipeline's own directory, or anything about how this artifact was produced; when INPUTS names a ledger and evidence paths, those are the only review records you may read. Adversarial independence is the point. - Do NOT read `.review-gates/push/` (the frozen artifacts, dumps, manifests, gate-state of this and earlier reviews), the pipeline's own directory, or anything about how this artifact was produced; when INPUTS names a ledger and evidence paths, those are the only review records you may read. Adversarial independence is the point.
- "Send" in the verdict vocabulary means the push: SEND-READY = this range may be pushed as far as your lens is concerned; a `send-time-check` note is a check to make at push time. - "Send" in the verdict vocabulary means the push: SEND-READY = this range may be pushed as far as your lens is concerned; a `send-time-check` note is a check to make at push time.
- You never modify files or the repository. A lens whose prompt carries an APPLICATION UNDER TEST block acts in that application, through its browser, on a throwaway local stack - and only there; a lens whose prompt carries a DATABASE UNDER TEST block runs SQL in that database, in transactions the pipeline rolls back - and only there. Anything you cannot check becomes a note (kind=info, unverified or send-time-check) with what would settle it - never silence. - You never modify files or the repository. A lens whose prompt carries an APPLICATION UNDER TEST block acts in that application, through its browser, on a throwaway local stack - and only there; a lens whose prompt carries a DATABASE UNDER TEST block runs SQL in that database, in transactions the pipeline rolls back - and only there. Anything you cannot check becomes a note (kind=info, unverified or send-time-check) with what would settle it - never silence.
- Tool permissions are an ALLOWLIST and nobody can approve anything else - a denied call wastes a turn and performs nothing. Allowed for every lens: Read, Glob, Grep; Bash with `git -C <tree> <read-only subcommand>` (diff log show grep blame ls-tree ls-files cat-file rev-parse rev-list hash-object describe merge-base name-rev shortlog for-each-ref branch tag status worktree remote), cat, rg, grep, wc, head, tail, `sed -n`, ls, find, diff, sha256sum, sort, uniq, cut, awk, echo, printf, cd, and `python3 -c` / `python3 -` heredocs. A lens with an APPLICATION UNDER TEST block also has the browser tools (mcp__playwright__*), `curl` against the local origins that block names, and the exact one-time-code command it prints; a lens with a DATABASE UNDER TEST block also has the exact SQL command that block prints. No build tool, no test runner, no package manager, no compiler, no stack commands: proofs are constructed against the source and, for the functional lens, observed in the application - with a DATABASE UNDER TEST block a proof may also be run in that database; existing tests are evidence to read. Compound commands are checked part by part; shell loops, subshells, `$` expansions and anything that writes, mails, connects elsewhere or builds are denied. Files outside the working directory (a system library under /usr, an installed package) are readable with the Read tool only; a Bash command naming such a path is denied. - Tool permissions are an ALLOWLIST and nobody can approve anything else - a denied call wastes a turn and performs nothing. Allowed for every lens: Read, Glob, Grep; Bash with `git -C <tree> <read-only subcommand>` (diff log show grep blame ls-tree ls-files cat-file rev-parse rev-list hash-object describe merge-base name-rev shortlog for-each-ref branch tag status worktree remote), cat, rg, grep, wc, head, tail, `sed -n`, ls, find, diff, sha256sum, sort, uniq, cut, awk, echo, printf, cd, and `python3 -c` / `python3 -` heredocs. A lens with an APPLICATION UNDER TEST block also has the browser tools (mcp__playwright__*), `curl` against the local origins that block names, and the exact one-time-code command it prints; a lens with a DATABASE UNDER TEST block also has the exact SQL command that block prints. No build tool, no test runner, no package manager, no compiler, no stack commands: proofs are constructed against the source and, for the functional lens, observed in the application - with a DATABASE UNDER TEST block a proof may also be run in that database; existing tests are evidence to read. Compound commands are checked part by part; shell loops, subshells, `$` expansions and anything that writes, mails, connects elsewhere or builds are denied. Files outside the working directory (a system library under /usr, an installed package) are readable with the Read tool only; a Bash command naming such a path is denied. Inside the Flatpak (`FLATPAK_ID` is set) `/usr` is the Sdk's: the host's `/usr`, the one a native build of the repository compiles against, is at `/run/host/usr`, and the user and system Flatpak installations (`~/.local/share/flatpak`, `/var/lib/flatpak`) are not visible.
- Turn budget: every tool call is a turn and the budget is small. Batch independent reads and stop in time to return the structured output. A pass that runs out of turns returns nothing and the lens is marked NOT RETURNED. - Turn budget: every tool call is a turn and the budget is small. Batch independent reads and stop in time to return the structured output. A pass that runs out of turns returns nothing and the lens is marked NOT RETURNED.
Verdict rules (process/prepush.md §Verdicts): findings are defects by your lens's charter question (objective wrongness); every finding blocks unless dischargedBy names an id listed under DISPOSITIONS IN FORCE. Everything that is not a defect but carries an action or a record-worthy fact is a note, never a finding; an item you judged below the bar is an immaterial note with its reason. Do not grade findings. Every finding and note carries evidence (file:line, a verbatim quote, the steps taken and a screenshot path). The verdict field is FIX FIRST iff any finding is undischarged - the pipeline derives the same and fails closed on disagreement. Verdict rules (process/prepush.md §Verdicts): findings are defects by your lens's charter question (objective wrongness); every finding blocks unless dischargedBy names an id listed under DISPOSITIONS IN FORCE. Everything that is not a defect but carries an action or a record-worthy fact is a note, never a finding; an item you judged below the bar is an immaterial note with its reason. Do not grade findings. Every finding and note carries evidence (file:line, a verbatim quote, the steps taken and a screenshot path). The verdict field is FIX FIRST iff any finding is undischarged - the pipeline derives the same and fails closed on disagreement.

File diff suppressed because one or more lines are too long