FocusFlow v2.1

Crash-Safe Deep Work Discipline Engine, Dual-Stack Atomic Hosts Blocker & Catppuccin Mocha Desktop HUD.
Engineered in Go and Python (zero external runtime dependencies) for developers, students, and operators who demand uncompromising focus without network corruption.

---

Why FocusFlow v2.1?

Conventional website blockers and browser extensions fail under real-world conditions:

1. Trivial Extension Bypass: Browser extensions can be disabled in seconds or bypassed via private windows and secondary browsers.
2. IPv6 & DNS-over-HTTPS (DoH) Leaks: Single-stack 127.0.0.1 blockers leak traffic over IPv6 (AAAA) records and encrypted browser DoH resolvers (cloudflare-dns.com, dns.google, dns.quad9.net, dns.nextdns.io).
3. Hosts File & ACL Corruption: Naive scripts overwrite C:\Windows\System32\drivers\etc\hosts in place without write-ahead journaling or Windows DACL preservation—breaking DNS resolution after power loss, crashes, or reboots.
4. Heavy Runtime Dependencies: Typical desktop wrappers pull hundreds of megabytes of packages just to enumerate processes.

FocusFlow v2.1 solves these failure modes at the operating-system boundary:

• Unified Go CLI + Zero-Dependency Python HUD: cmd/focusflow (Go) and FocusFlowGUI.py + focusflow_core/ (Python stdlib + Win32 ctypes) share the exact same state directory, config.json, sessions.json, hosts.focusflow.journal.json, and managed block markers.
• Write-Ahead SHA-256 Rollback Journal & Auto-Recovery: Strips any prior managed blocks before computing a clean baseline SHA-256 backup, persists hosts.focusflow.journal.json before touching hosts, preserves Windows DACLs via ReplaceFileW (NetworkService / Users read permissions remain intact), and automatically recovers orphaned crash/reboot states on startup (RecoverIfOrphaned).
• Dual-Stack IPv4 + IPv6 Sinkhole & Expanded Anti-DoH: Blocks both 0.0.0.0 and :: (including www. subdomains) alongside major DoH bypass endpoints, with mid-session tamper verification and non-blocking DNS cache flushing.
• Hardened Native Process Supervisor: Uses Win32 CreateToolhelp32Snapshot (Process32FirstW/Process32NextW) on Windows (zero psutil required) and direct /proc inspection on Linux (resolving 15-byte TASK_COMM_LEN truncation without spawning ps every second), guarded by a strict critical system/host process denylist.
• High-Friction Strict Mode & Genuine Telemetry: Features a non-pasteable 16-character alphanumeric Friction Challenge, time.monotonic() zero-drift countdowns, Per-Monitor v2 High-DPI Catppuccin Mocha HUD, and real streak/completion analytics exported to JSON, CSV, or PNG.

---

Architecture

+----------------------------------------------------------------------+
|       FocusFlow v2.1 CLI (Go)    <==>    Desktop HUD (Python/Tk)     |
+-----------------------------------+----------------------------------+
                                    |
          Shared State (%APPDATA%\FocusFlow or $FOCUSFLOW_HOME)
     [config.json | sessions.json | hosts.focusflow.journal.json]
                                    |
        +---------------------------+---------------------------+
        |                           |                           |
        v                           v                           v
+------------------+      +-------------------+      +--------------------+
| Dual-Stack Hosts |      | Native Supervisor |      | Real-Time Metrics  |
| SHA-256 + Journal|      | Win32 / Linux proc|      | Streak, JSON & CSV |
+--------+---------+      +---------+---------+      +--------------------+
         |                          |
         v                          v
 [System hosts File]       [Blocked Processes]
 (ACL-Safe Swap)           (Denylist-Guarded)

---

Quick Start

1. Desktop HUD (Python 3.10+, Zero Required Packages)

Launch Launch_FocusFlow_GUI.bat on Windows or run directly:

python FocusFlowGUI.py

To launch directly with Administrator elevation prompt on Windows:

python FocusFlowGUI.py --elevate

(Optional) For PNG chart card rendering, install Pillow: pip install .[reports].

2. Native Standalone CLI (Go 1.23+)

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w -X main.Version=2.1.0" -o focusflow ./cmd/focusflow

---

CLI Reference

Privilege Model: Modifying the system hosts file requires Administrator (Windows) or root (Linux/macOS) privileges. When run unprivileged, FocusFlow honestly reports PROCESS-ONLY [UNPRIVILEGED] rather than claiming hosts is locked. Pass --elevate to request privilege elevation.

# Launch interactive terminal dashboard
focusflow menu

# Start a 50-minute Developer sprint (elevating via UAC/sudo if needed)
focusflow start --profile dev --minutes 50 --elevate

# Start a 25-minute Study sprint or Hardcore Aegis sprint
focusflow start --profile study --minutes 25
focusflow start --profile hardcore --strict hardcore

# Inspect shield capability, hosts status, and active journal (human or JSON)
focusflow status
focusflow status --json

# Manage custom RFC-1123 domains and denylist-checked executables
focusflow list --json
focusflow add site reddit.com
focusflow add app steam.exe
focusflow remove site reddit.com

# View genuine focus hours, completion rate, active streak, and 7-day ASCII chart
focusflow stats --days 7
focusflow stats --days 7 --json

# Export telemetry to JSON or CSV
focusflow export --format json --out focus_report.json
focusflow export --format csv --out focus_sessions.csv

# Run system diagnostics or recover orphaned crash/reboot state
focusflow doctor
focusflow doctor --json
focusflow recover --elevate

# Immediate rollback & DNS cache flush
focusflow stop
focusflow flush

---

Built-in Profiles

Profile	Default Interval	Target Workflow	Active Protections
study	25m / 5m	Academic & Exam Prep	Blocks video, social, streaming, chat clients, and game launchers
dev	50m / 10m	Software Engineering	Keeps GitHub, StackOverflow & technical docs open; blocks social & gaming
hardcore	25m / 5m	Aegis Lockdown	Study blocklist + strict Friction Challenge + Anti-Cheat task-manager suppression (taskmgr.exe, SystemInformer.exe, processhacker.exe)

---

Crash Safety & System Integrity

• Clean Baseline Guarantee: FocusFlow strips any current or legacy managed blocks before hashing and writing hosts.focusflow.bak, ensuring a contaminated hosts file is never backed up.
• Write-Ahead Rollback Journal: hosts.focusflow.journal.json records original_sha256, backup_path, hosts_path, session_id, pid, started_at, expected_end_at, and profile prior to any hosts write.
• Automatic Startup Recovery: On every CLI or GUI startup, RecoverIfOrphaned checks whether a prior session crashed, rebooted, or expired; verifies .bak against original_sha256 (falling back to deterministic marker stripping if .bak was altered); restores hosts while preserving OS permissions/ACLs; and marks the interrupted session completed: false in sessions.json.
• Critical Process Denylist: Kernel, session, shell, and host binaries (csrss.exe, lsass.exe, svchost.exe, explorer.exe, dwm.exe, winlogon.exe, python.exe, pythonw.exe, focusflow.exe, wt.exe, PIDs 0/4/self/parent) can never be added or terminated.

---

Testing

All Go and Python tests run hermetically inside temporary FOCUSFLOW_HOME and FOCUSFLOW_HOSTS_PATH sandboxes—never touching your real %APPDATA% or system hosts file:

go vet ./...
go test -v ./...
python -m pytest -v

---

License

Released under the MIT License by aloneangel45.