deadpush 0.2.1__tar.gz → 0.2.2__tar.gz

deadpush-0.2.2/.cursorignore

@@ -0,0 +1,23 @@
+
+# Added by deadpush
+**/playground.*
+**/scratch*.md
+**/temp*.py
+**/tmp*.go
+.claude_instructions
+.copilot-instructions.md
+.cursorrules
+.deadpush-archive/
+.deadpush-autoignore
+.deadpush-quarantine/
+.venv/
+__pycache__/
+agents.md
+ai_prompt.md
+claude.md
+dist/
+llm_context.txt
+node_modules/
+target/
+venv/
+windsurf_rules.md

deadpush-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  PYTHONUTF8: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Verify lockfile is in sync
+        run: uv lock --check
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Lint with ruff (blocking)
+        run: uv run ruff check deadpush/ tests/ scripts/
+
+  test:
+    # Unit + integration suite. Runs on Linux across supported Python versions
+    # and on macOS (the primary hardened-mode target). The integration test in
+    # tests/test_integration_lifecycle.py drives the installed CLI and executes
+    # the real generated git hooks — the closest deterministic proxy to a user's
+    # first run, without the flakiness of a background daemon in CI.
+    needs: [lint]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run tests
+        run: uv run pytest -v

{deadpush-0.2.1 → deadpush-0.2.2}/.gitignore

@@ -95,10 +95,9 @@ ipython_config.py
 # Pipfile.lock
 
 # UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-uv.lock
+#   deadpush is a distributed application/security tool, so uv.lock IS committed
+#   for reproducible builds. CI enforces it (uv lock --check, uv sync --frozen).
+# uv.lock
 
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.

deadpush-0.2.2/.vscode/mcp.json

@@ -0,0 +1,10 @@
+{
+  "servers": {
+    "deadpush": {
+      "command": "/Users/harris/Documents/personal/deadpush/.venv/bin/deadpush",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

{deadpush-0.2.1 → deadpush-0.2.2}/AGENT.md

@@ -6,9 +6,9 @@ This project uses **deadpush**: an agent-native guardrail system that intercepts
 
 - Write files normally via MCP (`write_file` tool). Guardrails run automatically.
 - If blocked → read the feedback file → fix the issue → retry.
-- If you hit a false positive → `add_allowed_pattern` to whitelist the code.
+- If you hit a false positive → `add_allowed_pattern` to whitelist the code (requires `deadpush mcp --danger`).
 
-## MCP Tools (24 available)
+## MCP Tools
 
 Connect via `deadpush mcp` (stdio JSON-RPC on `2024-11-05` protocol).
 
@@ -17,34 +17,27 @@ Connect via `deadpush mcp` (stdio JSON-RPC on `2024-11-05` protocol).
 |---|---|
 | `write_file(path, content)` | Write through guardrails. Blocked files go to quarantine + feedback. |
 | `check_file(path, content)` | Preview: would the file pass? Returns violations without writing. |
+| `verify_write(path, content)` | Write + run related tests. File only persists if tests pass. |
+| `get_write_diff(path, content)` | Preview diff + guardrail violations before writing. |
+| `retry_write(path, content)` | Submit corrected content for a previously blocked file. |
 
-### Scan
+### Quarantine
 | Tool | What it does |
 |---|---|
-| `scan` | Full analysis summary (dead symbols, debris, test issues, etc.) |
-| `get_dead_symbols` | Unreachable code |
-| `get_debris` | AI artifacts, stale files |
-| `get_test_issues` | No-assertion / tautology / empty tests |
-| `get_stale_docs` | Docstring-param mismatches |
-| `get_layer_violations` | Architectural import violations |
-| `get_security_boundaries` | Untested security-sensitive ops |
-| `get_complexity_alerts` | Complexity spikes |
-
-### Clean / Quarantine
-| Tool | What it does |
-|---|---|
-| `clean(mode)` | Remove dead code / debris (safe, dry_run, force) |
 | `quarantine_list(limit)` | List quarantined files |
-| `quarantine_restore(name)` | Restore from quarantine |
+| `quarantine_restore(name)` | Restore from quarantine (danger mode) |
 
 ### Feedback
 | Tool | What it does |
 |---|---|
 | `get_feedback(limit)` | Read recent guardrail feedback |
+| `get_recent_feedback(limit)` | Unacknowledged feedback only |
+| `acknowledge_feedback(name)` | Mark feedback as read/addressed |
 | `get_status` | Current paths + available tools |
 | `get_safety_score` | Latest guardian score |
+| `get_test_results(limit)` | Recent verify_write test output |
 
-### Config (agent self-service)
+### Config (agent self-service — danger mode for softening actions)
 | Tool | What it does |
 |---|---|
 | `get_runtime_config` | View all current rules |
@@ -53,15 +46,12 @@ Connect via `deadpush mcp` (stdio JSON-RPC on `2024-11-05` protocol).
 | `ignore_path(path)` | Skip a file entirely |
 | `set_guardrail_level(category, level)` | Set severity: `off`, `warn`, or `block` |
 | `reset_runtime_config` | Clear all overrides to defaults |
+| `allow_sensitive_write(path)` | Opt in to writing a sensitive config file |
+| `learn_false_positive(category, pattern, reason)` | Teach deadpush to suppress a false positive |
+| `adjudicate_finding(...)` | Structured adjudication rubric for a finding |
 
 All tools return `{"success": bool, "data": ..., "summary": "..."}`.
 
-### Diff / Preview
-| Tool | What it does |
-|---|---|
-| `get_write_diff(path, content)` | Preview diff + guardrail violations before writing |
-| `allow_sensitive_write(path)` | Opt in to writing a sensitive config file (CI/CD, Docker, etc.) |
-
 ## Guardrail Categories
 
 | Category | Default level | What it catches |
@@ -72,7 +62,7 @@ All tools return `{"success": bool, "data": ..., "summary": "..."}`.
 | `layer` | `block` | Imports violating architecture layer rules |
 | `sensitive` | `block` | Writes to CI/CD, deployment, Docker, and other sensitive config files |
 | `destructive` | `warn` | Near-empty rewrites of substantial files, >50% line reduction |
-| `debris` | `warn` | TODO stubs, FIXME markers, bare `pass` statements |
+| `debris` | `warn` | LLM context files, scratchpads, hardcoded secrets in debris scan |
 | `dependency` | `warn` | Typosquat packages, suspicious package names in dep files |
 
 ## Self-Correction Flow
@@ -95,8 +85,6 @@ Then retry — it will pass.
 Persisted in `.deadpush/rules.json`. Survives server restarts.
 Modify via MCP tools above. Do NOT edit the file directly.
 
-Use `set_guardrail_level("prompt_injection", "warn")` to downgrade a category to warning-only (doesn't block, just reports).
-
 ## What NOT To Do
 
 - Do NOT bypass guardrails by writing directly to the filesystem.

deadpush-0.2.2/CHANGELOG.md

@@ -0,0 +1,277 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.2] - 2026-07-04
+
+First public release on PyPI (`0.2.1` was burned by PyPI's deleted-filename
+reuse rule and skipped). The project stays on a 0.2.x beta line until the
+production-readiness gates (blocking lint, lockfiled reproducible builds, and
+green macOS + Linux CI including the lifecycle integration test) are met.
+
+### Security (hardened mode — Tier 0)
+
+A threat-model audit (adversarial agent running as the same UID) found five ways
+a same-UID agent could defeat *hardened* mode even though the daemon and hook
+files were protected. These close them so hardened mode is a real boundary, not
+just defense-in-depth. Covered by `tests/test_tier0_hardening.py` and validated
+end-to-end by `scripts/hardened_qa.sh`.
+
+- **Hardened hooks now execute the root-owned interpreter (H2)**: git hooks used
+  the *user's* interpreter and user-writable `deadpush` package, so a same-UID
+  agent could no-op the guardrails by editing the package — defeating even a
+  root-immutable hook file. Hardened hooks now run `/var/db/deadpush/venv/bin/
+  python` (owned by `_deadpush`, not user-writable). The guardian's auto-repair
+  re-pins this interpreter and re-locks `schg` instead of downgrading.
+- **Guardrail policy is now read from a root-owned dir (H1)**: enforcement read
+  `rules.json` / `learned_patterns.json` from the in-repo `.deadpush/` directory,
+  which the agent can write (it could set every category to `off` or allowlist
+  `.*`). Hardened installs now read/write policy from a root/`_deadpush`-owned
+  tree (`/var/db/deadpush/policy/<repo-id>/`) that the user can traverse and read
+  but not modify. Soft mode is unchanged (in-repo, deterrence only).
+- **Control server enforces a bearer token on mutations (H3)**: the localhost
+  control server shipped with auth wired up but disabled (no token), so any
+  local process — including the agent — could reset the allowlist or restore
+  quarantined files. A random token is now generated per guardian and stored
+  `0600` (root-owned in hardened mode, so the agent can't read it); state-changing
+  `POST`s require it (with a constant-time compare), while read-only `GET`s stay
+  open so the human dashboard still works.
+- **Quarantine restore is confined to the repo tree (H4)**: `restore()` moved a
+  file to the absolute "Original path" read from an agent-writable `.reason`
+  file, letting a crafted `.reason` make the guardian (running as `_deadpush`)
+  write anywhere — a confused-deputy write. The destination is now resolved and
+  required to stay within the repo, else the restore is refused.
+- **Fail-closed can no longer be cleared by the agent (H5)**: the hooks' fail-
+  closed decision keyed only off the agent-deletable in-repo `.deadpush/installed`
+  marker. Hardened setup now also writes a root-owned marker under
+  `/var/db/deadpush/policy/<repo-id>/`, and the hook prelude honors it, so
+  fail-closed holds even if the in-repo marker is deleted. (Combined with H2 the
+  root-owned interpreter is itself un-deletable by the agent.)
+- **Hardened state dir is now `0711` (was `0700`)**: required so the user's git
+  hooks can *traverse* to the root-owned interpreter and policy. The directory is
+  not listable and secret files (the control token) remain `0600`.
+
+### Added
+- **`SECURITY.md` threat model**: documents the adversary (a same-UID AI agent),
+  the soft-vs-hardened guarantees, the inherent limits of heuristic detection, and
+  private vulnerability reporting.
+- **Real-time move/delete handling**: the watchdog guardian only handled
+  `on_created`/`on_modified`, so an agent could evade the real-time layer by
+  moving un-scanned content into place (stage a payload in a skipped dir like
+  `node_modules/` then `mv` it in, or rename a benign file onto a dangerous
+  path/name). `on_moved` now evaluates the destination exactly like a fresh
+  write (dangerous content is quarantined). `on_deleted` records forensic
+  telemetry (log + session incident) but is deliberately non-punitive — it does
+  not auto-restore or dock the safety score, since the score never recovers and
+  a legitimate multi-file `git rm`/refactor would otherwise false-trigger
+  lockdown; tracked files remain recoverable from git history. Covered by
+  `tests/test_move_delete_events.py`.
+- **Fail-closed git hooks**: once a repo is protected (a `.deadpush/installed`
+  marker is written), the installed hooks refuse to run when the deadpush
+  interpreter goes missing, instead of silently allowing the push/commit.
+  `DEADPUSH_STRICT=1` forces fail-closed everywhere.
+- **`protect` verifies and reports failure**: `deadpush protect` now polls that
+  the guardian actually started, and exits non-zero with actionable guidance if
+  hooks, the marker, or the daemon did not come up (no more false "success").
+- **`doctor` protection checks**: reports the protection marker (and whether the
+  pinned interpreter still exists) plus git-hook integrity.
+- **Lifecycle integration test** (`tests/test_integration_lifecycle.py`): drives
+  the installed CLI and executes the real generated hooks; runs on macOS + Linux
+  in CI.
+- **Hardened-mode QA harness** (`scripts/hardened_qa.sh`): a manual, root-gated
+  end-to-end validator for the hardened guarantees CI cannot cover — privilege
+  separation, an agent-unkillable daemon (and launchd/systemd respawn),
+  root-immutable `schg`/`+i` hooks, repo + `$HOME`-traverse ACLs, real-time
+  quarantine, `core.hooksPath` self-heal, and a verified clean teardown. It runs
+  in a throwaway repo, escalates only via `sudo`, and refuses to run when a
+  `_deadpush` account already exists so it can't disturb a real install.
+- **`core.hooksPath` hijack detection + self-heal**: `git config core.hooksPath
+  /dev/null` (or any dir other than `.git/hooks`) silently disabled every hook
+  without tripping the checksum/immutability checks. `verify_hooks_installed` now
+  flags it, `repair_deadpush_hooks` restores it (repo-local only, overriding a
+  global hijack if needed), the running guardian auto-repairs it every cycle, and
+  `doctor` reports it. Covered by `tests/test_hookspath_hijack.py`.
+- **Root-immutable hooks in hardened mode**: hardened installs now lock the git
+  hooks ROOT-immutable (`sudo chflags schg` on macOS, `sudo chattr +i` on Linux)
+  instead of only user-immutable (`uchg`). A same-UID agent can no longer clear
+  the flag to delete or rewrite a hook — only root can. Soft mode keeps the
+  owner-clearable `uchg`. `_is_immutable` now recognises `schg` (so the guardian
+  never loops trying to "repair" a locked hook it cannot rewrite), `uninstall`
+  clears it via sudo (with an automatic escalation fallback), and if `schg` can't
+  be set it fails safe to `uchg` with a loud warning. Covered by
+  `tests/test_root_immutable.py`.
+
+### Fixed
+- **Pre-push new-branch range can no longer be poisoned (D4)**: for a brand-new
+  branch (remote side all-zeros) the hook derived the scan boundary from
+  `git rev-list … --not --remotes`, trusting local `refs/remotes/*`. Those refs are
+  writable by a same-UID agent, so forging `refs/remotes/x/y` at the payload commit
+  made git treat the dangerous content as "already on the remote" and shrank the
+  scanned diff to exclude it — while `git push` still shipped those commits. New
+  refs now always scan the entire pushed tree (`empty-tree..local_sha`), which
+  cannot be poisoned by local refs; existing-branch updates keep using the
+  trustworthy `remote_sha` git supplies from the real push negotiation. Covered by
+  `tests/test_prepush_newbranch.py`
+  (`test_new_branch_push_cannot_be_poisoned_by_fake_remote_ref`).
+- **Uninstall leaves the repo pristine**: cleanup only removed an empty
+  `.guardian`, leaving behind empty `.deadpush` (e.g. `.deadpush/feedback/`) and
+  `.deadpush-quarantine` directories. It now prunes deadpush's own now-empty
+  bookkeeping dirs — but strictly non-destructively: a directory is removed only
+  when it has no remaining contents, so real feedback data, config, and
+  quarantined files are always preserved. Covered by
+  `tests/test_integration_lifecycle.py`
+  (`test_uninstall_leaves_repo_pristine`, `test_uninstall_preserves_user_data`).
+- **Cross-platform uninstall**: `deadpush uninstall` invoked `launchctl`
+  unconditionally, which raised `FileNotFoundError` on Linux and made the command
+  exit non-zero. It now unloads/removes the correct service per platform (launchd
+  plist on macOS, systemd unit on Linux — the systemd unit was previously never
+  removed) and treats a missing/inactive service manager as a no-op.
+- **Hardened-mode teardown parity on Linux**: hardened setup already supported
+  Linux (`useradd`/`groupadd`/`setfacl`), but uninstall only ran macOS
+  `dscl`/`chmod -N`, so it crashed on Linux and orphaned the `_deadpush`
+  account/ACLs. Added `teardown_hardened_environment`, a platform-aware,
+  best-effort reversal that revokes every `_deadpush` ACL (repo tree,
+  `.guardian`, and parent traverse dirs — a shared walk with setup so the two
+  can't drift) and deletes the account (macOS `dscl`, Linux `userdel`/`groupdel`),
+  revoking ACLs before removing the account. Covered by
+  `tests/test_hardened.py::TestTeardownHardenedEnvironment`.
+
+### Changed
+- **Wider git-hook file coverage**: the pre-commit/pre-push/post-commit hooks
+  gated content scanning on a small extension allowlist (~18 types), so an agent
+  could commit dangerous content in files the hooks never read — extensionless
+  and config files such as `Dockerfile`, `Makefile`, `.env`, `.npmrc`, shell
+  rc-files, and LLM-context files like `.cursorrules` / `.claude_instructions`
+  (the watchdog daemon already scanned these; the hooks did not). A shared
+  `is_enforceable_path()` now mirrors the daemon's coverage: a much wider set of
+  code/config/infra/text extensions plus sensitive-by-name and `.env*` /
+  `Dockerfile*` files, while binary formats (images, archives, compiled objects,
+  keystores) are always skipped. Covered by `tests/test_file_coverage.py`.
+- **Robust hook/daemon entrypoint**: generated hooks, the launchd/systemd units,
+  and the shadow respawn command now launch via `deadpush_bootstrap` instead of
+  `-m deadpush.cli`, so they work in editable installs where macOS hides the
+  `.pth` file (previously the guardian and hooks failed to import deadpush from a
+  non-source working directory).
+- **Single source of truth for version**: `pyproject.toml` derives the version
+  from `deadpush/__init__.py` (hatchling dynamic version); metadata and
+  `deadpush.__version__` can no longer drift.
+
+### CI / tooling
+- Ruff is now a **blocking** gate; the codebase is lint-clean.
+- `uv.lock` is committed and CI runs `uv lock --check` + `uv sync --frozen` for
+  reproducible builds.
+- CI test matrix runs on **macOS and Linux** across supported Python versions.
+
+### Fixed
+- **launchctl bootstrap bug**: `protect` no longer marks the guardian as
+  bootstrapped when `launchctl bootstrap` fails; it now falls back to a direct
+  daemon launch and verifies the result.
+- `uninstall` now also removes the deadpush git hooks and the protection marker,
+  so a full uninstall truly leaves nothing behind.
+- **Pre-push scanning of new branches**: pushing a brand-new branch (remote side
+  all-zeros) previously diffed the working tree against the tip and scanned
+  nothing, letting a first push bypass content enforcement. New commits are now
+  resolved against the boundary already on the remote (or the whole tree when
+  there is no shared history) and scanned. Covered by `tests/test_prepush_newbranch.py`.
+- **Test isolation / macOS notification spam**: the autostart unit tests wrote
+  real plists into `~/Library/LaunchAgents` (path derived from `$HOME`, not the
+  temp repo), triggering a macOS "app can run in the background" notification per
+  run and littering hundreds of stale plists. They now use the isolated
+  `hardened_env` fixture.
+
+### Packaging
+- **Homebrew formula rewrite** (`Formula/deadpush.rb`): switched from a fragile
+  `pip3 install --prefix` to `virtualenv_install_with_resources` with runtime
+  dependencies pinned to the `uv.lock` versions (`click`, `pathspec`, `watchdog`),
+  a Homebrew-audit-clean `desc`, and a `--version` test. Passes `brew style`.
+  A release helper (`scripts/brew_release.sh`) fills the source `sha256` and runs
+  audit/install/test. Note: `brew install` requires the repo to be **public** with
+  the release tag pushed; the `sha256` is a placeholder until then.
+
+---
+
+## [1.0.0] - unreleased
+
+_Historical notes previously drafted under a 1.0.0 heading; not yet released._
+
+### Added
+- **Log rotation**: RotatingFileHandler (10MB × 5 files) prevents unbounded log growth
+- **Safety score JSON persistence**: Structured `safety_score.json` in state dir, auto-saved on every incident, read by MCP server
+- **MCP Bearer token authentication**: Optional token auth for GuardianControlServer endpoints
+- **Health endpoint**: `GET /health` on GuardianControlServer for launchd/systemd health checks
+- **CLI: doctor**: Comprehensive health check (`deadpush doctor`)
+- **CLI: uninstall**: Complete removal including hardened mode cleanup (`deadpush uninstall`)
+- **CLI: init**: Guided first-time setup (`deadpush init --mode default|hardened --daemon`)
+- **Hardened mode**: Full privilege separation via dedicated `_deadpush` user/group
+  - Dedicated `_deadpush` group (not wheel) — eliminates root escalation risk
+  - ACLs on repo (read) + `.guardian/` (write), hooks write access removed
+  - LaunchDaemon with `UserName=_deadpush`, state in `/var/db/deadpush/`
+  - `setup_hardened_environment()` one-time sudo setup
+- **Lock/PID improvements**: Holder PID stored in lock file, start-time verification, `--force` cleanup
+- **Daemon fork safety**: Handler and control server created post-fork, FD closure
+- **Shadow process hardening**: Health checks via `ps`, exponential backoff, PID coordination
+- **Lock manager**: Holder PID in lock file, `force_cleanup()`, `--force` CLI flag
+- **Test scripts**: `scripts/soak_test.py` (multi-repo), `scripts/stress_test.py` (high-concurrency)
+- **CI/CD**: GitHub Actions workflow for building wheels, publishing to PyPI, GitHub Releases
+- **Homebrew formula**: Template formula for `brew install deadpush`
+
+### Changed
+- **Per-repo hardened flag**: Replaced global `_hardened_enabled` with explicit `hardened` parameter on all functions
+- **Safety score storage**: Migrated from log parsing to structured JSON (`safety_score.json`)
+- **MCP safety score tool**: Now reads structured JSON instead of log parsing
+- **Lock manager**: Added holder PID tracking, force cleanup, `get_holder_pid()`
+- **Daemon fork safety**: `GuardianHandler` and `GuardianControlServer` created post-fork, all inherited FDs closed
+- **Shadow process**: Health checks via `ps`, exponential backoff (3s→60s), max 10 failures, PID file coordination
+- **PID reuse protection**: Start time verification via `ps -o etimes=` + command line check
+- **TOCTOU lock fix**: Holder PID stored, `--force` cleanup flag
+
+### Security
+- Removed `_deadpush` from wheel group — eliminated root escalation via sudoers
+- Removed hook write ACL for `_deadpush` — guardian no longer modifies `.git/hooks/`
+- Dedicated `_deadpush` group with GID 499
+
+### Fixed
+- PID reuse false positive in `DaemonManager.is_running()`
+- TOCTOU race in lock acquisition
+- Fork crash from thread-before-fork in daemon mode
+- Duplicate `_require_auth` method in control handler
+
+---
+
+## [0.2.1] - 2026-06-20
+
+### Added
+- Multi-agent Safety Score with burst detection
+- Session tracking (events, recent files, duration)
+- Per-repo scoped state files (PID, lock, port, suspend, plist)
+- Launchd/systemd autostart config generation
+- Shadow process for guardian respawn
+- MCP server with stdio transport
+- Agent-as-Adjudicator feedback loop
+- Debris detection (LLM context files, vibe scratchpads, secrets, duplicates)
+- Layer violation detection (architecture import rules)
+- Smart ignore file auto-merge
+
+### Changed
+- Safety score now tracks multi-agent bursts
+- Path-aware guardrail lowering for test/mock files
+- Learned false positive patterns persisted to `.deadpush/learned_patterns.json`
+
+---
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- Initial release
+- Real-time filesystem guardian with watchdog
+- 7-category guardrail pipeline (security, secrets, prompt injection, debris, layers, destructive, sensitive config)
+- Call graph dead code analysis with 8-factor scoring
+- Git pre-push hook installation
+- Quarantine system (safe restore via git)
+- Static call graph resolution
+- Basic MCP server with stdio transport

deadpush-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thanks for your interest in deadpush.
+
+## Getting Started
+
+```bash
+git clone https://github.com/harris-ahmad/deadpush
+cd deadpush
+./scripts/dev_install.sh
+source .venv/bin/activate
+```
+
+Or manually:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,rich]"
+```
+
+### macOS: editable install silently broken?
+
+On macOS, Python 3.12+ **skips `.pth` files marked hidden** (`UF_HIDDEN`). Files under `~/Documents` (and other iCloud-synced folders) often get this flag, so `pip install -e .` succeeds but `deadpush` only works when your cwd is the repo — from any other directory you get `ModuleNotFoundError`.
+
+Fix:
+
+```bash
+./scripts/dev_install.sh
+# or, if already installed:
+chflags -R nohidden .venv
+```
+
+Do **not** run plain `pip install deadpush` in the dev venv; use `pip install -e .` so the editable hook points at your source tree.
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Code Style
+
+We use ruff. Run before committing:
+
+```bash
+ruff check .
+```
+
+## Pull Requests
+
+- Keep changes focused. One PR = one concern.
+- Add tests for new functionality.
+- Run the full test suite before submitting.
+- Update CHANGELOG.md if the change is user-facing.
+
+## Questions?
+
+Open an issue at https://github.com/harris-ahmad/deadpush/issues

deadpush-0.2.2/Formula/deadpush.rb

@@ -0,0 +1,58 @@
+class Deadpush < Formula
+  include Language::Python::Virtualenv
+
+  desc "Real-time AI agent guardian with git hooks and MCP write interception"
+  homepage "https://github.com/harris-ahmad/deadpush"
+  url "https://github.com/harris-ahmad/deadpush/archive/refs/tags/v0.2.1.tar.gz"
+  # RELEASE STEP: placeholder sha256 (all-zeros). It can only be filled once the
+  # repo is PUBLIC and the tag is pushed. `brew install` will fail loudly with a
+  # checksum mismatch until then. Run scripts/brew_release.sh to fetch the tarball,
+  # compute the real sha256, write it here, and verify with brew audit/install/test.
+  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
+  license "MIT"
+
+  depends_on "python@3.14"
+
+  # Runtime dependencies, pinned to the exact versions in uv.lock (the versions
+  # the test suite runs against). Homebrew installs these with --no-deps, so every
+  # runtime dependency must be listed explicitly. The PEP 517 build backend
+  # (hatchling) is resolved automatically via pip build isolation and is not vendored.
+  resource "click" do
+    url "https://files.pythonhosted.org/packages/9b/98/518d8e5081007684232226f475082b30087d0f585e8457db087298259f49/click-8.4.1.tar.gz"
+    sha256 "918b5633eddf6b41c32d4f454bf0de810065c74e3f7dbf8ee5452f8be88d3e96"
+  end
+
+  resource "pathspec" do
+    url "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz"
+    sha256 "17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a"
+  end
+
+  resource "watchdog" do
+    url "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz"
+    sha256 "9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282"
+  end
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  def caveats
+    <<~EOS
+      Get started by protecting a repository:
+        cd your-repo && deadpush init
+
+      For hardened mode (privilege separation via a dedicated _deadpush user):
+        sudo deadpush init --mode hardened
+
+      Run the guardian as a background daemon:
+        deadpush protect --daemon
+
+      Check status:
+        deadpush status
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/deadpush --version")
+  end
+end