Phase 4: Usability & interface improvements

[schovi]

Enhancement

Batch of 14 usability, correctness, and ergonomic improvements across CLI, MCP, and daemon. Follows the Phase 4 section of the consolidated code review plan.

Solution

Each fix targets a specific UX gap or correctness issue. Changes are intentionally small and independent per item, touching the minimal surface area needed.

Changes

Timeout handling (4.1):

• exec and read (both CLI and MCP) return partial output on timeout instead of discarding it
• MCP responses include a warning field alongside partial output

Input validation (4.2):

• --cursor is rejected when combined with --snapshot or --follow (CLI + MCP)
• Cursor-advance errors after blocking read are now propagated instead of silently ignored

Info endpoint (4.3):

• info response includes cursors map showing all named cursor positions

Snapshot semantics (4.4):

• Snapshot no longer updates global ReadPos (pure peek, no side effects on normal reads)

Idempotent create (4.5):

• New --if-not-exists flag (CLI) / if_not_exists parameter (MCP) returns existing running session instead of error

List ordering (4.6):

• list returns sessions sorted by creation time (oldest first) instead of random map order

Error messages (4.7):

• Daemon startup failure now includes socket path, timeout duration, and troubleshooting hints
• Detects stale socket scenario

MCP settle semantics (4.8):

• settle_ms: 0 now means "don't wait" (previously treated as "use default 500ms")
• Uses *int to distinguish "not provided" from "explicitly zero"

Kill help (4.9):

• kill command help explains destructive behavior and suggests stop as alternative

SocketPath error handling (4.10):

• SocketPath() returns (string, error) instead of silently producing invalid path on UserHomeDir failure

Memory storage correctness (4.11):

• LoadMeta deep copies Cursors map and StoppedAt pointer to prevent shared mutation

Search display (4.12):

• Search output respects --strip-ansi flag for display (was unconditionally stripping)

Documentation (4.13):

• Removed stale --raw flag references from README (send always interprets escapes)
• Updated auto-detector skill to reflect TUI mode support for vim/htop

FileStorage (4.14):

• Removed redundant syscall.Flock from Append (Go mutex is sufficient for single-process daemon)

Root help (5.1):

• Added quick-start examples to shelli --help