pixie-lab-dibs 0.1.0__tar.gz → 0.2.0__tar.gz

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/.github/workflows/test.yml

@@ -40,3 +40,24 @@ jobs:
 
       - name: make build
         run: make build
+
+  service:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v7.2.1
+
+      # The pixie server dibs first ran on resolves users from files only,
+      # without nss-systemd. Match it, so a unit that relies on systemd's
+      # dynamic users fails here rather than there.
+      - name: Resolve users from /etc/passwd only
+        run: |
+          sudo sed -i 's/^passwd:.*/passwd: files/' /etc/nsswitch.conf
+          grep '^passwd' /etc/nsswitch.conf
+
+      - name: make build
+        run: make build
+
+      - name: make service-smoke
+        run: make service-smoke

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/.pre-commit-config.yaml

@@ -34,6 +34,10 @@ repos:
         # fail CI there.
         additional_dependencies:
           - mdformat-gfm==1.0.0
+          # Without this, mdformat rewrites the agent skill's YAML frontmatter
+          # into a horizontal rule and a heading, and Claude Code stops
+          # finding the skill.
+          - mdformat-frontmatter==2.1.2
 
   - repo: https://github.com/fsfe/reuse-tool
     rev: v6.2.0

pixie_lab_dibs-0.2.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# Changelog
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-27
+
+### Added
+
+- Parts: a thing can have parts named `<thing>.<part>`, claimable on
+  their own. Claiming the thing covers its parts, so it conflicts with
+  another user's claim on any part, and a part conflicts with another
+  user's claim on the thing. Forcing the thing takes over its parts.
+- `dibs skill install` puts a Claude Code skill in
+  `~/.claude/skills/dibs/` that teaches an agent to claim a lab machine
+  before using it, to claim the whole machine for anything through the
+  BMC, and to release when done. `dibs skill print` shows it.
+
+## [0.1.1] - 2026-10-27
+
+### Fixed
+
+- `dibs server install` over a running service now restarts it, so
+  installing again after an upgrade runs the new version. It used to
+  write the new unit and leave the old process running.
+- The system service refused every key at `dibs register` on hosts that
+  resolve users without nss-systemd, plain Debian among them: under
+  `DynamicUser=`, `ssh-keygen` could not look its own user up. `dibs server install` now creates a `dibs` system user and runs the service
+  as it. Run `sudo dibs server install` again to update an installed
+  service.
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- The first version: things to claim, fed from a config file and from
+  pixie servers; claims that are all or nothing, never expire unless
+  asked to, and say when an agent made them; users who register an SSH
+  public key, are approved by the admin, and log in by signing a
+  one-time challenge; a login hook that shows a machine's claim; and
+  one `dibs` command for the server, its systemd service, the admin, and
+  everyone claiming.

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/Makefile

@@ -9,7 +9,7 @@ UV ?= uv
 PRECOMMIT ?= pre-commit
 
 .DEFAULT_GOAL := help
-.PHONY: help format lint typecheck test build check
+.PHONY: help format lint typecheck test build check service-smoke
 
 help: ## Show this help
 	@grep -hE '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) \
@@ -35,3 +35,6 @@ build: ## Build the sdist and wheel, and check every command the wheel installs
 	done
 
 check: lint typecheck test ## Everything but format
+
+service-smoke: ## Install the built wheel as the real service and claim against it (sudo, systemd)
+	./scripts/service-smoke.sh

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pixie-lab-dibs
-Version: 0.1.0
+Version: 0.2.0
 Summary: Call dibs on shared lab machines: see who is using what, claim it, release it
 Project-URL: Homepage, https://github.com/safl/pixie-lab-dibs
 Author-email: "Simon A. F. Lund" <os@safl.dk>
@@ -81,8 +81,9 @@ sudo dibs server install
 
 The command writes a systemd unit for the `dibs` you ran, enables it
 and starts it. `dibs server start`, `stop`, `restart`, `status` and
-`logs` manage it from then on. The service runs as a throwaway system
-user that owns only `/var/lib/dibs`. Without root, `dibs server install --user` installs a per-user service instead. For a quick try,
+`logs` manage it from then on. The service runs as a `dibs` system
+user, which the install creates, with write access only to
+`/var/lib/dibs`. Without root, `dibs server install --user` installs a per-user service instead. For a quick try,
 `dibs serve` runs the server in the foreground.
 
 The system service can only run a `dibs` installed outside your home
@@ -143,10 +144,38 @@ those rather than parse the text.
 The exit status is 0 when done, 1 when refused because someone else
 holds a thing, and 2 for anything else.
 
+### Parts
+
+A thing can have parts that people use independently, named
+`<thing>.<part>` and listed in the config like any other thing:
+
+```toml
+[[thing]]
+name = "epyc-02.gpu1"
+```
+
+Claiming `epyc-02` takes the whole machine, parts included, so it is
+refused while someone else holds a part. Claiming `epyc-02.gpu1` leaves
+the other parts to others, and is refused while someone else holds the
+whole machine. A part listed without its thing still makes the thing
+claimable.
+
+Only make something a part if using it cannot disturb the rest of the
+machine. Anything that can, such as the BMC, power, the console or
+reflashing, needs a claim on the whole machine, so it is an attribute of
+the thing (`bmc = "10.20.30.82"`) rather than a part.
+
 ### AI-agents
 
-Point your agent at this section. An agent claims as its human, and
-names itself the way an `Assisted-by:` trailer does:
+For Claude Code, install the skill that teaches an agent all of this,
+and it applies whenever the agent is about to use a lab machine:
+
+```
+dibs skill install
+```
+
+`dibs skill print` shows it, to adapt for another agent. An agent claims
+as its human, and names itself the way an `Assisted-by:` trailer does:
 
 ```
 export DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5"
@@ -156,11 +185,13 @@ The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' has clai
 
 If you are an agent reading this: before you run anything on a lab
 machine, run `dibs list` and claim the machine with
-`dibs claim <machine> --for <purpose>`. Never use a machine someone else
-has claimed, and never pass `--force`; ask your human instead. Release
-what you claimed with `dibs release --mine` when the work is done, and
-also when it fails or is abandoned. That releases only what you claimed,
-not your human's own claims.
+`dibs claim <machine> --for <purpose>`. Power-cycling, the console,
+reflashing or anything else through the BMC needs the whole machine,
+never just a part. Never use a machine someone else has claimed, and
+never pass `--force`; ask your human instead. Release what you claimed
+with `dibs release --mine` when the work is done, and also when it fails
+or is abandoned. That releases only what you claimed, not your human's
+own claims.
 
 ### Automation-runners
 

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/README.md

@@ -59,8 +59,9 @@ sudo dibs server install
 
 The command writes a systemd unit for the `dibs` you ran, enables it
 and starts it. `dibs server start`, `stop`, `restart`, `status` and
-`logs` manage it from then on. The service runs as a throwaway system
-user that owns only `/var/lib/dibs`. Without root, `dibs server install --user` installs a per-user service instead. For a quick try,
+`logs` manage it from then on. The service runs as a `dibs` system
+user, which the install creates, with write access only to
+`/var/lib/dibs`. Without root, `dibs server install --user` installs a per-user service instead. For a quick try,
 `dibs serve` runs the server in the foreground.
 
 The system service can only run a `dibs` installed outside your home
@@ -121,10 +122,38 @@ those rather than parse the text.
 The exit status is 0 when done, 1 when refused because someone else
 holds a thing, and 2 for anything else.
 
+### Parts
+
+A thing can have parts that people use independently, named
+`<thing>.<part>` and listed in the config like any other thing:
+
+```toml
+[[thing]]
+name = "epyc-02.gpu1"
+```
+
+Claiming `epyc-02` takes the whole machine, parts included, so it is
+refused while someone else holds a part. Claiming `epyc-02.gpu1` leaves
+the other parts to others, and is refused while someone else holds the
+whole machine. A part listed without its thing still makes the thing
+claimable.
+
+Only make something a part if using it cannot disturb the rest of the
+machine. Anything that can, such as the BMC, power, the console or
+reflashing, needs a claim on the whole machine, so it is an attribute of
+the thing (`bmc = "10.20.30.82"`) rather than a part.
+
 ### AI-agents
 
-Point your agent at this section. An agent claims as its human, and
-names itself the way an `Assisted-by:` trailer does:
+For Claude Code, install the skill that teaches an agent all of this,
+and it applies whenever the agent is about to use a lab machine:
+
+```
+dibs skill install
+```
+
+`dibs skill print` shows it, to adapt for another agent. An agent claims
+as its human, and names itself the way an `Assisted-by:` trailer does:
 
 ```
 export DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5"
@@ -134,11 +163,13 @@ The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' has clai
 
 If you are an agent reading this: before you run anything on a lab
 machine, run `dibs list` and claim the machine with
-`dibs claim <machine> --for <purpose>`. Never use a machine someone else
-has claimed, and never pass `--force`; ask your human instead. Release
-what you claimed with `dibs release --mine` when the work is done, and
-also when it fails or is abandoned. That releases only what you claimed,
-not your human's own claims.
+`dibs claim <machine> --for <purpose>`. Power-cycling, the console,
+reflashing or anything else through the BMC needs the whole machine,
+never just a part. Never use a machine someone else has claimed, and
+never pass `--force`; ask your human instead. Release what you claimed
+with `dibs release --mine` when the work is done, and also when it fails
+or is abandoned. That releases only what you claimed, not your human's
+own claims.
 
 ### Automation-runners
 

pixie_lab_dibs-0.2.0/scripts/service-smoke.sh

@@ -0,0 +1,42 @@
+#!/bin/sh
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Install the built wheel as the real systemd service, then register, log
+# in and claim against it. This is the path the unit tests stub out, and
+# where dibs once broke: under systemd, ssh-keygen must be able to look its
+# own user up. Needs root through sudo and a running systemd; CI's runner
+# has both. Run from the repository root after "make build".
+set -eu
+
+wheel=$(ls dist/*.whl)
+tmp=$(mktemp -d)
+trap 'sudo dibs server uninstall >/dev/null 2>&1 || true; rm -rf "$tmp"' EXIT
+
+sudo env "PATH=$PATH" UV_TOOL_DIR=/opt/uv-tools UV_TOOL_BIN_DIR=/usr/local/bin \
+    uv tool install --python /usr/bin/python3 "$wheel"
+
+sudo mkdir -p /etc/dibs
+printf '[[thing]]\nname = "box"\nmac = "aa:bb:cc:dd:ee:ff"\n' | sudo tee /etc/dibs/dibs.toml >/dev/null
+sudo /usr/local/bin/dibs server install --port 8090
+
+export DIBS_URL=http://127.0.0.1:8090 XDG_CONFIG_HOME="$tmp/config"
+for _ in $(seq 1 30); do curl -fsS "$DIBS_URL/healthz" >/dev/null 2>&1 && break; sleep 1; done
+
+ssh-keygen -q -t ed25519 -N '' -f "$tmp/key"
+dibs register ci -i "$tmp/key.pub"
+sudo dibs admin approve ci
+dibs login
+dibs claim box --for smoke
+dibs list | grep -qx "'ci' has claimed 'box' for 'smoke' expires in: 'never'"
+dibs release --mine
+
+# Installing again, as an upgrade does, must replace the running process.
+before=$(systemctl show -p MainPID --value dibs.service)
+sudo /usr/local/bin/dibs server install --port 8090
+after=$(systemctl show -p MainPID --value dibs.service)
+[ "$before" != "$after" ] || { echo "install did not restart the running service" >&2; exit 1; }
+for _ in $(seq 1 30); do curl -fsS "$DIBS_URL/healthz" >/dev/null 2>&1 && break; sleep 1; done
+dibs list | grep -qx "'box' is free"
+echo "service smoke test passed"

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/src/dibs/__init__.py

@@ -12,4 +12,4 @@ everyone who is on a machine, and it never stops anyone from logging
 in.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/src/dibs/_sources.py

@@ -18,7 +18,9 @@ hand and names the pixie servers to poll::
     mac = "aa:bb:cc:dd:ee:ff"   # any other key is kept as an attribute
 
 A ``[[thing]]`` with the name of a pixie machine adds its attributes to
-that machine rather than making a second thing.
+that machine rather than making a second thing. A name with a dot is a
+part of the thing before the dot, ``epyc-02.bmc`` of ``epyc-02``, claimable
+on its own or along with the whole thing.
 """
 
 from __future__ import annotations
@@ -32,7 +34,7 @@ from typing import Any
 
 import httpx
 
-from dibs._store import Store, Thing, ts, validate_thing_name
+from dibs._store import Store, Thing, owner, ts, validate_thing_name
 
 log = logging.getLogger("dibs")
 
@@ -150,4 +152,10 @@ def sync(
             base.kind = t.kind
         else:
             merged[t.name] = Thing(t.name, t.kind, t.source, dict(t.attrs), stamp)
+    # A part listed without its thing still makes the thing claimable as a
+    # whole, so "epyc-02.bmc" alone gives you "epyc-02" too.
+    for t in list(merged.values()):
+        whole = owner(t.name)
+        if whole not in merged:
+            merged[whole] = Thing(whole, t.kind, t.source, {}, stamp)
     store.replace_things(sorted(merged.values(), key=lambda t: t.name))

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/src/dibs/_store.py

@@ -10,6 +10,13 @@ things table is rebuilt from the sources on every sync (see
 a table of their own, keyed by thing name, so a claim outlives a sync in
 which its source was unreachable or briefly forgot the thing.
 
+A thing may have **parts**, named ``<thing>.<part>``, such as
+``epyc-02.ssh`` and ``epyc-02.bmc``. Claiming the thing covers all of its
+parts; claiming a part leaves the others free for someone else. So a
+claim on a thing conflicts with another user's claim on any of its parts,
+and a claim on a part conflicts with another user's claim on that part
+or on the thing.
+
 Every surface (``dibs``, the web page, the login hook on a machine)
 prints a claim as the same sentence, from :func:`sentence`.
 """
@@ -31,8 +38,11 @@ from typing import Any
 _WRITE_LOCK = threading.Lock()
 
 # What people type and put in configs next to the hostname, so a host
-# label: lowercase a-z, 0-9 and -, at most 63 chars.
-THING_NAME_RE = re.compile(r"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$")
+# label (lowercase a-z, 0-9 and -, at most 63 chars), optionally followed
+# by one ".<part>" label. A hostname label has no dot, so the dot is free
+# to mean "part of".
+_LABEL = r"[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?"
+THING_NAME_RE = re.compile(rf"^{_LABEL}(\.{_LABEL})?$")
 
 PURPOSE_MAX = 128
 ASSISTED_BY_MAX = 64
@@ -68,12 +78,23 @@ def validate_thing_name(raw: str) -> str:
     name = (raw or "").strip().lower()
     if not THING_NAME_RE.match(name):
         raise ValueError(
-            f"name {name!r} must be a hostname label: a-z / 0-9 / -, "
-            "1-63 chars, no leading or trailing -"
+            f"name {name!r} must be a hostname label (a-z / 0-9 / -, 1-63 chars, "
+            "no leading or trailing -), optionally with one .part, e.g. epyc-02.bmc"
         )
     return name
 
 
+def owner(name: str) -> str:
+    """The thing a part belongs to; a thing is its own owner."""
+    return name.split(".", 1)[0]
+
+
+def overlaps(a: str, b: str) -> bool:
+    """Whether claims on ``a`` and ``b`` cover any of the same thing: the
+    same name, or a thing and one of its parts."""
+    return a == b or a == owner(b) or b == owner(a)
+
+
 def _one_line(field_name: str, raw: str, limit: int) -> str:
     value = (raw or "").strip()
     if not value:
@@ -160,17 +181,42 @@ def remaining(expires_at: str, now: datetime) -> str:
 
 
 def sentence(name: str, claim: Claim | None, now: datetime) -> str:
+    """One claim as it reads everywhere. The claim names the thing it is
+    on, which for a part covered by its thing's claim is not ``name``."""
     if claim is None or not claim.is_live(now):
         return f"'{name}' is free"
     who = f"'{claim.holder}'"
     if claim.assisted_by:
         who += f" assisted by '{claim.assisted_by}'"
     return (
-        f"{who} has claimed '{name}' for '{claim.purpose}' "
+        f"{who} has claimed '{claim.thing}' for '{claim.purpose}' "
         f"expires in: '{remaining(claim.expires_at, now)}'"
     )
 
 
+def covering(name: str, claims: dict[str, Claim], now: datetime) -> builtins.list[Claim]:
+    """The live claims that say who is on ``name``: its own claim, else
+    its thing's claim for a part, else its parts' claims for a thing."""
+    own = claims.get(name)
+    if own is not None and own.is_live(now):
+        return [own]
+    if "." in name:
+        whole = claims.get(owner(name))
+        return [whole] if whole is not None and whole.is_live(now) else []
+    return sorted(
+        (c for c in claims.values() if owner(c.thing) == name and c.is_live(now)),
+        key=lambda c: c.thing,
+    )
+
+
+def describe(name: str, claims: dict[str, Claim], now: datetime) -> str:
+    """The sentence for ``name``, counting claims on its thing or parts."""
+    found = covering(name, claims, now)
+    if not found:
+        return f"'{name}' is free"
+    return "; ".join(sentence(c.thing, c, now) for c in found)
+
+
 class Store:
     def __init__(self, db_path: Path) -> None:
         self.db_path = Path(db_path)
@@ -248,8 +294,10 @@ class Store:
         or without an agent, updates the purpose, expiry and
         ``assisted_by`` and keeps ``claimed_at``. ``expires_in`` is
         seconds from now; ``None`` never expires. Returns ``(before,
-        after)`` pairs so the caller can log what a ``force`` took over.
-        Callers check that the things exist."""
+        after)`` pairs so the caller can log what a ``force`` took over;
+        a forced claim on a thing also takes over other users' claims on
+        its parts, and those appear as pairs too. Callers check that the
+        things exist."""
         purpose = validate_purpose(purpose)
         assisted_by = validate_assisted_by(assisted_by)
         if expires_in is not None and expires_in <= 0:
@@ -260,14 +308,16 @@ class Store:
         with _WRITE_LOCK, self._conn() as conn:
             before = {n: self._claim_row(conn, n) for n in unique}
             live = {n: c for n, c in before.items() if c is not None and c.is_live(at)}
-            blockers = [c for c in live.values() if c.holder != holder]
+            others = [c for c in self._live_rows(conn, at) if c.holder != holder]
+            blockers = [c for c in others if any(overlaps(c.thing, n) for n in unique)]
             if blockers and not force:
                 raise ClaimConflict(blockers, at)
             out: builtins.list[tuple[Claim | None, Claim]] = []
+            afters: dict[str, Claim] = {}
             for n in unique:
                 prior = live.get(n)
                 since = prior.claimed_at if prior and prior.holder == holder else ts(at)
-                after = Claim(n, holder, purpose, since, assisted_by, expires_at)
+                after = afters[n] = Claim(n, holder, purpose, since, assisted_by, expires_at)
                 conn.execute(
                     "INSERT OR REPLACE INTO claims "
                     "(thing, holder, assisted_by, purpose, claimed_at, expires_at) "
@@ -275,6 +325,11 @@ class Store:
                     (n, holder, assisted_by, purpose, since, expires_at),
                 )
                 out.append((prior, after))
+            for b in blockers:
+                if b.thing not in afters:
+                    conn.execute("DELETE FROM claims WHERE thing = ?", (b.thing,))
+                    covering_name = next(n for n in unique if overlaps(b.thing, n))
+                    out.append((b, afters[covering_name]))
         return out
 
     def release(
@@ -313,6 +368,11 @@ class Store:
             ).fetchall()
         return [c for c in (Claim(**dict(r)) for r in rows) if c.is_live(at)]
 
+    @staticmethod
+    def _live_rows(conn: sqlite3.Connection, at: datetime) -> builtins.list[Claim]:
+        rows = conn.execute("SELECT * FROM claims").fetchall()
+        return [c for c in (Claim(**dict(r)) for r in rows) if c.is_live(at)]
+
     @staticmethod
     def _claim_row(conn: sqlite3.Connection, name: str) -> Claim | None:
         row = conn.execute("SELECT * FROM claims WHERE thing = ?", (name,)).fetchone()

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/src/dibs/app.py

@@ -31,7 +31,7 @@ from pydantic import BaseModel, Field
 
 import dibs
 from dibs._sources import Config, PixieSource, load_config, sync
-from dibs._store import Claim, ClaimConflict, Store, Thing, sentence
+from dibs._store import Claim, ClaimConflict, Store, Thing, covering, describe, sentence
 from dibs._users import DuplicateUser, LoginFailed, NotApproved, UsersStore
 
 log = logging.getLogger("dibs")
@@ -80,19 +80,28 @@ def current_user(request: Request) -> str:
     return str(user)
 
 
-def _view(name: str, thing: Thing | None, claim: Claim | None, now: datetime) -> dict[str, Any]:
-    """One thing as the API shows it. A claim on a thing no source lists
-    any more still shows, with ``source`` ``gone``, so it can be released."""
+def _view(
+    name: str, thing: Thing | None, claims: dict[str, Claim], now: datetime
+) -> dict[str, Any]:
+    """One thing as the API shows it. ``claim`` is a claim on this very
+    name; ``covered_by`` lists every live claim that says who is on it,
+    which for a part includes its thing's claim and for a thing its
+    parts'. A claim on a thing no source lists any more still shows,
+    with ``source`` ``gone``, so it can be released."""
     out: dict[str, Any] = {
         "name": name,
         "kind": thing.kind if thing else "unknown",
         "source": thing.source if thing else "gone",
-        "sentence": sentence(name, claim, now),
+        "sentence": describe(name, claims, now),
     }
     if thing and thing.attrs:
         out["attrs"] = thing.attrs
-    if claim is not None and claim.is_live(now):
-        out["claim"] = claim.to_dict()
+    own = claims.get(name)
+    if own is not None and own.is_live(now):
+        out["claim"] = own.to_dict()
+    found = covering(name, claims, now)
+    if found:
+        out["covered_by"] = [{"thing": c.thing, **c.to_dict()} for c in found]
     return out
 
 
@@ -153,16 +162,17 @@ def create_app(
         things = {t.name: t for t in store.list_things()}
         claims = store.list_claims()
         names = sorted(set(things) | {n for n, c in claims.items() if c.is_live(now)})
-        return {"things": [_view(n, things.get(n), claims.get(n), now) for n in names]}
+        return {"things": [_view(n, things.get(n), claims, now) for n in names]}
 
     @app.get("/things/{name}")
     def get_thing(name: str) -> dict[str, Any]:
         now = datetime.now(UTC)
+        name = name.strip().lower()
         thing = store.get_thing(name)
-        claim = store.get_claim(name.strip().lower())
-        if thing is None and claim is None:
+        claims = store.list_claims()
+        if thing is None and name not in claims:
             raise HTTPException(status_code=404, detail=f"no such thing: {name}")
-        out = _view(name.strip().lower(), thing, claim, now)
+        out = _view(name, thing, claims, now)
         if thing is not None and thing.source in app.state.pixies:
             info = app.state.pixies[thing.source].info(thing.name)
             if info is not None:
@@ -174,7 +184,7 @@ def create_app(
         name = name.strip().lower()
         if store.get_thing(name) is None:
             raise HTTPException(status_code=404, detail=f"no such thing: {name}")
-        return PlainTextResponse(sentence(name, store.get_claim(name), datetime.now(UTC)) + "\n")
+        return PlainTextResponse(describe(name, store.list_claims(), datetime.now(UTC)) + "\n")
 
     @app.get("/claim", response_class=PlainTextResponse)
     def claim_for_host(mac: str = "", host: str = "") -> PlainTextResponse:
@@ -183,7 +193,7 @@ def create_app(
         thing = store.thing_by_mac(mac.split(",")) or (store.get_thing(host) if host else None)
         if thing is None:
             raise HTTPException(status_code=404, detail="not a thing dibs knows")
-        text = sentence(thing.name, store.get_claim(thing.name), datetime.now(UTC))
+        text = describe(thing.name, store.list_claims(), datetime.now(UTC))
         return PlainTextResponse(text + "\n")
 
     @app.post("/claims")
@@ -209,7 +219,9 @@ def create_app(
                 log.warning("%s took %s from %s", user, after.thing, before.holder)
             log.info("%s", sentence(after.thing, after, now))
         things = {t.name: t for t in store.list_things()}
-        return {"things": [_view(a.thing, things.get(a.thing), a, now) for _, a in pairs]}
+        claims = store.list_claims()
+        claimed = list(dict.fromkeys(a.thing for _, a in pairs))
+        return {"things": [_view(n, things.get(n), claims, now) for n in claimed]}
 
     @app.post("/claims/release")
     def release(body: ReleaseBody, user: str = Depends(current_user)) -> dict[str, Any]:
@@ -225,9 +237,10 @@ def create_app(
         except ClaimConflict as exc:
             raise _conflict(exc) from exc
         things = {t.name: t for t in store.list_things()}
+        claims = store.list_claims()
         for c in released:
             log.info("%s released %s (held by %s)", user, c.thing, c.holder)
-        return {"things": [_view(c.thing, things.get(c.thing), None, now) for c in released]}
+        return {"things": [_view(c.thing, things.get(c.thing), claims, now) for c in released]}
 
     @app.post("/auth/register", status_code=202)
     def register(body: RegisterBody) -> dict[str, str]:

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/src/dibs/cli.py

@@ -41,6 +41,7 @@ EXIT_ERROR = 2
 
 DEFAULT_PORT = 8090
 UNIT_NAME = "dibs.service"
+SERVICE_USER = "dibs"
 
 _DURATION_RE = re.compile(r"^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$")
 _DEFAULT_KEYS = ("id_ed25519.pub", "id_ecdsa.pub", "id_rsa.pub")
@@ -405,10 +406,12 @@ ConfigurationDirectory=dibs
 Restart=on-failure"""
         target = "default.target"
     else:
-        # DynamicUser gives the service a throwaway system user that owns
-        # only its StateDirectory, so it needs no account set up.
+        # A static user rather than DynamicUser=: ssh-keygen looks its own
+        # user up, and a dynamic user resolves only where nss-systemd is set
+        # up, which plain Debian does not do.
         service = f"""ExecStart={serve}
-DynamicUser=yes
+User={SERVICE_USER}
+Group={SERVICE_USER}
 StateDirectory=dibs
 ConfigurationDirectory=dibs
 Restart=on-failure
@@ -444,6 +447,25 @@ def _systemctl(user: bool, *argv: str) -> None:
         raise CliError(f"{' '.join(cmd)} failed")
 
 
+def ensure_service_user() -> None:
+    """Create the ``dibs`` system user the system service runs as, once."""
+    if subprocess.run(["getent", "passwd", SERVICE_USER], capture_output=True).returncode == 0:
+        return
+    cmd = [
+        "useradd",
+        "--system",
+        "--user-group",
+        "--home-dir",
+        "/var/lib/dibs",
+        "--no-create-home",
+        "--shell",
+        "/usr/sbin/nologin",
+        SERVICE_USER,
+    ]
+    if subprocess.run(cmd).returncode != 0:
+        raise CliError(f"{' '.join(cmd)} failed; run dibs server install as root")
+
+
 def cmd_server_install(args: argparse.Namespace) -> None:
     exe = _exe()
     if not args.user and str(exe).startswith(str(Path.home())):
@@ -455,11 +477,16 @@ def cmd_server_install(args: argparse.Namespace) -> None:
     if args.print:
         sys.stdout.write(text)
         return
+    if not args.user:
+        ensure_service_user()
     path = unit_path(args.user)
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(text)
     _systemctl(args.user, "daemon-reload")
-    _systemctl(args.user, "enable", "--now", UNIT_NAME)
+    _systemctl(args.user, "enable", UNIT_NAME)
+    # Restart rather than start, so installing over a running service, as
+    # an upgrade does, replaces the process with the new code and unit.
+    _systemctl(args.user, "restart", UNIT_NAME)
     print(f"Installed {path} and started it; dibs listens on port {args.port}.")
     if args.user:
         print("To keep it running while you are logged out: loginctl enable-linger")
@@ -521,6 +548,25 @@ def cmd_admin_revoke(args: argparse.Namespace) -> None:
     print(f"Revoked {count} token(s) of '{args.name}'; they must log in again.")
 
 
+# ---- agent skill -----------------------------------------------------------
+
+SKILL = Path(__file__).parent / "skill" / "SKILL.md"
+
+
+def cmd_skill(args: argparse.Namespace) -> None:
+    """Install the Claude Code skill that teaches an agent to claim
+    machines before using them, or print it for another agent's setup."""
+    text = SKILL.read_text()
+    if args.action == "print":
+        sys.stdout.write(text)
+        return
+    target = Path(args.dir).expanduser() if args.dir else Path.home() / ".claude" / "skills"
+    path = target / "dibs" / "SKILL.md"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+    print(f"Installed {path}. Claude Code picks it up in new sessions.")
+
+
 # ---- shell completion ------------------------------------------------------
 
 # Commands whose positional arguments are thing names, which the
@@ -703,6 +749,11 @@ def build_parser() -> argparse.ArgumentParser:
         user_mode(p)
         p.set_defaults(func=func)
 
+    p = sub.add_parser("skill", help="install the agent skill that says how to use dibs")
+    p.add_argument("action", choices=["install", "print"])
+    p.add_argument("--dir", help="skills directory (default: ~/.claude/skills)")
+    p.set_defaults(func=cmd_skill)
+
     p = sub.add_parser("completion", help="print a shell completion script")
     p.add_argument("shell", choices=["bash"])
     p.set_defaults(func=cmd_completion)

pixie_lab_dibs-0.2.0/src/dibs/skill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: dibs
+description: Claim a shared lab machine with dibs before using it, and release it after. Use before you SSH into, run tests on, flash, reboot, power-cycle, or open the BMC or console of any lab machine (e.g. epyc-01, epyc-02, ryzen-01), including through cijoe, ipmitool or Redfish.
+---
+
+<!--
+SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# Claim lab machines with dibs
+
+Lab machines are shared with people, other agents and CI. dibs says who
+is on which. A claim is a note, not a lock: nothing stops you from
+logging in to a machine someone else holds, so it is on you not to.
+
+## Before you touch a machine
+
+1. Look: `dibs list`. Use `dibs list --json` to read it, not the text.
+
+1. Claim it, naming yourself as an agent and saying what for:
+
+   ```
+   DIBS_ASSISTED_BY="Claude Code:<your model id>" dibs claim <machine> --for "<what you are doing>"
+   ```
+
+   Set `DIBS_ASSISTED_BY` on every dibs command, inline, so each one
+   agrees on who you are. It uses your human's login; you need no login
+   of your own.
+
+1. Exit status 1 means someone else holds it. Do not use the machine and
+   do not pass `--force`. Tell your human who holds it (the error says)
+   and ask what to do.
+
+Anything that goes through the BMC or affects the whole box needs the
+whole machine: power-cycling, the serial or graphical console, booting
+or reflashing it, firmware, and kernel or driver changes. Claim
+`<machine>` for those.
+
+Some machines list parts in `dibs list`, named `<machine>.<part>`. Claim
+a part only when your work stays inside it and cannot disturb the rest
+of the machine; claiming the machine takes all of its parts. Claim
+several things in one command; it is all or nothing.
+
+## When you are done
+
+Release what you claimed, and also when the work fails, is abandoned, or
+waits on your human for long:
+
+```
+DIBS_ASSISTED_BY="Claude Code:<your model id>" dibs release --mine
+```
+
+This releases only what you claimed, not your human's own claims.
+
+## Never
+
+- Use a machine claimed by someone else, or one you have not claimed.
+- Pass `--force`, or release a claim you did not make.
+- Power-cycle, reflash, reboot or use the BMC of a machine when you hold
+  only a part of it.
+
+If `dibs` is not installed or `DIBS_URL` is not set, stop and tell your
+human rather than going ahead without a claim.

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/tests/test_app.py

@@ -153,3 +153,26 @@ def test_hook_sends_macs_and_hostname_once(hook: Path, tmp_path: Path) -> None:
     assert r.stdout == ""
     sent = calls.read_text().splitlines()
     assert len(sent) == 1 and "mac=" in sent[0] and "host=" in sent[0]
+
+
+def test_parts_over_the_api(client: TestClient, tokens, tmp_path: Path) -> None:
+    """A part and its thing, through claim, list, the text route and the
+    login hook's lookup."""
+    config = client.app.state.config  # type: ignore[attr-defined]
+    from dibs._store import Thing
+
+    config.things.append(Thing("ryzen-01.bmc", "machine", "config", {"host": "10.0.0.61"}))
+    client.app.state.sync()  # type: ignore[attr-defined]
+    assert _claim(client, tokens, "ryzen-01.bmc", who="bob").status_code == 200
+    r = _claim(client, tokens, "ryzen-01")
+    assert r.status_code == 409
+    assert r.json()["detail"]["claimed"] == [
+        "'bob' has claimed 'ryzen-01.bmc' for 'xnvme' expires in: 'never'"
+    ]
+    things = {t["name"]: t for t in client.get("/things").json()["things"]}
+    assert things["ryzen-01"]["sentence"].startswith("'bob' has claimed 'ryzen-01.bmc'")
+    assert "claim" not in things["ryzen-01"]
+    assert things["ryzen-01"]["covered_by"][0]["thing"] == "ryzen-01.bmc"
+    # The login hook on ryzen-01 (by MAC) sees the part's claim.
+    hook = client.get("/claim", params={"mac": "aa:bb:cc:dd:ee:60"}).text
+    assert hook.startswith("'bob' has claimed 'ryzen-01.bmc'")

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/tests/test_cli.py

@@ -128,7 +128,7 @@ def test_system_unit_runs_this_dibs_sandboxed() -> None:
     text = cli.unit_text(Path("/usr/local/bin/dibs"), user=False, host="0.0.0.0", port=8090)
     assert "ExecStart=/usr/local/bin/dibs serve --host 0.0.0.0 --port 8090\n" in text
     for line in (
-        "DynamicUser=yes",
+        "User=dibs",
         "StateDirectory=dibs",
         "ProtectHome=yes",
         "WantedBy=multi-user.target",
@@ -155,7 +155,8 @@ def test_server_install_writes_enables_and_controls(
     assert "--port 9000 --user" in unit.read_text()
     assert calls == [
         ["systemctl", "--user", "daemon-reload"],
-        ["systemctl", "--user", "enable", "--now", "dibs.service"],
+        ["systemctl", "--user", "enable", "dibs.service"],
+        ["systemctl", "--user", "restart", "dibs.service"],
     ]
     calls.clear()
     cli.main(["server", "stop", "--user"])
@@ -175,6 +176,29 @@ def test_server_install_writes_enables_and_controls(
     ]
 
 
+def test_system_unit_avoids_dynamic_user() -> None:
+    """ssh-keygen needs its user to resolve, and a DynamicUser= user does
+    not resolve without nss-systemd (plain Debian has none)."""
+    text = cli.unit_text(Path("/usr/local/bin/dibs"), user=False, host="0.0.0.0", port=8090)
+    assert "DynamicUser" not in text and "User=dibs\nGroup=dibs\n" in text
+
+
+@pytest.mark.parametrize(("exists", "want_useradd"), [(True, False), (False, True)])
+def test_service_user_is_created_once(
+    monkeypatch: pytest.MonkeyPatch, exists: bool, want_useradd: bool
+) -> None:
+    calls: list[list[str]] = []
+
+    def fake_run(cmd: list[str], *a: Any, **kw: Any) -> subprocess.CompletedProcess[str]:
+        calls.append(cmd)
+        return subprocess.CompletedProcess(cmd, 0 if exists or cmd[0] != "getent" else 2)
+
+    monkeypatch.setattr(cli.subprocess, "run", fake_run)
+    cli.ensure_service_user()
+    assert calls[0] == ["getent", "passwd", "dibs"]
+    assert any(c[0] == "useradd" and c[-1] == "dibs" for c in calls) == want_useradd
+
+
 def test_system_install_refuses_a_dibs_in_home(monkeypatch: pytest.MonkeyPatch, capsys) -> None:
     monkeypatch.setattr(cli, "_exe", lambda: Path.home() / ".local" / "bin" / "dibs")
     assert cli.main(["server", "install"]) == cli.EXIT_ERROR
@@ -235,3 +259,29 @@ def test_bash_completion(tmp_path: Path, capsys) -> None:
     assert _complete(script, "dibs claim --e", tmp_path) == ["--expires"]
     assert _complete(script, "dibs claim w", tmp_path) == ["warp"]
     assert "--names" not in _complete(script, "dibs list --", tmp_path)
+
+
+def test_skill_install_and_print(tmp_path: Path, capsys) -> None:
+    assert cli.main(["skill", "install", "--dir", str(tmp_path)]) == 0
+    installed = (tmp_path / "dibs" / "SKILL.md").read_text()
+    assert installed.startswith("---\nname: dibs\n")
+    assert "dibs release --mine" in installed and "--force" in installed
+    capsys.readouterr()
+    assert cli.main(["skill", "print"]) == 0
+    assert capsys.readouterr().out == installed
+
+
+def test_skill_ships_in_the_wheel(tmp_path: Path) -> None:
+    """The skill is data, not code, so check the built wheel carries it."""
+    import zipfile
+
+    if shutil.which("uv") is None:
+        pytest.skip("needs uv")
+    subprocess.run(
+        ["uv", "build", "--wheel", "--out-dir", str(tmp_path)],
+        cwd=Path(__file__).parent.parent,
+        check=True,
+        capture_output=True,
+    )
+    wheel = next(tmp_path.glob("*.whl"))
+    assert "dibs/skill/SKILL.md" in zipfile.ZipFile(wheel).namelist()

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/tests/test_sources.py

@@ -72,3 +72,11 @@ def test_a_machine_pixie_forgets_disappears(tmp_path: Path, pixie: FakePixie) ->
     pixie.machines = [m for m in pixie.machines if m.get("name") != "warp"]
     sync(store, load_config(tmp_path / "dibs.toml"), [pixie.source()])
     assert "warp" not in {t.name for t in store.list_things()}
+
+
+def test_a_part_alone_makes_its_thing_claimable(tmp_path: Path) -> None:
+    path = tmp_path / "dibs.toml"
+    path.write_text('[[thing]]\nname = "box.bmc"\nhost = "10.0.0.2"\n')
+    store = Store(tmp_path / "dibs.db")
+    sync(store, load_config(path), [])
+    assert [t.name for t in store.list_things()] == ["box", "box.bmc"]

{pixie_lab_dibs-0.1.0 → pixie_lab_dibs-0.2.0}/tests/test_store.py

@@ -113,3 +113,75 @@ def test_claimed_by_is_scoped_to_assisted_by(store: Store) -> None:
 def test_claim_rejects_bad_text(store: Store, purpose: str, assisted_by: str) -> None:
     with pytest.raises(ValueError):
         store.claim(["a"], holder="alice", purpose=purpose, assisted_by=assisted_by, now=T0)
+
+
+# ---- parts ----------------------------------------------------------------
+
+
+@pytest.mark.parametrize("name", ["epyc-02", "epyc-02.bmc", "a.b"])
+def test_part_names_are_accepted(name: str) -> None:
+    from dibs._store import validate_thing_name
+
+    assert validate_thing_name(name) == name
+
+
+@pytest.mark.parametrize("name", ["epyc-02.", ".bmc", "a.b.c", "a..b", "a.-b"])
+def test_bad_part_names_are_refused(name: str) -> None:
+    from dibs._store import validate_thing_name
+
+    with pytest.raises(ValueError):
+        validate_thing_name(name)
+
+
+def test_two_users_may_hold_different_parts(store: Store) -> None:
+    store.claim(["box.ssh"], holder="alice", purpose="x", now=T0)
+    store.claim(["box.bmc"], holder="bob", purpose="y", now=T0)
+    assert {n: c.holder for n, c in store.list_claims().items()} == {
+        "box.ssh": "alice",
+        "box.bmc": "bob",
+    }
+
+
+def test_the_whole_thing_conflicts_with_another_users_part(store: Store) -> None:
+    store.claim(["box.bmc"], holder="bob", purpose="y", now=T0)
+    with pytest.raises(ClaimConflict) as exc:
+        store.claim(["box"], holder="alice", purpose="x", now=T0)
+    assert exc.value.sentences == ["'bob' has claimed 'box.bmc' for 'y' expires in: 'never'"]
+
+
+def test_a_part_conflicts_with_another_users_whole_thing(store: Store) -> None:
+    store.claim(["box"], holder="bob", purpose="y", now=T0)
+    with pytest.raises(ClaimConflict):
+        store.claim(["box.ssh"], holder="alice", purpose="x", now=T0)
+    # The same user holding the whole thing may also claim a part of it.
+    store.claim(["box.ssh"], holder="bob", purpose="z", now=T0)
+
+
+def test_parts_of_other_things_do_not_conflict(store: Store) -> None:
+    store.claim(["box.bmc"], holder="bob", purpose="y", now=T0)
+    store.claim(["boxer", "boxer.bmc"], holder="alice", purpose="x", now=T0)
+
+
+def test_forcing_the_whole_thing_takes_over_its_parts(store: Store) -> None:
+    store.claim(["box.bmc"], holder="bob", purpose="y", now=T0)
+    pairs = store.claim(["box"], holder="alice", purpose="x", force=True, now=T0)
+    taken = [(b.thing, b.holder, a.thing) for b, a in pairs if b is not None]
+    assert taken == [("box.bmc", "bob", "box")]
+    assert set(store.list_claims()) == {"box"}
+
+
+def test_describe_reads_through_parts_and_wholes(store: Store) -> None:
+    from dibs._store import describe
+
+    store.claim(["box.bmc"], holder="bob", purpose="power", now=T0)
+    claims = store.list_claims()
+    assert (
+        describe("box", claims, T0) == "'bob' has claimed 'box.bmc' for 'power' expires in: 'never'"
+    )
+    assert describe("box.ssh", claims, T0) == "'box.ssh' is free"
+    store.release(["box.bmc"], holder="bob", now=T0)
+    store.claim(["box"], holder="alice", purpose="all", now=T0)
+    claims = store.list_claims()
+    assert (
+        describe("box.ssh", claims, T0) == "'alice' has claimed 'box' for 'all' expires in: 'never'"
+    )

pixie_lab_dibs-0.1.0/CHANGELOG.md

@@ -1,23 +0,0 @@
-<!--
-SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
-
-SPDX-License-Identifier: BSD-3-Clause
--->
-
-# Changelog
-
-Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-
-## [Unreleased]
-
-## [0.1.0] - 2026-10-27
-
-### Added
-
-- The first version: things to claim, fed from a config file and from
-  pixie servers; claims that are all or nothing, never expire unless
-  asked to, and say when an agent made them; users who register an SSH
-  public key, are approved by the admin, and log in by signing a
-  one-time challenge; a login hook that shows a machine's claim; and
-  one `dibs` command for the server, its systemd service, the admin, and
-  everyone claiming.