Parfii-bot 5993f32146 feat(v0.22): FS warn + battle-test matrix + USB docs platform split (Track C)

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>

2026-04-22 20:56:42 +08:00

6.1 KiB

Raw Blame History

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 — /Volumes/<LABEL>, APFS recommended, Gatekeeper / xattr handling.
Linux walkthrough — /media/$USER/<LABEL>, ext4 recommended, umount / optional systemd-udev auto-attach.
Windows walkthrough — 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

Portable brain — works from a USB drive, no installer needed on the brain itself.
Per-platform dispatch — schema v2 picks the right binary for the host OS+arch.
Multi-client fan-out — keisei mount attaches to every detected client in one call.
Clean detach — zero residue in host configs, preserves unrelated MCP servers.
Safety gates — path confinement, name regex, symlink rejection, manifest size bound, filesystem-type advisory (v0.22).
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.

6.1 KiB Raw Blame History Unescape Escape