5993f32146
1. Filesystem type detection (architect P2 finding)
_primitives/_rust/keisei/src/fs_type.rs (NEW, 103 LOC)
- statfs(2)-based detection on unix (libc = '0.2' under
[target.'cfg(unix)'.dependencies])
- Recognizes exfat / msdos (FAT32) via f_fstypename on macOS,
via f_type magic numbers on Linux (0x4d44, 0x2011bab0)
- Windows stub returns Unknown (GetVolumeInformationW TBD)
- warn_on_unsafe_fs(root) emits stderr warning on ExFat/Fat32
brain.rs::load calls warn_on_unsafe_fs after canonicalize+symlink
checks. Warning NOT fatal — user can opt into single-client use.
2. Battle-test matrix (architect P3 finding)
tests/battle/Dockerfile.install-test-alpine (NEW)
- alpine:3.19 + apk rust/cargo/pandoc
- Exposes musl-vs-glibc issues in aws-sdk-s3, rusqlite, git2
tests/battle/Dockerfile.install-test-debian (NEW)
- debian:12 + rustup stable + pandoc
- Default server distro, different apt structure from Ubuntu
tests/battle/README.md rewritten — 3-distro matrix with run script
3. USB-BRAIN-GUIDE platform split
docs/USB-BRAIN-GUIDE.md — restructured as TOC + platform-agnostic
preamble + exFAT warning + cross-platform troubleshooting
docs/USB-BRAIN-GUIDE-macos.md (NEW, 97 LOC) — Gatekeeper, diskutil,
/Volumes, xattr -d com.apple.quarantine
docs/USB-BRAIN-GUIDE-linux.md (NEW, 98 LOC) — /media/$USER,
umount, ext4 recommended, systemd-udev auto-mount note
docs/USB-BRAIN-GUIDE-windows.md (NEW, 115 LOC) — PowerShell
Dismount-Volume, NTFS, FS-advisory Unknown caveat
REAL VERIFICATION (paste from agent):
cargo check -p keisei: Finished (clean)
cargo test -p keisei --release: 32 passed 0 failed (30 existing + 2 new)
docker buildx outline: both new Dockerfiles parse
Constructor Pattern:
fs_type.rs 103 LOC, brain.rs 198 LOC (at limit 200, held the line)
All fns <30 LOC. Each USB guide sub-doc 97-115 LOC.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
98 lines
6.1 KiB
Markdown
98 lines
6.1 KiB
Markdown
# USB Exobrain — Step-by-Step Test Recipe
|
||
|
||
> Put a KeiSeiKit "brain" on a portable USB drive, mount it into Claude Code (and Cursor / Continue / Zed if installed), verify MCP tools, unplug — verify clean detach.
|
||
>
|
||
> This top-level document holds prerequisites, the shared filesystem warning, the TOC, and platform-agnostic troubleshooting. Step-by-step walkthroughs live in the three platform sub-documents.
|
||
|
||
## Platform walkthroughs
|
||
|
||
- [macOS walkthrough](./USB-BRAIN-GUIDE-macos.md) — `/Volumes/<LABEL>`, APFS recommended, Gatekeeper / `xattr` handling.
|
||
- [Linux walkthrough](./USB-BRAIN-GUIDE-linux.md) — `/media/$USER/<LABEL>`, ext4 recommended, `umount` / optional systemd-udev auto-attach.
|
||
- [Windows walkthrough](./USB-BRAIN-GUIDE-windows.md) — drive letter, NTFS recommended, `Dismount-Volume` / PowerShell.
|
||
|
||
---
|
||
|
||
## 0. Prerequisites (all platforms)
|
||
|
||
On the host:
|
||
|
||
- KeiSeiKit installed: `./install.sh --profile=full` ran successfully, `cargo test -p keisei` shows 32/32 pass (v0.22).
|
||
- `keisei` CLI on PATH: `ls ~/.claude/agents/_primitives/_rust/target/release/keisei` returns the binary. Symlink into `~/.local/bin/` or `%USERPROFILE%\bin` as convenient.
|
||
- At least one supported client installed (Claude Code / Cursor / Continue / Zed) — `keisei` auto-detects all four.
|
||
- A USB stick or flash card physically attached and mounted by the OS.
|
||
|
||
On the USB drive:
|
||
|
||
- Free space: ~500 MB recommended (5 mcp-server binaries × ~90 MB each + room for memory/artifacts SQLite).
|
||
- Filesystem — see the warning below.
|
||
|
||
---
|
||
|
||
## ⚠️ Filesystem warning — exFAT / FAT32 are NOT safe for multi-client attach
|
||
|
||
SQLite WAL mode (used by `kei-memory`, `kei-artifact`, `kei-social-store` inside a brain) requires a filesystem with reliable shared-memory mmap. exFAT and FAT32 do NOT provide this, and `keisei mount` (multi-client fan-out) WILL corrupt the memory DBs if the brain lives on one of those filesystems.
|
||
|
||
Since v0.22 `keisei` itself prints an advisory on stderr when it detects an exFAT / FAT32 root at load time (via `statfs(2)` on macOS + Linux; Windows returns `Unknown` pending `GetVolumeInformationW`). The warning is non-blocking — single-client `keisei attach` on exFAT is still a supported path.
|
||
|
||
- On exFAT / FAT32: use the brain with **ONE client at a time** (`keisei attach --scope=user`). Do NOT run `keisei mount`.
|
||
- For reliable multi-client use, format the stick as **APFS (macOS)**, **ext4 (Linux)**, or **NTFS (Windows)**. exFAT is fine for single-client or read-only cross-platform transport.
|
||
- If you already ran `keisei mount` on an exFAT brain and see SQLite errors, see "SQLite corruption on mount-attach" in Troubleshooting below.
|
||
|
||
---
|
||
|
||
## Brain safety invariants (all platforms)
|
||
|
||
The following load-time checks fire regardless of OS. They prevent the most common misuse and attack patterns:
|
||
|
||
- **Name regex** — `brain.name` must match `^[a-z][a-z0-9_-]{0,63}$` (lowercase letter start, 1-64 chars, word chars + hyphen).
|
||
- **Relative paths** — every `[paths.*]` entry must be relative; no absolute paths, no `..` components. Canonical form must live under the brain root.
|
||
- **Symlink reject** — the brain root itself cannot be a symlink. Pass the resolved path; this closes a USB→host pivot surface.
|
||
- **Manifest size cap** — `manifest.toml` is bounded at 64 KiB.
|
||
- **Schema** — `schema_version ∈ {1, 2}`. v1 uses single-string `mcp_server`; v2 uses per-platform map.
|
||
|
||
---
|
||
|
||
## Platform-agnostic troubleshooting
|
||
|
||
### "BrainNotFound" on attach
|
||
- Check `<BRAIN>/manifest.toml` exists.
|
||
- Pass an absolute path to `keisei attach`, not a relative one.
|
||
|
||
### "PathEscape" on attach
|
||
- Every `[paths.*]` entry must be relative and resolve inside the brain root. No `../`, no absolute paths.
|
||
|
||
### "BrainIsSymlink" on attach
|
||
- The brain root is a symlink. Pass the resolved path instead — `keisei` refuses symlink roots to prevent accidental host-dir pivot via a crafted USB.
|
||
|
||
### "NoPlatformBinary" on first use
|
||
- Your platform's binary isn't in `bin/`. Check `std::env::consts::{OS, ARCH}` on your host — the expected filename is `kei-mcp-server-<os-renamed>-<arch-renamed>` where `macos→darwin`, `x86_64→x64`, `aarch64→arm64`.
|
||
|
||
### "NameConflict" on attach
|
||
- An MCP server with the same name already exists in the client's config. Either rename your brain (`name` in `manifest.toml`) or remove the existing entry manually.
|
||
|
||
### SQLite corruption on mount-attach
|
||
- `kei-memory` / `kei-artifact` / `kei-social-store` databases show "disk image is malformed" or "database is locked" after `keisei mount` on a USB drive.
|
||
- Root cause: the brain lives on **exFAT or FAT32**, which don't reliably support SQLite WAL shared-memory mmap. Multi-client attach corrupts the DB.
|
||
- Fix:
|
||
1. Copy the brain dir to an APFS (macOS) / ext4 (Linux) / NTFS (Windows) volume.
|
||
2. Re-attach via `keisei attach <new-path>` or `keisei mount <new-path>`.
|
||
3. For single-client use on the same exFAT drive, restrict to `keisei attach --scope=user`. Do NOT use `keisei mount`.
|
||
|
||
### Filesystem-warning advisory not appearing
|
||
- `keisei` prints the exFAT/FAT32 warning to **stderr** (not stdout). Shells that redirect stderr away will hide it.
|
||
- Windows `detect_fs_warning` returns `Unknown` in v0.22 — format as NTFS manually.
|
||
|
||
---
|
||
|
||
## What this tests end-to-end
|
||
|
||
1. **Portable brain** — works from a USB drive, no installer needed on the brain itself.
|
||
2. **Per-platform dispatch** — schema v2 picks the right binary for the host OS+arch.
|
||
3. **Multi-client fan-out** — `keisei mount` attaches to every detected client in one call.
|
||
4. **Clean detach** — zero residue in host configs, preserves unrelated MCP servers.
|
||
5. **Safety gates** — path confinement, name regex, symlink rejection, manifest size bound, filesystem-type advisory (v0.22).
|
||
6. **Schema v1 compat** — an older v1 brain with a single-string `mcp_server` still works.
|
||
|
||
If the walkthrough for your platform passes end-to-end, the v0.22 exobrain is production-ready for single-user workflows on that platform.
|
||
|
||
For shared-brain scenarios (team members all mounting the same brain over git / S3) see the `kei-store` backend docs — `keisei attach s3://my-bucket/brain/` requires `--features s3` at install.
|