Crate agent_doc_log_time 

Module: log_time

Human-readable log timestamps (#opslogts) and low-level ops-log line formatting. Operators read the supervisor session log and .agent-doc/logs/ops.log to verify reported issues, and a bare Unix epoch like 1781771180 is not legible. This module formats every log entry’s timestamp as ISO-8601 UTC and parses it back, with no external date dependency (Howard Hinnant’s civil-date algorithms).

Spec

• format_log_timestamp renders a Unix epoch (seconds) as YYYY-MM-DDTHH:MM:SSZ (UTC).
• parse_log_timestamp is the matching reader: it accepts either a bare Unix epoch (pre-#opslogts log lines and cycles.jsonl timestamps) or an ISO-8601 UTC string and returns epoch seconds. This backward compatibility keeps the staleness / accretion / startup-miss / gate_verify scanners working across the format switch — old [<epoch>] lines still parse, and parse(format(x)) == x round-trips.
• current_log_timestamp samples the system clock and returns the current timestamp in the same ISO-8601 UTC format.
• format_ops_log_tracking_suffix renders the appended doc=<stem>[ session=<id>][ turn=<cycle_id>] suffix without knowing how callers found those values.
• format_ops_log_line renders the final bracketed ops-log line.

Agentic Contracts

• Formatting/parsing helpers are pure and deterministic for unit testing; no I/O and no orchestration dependencies.
• Clock helpers fail closed to Unix epoch 0 when the system clock is before UNIX_EPOCH.
• parse_log_timestamp fails closed (None) on garbage rather than mapping it to 0, so a malformed line is skipped, not mis-windowed.

Functions

current_epoch_secs

Return the current Unix epoch seconds, defaulting to 0 when the system clock is earlier than UNIX_EPOCH.

current_human_timestamp

Return the current timestamp in a compact human display format YYYY-MM-DD HH:MM:SS (UTC).

current_local_date_ymd

Return the current local date as YYYY-MM-DD using the platform date command, falling back to unknown-date when it is unavailable.

current_log_timestamp

Return the current timestamp in the log format YYYY-MM-DDTHH:MM:SSZ.

format_human_timestamp

Format a Unix epoch (seconds) as YYYY-MM-DD HH:MM:SS (UTC).

format_log_timestamp

Format a Unix epoch (seconds) as a human-readable ISO-8601 UTC timestamp YYYY-MM-DDTHH:MM:SSZ (#opslogts).

format_ops_log_line

Render a full bracketed .agent-doc/logs/ops.log line.

format_ops_log_tracking_suffix

Render the #opslogtrack suffix appended to each ops-log line.

parse_log_timestamp

Parse a log timestamp that is either a bare Unix epoch (seconds) or an ISO-8601 UTC string YYYY-MM-DDTHH:MM:SSZ, returning epoch seconds (#opslogts). The trailing Z is optional. Returns None on anything that is neither, so the staleness/gate scanners skip a malformed line.