If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/lg/murder shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 9y ago

• 8 active contributors
• Other licensed
• ⚠ Stale — last commit 9y ago
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live lg/murder repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/lg/murder.

What it runs against: a local clone of lg/murder — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in lg/murder | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 3443 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of lg/murder. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/lg/murder.git
#   cd murder
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of lg/murder and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "lg/murder(\\.git)?\\b" \\
  && ok "origin remote is lg/murder" \\
  || miss "origin remote is not lg/murder (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/capistrano/recipes/deploy/strategy/murder.rb" \\
  && ok "lib/capistrano/recipes/deploy/strategy/murder.rb" \\
  || miss "missing critical file: lib/capistrano/recipes/deploy/strategy/murder.rb"
test -f "lib/murder/murder.rb" \\
  && ok "lib/murder/murder.rb" \\
  || miss "missing critical file: lib/murder/murder.rb"
test -f "dist/murder_client.py" \\
  && ok "dist/murder_client.py" \\
  || miss "missing critical file: dist/murder_client.py"
test -f "dist/murder_tracker.py" \\
  && ok "dist/murder_tracker.py" \\
  || miss "missing critical file: dist/murder_tracker.py"
test -f "dist/murder_make_torrent.py" \\
  && ok "dist/murder_make_torrent.py" \\
  || miss "missing critical file: dist/murder_make_torrent.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 3443 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3413d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/lg/murder"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Murder is a BitTorrent-based large-scale server deployment system that distributes files across hundreds to tens of thousands of servers efficiently using peer-to-peer file transfer instead of centralized distribution. It wraps the BitTornado library (a Python BitTorrent implementation) with a Ruby/Capistrano interface to create torrents from deployment artifacts, coordinate seeders and peers, and manage tracker communication for production-grade multi-server deploys. Hybrid structure: Ruby gem wrapper (Rakefile, lib/, VERSION) over vendored Python BitTornado library (dist/BitTornado/ contains full source tree: BT1/ for core protocol, plus tracker, client, and utility scripts). Entry points are dist/murder_client.py (peer downloader) and dist/murder_make_torrent.py (torrent creation).

DevOps engineers and deployment specialists at large organizations (Twitter-scale or similar) who need to distribute deployment packages across massive server fleets quickly without overwhelming centralized distribution systems. Used by teams managing hundreds+ of servers who want faster, more scalable deploys than rsync or traditional package managers.

Abandoned and unmaintained—the README explicitly warns 'This project, though still functional, is no longer maintained.' Copyrighted 2010-2012 by Twitter Inc., it's a historical artifact showing BitTorrent deployment concepts rather than production-ready software. No modern CI, no recent commits, no test suite visible in the file structure.

High risk: unmaintained since ~2012, depends on BitTornado (itself deprecated), written against old Python 2 patterns visible in the dist/BitTornado vendored code, and no test coverage indicated. The Capistrano integration requires ancient Capistrano v2 syntax. Single-project origins (Twitter internal tool released post-hoc) with no community adoption path forward.

Nothing—this is archived. No active development, PRs, or maintenance. It exists as historical documentation of a solved problem (scalable deploys) that was superseded by cloud infrastructure and modern container distribution (Docker registries, artifact repositories).

gem install murder
# Then add to Capfile:
require 'murder'
set :deploy_via, :murder

Note: This assumes Capistrano v2.x installed and Python 2 available for BitTornado. Modern setups will fail due to Python 2 EOL and Capistrano 3+ API changes.

Daily commands:

# Start tracker (on a single machine):
python dist/BitTornado/BT1/track.py --port 6969

# Create torrent from deployment directory:
python dist/murder_make_torrent.py /path/to/files output.torrent http://tracker-ip:6969/announce

# Peers download via:
python dist/murder_client.py output.torrent /download/destination

• lib/capistrano/recipes/deploy/strategy/murder.rb — Core Capistrano integration point—implements the murder deploy strategy that orchestrates the entire BitTorrent-based distribution workflow.
• lib/murder/murder.rb — Main Murder module containing central business logic for managing torrent creation, seeding, and peer coordination.
• dist/murder_client.py — Client-side BitTornado implementation that servers run to download and seed deploy artifacts.
• dist/murder_tracker.py — Tracker daemon that coordinates peer discovery and swarm management for the BitTorrent network.
• dist/murder_make_torrent.py — Torrent metafile generator that creates .torrent files from deployment artifacts.
• dist/BitTornado/download_bt1.py — BitTornado core download engine handling peer communication, piece selection, and data assembly.
• README.md — Project overview explaining Murder's purpose, architecture, and quick-start setup for team onboarding.

Add a new deployment hook or administrative task

1. Define new Capistrano task in lib/murder/admin.rb with proper :deploy_to and server role references (lib/murder/admin.rb)
2. Add lifecycle hook (e.g., after 'deploy:setup') in lib/capistrano/recipes/deploy/strategy/murder.rb (lib/capistrano/recipes/deploy/strategy/murder.rb)
3. Reference task in example Capfile at doc/examples/Capfile for documentation (doc/examples/Capfile)

Modify the torrent creation or seeding workflow

1. Edit torrent generation logic in lib/murder/murder.rb (Murder class, create_torrent method) (lib/murder/murder.rb)
2. Adjust bencode encoding if metafile format changes in dist/BitTornado/bencode.py (dist/BitTornado/bencode.py)
3. Update tracker announce format or peer coordination in dist/murder_tracker.py if needed (dist/murder_tracker.py)

Add a new BitTornado protocol feature or optimization

1. Implement protocol logic in appropriate BT1 module (e.g., dist/BitTornado/BT1/Downloader.py for download changes) (dist/BitTornado/BT1/Downloader.py)
2. Update encrypter/protocol handler in dist/BitTornado/BT1/Encrypter.py for message format changes (dist/BitTornado/BT1/Encrypter.py)
3. Integrate client-side changes in dist/murder_client.py download loop if needed (dist/murder_client.py)

Tune network performance or rate limiting

1. Adjust rate limiter thresholds in dist/BitTornado/RateLimiter.py (dist/BitTornado/RateLimiter.py)
2. Modify socket handler concurrency and buffer sizes in dist/BitTornado/SocketHandler.py (dist/BitTornado/SocketHandler.py)
3. Configure Murder-level settings (e.g., seeder count, timeout) in lib/murder/murder.rb (lib/murder/murder.rb)

• BitTorrent (BitTornado library) — Decentralized peer-to-peer distribution scales horizontally; each peer becomes a seeder, reducing bottleneck at central distribution point and enabling deployments to thousands of servers in parallel.
• Ruby + Capistrano — Capistrano is the canonical infrastructure automation tool for Ruby deployments; integrating Murder as a strategy allows seamless adoption in existing Ruby/Rails deploy workflows.
• Python BitTornado client/tracker — BitTornado is a lightweight, pure-Python BitTorrent implementation ideal for embedded deploy agents on servers; reduces dependencies and simplifies cross-platform client deployment.
• Bencode serialization — Standard BitTorrent metafile and peer communication encoding; enables interoperability with standard BitTorrent infrastructure and tools.

• Centralized tracker instead of DHT

  • Why: Simplifies peer discovery in closed production networks and provides deterministic, auditable swarm coordination without relying on external DHT infrastructure.
  • Consequence: Tracker becomes a single point of coordination (not failure, due to seeder replication); requires separate tracker process management.

• Seeder-centric model (full copies on seed nodes before peer transfer)

  • Why: Ensures reliable first-peer availability and predictable initial transfer speed; avoids cascading slowdown from incomplete peer state.
  • Consequence: Requires sufficient seed capacity and storage; not optimal for incremental or partial updates—full artifact copy always required.

• Rate-limited upload from seeders

  • Why: Prevents network saturation and ensures fair bandwidth allocation across production systems.
  • Consequence: Transfer latency scales with file size and rate limit; very large deployments (TB+) may take hours rather than minutes.

• No built-in encryption or authentication

  • Why: Assumes deployment happens on isolated trusted networks (internal data centers); simplifies protocol and reduces CPU overhead.
  • Consequence: Unsuitable for untrusted networks; torrent files and peer communications are plaintext.

• Real-time or continuous deployment; designed for batch deploy events, not streaming updates.
• Incremental/delta sync; always transfers complete artifact bundles.
• Cross-datacenter or WAN optimization; assumes LAN or high-bandwidth intra-network deployment.
• Encryption or authentication of torrent content; assumes trusted network environment.
• Support for heterogeneous architectures or binary compatibility checking; operator responsibility.
• Automatic rollback or canary deployments; orchestration responsibility of Capistrano wrapper.

Python 2 only—all code in dist/BitTornado/ uses Python 2.x syntax (print statements, etc.); fails on Python 3. Requires Capistrano v2.x (ancient Capfile syntax); incompatible with modern Capistrano 3+. Tracker is HTTP-based and centralized despite P2P claims—network partition = broken deploys. No encryption or auth in tracker protocol. Requires tgz'ing and hash-computing entire payload upfront, so no incremental/streaming deploys.

• Bencode — Murder encodes torrent metadata and tracker announces in Bencoding; understanding this format is required to modify or debug torrent creation and peer communication
• BitTorrent Tracker Protocol — Murder's tracker (dist/BitTornado/BT1/track.py) implements the HTTP announce/scrape protocol that peers use to discover seeders and each other; this is the coordination point for the entire swarm
• Piece Selection / PiecePicker — BitTorrent efficiency depends on smart piece selection (rare-piece-first, sequential vs. random strategies); Murder's PiecePicker.py determines how fast deploys complete on P2P networks
• Choking Algorithm — BitTorrent's Choker.py limits upload slots to prevent resource exhaustion; this directly impacts seeder load and deploy latency in Murder's tree-propagation model
• Magnet Links vs. Torrent Files — Murder generates classic .torrent files (murder_make_torrent.py) rather than magnet links; understanding the trade-off (file coupling vs. tracker independence) explains why Murder requires centralized tracker communication
• Tree-Propagation / Swarm Distribution — Murder explicitly uses 'tree-fashion' distribution where early peers become seeders; this is a hybrid between star (hub-and-spoke) and pure P2P, and is key to Murder's scalability claim

• rapid7/commando — SSH-based parallel deployment alternative for large fleets; solves same 'deploy to thousands of servers' problem without BitTorrent overhead
• capistrano/capistrano — Murder is a Capistrano deployment strategy; understanding core Capistrano (v2 era code) is required to use this gem
• bittorrent/bittornado — Original BitTornado library that Murder vendors; provides the peer-to-peer protocol implementation this project wraps
• moby/moby — Modern replacement for Murder's use case: Docker container distribution achieves the same scalable multi-server deployment goal via image layers instead of torrents
• hashicorp/packer — Contemporary alternative (2010s onward) for pre-building and distributing machine images across infrastructure, reducing per-deploy transfer overhead

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for BitTornado bencode serialization (dist/BitTornado/bencode.py)

The bencode module is critical for torrent file parsing in Murder's deployment process, yet there are no visible test files in the repo. BitTornado's bencode implementation needs comprehensive test coverage for edge cases (nested structures, large integers, empty strings, invalid input) to ensure reliable torrent distribution. This directly impacts deployment reliability.

• [ ] Create test/test_bencode.py with fixtures for valid/invalid bencode strings
• [ ] Add tests for encoding/decoding dictionaries, lists, integers, and byte strings
• [ ] Add tests for malformed input error handling
• [ ] Add tests for the torrent metadata parsing workflow used in murder_make_torrent.py

Add integration tests for murder Capistrano deployment strategy (lib/capistrano/recipes/deploy/strategy/murder.rb)

The murder.rb strategy file is the core orchestrator but has no visible test suite. Without tests, changes to seeder coordination, tracker startup, or BitTorrent client invocation risk breaking production deployments. Integration tests would validate the full deploy flow: tracker startup → torrent generation → seeding → client distribution.

• [ ] Create spec/capistrano_murder_strategy_spec.rb with mock Capistrano tasks
• [ ] Add tests for 'murder:start_tracker', 'murder:start_seeding', 'murder:stop_seeding' task execution
• [ ] Add tests validating murder_client.py invocation with correct torrent paths
• [ ] Add tests for error scenarios (tracker failure, missing torrent file)

Add CLI validation tests and argument parsing for dist/murder_client.py and dist/murder_tracker.py

These are entry-point scripts used on hundreds/thousands of servers, but there are no tests for argument parsing, configuration validation, or failure modes. Missing tests for invalid port numbers, missing torrent files, or network configuration could cause silent failures at scale. This is high-risk given the 'tens of thousands of servers' deployment scenario.

• [ ] Create test/test_murder_client.py testing argument parsing (torrent path, port, output directory validation)
• [ ] Create test/test_murder_tracker.py testing port binding, metainfo file validation
• [ ] Add tests for missing/invalid configuration scenarios with clear error messages
• [ ] Add tests validating that client correctly reads .torrent files generated by murder_make_torrent.py

• Port dist/BitTornado/ from Python 2 to Python 3 (systematic: update print(), string/bytes handling, urllib calls in HTTPHandler.py and zurllib.py, dict iteration in bencode.py)
• Add integration tests: create a simple 3-peer test harness in spec/ that creates a dummy torrent, starts a tracker, and verifies download consistency across peers
• Document the .torrent file format used: create docs/TORRENT_FORMAT.md explaining what murder_make_torrent.py generates and how it differs from standard BitTorrent (if at all)

• Critical · Unmaintained Project with Known Vulnerabilities — README.md, entire codebase. The project is explicitly marked as no longer maintained (as stated in README). This means security patches and updates are not being applied. The BitTornado library and all dependencies are likely outdated with known CVEs. Fix: Do not use this project in production. Consider migrating to actively maintained alternatives for file distribution or implement a modern, maintained BitTorrent client.
• High · Insecure BitTornado Library Usage — dist/BitTornado/ directory and all imported modules. The project bundles BitTornado (dist/BitTornado/) which is an old, unmaintained BitTorrent library. BitTornado has known security vulnerabilities including potential remote code execution and man-in-the-middle attack vectors due to lack of modern encryption standards. Fix: Replace with a modern, maintained BitTorrent library. Audit the bundled BitTornado version for known CVEs.
• High · No HTTPS/TLS Configuration Visible — dist/murder_tracker.py, dist/murder_client.py, dist/BitTornado/HTTPHandler.py, dist/BitTornado/RawServer.py. The tracker (dist/murder_tracker.py) and client (dist/murder_client.py) components do not appear to implement HTTPS/TLS encryption for communication. BitTorrent traffic and tracker communication may be transmitted in plain text. Fix: Implement mandatory HTTPS/TLS for all communications. Use certificate pinning for tracker communication. Encrypt all metadata and peer discovery traffic.
• High · Potential Arbitrary File Distribution — lib/murder.rb, lib/capistrano/recipes/deploy/strategy/murder.rb, dist/murder_make_torrent.py. The murder.rb and deployment strategy (lib/capistrano/recipes/deploy/strategy/murder.rb) allow distributing files via BitTorrent without apparent integrity verification or signature validation mechanisms visible in the codebase. Fix: Implement cryptographic signature verification for all distributed files. Use checksums (SHA-256+) for integrity validation. Verify torrent metadata before distribution.
• High · No Authentication/Authorization Visible — dist/murder_tracker.py, dist/BitTornado/BT1/track.py. The tracker and client components do not appear to implement authentication or authorization checks. Any peer could potentially join the swarm and access distributed files. Fix: Implement peer authentication using tokens or certificates. Restrict tracker access to authorized hosts only. Use firewall rules to limit peer discovery.
• Medium · Potential Information Disclosure via Tracker — dist/murder_tracker.py, dist/BitTornado/BT1/track.py. BitTorrent trackers typically expose peer information (IPs, ports, statistics). The murder_tracker.py may expose sensitive infrastructure details about deployment targets. Fix: Implement access controls on tracker endpoints. Log and monitor tracker access. Consider running trackers on isolated, internal networks only.
• Medium · Hardcoded Configuration Paths — dist/BitTornado/ConfigDir.py, dist/BitTornado/ConfigReader.py, dist/BitTornado/inifile.py. References to ConfigDir.py and configuration file handling suggest potential hardcoded paths that may not work securely across different environments or may expose sensitive information. Fix: Use environment variables for all configuration paths. Implement secure file permissions (0600) for configuration files. Validate all file paths.
• Medium · Deprecated Python 2 Code — All .py files throughout the project. The codebase appears to be written for Python 2 (based on file names and structure). Python 2 is deprecated and no longer receives security patches. Fix: Modernize to Python 3. If upgrading is not possible, run only in isolated environments with restricted network access.
• Medium · Lack of Input Validation — dist/BitT. Files like parseargs.py, parsedir.py, and bencode.py handle parsing of user input and bencoded data without clear validation framework visible. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.