agent-statusline 0.3.5__tar.gz

agent_statusline-0.3.5/.gitignore

@@ -0,0 +1,40 @@
+# Runtime state never belongs in the repo - it lives in the agent's config dir
+# (~/.claude by default, or $AGENT_STATUSLINE_STATE). Listed here anyway so a
+# stray test run with AGENT_STATUSLINE_STATE=. cannot commit a cost ledger.
+cost-ledger.json
+statusline-transcript.json
+statusline-probe-cache.json
+statusline-last-payload.json
+statusline-last-error.json
+rate-limit-history.jsonl
+hook-lastrun.json
+*.tmp
+__pycache__/
+*.pyc
+.DS_Store
+
+# hatch-vcs writes this at build time
+src/agent_statusline/_version.py
+.verify-state/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+
+# Private session handoff and local Claude project state. Kept out of Git on
+# purpose: it records account details, spend figures and session history that
+# must not enter a repository that may become public.
+/.claude/
+
+# Local private workspace state and linked worktrees. Keep all three root
+# boundaries even when only one is currently present.
+/.pvt/
+/.worktrees/
+
+# Coverage output from a local test run.
+.coverage
+.coverage.*
+htmlcov/

agent_statusline-0.3.5/AGENTS.md

@@ -0,0 +1,98 @@
+# agent-statusline project instructions
+
+This is a local-first, dependency-free Python status line for coding agents.
+The installed command is `agent-statusline`. Release versions come from Git
+tags through hatch-vcs; never duplicate a version string in source.
+
+## Start here
+
+- Read [HANDOFF.md](HANDOFF.md) completely before changing the repository.
+- Read the affected module, tests, ADRs, and field documentation before
+  changing behavior.
+- Treat this file as the only authoritative assistant instruction file.
+
+## Product invariants
+
+- Preserve the approved Claude Code display: ten rows in `ORDER`, with their
+  current fields and priority order. Do not remove, rename, reorder, or simplify
+  a row or field without explicit maintainer approval.
+- Keep runtime behavior local. No telemetry, analytics, runtime networking,
+  automatic downloads, or cloud fallbacks.
+- Keep runtime dependencies empty. The renderer is a frequent short-lived
+  process and must run with the Python standard library alone.
+- Never test cost paths against live state. Set `AGENT_STATUSLINE_STATE` to a
+  disposable directory before importing the package.
+- A currency-labelled claim must be exactly accountable. An exact lower bound
+  uses `≥`; do not silently present partial or estimated spend as a total.
+- Preserve lifetime session, rolling 24h/7d/30d, `last5`, and `all` cost fields.
+  Rolling-cost changes must retain seed, resume, timestamp, pruning, malformed-
+  evidence, and concurrent-redraw coverage.
+- Keep mutable state outside the repository. Coordinate every read-modify-write
+  transaction through the locked storage service, publish atomically, and use
+  private file permissions.
+- Installation and removal may mutate only this package's status line, hooks,
+  and checkout symlink. Preserve unrelated configuration and fail closed on an
+  unreadable or malformed existing settings file.
+- Keep width fitting deterministic and ensure no physical output line exceeds
+  the detected terminal-cell width.
+- Treat Codex as a separate widget-based host. Do not claim that this Python
+  renderer can run in Codex unless the installed Codex interface actually adds
+  an arbitrary-command status line.
+
+## Development workflow
+
+- Use uv 0.12 or newer. Commit `uv.lock` and manage development tools in
+  `pyproject.toml`; do not add requirements files.
+- Use Hatchling and hatch-vcs with standard PEP 621 metadata.
+- Start each short-lived `codex/<type>/<version>-<slug>` or
+  `claude/<type>/<version>-<slug>` branch from the preceding released state on
+  `main`, not from an unreleased integration branch.
+- Add or update synthetic, privacy-neutral pytest coverage with every behavior
+  change. Do not read or publish live ledger contents in tests or documentation.
+- Run the documentation verifier, locked all-files gate, subprocess-aware
+  pytest coverage, and build before requesting review.
+- Both hosted workflows are active. Full-scope pull requests and `main` pushes
+  automatically run the Linux Python matrix and representative macOS evidence
+  behind one aggregate required result. Do not dispatch a duplicate run when an
+  automatic run already proves the same SHA. Documentation-only changes run
+  only the ancestry audit and remain outside the full hosted gate.
+- Pin future workflow action updates to immutable commits. Do not weaken local
+  evidence when a hosted lane is intentionally skipped.
+- Record durable decisions as one numbered ADR under `docs/adrs/`. Supersede an
+  accepted ADR rather than rewriting its history.
+- Keep `docs/CODE_REVIEW.md`, `docs/CHANGELOG.md`, `docs/ROADMAP.md`, and
+  `HANDOFF.md` synchronized with implementation status.
+- Follow [ADR 0030](docs/adrs/0030-ship-hardening-as-small-pre-one-patches.md)
+  while the project is pre-1.0: keep compatible hardening tags small, never
+  conceal a breaking change in a patch, describe future scope in the roadmap,
+  and keep the changelog limited to the next slice plus landed releases.
+- Stage newly added files before an all-files pre-commit gate. Git does not
+  include untracked files in `--all-files`.
+
+## Ownership and review
+
+- Each release has exactly one branch owner. The owner alone changes the release
+  branch, applies corrections, opens the pull request, and performs the release.
+- Work serially by default. At most one independent reviewer may be active at a
+  time; do not fan work out to multiple agents or add another delegation layer.
+- The reviewer uses a detached disposable worktree, reports findings, and does
+  not commit to or check out the owner's worktree. Remove the review worktree
+  when the verdict is complete.
+- Review an immutable exact candidate SHA against the preceding release. Any
+  correction changes the candidate and requires a renewed exact-SHA review.
+- Use concise one-line commits. Merge only the reviewed candidate after green
+  required checks, and create an immutable annotated release tag only from the
+  verified merge commit.
+- Use `git --no-optional-locks` for read-only inspection of an active worktree
+  where possible. Run `uv sync --locked` per worktree, but install pre-commit
+  only once from the primary clone because linked worktrees share `.git/hooks`.
+
+## Release-equivalent local gate
+
+```bash
+uv sync --locked --all-groups
+uv run --locked python scripts/verify_docs.py
+uv run --locked pre-commit run --all-files
+uv run --locked pytest --cov=agent_statusline --cov-report=term-missing
+uv build
+```

agent_statusline-0.3.5/HANDOFF.md

@@ -0,0 +1,97 @@
+# agent-statusline handoff
+
+This is the tracked, public-safe current-state record. Machine-local operational
+notes may add detail, but they do not override this file, [AGENTS.md](AGENTS.md),
+the roadmap, or accepted ADRs.
+
+## Current release boundary
+
+- Current release target: 0.3.5, public README and trusted production PyPI publication.
+- Preceding release: v0.3.4, the immutable base for this slice.
+- Branch owner: Codex; only the owner changes the release branch.
+- Reviewer role: one independent read-only reviewer, assigned after the exact
+  candidate SHA is frozen. No second reviewer or delegated worker runs beside it.
+- Both hosted workflows are active. Every pull request and `main` push runs one
+  complete-ancestry audit. Documentation-only refs skip both hosted test lanes;
+  full-scope refs run the Linux Python matrix and representative macOS evidence.
+  One stable aggregate job reports whether all required work passed or was
+  deliberately skipped. Missing, malformed, failed, cancelled, or inconsistent
+  results fail closed; only reviewed canonical direct keys are accepted.
+- The repository is public. Active no-bypass ruleset `22966865` protects
+  `main`: pull requests and resolved review threads are required, the aggregate
+  GitHub Actions result must pass against current `main`, and deletion and
+  force-push are blocked.
+- Runtime dependencies remain empty and versions remain Git-tag-derived.
+
+The first v0.3.5 phase replaces the exhaustive public README catalog and
+internal process narrative with a concise product and installation journey.
+The unmerged candidate may stage package-name commands, but production PyPI
+configuration, publication, merge, tagging, and release remain unapproved until
+the maintainer accepts the public copy and separately authorizes that boundary.
+
+## Stable product boundary
+
+The Claude Code renderer retains ten rows in this order:
+
+`PROJECT`, `MODEL`, `CONTEXT`, `USAGE`, `COST`, `SYSTEM`, `TOOLS`, `CACHE`,
+`TOKENS`, `TIMING`.
+
+Their current fields and priority order remain approved. Runtime behavior stays
+local, state stays outside the repository, runtime dependencies stay empty, and
+currency-labelled values remain exactly accountable. Codex remains a separate
+widget-based host; [PORTING.md](docs/PORTING.md) records the verified boundary.
+
+## Release train
+
+Released slices through v0.2.14 cover ownership-safe installation, the locked
+quality gate, malformed-input resilience, private serialized state, exact
+rolling-cost attribution, session-scoped process evidence, and bounded
+observation state, tracked governance, deterministic rendering safety, and
+hermetic installed-renderer evidence, isolated self-test, and safe diagnostics.
+They also cover pinned lean workflows, the ordinary reachable-history rewrite,
+accepted historical pull-ref boundary, prospective ancestry protection,
+oversized-evidence closure, protected public conversion, and exact aggregate CI.
+
+v0.2.14 completed public-CI alignment after conversion. v0.3.0 completed the
+production-ready records-and-metadata milestone promised by ADR 0030. v0.3.1
+completed measured hot-path import reduction and source-hermetic benchmark
+evidence. v0.3.2 completed public package metadata, portable package-page
+rendering, and package-manager guidance. v0.3.3 completed locked build-once
+artifact promotion and exact GitHub Release publication. v0.3.4 completed
+trusted TestPyPI publication and exact public-index verification.
+
+The complete sequence and exclusions are authoritative in
+[ROADMAP.md](docs/ROADMAP.md). Do not merge the historical hardening branch as
+a whole or import a later slice into the current release.
+
+## Resume point
+
+v0.3.4 is complete at tagged merge
+`d7f81ba7101eb4ee1fdc736bedd2fb5286e9e0ae`. Exact-SHA review, protected PR and
+merged-main CI, tag-triggered build-once Release, manually approved OIDC
+TestPyPI publication, public hash verification, and an isolated Python 3.9
+wheel self-test passed. Live Claude Code remains intentionally on exact
+installed v0.3.1 through one status-line command and four managed hooks, with
+unrelated settings and state preserved and no checkout symlink.
+
+The v0.3.5 owner branch starts from exact v0.3.4. The current phase contains the
+README, ADR 0044 and its index, synchronized release records, and the approved
+narrow correction that makes root-level Markdown obey the existing
+documentation-only CI boundary. Exact policy and executable scope regressions
+must accompany that workflow correction. The policy pins the complete scope
+step, including its trusted base expression and command order, so an appended
+output cannot override a full-scope result. It also exact-maps the `checks` job
+and binds its sole exported value to that reviewed scope step, preventing the
+downstream matrix from accepting an injected documentation-only result. Run the
+complete local gate and one independent exact-SHA review, then stop for
+maintainer acceptance. Do not
+configure a production publisher or environment, merge, tag, publish, access
+live state, or alter live installation. Explicit host acquisition and Codex
+evidence remain on the next minor track. Runtime behavior, accepted pull refs,
+unreachable objects, and recovery cleanup remain separate.
+[PUBLIC_READINESS.md](docs/PUBLIC_READINESS.md) records the protected baseline.
+
+Durable decisions live in [ADRs](docs/adrs/README.md), completed behavior in the
+[changelog](docs/CHANGELOG.md), review evidence in
+[CODE_REVIEW.md](docs/CODE_REVIEW.md), and measured or open questions in
+[RESEARCH.md](docs/RESEARCH.md).

agent_statusline-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nachiketbhujbal
+
+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.

agent_statusline-0.3.5/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: agent-statusline
+Version: 0.3.5
+Summary: A dense, width-aware status line for coding agents
+Project-URL: Homepage, https://github.com/nachiketbhujbal/agent-statusline
+Project-URL: Documentation, https://github.com/nachiketbhujbal/agent-statusline/tree/main/docs
+Project-URL: Source, https://github.com/nachiketbhujbal/agent-statusline
+Project-URL: Issues, https://github.com/nachiketbhujbal/agent-statusline/issues
+Project-URL: Changelog, https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/CHANGELOG.md
+Author: nachiketbhujbal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,cli,codex,statusline,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# agent-statusline
+
+[![CI](https://github.com/nachiketbhujbal/agent-statusline/actions/workflows/ci.yml/badge.svg)](https://github.com/nachiketbhujbal/agent-statusline/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-statusline.svg)](https://pypi.org/project/agent-statusline/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/nachiketbhujbal/agent-statusline/blob/main/LICENSE)
+[![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](https://github.com/nachiketbhujbal/agent-statusline/blob/main/pyproject.toml)
+
+A dense, local-first status line for
+[Claude Code](https://claude.com/claude-code). See the project, model, context,
+usage, cost, tools, cache, tokens, timing, and machine pressure of the session
+you are in—without telemetry, runtime network calls, or third-party packages.
+
+```text
+PROJECT acme-web/services │ feature/ingest* ↑2 stash1 │ "Rewrite the importer"
+MODEL   Opus 5:high │ think │ fast off │ auto │ v2.1.246
+CONTEXT ctx[██░░░░░░░░]  19% 189k/1M │ session 25.7M in · 311k out · 107k thinking · 189 api turns · avg 136k/1.65k per turn
+USAGE   5h [███░░░░░░░] 26% @19.7%/h ▸ 98% (reset Wed 19:30 | 3h40m) │ 7d [█████░░░░░] 50% @0.3%/h ▸ 50% (reset Wed 17:00 | 1h10m)
+COST    $2.10 session │ 24h $9.40 · 7d $31.20 · 30d $88.60 │ last5 $27.50 · all $142.30 (5 convos · 6 sess · 1 fork) │ +174/-12 lines │ credits on
+SYSTEM  this session 540M · 5 proc · pid 4821 │ all claude 512M · 1 proc · 1.6% of ram │ ram[█████░░░] 62% of 32.0G · 4.2G compressed │ disk[████░░░░] 48% · 210G free
+TOOLS   101 calls │ Bash81 Edit12 Read8 │ 2 tool errors │ 6 files edited · 14 read │ 0 subagents │ 0 compactions
+CACHE   97.9% hit │ 1h ttl ▸ expires 16:49 │ 0.12x vs all-uncached │ writes 504k 1h · 0 5m
+TOKENS  total 23.8M reused · 504k written · 366 uncached │ turn 184k reused · 5.2k written · 2 uncached
+TIMING  turn 12m last · 4m median · 12m max (3 timed) │ wall 1h11m · api 19m (27% busy) │ hooks 3 runs · 133ms median · 0 errors
+```
+
+Rows reflow deterministically as the terminal changes width. Each may wrap once;
+only then are lower-priority details removed with an `…` marker. No physical
+output line exceeds the detected terminal width.
+
+## Install
+
+The recommended installation keeps this frequently invoked command isolated:
+
+```bash
+uv tool install agent-statusline
+agent-statusline install
+```
+
+Restart Claude Code after installation. To preview the configuration changes
+first, run `agent-statusline install --dry-run`.
+
+The package is a standard Python distribution. These install the same command
+with other package managers:
+
+```bash
+pipx install agent-statusline
+python -m pip install agent-statusline
+```
+
+`pipx` isolates the command like `uv tool`; `pip` installs it into the active
+Python environment.
+
+Requirements: Python 3.9 or newer, Claude Code, and macOS or Linux. Git is
+optional and enriches the `PROJECT` row. On Linux, the macOS-specific memory
+probe gracefully reduces the `SYSTEM` row to the information available.
+
+## What it tracks
+
+- `PROJECT` and `MODEL`: location, Git state, task, model, effort, mode, and host version.
+- `CONTEXT` and `USAGE`: context consumption, session tokens, API turns, and rate-limit windows.
+- `COST`: current, rolling, recent, and lifetime spend plus session counts and line changes.
+- `SYSTEM` and `TOOLS`: process, memory, disk, tool, file, subagent, and compaction activity.
+- `CACHE`, `TOKENS`, and `TIMING`: cache efficiency, token flow, turn time, wall time, and hooks.
+
+The [field reference](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/FIELDS.md)
+documents every value and its source.
+
+## Local and private by design
+
+- Rendering uses local Claude Code payloads, transcripts, and machine state. It
+  sends no telemetry and has no cloud fallback.
+- Runtime state stays under `~/.claude/`, outside the repository. Package-owned
+  state is privately permissioned and locked, using atomic replacement or
+  durable append as appropriate.
+- Currency-labelled totals are exactly attributable. When retained evidence can
+  prove only a lower bound, the display says `≥` instead of presenting it as a total.
+- Installation backs up `settings.json`, preserves unrelated settings and hooks,
+  and refuses to replace configuration it cannot prove it owns.
+- `agent-statusline selftest` uses isolated synthetic state and never touches the
+  live cost ledger.
+
+The last-payload file can contain sensitive paths, titles, costs, and commands.
+Do not publish or attach files from the status-line state directory.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `agent-statusline install` | Wire the command and managed hooks into Claude Code |
+| `agent-statusline install --dry-run` | Preview installation without writing anything |
+| `agent-statusline selftest` | Render all ten rows from isolated synthetic data |
+| `agent-statusline ledger show` | Inspect the local cost ledger |
+| `agent-statusline uninstall` | Remove only configuration owned by this installation |
+| `agent-statusline --version` | Print the installed version |
+
+If the status line does not appear, run `agent-statusline selftest` first, then
+restart Claude Code. Unexpected renderer failures leave only their time and
+exception type in `~/.claude/statusline-last-error.json`.
+
+## Update or remove
+
+```bash
+uv tool upgrade agent-statusline
+agent-statusline install
+```
+
+Re-running `install` refreshes the managed Claude Code wiring while preserving
+unrelated configuration.
+
+```bash
+agent-statusline uninstall
+uv tool uninstall agent-statusline
+```
+
+Uninstalling leaves the local ledger and history in `~/.claude/` intact.
+
+## Develop from a checkout
+
+```bash
+git clone https://github.com/nachiketbhujbal/agent-statusline.git
+cd agent-statusline
+uv sync --locked --all-groups
+uv run --locked python scripts/verify_docs.py
+uv run --locked pre-commit run --all-files
+uv run --locked pytest --cov=agent_statusline --cov-report=term-missing
+uv build
+```
+
+Run `python3 install.py` to wire a development checkout into Claude Code through
+a symlink; working-tree edits then become live without reinstalling. Tests use
+synthetic inputs and must never read the real `~/.claude` state.
+
+Contributor-facing details live in the
+[implementation guide](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/INTERNALS.md)
+and [host-porting boundary](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/PORTING.md).
+
+## License
+
+[MIT](https://github.com/nachiketbhujbal/agent-statusline/blob/main/LICENSE).
+This independent project is not affiliated with or endorsed by Anthropic.

agent_statusline-0.3.5/README.md

@@ -0,0 +1,141 @@
+# agent-statusline
+
+[![CI](https://github.com/nachiketbhujbal/agent-statusline/actions/workflows/ci.yml/badge.svg)](https://github.com/nachiketbhujbal/agent-statusline/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-statusline.svg)](https://pypi.org/project/agent-statusline/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/nachiketbhujbal/agent-statusline/blob/main/LICENSE)
+[![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](https://github.com/nachiketbhujbal/agent-statusline/blob/main/pyproject.toml)
+
+A dense, local-first status line for
+[Claude Code](https://claude.com/claude-code). See the project, model, context,
+usage, cost, tools, cache, tokens, timing, and machine pressure of the session
+you are in—without telemetry, runtime network calls, or third-party packages.
+
+```text
+PROJECT acme-web/services │ feature/ingest* ↑2 stash1 │ "Rewrite the importer"
+MODEL   Opus 5:high │ think │ fast off │ auto │ v2.1.246
+CONTEXT ctx[██░░░░░░░░]  19% 189k/1M │ session 25.7M in · 311k out · 107k thinking · 189 api turns · avg 136k/1.65k per turn
+USAGE   5h [███░░░░░░░] 26% @19.7%/h ▸ 98% (reset Wed 19:30 | 3h40m) │ 7d [█████░░░░░] 50% @0.3%/h ▸ 50% (reset Wed 17:00 | 1h10m)
+COST    $2.10 session │ 24h $9.40 · 7d $31.20 · 30d $88.60 │ last5 $27.50 · all $142.30 (5 convos · 6 sess · 1 fork) │ +174/-12 lines │ credits on
+SYSTEM  this session 540M · 5 proc · pid 4821 │ all claude 512M · 1 proc · 1.6% of ram │ ram[█████░░░] 62% of 32.0G · 4.2G compressed │ disk[████░░░░] 48% · 210G free
+TOOLS   101 calls │ Bash81 Edit12 Read8 │ 2 tool errors │ 6 files edited · 14 read │ 0 subagents │ 0 compactions
+CACHE   97.9% hit │ 1h ttl ▸ expires 16:49 │ 0.12x vs all-uncached │ writes 504k 1h · 0 5m
+TOKENS  total 23.8M reused · 504k written · 366 uncached │ turn 184k reused · 5.2k written · 2 uncached
+TIMING  turn 12m last · 4m median · 12m max (3 timed) │ wall 1h11m · api 19m (27% busy) │ hooks 3 runs · 133ms median · 0 errors
+```
+
+Rows reflow deterministically as the terminal changes width. Each may wrap once;
+only then are lower-priority details removed with an `…` marker. No physical
+output line exceeds the detected terminal width.
+
+## Install
+
+The recommended installation keeps this frequently invoked command isolated:
+
+```bash
+uv tool install agent-statusline
+agent-statusline install
+```
+
+Restart Claude Code after installation. To preview the configuration changes
+first, run `agent-statusline install --dry-run`.
+
+The package is a standard Python distribution. These install the same command
+with other package managers:
+
+```bash
+pipx install agent-statusline
+python -m pip install agent-statusline
+```
+
+`pipx` isolates the command like `uv tool`; `pip` installs it into the active
+Python environment.
+
+Requirements: Python 3.9 or newer, Claude Code, and macOS or Linux. Git is
+optional and enriches the `PROJECT` row. On Linux, the macOS-specific memory
+probe gracefully reduces the `SYSTEM` row to the information available.
+
+## What it tracks
+
+- `PROJECT` and `MODEL`: location, Git state, task, model, effort, mode, and host version.
+- `CONTEXT` and `USAGE`: context consumption, session tokens, API turns, and rate-limit windows.
+- `COST`: current, rolling, recent, and lifetime spend plus session counts and line changes.
+- `SYSTEM` and `TOOLS`: process, memory, disk, tool, file, subagent, and compaction activity.
+- `CACHE`, `TOKENS`, and `TIMING`: cache efficiency, token flow, turn time, wall time, and hooks.
+
+The [field reference](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/FIELDS.md)
+documents every value and its source.
+
+## Local and private by design
+
+- Rendering uses local Claude Code payloads, transcripts, and machine state. It
+  sends no telemetry and has no cloud fallback.
+- Runtime state stays under `~/.claude/`, outside the repository. Package-owned
+  state is privately permissioned and locked, using atomic replacement or
+  durable append as appropriate.
+- Currency-labelled totals are exactly attributable. When retained evidence can
+  prove only a lower bound, the display says `≥` instead of presenting it as a total.
+- Installation backs up `settings.json`, preserves unrelated settings and hooks,
+  and refuses to replace configuration it cannot prove it owns.
+- `agent-statusline selftest` uses isolated synthetic state and never touches the
+  live cost ledger.
+
+The last-payload file can contain sensitive paths, titles, costs, and commands.
+Do not publish or attach files from the status-line state directory.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `agent-statusline install` | Wire the command and managed hooks into Claude Code |
+| `agent-statusline install --dry-run` | Preview installation without writing anything |
+| `agent-statusline selftest` | Render all ten rows from isolated synthetic data |
+| `agent-statusline ledger show` | Inspect the local cost ledger |
+| `agent-statusline uninstall` | Remove only configuration owned by this installation |
+| `agent-statusline --version` | Print the installed version |
+
+If the status line does not appear, run `agent-statusline selftest` first, then
+restart Claude Code. Unexpected renderer failures leave only their time and
+exception type in `~/.claude/statusline-last-error.json`.
+
+## Update or remove
+
+```bash
+uv tool upgrade agent-statusline
+agent-statusline install
+```
+
+Re-running `install` refreshes the managed Claude Code wiring while preserving
+unrelated configuration.
+
+```bash
+agent-statusline uninstall
+uv tool uninstall agent-statusline
+```
+
+Uninstalling leaves the local ledger and history in `~/.claude/` intact.
+
+## Develop from a checkout
+
+```bash
+git clone https://github.com/nachiketbhujbal/agent-statusline.git
+cd agent-statusline
+uv sync --locked --all-groups
+uv run --locked python scripts/verify_docs.py
+uv run --locked pre-commit run --all-files
+uv run --locked pytest --cov=agent_statusline --cov-report=term-missing
+uv build
+```
+
+Run `python3 install.py` to wire a development checkout into Claude Code through
+a symlink; working-tree edits then become live without reinstalling. Tests use
+synthetic inputs and must never read the real `~/.claude` state.
+
+Contributor-facing details live in the
+[implementation guide](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/INTERNALS.md)
+and [host-porting boundary](https://github.com/nachiketbhujbal/agent-statusline/blob/main/docs/PORTING.md).
+
+## License
+
+[MIT](https://github.com/nachiketbhujbal/agent-statusline/blob/main/LICENSE).
+This independent project is not affiliated with or endorsed by Anthropic.

agent_statusline-0.3.5/docs/ACTIONS_EXPOSURE_INVENTORY.md

@@ -0,0 +1,53 @@
+# Historical Actions exposure inventory
+
+This public-safe record inventories the GitHub Actions surface retained before
+repository visibility can change. It records identifiers and categories, never
+the private values that triggered a match.
+
+## Method
+
+At 2026-09-11T19:18:25Z, the authenticated GitHub API reported 41 workflow runs
+and 26 unexpired artifacts. Every run-log archive was downloaded and every text
+entry was scanned for the personal-provider email and private billing patterns
+used by the repository policy. Every artifact was downloaded, recursively
+opened through its outer artifact archive and inner wheel or source archive,
+and checked for private paths, personal-provider email, private billing
+evidence, and members above the two-MiB audit boundary.
+
+The first pass found no matching run log. It found the superseded ADR 0018
+billing phrase in the source distribution inside each artifact below:
+
+| Artifact ID | Workflow run ID |
+| --- | --- |
+| `10182553023` | `34555947827` |
+| `10184350659` | `34561155649` |
+| `10184366510` | `34561213302` |
+| `10185317588` | `34563964744` |
+| `10185337583` | `34564023511` |
+| `10185936009` | `34565747191` |
+| `10185954867` | `34565803226` |
+| `10186700274` | `34567959880` |
+| `10186730316` | `34568055955` |
+| `10187653749` | `34570718665` |
+| `10187672444` | `34570771590` |
+| `10188481916` | `34572971872` |
+| `10188519132` | `34573060459` |
+| `10190053406` | `34577055928` |
+| `10190368422` | `34577894293` |
+| `10190411583` | `34578002044` |
+
+## Disposition and verification
+
+The maintainer explicitly authorized deletion of exactly those 16 unsafe
+Actions artifacts. All deletions succeeded. Workflow runs and their logs,
+GitHub Releases and release assets, Git refs and tags, and the ten clean Actions
+artifacts were left intact.
+
+A complete post-deletion pass again downloaded all 41 retained log archives;
+all were available and no match remained. It downloaded all ten remaining
+artifacts; all were available and no private path, personal-provider email,
+private billing evidence, or oversized member remained.
+
+This inventory does not alter or expand the accepted twelve historical pull
+refs in ADR 0035. Unreachable objects, provider caches, visibility, and
+post-conversion repository protection remain separate boundaries.