pixie-lab-dibs 0.1.1__tar.gz → 0.2.1__tar.gz

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/.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.1.1 → pixie_lab_dibs-0.2.1}/CHANGELOG.md

@@ -10,6 +10,27 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-27
+
+### Added
+
+- `GET /agents` explains the server to whoever is pointed at it: setup
+  with this server's URL filled in, what is claimed right now, and the
+  agent skill's rules. The web page links to it.
+
+## [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

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pixie-lab-dibs
-Version: 0.1.1
+Version: 0.2.1
 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>
@@ -144,10 +144,44 @@ 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:
+Every dibs server explains itself at `/agents`: how to set up for this
+very server, with its URL filled in, what is claimed right now, and the
+rules below. So the one thing to tell a person or an agent about a lab
+is "before touching its machines, read `http://dibs:8090/agents`", in a
+prompt, a project's `AGENTS.md`, or a message.
+
+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"
@@ -157,11 +191,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
 
@@ -227,6 +263,7 @@ no login; claim and release take `Authorization: Bearer <token>`.
 | `POST /auth/register`      | `{"user": "...", "pubkey": "ssh-ed25519 ..."}`                                               |
 | `POST /auth/challenge`     | `{"user": "..."}` gives a nonce and the message to sign                                      |
 | `POST /auth/login`         | `{"user", "nonce", "signature"}` gives a token                                               |
+| `GET /agents`              | how to use this server, for a person or an agent, as text                                    |
 | `GET /login.sh`            | the login hook                                                                               |
 
 A claim or release blocked by someone else's claim answers 409 with

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/README.md

@@ -122,10 +122,44 @@ 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:
+Every dibs server explains itself at `/agents`: how to set up for this
+very server, with its URL filled in, what is claimed right now, and the
+rules below. So the one thing to tell a person or an agent about a lab
+is "before touching its machines, read `http://dibs:8090/agents`", in a
+prompt, a project's `AGENTS.md`, or a message.
+
+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"
@@ -135,11 +169,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
 
@@ -205,6 +241,7 @@ no login; claim and release take `Authorization: Bearer <token>`.
 | `POST /auth/register`      | `{"user": "...", "pubkey": "ssh-ed25519 ..."}`                                               |
 | `POST /auth/challenge`     | `{"user": "..."}` gives a nonce and the message to sign                                      |
 | `POST /auth/login`         | `{"user", "nonce", "signature"}` gives a token                                               |
+| `GET /agents`              | how to use this server, for a person or an agent, as text                                    |
 | `GET /login.sh`            | the login hook                                                                               |
 
 A claim or release blocked by someone else's claim answers 409 with

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/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.1"
+__version__ = "0.2.1"

pixie_lab_dibs-0.2.1/src/dibs/_skill.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: Simon A. F. Lund <os@safl.dk>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""The agent skill, shared by ``dibs skill`` and the server's ``/agents``
+page, so both say exactly the same thing."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SKILL_PATH = Path(__file__).parent / "skill" / "SKILL.md"
+
+# The YAML frontmatter Claude Code reads, then the REUSE comment.
+_PREAMBLE = re.compile(r"\A---\n.*?\n---\n\s*<!--.*?-->\s*", re.DOTALL)
+
+
+def skill_text() -> str:
+    """The skill as Claude Code installs it."""
+    return SKILL_PATH.read_text()
+
+
+def skill_body() -> str:
+    """The protocol alone, for readers that are not Claude Code."""
+    return _PREAMBLE.sub("", skill_text(), count=1)

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/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.1 → pixie_lab_dibs-0.2.1}/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.1 → pixie_lab_dibs-0.2.1}/src/dibs/app.py

@@ -30,8 +30,9 @@ from fastapi.responses import HTMLResponse, PlainTextResponse, Response
 from pydantic import BaseModel, Field
 
 import dibs
+from dibs._skill import skill_body
 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 +81,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 +163,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 +185,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 +194,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 +220,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 +238,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]:
@@ -284,6 +298,16 @@ def create_app(
         login. It points back at whichever dibs URL fetched it."""
         return PlainTextResponse(LOGIN_HOOK.format(base=str(request.base_url)))
 
+    @app.get("/agents", response_class=PlainTextResponse)
+    def agents(request: Request) -> PlainTextResponse:
+        """How to use dibs on this lab, for a person or an agent pointed at
+        it: the setup with this server's URL filled in, what is claimed
+        right now, then the protocol from the agent skill."""
+        base = str(request.base_url).rstrip("/")
+        now_lines = "\n".join(f"- {t['sentence']}" for t in list_things()["things"])
+        page = AGENTS_PAGE.format(base=base, now=now_lines or "- nothing to claim yet")
+        return PlainTextResponse(page + "\n" + skill_body(), media_type="text/plain; charset=utf-8")
+
     @app.get("/", response_class=HTMLResponse)
     def index() -> HTMLResponse:
         rows = list_things()["things"]
@@ -324,6 +348,30 @@ case $- in *i*)
 esac
 """
 
+AGENTS_PAGE = """\
+# dibs on this lab
+
+The machines on this lab are shared by people, ai-agents and
+automation-runners, and claimed with dibs at {base}. Read this before you
+touch any of them.
+
+## Set up, once per machine you work from
+
+```
+uv tool install pixie-lab-dibs
+export DIBS_URL={base}
+dibs register <your name>      # then ask the lab's admin to approve you
+dibs login
+```
+
+An agent uses its human's login and needs none of its own. For Claude
+Code, `dibs skill install` makes the rules below load by themselves.
+
+## Right now
+
+{now}
+"""
+
 PAGE = """<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>dibs</title>
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -334,7 +382,8 @@ td, th {{ text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #ddd;
 </style></head><body>
 <h1>dibs</h1>
 <p>Who is using which thing. Claim one with
-<code>dibs claim &lt;name&gt; --for &lt;purpose&gt;</code>.</p>
+<code>dibs claim &lt;name&gt; --for &lt;purpose&gt;</code>.
+New here, or an agent? Read <a href="/agents">/agents</a>.</p>
 <table><thead><tr><th>Name</th><th>Kind</th><th>Claim</th></tr></thead>
 <tbody>
 {rows}

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/src/dibs/cli.py

@@ -548,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 -----------------------------------------------------------
+
+
+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."""
+    from dibs._skill import skill_text
+
+    text = skill_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
@@ -730,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.1/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.1 → pixie_lab_dibs-0.2.1}/tests/test_app.py

@@ -153,3 +153,41 @@ 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'")
+
+
+def test_agents_page_is_set_up_for_this_server(client: TestClient, tokens) -> None:
+    from dibs._skill import skill_body
+
+    _claim(client, tokens, "warp")
+    r = client.get("/agents")
+    assert r.headers["content-type"].startswith("text/plain")
+    page = r.text
+    assert "export DIBS_URL=http://testserver\n" in page
+    assert "- 'alice' has claimed 'warp' for 'xnvme' expires in: 'never'" in page
+    assert page.endswith(skill_body())
+    # The skill's Claude Code frontmatter and licence comment are not for this reader.
+    assert "name: dibs" not in page and "SPDX" not in page
+    assert '<a href="/agents">' in client.get("/").text

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/tests/test_cli.py

@@ -259,3 +259,37 @@ 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()
+
+
+def test_skill_body_drops_only_the_preamble() -> None:
+    from dibs._skill import skill_body, skill_text
+
+    body = skill_body()
+    assert body.startswith("# Claim lab machines with dibs\n")
+    assert skill_text().endswith(body)

{pixie_lab_dibs-0.1.1 → pixie_lab_dibs-0.2.1}/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.1 → pixie_lab_dibs-0.2.1}/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'"
+    )