@veda-hq/kavach 0.3.0 → 0.6.0

package/README.md

@@ -3,11 +3,11 @@
 कवच, armour. Guards for coding agents: each tool call an agent makes is
 judged before it runs. Part of [Veda](https://github.com/veda-hq/veda).
 
-## v0.3: three guards and a rule-check engine
+## v0.5: three guards and a rule-check engine
 
 | Guard | Refuses | Entry point |
 | --- | --- | --- |
-| Worktree boundary | Any write outside the agent's own git worktree: a Bash command, an Edit or a Write. Read-only commands pass from any checkout. | `python3 python/kavach/worktree_guard.py` |
+| Worktree boundary | Any write outside the agent's own git worktree: a Bash command, an Edit or a Write; and, while a push runs, any write into it (below). Read-only commands pass from any checkout. | `python3 python/kavach/worktree_guard.py` |
 | Command guard | Git-hook bypasses (`--no-verify`, `core.hooksPath`…), history-destroying pushes, and the project's own command rules (settings below). | `python3 python/kavach/command_guard.py` |
 | Rule checks | The project's own checks, written in TypeScript, refusing or warning with the rule's reason. | `kavach-rule-checks` (`dist/rule-checks/cli.js`) |
 
@@ -60,6 +60,10 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   "worktree": {
     "trustedCommands": [
       { "script": "scripts/worktree.py", "pattern": "python3 scripts/worktree\\.py (?:status|retire --pr [1-9][0-9]*)" }
+    ],
+    "readOnlyCommands": [
+      { "pattern": "pnpm (?:health:check|(?:ls|list|why)(?: [A-Za-z0-9@][A-Za-z0-9@/._-]*)*(?: --depth [0-9]+)?)",
+        "env": { "AGENT_REMOTE": ["true"] }, "reason": "the script and pnpm's listing commands only read" }
     ]
   },
   "command": {
@@ -77,6 +81,14 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   pattern must match the whole command; trust only command lines of plain
   words (a whole line with any shell metacharacter is never trusted by its
   pattern alone).
+- `readOnlyCommands`: a command line you reviewed as only reading, though
+  the guard cannot prove it (a package runner's script, say). It runs with no
+  owned worktree, from a checkout's root only, and only while the hook's own
+  environment holds one of the listed values for every variable in `env`,
+  which is required. The pattern is matched as a trusted command's is. Keep
+  the list to commands that write nothing however they are called, and
+  name each option a pattern allows: a runner's own options after the
+  subcommand (`pnpm ls -C elsewhere`, `--pnpmfile`) move or widen what runs.
 - `protectedVariables`: environment variables a command may not assign, declare or
   export.
 - `pairedChanges`: a commit that may record a path ending in `changes` must
@@ -86,6 +98,33 @@ that cannot be read, is not JSON, or has an unknown key refuses every call.
   Keep a CI check behind it: the guard reads one command line, not the files
   other programs change.
 
+## While a push runs
+
+A push's checks read the worktree it was started from, and an edit made
+while they run either fails the push at its end or leaves it checking what
+was not pushed. So while a push runs, the worktree boundary refuses writes
+into that worktree: any Bash command it cannot prove read-only, run there
+(a trusted command included), and any Edit, Write or NotebookEdit of a path
+git does not ignore. Reads still run, and the file tools can still write
+files git ignores (drafts, scratch); a Bash command that writes one is still
+refused. The refusal names the push's pid and start. Commands that only reach
+the network, such as `gh pr comment`, wait too: the guard cannot tell what an
+unproven command writes.
+
+It knows a push is running from the marker the project's pre-push hook
+writes. Write it when a real push starts and clear it on every exit:
+
+```sh
+kavach-rule-checks push-marker write "$(git rev-parse --absolute-git-dir)" "$$"
+trap 'kavach-rule-checks push-marker clear "$(git rev-parse --absolute-git-dir)" "$$"' EXIT
+```
+
+Each push gets its own marker, `kavach-push-in-progress.<pid>.json` in the
+worktree's own git folder, naming its pid and start. A marker whose pid has
+ended or now belongs to a later process blocks nothing, so a killed push
+leaves no lock behind, and a push in another worktree never blocks this one.
+Without the marker, nothing here changes.
+
 ## Refusal log
 
 Each refusal of the two Python guards appends a row (time, guard, tool, first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veda-hq/kavach",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Guards for coding agents: refuses writes outside the agent's worktree, git-hook bypasses and history-destroying pushes, and runs a project's own rule checks on each tool call. Read-only commands pass.",
   "keywords": [
     "coding agents",

package/python/kavach/boundary.py

@@ -16,7 +16,7 @@ import stat
 import subprocess
 import sys
 from pathlib import Path
-from typing import Protocol, Sequence
+from typing import Mapping, Protocol, Sequence
 
 
 # Admission to this set means one thing: NO invocation of the command mutates
@@ -3246,22 +3246,10 @@ def trusted_request(
 
     if not trusted:
         return False
-    # A loose pattern (`.*`) must not trust a whole line that hides another
-    # command: the whole-line match holds only for plain words.
-    plain = TRUSTED_LINE_UNSAFE.search(command) is None
-    opening: tuple[str, list[list[str]]] | None = None
-    rest_is_inert: bool | None = None
+    line = ReviewedLine(command)
     for entry in trusted:
-        if not (plain and entry.pattern.fullmatch(command)):
-            if opening is None:
-                opening = trusted_opening(command)
-            first, rest = opening
-            if not first or not entry.pattern.fullmatch(first):
-                continue
-            if rest_is_inert is None:
-                rest_is_inert = all(segment_is_read_only(words) for words in rest)
-            if not rest_is_inert:
-                continue
+        if not line.matches(entry.pattern):
+            continue
         resolved = root.resolve()
         script = resolved / entry.script
         if cwd.resolve() == resolved and script.is_file() and script.resolve() == script:
@@ -3269,6 +3257,78 @@ def trusted_request(
     return False
 
 
+class ReviewedLine:
+    """One command line, as a consumer's reviewed pattern is matched to it.
+
+    A whole line of plain words matches when the pattern matches all of it. A
+    loose pattern (`.*`) must not admit a line that hides another command, so
+    any other line matches only by its first segment, as plain words, followed
+    by nothing but read-only segments (reviewed redirections included). The
+    parse is done once, for the first pattern that needs it.
+    """
+
+    def __init__(self, command: str) -> None:
+        self.command = command
+        self.plain = TRUSTED_LINE_UNSAFE.search(command) is None
+        self.opening: tuple[str, list[list[str]]] | None = None
+        self.rest_is_inert: bool | None = None
+
+    def matches(self, pattern: re.Pattern[str]) -> bool:
+        if self.plain and pattern.fullmatch(self.command):
+            return True
+        if self.opening is None:
+            self.opening = trusted_opening(self.command)
+        first, rest = self.opening
+        if not first or not pattern.fullmatch(first):
+            return False
+        if self.rest_is_inert is None:
+            self.rest_is_inert = all(segment_is_read_only(words) for words in rest)
+        return self.rest_is_inert
+
+
+class ReadOnlyEntry(Protocol):
+    """One reviewed read-only command, as `config.ReadOnlyCommand` carries it:
+    `pattern` must match the whole command line, and `env` pairs each
+    variable with the values the hook's environment may hold for it."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+
+
+def read_only_request(
+    command: str,
+    cwd: Path,
+    root: Path,
+    entries: Sequence[ReadOnlyEntry],
+    environ: Mapping[str, str],
+) -> bool:
+    """Recognize a command line the consumer reviewed as only reading.
+
+    Such a command reads although this parser cannot prove it: a package
+    runner's script, say, whose writes are the consumer's to review, not
+    kavach's. It needs no owned worktree, so the match is held as tight as a
+    trusted command's (``ReviewedLine``), and two more conditions apply:
+
+    - It runs from the checkout's root (``root``), so a relative script or
+      a package manifest means the root's own, never a subfolder's.
+    - Every variable the entry names holds one of its listed values in
+      ``environ``, the hook's own environment, which the command line cannot
+      set.
+
+    No entries: nothing is admitted here.
+    """
+
+    if not entries or cwd.resolve() != root.resolve():
+        return False
+    line = ReviewedLine(command)
+    for entry in entries:
+        if all(environ.get(name) in values for name, values in entry.env) and line.matches(
+            entry.pattern
+        ):
+            return True
+    return False
+
+
 def trusted_opening(command: str) -> tuple[str, list[list[str]]]:
     """The first segment of ``command`` as plain words, and the segments after.
 

package/python/kavach/config.py

@@ -2,8 +2,8 @@
 the environment variable KAVACH_CONFIG.
 
 kavach knows no product. What one product trusts or requires (a script its
-agents may run from any checkout, environment variables an agent must leave
-alone, a file whose change needs another in the same commit) comes from this
+agents may run from any checkout, a command it reviewed as only reading and allows in one
+environment, environment variables an agent must leave alone, a file whose change needs another in the same commit) comes from this
 file, and with no file every such rule is off.
 
 A file that cannot be read, is not JSON, has a key this module does not know,
@@ -38,6 +38,18 @@ class TrustedCommand:
     pattern: re.Pattern[str]
 
 
+@dataclass(frozen=True)
+class ReadOnlyCommand:
+    """A command line the consumer reviewed as only reading, allowed from a
+    checkout's root without an owned worktree, and only where the hook's own
+    environment holds one of the listed values for every variable in `env`.
+    `pattern` must match the whole command; `reason` says what was checked."""
+
+    pattern: re.Pattern[str]
+    env: tuple[tuple[str, tuple[str, ...]], ...]
+    reason: str
+
+
 @dataclass(frozen=True)
 class PairedChange:
     """A commit that may record a path ending in `changes` must also certainly
@@ -54,13 +66,14 @@ class Config:
     protected_variables: tuple[str, ...] = ()
     protected_variables_reason: str = ""
     paired_changes: tuple[PairedChange, ...] = ()
+    read_only_commands: tuple[ReadOnlyCommand, ...] = ()
 
 
 DEFAULT = Config()
 
 SHAPE: dict[str, set[str]] = {
     "": {"worktree", "command"},
-    "worktree": {"trustedCommands"},
+    "worktree": {"trustedCommands", "readOnlyCommands"},
     "command": {"protectedVariables", "protectedVariablesReason", "pairedChanges"},
 }
 
@@ -100,6 +113,32 @@ def _trusted(value: Any, index: int) -> TrustedCommand:
     return TrustedCommand(script, pattern)
 
 
+def _read_only(value: Any, index: int) -> ReadOnlyCommand:
+    where = f"worktree.readOnlyCommands[{index}]"
+    entry = _object(value, where, {"pattern", "env", "reason"})
+    source = _text(entry.get("pattern"), f"{where}.pattern")
+    try:
+        pattern = re.compile(source)
+    except re.error as error:
+        raise ConfigError(f"{where}.pattern is not a regular expression: {error}") from None
+    # The environment is required: an entry with no condition would widen the
+    # guard on every machine, which is what kavach's own read-only list is
+    # kept narrow to avoid.
+    raw_env = entry.get("env")
+    if not isinstance(raw_env, dict) or not raw_env:
+        raise ConfigError(f"{where}.env must be a non-empty JSON object of variable names")
+    env: list[tuple[str, tuple[str, ...]]] = []
+    for name, values in raw_env.items():
+        if not VARIABLE_NAME.fullmatch(name):
+            raise ConfigError(f"{where}.env has a key that is not a variable name: {name!r}")
+        listed = _list(values, f"{where}.env.{name}")
+        if not listed:
+            raise ConfigError(f"{where}.env.{name} must list at least one value")
+        env.append((name, tuple(_text(item, f"{where}.env.{name}[{at}]") for at, item in enumerate(listed))))
+    reason = _text(entry.get("reason"), f"{where}.reason")
+    return ReadOnlyCommand(pattern, tuple(env), reason)
+
+
 def _paired(value: Any, index: int) -> PairedChange:
     where = f"command.pairedChanges[{index}]"
     entry = _object(value, where, {"changes", "requires", "reason"})
@@ -135,7 +174,11 @@ def parse(data: Any) -> Config:
         _paired(entry, index)
         for index, entry in enumerate(_list(command.get("pairedChanges", []), "command.pairedChanges"))
     )
-    return Config(trusted, variables, reason, paired)
+    read_only = tuple(
+        _read_only(entry, index)
+        for index, entry in enumerate(_list(worktree.get("readOnlyCommands", []), "worktree.readOnlyCommands"))
+    )
+    return Config(trusted, variables, reason, paired, read_only)
 
 
 def load(environ: Mapping[str, str] | None = None) -> Config:

package/python/kavach/worktree_guard.py

@@ -22,6 +22,7 @@ import importlib.util
 import json
 import os
 import re
+import subprocess
 import sys
 from pathlib import Path
 from types import ModuleType
@@ -401,10 +402,200 @@ def denial(target: Path, root: Path, primary: Path) -> str:
     return message
 
 
+# A push in progress (0086 P-06). A pre-push hook that runs kavach's
+# `push-marker write <git-dir> <pid>` (`src/rule-checks/live-runs.ts`) leaves
+# one marker per push in the worktree's own git folder and clears it on exit.
+# While one names a live push, the push is checking this tree: an edit now
+# makes it fail at its end ("inputs changed") or check what was not pushed.
+# This reads the markers exactly as `live-runs.ts` does: the same name, the
+# same JSON, and the same rule for an ended push (`isGone`), so a marker a
+# killed push left behind, or one whose pid was reused, blocks nothing. A
+# marker that cannot be read names no push, as there: it guards against a
+# wasted push, not against the agent, whom the boundary above already holds.
+PUSH_MARKER = re.compile(r"kavach-push-in-progress\.\d+\.json")
+START_IDENTITY_FORMAT = "lstart-utc-c/1"
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+class PushRun:
+    """A push a marker records: its pid, start identity and start time."""
+
+    def __init__(self, pid: int, start_identity: str | None, started_at: str | None):
+        self.pid = pid
+        self.start_identity = start_identity
+        self.started_at = started_at
+
+
+def parse_push_run(raw: str) -> PushRun | None:
+    """A marker's run, as `parseRun` reads it; ``None`` for anything else."""
+
+    try:
+        value = json.loads(raw)
+    except ValueError:
+        return None
+    if not isinstance(value, dict):
+        return None
+    pid = value.get("pid")
+    if isinstance(pid, float) and pid.is_integer():
+        pid = int(pid)
+    if isinstance(pid, bool) or not isinstance(pid, int):
+        return None
+    if pid <= 1 or pid > MAX_SAFE_INTEGER:
+        return None
+    # A missing key is not JSON's null: `parseRun` refuses it, so this does.
+    if "startIdentity" not in value:
+        return None
+    identity = value["startIdentity"]
+    if identity is not None and not isinstance(identity, str):
+        return None
+    started = value.get("startedAt")
+    # Only a plain timestamp is quoted back in a refusal.
+    if not isinstance(started, str) or not re.fullmatch(r"[0-9T:.+Z-]{1,40}", started):
+        started = None
+    return PushRun(pid, identity, started)
+
+
+def ps_field(pid: int, field: str, environment: dict[str, str]) -> str | None:
+    """``ps -o <field>= -p <pid>``, stripped; ``None`` when ps fails."""
+
+    try:
+        result = subprocess.run(
+            ["ps", "-o", f"{field}=", "-p", str(pid)],
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+            check=False,
+            env=environment,
+        )
+    except OSError:
+        return None
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def process_alive(pid: int) -> bool:
+    """As `processProbe.isAlive`: only ESRCH or a zombie is dead."""
+
+    try:
+        os.kill(pid, 0)
+    except (ProcessLookupError, OverflowError):
+        # OverflowError: a safe integer past the system's pid range names no
+        # process.
+        return False
+    except OSError:
+        # EPERM (someone else's process) or anything else is no evidence.
+        pass
+    state = ps_field(pid, "stat", {**os.environ, "LC_ALL": "C"})
+    return state is None or not state.startswith("Z")
+
+
+def start_identity_of(pid: int) -> str | None:
+    """As `processProbe.startIdentityOf`: `lstart` read in UTC and the C locale."""
+
+    started = ps_field(pid, "lstart", {**os.environ, "TZ": "UTC", "LC_ALL": "C"})
+    return f"{START_IDENTITY_FORMAT} {started}" if started else None
+
+
+def is_current_identity(identity: str | None) -> bool:
+    return identity is not None and identity.startswith(f"{START_IDENTITY_FORMAT} ")
+
+
+def push_is_gone(run: PushRun) -> bool:
+    """As `isGone`: the pid is dead, or now a process that started later."""
+
+    if not process_alive(run.pid):
+        return True
+    if not is_current_identity(run.start_identity):
+        return False
+    current = start_identity_of(run.pid)
+    if current is None:
+        return not process_alive(run.pid)
+    return is_current_identity(current) and current != run.start_identity
+
+
+def git_dir_of(root: Path) -> Path | None:
+    """The worktree's own git folder, from its files first, then from git."""
+
+    try:
+        found = boundary.checkout_from_files(root)
+    except boundary.GitMustAnswer:
+        found = None
+    if found is not None:
+        return found[1]
+    answer = boundary.run_git(root, "rev-parse", "--absolute-git-dir")
+    return Path(answer) if answer else None
+
+
+def live_push(root: Path) -> PushRun | None:
+    """The first live push a marker in the worktree's git folder records."""
+
+    git_dir = git_dir_of(root)
+    if git_dir is None:
+        return None
+    try:
+        names = sorted(name for name in os.listdir(git_dir) if PUSH_MARKER.fullmatch(name))
+    except OSError:
+        return None
+    for name in names:
+        try:
+            raw = (git_dir / name).read_text(encoding="utf-8")
+        except (OSError, ValueError):
+            continue
+        run = parse_push_run(raw)
+        if run is not None and not push_is_gone(run):
+            return run
+    return None
+
+
+def git_ignores(root: Path, target: Path) -> bool:
+    """Whether git ignores ``target`` in the checkout at ``root``.
+
+    A tracked file is never ignored, whatever the patterns say; an answer git
+    cannot give counts as not ignored.
+    """
+
+    # `./` keeps a name such as `:(top)x` from being read as pathspec magic.
+    relative = f"./{os.path.relpath(target, root)}"
+    result = boundary.run_git_result(root, "check-ignore", "-q", "--", relative)
+    return result.returncode == 0
+
+
+def refuse_during_push(tool: object, targets: list[Path], root: Path) -> None:
+    """Refuse a write into the worktree while its push runs.
+
+    A Bash command that reached here is one the boundary could not prove
+    read-only, and its targets always include the directory it runs in, so
+    any such command run in the worktree waits: what it writes there cannot
+    be told. An Edit, Write or NotebookEdit names its one path, and a path git
+    ignores (a draft, a scratch file) changes nothing a push reads.
+    """
+
+    checkout = root.resolve()
+    inside = [target for target in targets if boundary.is_inside(target.resolve(), checkout)]
+    if not inside:
+        return
+    run = live_push(root)
+    if run is None:
+        return
+    if tool == "Bash":
+        what = "this command may write in it"
+    else:
+        changed = [target for target in inside if not git_ignores(checkout, target.resolve())]
+        if not changed:
+            return
+        what = f"this edits {os.path.relpath(changed[0].resolve(), checkout)}, which git does not ignore"
+    started = f", started {run.started_at}" if run.started_at else ""
+    boundary.deny(
+        f"this worktree's push (pid {run.pid}{started}) is still running, and {what}. "
+        "Wait for the push to end, then retry. Read-only commands still run, "
+        "and files git ignores can still be written with Edit or Write."
+    )
+
+
 def main() -> None:
     # First, so a misread settings file refuses every event, a read-only one
     # included.
-    trusted = settings().trusted_commands
+    loaded = settings()
+    trusted = loaded.trusted_commands
     data = boundary.read_input()
     cwd = Path(data.get("cwd") or Path.cwd()).resolve()
     state = boundary.checkout_state(cwd)
@@ -426,6 +617,13 @@ def main() -> None:
         command = boundary.tool_command(values)
         if command and boundary.shell_is_read_only(command):
             return
+        # A read the consumer reviewed (`worktree.readOnlyCommands`), from the
+        # checkout's root and only in the environment its entry names: like a
+        # proven read, it needs no owned worktree and waits for no push.
+        if command and boundary.read_only_request(
+            command, cwd, root, loaded.read_only_commands, os.environ
+        ):
+            return
     # Only the shell parser reads these (a file tool is never given them), and
     # finding them costs git starts, so an Edit or Write does not pay for them.
     read_namespaces = harness_state_roots(root, primary) if tool == "Bash" else ()
@@ -449,7 +647,9 @@ def main() -> None:
         boundary.tool_command(values), cwd, root, trusted
     ):
         # A script the consumer reviewed and trusts, reached only after
-        # ownership above.
+        # ownership above. What it writes is unproven, so it counts as
+        # writing in the checkout while a push runs.
+        refuse_during_push(tool, [root], root)
         return
     if targets is None:
         boundary.deny("mutation targets could not be resolved")
@@ -459,6 +659,7 @@ def main() -> None:
         # operand outside both still fails on that operand.
         if not (boundary.is_session_target(target, root, primary) or in_memory(target)):
             boundary.deny(denial(target, root, primary))
+    refuse_during_push(tool, targets, root)
 
 
 def run() -> None: