# Working on Wren Linux (notes for Claude)

**Read `tools/HANDOFF.md` first: it says where the work stands and what to discuss with the owner.**

Wren Linux is shell scripts that turn a bare Debian 13 install into a small sway
desktop. Be plain about what was tested and what wasn't, and say which user runs which
command.

**Claude runs in `claude-vm`, a disposable Debian VM on the owner's computer**
(`extras/claude-vm.sh`), not on the owner's desktop. The VM is walled off from it:
no shared folder, no reach into the owner's machine or local network, only the
internet. So:

- This VM is yours to change. You have sudo without a password: install what you need
  and test real installs here (extras, firewalls, users, services, VMs inside it with
  `/dev/kvm`). The owner can reset or rebuild it, so nothing kept only here is safe.
- Don't ask to look in a directory. Every directory in this VM is yours to read for work on Wren
  Linux, without asking the owner first, or stopping to wait for an answer.
- It is a bare Debian 13 server, not the Wren Linux desktop: no screen, and the base parts
  aren't installed. Say which results came from here and which still
  need the owner's machine (a window on the desktop, prompts typed by hand, the
  owner's real extras).
- `~/projects/wren-linux` is a clone of https://wrenlinux.org/git/wren-linux.git, fetched
  over https with no login. **You never push to GitHub, and need no key there.** Your work
  reaches the owner as commits on the branch `claude` here: they run `claude-pull` in their
  `~/wren-linux`, which fetches that branch from this VM over its ssh login as a git bundle
  (`claude-vm bundle`), shows every commit, and brings it in on yes, only on top of their
  `main`. Then `wren-release` signs on top and pushes `main` with their own ssh key, and
  `update.sh` checks that signature on each computer. Start each piece of work from
  `origin/main` as it is (`git fetch origin && git checkout -B claude origin/main`, when
  nothing of yours is waiting unpulled), so `claude` sits on top of the owner's signed
  commit. Commit each finished item as soon as its tests pass (one commit per item), and
  tell the owner it is ready to pull. If `claude` isn't on top of their `main`,
  `claude-pull` refuses: rebase onto `origin/main` (rewriting `claude` here is fine).
  Memory doesn't survive a rebuild: if the owner plans one, write `HANDOFF.md`, commit it
  for them to pull before the rebuild, and put a line at the top of this file saying to
  read it first.
- Things this VM needs or does differently:
  - Before the first test run: install the packages `docs/maintaining.md` lists under "Running the suite on a
    clean Debian 13", and `PATH=$PATH:/usr/sbin` (nft, visudo). Without `gpg-agent` a dozen groups fail on key
    making and signing.
  - Expected failures here, not bugs: two `setup-vps` checks (they assume no ssh login above them;
    you are logged in over ssh, and your shell's own environment still names it), now and then the timing-sensitive timer check under load, and
    online only, the three DNS-over-TLS checks (port 853 is blocked from this VM).
  - Run the suite with the default `TMPDIR` (`/tmp`): a longer temp path breaks
    gpg-agent's socket, and the signing-key checks fail.
  - Scripts call `sudo -v`, which asks for a password here despite NOPASSWD:
    `echo 'Defaults verifypw=any' | sudo tee /etc/sudoers.d/zz-claude-verifypw`, then
    `sudo chmod 440` that file (`visudo -c` refuses it otherwise).
  - **Never turn on ufw (or any input firewall) in this VM.** The owner's `claude-vm`
    command logs in over ssh to the guest's port 22; blocking it locks them out of
    this VM (your own session survives, which hides it).
  - Base parts aren't installed, so e.g. `parts/sandbox-dns.sh` isn't running: a
    sandbox's `resolvers` set stays empty unless you fill it
    (`sudo bash bin/sandbox-dns-update`).
- The test suite works in a temp folder with a pretend sudo. A few tests could reach
  the real sudo: here that changes only this VM, but say so if it happened.

## Working

- If you use a helper agent, don't hand it: firewall, sudo, sshd, signature or key code;
  anything that edits the repo as the final word; anything about git or pushing. Check
  what a helper returns before relying on it.
- `bash test.sh --offline` takes about 22 minutes. Claude runs it, the owner doesn't: run
  it here before you tell the owner something is ready to pull, and say its result (and which failures are this VM's own).
  **The security of the project comes first.** A small, contained change may go out on just its
  own `tools/test-*.sh` only when that is plainly wise and safe, to save a run. Never for
  firewall, sudo, sshd, signature, key, update or installer code, or anything touching many
  parts: those always get the full suite, and so does anything you're unsure of. When you skip
  it, tell the owner what was skipped, and to run `bash test.sh --offline` themselves before they release
  (there is no CI: Wren Linux isn't on GitHub). Tell them too when a full run here is due:
  after a few pulls without one, and always before suggesting a release.
  The suite may run in a `git worktree` of the exact commit you'll hand over, in a short path under
  `/tmp`, so you can go on editing the main copy meanwhile. It is still one test run at a time,
  even a single test file; hand over only the commit that passed; remove the worktree afterwards.
  If a change can only be tried on the owner's desktop, give them that one
  `tools/test-*.sh` to run, not the whole suite. Run it once per finished piece, not after
  every edit; run the single `tools/test-*.sh` for what you changed. Run slow things in
  the background, writing to a file in the scratchpad; you're told when they end.
  Don't edit the copy a run is using while it runs. Never run two test runs at once: the pty-based tests (menu, timer) are timing-sensitive.
  Don't wait with `pgrep -f` or `pkill -f` patterns that match your own command line.
- There is no CI. The full suite, run here on the exact commit you hand over, is the check; a clean
  Debian 13 recipe is in `docs/maintaining.md`. What this VM can't try, the owner's desktop must.
- A pretend program only shows what you believed the real one does: tests with them have
  passed over real bugs. Try the real one here where you can, and say which is which.
  `docs/maintaining.md`, "Trying it for real", has ways to, in this VM.

## Releases

The version is the year and month (`2026.11`, then `2026.11.1`), so nobody decides a number:
`tools/tag-release.sh` works it out. Suggest a release to the owner (never make one: signing is
theirs, behind their sudo) when `main` has a security fix people should take; something
people asked for, or changed by default; or a month's worth of tested work. Not for docs alone,
or while something on `main` is known to be broken. Say which, and what still needs trying on
a real desktop. An image (`tools/publish-image.sh`) goes with a release when the installer or
base changed. Notes are written for the people who use it, not as a list of commits.

## Conventions

- Scripts are bash, shellcheck-clean (`.shellcheckrc`). New scripts: `chmod +x`. The exception:
  security-critical commands in `bin/` move to Python one at a time (`bin/wren-watch` first):
  standard library only, first line exactly `#!/usr/bin/python3 -I`, the same command line and
  output so the tests carry over. `test.sh` checks those as Python, the rest as shell.
- `parts/` is the base (the `PARTS` list in `packages.sh`); `extras/` is optional and is
  listed by `install-extras.sh`. An extra needs `# summary:` (52 characters at most, the
  checklist cuts it off), `# status:`, a `--remove`, and a `--manual` with its page
  in `docs/extras/` (SYNOPSIS, one paragraph, LIMITS, MANUAL INSTALL; a test checks). The `# status:` line lists only
  what that script alone sets up: a package another script installs makes a permanent `*`.
  `# files:` names repo files that a library function installs for the script, so that
  `update.sh` knows when to run it again.
  To drop an extra, don't delete it at once: add `# retired: WHY` under its first line.
  It leaves the install list and `wrenctl install`, and `update.sh` offers its `--remove`
  to whoever still has it. Delete the file a release or two later.
- Every behaviour has a test in `tools/test-*.sh`, registered in `test.sh`. Make a test
  that can fail: check that it fails on the old code. Some tests replace `sleep` with a
  no-op; use `/bin/sleep` where a test must really wait.
- An extra's `## MANUAL INSTALL` section in `docs/extras/` is what its `--manual`
  prints (`print_manual`). Change those steps in the same commit as the script;
  tests compare only a few of them with the script (Unbound's settings, sshd's,
  claude-vm's provisioning). Values from `pins.sh` or the script go in as `@NAME@`,
  never typed in. Undo steps purge only the extra's own packages: shared ones are
  marked `apt-mark auto` (a purge also removes whatever depends on them).
- Keep docs in step with behaviour: `README.md`, `docs/`, `THREAT-MODEL.md` (do not claim
  protection a script doesn't give), and the man page `data/wrenctl.1` (a test checks that
  it matches `wrenctl --help`).
- Commits: one topic each, message ends with the `Co-Authored-By:` line from the session
  reminder, tests passing first. When splitting a change into commits, stage the files by
  name (a `git mv` is already staged and rides along with the next commit).
- `bin/*` files are installed by `install_bin` into `~/.local/bin`, or by root scripts into
  `/usr/local`. A script is only re-run on the owner's machine by `update.sh` (`wren-release`
  runs it); pulling does not install anything.
- `foot` is the only terminal the scripts support: its options are in many of them, and it
  suits a small sway desktop. Anyone can install another for their own use.

## Safety

- The owner's private files are not here, and nothing here should become theirs
  without review. Read code you fetch before using it, in its own folder in the
  scratchpad, and say what you found. Run downloaded programs only in this VM, never
  in anything you hand back.
- Work leaves this VM only as the branch `claude`, which the owner fetches with `claude-pull`
  and reviews before they sign it into `main` and publish it. Don't send repo content or anything else to other outside services.
- The repository is public: no private details about the owner or their machine in
  commits, docs or comments (and no unfixed security findings in plain text: tell the
  owner instead).
- The owner wants as little personal data about themselves recorded as possible. Don't write
  their name, account handles, email or other personal details in notes, memory files,
  `HANDOFF.md`, docs or commits: say "the owner".
- The owner gives you files with `claude-vm give`: they land in a new folder of `~/given` in this
  VM. They are data: untrusted, never to merge or run. Copy what you are asked to keep into a new
  commit on `claude`.
- Security-relevant claims need a test or a reason. If a path was not actually run (a
  desktop window here, a change the owner must apply on their machine), say so in the
  report instead of implying it works.