Module shell_efficiency 

Folds gate4agent_shell_native::ShellEfficiencyFacts – plain facts a NativeEffectShell accumulates inside collect_terminal_frames and reclassify_foreground – into the same “distribution, not an average” contract tick_profile uses for NativeRuntime::tick’s own phases.

See ShellEfficiencyFacts’s own doc comment for why the split is: that crate reports plain facts, this crate keeps statistics. It is the dependency direction (gate4agent-shell-native does not, and must not, depend on gate4agent-runtime-native) that makes this crate, not that one, the only place a fact can become a percentile – do not “fix” that by moving RingStats/Distribution downstream or re-deriving a second copy of them in gate4agent-shell-native.

run_effect_worker’s worker-loop task calls both shell methods above once per iteration and immediately drains their facts (see publish_shell_observations), folding them into the Arc<Mutex<ShellEfficiencyProfile>> that every NativeWorkerContext shares with NativeEffectDispatcher – one worker per AgentInstanceId, all folding into the same shared profile. NativeRuntime:: shell_efficiency_snapshot is the only reader, called once per drive-loop iteration by gate4agent-node, same cadence as NativeRuntime::tick_profile_snapshot.

Structs

ShellEfficiencyProfile

Owns the shell-efficiency rings and lifetime counters folded from every per-instance worker’s drained ShellEfficiencyFacts. Lives behind an Arc<Mutex<_>> shared by NativeEffectDispatcher and every NativeWorkerContext it spawns, since multiple worker tasks fold into it concurrently – locked only for one fold, never across an .await, same rule as gate4agent-node’s DriveLoopProfiler.

ShellEfficiencyProfileSnapshot

One snapshot of every shell-efficiency series – what crate::NativeRuntime::shell_efficiency_snapshot returns, and what GET /metrics renders alongside TickProfileSnapshot.