@team-agent/installer 0.3.22 → 0.3.24

package/crates/team-agent/src/state/projection.rs

@@ -298,6 +298,11 @@ pub fn project_top_level_view(state: &Value, team_key: &str) -> Value {
         team_entry_from_state(state, team_key).and_then(Value::as_object).cloned().unwrap_or_default();
     let mut p = entry_obj.clone(); // projection = deepcopy(entry)
     // setdefault session_name/team_dir ← entry.get(...)(缺则插,值可为 null)。
+    // **0.3.24 excision** (U1-A real-machine RED v2): the ff38ab9 root-state
+    // `or_else` fallback was reverted along with the wave-2 U1-A drift fallback,
+    // since this projection change had no other consumer. v0.3.25 will re-introduce
+    // this together with the writer-shape + rediscover-writer fix — see
+    // `.team/artifacts/u1-a-realmachine-v2-fix-or-excise.md`.
     if !p.contains_key("session_name") {
         p.insert("session_name".to_string(), entry_obj.get("session_name").cloned().unwrap_or(Value::Null));
     }

package/crates/team-agent/src/tmux_backend/tests.rs

@@ -526,6 +526,52 @@ CaptureMissingToken, not the static CaptureContainsToken false-positive"
         );
     }
 
+    #[test]
+    fn inject_waits_for_token_visibility_before_enter() {
+        let text = "hello [team-agent-token:e31]".to_string();
+        let marker_visible = format!("{text}\n");
+        let (be, rec) = backend_with(
+            MockResp::Out(ok("")),
+            vec![
+                MockResp::Out(ok("")), // set-buffer
+                MockResp::Out(ok("")), // paste-buffer
+                MockResp::Out(ok("")), // delete-buffer
+                MockResp::Out(ok("")), // pasted-content prompt poll 1
+                MockResp::Out(ok("")), // pasted-content prompt poll 2
+                MockResp::Out(ok("")), // pasted-content prompt poll 3
+                MockResp::Out(ok("")), // pasted-content prompt poll 4
+                MockResp::Out(ok("")), // pasted-content prompt poll 5
+                MockResp::Out(ok("")), // token gate: not visible yet
+                MockResp::Out(ok("")), // token gate: still not visible
+                MockResp::Out(ok(&marker_visible)), // token gate: visible, Enter may fire
+                MockResp::Out(ok("")), // send-keys Enter
+            ],
+        );
+
+        let report = be
+            .inject(&Target::Pane(PaneId::new("%7")), &InjectPayload::Text(text), Key::Enter, true)
+            .expect("inject");
+        let calls = rec.lock().unwrap().clone();
+        let submit_index = calls
+            .iter()
+            .position(|argv| argv.get(1).map(String::as_str) == Some("send-keys"))
+            .expect("inject must eventually send Enter");
+        let captures_before_submit = calls[..submit_index]
+            .iter()
+            .filter(|argv| argv.get(1).map(String::as_str) == Some("capture-pane"))
+            .count();
+
+        assert!(
+            captures_before_submit >= super::PASTED_CONTENT_APPEAR_POLLS as usize + 3,
+            "Enter must wait until the pasted token is visible; calls={calls:?}"
+        );
+        assert_eq!(report.inject_verification, InjectVerification::CaptureContainsToken);
+        assert_eq!(
+            report.submit_verification,
+            SubmitVerification::EnterSentWithoutPlaceholderCheck
+        );
+    }
+
     #[test]
     fn send_keys_cancel_mode_queries_mode_and_dispatches_cancel_argv() {
         let (be, rec) = backend_with(

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

@@ -845,16 +845,28 @@ fn token_visible_in_capture(
     }
 }
 
-/// U1 #7: capture the pane just before submit and report whether the just-pasted
-/// token marker is actually visible. `Ok(None)` for non-token payloads (nothing to
-/// check). `Ok(Some(false))` means the paste silently dropped — a false-positive that
-/// the static `inject_verification_for_payload` would have reported as success.
+/// U1 #7 / E31: wait briefly for the just-pasted token marker before submitting.
+/// `Ok(None)` for non-token payloads (nothing to check). `Ok(Some(false))` means the
+/// paste did not become visible before the Python-parity fallback delay.
 fn pre_submit_token_visible(
     backend: &TmuxBackend,
     target: &Target,
     payload: &InjectPayload,
 ) -> Result<Option<bool>, TransportError> {
-    token_visible_in_capture(backend, target, payload)
+    if payload_token_marker(payload).is_none() {
+        return Ok(None);
+    }
+    for attempt in 0..PASTED_CONTENT_APPEAR_POLLS {
+        if let Some(true) = token_visible_in_capture(backend, target, payload)? {
+            return Ok(Some(true));
+        }
+        if attempt + 1 < PASTED_CONTENT_APPEAR_POLLS {
+            std::thread::sleep(Duration::from_millis(25));
+        }
+    }
+    // Python waits 250ms between paste-buffer and Enter to let bracketed paste settle.
+    std::thread::sleep(Duration::from_millis(250));
+    Ok(Some(false))
 }
 
 const TOKEN_POST_SUBMIT_READBACK_POLLS: u32 = 5;

package/crates/team-agent/src/transport/test_support.rs

@@ -37,6 +37,18 @@ struct OfflineState {
     inject_targets: Vec<Target>,
     inject_payloads: Vec<String>,
     tmux_endpoint: Option<String>,
+    /// U1-B contract: when set, `list_targets()` returns `TransportError::MuxUnavailable`
+    /// — used to model tmux server jitter (subprocess-fork-failed level). The whole
+    /// resolve must DEFER, not silently coerce to an empty vec.
+    list_targets_error: Option<String>,
+    /// U1-C / general: pre-staged `capture()` payload, keyed by target stringification.
+    /// `Target::Pane(p)` keys as `p.as_str()`; `Target::SessionWindow{session,window}`
+    /// keys as `format!("{session}:{window}")`. A miss returns empty text (current
+    /// default behaviour).
+    capture_text: BTreeMap<String, String>,
+    /// U1-C Tail-peek contract: every `capture()` call records its `CaptureRange`,
+    /// in order, so a test can prove the delivery peek site narrowed Full → Tail(80).
+    capture_ranges: Vec<CaptureRange>,
 }
 
 impl Default for OfflineState {
@@ -57,6 +69,9 @@ impl Default for OfflineState {
             inject_targets: Vec::new(),
             inject_payloads: Vec::new(),
             tmux_endpoint: None,
+            list_targets_error: None,
+            capture_text: BTreeMap::new(),
+            capture_ranges: Vec::new(),
         }
     }
 }
@@ -127,6 +142,40 @@ impl OfflineTransport {
         self
     }
 
+    /// U1-B: stage a `list_targets()` error to model tmux server jitter. While set,
+    /// every call returns `Err(TransportError::MuxUnavailable{detail})`. Pass an
+    /// empty string to clear via re-builder if needed.
+    pub fn with_list_targets_error(self, detail: impl Into<String>) -> Self {
+        self.with_state(|state| state.list_targets_error = Some(detail.into()));
+        self
+    }
+
+    /// Pre-stage `capture()` output for a `Target::Pane(pane_id)` key.
+    pub fn with_capture_for_pane(
+        self,
+        pane_id: impl Into<String>,
+        text: impl Into<String>,
+    ) -> Self {
+        self.with_state(|state| {
+            state.capture_text.insert(pane_id.into(), text.into());
+        });
+        self
+    }
+
+    /// Pre-stage `capture()` output for a `Target::SessionWindow{session,window}` key.
+    pub fn with_capture_for_session_window(
+        self,
+        session: impl Into<String>,
+        window: impl Into<String>,
+        text: impl Into<String>,
+    ) -> Self {
+        let key = format!("{}:{}", session.into(), window.into());
+        self.with_state(|state| {
+            state.capture_text.insert(key, text.into());
+        });
+        self
+    }
+
     pub fn calls(&self) -> Vec<&'static str> {
         self.with_state(|state| state.calls.clone())
     }
@@ -163,6 +212,12 @@ impl OfflineTransport {
         self.with_state(|state| state.inject_payloads.clone())
     }
 
+    /// All `capture()` ranges observed, in call order. Used by U1-C Tail-peek
+    /// contracts to prove the delivery peek site requested Tail rather than Full.
+    pub fn capture_ranges(&self) -> Vec<CaptureRange> {
+        self.with_state(|state| state.capture_ranges.clone())
+    }
+
     fn record(&self, call: &'static str) {
         self.with_state(|state| state.calls.push(call));
     }
@@ -294,11 +349,21 @@ impl Transport for OfflineTransport {
 
     fn capture(
         &self,
-        _target: &Target,
+        target: &Target,
         range: CaptureRange,
     ) -> Result<CapturedText, TransportError> {
-        self.record("capture");
-        Ok(CapturedText { text: String::new(), range })
+        let key = match target {
+            Target::Pane(p) => p.as_str().to_string(),
+            Target::SessionWindow { session, window } => {
+                format!("{}:{}", session.as_str(), window.as_str())
+            }
+        };
+        let text = self.with_state(|state| {
+            state.calls.push("capture");
+            state.capture_ranges.push(range);
+            state.capture_text.get(&key).cloned().unwrap_or_default()
+        });
+        Ok(CapturedText { text, range })
     }
 
     fn query(
@@ -329,10 +394,18 @@ impl Transport for OfflineTransport {
     }
 
     fn list_targets(&self) -> Result<Vec<PaneInfo>, TransportError> {
-        Ok(self.with_state(|state| {
+        // U1-B: when `with_list_targets_error` is set, return a real Err so the
+        // caller sees server jitter rather than a coerced empty vec.
+        if let Some(detail) = self.with_state(|state| {
             state.calls.push("list_targets");
-            state.targets.clone()
-        }))
+            state.list_targets_error.clone()
+        }) {
+            return Err(TransportError::MuxUnavailable {
+                backend: BackendKind::Tmux,
+                detail,
+            });
+        }
+        Ok(self.with_state(|state| state.targets.clone()))
     }
 
     fn has_session(&self, _session: &SessionName) -> Result<bool, TransportError> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.3.22",
-    "@team-agent/cli-darwin-x64": "0.3.22",
-    "@team-agent/cli-linux-x64": "0.3.22"
+    "@team-agent/cli-darwin-arm64": "0.3.24",
+    "@team-agent/cli-darwin-x64": "0.3.24",
+    "@team-agent/cli-linux-x64": "0.3.24"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/SKILL.md

@@ -158,6 +158,7 @@ For diagnosis, run `team-agent profile show deepseek --workspace . --json`; neve
 - Quick-start generated files stay inside the selected team directory, for example `.team/current/` or `.team/alpha/`; do not create or expect root `team.spec.yaml` or `team_state.md`.
 - Use `team-agent quick-start ./roles --team-id alpha` to create a second generated team under `.team/alpha/`, or pass an existing team directory directly such as `team-agent quick-start .team/alpha`.
 - `quick-start` is for fresh startup from role docs. If stored worker context already exists for that runtime session, follow the returned `team-agent restart . --team <session>` action to resume it. Use `--fresh` only when the user explicitly accepts new blank worker contexts.
+- If the user explicitly asks a worker to create or operate a nested child team, first read `references/team-in-team.md`. Child teams must use an independent child workspace, never the parent `.team/current`.
 - `team-agent send --watch-result coder "Do the bounded task"` sends a direct worker message, returns after delivery, and lets the coordinator collect/report completion asynchronously.
 - After `send --watch-result` succeeds, do not run `sleep`, `status`, `inbox`, or `collect` polling loops unless the user explicitly asks for diagnosis; the coordinator will notify the leader when the result arrives.
 - `team-agent send --task task_initial "Start"` routes by task.
@@ -214,7 +215,7 @@ Removing a worker at runtime is the symmetric `team-agent remove-agent <agent> -
 
 ## Worker Protocol
 
-Workers do not run nested Team Agent teams. Workers only provide the target and content for progress, and a short completion summary at the end:
+Workers normally do not run nested Team Agent teams. When the user or leader explicitly asks for a child team, follow `references/team-in-team.md`; otherwise workers only provide the target and content for progress, and a short completion summary at the end:
 
 ```text
 team_orchestrator.send_message(to="leader", content="short progress or blocker")

package/skills/team-agent/references/team-in-team.md

@@ -0,0 +1,127 @@
+# Team-In-Team Reference
+
+This reference is for explicitly requested nested Team Agent teams. Use it only when the user or leader asks a worker to create or operate a child team. For normal work, a worker should stay inside its parent team and report through `team_orchestrator`.
+
+## Safety Rules
+
+- Use the Team Agent framework skill and `team-agent` CLI. Do not use a provider's built-in agent-team feature when the user asked for Team Agent.
+- Never create a child team in the parent team's `.team/current` directory.
+- Never edit, delete, or reuse files under the parent team's `.team/current`.
+- Never shut down a team just because `.team/current` is already occupied. In a nested setup, that is probably the parent team; shutting it down can kill the main node.
+- A child team needs its own workspace directory. The role-doc directory is not the child workspace.
+- MCP tools are team-scoped. A worker must not try to widen `team_orchestrator.send_message` to another team.
+
+## Child Workspace
+
+Pick an independent directory before writing `TEAM.md` or agent role docs. A safe default is a child workspace under the parent workspace, but outside the parent `.team/current`:
+
+```bash
+PARENT_WORKSPACE="$PWD"
+case "$PARENT_WORKSPACE" in
+  */.team/current|*/.team/current/*)
+    echo "Refusing to create a child team from parent .team/current; cd to the parent workspace root first." >&2
+    exit 1
+    ;;
+esac
+CHILD_TEAM="child-review-team"
+CHILD_WORKSPACE="$PARENT_WORKSPACE/.team/children/review-$(date +%Y%m%d%H%M%S)"
+mkdir -p "$CHILD_WORKSPACE"
+cd "$CHILD_WORKSPACE"
+mkdir -p .team/current/agents
+```
+
+Then create the child team's files inside the child workspace:
+
+```bash
+cat > .team/current/TEAM.md <<'EOF'
+---
+name: child-review-team
+objective: Run a bounded child-team task and report to the parent worker.
+dangerous_auto_approve: false
+fast: false
+---
+
+Child team config only.
+EOF
+
+cat > .team/current/agents/reviewer.md <<'EOF'
+---
+name: reviewer
+role: Independent Reviewer
+provider: codex
+tools:
+  - fs_read
+  - fs_list
+  - mcp_team
+---
+
+Review only the files and instructions provided by the child-team leader.
+Report findings with team_orchestrator.report_result exactly once.
+EOF
+
+team-agent quick-start .team/current
+```
+
+If `quick-start` reports that `current` or a tmux session already exists, do not run `shutdown`. Move to a new child workspace or change the child team name.
+
+## Parent Protection
+
+The parent worker is also the child team's leader. Keep the two scopes separate:
+
+- Parent team: the worker talks upward with its parent `team_orchestrator` MCP tools.
+- Child team: the same worker talks downward with `team-agent send --workspace "$CHILD_WORKSPACE" --team "$CHILD_TEAM" ...`.
+
+Do not run child lifecycle commands against the parent workspace. Always pass the child workspace and team when operating the child team from the parent worker.
+
+## Parent-Child Messaging
+
+Use explicit two-hop routing.
+
+Parent leader to child worker:
+
+1. Parent leader sends the child-task instruction to the parent worker that owns the child team.
+2. Parent worker sends into the child team:
+
+```bash
+team-agent send reviewer "Review this patch and report findings" \
+  --workspace "$CHILD_WORKSPACE" \
+  --team "$CHILD_TEAM" \
+  --watch-result
+```
+
+Child worker to parent leader:
+
+1. Child worker reports to its child leader:
+
+```text
+team_orchestrator.send_message(to="leader", content="short progress")
+team_orchestrator.report_result(summary="short completion", status="success")
+```
+
+2. The parent worker, acting as child leader, relays the relevant summary upward to the parent leader with its parent-team MCP tools.
+
+Do not ask a child worker to send directly to a parent-team agent id. Current MCP scope is team-local and should refuse out-of-scope peers. Use CLI `--workspace` and `--team` only from the appropriate leader/operator side when crossing team boundaries.
+
+## Clean-Context Roles
+
+Asking for a clean-context role is a normal feature request when the user wants a blind reviewer, a fresh second opinion, or a role that forgets earlier conversation. It is not the same as failure recovery.
+
+For an existing worker that should restart with a blank provider context, the leader can use:
+
+```bash
+team-agent reset-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
+```
+
+or the equivalent restart form:
+
+```bash
+team-agent restart-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
+```
+
+Use this only when the user intentionally wants a clean context. For incident recovery, follow `recovery-runbook.md`, where context-preserving repair comes first.
+
+## Framework Gaps To Track
+
+- Nested mode needs a way to pin the framework Team Agent skill by absolute path, so providers do not choose their built-in agent-team feature.
+- A child-team worker should be prevented from shutting down the parent team by mistake.
+- Child team creation should avoid defaulting to the fragile parent `current` directory.