fix: clarify doctor launcher diagnostics and strengthen store checks

[Pushkraj-Space]

Summary

moirai doctor labels desktop launch programs as ordinary executables, and its troubleshooting documentation says the Unix write-access check always succeeds for root. This follow-up to #19 makes launcher reporting explicit, treats close failures as failed readability checks, simplifies store-kind handling, and expands regression coverage for symlinks, permissions, environment overrides, and JSON omissions.

Implementation

• Label Claude Cowork and Cursor Desktop programs as launcher in human output. Preserve the programs returned by CommandFor: Cowork uses open on macOS, cmd on Windows, and claude-desktop on Linux; Cursor Desktop uses cursor.
• Continue using successful CommandFor(format, SessionRef{}) lookup as the sole gate for executable diagnostics. installed still means only that exec.LookPath found the launch program. Amp and Hermes report no executable status, even when similarly named binaries exist.
• Declare the file-backed formats explicitly (opencode, hermes) instead of coupling the kind check to concrete store implementations.
• Remove the internal writeChecked flag. Derive whether a write-status phrase applies from the completed readability check, the Save capability, and the expected root kind.
• Check the result of closing the root as well as opening it. Either failure produces readable: false and a store_unreadable warning.
• Preserve the inspection sequence: os.Stat → expected-kind check → os.Open and Close → eligible Unix write-access query. Symlinks to legitimate roots are followed; roots identified as FIFOs, sockets, devices, or the wrong kind are rejected before opening.

Tests

Area	Added or strengthened coverage
Registry metadata and ordering	Assert canonical format order in both JSON and human reports, and compare display names and capabilities with registry metadata.
Executable detection	Exercise an empty isolated PATH and fake executables for every supported launch command; verify missing-program warnings and desktop launcher labels.
Nullable fields	Assert omitted exists, readable, and writable keys on stat failure; omitted read/write checks for FIFO roots; no write status for file-backed or source-only stores; Windows write access remains unqueried.
Environment precedence	Exercise both overrides set, an empty higher-priority variable, and both variables empty; confirm default-root restoration and that a row does not expose the shadowed override value. Includes the Windows Cowork APPDATA case.
Symlinks	Accept symlinks to directories and regular files. A symlink loop produces store_stat_failed with unknown status. A regular-file target contains invalid database bytes to exercise root-only inspection.
FIFOs	Cover direct FIFOs and symlinks to FIFOs for both directory-backed Pi and file-backed OpenCode. Run doctor in a child process with a 10-second timeout so a regression can be terminated without leaving a blocked goroutine during environment cleanup.
Unix permissions	Confirm a healthy directory is writable and strengthen stat-failure key assertions. Retain mode-denial cases for unreadable, unwritable, and unsearchable directories; correct the root-skip explanation.
Output regression	Add an exact human formats fixture captured before the capability formatter extraction.

Existing tests continue to cover missing stores with successful command exit, wrong root types, read-only filesystem snapshots, terminal control-character scrubbing, and invalid doctor arguments. Doctor fixtures use temporary homes and stores, clear the store override variables, and replace PATH with an isolated fake-bin directory.

Documentation

Expand README troubleshooting with the six warning codes and corrective actions, a JSON example, optional-boolean semantics, override precedence, desktop launcher semantics, and the successful exit status for diagnostic warnings.

Explain that Unix writability uses access(2) with W_OK | X_OK and the process's real user/group credentials, while os.Open uses effective credentials. The write query is advisory: root can bypass ordinary mode bits, but a read-only filesystem can still reject it. Non-Unix platforms do not query writability; file-backed and source-only stores omit that status.

Verification

Run after rebasing onto current upstream main:

• go test -race ./...
• go vet ./...
• go run honnef.co/go/tools/cmd/staticcheck@2026.1 ./...
• go build -o /tmp/moirai-doctor-validation/moirai ./cmd/moirai
• GOOS=windows GOARCH=amd64 go test -c -o /tmp/moirai-doctor-validation/moirai-windows.test.exe ./cmd/moirai
• GOOS=darwin GOARCH=arm64 go test -c -o /tmp/moirai-doctor-validation/moirai-darwin.test ./cmd/moirai
• Byte-for-byte comparisons of both human and JSON formats output against the original main baseline.
• Go formatting and git diff --check.

Linux tests ran as a non-root user, including the mode-denial cases. Windows and macOS test binaries were cross-compiled, not executed locally. Native zsh/fish completion checks are unavailable in this environment.

Privacy and compatibility

Doctor remains read-only: it inspects and opens/closes store roots without enumerating directories, discovering or loading sessions, parsing transcripts, executing launchers, writing probes, or making network requests. Environment-variable values are not printed separately; the resolved root may still reveal all or part of the active override value. Human paths and warning messages remain terminal-scrubbed; JSON preserves their text.

The JSON field names and optional-value behavior introduced in #19 remain unchanged. Human output now calls desktop programs launcher, and readability warning text covers both open and close failures. The --json-only flag surface, shell completion, formats output, launch commands, store interfaces/registries, codecs, archive formats, and dependencies are unchanged by this follow-up. No compatibility layer, migration, or stored-data change is introduced.

Checklist

• I did not include credentials, private sessions, customer data, or internal documents.
• I added or updated tests for behavior changes.
• I updated public documentation or schemas when needed.
• I kept the change focused.

closes #10

[harshsaver]

Reviewed the production diff and diagnostics tests against current main. Launcher labels are accurate, filesystem checks remain read-only, and redundant writeChecked state is removed. Local race tests and vet passed; all platform/package CI checks are green.