@team-agent/installer 0.5.119 → 0.5.120

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

@@ -2217,6 +2217,43 @@ fn kill_session_and_kill_window_argv() {
     );
 }
 
+#[test]
+fn issue336_session_listing_accepts_tab_and_literal_escape_without_rewriting_names() {
+    for separator in ["\t", "\\t"] {
+        let (backend, calls) = backend_with(
+            MockResp::Out(ok("")),
+            vec![
+                MockResp::Out(ok(&format!("%7{separator}worker\\tname\n"))),
+                MockResp::Out(ok("%8\n")),
+            ],
+        );
+        backend.preserve_session_before_stop(
+            &SessionName::new("sess"),
+            &[Target::SessionWindow {
+                session: SessionName::new("sess"),
+                window: WindowName::new("worker\\tname"),
+            }],
+        ).unwrap();
+        assert_eq!(calls.lock().unwrap().len(), 4, "separator={separator:?}");
+    }
+}
+
+#[test]
+fn issue336_escaped_listing_keeps_survivors_and_malformed_rows_fail_closed() {
+    let (backend, calls) = backend_with(MockResp::Out(ok("%7\\tworker\n%8\\tleader\n")), vec![]);
+    backend.preserve_session_before_stop(
+        &SessionName::new("sess"), &[Target::Pane(PaneId::new("%7"))],
+    ).unwrap();
+    assert_eq!(calls.lock().unwrap().len(), 1);
+    for row in ["%7 worker", "%7", ""] {
+        let (backend, calls) = backend_with(MockResp::Out(ok(row)), vec![]);
+        assert!(backend.preserve_session_before_stop(
+            &SessionName::new("sess"), &[Target::Pane(PaneId::new("%7"))],
+        ).is_err());
+        assert_eq!(calls.lock().unwrap().len(), 1);
+    }
+}
+
 #[test]
 fn stop_session_preservation_creates_processless_anchor_by_exact_pane_id() {
     let (be, rec) = backend_with(

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

@@ -4201,13 +4201,20 @@ impl Transport for TmuxBackend {
             return Err(subprocess_error(list_argv, output));
         }
         for line in output.stdout.lines() {
-            let Some((pane, window)) = line.split_once('\t') else {
+            // Some tmux/runner combinations return the literal escape. Split
+            // only the first column boundary; window names are not unescaped.
+            let separator = line.find('\t').map(|at| (at, 1)).into_iter()
+                .chain(line.find("\\t").map(|at| (at, 2)))
+                .min_by_key(|(at, _)| *at);
+            let Some((at, width)) = separator else {
                 return Err(TransportError::Subprocess {
                     argv: list_argv,
                     code: output.code,
                     stderr: "tmux returned an invalid session pane listing".to_string(),
                 });
             };
+            let (pane, rest) = line.split_at(at);
+            let window = &rest[width..];
             if !targets.iter().any(|target| match target {
                 Target::Pane(id) => id.as_str() == pane,
                 Target::SessionWindow {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.119",
+  "version": "0.5.120",
   "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.5.119",
-    "@team-agent/cli-darwin-x64": "0.5.119",
-    "@team-agent/cli-linux-x64": "0.5.119"
+    "@team-agent/cli-darwin-arm64": "0.5.120",
+    "@team-agent/cli-darwin-x64": "0.5.120",
+    "@team-agent/cli-linux-x64": "0.5.120"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/SKILL.md

@@ -5,27 +5,30 @@ requires_team_agent: ">=0.5.0"
 ---
 # Team Agent
 
-The current assistant is the **leader**. Workers use separate role files and report through Team Agent. Start from a tmux-addressable terminal or supported agent pane, in the workspace root (the parent of the team directory).
+Use the authorized **Leader's** native tool context for lifecycle operations. Workers report through their team-scoped MCP tools; loading this skill does not promote a worker to Leader. Operate in the workspace root, not inside another team's role directory.
 
-## Decide before creating a team
+## Check the actual CLI
+
+Check `team-agent --version`, `team-agent start --help` and `team-agent team --help` before using this guide. It requires the intuitive `start`, `stop`, `team` and `agent` surface. A version string or this skill's compatibility floor is not proof those commands exist. If missing, ask for an authorized installation of a supporting build; do not silently switch binaries, rewrite bindings or fall back to an old creation recipe.
+
+## User decisions come first
 
 **The user decides each worker's provider and permission bypass. Do not silently choose Pi, true, or false.** Reuse an explicit user policy when it covers the worker; otherwise explain the choices and ask before starting.
 
-Use existing resources rather than establishing new accounts: `team-agent doctor --workspace . --json` reports discovered tools, but installed does not mean authenticated and an absent entry or unknown auth is not proof of unavailability. For providers supported by `models`, use `team-agent models --provider NAME` to check exact model IDs. Do not inspect credentials, automatically log in, or silently substitute a provider after a failed probe.
+Use existing resources rather than establishing accounts. `team-agent doctor --workspace . --json` reports discovered tools; installed is not authenticated, and an unknown probe is not proof of unavailability. Use `team-agent models --provider NAME` where supported for exact model IDs. Do not inspect credentials, automatically log in, or silently substitute providers.
 
-| Choice | What to explain |
+| Choice | Explain |
 |---|---|
-| Pi | One Agent tool can use several model catalogs; explicit models require a qualified ID such as `openai-codex/gpt-6-luna` |
-| Codex | The user's existing Codex workflow, native tools, permissions and resumable sessions |
-| Claude / Claude Code | The user's existing Claude workflow, models, native tools and session behavior |
-| Bypass `true` | Fewer permission interruptions, but broader automatic execution authority |
-| Bypass `false` | Keep the selected tool's native permissions; human confirmation may interrupt unattended work |
+| Pi | Several model catalogs; an explicit model needs a qualified ID such as `openai-codex/gpt-6-luna` |
+| Codex / Claude / other native CLIs | The user's existing workflow, native permissions, model catalog and supported session capabilities |
+| Bypass `true` | Fewer interruptions, broader automatic authority |
+| Bypass `false` | Native permissions remain; human confirmation may interrupt unattended work |
 
-False is **not** a read-only or sandbox guarantee. Native permission capabilities differ between tools. Suggest combinations based on the user's installed tools, subscriptions and task: for example, an explicitly chosen Codex implementer and Claude reviewer, or two Pi workers when those are the available resources. Different workers may use different providers; an existing worker cannot change provider.
+False is **not** a read-only or sandbox guarantee. Different workers may use different providers; an existing worker cannot change provider. Do not invent a model or effort when the user left it unset.
 
-## Create and start
+## Prepare once, start every day
 
-Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name.
+Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name:
 
 ```text
 .team/current/
@@ -33,7 +36,7 @@ Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The
   agents/reviewer.md
 ```
 
-For a **new plan**, record the user's two decisions in every role. This example assumes the user selected Pi and bypass false; it is not a default:
+Record provider and boolean bypass in every new role. This example assumes the user explicitly chose Pi and bypass false; it is not a default:
 
 ```markdown
 ---
@@ -43,43 +46,58 @@ dangerously_skip_permissions: false
 Review the change and report concrete regression risks.
 ```
 
+From the authorized Leader context, select the intended workspace/team:
+
 ```sh
-team-agent quick-start .team/current
-team-agent send reviewer "Review this change"
-team-agent inbox reviewer -n 3
+team-agent start --from .team/current --workspace . --team project-team
+team-agent start --workspace . --team project-team
+team-agent send reviewer "Review this change" --workspace . --team project-team
+team-agent inbox leader --workspace . --team project-team -n 3
 ```
 
-Traditional file-based quick-start/compile behavior remains supported, including legacy minimal role documents; no conversion to CLI-created roles is required. Legacy interpretation is not permission to silently choose settings for a new user plan. Model and effort may remain unset; preserve the existing file compiler's native/default interpretation rather than inventing a model or effort.
+The first `start` creates a complete configured team through the original creation path. Later `start` keeps physically verified, drift-free live seats unchanged and starts stopped non-paused seats, including explicitly stopped seats. It is not a reset. Missing configuration, ambiguous scope or unknown physical identity is a refusal, not permission to overwrite state. `--dry-run` plans without lifecycle effects; final locked admission is still deferred.
+
+Accepted/queued send is **not** the worker's answer. Wait for a natural reply/result. `ok: true` with pending readiness is not business readiness. A live no-op does not synchronize edited role bodies or apply changed launch settings.
 
-To add a **new** seat to an existing team, provider and bypass must be explicitly defined in the CLI or role file. A complete traditional role file needs no repeated flags. If both sources define a field, equal values are accepted and **conflicting values are rejected before any write or startup**:
+## Stop, wake and restart
 
 ```sh
-# These values must be the user's choices, not inferred defaults.
-team-agent add-agent analyst --provider pi --bypass true --prompt "Analyze the proposed change"
-# auditor.md already contains the user's provider and bypass decisions.
-team-agent add-agent auditor --role-file /absolute/path/to/auditor.md
+team-agent stop reviewer --workspace . --team project-team
+team-agent start reviewer --workspace . --team project-team
+team-agent restart reviewer --workspace . --team project-team
+team-agent stop --workspace . --team project-team --json
+team-agent start --workspace . --team project-team
+team-agent team restart --workspace . --team project-team --json
 ```
 
-Add creates and immediately starts the seat. Ordinary add rejects an occupied ID, including stopped seats. Disaster recovery has one explicit exception: `add-agent ID --role-file FILE --force` may reuse the existing force-recreate lifecycle only when the registered old pane is positively confirmed dead and no live target cohort exists. A live seat or unknown/missing death proof is refused; force is not a routine configuration-update shortcut. External role files are imported into the team's `agents/ID.md` and left untouched. A file already at that path is used in place, without copying itself.
+| Intent | Rule |
+|---|---|
+| `start AGENT` | Wake a stopped registered seat; verified live/no-drift is a no-op. A RoleOnly seat can be added from its complete role file |
+| `start` | Explicitly activate the selected non-paused roster; do not use it unless that activation is authorized |
+| `stop AGENT` / `stop` | Retain saved session associations; whole-team stop also checks scoped residual resources |
+| `restart AGENT` / `team restart` | Default `--session auto`: resume when proven, otherwise only the original legal fresh fallback. **Auto does not guarantee preserved memory** |
+| `--session preserve` | Require available continuation evidence; refuse before stopping when continuation is known unavailable |
+
+Team restart preserves explicitly stopped and paused seats; use `start` when intentionally waking the roster. Paused seats are not implicitly unpaused. A same-named directory makes `restart ID` ambiguous: use `agent restart ID`. `reviewer.v2` remains an agent ID; choose a team source with `--from DIR`, `team start DIR` or an explicit path such as `./roles`.
+
+For strict recovery, prefer `team-agent team restart --session preserve --workspace . --team project-team`. Do not convert a refusal or partial/unknown replacement into reset, force or blind retry. Inspect `status`/`doctor` in the same scope first. Native unsupported capabilities remain refusals, never a legacy fallback.
 
-## Change and start an existing worker
+## Add or change one worker
 
-**Stop first if it is running.** Start never implicitly kills or restarts a running worker:
+With the user's provider/bypass choices, `start` unifies adding an absent seat and waking an existing one:
 
 ```sh
-team-agent stop-agent reviewer
-team-agent start-agent reviewer --effort high --bypass true
-team-agent stop-agent reviewer
-team-agent start-agent reviewer --prompt "Review only regression risks; do not change product code"
+team-agent start auditor --role-file /absolute/path/to/auditor.md
+team-agent start analyst --provider pi --bypass false --prompt "Analyze the proposed change"
+team-agent stop reviewer
+team-agent start reviewer --effort high --bypass false
 ```
 
-Start updates the same role file and recompiles it before normal startup. Omitted options preserve the file's values and body; `--prompt` replaces the permanent role body, not a one-time task message. `--bypass true` and `--bypass false` are explicit values, not bare switches. Model, effort and an existing profile can also be set. Direct file edits followed by start use the same reload path.
+The Pi/false example above still requires the user's explicit choices. File/CLI conflicts are rejected before writing or startup. Omitted settings/body are preserved; `--prompt` replaces the permanent role body, not a one-time task. Stop a running worker before changing settings or instructions. Provider changes are refused. Startup failure restores role/spec bytes and reports failure, not an applied update.
 
-A different `--provider`, including a manually edited role provider, is rejected before launch. A matching provider is allowed. Create a separate ID to use a different engine. If startup fails, the role file and runtime spec are restored to their pre-command contents; the command reports failure, not an applied update.
+Use `agent add/remove/reset/clone/fork` only for those explicit operations. Reset needs intentional approval and `--discard-session`; fork requires `--as NEW_ID`, and `--in-place` is not supported. See [the operator reference](references/team-agent-operator.md) for capability, profile, force and import boundaries. Never put secrets in role text or copy authentication from another directory.
 
-Profiles keep provider authentication, endpoints and custom-model settings local. Imported roles use this team's/workspace's `profiles`, never the original external directory. Prepare a named profile locally through the public profile commands; do not search for or copy external credentials. Never put secrets in `TEAM.md` or a role file. See [the operator reference](references/team-agent-operator.md) for existing profile and field details. Supported metadata also includes `agent_id` (legacy `name`), `role`, `auth_mode`, and `communication_mode`; old `tools`, `permission_mode`, and `label` keys do not configure a worker.
-
-## Global native CLI argv (optional)
+## Optional native CLI argv routing
 
 Default OFF; no workspace or provider login is needed to manage routes:
 
@@ -93,29 +111,28 @@ team-agent route clear pi
 team-agent route disable
 ```
 
-`set` replaces one mapping, `add` appends without deduplication, `clear` removes it;
-none changes the switch. `enable`/`disable` preserve mappings in `~/.team-agent/argv-routing.json`.
-`TEAM_AGENT_CLI_ARGV_ROUTING` overrides the switch: `1/true/on`, `0/false/off` (case-insensitive,
-trimmed); invalid values disable routing. Check `persisted_enabled`, `effective_enabled` and
-`override_status` rather than assuming `enable` defeats an environment OFF.
+`set` replaces one mapping, `add` appends without deduplication, `clear` removes it; none changes the switch. `enable`/`disable` preserve mappings in `~/.team-agent/argv-routing.json`. `TEAM_AGENT_CLI_ARGV_ROUTING` overrides the switch: `1/true/on`, `0/false/off` (case-insensitive, trimmed); invalid values disable routing. Check `persisted_enabled`, `effective_enabled` and `override_status`.
 
-Keys: `claude`, `codex`, `copilot`, `gemini_cli`, `grok`, `cursor_agent`, `pi`.
-Claude/Claude Code share `claude`; aliases `claude_code/claude-code`, `agent/cursor` are accepted.
-The first `--` ends control parsing: subsequent tokens, including `--help`, `--json`, empty strings
-and `{workspace}`, are literal data. Tokens go after the executable and before its original tail;
-there is no shell expansion. Do not route secrets or override framework-managed session/MCP/permission flags.
+Keys: `claude`, `codex`, `copilot`, `gemini_cli`, `grok`, `cursor_agent`, `pi`. Claude/Claude Code share `claude`; aliases `claude_code/claude-code`, `agent/cursor` are accepted. Everything after the first `--`, including `--help`, `--json`, empty strings and `{workspace}`, is literal argv. No shell expansion. Do not route secrets or override framework-managed session/MCP/permission flags.
 
-The current mapping affects the next actual Leader/worker spawn (also restart, single-seat start/reset,
-add/clone, Pi new-seat fork and remove rollback), not running/attached processes, dry-run or helper probes.
-Enabled bad configuration prevents native spawn; an emergency environment OFF avoids reading it,
-while `route disable` will not overwrite a broken file. Pi `--mode rpc` does not provide an RPC host
-or change the existing Team Agent transport.
+Mappings affect the next actual native spawn, not running/attached processes, dry-run or helper probes. Invalid enabled configuration refuses spawn; an emergency environment OFF avoids reading it, while `route disable` will not overwrite a broken file. Pi `--mode rpc` does not provide an RPC host or replace Team Agent's transport.
 
-## Inspect and stop
+## Observe, communicate and clean up
 
-Use `team-agent status --json` for readiness and the installed command's `--help` for syntax. `ok: true` with `ready: false` means the team is not ready; follow the reported action. Accepted/queued send is not the worker's reply: wait for a natural response or result. Use `<workspace>::<team>/<agent>` when a fully qualified recipient is needed.
+Use `team-agent status --json` (or `team status`) for the concise node projection and `doctor` for diagnosis; `--detail` does not restore old internal status dumps. Use `<workspace>::<team>/<agent>` for an explicitly qualified logical recipient, or the in-team short name. Workers have exactly `send_message`, `report_result` and optional `get_team_status`; lifecycle stays on the authorized CLI. Read [nested teams](references/team-in-team.md) only when explicitly requested and [recovery](references/recovery-runbook.md) for incidents.
 
-Worker MCP provides `send_message`, `report_result`, and `get_team_status`. Lifecycle actions remain on the authorized CLI. See [nested teams](references/team-in-team.md) only when needed. Stop the selected team with `team-agent shutdown --workspace .` when authorized.
+Finish with `team-agent stop --workspace . --team project-team --json` when authorized. Check the actual scoped residual report; exit0 alone is not proof of zero resources. Do not kill shared servers or touch sibling workspaces.
 
----
-This skill is a concise public guide. Do not infer a tested version from package metadata; verify the installed CLI with `team-agent --version` when version-specific behavior matters.
+## Compatibility bridges, not the daily workflow
+
+Old commands remain available for existing scripts; their output/defaults are not silently rewritten:
+
+| Compatibility entry | Preferred daily surface |
+|---|---|
+| `quick-start` | `start --from TEAMDIR` for creation and later `start` for activation |
+| `shutdown` | `stop` / `team stop` |
+| `add-agent` / `start-agent` / `stop-agent` | `agent add` for strict add, or `start AGENT` / `stop AGENT` |
+| `remove-agent` / `reset-agent` / `clone-agent` / `fork-agent` | The corresponding `agent` operation |
+| Bare or explicit-path `restart` | Frozen preserve bridge; deliberate `team restart` defaults to auto |
+
+These are not all byte-equivalent aliases: legacy single-seat start refuses a running seat, while new start can prove a no-op. Do not mechanically rename automation, assume unsupported provider capabilities, or infer deployment from package metadata.