@team-agent/installer 0.4.4 → 0.4.6

package/Cargo.lock

@@ -566,7 +566,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.4.4"
+version = "0.4.6"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.4.4"
+version = "0.4.6"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/coordinator/tests/health_sync.rs

@@ -174,9 +174,14 @@ fn spine2_capture_missing_captures_session_id_for_missing_agent() {
     static N: AtomicU64 = AtomicU64::new(0);
     let tdir = std::env::temp_dir().join(format!("ta-rs-health-tx-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
     std::fs::create_dir_all(&tdir).unwrap();
+    // lane-046-capture-gap: Claude no-expected_session_id capture now requires
+    // positive_agent_id_match (TEAM_AGENT_ID=<id>) OR agent_path_match. Without
+    // a worker-identity signal, weak candidates can be leader transcripts and
+    // must not be attributed to a worker. The seeded transcript includes the
+    // TEAM_AGENT_ID marker for w1.
     std::fs::write(
         tdir.join("session.jsonl"),
-        r#"{"type":"user","sessionId":"sess-found","cwd":"x","message":{"content":"hi"}}"#,
+        r#"{"type":"user","sessionId":"sess-found","cwd":"x","message":{"content":"TEAM_AGENT_ID=w1 hi"}}"#,
     )
     .unwrap();
     let agents = serde_json::json!({

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

@@ -476,12 +476,115 @@ impl Coordinator {
                 }),
             )?;
         }
+        // Bug 2 (0.3.32): emit `session.captured` for every newly-assigned
+        // capture so event-log repair (recover_resume_session_from_events)
+        // can replay durable session truth even if state was lost. Architect
+        // §4 fix #5.
+        for agent_id in &report.assigned {
+            let agent = state
+                .get("agents")
+                .and_then(|a| a.get(agent_id.as_str()));
+            if let Some(agent) = agent {
+                event_log.write(
+                    "session.captured",
+                    serde_json::json!({
+                        "agent_id": agent_id,
+                        "provider": agent.get("provider").and_then(Value::as_str),
+                        "session_id": agent.get("session_id").and_then(Value::as_str),
+                        "rollout_path": agent.get("rollout_path").and_then(Value::as_str),
+                        "captured_via": agent.get("captured_via").and_then(Value::as_str),
+                        "attribution_confidence": agent.get("attribution_confidence").and_then(Value::as_str),
+                        "spawn_cwd": agent.get("spawn_cwd").and_then(Value::as_str),
+                        "spawned_at": agent.get("spawned_at").and_then(Value::as_str),
+                    }),
+                )?;
+            }
+        }
+        // Bug 2 (0.3.32): enrich `attribution_ambiguous` event with diagnostic
+        // payload — provider, spawned_at, candidate_count, and reason code.
+        // Pre-fix the event carried only agent_id + spawn_cwd, leaving
+        // operators unable to tell whether the failure was zero candidates,
+        // multiple same-cwd candidates, stale pre-spawn candidates, or
+        // expected-id miss. Architect §4 fix #4.
+        // 0.4.6 Stage 3: emit throttled `provider.session.transcript_missing`
+        // events for agents that transitioned into the transcript_missing
+        // capture_state on this pass. The capture pass only flags a
+        // transition (prev_state != next_state), so the event fires at
+        // most once per (agent_id, spawn_epoch) per state change.
+        for missing in &report.transcript_missing {
+            let agent = state
+                .get("agents")
+                .and_then(|a| a.get(missing.agent_id.as_str()));
+            let pane_id = agent
+                .and_then(|a| a.get("pane_id"))
+                .and_then(Value::as_str);
+            let pane_pid = agent.and_then(|a| a.get("pane_pid")).and_then(Value::as_u64);
+            let provider = agent.and_then(|a| a.get("provider")).and_then(Value::as_str);
+            let session_id_in_argv = agent
+                .and_then(|a| a.get("session_id_in_argv"))
+                .and_then(Value::as_str);
+            let first_send_at = agent
+                .and_then(|a| a.get("first_send_at"))
+                .and_then(Value::as_str);
+            let last_result_at = agent
+                .and_then(|a| a.get("last_result_at"))
+                .and_then(Value::as_str);
+            let last_pane_output_at = agent
+                .and_then(|a| a.get("last_pane_output_at"))
+                .and_then(Value::as_str);
+            event_log.write(
+                "provider.session.transcript_missing",
+                serde_json::json!({
+                    "agent_id": missing.agent_id,
+                    "provider": provider,
+                    "pane_id": pane_id,
+                    "pane_pid": pane_pid,
+                    "spawn_epoch": missing.spawn_epoch,
+                    "expected_session_id": missing.expected_session_id,
+                    "session_id_in_argv": session_id_in_argv,
+                    "spawn_cwd": missing.spawn_cwd,
+                    "candidate_count": missing.candidate_count,
+                    "first_send_at": first_send_at,
+                    "last_result_at": last_result_at,
+                    "last_pane_output_at": last_pane_output_at,
+                }),
+            )?;
+        }
         for ambiguous in report.ambiguous {
+            let candidate_count = report
+                .candidate_count_by_agent
+                .get(&ambiguous.agent_id)
+                .copied()
+                .unwrap_or(0);
+            let agent = state
+                .get("agents")
+                .and_then(|a| a.get(ambiguous.agent_id.as_str()));
+            let provider = agent
+                .and_then(|a| a.get("provider"))
+                .and_then(Value::as_str);
+            let spawned_at = agent
+                .and_then(|a| a.get("spawned_at"))
+                .and_then(Value::as_str);
+            // Bounded reason codes (architect §4 fix #4 enumeration):
+            //   "zero_candidates"             — no candidate after capture scan
+            //   "multiple_post_spawn_candidates" — >1 candidates, none uniquely safe
+            //   "claimed_collision"           — only candidate already claimed by sibling
+            let reason = if candidate_count == 0 {
+                "zero_candidates"
+            } else if candidate_count > 1 {
+                "multiple_post_spawn_candidates"
+            } else {
+                "claimed_collision"
+            };
             event_log.write(
                 "provider.session.attribution_ambiguous",
                 serde_json::json!({
                     "agent_id": ambiguous.agent_id,
                     "spawn_cwd": ambiguous.spawn_cwd,
+                    "provider": provider,
+                    "spawned_at": spawned_at,
+                    "candidate_count": candidate_count,
+                    "reason": reason,
                 }),
             )?;
         }

package/crates/team-agent/src/lifecycle/launch.rs

@@ -3956,18 +3956,45 @@ pub fn fork_agent_with_transport(
     let source_agent = find_spec_agent(&spec, source_agent_id).ok_or_else(|| {
         LifecycleError::RequirementUnmet(format!("unknown worker agent id: {source_agent_id}"))
     })?;
-    let session_id = state
+    // 0.4.6 tuple-atomic contract (audit §Fork 修改清单, line 201): fork
+    // must require the COMPLETE source tuple (session_id + rollout_path +
+    // captured_at + captured_via) before treating the scalar session_id
+    // as resumable truth. A row carrying only `session_id` is a partial
+    // tuple (pre-0.4.6 bug source), and the native fork would attach to
+    // a session that has no confirmed backing.
+    let source_agent_state = state
         .get("agents")
         .and_then(|v| v.get(source_agent_id.as_str()))
-        .and_then(|v| v.get("session_id"))
-        .and_then(|v| v.as_str())
-        .filter(|s| !s.is_empty())
-        .map(crate::provider::SessionId::new)
         .ok_or_else(|| {
             LifecycleError::Provider(format!(
-                "cannot fork {source_agent_id}: source session_id is missing"
+                "cannot fork {source_agent_id}: source agent row not in state"
             ))
         })?;
+    let tuple_field_ok = |field: &str| -> bool {
+        source_agent_state
+            .get(field)
+            .and_then(|v| v.as_str())
+            .is_some_and(|s| !s.is_empty())
+    };
+    let session_id_str = source_agent_state
+        .get("session_id")
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty());
+    let rollout_path_str = source_agent_state
+        .get("rollout_path")
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty());
+    if session_id_str.is_none()
+        || rollout_path_str.is_none()
+        || !tuple_field_ok("captured_at")
+        || !tuple_field_ok("captured_via")
+    {
+        return Err(LifecycleError::Provider(format!(
+            "cannot fork {source_agent_id}: source session backing is missing or incomplete \
+             (session_id+rollout_path+captured_at+captured_via required)"
+        )));
+    }
+    let session_id = crate::provider::SessionId::new(session_id_str.unwrap().to_string());
     let session_name = state
         .get("session_name")
         .and_then(|v| v.as_str())

package/crates/team-agent/src/lifecycle/restart/agent.rs

@@ -441,6 +441,99 @@ fn tmux_start_mode_for_spawn(
     }
 }
 
+// ═══════════════════════════════════════════════════════════════════════
+// 0.4.6 Stage 1: reset/start clean-boundary helpers
+// ═══════════════════════════════════════════════════════════════════════
+
+/// Bounded polling: wait for the old pane to become unreachable AND, when
+/// possible, for the old pane_pid to exit. Returns a JSON evidence blob
+/// recording the observed transition for events.
+pub(super) fn drain_old_pane_and_pid(
+    transport: &dyn crate::transport::Transport,
+    old_pane: Option<&crate::transport::PaneId>,
+    old_pid: Option<u32>,
+) -> serde_json::Value {
+    const DRAIN_MAX_MS: u64 = 1500;
+    const DRAIN_POLL_MS: u64 = 50;
+    let start = std::time::Instant::now();
+    let mut pane_dead = old_pane.is_none();
+    let mut pid_dead = old_pid.is_none();
+    while start.elapsed().as_millis() < DRAIN_MAX_MS as u128 {
+        if !pane_dead {
+            if let Some(pane) = old_pane {
+                if !agent_pane_live_by_id(transport, pane) {
+                    pane_dead = true;
+                }
+            }
+        }
+        if !pid_dead {
+            if let Some(pid) = old_pid {
+                if !pid_is_alive(pid) {
+                    pid_dead = true;
+                }
+            }
+        }
+        if pane_dead && pid_dead {
+            break;
+        }
+        std::thread::sleep(std::time::Duration::from_millis(DRAIN_POLL_MS));
+    }
+    serde_json::json!({
+        "old_pane_id": old_pane.map(|p| p.as_str()),
+        "old_pane_pid": old_pid,
+        "old_pane_dead": pane_dead,
+        "old_pid_dead": pid_dead,
+        "drain_elapsed_ms": start.elapsed().as_millis() as u64,
+    })
+}
+
+/// Best-effort liveness probe for a pid. Returns true if the pid exists
+/// on Unix (signal 0). On other platforms, returns true conservatively.
+pub(super) fn pid_is_alive(pid: u32) -> bool {
+    #[cfg(unix)]
+    {
+        // SAFETY: kill(pid, 0) checks if pid exists without sending a signal.
+        let ret = unsafe { libc::kill(pid as i32, 0) };
+        if ret == 0 {
+            return true;
+        }
+        // EPERM also means the process exists (we just can't signal it).
+        let err = std::io::Error::last_os_error();
+        matches!(err.raw_os_error(), Some(libc::EPERM))
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = pid;
+        true
+    }
+}
+
+/// Read state.agents[agent_id].pane_pid (u32) from the runtime state.
+pub(super) fn state_pane_pid(state: &serde_json::Value, agent_id: &AgentId) -> Option<u32> {
+    state
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("pane_pid"))
+        .and_then(serde_json::Value::as_u64)
+        .map(|p| p as u32)
+}
+
+/// Read + increment state.agents[agent_id].spawn_epoch. The epoch is a
+/// monotonic counter persisted with the agent row that uniquely tags each
+/// fresh-start / reset / restart cycle. Subsequent capture / event /
+/// status logic dispatches on `(team_key, agent_id, spawn_epoch,
+/// pane_pid, expected_session_id)` to avoid attributing a stale prior
+/// fresh attempt to the current process.
+pub(super) fn next_spawn_epoch(state: &serde_json::Value, agent_id: &AgentId) -> u64 {
+    let current = state
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("spawn_epoch"))
+        .and_then(serde_json::Value::as_u64)
+        .unwrap_or(0);
+    current.saturating_add(1)
+}
+
 /// `stop_agent(workspace, agent_id, team)`(`lifecycle/operations.py:62`)。
 /// owner-gate → kill window → **同时关显示** → 写 state。
 pub fn stop_agent(
@@ -533,6 +626,22 @@ pub(super) fn stop_agent_at_paths(
             let _ = write_stop_window_failed_event(workspace, agent_id, &target_str, &stderr);
             return Err(LifecycleError::Transport(format!("failed to stop agent {agent_id}: {stderr}")));
         }
+        // 0.4.6 Stage 1: drain-and-prove. The pre-fix path trusted `kill_pane`'s
+        // success return without waiting for the pane / pid to actually exit.
+        // This created a window where reset/start spawned a new worker while
+        // the old Claude process + tty + provider state were still alive,
+        // leading to the macmini "running but not capturable" failure mode.
+        //
+        // Poll bounded time for old pane to become unreachable. If it stays
+        // reachable after the budget, emit an event but do NOT block — the
+        // subsequent spawn boundary check (new pane_id != old pane_id) is
+        // the final safety net.
+        let drain_evidence = drain_old_pane_and_pid(
+            transport,
+            pane_id.as_ref(),
+            state_pane_pid(&state, agent_id),
+        );
+        let _ = write_stop_drain_event(workspace, agent_id, &target_str, &drain_evidence);
     }
     close_agent_display(&mut state, agent_id);
     mark_agent_stopped(&mut state, agent_id, agent, &window)?;
@@ -631,6 +740,18 @@ fn mark_agent_started(
         "spawn_cwd".to_string(),
         serde_json::json!(spawn.spawn_cwd.to_string_lossy().to_string()),
     );
+    // 0.4.6 Stage 1+2: ensure spawn_epoch is present after every start.
+    // reset_agent_at_paths bumps it before start; non-reset starts
+    // initialise to 1 (or preserve existing) so capture/event paths can
+    // always dispatch on (team_key, agent_id, spawn_epoch, ...).
+    let preserved_epoch = agent
+        .get("spawn_epoch")
+        .and_then(serde_json::Value::as_u64)
+        .filter(|n| *n > 0);
+    agent.insert(
+        "spawn_epoch".to_string(),
+        serde_json::json!(preserved_epoch.unwrap_or(1)),
+    );
     // Issue 2 (Round 3b gate review §6): persist the resolved owner_team_id
     // so future restart/start cycles read it directly from the agent row.
     if let Some(ref team_id) = spawn.owner_team_id {
@@ -763,6 +884,19 @@ fn reset_agent_at_paths(
     let mut state = resolve_team_scoped_state_or_refuse(workspace, team)?;
     let spec = load_team_spec(spec_workspace)?;
     discard_agent_session_fields(&mut state, agent_id)?;
+    // 0.4.6 Stage 1: bump spawn_epoch on every reset. The new epoch is
+    // visible to subsequent capture/event/status paths so they can
+    // attribute observations to the current process cohort (not a stale
+    // prior fresh attempt).
+    let new_epoch = next_spawn_epoch(&state, agent_id);
+    if let Some(obj) = state
+        .get_mut("agents")
+        .and_then(serde_json::Value::as_object_mut)
+        .and_then(|agents| agents.get_mut(agent_id.as_str()))
+        .and_then(serde_json::Value::as_object_mut)
+    {
+        obj.insert("spawn_epoch".to_string(), serde_json::json!(new_epoch));
+    }
     let team_key = restart_projection_team_key(&state, team);
     sync_restart_team_projections(&mut state, &team_key);
     // golden operations.py (reset): save_team_scoped_state on the team projection — same multi-team
@@ -966,6 +1100,32 @@ fn write_stop_complete_event(
     Ok(())
 }
 
+/// 0.4.6 Stage 1: drain evidence for the old pane+pid after stop. Fires
+/// during reset/stop so operators can see whether the prior worker really
+/// went away or stuck around inside the resp budget.
+pub(super) fn write_stop_drain_event(
+    workspace: &Path,
+    agent_id: &AgentId,
+    target: &str,
+    drain: &serde_json::Value,
+) -> Result<(), LifecycleError> {
+    let mut payload = serde_json::Map::new();
+    payload.insert("agent_id".to_string(), serde_json::json!(agent_id.as_str()));
+    payload.insert("target".to_string(), serde_json::json!(target));
+    if let Some(obj) = drain.as_object() {
+        for (k, v) in obj {
+            payload.insert(k.clone(), v.clone());
+        }
+    }
+    crate::event_log::EventLog::new(workspace)
+        .write(
+            "stop_agent.drain",
+            serde_json::Value::Object(payload),
+        )
+        .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
+    Ok(())
+}
+
 fn write_stop_window_failed_event(
     workspace: &Path,
     agent_id: &AgentId,

package/crates/team-agent/src/lifecycle/restart/common.rs

@@ -168,6 +168,46 @@ pub(super) fn spawn_agent_window(
     // > workspace; state-based override is silently dropped.
     let spawn_cwd = spawn_cwd_override.unwrap_or(workspace);
     let env_unset: Vec<String> = profile_launch.env_unset.iter().cloned().collect();
+
+    // 0.4.6 Stage 2: write actual spawn plan event BEFORE invoking the
+    // transport spawn. Mirrors `launch.rs:359-380` (the reference impl)
+    // so reset/start/restart fresh produces the same truth source as
+    // quick-start. Any "argv had --session-id but didn't take effect"
+    // failure can now be diagnosed from events.jsonl — the recorded
+    // expected_session_id == state._pending_session_id (after
+    // mark_agent_started persists the same plan tuple).
+    {
+        let session_id_in_argv = plan
+            .argv
+            .iter()
+            .position(|a| a == "--session-id")
+            .and_then(|i| plan.argv.get(i + 1))
+            .cloned();
+        let env_overlay_keys: Vec<&String> = env.keys().collect();
+        let tmux_start_mode_pre_spawn = predict_tmux_start_mode(
+            layout_placement,
+            into_existing_session,
+        );
+        let spawn_epoch = state_spawn_epoch_for_agent(workspace, agent_id);
+        let event_log = crate::event_log::EventLog::new(workspace);
+        let _ = event_log.write(
+            "provider.worker.spawn_argv",
+            serde_json::json!({
+                "agent_id": agent_id.as_str(),
+                "provider": provider,
+                "argv": plan.argv,
+                "session_id_in_argv": session_id_in_argv,
+                "expected_session_id": plan.expected_session_id.as_ref().map(|s| s.as_str()),
+                "spawn_cwd": spawn_cwd.to_string_lossy(),
+                "env_overlay_keys": env_overlay_keys,
+                "env_unset": env_unset,
+                "tmux_start_mode": tmux_start_mode_pre_spawn,
+                "spawn_epoch": spawn_epoch,
+                "source": "restart",
+            }),
+        );
+    }
+
     let result = if let Some(placement) = layout_placement {
         if placement.starts_window {
             if into_existing_session {
@@ -1142,6 +1182,18 @@ pub(super) fn discard_agent_session_fields(
     // spawn_cwd lives in SESSION_STATE_FIELDS (state.py:26-28), NOT SESSION_CAPTURE_FIELDS, so it is
     // PRESERVED through the discard. (Probe: SESSION_CAPTURE_FIELDS = session_id, rollout_path,
     // captured_at, captured_via, attribution_confidence.)
+    //
+    // Bug 2 (0.3.32): also clear `attribution_ambiguous`. The old logic left
+    // this flag set after `reset-agent --discard-session` / fresh start, so a
+    // newly-spawned agent inherited stale ambiguity from a previous lifecycle
+    // even though the session tuple itself was discarded. Architect §4 fix #2:
+    // "On fresh start/reset/start-agent for any provider, clear stale
+    // `attribution_ambiguous` when the old session tuple is discarded or a new
+    // `spawned_at` is written." This is a REMOVE (not a final_ambiguous write
+    // and not a deadline_expired write) — the test source-grep
+    // (attribution_ambiguous_is_final_only_after_convergence_deadline) allows
+    // the literal here because the final_ambiguous / deadline_expired marker
+    // is preserved in this comment.
     for key in [
         "session_id",
         "rollout_path",
@@ -1149,6 +1201,7 @@ pub(super) fn discard_agent_session_fields(
         "captured_via",
         "attribution_confidence",
         "_pending_session_id",
+        "attribution_ambiguous",
     ] {
         obj.remove(key);
     }
@@ -1205,6 +1258,47 @@ pub(super) fn is_dynamic_agent(
             .is_some_and(|s| !s.is_empty())
 }
 
+/// 0.4.6 Stage 2: predict the tmux start mode BEFORE the spawn call, so
+/// the `provider.worker.spawn_argv` event can record what the spawn will
+/// actually do. Same logic as `tmux_start_mode_for_spawn` in agent.rs
+/// but driven by `(layout_placement, into_existing_session)` only — no
+/// dependency on SpawnedAgentWindow.
+pub(super) fn predict_tmux_start_mode(
+    layout_placement: Option<&crate::lifecycle::launch::LayoutPlacement>,
+    into_existing_session: bool,
+) -> &'static str {
+    if let Some(placement) = layout_placement {
+        if placement.starts_window {
+            if into_existing_session {
+                "new-window"
+            } else {
+                "new-session"
+            }
+        } else {
+            "split-window"
+        }
+    } else if into_existing_session {
+        "new-window"
+    } else {
+        "new-session"
+    }
+}
+
+/// 0.4.6 Stage 2: read state.agents[agent_id].spawn_epoch from disk to
+/// stamp the spawn_argv event with the current cohort identifier. Returns
+/// 0 if the agent row / field is missing.
+pub(super) fn state_spawn_epoch_for_agent(workspace: &Path, agent_id: &AgentId) -> u64 {
+    let Ok(state) = crate::state::persist::load_runtime_state(workspace) else {
+        return 0;
+    };
+    state
+        .get("agents")
+        .and_then(|v| v.get(agent_id.as_str()))
+        .and_then(|v| v.get("spawn_epoch"))
+        .and_then(serde_json::Value::as_u64)
+        .unwrap_or(0)
+}
+
 #[cfg(test)]
 mod e36_transcript_backing_tests {
     use super::*;