code-context-control 2.65.0__tar.gz → 2.67.0__tar.gz

{code_context_control-2.65.0/code_context_control.egg-info → code_context_control-2.67.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.65.0
+Version: 2.67.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -186,7 +186,7 @@ Twelve tabs. The dashboard above shows token savings, indexed files, the live se
 
 ## The MCP tool suite
 
-C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
+C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 
 | Tool | What it does |
 |---|---|
@@ -201,6 +201,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_memory` | Fact store with categories, recall, graph queries, `index`→`fetch` two-step |
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
+| `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter |
@@ -211,7 +212,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |
 
-Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task`.
+Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task` / `c3_locks`.
 
 On Windows `c3_shell` uses Git Bash when available. Git Bash bundles no `jq`; use `python -m json.tool` for portable JSON formatting.
 
@@ -242,12 +243,61 @@ c3 access mask activate                         # purge pre-mask artifacts, buil
 - **Masked means read-only, always.** Cropped rows have no inverse, so an edit in transformed coordinates would corrupt the one file you protected.
 - **Four deterministic presets, no LLM in the read path:** `redact_secrets`, `redact_columns` (salted one-way pseudonyms — joins survive, no reverse dictionary), `sample_rows`, `signatures_only`.
 - **Rule changes are human-only** (UI tab or CLI) and ledger-logged. Agents have no mutation surface.
+- **Built-ins can be switched off when you need to** (v2.65.0). `**/.env*`, `**/.c3/**`, `**/.claude/settings*.json` and `**/.git/**` yield to `c3 access builtin disable <glob>`, which makes you retype the glob first. It takes **two keys** — a config entry *and* a keyring attestation — so an agent that manages to write `config.json` still cannot grant itself write access to your settings. The credential vault stays absolute.
 - **Honest coverage.** This guards *cooperative* agents against mistakes and prompt injection. It is not a sandbox — a raw shell outside C3's tools still sees the real bytes.
 
 → [Access Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/access-guard.md) · [Mask Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/mask-guard.md)
 
 ---
 
+## Agent Locks — several agents, one repo (v2.65.0)
+
+Guards answer *may the agent touch this?* Locks answer *is someone already touching it?*
+
+Two agents editing one file used to be silent data loss. `c3_edit` serialized
+same-file edits with an in-process lock, but every session runs its own `c3-mcp`
+server — so two sessions could interleave read → replace → write and lose an edit
+with no error on either side. Create mode was worse: both agents "succeeded" and
+one file won.
+
+Now there are two mechanisms, because they solve different problems:
+
+- **Torn writes** — a cross-process file lock, held across create, single-edit and
+  batch alike. No daemon, no configuration, nothing to switch on.
+- **Overlapping work** — a *lease*. `c3_edit` takes one on the file it edits,
+  carrying the intent from your edit summary. A second agent gets told who holds
+  it and why:
+
+```text
+[c3-lock:held] services/router.py is held by claude-code:a3f19c2b.
+  intent: "refactor retry backoff"
+  lease expires in 6m12s.
+```
+
+```bash
+c3 locks list                              # who holds what, across the project
+c3 locks force-release services/router.py  # break a stuck lease (human-only, audited)
+```
+
+- **TTL is the real release mechanism.** Agents forget to release, so nothing
+  assumes they will — a crashed agent can never wedge a repo.
+- **Acquisition is all-or-nothing** over a sorted path list, so two agents grabbing
+  the same pair in opposite order cannot deadlock.
+- **`force-release` bumps a fencing counter**, so a holder that comes back is stale
+  by construction rather than by hope. It lives in the CLI and the Hub, never in
+  the agent-facing tool.
+- **The Hub's Locks tab badges a project it cannot read as `UNREADABLE`**, not as
+  zero leases — "all clear" is a different claim from "we don't know".
+- **Honest coverage, again.** Leases gate C3's own tool surfaces. A raw `c3_shell`
+  redirect, a non-Claude agent, or a human in an editor is *not* covered, and the
+  UI says so on screen.
+
+Set `locks.enabled: false` in `.c3/config.json` to opt out.
+
+→ [Agent Locks](https://github.com/drknowhow/code-context-control/blob/main/docs/agent-locks.md)
+
+---
+
 ## Integrations
 
 | | What you get | Guide |

{code_context_control-2.65.0 → code_context_control-2.67.0}/README.md

@@ -123,7 +123,7 @@ Twelve tabs. The dashboard above shows token savings, indexed files, the live se
 
 ## The MCP tool suite
 
-C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
+C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 
 | Tool | What it does |
 |---|---|
@@ -138,6 +138,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_memory` | Fact store with categories, recall, graph queries, `index`→`fetch` two-step |
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
+| `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter |
@@ -148,7 +149,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |
 
-Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task`.
+Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task` / `c3_locks`.
 
 On Windows `c3_shell` uses Git Bash when available. Git Bash bundles no `jq`; use `python -m json.tool` for portable JSON formatting.
 
@@ -179,12 +180,61 @@ c3 access mask activate                         # purge pre-mask artifacts, buil
 - **Masked means read-only, always.** Cropped rows have no inverse, so an edit in transformed coordinates would corrupt the one file you protected.
 - **Four deterministic presets, no LLM in the read path:** `redact_secrets`, `redact_columns` (salted one-way pseudonyms — joins survive, no reverse dictionary), `sample_rows`, `signatures_only`.
 - **Rule changes are human-only** (UI tab or CLI) and ledger-logged. Agents have no mutation surface.
+- **Built-ins can be switched off when you need to** (v2.65.0). `**/.env*`, `**/.c3/**`, `**/.claude/settings*.json` and `**/.git/**` yield to `c3 access builtin disable <glob>`, which makes you retype the glob first. It takes **two keys** — a config entry *and* a keyring attestation — so an agent that manages to write `config.json` still cannot grant itself write access to your settings. The credential vault stays absolute.
 - **Honest coverage.** This guards *cooperative* agents against mistakes and prompt injection. It is not a sandbox — a raw shell outside C3's tools still sees the real bytes.
 
 → [Access Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/access-guard.md) · [Mask Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/mask-guard.md)
 
 ---
 
+## Agent Locks — several agents, one repo (v2.65.0)
+
+Guards answer *may the agent touch this?* Locks answer *is someone already touching it?*
+
+Two agents editing one file used to be silent data loss. `c3_edit` serialized
+same-file edits with an in-process lock, but every session runs its own `c3-mcp`
+server — so two sessions could interleave read → replace → write and lose an edit
+with no error on either side. Create mode was worse: both agents "succeeded" and
+one file won.
+
+Now there are two mechanisms, because they solve different problems:
+
+- **Torn writes** — a cross-process file lock, held across create, single-edit and
+  batch alike. No daemon, no configuration, nothing to switch on.
+- **Overlapping work** — a *lease*. `c3_edit` takes one on the file it edits,
+  carrying the intent from your edit summary. A second agent gets told who holds
+  it and why:
+
+```text
+[c3-lock:held] services/router.py is held by claude-code:a3f19c2b.
+  intent: "refactor retry backoff"
+  lease expires in 6m12s.
+```
+
+```bash
+c3 locks list                              # who holds what, across the project
+c3 locks force-release services/router.py  # break a stuck lease (human-only, audited)
+```
+
+- **TTL is the real release mechanism.** Agents forget to release, so nothing
+  assumes they will — a crashed agent can never wedge a repo.
+- **Acquisition is all-or-nothing** over a sorted path list, so two agents grabbing
+  the same pair in opposite order cannot deadlock.
+- **`force-release` bumps a fencing counter**, so a holder that comes back is stale
+  by construction rather than by hope. It lives in the CLI and the Hub, never in
+  the agent-facing tool.
+- **The Hub's Locks tab badges a project it cannot read as `UNREADABLE`**, not as
+  zero leases — "all clear" is a different claim from "we don't know".
+- **Honest coverage, again.** Leases gate C3's own tool surfaces. A raw `c3_shell`
+  redirect, a non-Claude agent, or a human in an editor is *not* covered, and the
+  UI says so on screen.
+
+Set `locks.enabled: false` in `.c3/config.json` to opt out.
+
+→ [Agent Locks](https://github.com/drknowhow/code-context-control/blob/main/docs/agent-locks.md)
+
+---
+
 ## Integrations
 
 | | What you get | Guide |

{code_context_control-2.65.0 → code_context_control-2.67.0}/cli/_hook_utils.py

@@ -96,12 +96,111 @@ def _empty_state(session_id: str = "") -> dict:
     return {"session_id": session_id or "", "last_c3_call": None, "unlocked_files": {}}
 
 
+#: os.replace retries for when Windows briefly holds a handle on the target —
+#: AV scanner, Search indexer, or a concurrent hook reading the same state.
+_REPLACE_ATTEMPTS = 4
+_REPLACE_BACKOFF_S = 0.02
+
+
 def _atomic_write_json(path: Path, data: dict) -> None:
-    """Write JSON atomically: temp file in the same directory + os.replace."""
+    """Write JSON durably: temp file in the same directory + os.replace.
+
+    Three failure modes this guards against, all observed in the wild
+    (10 orphaned .tmp<pid> files and a truncated enforcement_state.json on a
+    Windows box before v2.66):
+
+    1. **Torn write.** Without fsync, os.replace can publish a file whose
+       bytes are still in the OS cache. A crash or power loss then leaves a
+       zero-length or half-written JSON that every later read quarantines —
+       which silently drops all sticky unlocks and makes enforcement *more*
+       aggressive, not less.
+    2. **Orphaned temp files.** If os.replace raised, the temp file was
+       simply abandoned. They accumulate forever in .c3/ and are easy to
+       mistake for real state.
+    3. **Transient Windows sharing violations.** Another process holding a
+       read handle on the target makes os.replace raise PermissionError; a
+       single attempt turned that into a lost write.
+    """
+    import time
+
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_name(f"{path.name}.tmp{os.getpid()}")
-    tmp.write_text(json.dumps(data), encoding="utf-8")
-    os.replace(tmp, path)
+    try:
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(data, fh)
+            fh.flush()
+            os.fsync(fh.fileno())  # durability before publish (fixes #1)
+
+        last_exc = None
+        for attempt in range(_REPLACE_ATTEMPTS):
+            try:
+                os.replace(tmp, path)
+                return
+            except PermissionError as exc:  # fixes #3
+                last_exc = exc
+                if attempt < _REPLACE_ATTEMPTS - 1:
+                    time.sleep(_REPLACE_BACKOFF_S * (2 ** attempt))
+        if last_exc is not None:
+            raise last_exc
+    finally:
+        # fixes #2 — a successful replace already consumed tmp, so this only
+        # fires on the failure paths.
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except OSError:
+            pass
+
+
+def sweep_stale_temps(project_path: Path | None = None) -> int:
+    """Remove orphaned *.tmp<pid> files left by older C3 builds.
+
+    Only touches temp files whose owning PID is gone, so a concurrent hook
+    mid-write is never disturbed. Returns how many were removed; never raises.
+    """
+    removed = 0
+    try:
+        base = project_path if project_path is not None else Path.cwd()
+        c3_dir = base / ".c3"
+        if not c3_dir.is_dir():
+            return 0
+        for tmp in c3_dir.glob("*.tmp*"):
+            suffix = tmp.name.rsplit(".tmp", 1)[-1]
+            if not suffix.isdigit():
+                continue
+            if _pid_alive(int(suffix)):
+                continue
+            try:
+                tmp.unlink()
+                removed += 1
+            except OSError:
+                pass
+    except Exception:
+        pass
+    return removed
+
+
+def _pid_alive(pid: int) -> bool:
+    """Best-effort liveness check. On error assume ALIVE (don't delete)."""
+    if pid <= 0:
+        return False
+    try:
+        if os.name == "nt":
+            import ctypes
+            # PROCESS_QUERY_LIMITED_INFORMATION — works without elevation.
+            handle = ctypes.windll.kernel32.OpenProcess(0x1000, False, pid)
+            if not handle:
+                return False
+            ctypes.windll.kernel32.CloseHandle(handle)
+            return True
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists but not ours
+    except Exception:
+        return True  # unknown → conservative
 
 
 def _read_legacy_state(base: Path) -> dict:
@@ -163,6 +262,10 @@ def load_enforcement_state(project_path: Path | None = None, session_id: str = "
                 state_path.replace(state_path.with_name(state_path.name + ".corrupt"))
             except Exception:
                 pass
+            # Corruption is the one reliable signal that a previous write went
+            # wrong, so it is also the moment to clear any temp files that
+            # write orphaned (pre-v2.66 _atomic_write_json had no cleanup).
+            sweep_stale_temps(base)
             STATE_WARNINGS.append(
                 "[c3:hook-error] enforcement_state: corrupted "
                 f"{ENFORCEMENT_STATE_FILE} quarantined ({type(exc).__name__}); "