Terminal Recoverer

Table of Contents

• Features
  • Persistent Recovery Session
  • Optional Terminal Session Logging
  • Crash Capture Pipeline
• Installation
• Enabling Services
• Usage
  • Ensure recovery session exists
  • Start terminal logging for this shell
  • Start coredump watcher manually
• Directory Layout

Terminal Recoverer is a lightweight continuity steward for your terminal environment.

• A persistent tmux recovery session available at all times.

• Optional full-session logging for interactive shells.

• A best-effort crash-capture pipeline triggered by systemd-coredump.

The goal is simple: reduce loss, preserve context, and make post-crash investigation humane.

Features

Persistent Recovery Session

A user-level systemd service ensures a tmux session named recovery is always running. If your terminal crashes, you can immediately reattach:

tmux attach -t recovery

Optional Terminal Session Logging

When enabled, each interactive shell is recorded using script(1) into timestamped logs:

~/Documents/terminal-logs/terminal-YYYY-MM-DD-HHMMSS.log

Enable it by exporting:

export ENABLE_TERMINAL_LOGGING=1

Crash Capture Pipeline

A background watcher listens for systemd-coredump events. For each crash, it creates a structured capture directory:

~/Documents/crash-captures/coredump-YYYY-MM-DD-HHMMSS/

Each capture includes:

• triggering journal line

• system metadata (uname, uptime)

• recent system, kernel, and user logs

• coredumpctl output (if available)

• dmesg, top, ps, free, df, lsblk

• failed user systemd units

This forms a self-contained forensic bundle for debugging.

Installation

Clone the repository and run:

./install.sh

This installs:

• ~/.local/bin/terminal-recoverer

• ~/.bashrc.d/recoverer.sh

• ~/.config/systemd/user/terminal-recoverer.service

• ~/.config/systemd/user/terminal-recoverer-coredump.service

• ~/terminal-recoverer-HOWTO.txt

Enabling Services

Start the recovery session steward:

systemctl --user enable --now terminal-recoverer.service

Enable the crash-capture watcher:

systemctl --user enable --now terminal-recoverer-coredump.service

Usage

Ensure recovery session exists

terminal-recoverer ensure

Start terminal logging for this shell

terminal-recoverer log-shell

Start coredump watcher manually

terminal-recoverer watch-coredump

Directory Layout

~/Documents/terminal-logs/        # Optional session logs
~/Documents/crash-captures/       # Crash forensic bundles

=== Uninstall To remove Sentinel from your user environment:

---- just uninstall ----

== Philosophy

Terminal Recoverer is designed as a small, narratable subsystem.
It aims to:

* minimise irreversible loss
* preserve context during failure
* provide structured, timestamped artefacts
* operate quietly in the background
* remain fully user-controlled and reversible

It is intentionally simple: no daemons, no heavy dependencies, no magic.

== License
Terminal-recoverer is licensed under the Palimpsest License.

The canonical legal text is maintained in the central licensing repository: https://github.com/hyperpolymath/palimpsest-license/

This repository includes only an SPDX stub for reference.