Millmux

Millmux is a local, durable process and terminal multiplexer substrate. It starts and owns PTY or pipe-backed sessions, keeps their workers and children alive when clients disconnect, and exposes local control to operators, agents, and Millrace OS.

Millmux is not workflow authority. It does not own queues, tasks, approvals, incidents, policy, or completion semantics. Millrace OS is the normal human-facing control product and uses the versioned Millmux protocol instead of scraping local state or parsing CLI output.

This checkout is an intentionally reduced, breaking extraction baseline. It keeps the headless host, per-session workers, local protocol, and administrative CLI. It has no built-in cockpit, console, panes, UI contexts, monitor profile, attention state, or Millrace-specific session control.

Install

Build from this checkout with Rust 1.78 or newer:

cargo install --path crates/millrace-sessions --locked --force

The install-facing crate supplies three compatible binaries:

Binary	Role
millmux	Headless local administrative CLI.
millrace-sessiond	Local SessionControl host daemon.
millrace-session-worker	Per-session PTY or pipe worker.

The host starts on demand for control operations. Disconnecting a client does not stop its host, worker, or child process.

Current Session Surface

PTY sessions support input, resize, live attach/detach, raw-byte attach, and single-client input ownership. Pipe sessions provide durable lifecycle and separate stdout/stderr capture without terminal allocation. Roles are generic session metadata; custom roles are allowed.

The current CLI is:

# Start a durable PTY session.
millmux start --name shell --role shell -- sh

# Start a pipe-backed process with separate stdout and stderr evidence.
millmux start --spawn-mode pipe --name service --role generic -- sh -c 'exec my-service'

# Inspect and control generic sessions.
millmux list --json
millmux status shell --json
millmux inspect shell --json
millmux events shell --json
millmux attach shell --raw
millmux send shell --text 'status\n'
millmux resize shell --rows 30 --cols 100
millmux stop shell
millmux kill shell
millmux delete shell
millmux delete shell --purge
millmux doctor --json

delete archives a stopped session by default. delete --purge permanently removes an archived or stopped session. delete --kill is required when a running session must be removed.

Evidence And Current Omissions

Millmux records private session metadata, worker state, lifecycle events, and raw evidence files: pty.log for PTY sessions, or stdout.log and stderr.log for pipe sessions. The CLI does not currently provide log query or follow commands; inspect these retained evidence files through a supported consumer or during recovery.

Replay, scrollback/history, terminal snapshots, and structured screen reads are not currently provided. screen, logs, and replay flags are removed from the active CLI rather than retained as compatibility behavior. Future replacement surfaces must be rebuilt against the headless protocol rather than restoring the former cockpit-era design.

Use the CLI and doctor commands for operational changes. Do not hand-edit live state files.

Verification

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace -- --test-threads=1