collab-runtime 0.4.2__tar.gz → 0.5.0__tar.gz

{collab_runtime-0.4.2/collab_runtime.egg-info → collab_runtime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.4.2
+Version: 0.5.0
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/README.md

@@ -74,15 +74,18 @@ The setup script automatically:
 
 After setup, verify your `.env` at the project root has these values:
 
-| Variable                    | Description                                                      |
-| --------------------------- | ---------------------------------------------------------------- |
-| `SUPABASE_URL`              | Your Supabase project URL (from Project Settings → API)          |
-| `SUPABASE_ANON_KEY`         | Anonymous/public key (from Project Settings → API)               |
-| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)      |
-| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only)  |
-| `COLLAB_AGENT_ID`           | Optional stable id for an AI agent session (multi-agent locking) |
-| `COLLAB_AGENT_LABEL`        | Optional display label (e.g. `refactor-auth`)                    |
-| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset       |
+| Variable                    | Description                                                         |
+| --------------------------- | ------------------------------------------------------------------- |
+| `SUPABASE_URL`              | Your Supabase project URL (from Project Settings → API)             |
+| `SUPABASE_ANON_KEY`         | Anonymous/public key (from Project Settings → API)                  |
+| `SUPABASE_SERVICE_ROLE_KEY` | Service role key (**required** for dashboard force-release)         |
+| `LOCK_STRICT`               | If `1`, git hooks block on lock errors. Default `0` (warn only)     |
+| `COLLAB_AGENT_ID`           | Optional stable id for an AI agent session (multi-agent locking)    |
+| `COLLAB_AGENT_LABEL`        | Optional task label shown on the dashboard (e.g. `refactor-auth`)   |
+| `COLLAB_AGENT_KIND`         | Optional AI runtime for the dashboard icon (auto-detected)          |
+| `COLLAB_AGENT_MODE`         | Set to `1` to auto-generate/persist an agent id when unset          |
+| `COLLAB_AGENT_HOOKS`        | Set to `1` to enable the IDE edit hook that auto-claims agent edits |
+| `COLLAB_WATCHER_AGENT_ID`   | Opt in to a dedicated agent watcher (default: watcher = human)      |
 
 > **Important:** `SUPABASE_SERVICE_ROLE_KEY` is needed for the dashboard's Force Release button. Without it, only your own locks can be released.
 
@@ -102,9 +105,28 @@ set COLLAB_AGENT_ID=agent-fix-tests
 collab acquire src/auth.py   # conflict — locked by agent-refactor-auth
 ```
 
-For existing Supabase projects, re-run the `acquire_lock` function and add the `agent_id` /
-`agent_label` columns from the updated [supabase/schema.sql](supabase/schema.sql) (fresh installs
-already include them).
+For existing Supabase projects, re-run [supabase/schema.sql](supabase/schema.sql) to add the
+`agent_id` / `agent_label` / `origin` / `agent_kind` columns and the updated `acquire_lock` function
+(the script is idempotent; fresh installs already include them).
+
+#### Strict user-vs-agent attribution
+
+The dashboard distinguishes **human** edits from **AI agent** edits and shows _what the agent is
+working on_ — not a cryptic id. Attribution is decided by an explicit signal:
+
+- The background watcher locks bulk git changes as the **human** (`User` chip), even inside an AI
+  IDE. So normal work is never mislabelled as an agent.
+- An AI agent claims the files it edits, producing an **"AI Agent"** badge (runtime icon + task).
+  Make this automatic by wiring your IDE's edit hook to `collab claim` — see
+  [scripts/agent-hooks/](scripts/agent-hooks/README.md). It is **runtime-agnostic** (Cursor, Claude
+  Code, Copilot, Gemini, ...). Enable with `COLLAB_AGENT_HOOKS=1` and optionally
+  `COLLAB_AGENT_LABEL="<task>"`.
+
+Agents can also claim explicitly:
+
+```bash
+collab claim src/auth.py --label "refactor-auth" --reason "Refactor auth"
+```
 
 ### 4. Verify Setup
 

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/agent_identity.py

@@ -58,13 +58,19 @@ def detect_agent_runtime_label() -> Optional[str]:
 
 
 def is_agent_mode_requested() -> bool:
-    """Return True when agent identity should be active for this process."""
+    """Return True when agent identity should be active for this process.
+
+    STRICT ATTRIBUTION: the mere *presence* of an AI runtime (e.g. a process
+    spawned from a Cursor/Claude terminal that exports ``CURSOR_TRACE_ID``) does
+    NOT by itself attribute locks to an agent. Doing so caused every background
+    auto-lock to be mislabelled as the runtime. Agent attribution now requires an
+    *explicit* signal: ``COLLAB_AGENT_ID`` or ``COLLAB_AGENT_MODE``. The detected
+    runtime is still used for friendly display only (see :func:`resolve_agent_kind`).
+    """
     if _read_clean_env("COLLAB_AGENT_ID"):
         return True
     if _is_truthy_env("COLLAB_AGENT_MODE"):
         return True
-    if detect_agent_runtime_label():
-        return True
     return False
 
 
@@ -152,12 +158,17 @@ def resolve_agent_label(
     explicit_label: Optional[str] = None,
     runtime_label: Optional[str] = None,
 ) -> Optional[str]:
-    """Resolve optional human-readable agent label."""
+    """Resolve the human-readable *task* label (the "why / what for").
+
+    This intentionally does NOT fall back to the runtime name (e.g. ``cursor``): the
+    label describes the task an agent is working on (``fix-ci-dashboard``), while the
+    runtime family is tracked separately as ``agent_kind`` for display. When no task
+    label is supplied the dashboard shows a generic "AI Agent".
+    """
     for candidate in (
         explicit_label,
         _read_clean_env("COLLAB_AGENT_LABEL"),
         runtime_label,
-        detect_agent_runtime_label(),
     ):
         if candidate:
             val = candidate.strip()
@@ -166,6 +177,40 @@ def resolve_agent_label(
     return None
 
 
+def resolve_agent_kind(
+    *,
+    explicit_kind: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve the AI runtime family for friendly display (icon/name).
+
+    Precedence: explicit value → ``COLLAB_AGENT_KIND`` → detected runtime marker.
+    When an agent identity exists but the runtime is unknown, falls back to the
+    generic ``"other"`` so the dashboard can still render an AI badge. Returns
+    ``None`` for human (no agent) locks.
+    """
+    for candidate in (
+        explicit_kind,
+        _read_clean_env("COLLAB_AGENT_KIND"),
+        detect_agent_runtime_label(),
+    ):
+        if candidate:
+            val = candidate.strip().lower()
+            if val:
+                return val[:64]
+    if agent_id:
+        return "other"
+    return None
+
+
+def resolve_origin(agent_id: Optional[str]) -> str:
+    """Return the authoritative attribution origin for a lock.
+
+    ``'agent'`` when a unique agent identity is present, otherwise ``'human'``.
+    """
+    return "agent" if agent_id else "human"
+
+
 def agent_ids_match(
     lock_agent_id: Optional[str],
     client_agent_id: Optional[str],
@@ -282,6 +327,7 @@ def identity_summary(
     developer_id: str,
     agent_id: Optional[str],
     agent_label: Optional[str],
+    agent_kind: Optional[str] = None,
 ) -> dict[str, Optional[str]]:
     """Return a dict suitable for ``collab whoami`` JSON output."""
     mode = "agent" if agent_id else "human"
@@ -289,5 +335,6 @@ def identity_summary(
         "developer_id": developer_id,
         "agent_id": agent_id,
         "agent_label": agent_label,
+        "agent_kind": agent_kind,
         "mode": mode,
     }

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/dashboard/index.html

@@ -324,6 +324,55 @@
             color: #4338ca;
         }
 
+        /* Human vs AI actor attribution badges */
+        .actor-chip {
+            display: inline-flex;
+            align-items: center;
+            gap: 0.3rem;
+            margin-left: 0.4rem;
+            padding: 0.12rem 0.5rem;
+            border-radius: 999px;
+            font-size: 0.72rem;
+            font-weight: 600;
+            white-space: nowrap;
+            vertical-align: middle;
+        }
+
+        .user-chip {
+            background: #f1f5f9;
+            color: #475569;
+            border: 1px solid var(--border-color);
+        }
+
+        .agent-badge {
+            background: linear-gradient(135deg, #ede9fe 0%, #e0e7ff 100%);
+            color: #5b21b6;
+            border: 1px solid #ddd6fe;
+        }
+
+        .agent-badge-owner {
+            background: linear-gradient(135deg, #ddd6fe 0%, #c7d2fe 100%);
+            color: #4c1d95;
+            border-color: #c4b5fd;
+        }
+
+        .agent-badge .agent-badge-kind {
+            font-weight: 700;
+            text-transform: capitalize;
+        }
+
+        .agent-badge .agent-badge-task {
+            font-weight: 500;
+            opacity: 0.85;
+            max-width: 16rem;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }
+
+        .agent-badge .agent-badge-sep {
+            opacity: 0.5;
+        }
+
         code {
             color: #1d4ed8;
             background: #f8fafc;
@@ -759,20 +808,98 @@ SUPABASE_ANON_KEY=your_anon_key</pre>
             return !!(SUPABASE_USER && lock.developer_id === SUPABASE_USER);
         }
 
+        function escapeHtml(value) {
+            return String(value == null ? "" : value)
+                .replace(/&/g, "&amp;")
+                .replace(/</g , "&lt;") .replace( />/g, "&gt;")
+                .replace(/"/g, "&quot;")
+                .replace(/'/g, "&#39;");
+        }
+
+        function isAgentLock(lock) {
+            if (lock.origin === "agent") {
+                return true;
+            }
+            // Backward compatibility for rows created before `origin` existed.
+            return !!lock.agent_id && lock.origin !== "human";
+        }
+
+        function agentKindIcon(kind) {
+            switch (String(kind || "").toLowerCase()) {
+                case "cursor":
+                    return '<i class="fas fa-i-cursor"></i>';
+                case "copilot":
+                    return '<i class="fab fa-github"></i>';
+                case "claude-code":
+                case "claude":
+                case "composer":
+                case "other":
+                default:
+                    return '<i class="fas fa-robot"></i>';
+            }
+        }
+
+        function prettifyKind(kind) {
+            const k = String(kind || "").trim();
+            if (!k || k === "other") {
+                return "";
+            }
+            return k
+                .split(/[-_]/)
+                .map((p) => (p ? p.charAt(0).toUpperCase() + p.slice(1) : p))
+                .join(" ");
+        }
+
         function formatDeveloperCell(lock) {
             const dev = lock.developer_id || "?";
-            const agentText = lock.agent_label || lock.agent_id;
-            const chip = agentText
-                ? '<span class="agent-chip' + (lockOwnedByMe(lock) ? " agent-chip-owner" : "") + '">' +
-                  agentText +
-                  "</span>"
-                : '<span class="agent-chip">user</span>';
-            return (
+            const devTag =
                 '<span class="dev-tag ' + (lockOwnedByMe(lock) ? "dev-tag-owner" : "") + '">' +
-                dev +
-                "</span>" +
-                chip
-            );
+                escapeHtml(dev) +
+                "</span>";
+
+            if (!isAgentLock(lock)) {
+                const userChip =
+                    '<span class="actor-chip user-chip" title="Edited by a human developer">' +
+                    '<i class="fas fa-user"></i>User</span>';
+                return devTag + userChip;
+            }
+
+            // AI agent lock: show clearly that it was an AI agent and what for.
+            // The raw agent_id is intentionally never displayed in the cell — it
+            // appears only in the hover tooltip for debugging.
+            const kind = lock.agent_kind || "";
+            const kindName = prettifyKind(kind);
+            const task = String(lock.agent_label || "").trim();
+
+            const tip = ["Edited by an AI agent"];
+            if (kindName) tip.push("Runtime: " + kindName);
+            if (task) tip.push("Task: " + task);
+            if (lock.agent_id) tip.push("Agent id: " + lock.agent_id);
+            if (lock.reason) tip.push("Reason: " + lock.reason);
+
+            let inner =
+                agentKindIcon(kind) + '<span class="agent-badge-text">AI Agent</span>';
+            if (kindName) {
+                inner +=
+                    '<span class="agent-badge-sep">·</span>' +
+                    '<span class="agent-badge-kind">' +
+                    escapeHtml(kindName) +
+                    "</span>";
+            }
+            if (task) {
+                inner +=
+                    '<span class="agent-badge-sep">·</span>' +
+                    '<span class="agent-badge-task">' +
+                    escapeHtml(task) +
+                    "</span>";
+            }
+
+            const badge =
+                '<span class="actor-chip agent-badge' + (lockOwnedByMe(lock) ? " agent-badge-owner" : "") + '" title="' + escapeHtml(tip.join("\n")) + '">' +
+                inner +
+                "</span>";
+
+            return devTag + badge;
         }
 
         function updateTimestamp() {

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/dashboard_server.py

@@ -161,6 +161,7 @@ def load_runtime_supabase_config(project_root: str) -> dict[str, Any]:
     state_dir = state_override or os.path.join(project_root, ".collab")
     agent_id = agent_identity.resolve_agent_id(state_dir)
     agent_label = agent_identity.resolve_agent_label()
+    agent_kind = agent_identity.resolve_agent_kind(agent_id=agent_id)
     project_name = resolve_project_display_name(project_root, file_vals)
     return {
         "url": url,
@@ -169,6 +170,7 @@ def load_runtime_supabase_config(project_root: str) -> dict[str, Any]:
         "user": user,
         "agentId": agent_id,
         "agentLabel": agent_label,
+        "agentKind": agent_kind,
         "projectName": project_name,
     }
 

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/live_locks_watcher.py

@@ -239,6 +239,7 @@ PID_FILE = agent_identity.resolve_daemon_pid_path(_COLLAB_ROOT, None)
 DEVELOPER_ID = None
 AGENT_ID: Optional[str] = None
 AGENT_LABEL: Optional[str] = None
+AGENT_KIND: Optional[str] = None
 
 # Ephemeral developer prefixes enforced in code (not via env) to avoid
 # accidental disabling of lock persistence. These accounts (e.g. CI/test)
@@ -362,6 +363,8 @@ def _acquire_rpc_payload(
         "p_is_ephemeral": _is_ephemeral_dev(DEVELOPER_ID or ""),
         "p_agent_id": AGENT_ID,
         "p_agent_label": AGENT_LABEL,
+        "p_origin": agent_identity.resolve_origin(AGENT_ID),
+        "p_agent_kind": AGENT_KIND,
     }
 
 
@@ -749,6 +752,88 @@ def _process_releases(client, released: set[str]) -> None:
                 logger.exception("Failed to release lock for %s", fp)
 
 
+def _resolve_watcher_identity(
+    agent_id: Optional[str],
+    agent_label: Optional[str],
+    agent_kind: Optional[str],
+) -> tuple[Optional[str], Optional[str], Optional[str]]:
+    """Apply strict attribution to the watcher's resolved identity.
+
+    The background watcher attributes bulk auto-locks to the human developer
+    unless a dedicated agent watcher explicitly opts in via
+    ``COLLAB_WATCHER_AGENT_ID``. When opting out (the default) the agent identity
+    is dropped so every auto-lock is stamped ``origin=human``.
+    """
+    if os.getenv("COLLAB_WATCHER_AGENT_ID", "").strip():
+        return agent_id, agent_label, agent_kind
+    return None, None, None
+
+
+def _release_developer_scope(client, file_path: str) -> bool:
+    """Release a lock for *file_path* owned by this developer, ignoring agent id.
+
+    Used by the human watcher to clean up the developer's own AI-agent locks for files
+    that are no longer in progress. It never touches other developers' locks. Returns
+    True when a delete was issued.
+    """
+    if _is_ephemeral_dev(DEVELOPER_ID):
+        return False
+    try:
+        client.table("file_locks").delete().eq("file_path", file_path).eq(
+            "developer_id", DEVELOPER_ID
+        ).execute()
+    except Exception:
+        logger.exception("Developer-scoped release failed for %s", file_path)
+        return False
+    _local_owned_locks.discard(file_path)
+    return True
+
+
+def _fetch_dev_other_identity_locks(client) -> dict[str, dict]:
+    """Return ``{file_path: lock}`` for same-developer locks NOT owned by us.
+
+    When the watcher runs as the human (the default), these are the developer's
+    AI-agent locks. Strict attribution requires the watcher to never fight or
+    downgrade them: it skips acquiring such files and only cleans them up once the
+    file is no longer in progress (mirrors the ``collab watch`` reconcile).
+    """
+    try:
+        res = (
+            client.table("file_locks")
+            .select("*")
+            .eq("developer_id", DEVELOPER_ID)
+            .execute()
+        )
+        rows = getattr(res, "data", None) or []
+    except Exception as exc:
+        logger.debug("Failed to fetch developer locks for attribution: %s", exc)
+        return {}
+    out: dict[str, dict] = {}
+    for lock in rows:
+        fp = lock.get("file_path", "")
+        if fp and not _lock_owned_by_us(lock):
+            out[fp] = lock
+    return out
+
+
+def _filter_agent_held_new_files(client, new_files: set[str]) -> set[str]:
+    """Drop files already held by this developer's AI agent from the auto-lock set.
+
+    Prevents the human watcher from fighting (and logging false CONFLICTs for) the
+    developer's own agent locks. The ``acquire_lock`` RPC lets an agent take over a
+    human auto-lock, never the reverse, so the human watcher must simply step aside.
+    """
+    if not new_files:
+        return new_files
+    dev_agent_held = set(_fetch_dev_other_identity_locks(client))
+    skipped = new_files & dev_agent_held
+    if not skipped:
+        return new_files
+    for fp in sorted(skipped):
+        logger.debug("Skipping auto-lock for %s — held by this developer's agent", fp)
+    return new_files - dev_agent_held
+
+
 def _start_dashboard_server() -> str | None:
     """Start a local HTTP server serving the dashboard and return the URL.
 
@@ -970,8 +1055,24 @@ def _reconcile_on_startup(client) -> None:
             except Exception:
                 logger.exception("Failed to release stale lock for %s", fp)
 
-    # Step D: Acquire locks for dirty files that have no existing lock
+    # Step D: Acquire locks for dirty files that have no existing lock.
     unlocked_dirty = dirty_files - locked_paths
+
+    # Strict attribution: never fight this developer's AI-agent locks. Skip
+    # acquiring files already held by the same developer under another identity,
+    # and clean up such locks for files that are no longer in progress.
+    dev_other = _fetch_dev_other_identity_locks(client)
+    if dev_other:
+        unlocked_dirty -= set(dev_other)
+        for fp in sorted(set(dev_other) - dirty_files):
+            if _release_developer_scope(client, fp):
+                n_stale_released += 1
+                msg = (
+                    f"🔓 [STALE-RELEASED] {fp} — agent lock for clean file, "
+                    "releasing"
+                )
+                logger.info(_color(msg, Fore.MAGENTA) if _HAS_COLORAMA else msg)
+
     for fp in sorted(unlocked_dirty):
         if _should_ignore_path(fp):
             continue
@@ -1647,10 +1748,19 @@ def main() -> None:
         sys.exit(1)
 
     # Normalize developer ID aggressively to avoid token divergence between IDEs
-    global DEVELOPER_ID, AGENT_ID, AGENT_LABEL, SESSION_TOKEN, PID_FILE
+    global DEVELOPER_ID, AGENT_ID, AGENT_LABEL, AGENT_KIND, SESSION_TOKEN, PID_FILE
     DEVELOPER_ID = _get_developer_id().strip()
     AGENT_ID = agent_identity.resolve_agent_id(_COLLAB_ROOT)
     AGENT_LABEL = agent_identity.resolve_agent_label()
+    AGENT_KIND = agent_identity.resolve_agent_kind(agent_id=AGENT_ID)
+    # Strict attribution (parity with ``collab watch``): the background watcher —
+    # including this PyCharm entrypoint — attributes bulk git-status auto-locks to
+    # the HUMAN developer, never to an AI agent, even when launched from a terminal
+    # that exported COLLAB_AGENT_ID/COLLAB_AGENT_MODE. A dedicated agent watcher
+    # can opt in explicitly via COLLAB_WATCHER_AGENT_ID.
+    AGENT_ID, AGENT_LABEL, AGENT_KIND = _resolve_watcher_identity(
+        AGENT_ID, AGENT_LABEL, AGENT_KIND
+    )
     if not os.getenv("COLLAB_PID_FILE"):
         PID_FILE = agent_identity.resolve_daemon_pid_path(_COLLAB_ROOT, AGENT_ID)
 
@@ -1848,6 +1958,10 @@ def main() -> None:
 
                 # New files to lock
                 new_files = current_modified - last_modified
+                # Strict attribution: never auto-lock (as the human) a file that
+                # this developer's AI agent already holds — that would create
+                # false CONFLICT noise and fight the agent.
+                new_files = _filter_agent_held_new_files(client, new_files)
                 # Delegate acquire/release logic to helper functions to allow
                 # targeted unit tests to exercise error/fallback branches.
                 _process_new_files(client, branch, new_files)

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/lock_client.py

@@ -661,6 +661,8 @@ class LockClient:
         local_only: bool = False,
         agent_id: Optional[str] = None,
         agent_label: Optional[str] = None,
+        agent_kind: Optional[str] = None,
+        agent_mode: Optional[bool] = None,
     ) -> None:
         from typing import cast
 
@@ -669,15 +671,21 @@ class LockClient:
             developer_id or os.getenv("COLLAB_DEVELOPER_ID") or self._get_git_username()
         )
         state_dir = _get_state_dir()
-        runtime_label = agent_identity.detect_agent_runtime_label()
         self.agent_id = agent_identity.resolve_agent_id(
             state_dir,
             explicit_agent_id=agent_id,
+            agent_mode=agent_mode,
         )
         self.agent_label = agent_identity.resolve_agent_label(
             explicit_label=agent_label,
-            runtime_label=runtime_label,
         )
+        # Runtime family (cursor/claude-code/...) for friendly display only, and
+        # the authoritative attribution origin (human vs agent).
+        self.agent_kind = agent_identity.resolve_agent_kind(
+            explicit_kind=agent_kind,
+            agent_id=self.agent_id,
+        )
+        self.origin = agent_identity.resolve_origin(self.agent_id)
         _refresh_pid_file(self.agent_id)
         self._client: Optional[Any] = None
         self._branch_name: Optional[str] = None
@@ -1032,6 +1040,9 @@ class LockClient:
             "p_is_ephemeral": bool(getattr(self, "_is_ephemeral", False)),
             "p_agent_id": self.agent_id,
             "p_agent_label": self.agent_label,
+            "p_origin": getattr(self, "origin", None)
+            or agent_identity.resolve_origin(self.agent_id),
+            "p_agent_kind": getattr(self, "agent_kind", None),
         }
 
         client = self._require_client()
@@ -1380,6 +1391,35 @@ class LockClient:
                 count += 1
         return True, count, "Success"
 
+    def _release_developer_scope(self, file_path: str) -> bool:
+        """Release a lock owned by this *developer*, ignoring agent identity.
+
+        Used by the background watcher to clean up this developer's locks for files that
+        are no longer in progress (e.g. after a push), regardless of whether the lock
+        was created by the human auto-watcher or by an AI agent of the same developer.
+        It never touches other developers' locks.
+        """
+        if getattr(self, "_is_ephemeral", False):
+            return True
+        try:
+            client = self._require_client()
+            norm = self._normalize_file_path(file_path)
+            delete_query = (
+                client.table("file_locks")
+                .delete()
+                .eq("file_path", norm)
+                .eq("developer_id", self.developer_id)
+            )
+            res = _retry_on_network_error(lambda: delete_query.execute())
+        except Exception as exc:
+            logger.debug("Developer-scoped release failed for %s: %s", file_path, exc)
+            return False
+        status, data, error = self._parse_response(res)
+        if error:
+            logger.debug("Developer-scoped release error for %s: %s", file_path, error)
+            return False
+        return status in (200, 204) or data is not None
+
     def history(self, file_path: Optional[str] = None, limit: int = 20) -> List[Dict]:
         """Fetch lock history records.
 
@@ -3140,11 +3180,18 @@ class LockClient:
             my_locks = {lk["file_path"] for lk in active if self._lock_owned_by_me(lk)}
             # Build lock_map for token checking
             lock_map: dict[str, dict] = {}
+            # Locks held by THIS developer under a *different* identity. For the
+            # background watcher (which runs as the human) these are the same
+            # developer's AI-agent locks. We must never downgrade or fight them.
+            dev_other_locked: set = set()
             for lk in active:
+                fp = lk.get("file_path", "")
+                if not fp:
+                    continue
                 if self._lock_owned_by_me(lk):
-                    fp = lk.get("file_path", "")
-                    if fp:
-                        lock_map[fp] = lk
+                    lock_map[fp] = lk
+                elif lk.get("developer_id") == self.developer_id:
+                    dev_other_locked.add(fp)
         except LockServiceUnavailableError as e:
             logger.error("Error getting Supabase locks (service unavailable): %s", e)
             return git_modified
@@ -3152,11 +3199,26 @@ class LockClient:
             logger.error("Error getting Supabase locks: %s", e)
             return git_modified
 
-        # Calculate lock categories
+        # Calculate lock categories. ``missing`` excludes files already held by
+        # this developer under another (agent) identity so the human watcher does
+        # not generate conflicts trying to re-lock an agent's file. Agent claims
+        # take over human auto-locks atomically in the acquire_lock RPC instead.
         stale = my_locks - git_modified
-        missing = git_modified - my_locks
+        missing = git_modified - my_locks - dev_other_locked
         still_valid = my_locks & git_modified
 
+        # Clean up this developer's agent locks for work that is no longer in
+        # progress (e.g. after a push). Keeps the dashboard tidy without an agent
+        # having to explicitly release every file it touched.
+        dev_other_stale = dev_other_locked - git_modified
+        if dev_other_stale:
+            for fp in sorted(dev_other_stale):
+                logger.info(
+                    "🔓 [STALE-RELEASED] %s — agent lock for clean file, releasing",
+                    fp,
+                )
+                self._release_developer_scope(fp)
+
         # Count categories for summary
         current_token = self._get_session_token()
         resumed_locks = []

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/collab/main.py

@@ -93,7 +93,16 @@ def _run_cli() -> None:
         "--agent-label",
         dest="agent_label",
         default=None,
-        help="Human-readable agent label (or set COLLAB_AGENT_LABEL)",
+        help="Human-readable agent task label (or set COLLAB_AGENT_LABEL)",
+    )
+    common.add_argument(
+        "--agent-kind",
+        dest="agent_kind",
+        default=None,
+        help=(
+            "AI runtime family for display, e.g. cursor|claude-code|copilot "
+            "(or set COLLAB_AGENT_KIND; auto-detected when possible)"
+        ),
     )
 
     parser = ArgumentParser(
@@ -107,6 +116,22 @@ def _run_cli() -> None:
     acq.add_argument("file_path")
     acq.add_argument("--reason", help="Reason for the lock")
 
+    # claim — runtime-agnostic entrypoint for AI agents / IDE hooks. Acquires
+    # one or more files as the current AI agent (origin=agent), auto-generating a
+    # stable agent identity when none is supplied. Designed to be invoked from
+    # any IDE's edit hook (Cursor, Claude Code, Copilot, Gemini, ...).
+    clm = sub.add_parser(
+        "claim",
+        help="Claim file(s) as an AI agent edit (origin=agent)",
+    )
+    clm.add_argument("file_paths", nargs="+")
+    clm.add_argument("--reason", help="Reason for the claim")
+    clm.add_argument(
+        "--label",
+        dest="claim_label",
+        help="Task label describing what the agent is working on",
+    )
+
     # release
     rel = sub.add_parser("release", help="Release a lock on a file")
     rel.add_argument("file_path")
@@ -238,16 +263,44 @@ def _run_cli() -> None:
         sys.exit(1)
 
     local_only = args.command in ("daemon-status", "daemon-stop")
+
+    # ``claim`` always runs as an AI agent. Enable agent mode so a stable agent
+    # identity is generated/persisted even when the caller (IDE hook) did not set
+    # COLLAB_AGENT_ID, and prefer the claim-specific task label.
+    resolved_agent_label = getattr(args, "agent_label", None)
+    agent_mode: bool | None = None
+    if args.command == "claim":
+        agent_mode = True
+        resolved_agent_label = (
+            getattr(args, "claim_label", None) or resolved_agent_label
+        )
+
     client = LockClient(
         local_only=local_only,
         agent_id=getattr(args, "agent_id", None),
-        agent_label=getattr(args, "agent_label", None),
+        agent_label=resolved_agent_label,
+        agent_kind=getattr(args, "agent_kind", None),
+        agent_mode=agent_mode,
     )
 
+    # The background watcher must attribute bulk git-status auto-locks to the
+    # HUMAN developer, never to an AI agent — even when launched from a terminal
+    # that exported agent env vars. A dedicated agent watcher can opt in with
+    # COLLAB_WATCHER_AGENT_ID.
+    if args.command == "watch":
+        watcher_agent = os.getenv("COLLAB_WATCHER_AGENT_ID", "").strip()
+        if not watcher_agent:
+            client.agent_id = None
+            client.agent_label = None
+            client.agent_kind = None
+            client.origin = "human"
+            client._session_token = None
+
     # Keep CLI output clean by silencing noisy dependency logs (httpx, urllib3,
     # postgrest, supabase) for user-facing commands that can hit network APIs.
     quiet_commands = {
         "acquire",
+        "claim",
         "release",
         "active",
         "status",
@@ -274,6 +327,7 @@ def _run_cli() -> None:
                 client.developer_id,
                 client.agent_id,
                 client.agent_label,
+                getattr(client, "agent_kind", None),
             )
             print(f"Developer: {summary['developer_id']}")
             print(f"Mode:      {summary['mode']}")
@@ -281,6 +335,8 @@ def _run_cli() -> None:
                 print(f"Agent ID:    {summary['agent_id']}")
             if summary["agent_label"]:
                 print(f"Agent label: {summary['agent_label']}")
+            if summary["agent_kind"]:
+                print(f"Agent kind:  {summary['agent_kind']}")
             sys.exit(0)
 
         elif args.command == "acquire":
@@ -291,6 +347,16 @@ def _run_cli() -> None:
                 print(f"✗ Failed to lock {args.file_path}: {msg}")
             sys.exit(0 if ok else 1)
 
+        elif args.command == "claim":
+            reason = args.reason or "AI agent edit"
+            ok, failed, _msg = client.acquire_multiple(args.file_paths, reason=reason)
+            claimed = [fp for fp in args.file_paths if fp not in failed]
+            if claimed:
+                print(f"✓ Claimed {len(claimed)} file(s) as agent.")
+            if failed:
+                print(f"✗ Could not claim: {', '.join(failed)}")
+            sys.exit(0 if ok else 1)
+
         elif args.command == "release":
             ok, msg = client.release(args.file_path)
             print(f"{'✓' if ok else '✗'} {msg}")

{collab_runtime-0.4.2 → collab_runtime-0.5.0/collab_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: collab-runtime
-Version: 0.4.2
+Version: 0.5.0
 Summary: Collaborative file locking runtime
 Author-email: KirilMT <kiril.mt95@gmail.com>
 License-Expression: MIT

{collab_runtime-0.4.2 → collab_runtime-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "collab-runtime"
-version = "0.4.2"
+version = "0.5.0"
 description = "Collaborative file locking runtime"
 readme = "docs/pypi/README.md"
 license = "MIT"