@team-agent/installer 0.5.50 → 0.5.52

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

@@ -52,6 +52,8 @@ pub enum MessageStoreError {
     Sqlite(#[from] rusqlite::Error),
     #[error("io: {0}")]
     Io(#[from] std::io::Error),
+    #[error("delivery receipt missing for message: {0}")]
+    DeliveryReceiptMissing(String),
 }
 
 /// Outcome of [`MessageStore::claim_leader_notification_delivery`]
@@ -78,6 +80,40 @@ pub struct NotificationClaimParams<'a> {
     pub pane_id: Option<&'a str>,
 }
 
+/// Canonical initial message-row statuses shared by persistence, presentation,
+/// claiming and recovery. New durable dispositions must be added here first.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MessageRowStatus {
+    Accepted,
+    QueuedUntilLeaderAttach,
+    QueuedCoordinatorUnavailable,
+}
+
+impl MessageRowStatus {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Accepted => "accepted",
+            Self::QueuedUntilLeaderAttach => "queued_until_leader_attach",
+            Self::QueuedCoordinatorUnavailable => "queued_coordinator_unavailable",
+        }
+    }
+}
+
+/// Fully resolved durable-message insert. Grammar, scope and transport data do
+/// not belong here; callers must resolve those before crossing this boundary.
+pub struct PersistMessageInput<'a> {
+    pub message_id: Option<&'a str>,
+    pub owner_team_id: Option<&'a str>,
+    pub task_id: Option<&'a str>,
+    pub sender: &'a str,
+    pub recipient: &'a str,
+    pub reply_to: Option<&'a str>,
+    pub requires_ack: bool,
+    pub status: MessageRowStatus,
+    pub content: &'a str,
+    pub error: Option<&'a str>,
+}
+
 /// `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 {
@@ -133,44 +169,67 @@ impl MessageStore {
         &self.path
     }
 
-    /// `create_message` (`core.py:71-114`). Returns `msg_<uuid4 hex[:12]>`; inserts
-    /// a row with `status='accepted'`, `requires_ack` as 0/1 int, `artifact_refs`
-    /// defaulting to `'[]'`, `delivery_attempts=0`, timestamps = now.
-    #[allow(clippy::too_many_arguments)]
-    pub fn create_message(
+    pub fn persist_message(
         &self,
-        task_id: Option<&str>,
-        sender: &str,
-        recipient: &str,
-        content: &str,
-        reply_to: Option<&str>,
-        requires_ack: bool,
-        owner_team_id: Option<&str>,
+        input: PersistMessageInput<'_>,
     ) -> Result<String, MessageStoreError> {
         let conn = crate::db::schema::open_db(&self.path)?;
-        let message_id = next_message_id();
+        let message_id = input
+            .message_id
+            .map(ToOwned::to_owned)
+            .unwrap_or_else(next_message_id);
         let now = now_ts();
         conn.execute(
             "insert into messages(
                 message_id, owner_team_id, task_id, sender, recipient, reply_to, requires_ack,
                 status, content, artifact_refs, created_at, updated_at, delivered_at,
                 acknowledged_at, error, delivery_attempts
-            ) values (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'accepted', ?8, '[]', ?9, ?9, null, null, null, 0)",
+            ) values (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, '[]', ?10, ?10, null, null, ?11, 0)",
             params![
                 message_id,
-                owner_team_id,
-                task_id,
-                sender,
-                recipient,
-                reply_to,
-                if requires_ack { 1 } else { 0 },
-                content,
+                input.owner_team_id,
+                input.task_id,
+                input.sender,
+                input.recipient,
+                input.reply_to,
+                if input.requires_ack { 1 } else { 0 },
+                input.status.as_str(),
+                input.content,
                 now,
+                input.error,
             ],
         )?;
         Ok(message_id)
     }
 
+    /// `create_message` (`core.py:71-114`). Returns `msg_<uuid4 hex[:12]>`; inserts
+    /// a row with `status='accepted'`, `requires_ack` as 0/1 int, `artifact_refs`
+    /// defaulting to `'[]'`, `delivery_attempts=0`, timestamps = now.
+    #[allow(clippy::too_many_arguments)]
+    pub fn create_message(
+        &self,
+        task_id: Option<&str>,
+        sender: &str,
+        recipient: &str,
+        content: &str,
+        reply_to: Option<&str>,
+        requires_ack: bool,
+        owner_team_id: Option<&str>,
+    ) -> Result<String, MessageStoreError> {
+        self.persist_message(PersistMessageInput {
+            message_id: None,
+            owner_team_id,
+            task_id,
+            sender,
+            recipient,
+            reply_to,
+            requires_ack,
+            status: MessageRowStatus::Accepted,
+            content,
+            error: None,
+        })
+    }
+
     /// Caller-supplied-id variant of [`create_message`] (CR-015/054 — `--message-id`).
     /// Inserts exactly the given `message_id` instead of generating one. The store
     /// PK is `message_id`, so a repeat with the same id is rejected by SQLite; the
@@ -190,27 +249,18 @@ impl MessageStore {
         requires_ack: bool,
         owner_team_id: Option<&str>,
     ) -> Result<String, MessageStoreError> {
-        let conn = crate::db::schema::open_db(&self.path)?;
-        let now = now_ts();
-        conn.execute(
-            "insert into messages(
-                message_id, owner_team_id, task_id, sender, recipient, reply_to, requires_ack,
-                status, content, artifact_refs, created_at, updated_at, delivered_at,
-                acknowledged_at, error, delivery_attempts
-            ) values (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'accepted', ?8, '[]', ?9, ?9, null, null, null, 0)",
-            params![
-                message_id,
-                owner_team_id,
-                task_id,
-                sender,
-                recipient,
-                reply_to,
-                if requires_ack { 1 } else { 0 },
-                content,
-                now,
-            ],
-        )?;
-        Ok(message_id.to_string())
+        self.persist_message(PersistMessageInput {
+            message_id: Some(message_id),
+            owner_team_id,
+            task_id,
+            sender,
+            recipient,
+            reply_to,
+            requires_ack,
+            status: MessageRowStatus::Accepted,
+            content,
+            error: None,
+        })
     }
 
     /// `true` iff a `messages` row with this `message_id` already exists. Used by
@@ -260,6 +310,62 @@ impl MessageStore {
         Ok(())
     }
 
+    /// Record that the transport submitted a message without claiming that the
+    /// provider accepted it. The stable message id is also the receipt token.
+    pub fn record_delivery_submission(
+        &self,
+        message_id: &str,
+        visible: bool,
+    ) -> Result<(), MessageStoreError> {
+        let conn = crate::db::schema::open_db(&self.path)?;
+        let now = now_ts();
+        conn.execute(
+            "insert into delivery_tokens(
+                 message_id, unique_token, injected_at, visible_at,
+                 consumed_at, failed_at, failure_reason
+             ) values (?1, ?1, ?2, ?3, null, null, null)
+             on conflict(message_id) do update set
+                 visible_at = coalesce(delivery_tokens.visible_at, excluded.visible_at),
+                 failed_at = null,
+                 failure_reason = null",
+            params![message_id, now, visible.then_some(now_ts())],
+        )?;
+        Ok(())
+    }
+
+    /// Atomically persist the provider-side receipt and advance the message to
+    /// delivered. A transport-only caller cannot use this without first
+    /// recording the submission row above.
+    pub fn mark_delivered_with_receipt(&self, message_id: &str) -> Result<(), MessageStoreError> {
+        let mut conn = crate::db::schema::open_db(&self.path)?;
+        let tx = conn.transaction()?;
+        let now = now_ts();
+        let receipts = tx.execute(
+            "update delivery_tokens
+             set consumed_at = coalesce(consumed_at, ?2),
+                 failed_at = null,
+                 failure_reason = null
+             where message_id = ?1",
+            params![message_id, now],
+        )?;
+        if receipts != 1 {
+            return Err(MessageStoreError::DeliveryReceiptMissing(
+                message_id.to_string(),
+            ));
+        }
+        tx.execute(
+            "update messages
+             set status = case when status = 'acknowledged' then status else 'delivered' end,
+                 updated_at = ?2,
+                 delivered_at = ?2,
+                 error = null
+             where message_id = ?1",
+            params![message_id, now_ts()],
+        )?;
+        tx.commit()?;
+        Ok(())
+    }
+
     /// `claim_for_delivery` (`core.py:190-205`): atomic single-winner claim. Flips an
     /// eligible row (status ∈ pending/accepted/queued_until_idle/queued_until_start/
     /// queued_stopped/queued_pane_missing) to `target_resolved`, `delivery_attempts +=
@@ -274,9 +380,13 @@ impl MessageStore {
              where message_id = ?1
                and status in (
                    'pending', 'accepted', 'queued_until_idle', 'queued_until_start',
-                   'queued_stopped', 'queued_pane_missing'
+                   'queued_stopped', 'queued_pane_missing', ?3
                )",
-            params![message_id, now_ts()],
+            params![
+                message_id,
+                now_ts(),
+                MessageRowStatus::QueuedCoordinatorUnavailable.as_str()
+            ],
         )?;
         Ok(rows == 1)
     }

package/crates/team-agent/src/event_log.rs

@@ -35,6 +35,38 @@ use crate::model::paths::logs_dir;
 pub const EVENT_LOG_ROTATE_BYTES: u64 = 5 * 1024 * 1024;
 /// `events.py:18`:保留 5 个 archive。
 pub const EVENT_LOG_ARCHIVE_KEEP: u32 = 5;
+pub(crate) const PROVIDER_SESSION_CONVERGING: &str = "provider.session.converging";
+pub(crate) const PROVIDER_WORKER_SPAWN_ARGV: &str = "provider.worker.spawn_argv";
+
+pub(crate) fn provider_worker_spawn_argv_fields(fields: Value) -> Value {
+    let object = fields.as_object();
+    let field = |key: &str| {
+        object
+            .and_then(|object| object.get(key))
+            .cloned()
+            .unwrap_or(Value::Null)
+    };
+    let array = |key: &str| match field(key) {
+        value @ Value::Array(_) => value,
+        _ => Value::Array(Vec::new()),
+    };
+    serde_json::json!({
+        "agent_id": field("agent_id"),
+        "provider": field("provider"),
+        "argv": array("argv"),
+        "session_id_in_argv": field("session_id_in_argv"),
+        "expected_session_id": field("expected_session_id"),
+        "spawn_cwd": field("spawn_cwd"),
+        "spawned_at": field("spawned_at"),
+        "source": field("source"),
+        "spawn_epoch": field("spawn_epoch"),
+        "env_overlay_keys": array("env_overlay_keys"),
+        "env_unset": array("env_unset"),
+        "tmux_start_mode": field("tmux_start_mode"),
+        "tmux_endpoint": field("tmux_endpoint"),
+        "tmux_endpoint_source": field("tmux_endpoint_source"),
+    })
+}
 
 #[derive(Debug, Error)]
 pub enum EventLogError {
@@ -277,6 +309,47 @@ mod tests {
         assert!(ts.ends_with("+00:00"));
     }
 
+    #[test]
+    fn provider_spawn_fields_have_one_canonical_shape() {
+        let fields = provider_worker_spawn_argv_fields(json!({
+            "agent_id": "worker",
+            "provider": "fake",
+            "source": "restart",
+            "ignored": "not part of the schema",
+        }));
+        let object = fields.as_object().unwrap();
+        let keys = object
+            .keys()
+            .map(String::as_str)
+            .collect::<std::collections::BTreeSet<_>>();
+        assert_eq!(
+            keys,
+            [
+                "agent_id",
+                "argv",
+                "env_overlay_keys",
+                "env_unset",
+                "expected_session_id",
+                "provider",
+                "session_id_in_argv",
+                "source",
+                "spawn_cwd",
+                "spawn_epoch",
+                "spawned_at",
+                "tmux_endpoint",
+                "tmux_endpoint_source",
+                "tmux_start_mode",
+            ]
+            .into_iter()
+            .collect::<std::collections::BTreeSet<_>>()
+        );
+        assert_eq!(fields["argv"], json!([]));
+        assert_eq!(fields["env_overlay_keys"], json!([]));
+        assert_eq!(fields["env_unset"], json!([]));
+        assert!(fields["spawn_cwd"].is_null());
+        assert!(fields.get("ignored").is_none());
+    }
+
     #[test]
     fn tail_returns_last_n_and_raw_on_bad_line() {
         let ws = temp_ws();

package/crates/team-agent/src/leader/lease.rs

@@ -712,25 +712,46 @@ fn claim_lease_no_incident_with_target(
             candidate_source,
             pre_epoch,
         );
-        if converged {
+        let observation_refreshed = caller_pane_info.is_some_and(|pane_info| {
+            refresh_already_bound_receiver_observation(
+                state,
+                pane_info,
+                observed_endpoint.or(current_endpoint.as_deref()),
+                scoped_team.or(team),
+            )
+        });
+        if converged || observation_refreshed {
             write_claim_state(workspace, state, scoped_team, team)?;
-            topology_convergence = verify_persisted_topology_convergence(
-                workspace,
-                team_id.as_str(),
-                topology_convergence,
-                pre_epoch,
-            )?;
-            if topology_convergence
-                .as_ref()
-                .and_then(|metadata| metadata.get("status"))
-                .and_then(Value::as_str)
-                != Some("converged")
-            {
-                return Ok(convergence_persistence_refusal(
+            if observation_refreshed {
+                event_log.write(
+                    "leader_receiver.observation_refreshed",
+                    json!({
+                        "pane_id": caller_pane.as_str(),
+                        "owner_epoch": pre_epoch.0,
+                        "owner_changed": false,
+                        "source": "claim_leader_already_bound",
+                    }),
+                )?;
+            }
+            if converged {
+                topology_convergence = verify_persisted_topology_convergence(
+                    workspace,
+                    team_id.as_str(),
                     topology_convergence,
                     pre_epoch,
-                    Some(caller_pane.clone()),
-                ));
+                )?;
+                if topology_convergence
+                    .as_ref()
+                    .and_then(|metadata| metadata.get("status"))
+                    .and_then(Value::as_str)
+                    != Some("converged")
+                {
+                    return Ok(convergence_persistence_refusal(
+                        topology_convergence,
+                        pre_epoch,
+                        Some(caller_pane.clone()),
+                    ));
+                }
             }
         }
         return Ok(LeaseResult {
@@ -1659,6 +1680,108 @@ fn receiver_fingerprint(target: &PaneInfo) -> String {
     )
 }
 
+fn refresh_already_bound_receiver_observation(
+    state: &mut Value,
+    observed: &PaneInfo,
+    observed_endpoint: Option<&str>,
+    team_key: Option<&str>,
+) -> bool {
+    let attached_at = now_ts();
+    let mut refreshed = state
+        .get_mut("leader_receiver")
+        .and_then(Value::as_object_mut)
+        .is_some_and(|receiver| {
+            refresh_receiver_observation(
+                receiver,
+                observed,
+                observed_endpoint,
+                attached_at.as_str(),
+            )
+        });
+    if let Some(team_key) = team_key {
+        refreshed |= state
+            .get_mut("teams")
+            .and_then(|teams| teams.get_mut(team_key))
+            .and_then(|entry| entry.get_mut("leader_receiver"))
+            .and_then(Value::as_object_mut)
+            .is_some_and(|receiver| {
+                refresh_receiver_observation(
+                    receiver,
+                    observed,
+                    observed_endpoint,
+                    attached_at.as_str(),
+                )
+            });
+    }
+    refreshed
+}
+
+fn refresh_receiver_observation(
+    receiver: &mut serde_json::Map<String, Value>,
+    observed: &PaneInfo,
+    observed_endpoint: Option<&str>,
+    attached_at: &str,
+) -> bool {
+    let before = Value::Object(receiver.clone());
+    receiver.insert(
+        "session_name".to_string(),
+        Value::String(observed.session.as_str().to_string()),
+    );
+    receiver.insert(
+        "window_index".to_string(),
+        observed
+            .window_index
+            .map(|value| Value::String(value.to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "window_name".to_string(),
+        observed
+            .window_name
+            .as_ref()
+            .map(|value| Value::String(value.as_str().to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_index".to_string(),
+        observed
+            .pane_index
+            .map(|value| Value::String(value.to_string()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_tty".to_string(),
+        observed
+            .tty
+            .as_ref()
+            .map(|value| Value::String(value.clone()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "pane_current_command".to_string(),
+        observed
+            .current_command
+            .as_ref()
+            .map(|value| Value::String(value.clone()))
+            .unwrap_or(Value::Null),
+    );
+    receiver.insert(
+        "fingerprint".to_string(),
+        Value::String(receiver_fingerprint(observed)),
+    );
+    if let Some(endpoint) = observed_endpoint.filter(|value| !value.is_empty()) {
+        receiver.insert(
+            "tmux_socket".to_string(),
+            Value::String(endpoint.to_string()),
+        );
+    }
+    receiver.insert(
+        "attached_at".to_string(),
+        Value::String(attached_at.to_string()),
+    );
+    Value::Object(receiver.clone()) != before
+}
+
 fn make_owner(
     provider: Provider,
     pane: &NonEmptyPaneId,
@@ -2124,6 +2247,22 @@ fn readable_team_snapshot_path(w: &BP, n: &str) -> BF /* B0_DIAGNOSTIC_LEGACY_SN
 mod tests {
     use super::*;
 
+    fn observed_pane() -> PaneInfo {
+        PaneInfo {
+            pane_id: PaneId::new("%7"),
+            session: crate::transport::SessionName::new("new-session"),
+            window_index: Some(3),
+            window_name: Some(crate::transport::WindowName::new("new-window")),
+            pane_index: Some(1),
+            tty: Some("/dev/ttys007".to_string()),
+            current_command: Some("codex".to_string()),
+            current_path: None,
+            active: true,
+            pane_pid: Some(700),
+            leader_env: std::collections::BTreeMap::new(),
+        }
+    }
+
     #[test]
     fn attribute_command_provider_recognizes_copilot() {
         assert_eq!(
@@ -2135,4 +2274,51 @@ mod tests {
             Some(Provider::Copilot)
         );
     }
+
+    #[test]
+    fn already_bound_refresh_updates_observations_without_reclaiming() {
+        let mut state = json!({
+            "leader_receiver": {
+                "status": "attached",
+                "pane_id": "%7",
+                "owner_epoch": 10,
+                "owner_agent_id": "leader",
+                "session_name": "old-session",
+                "pane_tty": "/dev/old",
+                "attached_at": "2026-01-01T00:00:00Z"
+            },
+            "teams": {"team-a": {"leader_receiver": {
+                "status": "attached",
+                "pane_id": "%7",
+                "owner_epoch": 10,
+                "owner_agent_id": "leader",
+                "session_name": "old-session",
+                "pane_tty": "/dev/old",
+                "attached_at": "2026-01-01T00:00:00Z"
+            }}}
+        });
+
+        assert!(refresh_already_bound_receiver_observation(
+            &mut state,
+            &observed_pane(),
+            Some("/tmp/team-agent-live.sock"),
+            Some("team-a"),
+        ));
+        let receiver = &state["leader_receiver"];
+        assert_eq!(receiver["owner_epoch"], json!(10));
+        assert_eq!(receiver["owner_agent_id"], json!("leader"));
+        assert_eq!(receiver["session_name"], json!("new-session"));
+        assert_eq!(receiver["window_name"], json!("new-window"));
+        assert_eq!(receiver["pane_tty"], json!("/dev/ttys007"));
+        assert_eq!(receiver["tmux_socket"], json!("/tmp/team-agent-live.sock"));
+        assert_ne!(receiver["attached_at"], json!("2026-01-01T00:00:00Z"));
+        assert_eq!(
+            state["teams"]["team-a"]["leader_receiver"]["session_name"],
+            json!("new-session")
+        );
+        assert_eq!(
+            state["teams"]["team-a"]["leader_receiver"]["owner_epoch"],
+            json!(10)
+        );
+    }
 }

package/crates/team-agent/src/leader/start.rs

@@ -816,7 +816,13 @@ fn persist_managed_leader_binding(
         .with_team_owner(owner)
         .with_owner_epoch(owner_epoch);
     crate::state::ownership::write_owner(&mut state, identity.team_id.as_str(), record);
-    crate::state::persist::save_runtime_state(workspace, &state)?;
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::LeaderStartBinding {
+            team_key: identity.team_id.as_str(),
+            transport_kind: "managed",
+        },
+        &state,
+    )?;
     Ok(())
 }
 
@@ -933,7 +939,13 @@ fn persist_exec_provider_leader_binding(
         .with_team_owner(owner)
         .with_owner_epoch(owner_epoch);
     crate::state::ownership::write_owner(&mut state, identity.team_id.as_str(), record);
-    crate::state::persist::save_runtime_state(workspace, &state)?;
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::LeaderStartBinding {
+            team_key: identity.team_id.as_str(),
+            transport_kind: "exec_provider",
+        },
+        &state,
+    )?;
     Ok(())
 }
 
@@ -1124,7 +1136,13 @@ fn refresh_managed_leader_provider_binding(
         .with_team_owner(owner)
         .with_owner_epoch(existing_epoch);
     crate::state::ownership::write_owner(&mut state, team_key, record);
-    crate::state::persist::save_runtime_state(workspace, &state)?;
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::LeaderStartBinding {
+            team_key,
+            transport_kind: "managed_reentry",
+        },
+        &state,
+    )?;
     Ok(())
 }
 
@@ -1169,7 +1187,13 @@ fn persist_external_leader_topology_marker(
             teams.insert(identity.team_id.as_str().to_string(), entry);
         }
     }
-    crate::state::persist::save_runtime_state(workspace, &state)?;
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::LeaderStartBinding {
+            team_key: identity.team_id.as_str(),
+            transport_kind: "external",
+        },
+        &state,
+    )?;
     Ok(())
 }