Investigate Linux support

[raiseCatError]

Status (updated at the v0.16 feature freeze)

Done: the Linux baseline and hardening (#279, #281, #284) and v0.16 Linux/WSL work run the canonical suite on Ubuntu 24.04 (Node 22/26) in CI; findings are in docs/architecture/v013-linux-foundations.md.

Remaining scope (physical): the "attempt to run NMSh on a Linux machine or VM" acceptance item: install/build, launch with real zsh, sessions, notifications (notify-send), clipboard (wl-copy / xclip), and WSL 2 under Windows Terminal. CI on Ubuntu is not physical validation.

Goal

Investigate what would be required to run NMSh on Linux, and whether the existing architecture translates cleanly.

Why

Linux is the preferred first non-macOS platform because the POSIX PTY and zsh model maps naturally to the NMSh architecture. There are no fundamental architectural barriers, but testing and packaging have not been done.

Research scope

• Does the PTY/zsh session work on Linux without modification?
• Are there Node.js PTY library differences on Linux?
• Are there any macOS-specific APIs in NMSh that need Linux equivalents?
• What terminal hosts are relevant for Linux testing (GNOME Terminal, Konsole, Alacritty, Kitty, WezTerm)?
• What packaging/distribution approach makes sense for Linux (AppImage, Flatpak, Snap, AUR, deb)?
• Are there any keyboard protocol or ANSI handling differences to test?

Non-goals

• Full Linux release in this issue
• CI infrastructure for Linux (separate concern)

Acceptance criteria (research)

• Document: what works today on Linux with no changes
• Document: what requires changes or investigation
• Rough estimate of porting effort
• Recommended first Linux terminal host to target

Human verification

• Attempt to run NMSh on a Linux machine or VM
• Document results

Dependencies

None blocking.

Rough effort

Research: 1 day; initial porting pass: unknown until research complete

[raiseCatError]

Research findings (no Linux execution performed)

Portability inventory. Current package is Node >=22 plus node-pty, Ink/React and string-width. node-pty documents Linux support; its Linux PTY backend uses forkpty APIs, so the core interactive zsh/PTTY model is a credible port, but still needs Linux install/build/runtime verification: https://github.com/microsoft/node-pty#readme. NMSh already has an XDG-aware config helper and Ghostty config paths, but session socket placement is tmpdir()/nmsh-, clipboard is hard-coded to pbcopy, and several UI/provider flows advertise or invoke Homebrew. Process-group signaling and raw-mode restoration require host/runtime validation.

XDG and macOS-specific assumptions. On Linux, use absolute valid XDG_CONFIG_HOME for config (fallback ~/.config), XDG_STATE_HOME for durable journals/transcripts (fallback ~/.local/state), and XDG_RUNTIME_DIR for private sockets when present and valid; the spec describes runtime files including sockets and requires private user runtime semantics. Validate owner/mode and do not trust an invalid env path; provide a private per-user temp fallback where the variable is absent. https://specifications.freedesktop.org/basedir/0.8/ Existing state/history paths and config migration need inventory before adopting XDG so existing user data is not silently orphaned. macOS assumptions include pbcopy, ~/Library/Application Support, /opt/homebrew and Homebrew-only install/update paths; /tmp debug output and shell executable paths also need review. Homebrew messaging can become distro/package-neutral or host an optional installer rather than being generalized as the Linux package manager.

Effort and compatibility outlook (inference): easy: Node/node-pty POSIX baseline, path utilities, zsh if installed, ANSI model. Medium: XDG state/runtime policies; clipboard providers (wl-copy, xclip/xsel with clear no-provider behavior); notifications; package/update strategy; terminal keyboard capability negotiation; missing fonts/glyph fallback. Hard/unknown: distribution-maintained packaging/update channels, broad terminal-host keyboard/resize/selection compatibility, and physical validation. Suggested matrix: GNOME Terminal as initial baseline; Konsole, Kitty, Ghostty, WezTerm, foot as follow-up hosts. Test common Linux distributions and Wayland plus X11 clipboard environments; terminals are host capabilities, not OS guarantees.

Sequence/recommendation. First run an unmodified source checkout on a Linux VM with zsh and a supported terminal; record startup, input, resize, passthrough, clipboard and glyph results. Then implement filesystem/runtime and clipboard/provider abstractions; add Linux CI/build coverage; choose one packaging channel only after a user/distribution target is selected; expand terminal matrix. Research suggests a bounded first port is plausible, but no support claim is verified here. Enter roadmap after a Linux maintainer/user and target install/update channel exist; plan an initial compatibility pass, not a universal Linux promise.

[raiseCatError]

Execution follow-up: Linux environment unavailable

I could not produce Linux execution evidence from this session. The execution host is macOS, not Linux, and no Linux container runtime or VM is available here: docker info failed because the docker executable is absent, and podman info likewise failed because podman is absent. The command environment also reports not a tty, so it cannot provide a Linux terminal emulator/PTY session.

Environment observed:

• OS/kernel: Darwin 27.0.0 (xnu-13432.1.9~1), host Darwin Jais-MacBook-Air.local
• Architecture: arm64
• Node: v26.8.1; npm: 11.19.0
• zsh: 5.9, built for arm64-apple-darwin26.0 (not a Linux zsh)
• Terminal/PTY: no Linux terminal or PTY available; tty reports not a tty

Commands run for this environment check: uname -a, node --version, npm --version, zsh --version, tty, docker info, and podman info. I did not run dependency installation, build, typecheck, tests, CLI startup, PTY/session behavior, resize, job-control, or XDG-path checks under Linux. Running them on this macOS host would not satisfy the Linux execution requirement, so Linux compatibility remains unverified. No Linux terminal-host compatibility claim is made.

[raiseCatError]

Current-source research above frozen #278 confirms Linux is feasible without replacing the persistent real-zsh/PT Y architecture. Implementation child: #279; milestone #13.

• node-pty 1.1.0 uses Unix PTYs on macOS/Linux. The installed package has macOS/Windows prebuilds but no Linux prebuild: Ubuntu needs Python/make/C++ for native compilation. Linux CI must prove the installed binding, not just TypeScript.
• ShellSession, POSIX process groups/signals, authenticated command markers, socket service, composer/transcript/history and detached helper boundaries translate directly. Existing real-PTY tests cover interrupt/suspend, resize, alternate-screen bytes, completion and detach/reattach.
• Changes justified: executable zsh discovery with factual missing-shell error; secure private XDG_RUNTIME_DIR selection with short Unix-socket fallback; remove macOS-only assumptions in platform-neutral test expectations. Keep macOS data paths unchanged.
• macOS-only features are isolated: osascript notifications and Terminal.app window launching are optional. Linux notifications remain no-op; desktop notification parity does not justify adding dependencies. Ghostty/kitty launch adapters stay bounded and best-effort.
• Linux config uses existing ~/.config/nmsh or XDG_CONFIG_HOME. Journals retain existing persistence location; no gratuitous data migration. Private temp roots use Node os.tmpdir; session sockets need short paths. POSIX uid/0700 ownership checks remain required.
• Host profiles are capabilities: Kitty/WezTerm retain known hints; GNOME Terminal/Konsole/Alacritty/unknown use conservative baseline plus protocol evidence. First physical target: Kitty, then GNOME Terminal baseline. No physical host support claim.
• Initial installation: source checkout, Node >=22, zsh, native build tools, npm ci/build/link. package private=true means npm registry/global package publication is not currently available; source npm link is appropriate now. Homebrew Linux/deb/rpm/AUR require packaging maintenance; AppImage/Flatpak/Snap add no necessary CLI capability. No installer child justified.
• Estimate: small portability pass plus hosted runtime verification (days, not a new backend); physical terminal QA is additive and deferred. Linux runtime success remains pending CI evidence, not assumed from this audit.

Primary dependency reference: https://github.com/microsoft/node-pty/tree/1.1.0
XDG specification: https://specifications.freedesktop.org/basedir/latest/
#18 remains open because physical Linux validation is deferred.

[raiseCatError]

v0.13 Linux development evidence is now available in the unmerged stack: #278 → #280 → #282 → #283. Milestone #13; children #279 (Linux baseline/CI) and #281 (hardening).

• Existing node-pty 1.1.0 Unix PTY + persistent real zsh works on Ubuntu 24.04. Native binding installation, startup, completion, session persistence, transcript/history, signals, resize, passthrough and detach/reattach ran through the canonical suite. zsh is required; no bash fallback.
• Narrow changes: executable zsh discovery, private/short XDG runtime selection, absolute config fallback, literal HOME quoting and absent-HOME guards, factual Status diagnostics. macOS paths and notification behavior are retained; Linux notifications no-op safely.
• Hosted global completion permissions needed CI-only repair with compaudit still enabled. Slow bootstrap exposed submitted-command and replay lifecycle defects; fixed above the frozen base. PTY chunk boundaries exposed an invalid fixture assumption about retained tails after the cap; bounded retention, factual truncation and lifecycle remain verified.
• Implementation CI: macOS/Linux Node 22/26 all green, 868 tests per lane; macOS 860 pass/8 optional skips, Linux 864 pass/4 skips; no failures or process leaks. Final acceptance docs: v0.13 portability acceptance and deferred physical QA #283 reruns these lanes with transcript presentation timings.
• Packaging: source npm ci/build/link is the maintainable initial path. private:true currently prevents registry publication. No distro packaging child is justified. First later physical hosts: Kitty then GNOME Terminal baseline.

Detailed Linux findings, acceptance evidence, additive physical QA. Correct pinned dependency reference: node-pty v1.1.0.

This is a development baseline, not a Linux release. Physical QA remains deferred. No merge or issue closure; #18 stays open.

[raiseCatError]

Final cumulative head: docs/v013-cumulative-acceptance / e325bb30628b120837c28dd10d569e85ec7b0a12, PR #283.

Final CI run 37034562724 is green in all four lanes: macOS and Ubuntu 24.04 on Node 22/26. Each ran 868 tests, zero failures; macOS 860 pass/8 optional skips, Linux 864 pass/4 skips. Build, typecheck, benchmark typing, timing/presentation probes, diff and process-leak gates passed. Local macOS 868/868 passed, with no process/helper-temp/private-runner-root leftovers.

Final Node 26 p50 timings (macOS / Linux, ms): PTY 34.24 / 290.97, service 275.40 / 467.22, cleanup 11.44 / 10.37, completion cold 367.32 / 393.19, warm 34.09 / 6.92, transcript presentation 10k 43.37 / 26.19 and 100k 442.92 / 300.38. These are workload-specific observations, not cross-OS equality requirements. Existing history latency and readiness/cleanup bounds passed.

Review order: #278 → #280 → #282 → #283. Every PR targets its predecessor; all remain open/unmerged. #278 stays at cfc9c08. Package/lockfile 0.7.0; no merge/tag/release.

Physical QA remains intentionally deferred. Follow docs/testing/v013-physical-qa.md; issues requiring it stay open with needs-human-test. Ubuntu CI does not establish physical terminal or WSL/native Windows support. Project updates lacked read:project access; issue/PR activity and labels provide the durable handoff.

[raiseCatError]

Code and CI for Linux and WSL shipped in v0.17: Ubuntu 24.04 full suite plus a Fedora subset, XDG paths, package-manager plans, xdg-open/wslview, clipboard and notification fallback order, WSL detection fixtures (#309, #312). No physical Linux or WSL 2 session was used; that validation is tracked in #311. Closing this issue as implemented.