Module trigger 

The per-session push trigger.

Extracted from a daemon client’s transcript uploader. A client evaluates every tracked session on a timer and asks decide whether to push that session’s transcript files now. Three things can trigger a push:

• Quiescence — files changed since the last successful push and the newest mtime is at least TriggerPolicy::quiescence old. The common case: a turn finishes, the harness stops writing, the transcript lands half a minute later.
• Periodic safety net — files changed and at least TriggerPolicy::periodic has passed since the last push (or since the session was first seen). Covers sessions that write continuously and never quiesce.
• Exit — the harness process is gone. Final push, then the client retires the session.

Why this is safe to get wrong in the eager direction

The trigger only ever decides when to push, never whether the data is wanted, because the transcript-ingest endpoint is idempotent by construction: the server keys rows on a content hash of the records array, so re-pushing unchanged content answers deduped and a grown transcript appends a new version. That makes every retry, every duplicate tick, and every push after a client restart safe. The design leans on that instead of client-side cleverness — which is also why the fingerprint feeding TriggerInput::dirty is deliberately coarse (size + mtime): any drift re-pushes, and the server sorts it out.

What stays with the client

Failure backoff. A client that cannot reach ingest must not hammer it, but how long to wait, how many times, and when to give up depend on how that client authenticates and what it can fall back to — so the client owns the backoff schedule and merely reports the result through TriggerInput::in_backoff, which gates everything.

Structs

TriggerInput

Pure inputs to the per-session trigger decision, separated from the IO that gathers them so the state machine is unit-testable with synthetic values.

TriggerPolicy

Timing thresholds for decide.

Enums

PushReason

Why a push fired. Clients log this with every upload batch.

Constants

DEFAULT_PERIODIC

Default safety-net push interval for sessions that never quiesce.

DEFAULT_QUIESCENCE

Default idle window after the last transcript write before a push.

DEFAULT_TICK

Suggested cadence for evaluating the trigger.

Functions

decide

The trigger state machine.