Audit Agent OS for Windows support

Context

The Neo Agent OS (ai/ directory — MCP servers, SDK, build scripts, daemons) has grown organically under macOS/Linux development and CI. No explicit Windows dev or CI path exists. As the Agent OS stabilizes post-#9999 (Cloud-Native Knowledge & Multi-Tenant Memory Core Epic), Windows compatibility becomes a question worth answering systematically rather than fixing one CLI gate at a time.

This is the exploration tracker for that systematic audit. Blocked by #9999 — the right time to run the audit is once critical-path multi-tenant work stabilizes, not during current churn.

Triggering signal: concrete gap surfaced in PR #10131 self-review — backup.mjs uses import.meta.url === \file://${process.argv[1]}`` for its auto-run gate, which may not match Windows drive-letter paths. That's one line. A full audit would find dozens of similar one-liners.

The Problem

Systematic unknowns as of 2026-04-20:

1. Path handling — path.resolve vs. hand-built /-separated strings; POSIX path assumptions
2. Process invocation — process.argv[1] vs. file:// URLs; shell-dependent child_process calls; execSync('sh -c ...') availability
3. SQLite / native modules — better-sqlite3 native bindings build on Windows?
4. Chroma server — chroma binary (Python-packaged) Windows install path
5. Shell scripts — any .sh in buildScripts/? Or all .mjs?
6. Line endings — .jsonl emission, git core.autocrlf, test fixture round-trips
7. .env / dotenv — Windows home dir conventions
8. Tool limits — same Anthropic/Gemini MCP limits cross-platform (no concern)
9. WSL as escape hatch — does WSL coverage mostly solve this, or do we want native Windows?

The Architectural Reality

Audit scope:

• buildScripts/ai/** — all Node scripts
• ai/mcp/server/** — MCP server services
• ai/services.mjs — SDK boundary
• ai/daemons/** — offline cognitive pipelines
• test/playwright/** — test runner assumptions
• ai/scripts/** — bootstrap / telemetry / sync utilities
• package.json scripts — shell-piping / && / POSIX quoting

The Fix

This is an audit ticket, not an implementation ticket. Deliverables:

1. Structured report categorizing findings by severity (Blocker / Works-via-WSL-only / Minor / N/A)
2. Per-finding: file:line citation, reproducer, recommended fix (one-liner vs. architectural)
3. Decision: Windows CI matrix lane, WSL-only stance, or "no-op — WSL is sufficient"
4. If any Blockers / Minors warrant implementation: spawn per-fix tickets linked to this audit

Estimated: 1 full working session (exploration + report). Implementation of findings is separate follow-up work.

Acceptance Criteria

• Audit report document exists (location TBD — likely learn/agentos/WindowsSupport.md)
• Every scope area above has a finding
• Findings are severity-ranked
• Decision on Windows CI vs. WSL-only documented
• Per-fix follow-up tickets filed for any Blocker / Minor findings

Out of Scope

• Implementation of specific fixes — separate tickets per finding
• Frontend / GUI cross-platform concerns — Agent OS (Node/server-side) only
• Non-standard Windows shells (cmd.exe, PowerShell 5.1) unless evidence demands it

Avoided Traps

• Rejected: fix one-off Windows bugs as they surface. Firefighting leaves dozens of sibling issues undiscovered until a future user hits them. Systematic audit surfaces the full surface area.
• Rejected: run the audit now. During active #9999 churn the audit would compete for attention and miss things as the codebase shifts. Defer to post-#9999.

Related

• Blocked by #9999 (Cloud-Native Knowledge & Multi-Tenant Memory Core)
• Triggering signal: #10131 self-review note on file:// gate
• Prior art: learn/agentos/tooling/AiToolingWslSetup.md — implies earlier Windows-via-WSL consideration

Origin Session ID: 5a521819-dc75-4549-888e-fcea818d0401