@team-agent/installer 0.5.61 → 0.5.62

package/crates/team-agent/src/coordinator/tick.rs

@@ -1,3 +1,4 @@
+//!
 //! Coordinator core:daemon lifecycle 宿主 + 单次 tick 编排(19 步固定顺序)+ health/start/stop。
 
 use std::collections::BTreeMap;
@@ -19,6 +20,7 @@ use super::health::{
     pid_is_running, read_coordinator_metadata, write_coordinator_metadata,
 };
 use super::runtime_observation::{self, CapturedRuntimeFact};
+use super::steps::TickStepGroup;
 use super::types::{
     AgentId, CoordinatorHealthStatus, HealthReport, MetadataSource, Pid, ProviderRegistry,
     SchemaHealth, StartError, StartOutcome, StartReport, StopError, StopOutcome, StopReport,
@@ -225,7 +227,7 @@ impl Coordinator {
     /// `if let Some(rec) = &self.order_recorder { rec.lock()...push(STEP_NAME) }`(tick
     /// 副作用 ORDER 测试断言固定序列)。生产两者均 `None`,零开销。
     pub fn tick(&self) -> Result<TickReport, TickError> {
-        self.record_step("load_state");
+        self.record_step(TickStepGroup::SessionGate, "load_state");
         let raw_state = crate::state::persist::load_runtime_state(self.workspace.as_path())?;
         // Issue 2 (Round 3b gate review §6): when the runtime carries
         // `active_team_key` AND `teams.<key>` exists, project the team-scoped
@@ -246,7 +248,7 @@ impl Coordinator {
         let event_log = EventLog::new(self.workspace.as_path());
         increment_coordinator_tick_iteration_count(&self.workspace);
 
-        self.record_step("tmux_session_gate");
+        self.record_step(TickStepGroup::SessionGate, "tmux_session_gate");
         if let Some(session_name) = state
             .get("session_name")
             .and_then(Value::as_str)
@@ -268,7 +270,7 @@ impl Coordinator {
             }
         }
 
-        self.record_step("capture_missing");
+        self.record_step(TickStepGroup::SessionGate, "capture_missing");
         let pending_context_fork_audits =
             match self.capture_missing_sessions(&mut state, &event_log) {
                 Ok(audits) => audits,
@@ -293,10 +295,10 @@ impl Coordinator {
             .unwrap_or_default();
         let has_work_obligation = tick_has_work_obligation(&store);
 
-        self.record_step("refresh_statuses");
+        self.record_step(TickStepGroup::HealthSync, "refresh_statuses");
         // TODO(spine slice 2b): split lightweight runtime status refresh from health sync.
 
-        self.record_step("startup_prompts");
+        self.record_step(TickStepGroup::RuntimePrompts, "startup_prompts");
         self.handle_startup_prompts(&mut state, &event_log, &pane_snapshot, &window_snapshot);
 
         // #229 step2-retry: once an agent's `startup_prompts` flipped to `handled`
@@ -318,7 +320,7 @@ impl Coordinator {
         // 否则 deliver_pending(下行投递主干)够不到,消息卡 accepted。
         // bug-084 哲学 + A-6 同族:每步独立 try,失败写 `coordinator.tick.<step>_failed`
         // 事件后继续走下一步;tick 本身仍返 Ok。
-        self.record_step("runtime_prompts");
+        self.record_step(TickStepGroup::RuntimePrompts, "runtime_prompts");
         if let Err(error) = self.handle_runtime_approval_prompts(
             &mut state,
             &event_log,
@@ -331,7 +333,7 @@ impl Coordinator {
             );
         }
 
-        self.record_step("sync_health");
+        self.record_step(TickStepGroup::HealthSync, "sync_health");
         // P5 (C-P5-1, N3): ONE pane snapshot per tick, shared by sync_health and the
         // abnormal-exit pass (same-tick reuse only — the snapshot does not outlive
         // this tick; every tick re-reads).
@@ -365,7 +367,7 @@ impl Coordinator {
             );
         }
 
-        self.record_step("deliver_pending");
+        self.record_step(TickStepGroup::Delivery, "deliver_pending");
         let delivered = crate::messaging::deliver_pending_messages(
             self.workspace.as_path(),
             &state,
@@ -376,7 +378,7 @@ impl Coordinator {
         .map(|message_id| DeliveredMessage { message_id })
         .collect::<Vec<_>>();
 
-        self.record_step("fire_scheduled");
+        self.record_step(TickStepGroup::Delivery, "fire_scheduled");
         let scheduled = crate::messaging::fire_due_scheduled_events(
             self.workspace.as_path(),
             &store,
@@ -394,18 +396,18 @@ impl Coordinator {
         // (deliver_pending / fire_scheduled / collect_results) above and below this
         // block continue to flow unchanged. `_state` / `_store` here are intentionally
         // unused (the lookups they powered were nag inputs only).
-        self.record_step("detect_stuck");
+        self.record_step(TickStepGroup::Abnormal, "detect_stuck");
         let stuck: Vec<AgentId> = Vec::new();
-        self.record_step("record_unknown_idle");
-        self.record_step("evaluate_takeover");
+        self.record_step(TickStepGroup::Abnormal, "record_unknown_idle");
+        self.record_step(TickStepGroup::Abnormal, "evaluate_takeover");
         let idle_alerts: Vec<IdleAlert> = Vec::new();
-        self.record_step("detect_deadlocks");
+        self.record_step(TickStepGroup::Abnormal, "detect_deadlocks");
         let deadlock_alerts: Vec<DeadlockAlert> = Vec::new();
         let _ = &store;
 
-        self.record_step("detect_compaction");
-        self.record_step("detect_drift");
-        self.record_step("detect_api_errors");
+        self.record_step(TickStepGroup::Abnormal, "detect_compaction");
+        self.record_step(TickStepGroup::Abnormal, "detect_drift");
+        self.record_step(TickStepGroup::Abnormal, "detect_api_errors");
         let leader_capture = self.capture_leader_receiver(&state);
         let observations = runtime_observation::observe(
             self.workspace.as_path(),
@@ -425,7 +427,7 @@ impl Coordinator {
             results: Vec::new(),
         };
 
-        self.record_step("atomic_save");
+        self.record_step(TickStepGroup::Persist, "atomic_save");
         let saved = match &self.save_hook {
             Some(hook) => hook(&self.workspace, &state),
             None => {
@@ -474,20 +476,20 @@ impl Coordinator {
         // step, and drives the lifecycle helper. Runs OUTSIDE the pre-save
         // window so nested lifecycle saves cannot be clobbered by this
         // tick's final in-memory save (R6 boundary guard).
-        self.record_step("attempt_api_error_recoveries");
+        self.record_step(TickStepGroup::Abnormal, "attempt_api_error_recoveries");
         crate::coordinator::steps::abnormal::attempt_due_recoveries(
             self.workspace.as_path(),
             &event_log,
             self.transport.as_ref(),
         );
 
-        self.record_step("collect_results");
+        self.record_step(TickStepGroup::Delivery, "collect_results");
         collections.results =
             collect_results(crate::messaging::collect_results_and_notify_watchers(
                 self.workspace.as_path(),
                 &event_log,
             )?);
-        self.record_step("prune_dedupe_log");
+        self.record_step(TickStepGroup::Persist, "prune_dedupe_log");
         Ok(base_tick_report(true, false, None, Some(true), collections))
     }
 
@@ -1430,7 +1432,8 @@ impl Coordinator {
         super::health::message_store_schema_health(&self.workspace)
     }
 
-    fn record_step(&self, step: &'static str) {
+    fn record_step(&self, group: TickStepGroup, step: &'static str) {
+        debug_assert!(TickStepGroup::ordered().contains(&group));
         if let Some(recorder) = &self.order_recorder {
             if let Ok(mut guard) = recorder.lock() {
                 guard.push(step);
@@ -2757,13 +2760,6 @@ mod u1_tests {
                 ),
             )
         }
-
-        fn error_lists(
-            &self,
-            _provider: crate::provider::Provider,
-        ) -> super::super::types::ErrorLists {
-            super::super::types::ErrorLists::default()
-        }
     }
 
     #[test]

package/crates/team-agent/src/coordinator/types.rs

@@ -1,5 +1,5 @@
 //! coordinator 共享数据面:常量 / newtype / 穷尽 enum / metadata / schema health /
-//! report 结构 / CoordinatorEvent / abnormal-track 数据型 / WatchCursor / cross-dep 占位。
+//! report 结构 / abnormal-track 数据型 / WatchCursor / cross-dep 占位。
 
 use std::collections::BTreeSet;
 use std::path::{Path, PathBuf};
@@ -9,11 +9,10 @@ use serde_json::Value;
 use thiserror::Error;
 
 // ── REUSE — committed model types(不重定义)──────────────────────────────────
-use crate::model::enums::{AuthMode, Provider};
-// AuthMode/PaneLiveness 经 provider/transport 间接复用;此处只点名直接用到的。
+use crate::model::enums::Provider;
 
 // ── REUSE — step 8 provider(经 trait,MUST-NOT-13:绝不依赖 provider client crate)──
-use crate::provider::{ProcessLiveness, ProviderAdapter, RolloutPath, TurnId, TurnState};
+use crate::provider::{ProviderAdapter, RolloutPath, TurnState};
 
 // ===========================================================================
 // CONSTANTS(metadata.py:13 / __main__.py:101)
@@ -354,137 +353,10 @@ pub struct StopReport {
     pub pid: Option<Pid>,
 }
 
-// ===========================================================================
-// CoordinatorEvent(§3/§22:typed event enum,serde tag 与 Python 字节级一致)
-// ===========================================================================
-
-/// 本 step 发出的事件(card 表整列;事件名稳定契约由 step 4 EventLog 拥有,本卡只点名
-/// coordinator 发的那批)。serde `tag = "event"` + 精确 rename 锁死字节(与 events.jsonl 一致)。
-/// 渲染(`watch::render_event_line`)是它的 `Display` 投影。
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] // 无 Eq:某变体含 f64
-#[serde(tag = "event")]
-pub enum CoordinatorEvent {
-    #[serde(rename = "coordinator.boot")]
-    Boot { workspace: String, once: bool },
-    #[serde(rename = "coordinator.started")]
-    Started { pid: Pid, log: String },
-    #[serde(rename = "coordinator.stopped")]
-    Stopped { pid: Pid },
-    #[serde(rename = "coordinator.exit")]
-    Exit { stop: bool },
-    #[serde(rename = "coordinator.session_missing")]
-    SessionMissing { session: String },
-    #[serde(rename = "coordinator.orphan_self_terminate")]
-    OrphanSelfTerminate {
-        initial_ppid: u32,
-        current_ppid: u32,
-        workspace: String,
-    },
-    #[serde(rename = "coordinator.tick_error")]
-    TickError {
-        error: String,
-        exc_type: String,
-        consecutive_failures: u32,
-        next_sleep_sec: f64,
-    },
-    #[serde(rename = "coordinator.tick_error.suppressed")]
-    TickErrorSuppressed {
-        consecutive_failures: u32,
-        next_sleep_sec: f64,
-    },
-    #[serde(rename = "coordinator.tick_recovered")]
-    TickRecovered { consecutive_failures: u32 },
-    #[serde(rename = "coordinator.restart_incompatible")]
-    RestartIncompatible {
-        pid: Option<Pid>,
-        expected_protocol: u32,
-        expected_schema: i64,
-    },
-    #[serde(rename = "coordinator.restart_incompatible_stop_failed")]
-    RestartIncompatibleStopFailed { pid: Option<Pid> },
-    #[serde(rename = "coordinator.schema_incompatible")]
-    SchemaIncompatible {
-        table: Option<String>,
-        missing_columns: Vec<String>,
-    },
-    #[serde(rename = "idle_takeover.unknown_persistent")]
-    IdleTakeoverUnknownPersistent {
-        node_id: String,
-        provider: Option<Provider>,
-        auth_mode: Option<AuthMode>,
-        consecutive_ticks: u32,
-        rollout_path: Option<RolloutPath>,
-    },
-    #[serde(rename = "abnormal.notify")]
-    AbnormalNotify {
-        signature: String,
-        turn_id: Option<TurnId>,
-        decision: AbnormalDecision,
-    },
-    #[serde(rename = "worker.abnormal_exit")]
-    WorkerAbnormalExit {
-        team_id: String,
-        agent_id: String,
-        provider: Provider,
-        path: String,
-        provider_process_dead: bool,
-        latest_explicit_error: bool,
-        signature: String,
-        turn_id: Option<TurnId>,
-        process_liveness: ProcessLiveness,
-    },
-    #[serde(rename = "worker.abnormal_exit.check")]
-    WorkerAbnormalExitCheck {
-        team_id: String,
-        agent_id: String,
-        provider: Provider,
-        path: String,
-        provider_process_dead: bool,
-        latest_explicit_error: bool,
-        notification: bool,
-        suppressed_reason: Option<String>,
-    },
-    #[serde(rename = "abnormal_exit.single_signal_suppressed")]
-    AbnormalExitSingleSignalSuppressed {
-        team_id: String,
-        agent_id: String,
-        provider: Provider,
-        path: String,
-        reason: String,
-        provider_process_dead: bool,
-        dead_process: bool,
-        latest_explicit_error: bool,
-    },
-    #[serde(rename = "abnormal.whole_team_gone")]
-    AbnormalWholeTeamGone { classification: WholeTeamGoneClass },
-    #[serde(rename = "leader_notification.log_pruned")]
-    LeaderNotificationLogPruned { removed: u64 },
-    #[serde(rename = "leader_notification.prune_failed")]
-    LeaderNotificationPruneFailed { error: String },
-    #[serde(rename = "runtime.state.save_failed")]
-    RuntimeStateSaveFailed {
-        phase: String,
-        error: String,
-        exc_type: String,
-    },
-}
-
 // ===========================================================================
 // 异常轨 abnormal_track(abnormal_track.py)—— provider-neutral 数据型
 // ===========================================================================
 
-/// `_classify` 决策(`abnormal_track.py:198-204`)。whitelist > blacklist > default(C9 catch-bias)。
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum AbnormalDecision {
-    /// whitelist 命中 → 不通知(`abnormal_track.py:201`)。
-    Skip,
-    /// blacklist 命中 → 通知(`abnormal_track.py:203`)。
-    NotifyBlacklist,
-    /// 结构化 fault 默认通知(C9 catch-bias,`abnormal_track.py:204`)。
-    NotifyDefault,
-}
-
 /// `detect_whole_team_gone` 分类(`abnormal_track.py:130/132/143`)。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -498,35 +370,6 @@ pub enum WholeTeamGoneClass {
     UnexpectedExit,
 }
 
-/// `process_abnormal_records` 单条通知(`abnormal_track.py:70-79`)。
-/// dedup key = `(signature, turn_id|fingerprint)`(C8,`abnormal_track.py:64-66`):turn_id 缺失退化为
-/// per-record content fingerprint 桶,**绝不**把不同 fault 折叠进一个全局桶。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AbnormalNotification {
-    pub signature: String,
-    pub turn_id: Option<TurnId>,
-    /// `kind == "approval"` → blocked_on_human,否则 abnormal(`abnormal_track.py:74`)。
-    pub state: TurnState,
-    pub decision: AbnormalDecision,
-    pub provider: Option<Provider>,
-    /// 原始 fault fact(provider reader 产出的结构化记录;本 module 不读屏不命名 provider)。
-    pub raw: Value,
-}
-
-/// `process_abnormal_records` 返回(`abnormal_track.py:83-88` typed 版)。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AbnormalProcessOutput {
-    pub notifications: Vec<AbnormalNotification>,
-    /// 更新后的去重状态(`seen` 集合,`abnormal_track.py:82`)——caller 回存。
-    pub notification_state: AbnormalNotificationState,
-}
-
-/// abnormal 去重状态(`abnormal_track.py:31-32,82`)。`seen` = `signature\0bucket` key 集合。
-#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
-pub struct AbnormalNotificationState {
-    pub seen: BTreeSet<String>,
-}
-
 /// `detect_whole_team_gone` 返回(`abnormal_track.py:140-147` typed 版)。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct WholeTeamGoneReport {
@@ -551,13 +394,6 @@ pub struct TeamPresenceSnapshot {
     pub restart_in_progress: bool,
 }
 
-/// abnormal track 错误(provider reader 翻译 fault facts 失败)。
-#[derive(Debug, Error)]
-pub enum AbnormalError {
-    #[error("provider: {0}")]
-    Provider(#[from] crate::provider::ProviderError),
-}
-
 // ===========================================================================
 // WatchCursor(watch/__init__.py)
 // ===========================================================================
@@ -591,15 +427,6 @@ pub use crate::model::ids::AgentId;
 pub trait ProviderRegistry {
     /// 拿某 provider 的 adapter(`providers.get_adapter`)。
     fn adapter_for(&self, provider: Provider) -> Box<dyn ProviderAdapter>;
-    /// 该 provider 的 error 黑白名单(`get_provider_registry(provider)["error_lists"]`,abnormal_track 用)。
-    fn error_lists(&self, provider: Provider) -> ErrorLists;
-}
-
-/// provider error 黑白名单(`abnormal_track.py:184-195`)。**PLACEHOLDER**(step 8 拥有)。
-#[derive(Debug, Clone, Default, PartialEq, Eq)]
-pub struct ErrorLists {
-    pub whitelist: Vec<String>,
-    pub blacklist: Vec<String>,
 }
 
 /// idle take-over 候选 node(`idle_takeover_wiring.build_idle_nodes`,step 8/11 拥有真名)。

package/crates/team-agent/src/db/agent_health_capture.rs

@@ -1,3 +1,4 @@
+//!
 //! Phase-DX E2: `agent_health` row capture/restore for the remove-agent flow.
 //!
 //! Extracted from `lifecycle/restart/remove.rs` so the SQL column reference to

package/crates/team-agent/src/db/message_store.rs

@@ -4,6 +4,7 @@
 // physical relocation (zero behavior change).
 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
 
+//!
 //! step 7 · message_store — core message lifecycle over `team.db`.
 //!
 //! Truth source (READ-ONLY): `team-agent-public` @ v0.2.11,
@@ -205,7 +206,7 @@ pub struct PersistMessageInput<'a> {
 
 /// `leader_notification_log._legacy_epoch_from_uuid` (line 145-147):
 /// `int(zlib.crc32(str(uuid or "").encode("utf-8")) & 0x7FFFFFFF)`.
-pub fn legacy_epoch_from_uuid(leader_session_uuid: Option<&str>) -> i64 {
+fn legacy_epoch_from_uuid(leader_session_uuid: Option<&str>) -> i64 {
     let mut crc = 0xFFFF_FFFFu32;
     for byte in leader_session_uuid.unwrap_or("").as_bytes() {
         crc ^= u32::from(*byte);

package/crates/team-agent/src/db/migration.rs

@@ -1,3 +1,4 @@
+//!
 //! `team.db` 列布局迁移(Gap 46;真相源 `message_store/schema_migration.py`)。
 //!
 //! 检测**物理列序漂移**(`pragma table_info` 顺序 vs canonical),在**一个原子事务**
@@ -141,7 +142,7 @@ fn create_table_ddl(table: &str, name: &str) -> Option<String> {
 
 /// 一张表的布局 diff。
 #[derive(Debug, Clone)]
-pub struct Diff {
+struct Diff {
     pub table: &'static str,
     pub expected: Vec<&'static str>,
     pub actual: Vec<String>,
@@ -187,7 +188,7 @@ fn table_count(conn: &Connection, table: &str) -> Result<i64, DbError> {
     Ok(conn.query_row(&format!("select count(*) from {table}"), [], |r| r.get(0))?)
 }
 
-pub fn pragma_user_version(conn: &Connection) -> Result<i64, DbError> {
+fn pragma_user_version(conn: &Connection) -> Result<i64, DbError> {
     Ok(conn.query_row("pragma user_version", [], |r| r.get(0))?)
 }
 
@@ -230,7 +231,7 @@ fn run_version_migrations(conn: &Connection, schema_version: i64) -> Result<(),
 
 /// `schema_migration.py:_layout_diffs`:按 `table_info` 物理列序检测漂移。
 /// 无任何 managed 表存在(fresh DB)→ 空(initialize 随后建表)。
-pub fn layout_diffs(conn: &Connection) -> Result<Vec<Diff>, DbError> {
+fn layout_diffs(conn: &Connection) -> Result<Vec<Diff>, DbError> {
     let mut any = false;
     for (t, _) in MANAGED_TABLE_LAYOUTS {
         if table_exists(conn, t)? {
@@ -419,7 +420,7 @@ pub fn ensure_table_layout(
 }
 
 /// `schema_migration.py:schema_diagnosis`:只读判定(不变更 DB)。
-pub fn schema_diagnosis(db_path: &Path, schema_version: i64) -> Result<Diagnosis, DbError> {
+fn schema_diagnosis(db_path: &Path, schema_version: i64) -> Result<Diagnosis, DbError> {
     if !db_path.exists() {
         // T3-3 cr verdict (A parity lock, 2026-06-10): a missing db is the LEGAL
         // first-use state — ok:true is layered with the explicit status axis and the

package/crates/team-agent/src/db/mod.rs

@@ -1,3 +1,4 @@
+//!
 //! step 3 · db — `team.db`(SQLite)的 schema 与迁移层(真相源 `message_store/schema*.py`)。
 //!
 //! §6 step 3:schema/migrations/indexes/WAL+busy-timeout/只读兼容。**消息操作本身(send/

package/crates/team-agent/src/db/schema.rs

@@ -1,3 +1,4 @@
+//!
 //! `team.db` schema 初始化(真相源 `message_store/schema.py` + `schema_migration.py`)。
 //!
 //! slice 1:fresh DB schema —— 8 表 DDL、6 索引、ALTER 式列迁移、agent_health 重建、

package/crates/team-agent/src/diagnose/comms.rs

@@ -1,3 +1,4 @@
+
 use std::path::Path;
 
 use serde_json::{json, Value};
@@ -212,7 +213,7 @@ fn verifies_json(check: &SelftestCheck) -> Value {
     serde_json::to_value(check.verifies).unwrap_or_else(|_| json!("unknown"))
 }
 
-pub fn receiver_binding_mismatches(
+fn receiver_binding_mismatches(
     owner_pane_id: &Value,
     caller_pane_id: &Value,
     pane_id: &Value,

package/crates/team-agent/src/diagnose/mod.rs

@@ -1,3 +1,4 @@
+//!
 //! Shared doctor gate seams.
 
 use std::path::Path;

package/crates/team-agent/src/diagnose/orphans.rs

@@ -1,3 +1,4 @@
+
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 use std::process::Command;

package/crates/team-agent/src/layout/manager.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.3.28 layout step 2 — leader placement.
 //!
 //! Public API for managed-mode leader placement. The runtime calls
@@ -34,6 +35,7 @@ pub enum LeaderPlacement {
     },
 }
 
+///
 /// Compute the placement for a leader given its identity, the desired
 /// `LeaderStartMode`, and the environment (used to detect `$TMUX`).
 ///
@@ -58,13 +60,6 @@ pub fn leader_placement(
     }
 }
 
-/// The leader session name for a given provider + workspace. `LeaderIdentity`
-/// in this codebase does not carry the provider field; the caller supplies it
-/// explicitly (matches how `leader_session_name` itself is shaped).
-pub fn leader_session_for_provider(provider: Provider, workspace: &Path) -> SessionName {
-    leader_session_name(provider, workspace)
-}
-
 #[allow(dead_code)]
 fn _unused_identity_marker(_id: &LeaderIdentity) {}
 
@@ -74,6 +69,7 @@ use crate::layout::placement::{WorkerSpawnAction, WorkerSpawnTarget};
 use crate::model::yaml::Value as YamlValue;
 use crate::transport::Transport;
 
+///
 /// Compute the spawn target for a worker. Python parity: one window per
 /// agent in the worker session, named after `agent_id`. First worker
 /// (= session does not yet exist) → NewSession; otherwise NewWindow.

package/crates/team-agent/src/layout/mod.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.3.28 — Unified adaptive layout manager.
 //!
 //! Single source of truth for tmux topology decisions in the runtime:
@@ -31,6 +32,5 @@ pub mod worker_env;
 pub mod worker_window_helpers;
 
 pub use runtime_sessions::{
-    LeaderLauncherSession, LeaderLauncherSessionError, RuntimeSessionAnomaly, RuntimeSessions,
-    WorkerSession, WorkerSessionError,
+    LeaderLauncherSession, RuntimeSessionAnomaly, RuntimeSessions, WorkerSession,
 };

package/crates/team-agent/src/layout/overlay.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.3.28 layout step 8 — display overlay (3-pane tiling).
 //!
 //! Python truth source: 3-pane tiling exists ONLY in the display overlay
@@ -15,6 +16,7 @@ use crate::transport::{SessionName, WindowName};
 /// 3 panes per overlay window — Python parity.
 pub const OVERLAY_PANES_PER_WINDOW: usize = 3;
 
+///
 /// Overlay window name for a 0-based group index. Index 0 → `overview`;
 /// N ≥ 1 → `overview-{N+1}`. Names are scoped by `session_tag` so multiple
 /// teams can coexist on one leader session.
@@ -38,6 +40,7 @@ pub struct OverlayPlacement {
     pub window: WindowName,
 }
 
+///
 /// Compute the overlay placements for a list of agent_ids. Deterministic by
 /// input order: agent `i` → window `i / 3`, slot `i % 3`.
 pub fn plan_overlay_placements(session_tag: &str, agents: &[&str]) -> Vec<OverlayPlacement> {
@@ -53,9 +56,10 @@ pub fn plan_overlay_placements(session_tag: &str, agents: &[&str]) -> Vec<Overla
         .collect()
 }
 
+///
 /// True when a window name belongs to a display overlay (matches
 /// `team-agent:<...>:overview[-N]`).
-pub fn is_overlay_window(name: &WindowName) -> bool {
+fn is_overlay_window(name: &WindowName) -> bool {
     let n = name.as_str();
     if !n.starts_with("team-agent:") {
         return false;
@@ -63,6 +67,7 @@ pub fn is_overlay_window(name: &WindowName) -> bool {
     n.contains(":overview")
 }
 
+///
 /// 0.3.28 Step 8 invariant: `spawn_split` may ONLY be called from the
 /// overlay module. This helper emits a warn-level event when called from
 /// anywhere else (Step 9 promotes to a hard error / panic gate). The

package/crates/team-agent/src/layout/placement.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.3.28 layout step 4 — typed worker placement target.
 //!
 //! Python parity (`runtime.py:1017-1020`): one window per agent in the

package/crates/team-agent/src/layout/recovery.rs

@@ -1,3 +1,4 @@
+//!
 //! 0.3.28 layout step 7 — leader pane recovery.
 //!
 //! Python truth source (`leader/__init__.py:885-887` +
@@ -28,6 +29,7 @@ pub enum RecoveryOutcome {
     NeedsUserAttach,
 }
 
+///
 /// Compute the recovery outcome from the current environment.
 ///
 /// Reads `TMUX_PANE` from the supplied environment iterator (use
@@ -44,6 +46,7 @@ where
     RecoveryOutcome::NeedsUserAttach
 }
 
+///
 /// Emit the canonical `leader_receiver.rebind_required` event when the
 /// runtime falls through to `NeedsUserAttach`. Logs to stderr so operators
 /// see the cascade in event logs.

package/crates/team-agent/src/layout/runtime_sessions.rs

@@ -1,3 +1,4 @@
+//!
 //! unit-1 (Stage 1) — typed runtime session identity.
 //!
 //! Provides two compile-time-distinct newtypes plus a `RuntimeSessions`
@@ -35,7 +36,7 @@ pub struct LeaderLauncherSession(SessionName);
 
 /// Why `WorkerSession::new` rejected a name.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum WorkerSessionError {
+enum WorkerSessionError {
     /// The name is empty.
     Empty,
     /// The name carries the leader launcher prefix — must not be a worker
@@ -45,7 +46,7 @@ pub enum WorkerSessionError {
 
 /// Why `LeaderLauncherSession::new` rejected a name.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum LeaderLauncherSessionError {
+enum LeaderLauncherSessionError {
     /// The name is empty.
     Empty,
     /// The name does not carry the required leader launcher prefix.
@@ -136,6 +137,7 @@ pub enum RuntimeSessionAnomaly {
 }
 
 impl RuntimeSessions {
+    ///
     /// Read state.json's session-identity fields and wrap them in typed
     /// values. Never panics on bad state — anomalies are surfaced for
     /// callers to act on.
@@ -197,11 +199,13 @@ impl RuntimeSessions {
         }
     }
 
+    ///
     /// True if any session-identity anomaly was detected in state.
     pub fn has_anomalies(&self) -> bool {
         !self.anomalies.is_empty()
     }
 
+    ///
     /// True if a `state.session_name` looked like a leader launcher session
     /// — the exact 0.3.39 shape unit-3 must refuse before any kill.
     pub fn worker_session_name_is_leader_prefixed(&self) -> bool {
@@ -214,9 +218,10 @@ impl RuntimeSessions {
     }
 }
 
+///
 /// True when `name` is a leader launcher session (mirrors
 /// `layout::sessions::is_leader_session` on a raw &str).
-pub fn name_is_leader_launcher(name: &str) -> bool {
+fn name_is_leader_launcher(name: &str) -> bool {
     let session = SessionName::new(name);
     is_leader_session(&session)
 }