v0.16.0: The Co-Pilot Update, Configuration Overhaul & Protostar Spin-off

Summary

This release completes Phase 1 of the roadmap, transitioning Git Pulsar from a strict background daemon into an interactive co-pilot. It also introduces major upgrades to the configuration engine, fundamentally redesigns our testing architecture for distributed state capture, and cleanly separates environment scaffolding into a dedicated tool.

Interactive State Negotiations

• Smart Restore: git pulsar restore now utilizes an interactive state machine when encountering dirty files in the working directory, allowing you to inspect diffs or cancel before applying destructive overwrites.
• Pre-Flight Finalize Checklist: git pulsar finalize intercepts the octopus squash execution pipeline to aggregate diff statistics (diff --shortstat) across all remote machine streams, rendering a deterministic summary table before mutating the primary branch history.

Configuration Engine Overhaul

• Human-Readable Parameters: The configuration parser now accepts human-readable strings for time intervals (e.g., "10m", "1hr") and resource limits (e.g., "100mb", "1gb") with robust fallback logic.
• Schema Introspection: Running git pulsar config --list directly outputs a comprehensive table detailing all available configuration sections, keys, types, and defaults.
• Strict Boundary Enforcement: Added a manage_gitignore boolean to FilesConfig, giving users the ability to explicitly block the daemon from appending state data to project .gitignore files.

Interface & CLI Refinements

• Signal-to-Noise Reduction: A custom argparse.HelpFormatter subclass now intercepts CLI rendering to suppress default container artifacts and cluster subcommands into logical groups (Backup Management, Repository Control, etc.).
• Dynamic Metadata: Introduced a --version flag that dynamically resolves package data via importlib.metadata.
• Documentation Compliance: Enforced Google-style docstrings globally via ruff pydocstyle rules and bumped pre-commit hooks.

Separation of Concerns: Protostar

• Scaffolding Extraction: The --env global flag and its associated environment bootstrapping logic (uv, direnv, IDE settings) have been entirely excised from the Pulsar codebase.
• Migration: Project scaffolding is fundamentally distinct from version control. This logic has been expanded and relocated to a vertically integrated CLI tool: Protostar.

Diagnostics & CI/CD Infrastructure

• Three-Tiered Sandbox Testing: Deployed a highly isolated testing architecture. Tier 2 simulates distributed node synchronization via localized bare remotes, while Tier 3 automates ephemeral Ubuntu VMs (Canonical Multipass) to validate OS-level daemon integrations (systemd, sysfs) without contaminating the host filesystem.
• Telemetry Integration: Integrated Codecov into the GitHub Actions pipeline, establishing a defined baseline with strict degradation thresholds for automated PR analysis.
• Native Dependency Syncing: Rewrote the CD pipeline to utilize PyPI source distributions (SDist) and Homebrew's native brew update-python-resources, ensuring deterministic synchronization of the dependency graph without relying on regex matchers.

Release v0.15.0: Active Observability & Smart Identity

Summary

This release fundamentally shifts Git Pulsar from a reactive utility into a proactive, state-aware daemon. By decoupling diagnostic polling from the presentation layer and implementing atomic state I/O, v0.15.0 reduces noise, minimizes alert fatigue, and intercepts local entropy before it pollutes your working directory.

Here is the breakdown of the major changes.

---

📡 Roaming Radar & Zero-Latency Telemetry

Drift detection is no longer a passive CLI poll; it is an asynchronous background event.

• Proactive Interruption: The daemon now monitors for upstream session divergence and triggers cross-platform OS notifications (SYSTEM.notify) to warn you before you introduce conflicting local changes.
• Atomic State Caching: To prevent data collisions between the background daemon and foreground CLI, state caching now uses atomic pointer swaps (os.replace) and explicit hardware syncs (os.fsync).
• Zero-Latency Dashboard: The git pulsar status command has been upgraded. It instantly surfaces power telemetry (e.g., Eco-Mode throttling), pipeline blockers, and cached drift warnings without hanging on live network calls.

🧬 Smart Identity & Collision Avoidance

We've engineered a deterministic solution to the "identical hostname" problem (e.g., multiple machines defaulting to macbook-pro) overwriting backup DAGs.

• Composite Slugs: References now use a {human_name}--{short_id} format, fusing the immutability of a hardware UUID with human-readable tracking.
• Remote Collision Detection: During repository initialization, Pulsar executes a lightweight git ls-remote check to scan the remote namespace and explicitly warn you if your chosen identity is already broadcasting.

🩺 State-Aware Diagnostics (Active Doctor)

git pulsar doctor has been overhauled from a static log parser into a two-stage interactive resolution engine.

• State vs. Event Correlation: It now evaluates your actual repository topology before parsing logs. If the system state is healthy, transient errors within the lookback window are mathematically suppressed to prevent alert fatigue.
• Interactive Auto-Fixes: The CLI now queues up Tier 1 resolutions, prompting you ([y/N]) to safely clean up ghost registry entries, purge stale .git/index.lock files, or enable systemd user lingering.
• Pre-Flight Scans: Proactively checks .git/hooks/ for strict executable scripts that lack bypass logic, providing the exact bash snippets needed to prevent background hangs.

⚙️ Pipeline Integrity & Optimization

• The "Neutrino Detector": Suppressed exceptions—such as network timeouts, strict file permissions, or malformed git objects—are now piped directly into the logging stream. This preserves critical forensic stack traces without disrupting the TUI.
• Targeted Syncing: git pulsar sync now restricts its fetch operation solely to the target branch history instead of pulling the entire namespace, drastically reducing network I/O.
• Strict Execution Baselines: The environment is now strictly pinned to Python 3.12+, enforced by aggressive Ruff and Mypy rulesets to guarantee forward-compatibility and prevent syntax crashes on headless Linux deployments.
• Global Config Caching: Config.load() now caches in memory to eliminate redundant disk reads during the high-frequency daemon loop.

v0.14.0: The "Energy Saver" Update

This release introduces a fundamental architectural shift: Decoupled Backup Cycles.

Previously, git-pulsar treated "snapshotting" and "pushing" as a single atomic operation. In v0.14.0, these are separate loops. You can now capture local state frequently (e.g., every 5 minutes) to protect against crashes, while only syncing to the remote occasionally (e.g., every hour) to save battery and bandwidth.

🚀 Key Features

Decoupled Daemon Cycles

• Commit Interval: Controls how often a shadow commit is created locally.
• Push Interval: Controls how often those commits are pushed to the remote.
• Benefit: High-frequency protection with low-frequency network usage.

Cascading Configuration

Settings are now resolved in a strict hierarchy (highest priority wins):

1. Local: pulsar.toml OR pyproject.toml (in the repository root).
2. Global: ~/.config/git-pulsar/config.toml.
3. Defaults: Hardcoded safety values.

> Note: List options (like ignore patterns) in local configuration are appended to the global list, ensuring you don't accidentally un-ignore system files.

Presets

We added configuration presets to simplify tuning. You can now set preset in your config instead of manually calculating seconds:

• paranoid (5m commit / 5m push)
• aggressive (10m commit / 10m push)
• balanced (15m commit / 1h push) [Default]
• lazy (1h commit / 4h push)

New Commands

• git pulsar config: Opens the global configuration file in your system's default editor (respects $EDITOR or falls back to sensible defaults like VS Code/Nano).
• git pulsar status: Updated to show separate timestamps for Last Commit and Last Push.

🐛 Improvements & Fixes

• Dynamic Limits: The large_file_threshold check now correctly respects repository-specific config overrides.
• Test Stability: Fixed non-deterministic test failures in CI environments by properly mocking system load checks.
• Documentation: Updated architecture diagrams and README to reflect the new config hierarchy.

v0.13.0: The "Polished & Professional" Release

🚀 Summary

Release v0.13.0 marks a significant milestone in maturity for Git Pulsar. This update focuses heavily on User Experience, System Stability, and Code Health.

We have overhauled the CLI to use professional, text-based labels (removing "emoji clutter"), introduced animated spinners for network operations, and fixed a critical issue regarding machine identity drift on roaming networks. Under the hood, the entire codebase has been standardized with Google-style docstrings to support better tooling and developer onboarding.

---

✨ Key Features & Changes

🎨 User Experience & Visuals

• Interactive Polish: Commands like now, sync, finalize, and prune now use animated rich spinners instead of spamming raw Git logs.
• Structured Output: Replaced "wall of text" information with formatted rich.panel.Panel elements (e.g., when viewing the latest session in sync).
• Professional Styling: Transformed the UI from an "emoji-heavy" aesthetic to a standard text-based label system (e.g., [ERROR], [SUCCESS]) for better clarity and terminal compatibility.
• Dark/Light Mode Demos: README.md now features dynamic, theme-aware GIFs generated via VHS.

🏥 Observability & Diagnostics

• Smart Status: git pulsar status now correctly distinguishes between Active (Idle) (daemon waiting) and Stopped (service disabled).
• Deep Doctor: git pulsar doctor has been upgraded to:
  • Scan the last 24h of logs for ERROR patterns.
  • Detect "Stalled" repositories (changes pending > 2 hours with no backup).
  • Validate registry hygiene.
• Log Context: git pulsar log now outputs the preceding 1000 lines before tailing, providing immediate context for debugging.

🆔 Critical Fix: Machine Identity

• Hardware-Based Identity: Fixed an issue where backups would fragment when connecting to different networks (e.g., University DHCP).
  • macOS: Now uses IOPlatformUUID.
  • Linux: Now uses /etc/machine-id or /var/lib/dbus/machine-id.
• Legacy Fallback: socket.gethostname() is now only used as a last resort.

🧹 Code Health & Refactoring

• Standardized Docstrings: The entire codebase (src/ and tests/) has been updated to use Google-style docstrings. This ensures accurate auto-generated documentation and clarifies intent for all modules, classes, and functions.
• Rich Console Standardization: Refactored core modules (ops, daemon, service) to exclusively use a shared rich.console instance, resolving thread-safety issues with mixed print() calls.

---

📦 Changes by Component

• Daemon: Silenced raw push logs, added spinners, and enforced resource limits.
• CLI: Standardized argument parsing, status reporting, and error handling docstrings.
• System: Implemented robust strategies for battery checks and machine ID resolution.
• Docs: Updated README.md command references and added CONTRIBUTING.md guidelines.

🧪 Testing

• Added tests/test_system.py to verify platform-specific identity logic.
• Standardized documentation for all test cases to explain fixtures and verification steps clearly.

v0.12.1: Enforce Homebrew Service on macOS

⚠️ Breaking Changes

• macOS Service Management: Removed internal install-service logic for macOS. The CLI now strictly enforces brew services usage to prevent daemon conflicts.
  • Migration: Run git pulsar uninstall-service, then brew services start git-pulsar.

Changes

• Refactor: doctor command now recognizes the homebrew.mxcl.git-pulsar label as a valid active state.
• UX: Added rich styled error messages when attempting to use OS-mismatched service commands.
• Docs: Updated README to explicitly decouple macOS (Homebrew) and Linux (Systemd) installation instructions.

v0.12.0: The "Polished & Paranoid" Update

Summary

v0.12.0 marks a significant maturity milestone for Git Pulsar. This release focuses on elevating the user experience from "hacky script" to "professional tool" through a complete CLI visual overhaul, while simultaneously hardening the core backup logic to be truly invisible and self-maintaining.

🎨 New Feature: Modern CLI Experience

This release introduces the Rich library to provide a responsive, semantic, and visually structured terminal interface.

• Dashboard Status: The git pulsar status command now uses Panels to visually separate Daemon health from Repository state, replacing the old ad-hoc print statements.
• Dynamic Tables: git pulsar list now renders a responsive table that automatically handles long paths and terminal resizing.
• Visual Feedback: Blocking operations (installation, pruning, finalizing) are now wrapped in animated progress spinners.
• Semantic Coloring: Status indicators rely on standard ANSI color codes (Green/Red/Yellow) rather than ambiguous emojis.

🛠 Core: Invisible Backups (Namespace Refactor)

The backup engine has been refactored to eliminate "zombie branches."

• Ref-Based Storage: Backups no longer rely on a local wip/pulsar branch. Instead, they write directly to a Git reference namespace (refs/heads/wip/pulsar/...).
• Zero Interference: This ensures the daemon never switches your working directory or creates "detached HEAD" states, keeping your git status clean and your workflow uninterrupted.
• Dynamic Resolution: Backup references are now constructed dynamically based on the Machine ID, allowing for safer synchronization across multiple devices.

🤖 Automations: "Set and Forget" Maintenance

• Weekly Auto-Prune: The daemon now includes a maintenance scheduler. Every 7 days, it automatically runs garbage collection on all tracked repositories to enforce the 30-day retention policy. You no longer need to manually run git pulsar prune.

🚑 Stability & Observability

• PID File Management: Status checks now rely on a robust daemon.pid file and process signaling (os.kill) rather than brittle parsing of systemctl stdout.
• Crash Forensics: The daemon now logs full stack traces (logger.exception) instead of silent errors, and log rotation has been increased to prevent history loss during crash loops.
• Config Hardening: Malformed config.toml files now cause an immediate, descriptive exit rather than silently loading defaults.

🐛 Bug Fixes

• Test Suite Isolation: Fixed a critical issue where tests/test_cli.py leaked the Current Working Directory (CWD) state, inadvertently corrupting the user's actual ~/.local/state/git-pulsar/registry during development.
• Ghost Entries: Fixed an issue where the daemon would alert on "Missing Repos" that were actually artifacts of the test suite leak.
• Context Safety: Implemented a @temporary_index context manager to ensure the git index is always cleaned up, even if a backup operation crashes.

v0.11.0: The Control Plane Update

This release shifts Git Pulsar from being purely "invisible" to being "invisible but controllable." It introduces a suite of active commands to manage your backup history, clean up your registry, and explicitly sync work between machines.

🚀 New Features

• git pulsar sync: The "teleport" button. It scans your backup history across all machines (Laptop, Desktop, etc.) and fast-forwards your current directory to the absolute latest session found.
• git pulsar doctor: A self-healing diagnostic tool. It scrubs your registry of deleted repositories, checks if the daemon is alive, and verifies SSH connectivity to your remote.
• git pulsar prune: Keeps your .git directory lean. It scans for shadow commits older than 30 days and garbage collects them to save disk space.
• git pulsar list: Now displays a live status dashboard, showing which repos are Active 🟢, Paused ⏸️, or Missing 🔴.

🛠 Utilities

• git pulsar remove: Stop tracking a repository without uninstalling the daemon.
• git pulsar ignore <pattern>: Quickly add patterns to .gitignore (and untrack them if they were accidentally committed).

📝 Documentation

We have updated the documentation to recommend the space-separated syntax:

• Old: git-pulsar status
• New: git pulsar status (feels more native!)

v0.10.2: macOS Service Plist Bug Fix

🐛 Bug Fixes

• macOS Service Installer: Fixed a regression in install-service where a malformed plist (duplicate XML key) caused launchctl to fail with an Input/output error. The background daemon now installs correctly on macOS.

🛡️ Reliability

• Config Validation: Added a plutil -lint pre-check during service installation on macOS. Invalid service definitions will now trigger a clear syntax error immediately rather than failing silently or opaquely during the load phase.

v0.10.1: Bug Fixes

Summary

This release addresses a critical packaging regression where the src directory was strictly interpreted during installation, leading to immediate runtime failures for end users despite passing in CI.

Critical Fixes

• Refactored Source Layout: We have migrated the project structure to a strict src-layout. Implementation files have been moved from the root of src/ into a dedicated git_pulsar package directory. This resolves the ModuleNotFoundError: No module named 'src' error seen when running the installed CLI.
• Entry Point Resolution: Updated pyproject.toml scripts to point to the persistent git_pulsar.cli:main entry point rather than the ephemeral src.cli:main.

Build & CI

• Test Suite Alignment: Updated all test imports to target the installed package context (git_pulsar) rather than the local source tree. This ensures our test suite accurately reflects the installed behavior of the package.

v0.10.0: The Ghost in the Machine 👻

Summary

This release introduces "Shadow Commits" (invisible backups) and "Roaming Profiles" (multi-machine sync).

Git Pulsar now operates completely in the background without touching your index or staging area, and supports seamless handoff between devices.

🔦 Highlights

👻 Ghost Mode (Shadow Commits)

Pulsar now uses low-level git plumbing (write-tree, commit-tree) to snapshot your work.

• Zero Interference: You can now stage files (git add -p) or run interactive rebases while Pulsar runs in the background. It will never lock your index or mess up your staging area.
• Isolated State: Backups are strictly read-only snapshots of your working directory.

🌍 Roaming Profiles

Backups are now namespaced by Machine ID (e.g., refs/heads/wip/pulsar/macbook/...).

• Sync Command: New git-pulsar sync command. It scans the network for your latest work on any machine and fast-forwards your current directory to match it.
• Identity: On first run, you will be asked to name your machine (e.g., "lab-desktop", "home-laptop").

🐙 Grand Unification

The finalize command has been upgraded to perform an Octopus Merge.

• When you finish an assignment, Pulsar fetches the backup history from all your registered machines.
• It squash-merges them all into main simultaneously, preserving the timeline of your work across every device you used.

---

⚠️ Upgrade Notes

1. Breaking Ref Change:

   • Old backups stored in the local wip/pulsar branch are deprecated.
   • New backups are stored in refs/heads/wip/pulsar/<machine-id>/....
   • Action: None required. Old backups remain accessible but will not be appended to.

2. First Run Setup:

   • After updating, the first time you run git-pulsar (or when the daemon wakes up), it will create a ~/.config/git-pulsar/machine_id file. You may be prompted to confirm the machine name if running interactively.

---

📜 Changelog

• feat!: Implement shadow commits using write-tree (removes git add dependency).
• feat: Add git-pulsar sync for cross-device session restoration.
• feat: Implement persistent machine_id configuration.
• feat: Add Octopus Merge strategy to finalize for aggregating multi-host history.
• fix: Namespace refs to prevent history divergence/rejects on multiple machines.
• docs: Complete rewrite of README to reflect v0.10.0 architecture.

Full Changelog: v0.9.1...v0.10.0