@team-agent/installer 0.3.22 → 0.3.23

package/Cargo.lock

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

package/Cargo.toml

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

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

@@ -403,6 +403,7 @@ pub(super) fn resume_backing_exists_for_agent(
         Provider::Claude | Provider::ClaudeCode => {
             rollout_path_exists(rollout_path)
                 || event_log_transcript_exists(workspace, agent_id.as_str(), session_id.as_str())
+                || claude_project_transcript_exists(agent, session_id.as_str())
         }
         Provider::Copilot => copilot_session_store_has_session(session_id.as_str()),
         Provider::GeminiCli | Provider::Fake => false,
@@ -448,6 +449,42 @@ fn event_transcript_path(event: &serde_json::Value) -> Option<PathBuf> {
         .map(PathBuf::from)
 }
 
+/// E36 fix-B: a real Claude worker writes its session transcript to
+/// `<claude_projects_root>/<workspace-slug>/<session_id>.jsonl` even when neither
+/// `rollout_path` was persisted to state nor a `session.captured` event was logged.
+/// That landed transcript is itself a valid resume backing — restart was wrongly
+/// refusing resumable workers because it only checked the two paths above. Scan the
+/// projects root recursively for `<session_id>.jsonl` (session_id is a unique UUID,
+/// so we avoid recomputing the project-dir slug, which is brittle for non-ASCII
+/// workspace paths).
+fn claude_project_transcript_exists(agent: &serde_json::Value, session_id: &str) -> bool {
+    if session_id.is_empty() {
+        return false;
+    }
+    let projects_root = agent
+        .get("claude_projects_root")
+        .and_then(serde_json::Value::as_str)
+        .filter(|value| !value.is_empty())
+        .map(PathBuf::from)
+        .or_else(|| {
+            std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".claude").join("projects"))
+        });
+    let Some(projects_root) = projects_root else {
+        return false;
+    };
+    if !projects_root.is_dir() {
+        return false;
+    }
+    let transcript_name = format!("{session_id}.jsonl");
+    let Ok(project_dirs) = std::fs::read_dir(&projects_root) else {
+        return false;
+    };
+    project_dirs
+        .flatten()
+        .filter(|entry| entry.path().is_dir())
+        .any(|entry| entry.path().join(&transcript_name).is_file())
+}
+
 fn copilot_session_store_has_session(session_id: &str) -> bool {
     let Some(home) = std::env::var_os("HOME").map(PathBuf::from) else {
         return false;
@@ -908,3 +945,69 @@ pub(super) fn is_dynamic_agent(
             .and_then(YamlValue::as_str)
             .is_some_and(|s| !s.is_empty())
 }
+
+#[cfg(test)]
+mod e36_transcript_backing_tests {
+    use super::*;
+
+    struct ScratchDir(PathBuf);
+    impl ScratchDir {
+        fn new(tag: &str) -> Self {
+            let pid = std::process::id();
+            let base = std::env::temp_dir().join(format!("ta-e36-{tag}-{pid}"));
+            std::fs::create_dir_all(&base).expect("scratch dir");
+            ScratchDir(base)
+        }
+        fn path(&self) -> &Path {
+            &self.0
+        }
+    }
+    impl Drop for ScratchDir {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.0);
+        }
+    }
+
+    // E36 fix-B RED→GREEN: a real Claude worker that sent a message has its session
+    // transcript landed at <projects_root>/<slug>/<session_id>.jsonl, but neither
+    // rollout_path was persisted to state nor a session.captured event was logged.
+    // Before the fix, claude_project_transcript_exists did not exist and restart
+    // refused such a worker. This asserts the landed transcript is recognized.
+    #[test]
+    fn claude_project_transcript_is_recognized_without_rollout_or_capture_event() {
+        let scratch = ScratchDir::new("recognized");
+        let projects_root = scratch.path().join("projects");
+        let slug_dir = projects_root.join("-Users-alauda-Documents-code---rust---9");
+        std::fs::create_dir_all(&slug_dir).expect("mkdir slug");
+        let session_id = "87742d3f-0b4e-4fc1-ad35-447ac2340b65";
+        std::fs::write(slug_dir.join(format!("{session_id}.jsonl")), b"{}\n").expect("transcript");
+
+        let agent = serde_json::json!({
+            "claude_projects_root": projects_root.to_string_lossy(),
+        });
+        assert!(
+            claude_project_transcript_exists(&agent, session_id),
+            "landed claude transcript must count as resume backing (E36 fix-B)"
+        );
+    }
+
+    #[test]
+    fn missing_claude_transcript_is_not_backing() {
+        let scratch = ScratchDir::new("missing");
+        let projects_root = scratch.path().join("projects");
+        std::fs::create_dir_all(&projects_root).expect("mkdir");
+        let agent = serde_json::json!({
+            "claude_projects_root": projects_root.to_string_lossy(),
+        });
+        assert!(
+            !claude_project_transcript_exists(&agent, "deadbeef-0000-0000-0000-000000000000"),
+            "no transcript file => no backing"
+        );
+    }
+
+    #[test]
+    fn empty_session_id_is_not_backing() {
+        let agent = serde_json::json!({});
+        assert!(!claude_project_transcript_exists(&agent, ""));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.3.22",
+  "version": "0.3.23",
   "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.23",
+    "@team-agent/cli-darwin-x64": "0.3.23",
+    "@team-agent/cli-linux-x64": "0.3.23"
   },
   "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.