What is something you learned using Coding agents?
For me it was Claude code who kept talking about footguns (which I legitimately knew nothing about). Humor me with a little context on this one.
I transitioned from BluefinOS to NixOS mid last December. My workflow then was Tailscale Android app on GrapheneOS in Termux ssh'ing into machines at my house using Claude Code. I was delivering Uber Eats and DoorDash running 3 phones into 3 machines- I don't recommend this 😂 btw.
But Coder kept talking about footguns and after about 9 or 10 of them I asked what they were and culture.git was born and here's our standing list. Serious question, do you have a documented footgun list and would you share it with the community? 🤔🧐😂
# Known Footguns
A catalog of recurring traps that have bitten contributors during UCOS work. Each entry names a specific shape, where it surfaces, what it looks like when you've stepped on it, and the discipline that prevents it.
This document complements CULTURE.md. Culture is how the team works
when it is working well; this is the inverse — patterns that produce
failures when discipline lapses. Entries are added as the patterns
surface in real work.
CULTURE.md Rule 10 (new Nix files must be staged before flake builds) was the trigger for creating this doc. It is now Entry 1 below; CULTURE.md retains a stub pointing here.
---
## Footgun 1: New Nix files must be staged before flake builds see them
Where it surfaces: any time you create a new .nix file in a
flake-managed repository and run nix build or nix flake check
before git add-ing the file.
Surfaced during: FU-009 (kubo.nix), 2026-05-01.
The shape: nix build and nix flake check operate on a source
snapshot of the flake. Untracked files are invisible to this
snapshot — they do not exist as far as Nix is concerned. The
dirty-tree warning (warning: Git tree is dirty) only fires for
modified tracked files, not untracked ones, so its absence is not
a signal that the build will see your new file.
What it looks like when you step on it:
The build fails with
error: path '/nix/store/...source/micros/modules/services/<file>.nix' does not exist.
The error reads like a module path or import bug, not a git-staging
issue. The dirty-tree warning (when it fires for an unrelated modified
tracked file) further masks the cause.
The discipline that prevents it:
Any time you create a new .nix file, run git add <file> before
the first nix build. The file does not need to be committed — only
staged — for Nix to see it.
---
## Footgun 2: #[path] re-imports compile shared sources twice
Where it surfaces: integration tests for binary-only Cargo
packages ([[bin]] with no [lib]) that share source files between
the binary and the integration crate via
#[path = "../src/foo.rs"] mod foo.
Surfaced during: FU-032a, 2026-05-02. The
daemons/linux/wasm-executor/tests/shell_bridge_integration.rs test
crate uses #[path] to re-import shell_bridge.rs so it can exercise
the bridge's public surface against a mock Shell. Two unforced build
errors in one sprint traced to the same shape; both took a full
30-minute Nix build cycle to surface.
The shape: when you #[path]-include a source file into a second
crate, that file is compiled twice — once in its native binary
context where its use crate::Foo references resolve to the binary's
own modules, and once in the test crate context where crate:: means
the test crate's root. Anything crate::Foo references must exist at
the test crate's root, typically via a mod stubs { ... } block plus
a use stubs::{Foo, ...} re-export.
What it looks like when you step on it:
error[E0432]: unresolved import 'crate::Foo'in the integration test build, even thoughcargo buildof the binary succeeds.error[E0599]: no function or associated item named 'bar' found for struct 'stubs::Foo'when a stub struct exists but is missing a method the shared source's#[cfg(test)]block calls.error[E0277]: 'Foo' doesn't implement 'Debug'when a test inside the shared source uses{:?}formatting against a Result whose type parameter does not deriveDebug— derive macros that work for the binary may surface failures in the test crate context if test-local types lack the same derives.
The discipline that prevents it:
Before any flake bump or Nix build that includes a change to the shared source or to the integration test crate's stubs:
Enumerate every
use crate::Fooanywhere in the shared source, including inside#[cfg(test)] mod testsblocks. The list is exhaustive — every name on the right side ofcrate::must be at the integration crate's root.Cross-check that list against what the integration crate re-exports via
use stubs::{...}. Missing one is a compile error.Trace every
Foo::bar()call the shared source makes. Each such call requires the stubFooto define abarwith the same signature. Adding the stub struct is not enough; its associated functions must be present too.Audit
panic!("...{:?}", x)andResult::unwrap_err()paths — these needDebugon every type parameter. Test-local types need#[derive(Debug)]even when the shared source's main types already have it.
The three items together take five minutes. Skipping them costs a 30-minute Nix build cycle.
Pattern-match alternative: if the integration coverage burden
grows past what a #[path] re-import can carry cleanly (more than
~5 stub items, or stubs that need real behavior), the right move is
to add a [lib] target to the package's Cargo.toml and have both
the binary and the integration crate consume the library. That is a
larger architectural change and should be a deliberate decision, not
a reactive fix.
---
## Footgun 3: shell-daemon bind failure hangs wasm-executor at boot
Where it surfaces: ProBook (and any substrate ISO that enables
both services.shell and services.wasm-executor).
Surfaced during: FU-032b implementation, 2026-05-03.
The shape: wasm-executor's runit runScript waits on
until [ -S /tmp/shell-bridge.sock ] before exec'ing the daemon.
If shell-daemon ever fails to bind for reasons other than a stale
socket file (the stale-file case is auto-handled by remove_file at
shell-daemon's main.rs:18), the loop never exits and wasm-executor
hangs indefinitely. Bind can fail for kernel resource exhaustion,
filesystem permissions on /tmp, or symlink replacement attacks.
The discipline: if wasm-executor's log shows the
"waiting for /tmp/shell-bridge.sock" pattern across more than ~10
seconds at boot, check /var/log/shell/current for bind errors
before assuming the dependency wiring is broken. The fix is on the
shell-daemon side, not the executor side.
---
## Footgun 4: runit supervise/ok proves runsv started, not that the daemon is actually ready
Where it surfaces: any runit dependencies = [ "<svc>" ] chain
where the dependent service's readiness is what the dependee actually
needs (e.g., a daemon listening on a socket, a server accepting TCP
connections, a process having loaded its config).
Surfaced during: FU-032b implementation, 2026-05-03 — generalized from the shell-daemon ↔ wasm-executor pair where the runit dep alone was insufficient.
The shape: runit creates /etc/service/<svc>/supervise/ok (a FIFO)
as soon as runsv starts, before the supervised binary has a
chance to call bind(), open its database, parse its config, or
otherwise become functionally ready. A dependencies = [ "<svc>" ]
gate that waits on supervise/ok therefore proves the supervisor
exists, not the daemon serves. The race window is small (typically
milliseconds) but real, and it widens whenever the supervised binary
does any non-trivial setup before its serve loop. FU-005 hit it with
searxng-client waiting on searxng's TCP port (resolved with
nc -z polling); FU-032b hit it with wasm-executor waiting on
shell-daemon's Unix socket (resolved with until [ -S ... ]
polling). FU-027 names this as a standing audit item.
The discipline: every dependencies = [ "<svc>" ] declaration
that needs functional readiness from <svc> must pair with a
discriminator-specific readiness check inside the dependee's
runScript. The discriminator depends on the daemon's contract:
TCP server →
nc -z 127.0.0.1 <port>loopUnix socket server →
until [ -S /path/to.sock ]loopDatabase / config loader → grep its log for the "ready" line
Process that does work then exits → don't gate on it; rethink the dep
The runit dep stays — it provides ordering. The polling check inside runScript stays too — it provides actual readiness. Belt-and-braces.
--- I think there's over 100 now and Coder isn't as bad at hitting them more than once as it once was 😂. What are your top footgun candidates?
One thoughtful comment unlocks the ability to create threads.
Apparently Chrome saved what boxes you checked in a local db, I accidentally exited out of a Claude artifact where I was marking things as yes / no and thought I lost my work but Claude Code was able to recover it from this cache I had no idea existed!