Skip to content

refactor!: comprehensive cleanup — architecture, protocol, supervisor hardening#6

Merged
nazq merged 1 commit intomainfrom
cleanup
Mar 15, 2026
Merged

refactor!: comprehensive cleanup — architecture, protocol, supervisor hardening#6
nazq merged 1 commit intomainfrom
cleanup

Conversation

@nazq
Copy link
Copy Markdown
Owner

@nazq nazq commented Mar 15, 2026

Summary

  • Decompose monolithic main.rs into focused modules (cli, commands, config, terminal, pidfile, util)
  • Harden supervisor: two-line PID file with flock, /proc diagnostics on lock contention, strict stale socket cleanup, hard-fail on log creation
  • Protocol discipline: strict payload validation, golden byte tests, correct atomic ordering for EXIT broadcast
  • Add hm clean subcommand for orphaned log cleanup with retention window
  • Add log_filter config/CLI for per-crate tracing directives
  • Extract event_loop() from 130-line closure into standalone async fn
  • Eliminate hot-path allocations in pty read loop and socket write path
  • PTY primer docs with ASCII diagrams
  • 187 tests (126 unit + 61 integration), all passing

Test plan

  • cargo test — 126 unit tests pass
  • cargo test --test integration — 61 integration tests pass
  • cargo clippy -- -W clippy::all — zero warnings
  • PID file format validated with 14 unit tests (parse, edge cases, liveness)
  • hm clean validated with 4 integration tests (remove old, preserve young, dry-run default, skip live)
  • Duration parser validated with 10 unit tests
  • Golden byte tests assert exact wire format against protocol spec

… hardening

Decompose, harden, and document the entire supervisor stack.

- Decompose monolithic main.rs into focused modules: cli.rs (clap
  structs, config merge), commands.rs (status/list/kill/clean),
  config.rs (TOML loading, classifier config), terminal.rs (ANSI,
  status bar, termios guard)
- Per-classifier config: simple and claude classifiers carry their
  own parameters (idle_threshold_ms, debounce_ms) in the config
  enum, CLI flags override per-classifier fields
- Protocol boundary discipline: strict payload length validation
  (== not >=), golden byte tests asserting exact wire format against
  documented spec, catching symmetric pack/parse bugs that round-trip
  tests miss
- Atomic ordering audit: Relaxed→Release/Acquire for exit_code and
  alive flag, correct EXIT broadcast ordering (broadcast before
  alive=false to prevent subscribers seeing stale state)
- PID file abstraction (pidfile.rs): two-line format (supervisor PID
  line 1, child PID line 2), flock-protected, read/write/liveness
  API with 14 unit tests
- Consolidate scattered .sock/.pid path construction into
  util::socket_path() and util::pid_path()
- Extract die_session_locked() with PID retry loop, /proc diagnostics
  (uptime, cmdline), actionable error messages
- Harden stale socket cleanup: surface permission errors instead of
  silent failure
- Hard-fail on log file creation instead of silent /dev/null fallback
- Add log_filter config/CLI for per-crate tracing directives
- Extract event_loop() from 130-line closure into standalone async fn
- Add hm clean subcommand: orphaned log cleanup with --older-than
  duration (default 24h), dry-run by default, --force to delete
- Eliminate hot-path allocations: BytesMut zero-copy in pty read loop,
  pre-allocated frame buffer in socket write path
- PTY primer docs with ASCII diagrams (data flow, architecture,
  fork-exec sequence)
- Update ARCH.md with PID file format, flock lifecycle, module map
- Migrate Python attach tests to uv + pytest
- Pin rust-toolchain.toml to stable channel
- 187 tests (126 unit + 61 integration), all passing
@nazq nazq merged commit 2501077 into main Mar 15, 2026
6 checks passed
@nazq nazq deleted the cleanup branch March 15, 2026 01:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant