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

{pixie_lab_dibs-0.2.0 → pixie_lab_dibs-0.3.0}/CHANGELOG.md

@@ -10,6 +10,35 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-27
+
+### Added
+
+- Agent sessions: `DIBS_SESSION` tags the claims of one agent session,
+  with a random tag from `dibs session`,
+  and claims read `... assisted by 'Claude Code:<model>' (session <tag>) ...`. `release --mine` releases only that session's claims.
+- `dibs whoami` shows who claims are made as, and fails when nobody has
+  logged in, so an agent can tell setup is missing.
+- `/agents` and the skill now say who does what: a person sets up once
+  per workstation, and every agent there uses that login, never
+  registering itself.
+
+### Changed
+
+- A claim belongs to its actor, the user with their agent and session,
+  rather than to the user alone. Two agents of one person, or a person
+  and their agent, now conflict when claiming the same thing, instead of
+  the second silently taking over. A person claiming by hand can still
+  release any of their agents' claims without `--force`.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pixie-lab-dibs
-Version: 0.2.0
+Version: 0.3.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>
@@ -167,6 +167,12 @@ the thing (`bmc = "10.20.30.82"`) rather than a part.
 
 ### AI-agents
 
+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:
 
@@ -174,24 +180,31 @@ 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:
+`dibs skill print` shows it, to adapt for another agent.
+
+An agent never registers or logs in. It claims with its human's login,
+names itself the way an `Assisted-by:` trailer does, and tags its
+session with a tag from `dibs session`, so that two agents of one person
+do not take or release each other's claims. The login is shared; the
+tag is not, because each agent passes its own on its commands:
 
 ```
-export DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5"
+DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5" DIBS_SESSION=s-3f2a9c41 dibs claim epyc-02 --for "ring test"
 ```
 
-The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' has claimed ...`.
+The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' (session s-3f2a9c41) has claimed ...`. Another session cannot claim
+over it or release it without `--force`. The human, claiming by hand,
+can release any of their agents' claims, but needs `--force` to claim
+over one.
 
-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>`. 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.
+If you are an agent reading this: run `dibs whoami` first; if it fails,
+stop and tell your human, never register yourself. Before you run
+anything on a lab machine, run `dibs list` and claim the machine.
+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 with `dibs release --mine` when the work is done, and also when
+it fails or is abandoned. That releases only your session's claims.
 
 ### Automation-runners
 
@@ -257,6 +270,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.2.0 → pixie_lab_dibs-0.3.0}/README.md

@@ -145,6 +145,12 @@ the thing (`bmc = "10.20.30.82"`) rather than a part.
 
 ### AI-agents
 
+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:
 
@@ -152,24 +158,31 @@ 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:
+`dibs skill print` shows it, to adapt for another agent.
+
+An agent never registers or logs in. It claims with its human's login,
+names itself the way an `Assisted-by:` trailer does, and tags its
+session with a tag from `dibs session`, so that two agents of one person
+do not take or release each other's claims. The login is shared; the
+tag is not, because each agent passes its own on its commands:
 
 ```
-export DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5"
+DIBS_ASSISTED_BY="Claude Code:claude-opus-5-5" DIBS_SESSION=s-3f2a9c41 dibs claim epyc-02 --for "ring test"
 ```
 
-The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' has claimed ...`.
+The claim then reads `'alice' assisted by 'Claude Code:claude-opus-5-5' (session s-3f2a9c41) has claimed ...`. Another session cannot claim
+over it or release it without `--force`. The human, claiming by hand,
+can release any of their agents' claims, but needs `--force` to claim
+over one.
 
-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>`. 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.
+If you are an agent reading this: run `dibs whoami` first; if it fails,
+stop and tell your human, never register yourself. Before you run
+anything on a lab machine, run `dibs list` and claim the machine.
+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 with `dibs release --mine` when the work is done, and also when
+it fails or is abandoned. That releases only your session's claims.
 
 ### Automation-runners
 
@@ -235,6 +248,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.2.0 → pixie_lab_dibs-0.3.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.2.0"
+__version__ = "0.3.0"

pixie_lab_dibs-0.3.0/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.2.0 → pixie_lab_dibs-0.3.0}/src/dibs/_store.py

@@ -17,6 +17,13 @@ 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.
 
+A claim is made by an **actor**: the user, and when an agent claims for
+them, the agent (``assisted_by``) and its session. One actor cannot claim
+over another's claim, even of the same user, so two agents of one person
+do not collide unnoticed. Releasing is the same, except that the user
+claiming by hand, without agent or session, may release any claim made
+under their name: an agent answers to its human.
+
 Every surface (``dibs``, the web page, the login hook on a machine)
 prints a claim as the same sentence, from :func:`sentence`.
 """
@@ -47,6 +54,9 @@ THING_NAME_RE = re.compile(rf"^{_LABEL}(\.{_LABEL})?$")
 PURPOSE_MAX = 128
 ASSISTED_BY_MAX = 64
 
+# Short, and plain, since it is typed into every command of a session.
+SESSION_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$")
+
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS things (
     name       TEXT PRIMARY KEY,
@@ -61,7 +71,8 @@ CREATE TABLE IF NOT EXISTS claims (
     assisted_by  TEXT NOT NULL DEFAULT '',
     purpose      TEXT NOT NULL,
     claimed_at   TEXT NOT NULL,
-    expires_at   TEXT NOT NULL DEFAULT ''
+    expires_at   TEXT NOT NULL DEFAULT '',
+    session      TEXT NOT NULL DEFAULT ''
 );
 """
 
@@ -117,6 +128,14 @@ def validate_assisted_by(raw: str) -> str:
     return _one_line("assisted_by", raw, ASSISTED_BY_MAX) if (raw or "").strip() else ""
 
 
+def validate_session(raw: str) -> str:
+    """Optional, so blank passes."""
+    value = (raw or "").strip()
+    if value and not SESSION_RE.match(value):
+        raise ValueError(f"session {value!r} must be letters, digits, . _ or -, at most 32 chars")
+    return value
+
+
 @dataclass
 class Thing:
     name: str
@@ -139,6 +158,12 @@ class Claim:
     an ``Assisted-by:`` trailer; blank for a claim made by hand."""
     expires_at: str = ""
     """Blank for a claim that never expires."""
+    session: str = ""
+    """Which of the holder's agent sessions made it; blank by hand."""
+
+    @property
+    def actor(self) -> tuple[str, str, str]:
+        return (self.holder, self.assisted_by, self.session)
 
     def is_live(self, now: datetime) -> bool:
         """A claim past its expiry counts as no claim: the thing is free
@@ -153,13 +178,15 @@ class Claim:
         }
         if self.assisted_by:
             out["assisted_by"] = self.assisted_by
+        if self.session:
+            out["session"] = self.session
         if self.expires_at:
             out["expires_at"] = self.expires_at
         return out
 
 
 class ClaimConflict(ValueError):
-    """One or more things are claimed by another user."""
+    """One or more things are claimed by another actor."""
 
     def __init__(self, blockers: Sequence[Claim], now: datetime) -> None:
         self.blockers = list(blockers)
@@ -188,6 +215,8 @@ def sentence(name: str, claim: Claim | None, now: datetime) -> str:
     who = f"'{claim.holder}'"
     if claim.assisted_by:
         who += f" assisted by '{claim.assisted_by}'"
+    if claim.session:
+        who += f" (session {claim.session})"
     return (
         f"{who} has claimed '{claim.thing}' for '{claim.purpose}' "
         f"expires in: '{remaining(claim.expires_at, now)}'"
@@ -222,6 +251,9 @@ class Store:
         self.db_path = Path(db_path)
         with self._conn() as conn:
             conn.executescript(_SCHEMA)
+            cols = {r[1] for r in conn.execute("PRAGMA table_info(claims)")}
+            if "session" not in cols:  # a database from before sessions
+                conn.execute("ALTER TABLE claims ADD COLUMN session TEXT NOT NULL DEFAULT ''")
 
     @contextlib.contextmanager
     def _conn(self) -> Generator[sqlite3.Connection]:
@@ -283,23 +315,25 @@ class Store:
         holder: str,
         purpose: str,
         assisted_by: str = "",
+        session: str = "",
         expires_in: int | None = None,
         force: bool = False,
         now: datetime | None = None,
     ) -> builtins.list[tuple[Claim | None, Claim]]:
-        """Claim every thing in ``names`` for ``holder``, or none of them:
-        if any holds a live claim by another user (and ``force`` is off)
-        this raises :class:`ClaimConflict` and changes nothing.
-        Ownership is the user's: claiming again as the same holder, with
-        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;
-        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."""
+        """Claim every thing in ``names`` for the actor ``holder`` /
+        ``assisted_by`` / ``session``, or none of them: if any holds a live
+        claim by another actor (and ``force`` is off) this raises
+        :class:`ClaimConflict` and changes nothing. Claiming again as the
+        same actor updates the purpose and expiry 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; a forced claim on a thing also takes
+        over other actors' 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)
+        session = validate_session(session)
+        me = (holder, assisted_by, session)
         if expires_in is not None and expires_in <= 0:
             raise ValueError("expires_in must be a positive number of seconds")
         at = now or datetime.now(UTC)
@@ -308,7 +342,7 @@ 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)}
-            others = [c for c in self._live_rows(conn, at) if c.holder != holder]
+            others = [c for c in self._live_rows(conn, at) if c.actor != me]
             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)
@@ -316,13 +350,21 @@ class Store:
             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 = afters[n] = Claim(n, holder, purpose, since, assisted_by, expires_at)
+                since = prior.claimed_at if prior and prior.actor == me else ts(at)
+                after = afters[n] = Claim(
+                    thing=n,
+                    holder=holder,
+                    purpose=purpose,
+                    claimed_at=since,
+                    assisted_by=assisted_by,
+                    expires_at=expires_at,
+                    session=session,
+                )
                 conn.execute(
                     "INSERT OR REPLACE INTO claims "
-                    "(thing, holder, assisted_by, purpose, claimed_at, expires_at) "
-                    "VALUES (?, ?, ?, ?, ?, ?)",
-                    (n, holder, assisted_by, purpose, since, expires_at),
+                    "(thing, holder, assisted_by, purpose, claimed_at, expires_at, session) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (n, holder, assisted_by, purpose, since, expires_at, session),
                 )
                 out.append((prior, after))
             for b in blockers:
@@ -337,34 +379,48 @@ class Store:
         names: Sequence[str],
         *,
         holder: str,
+        assisted_by: str = "",
+        session: str = "",
         force: bool = False,
         now: datetime | None = None,
     ) -> builtins.list[Claim]:
         """Release the claims on ``names``, all or nothing like
-        :meth:`claim`: releasing another user's live claim needs
-        ``force``. Expired claims are cleared whoever holds them. Returns
-        the live claims released."""
+        :meth:`claim`. Without ``force`` an actor may release its own
+        claims, and the user by hand (no agent, no session) may also
+        release its agents'. Expired claims are cleared whoever holds
+        them. Returns the live claims released."""
         at = now or datetime.now(UTC)
         unique = list(dict.fromkeys(names))
+        me = (holder, assisted_by.strip(), session.strip())
+        by_hand = not me[1] and not me[2]
+
+        def mine(c: Claim) -> bool:
+            return c.actor == me or (by_hand and c.holder == holder)
+
         with _WRITE_LOCK, self._conn() as conn:
             before = [c for c in (self._claim_row(conn, n) for n in unique) if c is not None]
-            blockers = [c for c in before if c.is_live(at) and c.holder != holder]
+            blockers = [c for c in before if c.is_live(at) and not mine(c)]
             if blockers and not force:
                 raise ClaimConflict(blockers, at)
             conn.executemany("DELETE FROM claims WHERE thing = ?", [(c.thing,) for c in before])
         return [c for c in before if c.is_live(at)]
 
     def claimed_by(
-        self, holder: str, assisted_by: str = "", *, now: datetime | None = None
+        self,
+        holder: str,
+        assisted_by: str = "",
+        session: str = "",
+        *,
+        now: datetime | None = None,
     ) -> builtins.list[Claim]:
-        """Live claims held by ``holder`` through exactly ``assisted_by``
-        (blank: claimed by hand), so an agent's ``release --mine`` leaves
-        its human's own claims alone."""
+        """Live claims of exactly this actor, so an agent's ``release
+        --mine`` leaves its human's and its other sessions' claims alone."""
         at = now or datetime.now(UTC)
         with self._conn() as conn:
             rows = conn.execute(
-                "SELECT * FROM claims WHERE holder = ? AND assisted_by = ? ORDER BY thing",
-                (holder, assisted_by.strip()),
+                "SELECT * FROM claims WHERE holder = ? AND assisted_by = ? AND session = ? "
+                "ORDER BY thing",
+                (holder, assisted_by.strip(), session.strip()),
             ).fetchall()
         return [c for c in (Claim(**dict(r)) for r in rows) if c.is_live(at)]
 

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

@@ -30,6 +30,7 @@ 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, covering, describe, sentence
 from dibs._users import DuplicateUser, LoginFailed, NotApproved, UsersStore
@@ -41,6 +42,7 @@ class ClaimBody(BaseModel):
     things: list[str] = Field(..., min_length=1)
     purpose: str
     assisted_by: str = Field(default="", description="Agent:model, as in an Assisted-by trailer")
+    session: str = Field(default="", description="Which agent session of the user is claiming")
     expires_in: int | None = Field(default=None, description="Seconds; null never expires")
     force: bool = False
 
@@ -48,7 +50,10 @@ class ClaimBody(BaseModel):
 class ReleaseBody(BaseModel):
     things: list[str] = Field(default_factory=list)
     assisted_by: str = ""
-    mine: bool = Field(default=False, description="Every live claim you hold through assisted_by")
+    session: str = ""
+    mine: bool = Field(
+        default=False, description="Every live claim of this user, assisted_by and session"
+    )
     force: bool = False
 
 
@@ -76,7 +81,11 @@ def current_user(request: Request) -> str:
     """Dependency: the user a bearer token belongs to, else 401."""
     user = request.app.state.users.user_for_token(_bearer(request))
     if user is None:
-        raise HTTPException(status_code=401, detail="not logged in; run: dibs login <user>")
+        raise HTTPException(
+            status_code=401,
+            detail="not logged in; a person sets up with dibs register and dibs login "
+            "(agents use their person's login)",
+        )
     return str(user)
 
 
@@ -206,6 +215,7 @@ def create_app(
                 holder=user,
                 purpose=body.purpose,
                 assisted_by=body.assisted_by,
+                session=body.session,
                 expires_in=body.expires_in,
                 force=body.force,
                 now=now,
@@ -229,11 +239,20 @@ def create_app(
         if body.mine == bool(body.things):
             raise HTTPException(status_code=422, detail="name things to release, or set mine")
         if body.mine:
-            names = [c.thing for c in store.claimed_by(user, body.assisted_by, now=now)]
+            names = [
+                c.thing for c in store.claimed_by(user, body.assisted_by, body.session, now=now)
+            ]
         else:
             names = [n.strip().lower() for n in body.things]
         try:
-            released = store.release(names, holder=user, force=body.force, now=now)
+            released = store.release(
+                names,
+                holder=user,
+                assisted_by=body.assisted_by,
+                session=body.session,
+                force=body.force,
+                now=now,
+            )
         except ClaimConflict as exc:
             raise _conflict(exc) from exc
         things = {t.name: t for t in store.list_things()}
@@ -297,6 +316,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"]
@@ -337,6 +366,53 @@ case $- in *i*)
 esac
 """
 
+AGENTS_PAGE = """\
+# dibs on this lab
+
+The machines on this lab are shared by people, ai-agents and
+automation-runners. Each is claimed with dibs, at {base}, before anyone
+touches it. Read the part for you.
+
+## If you are a person: set up once per workstation
+
+```
+uv tool install pixie-lab-dibs
+echo 'export DIBS_URL={base}' >> ~/.bashrc
+dibs register <name>     # then ask the lab's admin to approve you
+dibs login
+dibs skill install       # Claude Code agents then follow the rules below by themselves
+```
+
+Every agent you run on this workstation uses this login. Agents never
+register or log in themselves.
+
+## If you are an agent: before anything else
+
+1. Check that your human has set up this workstation:
+
+   ```
+   DIBS_URL={base} dibs whoami
+   ```
+
+   It prints your human's name. If it fails, stop, and give your human the
+   setup above. Do not register or log in yourself.
+
+1. Get a session tag for this conversation, once, with `dibs session`, and
+   pass it, with who you are, on every dibs command:
+
+   ```
+   DIBS_URL={base} DIBS_ASSISTED_BY="Claude Code:<model>" DIBS_SESSION=<tag> dibs ...
+   ```
+
+   Your claims then say which agent made them, and no other agent of the
+   same person can take or release them without `--force`.
+
+## 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">
@@ -347,7 +423,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.2.0 → pixie_lab_dibs-0.3.0}/src/dibs/cli.py

@@ -14,7 +14,9 @@ and ``dibs list``, ``info``, ``claim`` and ``release`` use it. The client
 finds the server with ``--url`` or ``DIBS_URL``, keeps its token per URL
 in ``$XDG_CONFIG_HOME/dibs/client.json`` (``DIBS_TOKEN`` overrides it, for
 runners), and an agent sets ``DIBS_ASSISTED_BY`` (``Agent:model``, as in
-an ``Assisted-by:`` trailer) so its claims say so.
+an ``Assisted-by:`` trailer) and ``DIBS_SESSION`` (a tag for this agent
+session) so its claims say which agent made them and other agents of the
+same person leave them alone.
 
 Exit status: 0 done, 1 refused because a thing is claimed by someone
 else, 2 anything else (usage, unknown thing, server unreachable).
@@ -137,6 +139,10 @@ def assisted_by() -> str:
     return os.environ.get("DIBS_ASSISTED_BY", "").strip()
 
 
+def session() -> str:
+    return os.environ.get("DIBS_SESSION", "").strip()
+
+
 def default_key() -> Path:
     for name in _DEFAULT_KEYS:
         path = Path.home() / ".ssh" / name
@@ -312,6 +318,7 @@ def cmd_claim(args: argparse.Namespace) -> None:
         "things": args.things,
         "purpose": args.purpose,
         "assisted_by": assisted_by(),
+        "session": session(),
         "expires_in": args.expires,
         "force": args.force,
     }
@@ -325,6 +332,7 @@ def cmd_release(args: argparse.Namespace) -> None:
     body = {
         "things": args.things,
         "assisted_by": assisted_by(),
+        "session": session(),
         "mine": args.mine,
         "force": args.force,
     }
@@ -363,6 +371,37 @@ def cmd_login(args: argparse.Namespace) -> None:
     print(f"Logged in as '{answer['user']}'.")
 
 
+def cmd_whoami(args: argparse.Namespace) -> None:
+    """Who this workstation's dibs claims as: the user from the login,
+    and the agent and session from the environment. Fails when nobody
+    has logged in, which is how an agent learns setup is missing."""
+    url = _url(args)
+    me: dict[str, str] = {"user": _request(url, "GET", "/auth/whoami")["user"]}
+    if assisted_by():
+        me["assisted_by"] = assisted_by()
+    if session():
+        me["session"] = session()
+    if args.format:
+        sys.stdout.write(dump(me, args.format))
+        return
+    line = f"'{me['user']}'"
+    if "assisted_by" in me:
+        line += f" assisted by '{me['assisted_by']}'"
+    if "session" in me:
+        line += f" (session {me['session']})"
+    print(line)
+
+
+def cmd_session(args: argparse.Namespace) -> None:
+    """A fresh session tag for an agent to pass as ``DIBS_SESSION`` for
+    the rest of its conversation. Random, so two agents of the same
+    person never pick the same one; nothing is stored, here or on the
+    server, until a claim carries it."""
+    import secrets
+
+    print(f"s-{secrets.token_hex(4)}")
+
+
 def cmd_logout(args: argparse.Namespace) -> None:
     url = _url(args)
     if token(url):
@@ -550,13 +589,13 @@ def cmd_admin_revoke(args: argparse.Namespace) -> None:
 
 # ---- 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()
+    from dibs._skill import skill_text
+
+    text = skill_text()
     if args.action == "print":
         sys.stdout.write(text)
         return
@@ -639,7 +678,8 @@ def build_parser() -> argparse.ArgumentParser:
         epilog=(
             "The client finds the server via --url or DIBS_URL. Claiming needs a login: "
             "register, have the admin approve you, then login. Agents set "
-            "DIBS_ASSISTED_BY; runners may pass a token in DIBS_TOKEN. Exit status: 0 done, "
+            "DIBS_ASSISTED_BY and DIBS_SESSION; runners may pass a token in DIBS_TOKEN. "
+            "Exit status: 0 done, "
             "1 claimed by someone else, 2 other errors."
         ),
     )
@@ -696,6 +736,12 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("-i", "--key", help="SSH public key file (default: the one you registered with)")
     p.set_defaults(func=cmd_login)
 
+    p = sub.add_parser("whoami", parents=[data], help="show who your claims are made as")
+    p.set_defaults(func=cmd_whoami)
+
+    p = sub.add_parser("session", help="print a fresh session tag for an agent")
+    p.set_defaults(func=cmd_session)
+
     p = sub.add_parser("logout", help="drop your token for this server")
     p.set_defaults(func=cmd_logout)
 

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

@@ -0,0 +1,86 @@
+---
+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.
+
+## Once per conversation
+
+1. Check that your human has set up this workstation:
+
+   ```
+   dibs whoami
+   ```
+
+   It prints your human's name. If it fails, or `dibs` or `DIBS_URL` is
+   missing, stop and tell your human to read `$DIBS_URL/agents`, or the
+   dibs README. Never run `dibs register` or `dibs login` yourself: you
+   claim with your human's login.
+
+1. Get a session tag for this conversation, once, with `dibs session`.
+   It prints a random tag such as `s-3f2a9c41`. Do not make one up: two
+   agents could pick the same. Pass it, and who you are, on every dibs
+   command, inline, so every call agrees:
+
+   ```
+   DIBS_ASSISTED_BY="Claude Code:<your model id>" DIBS_SESSION=<tag> dibs ...
+   ```
+
+   Your claims then say which agent made them, and another agent of the
+   same person cannot take or release them without `--force`; nor can you
+   theirs.
+
+## Before you touch a machine
+
+1. Look: `dibs list --json`, and read the JSON rather than the text.
+
+1. Claim it, saying what for:
+
+   ```
+   DIBS_ASSISTED_BY=... DIBS_SESSION=... dibs claim <machine> --for "<what you are doing>"
+   ```
+
+1. Exit status 1 means someone else holds it, maybe another agent of
+   your human's. 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=... DIBS_SESSION=... dibs release --mine
+```
+
+This releases only this session's claims: not your human's, and not
+other agents'.
+
+## Never
+
+- Use a machine claimed by someone else, or one you have not claimed.
+- Pass `--force`, or release a claim this session did not make.
+- Register or log in to dibs yourself.
+- Power-cycle, reflash, reboot or use the BMC of a machine when you hold
+  only a part of it.

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

@@ -67,11 +67,15 @@ def test_conflict_unknown_and_invalid(client: TestClient, tokens) -> None:
     assert _claim(client, tokens, "ryzen-01", purpose="").status_code == 422
 
 
-def test_release_mine_is_scoped_to_assisted_by(client: TestClient, tokens) -> None:
+def test_release_mine_is_scoped_to_the_session(client: TestClient, tokens) -> None:
     _claim(client, tokens, "epyc-02")
-    r = _claim(client, tokens, "warp", assisted_by=AGENT)
-    assert r.json()["things"][0]["sentence"].startswith(f"'alice' assisted by '{AGENT}'")
-    released = _release(client, tokens, mine=True, assisted_by=AGENT).json()["things"]
+    r = _claim(client, tokens, "warp", assisted_by=AGENT, session="s1")
+    assert r.json()["things"][0]["sentence"].startswith(
+        f"'alice' assisted by '{AGENT}' (session s1)"
+    )
+    assert r.json()["things"][0]["claim"]["session"] == "s1"
+    _claim(client, tokens, "ryzen-01", assisted_by=AGENT, session="s2")
+    released = _release(client, tokens, mine=True, assisted_by=AGENT, session="s1").json()["things"]
     assert [t["name"] for t in released] == ["warp"]
     assert client.get("/things/epyc-02").json()["claim"]["holder"] == "alice"
     assert _release(client, tokens).status_code == 422
@@ -176,3 +180,21 @@ def test_parts_over_the_api(client: TestClient, tokens, tmp_path: Path) -> None:
     # 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 "echo 'export DIBS_URL=http://testserver' >> ~/.bashrc" in page
+    assert "DIBS_URL=http://testserver dibs whoami" in page
+    assert "If you are a person" in page and "If you are an agent" in page
+    assert "Agents never\nregister" 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.2.0 → pixie_lab_dibs-0.3.0}/tests/test_cli.py

@@ -285,3 +285,55 @@ def test_skill_ships_in_the_wheel(tmp_path: Path) -> None:
     )
     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)
+
+
+def test_whoami_shows_the_actor(run: Run, monkeypatch: pytest.MonkeyPatch, capsys) -> None:
+    assert run("whoami") == 0
+    assert capsys.readouterr().out == "'alice'\n"
+    monkeypatch.setenv("DIBS_ASSISTED_BY", "Claude Code:claude-opus-5-5")
+    monkeypatch.setenv("DIBS_SESSION", "s1")
+    assert run("whoami") == 0
+    assert (
+        capsys.readouterr().out
+        == "'alice' assisted by 'Claude Code:claude-opus-5-5' (session s1)\n"
+    )
+    assert run("whoami", "--json") == 0
+    assert json.loads(capsys.readouterr().out) == {
+        "user": "alice",
+        "assisted_by": "Claude Code:claude-opus-5-5",
+        "session": "s1",
+    }
+    # With nobody logged in it fails, which is how an agent finds out.
+    assert run("whoami", who=None) == cli.EXIT_ERROR
+    assert "agents use their person's login" in capsys.readouterr().err
+
+
+def test_claims_carry_the_session(run: Run, monkeypatch: pytest.MonkeyPatch, capsys) -> None:
+    monkeypatch.setenv("DIBS_ASSISTED_BY", "Claude Code:claude-opus-5-5")
+    monkeypatch.setenv("DIBS_SESSION", "s1")
+    assert run("claim", "warp", "--for", "x") == 0
+    assert "(session s1) has claimed 'warp'" in capsys.readouterr().out
+    monkeypatch.setenv("DIBS_SESSION", "s2")
+    assert run("claim", "warp", "--for", "y") == cli.EXIT_REFUSED
+    assert run("release", "--mine") == 0
+    assert capsys.readouterr().out.endswith("nothing to release\n")
+
+
+def test_session_tags_are_fresh_and_valid(capsys) -> None:
+    from dibs._store import validate_session
+
+    tags = set()
+    for _ in range(20):
+        assert cli.main(["session"]) == 0
+        tag = capsys.readouterr().out.strip()
+        assert validate_session(tag) == tag
+        tags.add(tag)
+    assert len(tags) == 20

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

@@ -29,8 +29,12 @@ def test_sentence_free_claimed_and_assisted(store: Store) -> None:
     assert sentence("node-01", c, T0) == (
         "'alice' has claimed 'node-01' for 'xnvme' expires in: 'never'"
     )
-    [(_, c)] = store.claim(["node-01"], holder="alice", purpose="x", assisted_by=AGENT, now=T0)
-    assert sentence("node-01", c, T0).startswith(f"'alice' assisted by '{AGENT}' has claimed")
+    [(_, c)] = store.claim(
+        ["node-02"], holder="alice", purpose="x", assisted_by=AGENT, session="s1", now=T0
+    )
+    assert sentence("node-02", c, T0).startswith(
+        f"'alice' assisted by '{AGENT}' (session s1) has claimed 'node-02'"
+    )
 
 
 @pytest.mark.parametrize(
@@ -66,11 +70,61 @@ def test_claim_is_all_or_nothing(store: Store) -> None:
     assert store.get_claim("a") is None
 
 
-def test_an_agent_and_its_human_do_not_block_each_other(store: Store) -> None:
+def test_two_agent_sessions_of_one_user_conflict(store: Store) -> None:
+    store.claim(["a"], holder="alice", purpose="x", assisted_by=AGENT, session="s1", now=T0)
+    with pytest.raises(ClaimConflict) as exc:
+        store.claim(["a"], holder="alice", purpose="y", assisted_by=AGENT, session="s2", now=T0)
+    assert "(session s1)" in exc.value.sentences[0]
+    with pytest.raises(ClaimConflict):
+        store.release(["a"], holder="alice", assisted_by=AGENT, session="s2", now=T0)
+    # The same session claiming again just updates its claim.
+    store.claim(["a"], holder="alice", purpose="z", assisted_by=AGENT, session="s1", now=T0)
+    assert store.get_claim("a").purpose == "z"  # type: ignore[union-attr]
+
+
+def test_an_agent_cannot_take_or_release_its_humans_claim(store: Store) -> None:
     store.claim(["a"], holder="alice", purpose="x", now=T0)
-    store.claim(["a"], holder="alice", purpose="y", assisted_by=AGENT, now=T0)
-    store.release(["a"], holder="alice", now=T0)
-    assert store.get_claim("a") is None
+    with pytest.raises(ClaimConflict):
+        store.claim(["a"], holder="alice", purpose="y", assisted_by=AGENT, session="s1", now=T0)
+    with pytest.raises(ClaimConflict):
+        store.release(["a"], holder="alice", assisted_by=AGENT, session="s1", now=T0)
+
+
+def test_the_human_may_release_their_agents_claims(store: Store) -> None:
+    store.claim(["a"], holder="alice", purpose="x", assisted_by=AGENT, session="s1", now=T0)
+    # Claiming over it still needs force, so nothing is overwritten unnoticed...
+    with pytest.raises(ClaimConflict):
+        store.claim(["a"], holder="alice", purpose="y", now=T0)
+    # ...but cleaning up after one's own agent does not.
+    assert [c.thing for c in store.release(["a"], holder="alice", now=T0)] == ["a"]
+
+
+def test_another_users_human_may_not_release_my_agents_claim(store: Store) -> None:
+    store.claim(["a"], holder="alice", purpose="x", assisted_by=AGENT, session="s1", now=T0)
+    with pytest.raises(ClaimConflict):
+        store.release(["a"], holder="bob", now=T0)
+
+
+def test_old_database_gains_sessions(tmp_path: Path) -> None:
+    import sqlite3
+
+    db = tmp_path / "old.db"
+    conn = sqlite3.connect(str(db))
+    conn.executescript(
+        "CREATE TABLE claims (thing TEXT PRIMARY KEY, holder TEXT NOT NULL, "
+        "assisted_by TEXT NOT NULL DEFAULT '', purpose TEXT NOT NULL, claimed_at TEXT NOT NULL, "
+        "expires_at TEXT NOT NULL DEFAULT '');"
+        "INSERT INTO claims (thing, holder, purpose, claimed_at) VALUES ('a', 'alice', 'x', 'y');"
+    )
+    conn.commit()
+    conn.close()
+    assert Store(db).get_claim("a").session == ""  # type: ignore[union-attr]
+
+
+@pytest.mark.parametrize("raw", ["-x", "a b", "x" * 33, "a/b"])
+def test_bad_sessions_are_refused(store: Store, raw: str) -> None:
+    with pytest.raises(ValueError):
+        store.claim(["a"], holder="alice", purpose="x", session=raw, now=T0)
 
 
 def test_force_takeover_reports_previous_holder(store: Store) -> None:
@@ -99,12 +153,13 @@ def test_release_rules(store: Store) -> None:
     assert store.get_claim("b") is None
 
 
-def test_claimed_by_is_scoped_to_assisted_by(store: Store) -> None:
+def test_claimed_by_is_scoped_to_the_actor(store: Store) -> None:
     store.claim(["a"], holder="alice", purpose="x", now=T0)
-    store.claim(["b"], holder="alice", purpose="y", assisted_by=AGENT, now=T0)
+    store.claim(["b"], holder="alice", purpose="y", assisted_by=AGENT, session="s1", now=T0)
+    store.claim(["d"], holder="alice", purpose="y", assisted_by=AGENT, session="s2", now=T0)
     store.claim(["c"], holder="alice", purpose="z", expires_in=60, now=T0 - timedelta(hours=1))
     assert [c.thing for c in store.claimed_by("alice", now=T0)] == ["a"]
-    assert [c.thing for c in store.claimed_by("alice", AGENT, now=T0)] == ["b"]
+    assert [c.thing for c in store.claimed_by("alice", AGENT, "s1", now=T0)] == ["b"]
 
 
 @pytest.mark.parametrize(

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

@@ -1,65 +0,0 @@
----
-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.