{
  "report_info": {
    "version": "9.0.1",
    "generated_at": "2026-07-21T01:54:14Z",
    "binary_name": "kodachi-session-helper"
  },
  "binary": {
    "name": "kodachi-session-helper",
    "path": "/opt/kodachi/dashboard/hooks/kodachi-session-helper",
    "timestamp": "2026-07-21T01:54:14Z",
    "file_info": {
      "size": 2458368,
      "sha256": "5492e7eea1fecdcb56b2a0da7e0fa45b660dd433b933ac0c063b79636c197ce5"
    },
    "flag_n": {
      "command": "info",
      "data": {
        "author": "Warith Al Maawali",
        "copyright": "© 2026 Kodachi OS",
        "description": "Global emergency keyboard shortcut daemon for Kodachi OS",
        "features": [
          "X11 key grab registration with collision detection",
          "Raw /dev/input hardware corroboration (anti-XTEST)",
          "Hold-to-trigger with auto-repeat rejection (1500ms default)",
          "Local session token authentication (no network required)",
          "Delayed lockdown with cancel capability",
          "Unix socket for dashboard status queries",
          "Atomic config reload via SIGHUP",
          "LUKS device wipe + dashboard nuke combined actions",
          "X11 disconnect detection with auto-reconnect",
          "Memory protection via mlock and PR_SET_DUMPABLE"
        ],
        "license": "Proprietary",
        "name": "kodachi-session-helper",
        "securityFeatures": {
          "authentication": "Local 256-bit session token (no network dependency)",
          "encryption": "SHA-256 token digest; memory locked and zeroized on exit",
          "inputValidation": "All configuration validated; key grabs verified against collisions",
          "rateLimiting": "Hold-to-trigger with cooldown prevents accidental re-trigger"
        },
        "systemRequirements": {
          "dependencies": [
            "X11 display server",
            "health-control binary",
            "/dev/input access (input group)"
          ],
          "os": "Linux (Kodachi OS / Debian-based with X11)",
          "privileges": "User session (non-root); 'input' group for evdev"
        },
        "version": "9.8.4 (build 320)",
        "website": "https://digi77.com"
      },
      "errors": [],
      "metadata": {
        "executionTime": 1,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:14.140775165Z",
      "version": "9.8.4 (build 320)",
      "warnings": []
    },
    "flag_v": {
      "command": "version",
      "data": {
        "buildDate": "REDACTED-BUILD-TIME",
        "gitCommit": "unknown",
        "name": "kodachi-session-helper",
        "rustVersion": "1.82.0",
        "version": "9.8.4 (build 320)"
      },
      "errors": [],
      "metadata": {
        "executionTime": 1,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:14.285460008Z",
      "version": "9.8.4 (build 320)",
      "warnings": []
    },
    "flag_h": {
      "command": "help",
      "data": {
        "commandCategories": [
          {
            "category": "Daemon Control",
            "commands": [
              {
                "description": "Start the emergency shortcut daemon (foreground, runs until signalled)",
                "examples": [
                  "kodachi-session-helper daemon",
                  "kodachi-session-helper daemon --json"
                ],
                "name": "daemon",
                "options": [
                  {
                    "description": "Print help information",
                    "flag": "-h, --help"
                  },
                  {
                    "description": "Print version information",
                    "flag": "-v, --version"
                  },
                  {
                    "description": "Display detailed information",
                    "flag": "-n, --info"
                  },
                  {
                    "description": "Show usage examples",
                    "flag": "-e, --examples"
                  },
                  {
                    "description": "Output in JSON format",
                    "flag": "--json"
                  },
                  {
                    "description": "Pretty-print JSON output",
                    "flag": "--json-pretty"
                  },
                  {
                    "description": "Enhanced JSON output (like jq)",
                    "flag": "--json-human"
                  },
                  {
                    "description": "Enable verbose output",
                    "flag": "--verbose"
                  },
                  {
                    "description": "Suppress non-essential output",
                    "flag": "--quiet"
                  }
                ],
                "requires_sudo": false,
                "usage": "kodachi-session-helper daemon [OPTIONS]"
              },
              {
                "description": "Query the running daemon over its Unix socket",
                "examples": [
                  "kodachi-session-helper status",
                  "kodachi-session-helper status --json"
                ],
                "name": "status",
                "options": [
                  {
                    "description": "Print help information",
                    "flag": "-h, --help"
                  },
                  {
                    "description": "Print version information",
                    "flag": "-v, --version"
                  },
                  {
                    "description": "Display detailed information",
                    "flag": "-n, --info"
                  },
                  {
                    "description": "Show usage examples",
                    "flag": "-e, --examples"
                  },
                  {
                    "description": "Output in JSON format",
                    "flag": "--json"
                  },
                  {
                    "description": "Pretty-print JSON output",
                    "flag": "--json-pretty"
                  },
                  {
                    "description": "Enhanced JSON output (like jq)",
                    "flag": "--json-human"
                  },
                  {
                    "description": "Enable verbose output",
                    "flag": "--verbose"
                  },
                  {
                    "description": "Suppress non-essential output",
                    "flag": "--quiet"
                  }
                ],
                "requires_sudo": false,
                "usage": "kodachi-session-helper status [OPTIONS]"
              },
              {
                "description": "Send SIGHUP to the running daemon to reload its configuration",
                "examples": [
                  "kodachi-session-helper reload",
                  "kodachi-session-helper reload --json"
                ],
                "name": "reload",
                "options": [
                  {
                    "description": "Print help information",
                    "flag": "-h, --help"
                  },
                  {
                    "description": "Print version information",
                    "flag": "-v, --version"
                  },
                  {
                    "description": "Display detailed information",
                    "flag": "-n, --info"
                  },
                  {
                    "description": "Show usage examples",
                    "flag": "-e, --examples"
                  },
                  {
                    "description": "Output in JSON format",
                    "flag": "--json"
                  },
                  {
                    "description": "Pretty-print JSON output",
                    "flag": "--json-pretty"
                  },
                  {
                    "description": "Enhanced JSON output (like jq)",
                    "flag": "--json-human"
                  },
                  {
                    "description": "Enable verbose output",
                    "flag": "--verbose"
                  },
                  {
                    "description": "Suppress non-essential output",
                    "flag": "--quiet"
                  }
                ],
                "requires_sudo": false,
                "usage": "kodachi-session-helper reload [OPTIONS]"
              }
            ]
          }
        ],
        "description": "Global emergency keyboard shortcut daemon for Kodachi OS",
        "environmentVariables": [
          {
            "default": ":0",
            "description": "X11 display to connect to",
            "name": "DISPLAY",
            "values": ":0, :1, etc."
          },
          {
            "default": "/run/user/<uid>",
            "description": "Runtime directory for the status socket, the config file and the session-token digest. Falls back to <execution folder>/tmp when it is unset or not writable",
            "name": "XDG_RUNTIME_DIR",
            "values": "Directory path"
          }
        ],
        "exitCodes": {
          "0": "Success",
          "1": "General error (includes: daemon not running for status/reload)",
          "2": "Invalid arguments",
          "3": "Permission denied (running as root)",
          "4": "X11 not available",
          "5": "Wayland session (unsupported)"
        },
        "globalOptions": [
          {
            "description": "Print help information",
            "flag": "-h, --help"
          },
          {
            "description": "Print version information",
            "flag": "-v, --version"
          },
          {
            "description": "Display detailed information",
            "flag": "-n, --info"
          },
          {
            "description": "Show usage examples",
            "flag": "-e, --examples"
          },
          {
            "description": "Output in JSON format",
            "flag": "--json"
          },
          {
            "description": "Pretty-print JSON output",
            "flag": "--json-pretty"
          },
          {
            "description": "Enhanced JSON output (like jq)",
            "flag": "--json-human"
          },
          {
            "description": "Enable verbose output",
            "flag": "--verbose"
          },
          {
            "description": "Suppress non-essential output",
            "flag": "--quiet"
          }
        ],
        "name": "kodachi-session-helper",
        "usage": "kodachi-session-helper [OPTIONS] [COMMAND]"
      },
      "errors": [],
      "metadata": {
        "executionTime": 1,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:14.418778670Z",
      "version": "9.8.4 (build 320)",
      "warnings": []
    },
    "flag_e": {
      "command": "examples",
      "data": {
        "categories": [
          {
            "description": "Start the emergency shortcut daemon in your desktop session, then confirm the shortcuts armed.",
            "examples": [
              {
                "command": "kodachi-session-helper daemon",
                "description": "Start the emergency shortcut daemon in the foreground",
                "expectedOutput": "Preflight checks pass, the X11 key grabs register, the status socket opens, and the daemon enters its event loop",
                "notes": "Run it as your desktop user, NOT as root (root exits with code 3). It needs an X11 session (a Wayland session exits with code 5) and membership of the 'input' group for raw /dev/input corroboration."
              },
              {
                "command": "kodachi-session-helper status",
                "description": "Confirm the daemon is up and see which shortcuts are armed",
                "expectedOutput": "Running state, PID, armed shortcut list, evdev state and any lockdown countdown",
                "notes": "Exits non-zero when no daemon is running, so a script can use it as a liveness probe."
              },
              {
                "command": "kodachi-session-helper status --json",
                "description": "The same check, machine readable (this is what the dashboard calls)",
                "expectedOutput": "JSON envelope with the running flag, the armed shortcuts and the daemon capabilities"
              }
            ],
            "id": "0_quick_start",
            "title": "Quick Start"
          },
          {
            "description": "What the daemon needs from the session, what it opens, and how it behaves when one is already running.",
            "examples": [
              {
                "command": "kodachi-session-helper daemon --json",
                "description": "Start the daemon with machine-readable output",
                "expectedOutput": "JSON envelope. If a daemon is already running it reports already_running with that daemon's PID and socket path instead of starting a second one",
                "notes": "The daemon is single-instance: it detects a live socket and refuses to duplicate itself."
              },
              {
                "command": "DISPLAY=:0 kodachi-session-helper daemon",
                "description": "Start the daemon from an autostart script or user unit that does not inherit DISPLAY",
                "expectedOutput": "Daemon connects to the named X11 display and registers its grabs there",
                "notes": "DISPLAY defaults to :0. XDG_RUNTIME_DIR decides where the socket, the config file and the session-token digest are written; when it is unset or not writable the daemon falls back to <execution folder>/tmp."
              }
            ],
            "id": "1_running_the_daemon",
            "title": "Running the Daemon"
          },
          {
            "description": "Status is served over a Unix domain socket at $XDG_RUNTIME_DIR/kodachi-session-helper.sock (fallback: <execution folder>/tmp/kodachi-session-helper.sock). No network is involved.",
            "examples": [
              {
                "command": "kodachi-session-helper status --json --json-pretty",
                "description": "Indented status JSON, easier to read by eye than the compact form",
                "expectedOutput": "Pretty-printed status envelope with one field per line"
              },
              {
                "command": "kodachi-session-helper status || echo 'session helper is DOWN'",
                "description": "Use the exit code to alert when the emergency shortcuts are not armed",
                "expectedOutput": "Either the status report, or the fallback message when the daemon is not running",
                "notes": "status exits 1 when the socket is absent, which is the state in which the panic shortcuts do nothing."
              }
            ],
            "id": "2_status_and_socket",
            "title": "Status and Socket"
          },
          {
            "description": "There is no 'stop' subcommand: the daemon's lifecycle is driven by signals. SIGHUP reloads the configuration, SIGTERM shuts it down cleanly.",
            "examples": [
              {
                "command": "kodachi-session-helper reload",
                "description": "Re-read the configuration and re-register the key grabs without restarting",
                "expectedOutput": "SIGHUP sent to daemon (PID <N>)",
                "notes": "Exits 1 when the daemon is not running. The configuration file lives at $XDG_RUNTIME_DIR/kodachi-session-helper.json."
              },
              {
                "command": "kodachi-session-helper reload --json",
                "description": "The same reload, machine readable, for the dashboard",
                "expectedOutput": "JSON envelope carrying success:true and the message \"SIGHUP sent to daemon (PID <N>)\""
              },
              {
                "command": "kill -HUP $(pgrep -x kodachi-session-helper)",
                "description": "Reload by signalling the process directly, when the helper is not on PATH",
                "expectedOutput": "Daemon re-reads its configuration and re-registers the key grabs",
                "notes": "Same effect as 'reload'. Prefer 'reload': it takes the daemon PID from the session-token digest file rather than matching on the process name."
              },
              {
                "command": "kill -TERM $(pgrep -x kodachi-session-helper)",
                "description": "Stop the daemon cleanly",
                "expectedOutput": "Daemon releases its X11 key grabs, zeroizes the session token in memory and exits",
                "notes": "This DISARMS the emergency shortcuts. Until the daemon is started again, the panic key combinations do nothing."
              }
            ],
            "id": "3_signals_and_lifecycle",
            "title": "Signals and Lifecycle"
          },
          {
            "description": "The standard Kodachi meta-flags. Each of them also works after a subcommand.",
            "examples": [
              {
                "command": "kodachi-session-helper -n",
                "description": "List the daemon's features, security properties and system requirements",
                "expectedOutput": "Feature list (key grabs, evdev corroboration, hold-to-trigger, session token, lockdown), plus the X11 and input-group requirements"
              },
              {
                "command": "kodachi-session-helper --version --json",
                "description": "Version as JSON for a build or health check",
                "expectedOutput": "JSON version envelope with the version, build date and git commit"
              },
              {
                "command": "kodachi-session-helper daemon -h",
                "description": "Help for one subcommand, including the SIGHUP and SIGTERM contract",
                "expectedOutput": "Help for the daemon subcommand only, not the top-level listing",
                "notes": "Per-subcommand -h and -e work for daemon, status and reload."
              }
            ],
            "id": "4_program_information",
            "title": "Program Information"
          }
        ],
        "description": "Usage examples for kodachi-session-helper",
        "name": "kodachi-session-helper",
        "quickReference": [
          "kodachi-session-helper daemon",
          "kodachi-session-helper status",
          "kodachi-session-helper status --json",
          "kodachi-session-helper reload",
          "kodachi-session-helper --help",
          "kodachi-session-helper --info --json",
          "kodachi-session-helper --examples --json"
        ]
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:14.693687207Z",
      "version": "9.8.4 (build 320)",
      "warnings": []
    }
  }
}