AIPass/tests/CROSS_OS_TESTING.md

AIPass Cross-OS Acceptance Checklist

Purpose: the definition of "AIPass works on this OS." Follow this top-to-bottom on any fresh machine or VM (Windows / macOS / Linux) to verify a real end-to-end install — the things automated CI structurally cannot reach (full install, interactive flows, background daemons, audible hooks). Copy a Run Record (bottom of this file) per machine and fill it in.

Code is truth. A green checkbox here means you watched it work on that OS, not that it should.

---

The 3 layers of cross-OS confidence

Layer	What	Where it runs	Catches
1 — Static	drone @seedgo Windows-compat scan	any OS, no execution	POSIX-only patterns (os.kill, start_new_session, /tmp, fcntl…) before you run
2 — Automated	pytest tests/e2e (the e2e-wheel.yml 4-tier gate)	CI on ubuntu+windows+macos, and locally	the wiring contract: clean-wheel install → aipass init scaffold → hook fires → drone routes
3 — Manual	this checklist	a real box / VM, by hand	full install, interactive init run, daemons, sound, per-branch smoke

Layers 1–2 are free and run on every push. This file is layer 3 — the human acceptance pass you do when you get hardware (a VM, a borrowed Mac, a new laptop).

Machine pre-flight (augments, never replaces layer 3). aipass init now runs a layer-3-lite pre-flight: stage 2 prints OS-relevant heads-ups for tracked gaps before scaffolding. For a fuller machine sweep, aipass doctor --cross-os reports the known-gap surface, --e2e runs the real layer-2 suite, and --record [PATH] emits a machine-filled Run Record. These front-run the obvious breakage — but the human acceptance pass below is still the real layer 3.

---

How to use

1. Capture output. Run your shell session into a log so any crash traceback is saved:
   • Linux/macOS: script -q aipass-crossos-$(uname -s).log (then run the checks, exit when done)
   • Windows PowerShell: Start-Transcript -Path aipass-crossos-win.log … Stop-Transcript
2. Work through Phase 0 → 7, then the Per-branch matrix.
3. For every check: run the command, compare to Expected, tick ⬜ → ✅ / ❌.
4. On ❌: note the exact error in the Run Record, check the Known gap registry (it may be a tracked one), and if new, file it / email the owning branch.
5. Paste the completed Run Record into the PR / DPLAN-0194 thread.

Legend: ✅ pass · ❌ fail · ⏭️ skipped (state why) · ⚠️ known-gap watch item

---

Phase 0 — Environment capture (record before anything)

#	Capture	Command
0.1	OS + version	uname -a / Win: cmd /c ver + systeminfo | findstr /B /C:"OS"
0.2	Arch	uname -m / Win: echo %PROCESSOR_ARCHITECTURE%
0.3	Python	python3 --version (Win: python --version) — must be 3.10+
0.4	Shell + terminal	which shell; is it Windows Terminal / cmd / PowerShell / iTerm?
0.5	AIPASS_HOME	echo $AIPASS_HOME (Win: echo %AIPASS_HOME%) — note set/unset
0.6	Git	git --version

Why terminal matters: the cp1252 stdout class of bug (fixed S190) only bites when stdout is a legacy/captured stream. Record whether you're on UTF-8-capable Windows Terminal vs legacy conhost — reds can differ.

---

Phase 1 — Clean install ⬜

#	Step	Expected	Watch
1.1	Fresh clone or wheel copy onto the box	files present	—
1.2	Run setup.sh (or pip install -e ".[dev]")	exits 0; .venv created with pip	⚠️ Windows .venv symlink WinError 1314 — needs os.symlink guarded w/ copy/junction fallback (DPLAN-0194 gap)
1.3	drone --version and aipass --version	both print a version, exit 0	⚠️ .venv/bin vs Scripts path resolution

---

Phase 2 — Automated wiring (run the e2e suite on the real box) ⬜

#	Step	Expected
2.1	pip install build pytest	installed
2.2	python -m pytest tests/e2e -v	14 passed (T0 install / T1 init scaffold / T2a hook fire / T3 drone routing)

This re-runs the CI gate on real hardware. If CI is green but this is red, the difference is the machine (real console, real paths) — exactly what we're hunting.

---

Phase 3 — aipass init (real scaffold + interactive) ⬜

#	Command	Expected	Watch
3.1	aipass init /tmp/demo demo (Win: a temp path)	creates DEMO_REGISTRY.json, .aipass/, .claude/settings.json, src/demo/ + prints ✓ Project initialized	⚠️ cp1252 banner crash (fixed S190 — verify it stays fixed)
3.2	aipass init run --dry-run	shows the 11-stage plan, no writes	—
3.3	aipass init run --non-interactive (in a throwaway dir)	completes all stages headless	⚠️ symlink/daemon steps
3.4	aipass init run (interactive, manual)	prompts render + accept input; completes	⚠️ interactive PTY — never machine-tested; pexpect territory
3.5	aipass doctor	health report renders, exit 0	—

@aipass is its own process — the user-facing concierge / onboarding CLI (init, doctor, scanner). It's the front door you run to bootstrap a project, so it's invoked directly as aipass … and is by design not routed through drone @aipass (unlike the other 12 branches).

---

Phase 4 — drone routing ⬜

#	Command	Expected
4.1	drone systems	lists all registered branches + modules
4.2	drone @ai_mail --help	help text, exit 0 (real registry-branch subprocess — the T3 path)
4.3	drone @seedgo --help	help text, exit 0 (in-process module path)
4.4	drone @ai_mail inbox	inbox renders (empty is fine)

---

Phase 5 — Daemons / background processes ⬜

#	Command	Expected	Watch
5.1	drone @ai_mail dispatch @devpulse "x-os test" "ping" then drone @ai_mail inbox	mail sent; target woken	⚠️ start_new_session= POSIX kwarg in ai_mail/flow daemon spawn
5.2	drone @devpulse watchdog --help then arm a watchdog	polls lock, exits clean	⚠️ os.kill POSIX-only; inotify vs Win file-watch
5.3	drone @prax monitor (then quit)	live dashboard renders	⚠️ interactive / curses-style on Win

---

Phase 6 — Hooks + sound ⬜

#	Step	Expected	Watch
6.1	Trigger rm_gate (attempt a raw rm -rf via the agent / fire the bridge)	blocked; src/aipass/hooks/logs/engine.jsonl gains a record	—
6.2	A hook with sound fires	audible cue plays	⚠️ aplay is Linux-only — needs afplay (macOS) / winsound (Windows)
6.3	drone @hooks status	per-project hook config renders	⚠️ hardcoded /tmp paths
6.4	drone @hooks hooksound (mute/unmute)	toggles without error	—

---

Phase 7 — Interactive layer (manual, hardest to automate) ⬜

#	Step	Expected	Watch
7.1	Launch an agent session in a terminal	starts, prompt usable	⚠️ tmux (Linux/mac) vs Windows terminal multiplexer
7.2	aipass init run full interactive (if not done in 3.4)	all 11 stages accept input	⚠️ PTY/pexpect
7.3	Any prompt-driven flow (--bypass/flags where available)	bypassable for headless	—

---

Per-branch smoke matrix (all 13 branches)

Run each branch's drone @<branch> --help first (the universal resolve → subprocess → execute → print proof), then the listed read-only commands. ⚠️ = mutates state / side-effect — run only deliberately. Every command should exit 0 and render readable (non-mojibake) output on the OS under test.

† aipass is the exception — it's the standalone user-facing concierge CLI, invoked directly (aipass …), not routed through drone. So it has no drone @aipass --help row; smoke it with the aipass command itself. The other 12 branches all route through drone.

Branch	--help ⬜	Read-only smoke	Side-effect (run deliberately)
drone	⬜	drone systems · drone list · drone --version	drone scan @<b> · drone activate @<b>
seedgo	⬜	drone @seedgo audit · drone @seedgo standards_query · drone @seedgo diagnostics	drone @seedgo audit aipass (full scan)
prax	⬜	drone @prax status · drone @prax dashboard · drone @prax log-audit	drone @prax monitor (interactive)
cli	⬜	drone @cli · drone @cli display · drone @cli templates	drone @cli display demo
ai_mail	⬜	drone @ai_mail inbox · drone @ai_mail sent · drone @ai_mail contacts	⚠️ dispatch / email / reply / close
api	⬜	drone @api status · drone @api stats · drone @api models · drone @api list-providers	⚠️ get-key / validate / call (touch keys/network)
flow	⬜	drone @flow list · drone @flow list open	⚠️ create / close / restore / aggregate
spawn	⬜	drone @spawn --help · drone @spawn sync-registry	⚠️ create / update / delete (use --dry-run)
trigger	⬜	drone @trigger errors · drone @trigger core	⚠️ medic toggle
memory	⬜	drone @memory search "test" · drone @memory verify	⚠️ rollover · watch (daemon)
aipass †	(n/a)	aipass --version · aipass --help · aipass init --help · aipass doctor	⚠️ aipass init … (scaffolds)
hooks	⬜	drone @hooks status · drone @hooks engine	⚠️ hooksound (mute) · claude (bridge)
devpulse	⬜	drone @devpulse feedback · drone @devpulse watchdog --help	⚠️ watchdog agent @<b> (arms wake)

---

Known cross-OS gap registry (living — update as fixed)

Tracks every confirmed/suspected portability gap so a red here is "expected, tracked" not a mystery. Source of truth: DPLAN-0194. Status: ✅ fixed · 🔧 owner assigned · ❓ suspected/untested.

#	Gap	OS	Symptom	Owner	Status
1	cp1252 stdout + Rich in CLI entry points	Win	UnicodeEncodeError('charmap') on aipass init banner & drone @branch print	aipass/drone	✅ S190 (reconfigure(utf-8) at entry)
2	.venv symlink	Win	setup.sh/init → WinError 1314 (no symlink priv)	aipass	❓ untested (CI left AIPASS_HOME unset)
3	start_new_session= kwarg	Win	daemon spawn throws (POSIX-only)	ai_mail / flow	❓
4	os.kill	Win	watchdog / daemon stop throws	flow + others	❓
5	.venv/bin vs Scripts	Win	path resolution misses console scripts	memory / drone / ai_mail	❓
6	hardcoded /tmp	Win	scratch-dir writes fail	hooks / seedgo	❓
7	aplay-only audio	Win/mac	hook sound silent / errors	hooks (+ template hooks)	❓ (mac needs afplay, Win winsound)
8	shell=True usage	Win	quoting/semantics differ	hooks	❓
9	route_command masks errors	all	real exceptions printed as "Unknown command"	aipass	🔧 recommended (not fixed — hid gap #1 for hours)

@seedgo's windows_compat_check.py already scans for several of these statically — extending it to flag the cp1252/entry-point pattern (#1) and the aplay//tmp/os.kill patterns is P2.

---

Run Record (copy one block per machine/run)

─────────────────────────────────────────────
AIPass Cross-OS Run Record
Machine/VM   :
OS + version :
Arch         :
Python       :
Shell / term :
AIPASS_HOME  :
Commit (drone @git log -1) :
Tester       :            Date :
─────────────────────────────────────────────
Phase 0 env capture .......... ✅ / ❌
Phase 1 clean install ........ ✅ / ❌   notes:
Phase 2 e2e suite (14/14) .... ✅ / ❌   notes:
Phase 3 aipass init .......... ✅ / ❌   notes:
Phase 4 drone routing ........ ✅ / ❌   notes:
Phase 5 daemons .............. ✅ / ❌   notes:
Phase 6 hooks + sound ........ ✅ / ❌   notes:
Phase 7 interactive .......... ✅ / ❌   notes:
Per-branch matrix (13) ....... ✅ / ❌   reds:
─────────────────────────────────────────────
New gaps found (file + assign):

Overall verdict: PASS / PARTIAL / FAIL
─────────────────────────────────────────────

---

Layer 3 of cross-OS confidence. Pairs with tests/e2e/ (layer 2) and drone @seedgo Windows-compat scan (layer 1). See DPLAN-0194 for the full strategy.