leasehold 0.2.0__tar.gz

leasehold-0.2.0/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.py) ;; *) exit 0 ;; esac; cd \"$CLAUDE_PROJECT_DIR\" && uv run --no-sync ruff check --fix \"$f\" 1>&2 && uv run --no-sync ruff format \"$f\" 1>&2 || exit 2",
+            "statusMessage": "ruff"
+          }
+        ]
+      }
+    ]
+  }
+}

leasehold-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "leasehold",
+  "owner": {
+    "name": "Matthew Strudwick"
+  },
+  "metadata": {
+    "description": "leasehold's Claude Code plugin: heavy commands take turns on a shared machine."
+  },
+  "plugins": [
+    {
+      "name": "leasehold",
+      "source": "./integrations/claude-code",
+      "description": "Heavy Bash commands wait for a lease on a shared machine instead of piling on."
+    }
+  ]
+}

leasehold-0.2.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,30 @@
+name: Bug
+description: Something does not work as the docs say.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to make it happen
+      description: Commands, the config (machine.toml) if it matters, and their output.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`leasehold doctor` output"
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: "`leasehold --version`, distribution and kernel"
+      placeholder: leasehold 0.2.0, Debian 13, 6.12
+    validations:
+      required: true

leasehold-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security problem
+    url: https://github.com/chalkworth/leasehold/security/advisories/new
+    about: Report a vulnerability privately, not as an issue.

leasehold-0.2.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,15 @@
+name: Idea
+description: Something leasehold should do, or do better.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What you are trying to do on your machine, and what gets in the way today.
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What would help

leasehold-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0  # it publishes no moving major tag
+      - run: uv sync --python 3.12
+      - run: uv run --no-sync ruff check
+      - run: uv run --no-sync ruff format --check
+      - run: uv run --no-sync lint-imports
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0  # it publishes no moving major tag
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run --no-sync pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0  # it publishes no moving major tag
+      - run: uv build
+      - name: The wheel carries its package data
+        run: |
+          python3 - <<'PY'
+          import glob, zipfile
+          names = zipfile.ZipFile(glob.glob("dist/*.whl")[0]).namelist()
+          for needed in ("leasehold/static/ui.html", "leasehold/templates/machine.toml"):
+              assert needed in names, f"{needed} is not in the wheel"
+          PY
+      - name: It installs and runs from the wheel
+        run: |
+          uv venv /tmp/try && uv pip install --python /tmp/try/bin/python dist/*.whl
+          /tmp/try/bin/leasehold --version
+          /tmp/try/bin/leasehold init --print > /dev/null
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/

leasehold-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+# Publishes docs/ (index.html and its media) to GitHub Pages. It runs only once the repository is
+# public: a Pages site of a private repository can still be public, and nothing is published
+# before the repository itself is. Pages must be set to "GitHub Actions" in the settings.
+name: pages
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    if: github.event.repository.visibility == 'public'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs
+      - id: deployment
+        uses: actions/deploy-pages@v5

leasehold-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+# Publishes to PyPI when a GitHub release is published, with PyPI's trusted publishing (no
+# token is stored anywhere). It needs, once: a PyPI project with this repository and workflow
+# named as a trusted publisher, and an environment "pypi" here. Nothing else triggers it.
+name: release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0  # it publishes no moving major tag
+      - run: uv build
+      - name: The version is the release's
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ls dist/leasehold-"$tag"-py3-none-any.whl
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

leasehold-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.import_linter_cache/
+/bench-results/

leasehold-0.2.0/.importlinter

@@ -0,0 +1,88 @@
+# leasehold's import contracts, checked by `uv run lint-imports` (pre-commit and CI).
+#
+# The library (model, admission, ledger, quota) is pure policy and storage: it never imports
+# the daemon. Commands that talk to a daemon (hold, handoff, report, top, the views and the MCP
+# server) reach it only through `leasehold.client`, never by importing the agent, the API or the
+# ledger.
+
+[importlinter]
+root_package = leasehold
+
+[importlinter:contract:layers]
+name = leasehold layers, top first: a module may import its own layer and those below
+type = layers
+layers =
+    cli
+    demo | mcp_server
+    setup
+    server | doctor | template | top | claude_code | shims
+    api
+    agent
+    status | lend | guard | events
+    machine
+    quota | observe | commands
+    shell
+    ledger
+    admission
+    model | discovery
+    paths
+containers =
+    leasehold
+
+[importlinter:contract:clients]
+name = commands that talk to a daemon use only the client
+type = forbidden
+source_modules =
+    leasehold.busy
+    leasehold.hold
+    leasehold.handoff
+    leasehold.report
+    leasehold.webui
+    leasehold.top
+    leasehold.claude_code
+    leasehold.shims
+    leasehold.mcp_server
+forbidden_modules =
+    leasehold.agent
+    leasehold.api
+    leasehold.server
+    leasehold.ledger
+    leasehold.machine
+    leasehold.admission
+
+[importlinter:contract:leaves]
+name = leaf modules import nothing else of leasehold's
+type = forbidden
+source_modules =
+    leasehold.model
+    leasehold.contain
+    leasehold.units
+    leasehold.process
+    leasehold.kinds
+    leasehold.exits
+    leasehold.client
+    leasehold.facts
+    leasehold.access
+    leasehold.paths
+    leasehold.jobs
+    leasehold.proctable
+    leasehold.metrics
+    leasehold.shell
+    leasehold.terminal
+    leasehold.hooknotes
+forbidden_modules =
+    leasehold.admission
+    leasehold.ledger
+    leasehold.quota
+    leasehold.machine
+    leasehold.agent
+    leasehold.api
+    leasehold.server
+    leasehold.cli
+    leasehold.hold
+    leasehold.handoff
+    leasehold.report
+    leasehold.top
+    leasehold.status
+    leasehold.lend
+    leasehold.load

leasehold-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# `uv tool install pre-commit && pre-commit install` runs these on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: import-contracts
+        name: import contracts (.importlinter)
+        entry: uv run --no-sync lint-imports
+        language: system
+        pass_filenames: false
+        files: ^src/

leasehold-0.2.0/AGENTS.md

@@ -0,0 +1,40 @@
+# Working on leasehold
+
+Notes for anyone changing this repository, people and coding agents alike. `CLAUDE.md` points
+here.
+
+## Checks
+
+```sh
+uv sync
+uv run pytest -q          # about a minute; daemon tests use real unix sockets under /tmp
+uv run ruff check && uv run ruff format --check
+uv run lint-imports       # the layer contracts in .importlinter
+```
+
+`pre-commit install` runs ruff and the import contracts on every commit.
+
+## Shape of the code
+
+- The library is pure: `model` (pools), `admission` (the decision), `ledger` (SQLite),
+  `quota`. It never imports the daemon. `.importlinter` enforces the layers; fix an upward
+  import rather than listing it as an exception.
+- The daemon is `machine` (config) → `agent` (requests, ticks) → `api` (routes, no sockets) →
+  `server` (the unix socket). `status` builds the status object as a pure function.
+- `paths` says where each mode (system, user) keeps things; `discovery` is how a client finds
+  a daemon; `doctor` checks a setup; `template` renders the config `init` writes.
+- `cli` is a package: one module per group of commands, each with a `register(sub)` and
+  handlers `(args, ctx) -> exit code`. A new command goes in the module of its group, or a new
+  module listed in `cli/__init__.py`.
+- Anything that talks to a daemon (`hold`, `handoff`, `report`, the views) does so through
+  `leasehold.client` only.
+- One module, one job. A new behaviour that does not belong to an existing module's docstring
+  gets its own module.
+
+## Conventions
+
+- Comments and docstrings state what is guaranteed, once, in plain words. No task history.
+- New behaviour comes with a test that would fail without it. Daemon behaviour is tested
+  against a real daemon on a temporary socket (`tests/support.py`).
+- Every change to a public name, config key, CLI flag, exit code, status field or error code is
+  listed in `CHANGELOG.md` under the next release.

leasehold-0.2.0/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to leasehold. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and versions follow [Semantic Versioning](https://semver.org/) as described under "Stability" in
+the README: before 1.0, a minor release may break the public API, and every break is listed
+here.
+
+## [Unreleased]
+
+## [0.2.0] - first public release
+
+leasehold gives the heavy commands on one Linux machine (coding agents' builds and test runs, CI
+jobs, people's work) a lease on a share of the machine before they start, sizes them to it, and,
+where systemd allows it, holds them to it while they run.
+
+### Added
+
+**For coding agents**
+
+- `leasehold setup` (and `--remove`): a config sized for the machine, a systemd user unit
+  running your own daemon, the PATH shims, the agents found on PATH, and a containment and
+  `doctor` check, in one step.
+- `leasehold run -- AGENT`: the agent as one session (`LEASEHOLD_SESSION`), the PATH shims first
+  on its PATH and, when contained, a slice of its own whose leftovers are stopped when it exits
+  (`--leave-running`, `--session`, `--quiet`, `--no-contain`).
+- PATH shims (`leasehold shims install|list|remove`) for the programs the `[commands]` rules
+  name: a matching command runs under a lease, anything else passes straight through, and a
+  command an agent hook has leased already runs in that lease.
+- The Claude Code plugin: a hook that takes a lease around a heavy Bash command, with a shell
+  pre-filter so ordinary commands start no Python, and a skill that tells the agent what a wait,
+  a refusal and the exit codes mean.
+- `[commands]` rules (built in, extendable): which programs and arguments are heavy, their
+  weight and memory. A busy machine refuses after 20 s (`wait_s`, `when_busy = "deny"`), and the
+  refusal names what holds the pool and the place in line. `leasehold commands --test` and
+  `--programs`.
+- `leasehold mcp` (experimental): MCP tools to read the machine's state and wait for a lease.
+
+**Admission**
+
+- Weighted leases on slots, renewed by their holder and expiring when it dies. Pools with
+  reserved and maximum slots and a priority; lease kinds `work`, `external`, `lend` and
+  `observed`. Turns go round by Unix user, then by session within a user; no backfill.
+- Lending (experimental): when nothing waits and pressure stall information is quiet, `lend`
+  leases use spare slots, and are revoked the moment other work queues or pressure rises.
+- The memory guard (`[guard]`): while memory pressure or available memory is past its
+  threshold, every pool admits only its reserved slots. On for a user's daemon.
+- `[[observe]]` rules (experimental): a known program started outside leasehold counts as a
+  lease while it runs.
+
+**Running a command**
+
+- `leasehold hold -- CMD`: wait for a lease, run the command in its own process group (the
+  terminal's foreground when run from one), renew the lease, and release it when the command
+  ends. With no `--weight`, the command is weighed by the `[commands]` rules. The command learns
+  its size from `LEASEHOLD_JOBS` and the job-count variables cargo, make, CMake, pytest-xdist,
+  Go and others read; `--jobserver` adds a GNU make jobserver.
+- Containment: where the caller runs in the user's own session and the systemd user manager is
+  delegated cpu and memory, `hold` and the shims start the command in a user scope with
+  `CPUWeight` 100 per slot and, with `--memory` or a rule's `memory`, `MemoryHigh`. `[contain]
+  mode` (`auto`, `off`), `hard_cpu`; `LEASEHOLD_CONTAIN=off`. Elsewhere leases are advisory.
+- `hold --if-unavailable run|fail`: with no daemon, run the command without a lease (the
+  default) or exit 69.
+- Exit codes: 69 no daemon, 75 busy (gave up waiting), 76 revoked, 77 refused, 127 not started.
+
+**The daemon and views**
+
+- `leasehold serve`: your own daemon (`--user`, no root) or the machine's (`--system`, a
+  `leasehold` group on its socket). One unix socket, a SQLite ledger, an HTTP API with a
+  versioned status object (schema 2).
+- `leasehold init` writes a commented config sized for the machine: two pools for a user's
+  daemon, four for the machine's.
+- `leasehold top` (terminal), `leasehold ui` (browser, experimental), `status`, `leases`,
+  `metrics` (Prometheus, experimental), `report` (a webhook, experimental) and `demo`, which
+  runs a made-up busy machine.
+- `leasehold doctor`: the config, socket and its path length and permissions, the daemon, PSI,
+  cgroups, the ledger and containment, each with a fix.
+- `bench/`: a seeded benchmark of several agents starting heavy jobs on one machine, run
+  unmanaged, under `nice`, in a low-weight systemd slice, with a fixed job count, and through
+  `leasehold hold` advisory and enforced (`bench/run.py`); method and results in `docs/bench.md`.
+- The admission policy as a library (`leasehold.model`, `admission`, `ledger`, `quota`,
+  `client`), with no daemon.

leasehold-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

leasehold-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Issues and pull requests are welcome. For anything larger than a fix, open an issue first, so
+we can agree on the shape before you write it.
+
+## Setup
+
+```sh
+git clone https://github.com/chalkworth/leasehold && cd leasehold
+uv sync                                          # Python 3.12+, the dev tools included
+uv tool install pre-commit && pre-commit install # ruff and the import contracts on each commit
+```
+
+## Checks
+
+Everything CI runs:
+
+```sh
+uv run ruff check
+uv run ruff format --check
+uv run lint-imports          # which module may import which (.importlinter)
+uv run pytest -q             # about two minutes; Linux only
+```
+
+Tests start real daemons on real unix sockets in temporary directories. A few need tools:
+`make` 4.4 for the jobserver test, which is skipped without it.
+
+## How the code is laid out
+
+`AGENTS.md` describes the layers and the rules each module keeps. In short:
+
+- The library (`model`, `admission`, `ledger`, `quota`) is pure policy and storage, and never
+  imports the daemon.
+- Everything that talks to a daemon (`hold`, the views, the agent integrations) goes through
+  `leasehold.client`.
+- The core depends on the standard library and pydantic only. Anything else is an optional
+  extra (`mcp`).
+
+## Changes that others depend on
+
+The command line and its exit codes, the config file, the HTTP API and its `status` schema,
+`--json` output and the library modules are public. A change to any of them gets a row in
+`CHANGELOG.md`, saying what to do instead.
+
+## Licence
+
+By contributing, you agree that your contribution is licensed under the Apache License 2.0,
+the licence of this project.