4top 0.2.0a1__tar.gz

4top-0.2.0a1/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+## 4top 0.2.0a1 — 2026-09-26
+
+The first release of the session-first line: 4top tracks transcripts rather than
+processes, and reaches other machines over ssh. The previous line owned a process
+per launch and reported liveness; that layer and its vocabulary are gone.
+
+### Breaking: 4top tracks sessions, not processes
+
+A native agent is recoverable from its transcript alone, so the transcript is the
+durable object and the process is the ephemeral one. 4top now keeps only
+transcripts: it does not own, supervise or report on a process, and it drives no
+terminal multiplexer of its own.
+
+- Deleted: the process-ownership layer and everything that existed to support it
+  — launch records, reservations, locks, the operation log, ownership markers,
+  exit-code and zombie evidence, the liveness states, and the commands, options
+  and `[runtime]` configuration section that reached into it.
+- `new` runs the agent in the calling terminal: the CLI replaces itself with the
+  agent (`execvpe`), and the TUI suspends, waits and returns to the panel. Keeping
+  work alive across a disconnect belongs to whatever the user already runs.
+- `list --json` rows are `schema_version` 2 and carry `key`, `agent`, `host`,
+  `cwd`, `title`, `started`, `last`, `source`, `status`, `problems` and
+  `can_resume`. Consumers of the previous row schema must be updated.
+- Local history is shown by default. The old view-schema `history` flag is
+  ignored and the view file is written as schema 3.
+- Nothing needs migrating: state is now a local identity plus the last selection.
+  Earlier files under `$XDG_STATE_HOME/4top` are ignored and can be deleted. A new
+  local identity changes history keys, so anything that copied a key must copy it
+  again.
+
+### Remote hosts over SSH
+
+- Add `[hosts.NAME]` with `ssh`, `command`, `refresh_seconds` and
+  `timeout_seconds`, plus the global `--host` option. Views are isolated:
+  `--host` replaces the local scope instead of merging machines into one table.
+- The remote side is the same CLI, with no daemon and no new port. It runs with
+  `BatchMode=yes` (a missing key fails fast), a `ControlMaster` socket inside
+  private state, and a hard timeout; every remote argument is quoted for the
+  remote shell.
+- A row whose `schema_version` differs is refused instead of partially parsed. A
+  remote row is relabelled with the configured host name, and its history key
+  stays opaque so it is never recomputed on the wrong machine.
+- `resume` and `new` with `--host` hand the terminal to `ssh -t`, so the process
+  is created on the machine that owns the history.
+- `H` switches the running panel between this machine and a configured host, so
+  comparing two machines no longer means quitting and relaunching. Rows, selection
+  and search state are dropped with the old scope, an in-flight refresh for the old
+  scope is discarded, and the saved selection stays local.
+
+### Releases
+
+- Publish one project per repository. The first attempt to publish both from this
+  workflow failed with `403 Invalid API Token: OIDC scoped token is not valid for
+  project '4top'`: one job means one OIDC exchange, and the token is scoped to the
+  project its publisher matched. Rather than disambiguate two publishers with two
+  environments, this workflow now publishes only `4top` and consumes `session-ls`
+  from PyPI, which is the layout the two packages actually have: separate projects,
+  separate version lines, separate pipelines.
+- Publish from CI on a `v<version>` tag: the suite runs, `scripts/check_release.py`
+  gates the release, both wheels are built and installed into a fresh environment,
+  `session-ls` is published before `4top`, and the GitHub release is opened. Uploads
+  use PyPI trusted publishing, so no token is stored in the repository, and the
+  manual trigger defaults to a dry run.
+- The gate refuses a tag that does not match the version, artifacts that are not the
+  versions being released, and a root requirement the library cannot satisfy. That
+  last one is real: the root requires `session-ls>=0.2.0` while PyPI only ever held
+  0.1.0, so publishing the root alone would have produced an uninstallable package.
+
+### Interface
+
+- The host picker (`H`) switches the panel between this machine and a configured
+  host, so comparing two machines no longer means relaunching.
+- The selection line is context and one action: `agent · directory` and what Enter
+  does. The history key moved to the details screen, where it is needed, and the
+  status line says nothing when there is nothing to report.
+- A recorded directory that no longer exists now names itself, is marked in the
+  details screen, and asks for a directory to resume in instead of failing with
+  "not accessible".
+- The mouse wheel moves the highlight with the view instead of scrolling the
+  viewport away from it.
+- Resume preflights first. `4top check KEY` reports whether a session can resume
+  here, and the panel asks before it hands over the terminal, so a host without
+  that agent installed is a visible message instead of a failure that flashes past
+  under a repainted screen. A hand-over that still fails reports its exit code, and
+  a dropped ssh connection says that the session is unchanged in its transcript.
+- The ssh connection keeps a liveness probe and a warm control connection, so an
+  unstable link fails instead of hanging.
+- `doctor` reports the `revision` of the code it is running, and `--host NAME doctor`
+  reports both, so two machines on different revisions is visible instead of turning
+  into a confusing error later.
+- `scripts/remote_update.py NAME` brings a remote's 4top forward. It uses the host's
+  own egress first and, only if that fails, lends this machine's proxy through a
+  reverse tunnel that lives exactly as long as the update. Both hosts were observed
+  with a proxy that answers on one port and fails on another, or works and then stops,
+  so the fallback is a real case and it says which one it used.
+- `scripts/check_docs.py` fails when the documentation stops describing the code,
+  and runs in a pre-commit hook, the test suite and CI.
+
+### Fixes in this line
+
+- A large history no longer costs a full re-render on every refresh. Rows whose
+  inputs are unchanged keep their rendered cells and their derived labels, so a
+  2.7k-row store renders in under two milliseconds per tick instead of about 50 ms.
+- Recognize Claude 2.1.x metadata-only session files. Claude prepends records such
+  as `last-prompt`, `mode`, `attachment` and `cost-state`, and a session that was
+  opened, renamed and quit never writes a user or assistant message; those files
+  were reported as `ValueError` instead of being listed. Identity now comes from
+  the `sessionId` these records carry, and the native `ai-title`/`agent-name` is
+  used as the title only when the session has no user text. `PARSER_VERSION` is 2
+  in both parsers, so the first scan after upgrading re-reads every file once.
+- Report why a history file was rejected, not only the exception class, and keep
+  OSError text (which contains the private path) out of the message.
+- Print the human table without the terminal UI stack. Display width is computed
+  with `unicodedata`, so `4top list` works where only the standard library is
+  installed. Found by running the CLI on a host that had neither the UI dependency
+  nor a package manager to add it.
+- Stop reporting a non-directory that a history pattern matched as an
+  unavailable directory. A real store keeps a marker file inside its project
+  directory, so every scan reported an issue and every list exited 6. A configured
+  root that is not a directory is still reported once, and a genuinely unreadable
+  directory is still reported.
+- Stop reporting a remote login banner as a query issue. Only diagnostics prefixed
+  by the remote CLI count, so a healthy host no longer looks broken and no longer
+  exits 6. Found by pointing `--host` at a machine whose ssh shell prints a banner.
+- Correct the acceptance record: Pi 0.87.0 is installed on the acceptance Mac and
+  its capability probe passes. No authenticated Pi smoke check was run, and the
+  previous "not installed" statement was wrong.
+
+## 4top 0.1.0a2 — 2026-09-24
+
+- Preserve absent native store environment overrides. In particular, launching
+  Claude no longer relocates its default configuration and triggers onboarding
+  for an already-authenticated installation. Explicit profiles still take priority.
+- Add 13 native-root regression cases covering all three agent drivers.
+- Explain that resume uses current native configuration, not replayed launch flags.
+- Validate 141 automated tests on macOS 27.0 arm64, plus a separate authenticated
+  Codex 0.155.1 exact-resume smoke check.
+- Add 32 regression cases hardening the then-current process-ownership layer
+  against exit races, PID reuse and malformed ownership data.
+- Establish the independent `4ier/4top` repository and fresh-wheel installation.
+- Keep Pi, other native versions, physical SSH loss and Linux native validation
+  explicitly outside this release's compatibility evidence.
+
+See [the Mac acceptance record](docs/validation/macos-0.1.0a2.md).
+
+## 4top 0.1.0a1 / session-ls 0.2.0
+
+- Initial keyboard-first TUI and scriptable CLI over a shared service layer.
+- Exact-target process management, bounded previews, safe destructive actions,
+  explicit history linking and same-history reservations. That layer is not part
+  of the current line; see the unreleased section above.
+- Experimental Claude/Codex/Pi exact resume drivers; read-only Cursor history.
+- Private atomic state, no extra daemon, no account.
+- Literal Unicode full search, cancellation, stable selection, no-color, isolated demo.
+- Real process and terminal tests alongside core and headless UI tests.
+- session-ls keeps its six-field JSON interface and independent stdlib-only package.
+  Imports no longer change SIGPIPE; full search now follows documented literal
+  semantics instead of accidentally interpreting a grep regular expression.
+- Cached file identity includes parser version and inode metadata; cache writes use
+  unique temporary names. Corrupt caches are rebuilt rather than silently trusted.
+
+This alpha does not certify authenticated native CLI compatibility, all minimum
+platform versions, cross-machine aggregation, or external-user usability gates.

4top-0.2.0a1/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to 4top
+
+Start with a reproducible bug or a small adapter fixture. The project intentionally
+leaves process ownership, persistence and multiplexing to the user and to the
+original CLI; proposals for agent loops, cloud accounts, semantic state guesses,
+process supervisors or automatic privilege bypasses are outside this release.
+
+## Development
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ./packages/session-ls -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+git config core.hooksPath .githooks   # once per clone: run the gates before commit
+```
+
+`scripts/check_docs.py` fails when the documentation stops describing the code: an
+undocumented command or key, a documented command that no longer exists, a missing
+configuration option, a broken relative link, or vocabulary from a design that has
+been removed. It runs in the pre-commit hook, in the test suite and in CI, so a
+stale README blocks the change instead of misleading the next reader.
+
+To make the `4top` command itself run this checkout, install it as an editable
+tool. Otherwise a previously installed copy keeps running older code, which looks
+like a bug in the change you just made.
+
+```sh
+uv tool install --force --editable .   # both packages stay live
+```
+
+No multiplexer is required. `tests/integration` starts real fake agents as real
+processes and asserts their argv, cwd, environment and written session file; the
+remote tests use a fake `ssh` on `PATH` instead of a network. Tests never access the
+developer's native HOME/store or the real state directory. Unexpected external
+pytest plugins can be excluded with
+`PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -p pytest_asyncio.plugin`.
+
+Use `requirements-dev.lock` to reproduce the tested development dependency set.
+The root package and session-ls have independent distribution metadata; do not put
+both console scripts into the root wheel or create a circular dependency.
+
+## Required evidence
+
+A PR explains the user-visible change, safety boundary, tests, actual environment,
+uncovered cases and rollback. Adapter PRs include synthetic/redacted fixtures and
+an exact native CLI version with capabilities split into history/new/resume.
+No arbitrary plugin code is loaded from history or configuration.
+
+Acceptance must distinguish unit tests, headless Textual, real-process launch,
+remote transport and human usability tests. Do not turn a mock result into an authenticated smoke-test
+claim. Performance results name the dataset, machine, versions and measurement.
+No recorded workload needs to contain real customer data.
+
+Run and update the [acceptance guide](docs/validation/README.md) before a release.
+Export the synthetic UI with `python scripts/export_demo.py`; the result must say
+DEMO. It is not a real-CLI demonstration or a performance benchmark.
+
+## Release
+
+Publishing is a tag; CI does the rest. PyPI versions are immutable, so a gate runs
+before anything is uploaded.
+
+1. Set the version in `pyproject.toml`, and in `packages/session-ls/pyproject.toml`
+   when the parser changed, and update the changelog.
+2. Check locally: `python scripts/check_release.py v<version>`.
+3. Tag and push: `git tag v<version> && git push origin v<version>`.
+4. CI runs the suite, gates the release, builds both wheels, installs them into a
+   fresh virtual environment, publishes `4top`, and opens the GitHub release.
+
+The gate is what stops the release that cannot work: the root wheel requires
+`session-ls>=0.2.0`, PyPI only ever held 0.1.0, so publishing the root alone would
+have produced a package nobody could install. A version already on PyPI is skipped
+rather than treated as an error, so re-running a release is safe;
+`python scripts/check_release.py --decide` says what would be uploaded.
+
+Uploads use PyPI trusted publishing, so no token is stored here. It needs one
+publisher on PyPI for the project `4top`, pointing at owner `4ier`, repository
+`4top`, workflow `publish.yml` and environment `pypi`.
+
+This repository publishes one project. `session-ls` has its own repository and its
+own pipeline and is consumed here as an ordinary PyPI dependency; publishing two
+projects from one workflow would need two jobs and two distinguishable publishers,
+because one job means one OIDC exchange and the minted token is scoped to the project
+its publisher matched. The
+manual trigger of that workflow defaults to a dry run, which rehearses the whole
+path without uploading.
+
+## Reporting
+
+Use the bug template and redact paths, prompts and credentials. For security issues,
+see SECURITY.md. Do not attach native auth files, raw production transcripts, or an
+unreviewed screen recording. No automated issue upload is performed by 4top.
+
+Code is MIT-licensed. Preserve attribution to the existing session-ls core. Keep
+English and Chinese README commands and limitations in sync.

4top-0.2.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4ier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

4top-0.2.0a1/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md README.zh-CN.md CHANGELOG.md CONTRIBUTING.md SECURITY.md requirements-dev.lock
+recursive-include docs *.md *.svg *.json
+recursive-include tests *.py
+recursive-include scripts *.py *.sh
+recursive-exclude * __pycache__ *.pyc

4top-0.2.0a1/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: 4top
+Version: 0.2.0a1
+Summary: Your coding agents, one terminal. Find, search and resume native sessions, locally or over SSH.
+Author: 4ier
+License-Expression: MIT
+Project-URL: Repository, https://github.com/4ier/4top
+Project-URL: Issues, https://github.com/4ier/4top/issues
+Keywords: coding-agents,terminal,session-history,claude,codex,pi,ssh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console :: Curses
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: session-ls<0.3,>=0.2.0
+Requires-Dist: textual<9,>=8.2.8
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.23; extra == "dev"
+Requires-Dist: pexpect<5,>=4.9; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Dynamic: license-file
+
+# 4top
+
+**Your coding agents, one terminal.**
+
+Find your work. Resume an exact native session. Reach your other machines over SSH.
+A keyboard-first terminal dashboard built on **session-ls**, with no extra 4top
+daemon, account, model calls, or telemetry.
+
+[中文](README.zh-CN.md) · [Compatibility](docs/compatibility.md) · [Remote hosts](docs/remote-design.md) · [Acceptance](docs/validation/README.md)
+
+![4top synthetic demo — no real user history](docs/demo/demo.svg)
+
+> **0.2.0a1 — alpha.** The current development line owns no process and drives no
+> multiplexer of its own. Codex **0.155.1** passed an authenticated exact-resume
+> smoke check against an earlier build;
+> Claude Code, Pi and other native versions are not certified.
+> [Evidence](docs/validation/macos-0.1.0a2.md). This release is not on PyPI.
+
+## Install from this checkout
+
+macOS or Linux; **Python 3.11+**. No multiplexer is required. Current validation
+records, rather than this minimum target, determine which versions were tested.
+Windows users need a Linux environment such as WSL; native Windows is unsupported.
+
+```sh
+git clone https://github.com/4ier/4top.git
+cd 4top
+python3 -m venv .venv
+.venv/bin/python -m pip install ./packages/session-ls .
+.venv/bin/4top --demo
+```
+
+Both local packages are intentionally supplied to pip: `session-ls 0.2.0` is not
+assumed to exist on a package registry. The root wheel contains only `fourtop`;
+the independent `session-ls` package retains its small, stdlib-only CLI.
+
+```sh
+. .venv/bin/activate
+4top                       # browse every session on this machine
+4top new codex             # start an agent here, in this terminal
+4top --host build-box      # view another machine over ssh
+```
+
+4top never installs or authenticates agents for you. Install the original Claude
+Code, Codex, or Pi CLI separately and keep its existing authentication flow.
+The panel also reads Cursor transcripts, but does not launch or resume Cursor.
+
+## The daily loop
+
+Open `4top` and you get every session on the machine, most recent first. Select a
+row and press **Enter**: 4top asks for confirmation and then runs the native CLI
+in this terminal to resume that exact session. Leave the agent and you are back in
+the panel. **`q` closes only the panel.**
+
+A plain terminal or any multiplexer you already run is equally fine: 4top starts
+the agent in the terminal it was launched from and never allocates a terminal of
+its own. If you want a session to survive closing your laptop, run 4top inside the
+multiplexer you already use.
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓`, `Enter` | Select and resume |
+| `H` | Switch the panel between this machine and a configured host |
+| `/`, `Enter`, `Esc` | Search metadata, return to table, clear/cancel |
+| `Ctrl-F` | Explicit literal full-content search; `Esc` cancels |
+| `Space`, `i` | Read-only preview, details |
+| `n`, `r`, `?` | New agent, refresh, help |
+| `q`, `Ctrl-C` | Close only the panel |
+
+Search supports case-insensitive words and quoted phrases; all terms must match.
+Full search decodes JSON text, including Chinese escaped as `\u....`. It reads
+only configured sources, reports partial scans, and never executes transcript
+content. The UI renders titles and previews as plain, sanitized text.
+
+## Sessions, not processes
+
+A native agent is a file. `pi --session <path>`, `claude --resume <id>` and
+`codex resume <id>` all work from the transcript alone, so the transcript is the
+thing 4top tracks, and the process is the ephemeral part.
+
+**Resume** starts a new native process from an exact ID or source path. It cannot
+restore lost memory, network connections, shell children, or a destroyed machine.
+Resume uses the CLI's **current native configuration**; 4top does not replay the
+original launch flags. Review native permissions before sending another task.
+
+Because 4top owns no process it claims nothing about liveness either: a row is a
+session you can resume, and that is all it says. Failed queries are reported as
+issues and never rendered as an empty machine.
+
+Two consequences worth knowing. A resumed agent is a **new** process; two agents in
+one directory still have **no code/worktree isolation**. And `4top new` runs the
+agent in the foreground of the terminal you launched it from: outside a multiplexer
+it ends with that terminal.
+
+## Remote hosts over SSH
+
+Point 4top at any machine you can already `ssh` into. There is no daemon to
+install, no port to open, and no credential store: the remote side is the same
+CLI, and the local 4top only runs it.
+
+```toml
+# ~/.config/4top/config.toml
+[hosts.build-box]
+ssh = "me@build-box"                 # any ssh destination, including a tailnet name
+# command = "/opt/4top/bin/4top"     # if a non-login PATH does not include 4top
+# refresh_seconds = 15.0               # slower than local: each tick is a round trip
+# timeout_seconds = 10.0
+```
+
+```sh
+4top --host build-box              # the whole panel, scoped to that host
+4top --host build-box list --json
+4top --host me@10.0.0.4 doctor     # an unconfigured target works too
+```
+
+Views stay isolated: the default scope is this machine, and a host replaces it
+rather than merging machines into one table. `H` switches the panel between them
+without leaving it; `--host NAME` starts the panel already scoped. Anything that starts a process runs
+**on that host** through `ssh -t`, so the resumed agent lives where its history
+lives; the remote CLI does the work and the local side only hands over the
+terminal. Connection reuse (`ControlMaster`) keeps refreshes cheap, `BatchMode`
+means a missing key fails fast instead of prompting, and a remote that speaks a
+different row schema is refused instead of partially parsed.
+
+Before it hands over the terminal, the panel asks the host that owns the session
+whether the resume can work there (`4top check`). A host without that agent
+installed, or a session whose directory is gone, is reported in the panel instead
+of failing during the hand-over, where the message would be painted over. The ssh
+connection also keeps a liveness probe, so a link that dies becomes an error rather
+than a hang, and the session stays in its transcript to be resumed again.
+
+## Command line
+
+```sh
+4top list --json                          # one JSON object per row
+4top list --agent pi --project 4top
+4top search 'retry "database timeout"'    # metadata match
+4top search '中文' --full                  # decoded full-content search
+4top preview h_<key>                      # one bounded read-only page
+4top check h_<key> --json                 # would a resume work here, and why not
+4top new codex -- --model MODEL           # native arguments after --
+4top resume h_<key> --yes                 # restore this process as the agent
+4top doctor --json
+```
+
+`doctor` also reports `revision`, and `4top --host NAME doctor` reports it for both
+sides, so a remote running older code is visible instead of failing later. Bring a
+remote forward with `scripts/remote_update.py NAME`; it uses the host's own egress
+first and falls back to a tunnel from this machine.
+
+`--config`, `--host` and `--no-color` work before or after the subcommand.
+`check` exits 0 when the session can resume here and 3 when it cannot. Keys
+may be shortened only when their prefixes are unambiguous (at least four
+characters). Row numbers are never execution targets. `list --json` rows carry
+`schema_version`, `key`, `agent`, `host`, `cwd`, `title`, `started`, `last`,
+`source`, `status` and `can_resume`.
+
+## Configuration and privacy
+
+Optional configuration: `$XDG_CONFIG_HOME/4top/config.toml` (default
+`~/.config/4top/config.toml`). No setup file is needed for standard stores.
+
+```toml
+[ui]
+refresh_seconds = 1.0
+history_refresh_seconds = 5.0
+color = "auto"                         # or "none"; NO_COLOR is also supported
+
+[history]
+metadata_max_bytes = 2097152
+metadata_max_lines = 2000
+preview_max_lines = 200
+
+[agents.codex]
+# root = "/absolute/path/to/codex-home"
+# executable = "/absolute/path/to/a-real-wrapper"
+```
+
+Agent store roots respect `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, and
+`PI_CODING_AGENT_DIR`; an explicit configured root wins. Selected history and
+launch profile must agree. Local state is private: `$XDG_STATE_HOME/4top` holds a
+local identity and your last selection, and `$XDG_CACHE_HOME/4top` holds
+rebuildable metadata. No environment values, prompt text, or transcripts are
+retained. The only network access is the ssh you configured.
+
+[Privacy](docs/privacy.md) · [Troubleshooting](docs/troubleshooting.md) · [Design](docs/design.md)
+
+## Develop and contribute
+
+```sh
+.venv/bin/python -m pip install -e ./packages/session-ls -e '.[dev]'
+.venv/bin/python -m pytest
+.venv/bin/python -m ruff check .
+uv tool install --force --editable .   # optional: `4top` runs this checkout
+```
+
+Tests use private temporary HOME/state directories and synthetic agents; the ssh
+tests use a fake `ssh` on `PATH`. No account credentials, network access or model
+calls are required. Record your OS, Python and native CLI versions when reporting
+compatibility. **Never post raw transcripts or tokens.**
+
+For fresh installation, CI, reproducible demo export, native smoke testing, and
+release gates, see [CONTRIBUTING](CONTRIBUTING.md) and the [acceptance guide](docs/validation/README.md).
+
+4top builds on 4ier's `session-ls` parsers and uses Textual. It is not affiliated
+with the vendors of the supported coding agents. **MIT licensed.**