TN-005: CommandHistory as Non-Critical Infrastructure¶

Summary¶

CommandHistory initialization and all writes are wrapped in try/except Exception: pass so that failures in history tracking never block or abort a measurement session.

Background¶

CommandHistory logs command lifecycle events (started, completed, error, interrupted) to a JSONL file for troubleshooting support. This file is useful when users report issues — it provides an exact record of what was run and what happened.

However, history tracking is purely diagnostic infrastructure. The primary purpose of kazunoko measure or kazunoko read is to collect detector events. If the history file cannot be written (disk full, permission error, unexpected exception), that must not prevent data collection.

Decision¶

All CommandHistory interactions are wrapped defensively:

# Initialization — failure silently produces None
try:
    history = CommandHistory.from_cli_context(...)
    history.update_status("started")
    history.save(output_dir)
except Exception:
    pass

# At completion — failure does not affect exit code
try:
    if history:
        history.update_status("completed")
        history.save(output_dir)
except Exception:
    pass

CommandHistory is initialized after setup_logger() so that structured logging is always available, even if history tracking fails.

The output filename is a class attribute (CommandHistory.FILENAME = "command_history.jsonl") so all scripts reference the same constant rather than hardcoding the string.

Alternatives Considered¶

Alternative	Reason Not Chosen
Let exceptions propagate	History tracking failure would abort measurements — unacceptable
Log the exception and continue	Adds noise to user-facing output for a non-critical failure
Async / background write	Adds complexity; history files are small and writes are infrequent
Skip history entirely	Lose troubleshooting capability; useful when users report issues

Consequences¶

History tracking failures are silent — users and operators are not notified.
In the rare case of a tracking failure during a bug report, the history file may be incomplete or absent; this is acceptable.
All 12 example scripts follow the same pattern: initialize after setup_logger(), save "started", update to "completed"/"error"/"interrupted" at each exit point.
CommandHistory is exported from the top-level kazunoko package so scripts import it without knowing the internal module path.