@team-agent/installer 0.5.66 → 0.5.68

package/npm/install.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+/**
+ * purpose: place the Team Agent runtime and login wrappers via the npx installer
+ * contract: wrappers land only in the declared bin dir (~/.local/bin or --prefix/bin); installer-managed wrappers recorded in the manifest or recognized by marker are rewritten onto this install's runtime; a non-writable declared dir fails closed with ACTION
+ * boundary: never selects a PATH entry as the install target; never creates wrappers in third-party package dirs; does not treat host login PATH order as a landing picker
+ */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { createRequire } from "node:module";
@@ -119,7 +124,7 @@ Usage:
   npx @team-agent/installer@latest uninstall
 
 Options:
-  --prefix <dir>       fallback wrapper prefix when no writable PATH dir exists, default ~/.local
+  --prefix <dir>       declared wrapper prefix (wrappers go in <dir>/bin), default ~/.local
   --runtime-dir <dir>  stable runtime root, default ~/.team-agent/runtime
   --purge-runtime      uninstall also removes the runtime root
 `);
@@ -128,6 +133,7 @@ Options:
 function install(argv) {
   const opts = parseOptions(argv);
   const runtimeRoot = path.resolve(expandHome(opts.runtimeDir || path.join(os.homedir(), ".team-agent", "runtime")));
+  const prevManifest = readInstallManifest(runtimeRoot);
   const installTarget = resolveInstallBinDir({ env: process.env, home: os.homedir(), prefix: opts.prefix });
   const binDir = installTarget.binDir;
   const version = packageJson.version || "dev";
@@ -161,6 +167,7 @@ function install(argv) {
     home: os.homedir(),
     binDir,
     runtimeBinary,
+    recordedBinDirs: recordedManagedBinDirs(prevManifest),
     log: (line) => console.log(line),
   });
   installSkills(runtimeBinary);
@@ -172,6 +179,11 @@ function install(argv) {
     installedAt: new Date().toISOString(),
     installTargetKind: installTarget.kind,
     pathShadowRepairs: shadowRepairs.map((repair) => repair.file),
+    managedBinDirs: uniqueDirs([
+      binDir,
+      ...recordedManagedBinDirs(prevManifest),
+      ...shadowRepairs.map((repair) => repair.binDir),
+    ]),
   });
 
   const teamAgent = path.join(binDir, "team-agent");
@@ -299,33 +311,71 @@ function parseOptions(argv) {
   return opts;
 }
 
+export function declaredInstallBinDir(options = {}) {
+  const home = options.home || os.homedir();
+  const prefix = options.prefix
+    ? path.resolve(expandHomeFor(options.prefix, home))
+    : path.join(home, ".local");
+  return path.join(prefix, "bin");
+}
+
 export function resolveInstallBinDir(options = {}) {
   const env = options.env || process.env;
   const home = options.home || os.homedir();
-  const entries = uniquePathEntries(env.PATH || "", home);
-  for (const entry of entries) {
-    if (isVersionManagedPath(entry) || !canWriteDir(entry) || hasForeignWrapper(entry)) {
-      continue;
-    }
-    return { binDir: entry, kind: "path", readyNow: true, rc: null };
+  const binDir = path.resolve(declaredInstallBinDir(options));
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+  } catch (error) {
+    throw declaredBinDirUnwritableError(binDir, "create", error);
   }
-
-  for (const entry of entries) {
-    if (isVersionManagedPath(entry) || !isReasonableUserBinDir(entry, home) || !canWriteDir(entry) || hasForeignWrapper(entry)) {
-      continue;
-    }
-    return { binDir: entry, kind: "path_user", readyNow: true, rc: null };
+  if (!canWriteDir(binDir)) {
+    throw declaredBinDirUnwritableError(binDir, "write");
   }
 
-  const fallbackPrefix = options.prefix
-    ? path.resolve(expandHomeFor(options.prefix, home))
-    : path.join(home, ".local");
-  const binDir = path.join(fallbackPrefix, "bin");
-  fs.mkdirSync(binDir, { recursive: true });
+  const onPath = uniquePathEntries(env.PATH || "", home).includes(binDir);
+  if (onPath) {
+    return { binDir, kind: "declared", readyNow: true, rc: null };
+  }
   const rc = ensureBinDirOnShellRc(binDir, { env, home });
   return { binDir, kind: "shell_rc", readyNow: false, rc };
 }
 
+function declaredBinDirUnwritableError(binDir, op, cause) {
+  const detail = cause instanceof Error ? cause.message : cause ? String(cause) : "permission denied";
+  return new Error(
+    [
+      `ERROR: cannot ${op} Team Agent wrapper directory ${binDir}`,
+      `ACTION: make it writable (\`mkdir -p ${binDir} && chmod u+w ${binDir}\`), or rerun with --prefix <writable-dir>`,
+      `LOG: declared wrapper dir is the only landing; installer does not fall back to a PATH entry (${detail})`,
+    ].join("\n"),
+  );
+}
+
+export function recordedManagedBinDirs(manifest) {
+  const dirs = [];
+  if (!manifest || typeof manifest !== "object") {
+    return dirs;
+  }
+  if (typeof manifest.binDir === "string" && manifest.binDir) {
+    dirs.push(manifest.binDir);
+  }
+  if (Array.isArray(manifest.managedBinDirs)) {
+    for (const dir of manifest.managedBinDirs) {
+      if (typeof dir === "string" && dir) {
+        dirs.push(dir);
+      }
+    }
+  }
+  if (Array.isArray(manifest.pathShadowRepairs)) {
+    for (const file of manifest.pathShadowRepairs) {
+      if (typeof file === "string" && file) {
+        dirs.push(path.dirname(file));
+      }
+    }
+  }
+  return uniqueDirs(dirs);
+}
+
 export function repairPathShadowingTeamAgentCommands(options = {}) {
   const env = options.env || process.env;
   const home = options.home || os.homedir();
@@ -337,42 +387,50 @@ export function repairPathShadowingTeamAgentCommands(options = {}) {
   }
   const installedWrapper = path.join(binDir, "team-agent");
   const repairs = [];
-  const candidates = pathShadowRepairCandidates(env.PATH || "", home, binDir);
-  log?.(`path-shadow: scanning ${candidates.length} candidate bin dirs before ${binDir}`);
+  const recordedBinDirs = options.recordedBinDirs || recordedManagedBinDirs(options.manifest);
+  const candidates = pathShadowRepairCandidates(env.PATH || "", home, binDir, recordedBinDirs);
+  log?.(`path-shadow: scanning ${candidates.length} candidate bin dirs for managed wrappers`);
   for (const candidateDir of candidates) {
     const entry = candidateDir.dir;
-    const candidate = path.join(entry, "team-agent");
     if (isVersionManagedPath(entry)) {
-      log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=version-managed-path`);
+      log?.(`path-shadow: skip ${path.join(entry, "team-agent")} source=${candidateDir.source} reason=version-managed-path`);
       continue;
     }
-    if (!fs.existsSync(candidate)) {
-      if (candidateDir.source === "home-local-bin") {
-        log?.(`path-shadow: checked ${candidate} source=${candidateDir.source} reason=not-found`);
+    for (const name of WRAPPER_NAMES) {
+      const candidate = path.join(entry, name);
+      if (!fs.existsSync(candidate)) {
+        if (name === "team-agent" && candidateDir.source === "home-local-bin") {
+          log?.(`path-shadow: checked ${candidate} source=${candidateDir.source} reason=not-found`);
+        }
+        continue;
       }
-      continue;
-    }
-    log?.(`path-shadow: found ${candidate} source=${candidateDir.source}`);
-    if (!isExecutableFile(candidate)) {
-      log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=not-executable-file`);
-      continue;
-    }
-    if (sameFile(candidate, installedWrapper)) {
-      log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=installed-wrapper`);
-      continue;
-    }
-    if (sameFile(candidate, runtimeBinary)) {
-      log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=runtime-binary`);
-      continue;
-    }
-    try {
-      writeExecWrapper(candidate, runtimeBinary, [], { allowForeign: true });
-    } catch (error) {
-      const detail = error instanceof Error ? error.message : String(error);
-      throw new Error(`failed to update PATH-shadowing team-agent at ${candidate}: ${detail}`);
+      log?.(`path-shadow: found ${candidate} source=${candidateDir.source}`);
+      if (!isExecutableFile(candidate)) {
+        log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=not-executable-file`);
+        continue;
+      }
+      if (sameFile(candidate, installedWrapper) && name === "team-agent") {
+        log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=installed-wrapper`);
+        continue;
+      }
+      if (sameFile(candidate, runtimeBinary)) {
+        log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=runtime-binary`);
+        continue;
+      }
+      if (!isInstallerManagedWrapper(candidate)) {
+        log?.(`path-shadow: skip ${candidate} source=${candidateDir.source} reason=not-installer-managed`);
+        continue;
+      }
+      const extraArgs = name === "team_orchestrator" ? ["mcp-server"] : name === "team-agent-coordinator" ? ["coordinator"] : [];
+      try {
+        writeExecWrapper(candidate, runtimeBinary, extraArgs, { allowForeign: true });
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to update PATH-shadowing team-agent at ${candidate}: ${detail}`);
+      }
+      log?.(`path-shadow: updated ${candidate} source=${candidateDir.source} to runtime shim`);
+      repairs.push({ file: candidate, binDir: entry, source: candidateDir.source });
     }
-    log?.(`path-shadow: updated ${candidate} source=${candidateDir.source} to runtime shim`);
-    repairs.push({ file: candidate, binDir: entry, source: candidateDir.source });
   }
   if (repairs.length === 0) {
     log?.("path-shadow: no stale team-agent command repaired");
@@ -434,16 +492,7 @@ export function parseTeamAgentVersion(output) {
   return bare ? bare[1] : null;
 }
 
-function shadowingPathEntries(searchPath, home, binDir) {
-  const entries = uniquePathEntries(searchPath, home);
-  const installedIndex = entries.findIndex((entry) => path.resolve(entry) === path.resolve(binDir));
-  if (installedIndex === -1) {
-    return entries;
-  }
-  return entries.slice(0, installedIndex);
-}
-
-function pathShadowRepairCandidates(searchPath, home, binDir) {
+function pathShadowRepairCandidates(searchPath, home, binDir, recordedBinDirs = []) {
   const candidates = [];
   const seen = new Set();
   const add = (dir, source) => {
@@ -454,17 +503,36 @@ function pathShadowRepairCandidates(searchPath, home, binDir) {
     seen.add(resolved);
     candidates.push({ dir: resolved, source });
   };
-  for (const entry of shadowingPathEntries(searchPath, home, binDir)) {
-    add(entry, "path-before-install");
+  for (const entry of uniquePathEntries(searchPath, home)) {
+    add(entry, "path");
   }
 
   const homeLocalBin = path.join(home, ".local", "bin");
-  if (!sameFile(homeLocalBin, binDir)) {
-    add(homeLocalBin, "home-local-bin");
+  add(homeLocalBin, "home-local-bin");
+  add(binDir, "declared-bin");
+  for (const dir of recordedBinDirs) {
+    add(dir, "manifest-recorded");
   }
   return candidates;
 }
 
+function uniqueDirs(dirs) {
+  const seen = new Set();
+  const out = [];
+  for (const dir of dirs) {
+    if (typeof dir !== "string" || !dir) {
+      continue;
+    }
+    const resolved = path.resolve(dir);
+    if (seen.has(resolved)) {
+      continue;
+    }
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
 function isExecutableFile(file) {
   try {
     fs.accessSync(file, fs.constants.X_OK);
@@ -513,11 +581,6 @@ function isVersionManagedPath(dir) {
   ].some((marker) => value.includes(marker));
 }
 
-function isReasonableUserBinDir(dir, home) {
-  const relative = path.relative(home, dir);
-  return Boolean(relative && !relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
 function canWriteDir(dir) {
   try {
     const probe = path.join(dir, `.team-agent-write-test-${process.pid}-${Date.now()}`);
@@ -529,13 +592,6 @@ function canWriteDir(dir) {
   }
 }
 
-function hasForeignWrapper(binDir) {
-  return WRAPPER_NAMES.some((name) => {
-    const file = path.join(binDir, name);
-    return fs.existsSync(file) && !isInstallerManagedWrapper(file);
-  });
-}
-
 function isInstallerManagedWrapper(file) {
   try {
     const text = fs.readFileSync(file, "utf8");

package/package.json

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

package/skills/team-agent/SKILL.md

@@ -1,272 +1,67 @@
 ---
 name: team-agent
 description: Use only when the user explicitly asks to start, operate, inspect, shutdown, or restart a Team Agent team. Treat the team-agent CLI as a sealed appliance.
+requires_team_agent: ">=0.5.0"
+last_verified_against: "0.5.66"
 ---
 
 # Team Agent
 
-Use this skill only for Team Agent operation. The leader is the current user-facing agent; do not create a `leader` worker. Worker role docs live in `<workspace>/agents/`; `TEAM.md` lives at `<workspace>/TEAM.md`.
+Sealed appliance for someone who just got the CLI. Operator handbook (permissions, models, routing, recovery): `docs/reference/team-agent-operator.md`.
 
-## Leader Requirement
-
-Real Team Agent teams require the current leader to run inside a tmux-managed pane. Prefer the short launchers:
+If `team-agent --version` does not match `last_verified_against`, do not copy examples as current truth. Learn from the live CLI:
 
 ```bash
-team-agent codex
-team-agent claude
+team-agent --version
+team-agent --help
+team-agent doctor --help
 ```
 
-Pass provider flags after the provider name, for example `team-agent codex --dangerously-bypass-approvals-and-sandbox`. Existing tmux layouts are valid too, including Finder/Ghostty launchers, as long as `team-agent quick-start` is invoked from the leader's current tmux pane. Do not start a real team from a naked terminal that Team Agent cannot address through tmux.
-
-## Leader Role
-
-Invoking this skill turns the current agent into the team leader. The leader **orchestrates**: read reports, set direction, decompose work, dispatch tasks to teammates, review results, and decide. The leader does **not** execute hands-on work — no `cargo test`, no product-code edits, no `git push`, no build/verify cycles. Those belong to teammates. If the leader catches themselves running tests, editing source files, or pushing commits, they have stepped out of role; stop and re-dispatch.
-
-When the user has been communicating in Chinese throughout the conversation, all leader↔teammate messaging (`send`, `report_result`, MCP messages, task descriptions) must also be in Chinese. The leader dispatches in Chinese, the worker reports back in Chinese. Switch back to the user's language only at the user-facing boundary.
-
-## Minimal Copy-Paste Team
-
-```bash
-mkdir -p .team/current/agents
-team-agent profile init codex-default --auth-mode subscription --workspace .
-cat > .team/current/TEAM.md <<'EOF'
----
-name: demo-team
-objective: One worker handles bounded tasks and reports through Team Agent MCP.
-dangerous_auto_approve: false
-fast: false
-provider_models:
-  codex: gpt-5.5
-  claude: claude-sonnet-4-6
-  claude_code: claude-sonnet-4-6
----
-
-Team config only. This is not a worker role.
-EOF
-cat > .team/current/agents/coder.md <<'EOF'
----
-name: coder
-role: Implementation Worker
-provider: codex
-auth_mode: subscription
-profile: codex-default
-tools:
-  - fs_read
-  - fs_list
-  - fs_write
-  - execute_bash
-  - mcp_team
-  - provider_builtin
----
-
-Handle one bounded task at a time. Send progress to leader only when needed. Final completion must call report_result exactly once; MCP fills task ids and result envelope fields.
-EOF
-team-agent quick-start .team/current
-```
-
-YAML lists must be block style. Use `tools:\n  - fs_read`; do not use `tools: [fs_read, mcp_team]`.
-
-Display choices (set `display_backend:` in `TEAM.md` to opt in):
-
-- `none` (default): headless / no GUI window manager. The team runs entirely in the per-workspace tmux server; this is what the demo above uses.
-- `adaptive`: framework picks an available GUI layout for the local platform.
-- `ghostty_workspace`: one Ghostty window. Workers are shown in tmux tabs/windows, up to 3 side-by-side panes per tab. Four workers become `3 + 1`; eight become `3 + 3 + 2`.
-- `ghostty_window`: one Ghostty window per worker.
+**Launch** from a tmux-addressable pane: `team-agent claude` or `team-agent codex`, then `team-agent quick-start .team/current`. Do not start a real team from a naked terminal. Existing tmux/Ghostty layouts are valid if `quick-start` runs from the leader pane.
 
-**Omitting `display_backend` defaults to `none`** (changed in 0.3.4). Set `display_backend: adaptive` (or one of the explicit ghostty variants) in `TEAM.md` only when the user wants GUI windows.
+**Operate**
 
-## Private Tmux Socket
+- Dispatch: `team-agent send TO MESSAGE` (positional TO; `--watch-result` is deprecated). After success, do not poll with `sleep` / `status` / `inbox` / `collect`.
+  TO has two co-equal logical forms: an **in-team short name** (`team-agent send reviewer "..."`) and a fully qualified `<workspace>::<team>/<agent>`. Use the qualified form across workspaces.
+- Inspect: `team-agent status` / `status --json`. `ok: true` plus `ready: false` is not a crash.
+- Lifecycle: `restart .` resumes a stopped team; `add-agent NAME --role-file FILE` adds or `--force` recreates one worker; `shutdown --workspace .` stops. Do not shutdown the whole team to add a worker.
+- Roles: every `agents/*.md` must declare boolean `dangerously_skip_permissions`. Never rewrite a user-supplied model id. Never read `.env` files.
 
-Worker windows live on a private per-workspace tmux server, not the user's default socket. `tmux list-sessions` (no `-L`/`-S`) will not show them; that is expected, not a failure.
+**On failure:** if the CLI prints a structured `action`, run that `action` first, then stop. Do not guess flags. `coordinator.session_missing` is a self-healing transient — re-check `status --json`; do not shutdown because of it.
 
-To attach manually, read `attach_commands` (or the `tmux` action printed near `ready:`) from `team-agent quick-start` / `team-agent restart` / `team-agent status --json` output. It is the canonical `tmux -L <socket-name> attach -t <session>` (or `-S <socket-path>`) line for the current team.
-
-Use `team-agent attach-leader` / `team-agent claim-leader` to bind the leader pane to a team. Do not invent socket paths by hand.
+The current user-facing agent is the leader (orchestrate only). Workers call `report_result` exactly once. Nested teams: `skills/team-agent/references/team-in-team.md`.
 
 ## Provider Capability Matrix
 
+Claude / Codex / Copilot / Gemini / fake: `docs/reference/team-agent-operator.md`. These two are in the runtime but were missing from that table:
+
 | Provider | Resume | Turn-state detection | Per-worker model override | Native session fork |
 |---|---|---|---|---|
-| `claude` / `claude_code` | yes (`--resume <id>`, transcript-verified) | yes (JSONL stream) | yes (role `model` overrides `provider_models`) | yes (snapshot copy + only `--resume <snapshot-id>`) |
-| `codex` | yes (`codex resume <id>`, session-store-verified) | yes (turn JSONL) | yes (role `model`) | yes (`codex fork`) |
-| `copilot` | yes (`copilot --resume <id|name>`, sqlite `sessions` row) | not yet (phase 1: `provider.classify.unsupported` event) | yes (role `model`) | yes (isolated `COPILOT_HOME` store fork) |
-| `gemini_cli` | no | no | yes | no |
-| `fake` (testing only) | no | no | n/a | no |
+| `grok` | yes (`--resume <id>`, archive-gated) | no | yes (role `model` required) | yes (`--fork-session` + new `--session-id`) |
+| `cursor_agent` | yes (argv `--resume <chatId>`, archive-gated) | no | required on role; same-family catalog id can take effect; unknown id silent-fallback; pane chrome ≠ proven live | **no — `CapabilityUnsupported`** |
 
-Notes:
-- Per-worker model override means a role-doc `model:` value wins over `TEAM.md` `provider_models.<provider>`; subscription defaults still fill blanks.
-- Copilot fork copies the source session into an isolated `COPILOT_HOME` and rekeys its SQLite session references atomically. Missing or incomplete backing fails closed; it never falls back to a fresh spawn.
-- Copilot phase-1 idle/turn detection is intentionally Unknown; tick emits a single explicit `provider.classify.unsupported` event per state change (P4 dedup), never a silent default.
+Grok / `cursor_agent` have no JSONL turn-state reader (classify → Unknown).
 
 ## Provider Prep
 
-### Subscription auth (Codex / Claude account login)
-
-Before workers can use a subscription provider, create a named subscription profile in the workspace and reference it from role docs:
-
-```bash
-team-agent profile init codex-default --auth-mode subscription --workspace .
-team-agent profile init claude-default --auth-mode subscription --workspace .
-```
-
-Then in `agents/<role>.md` frontmatter, set `auth_mode: subscription` and `profile: codex-default` (or `claude-default`). The demo above uses `profile: codex-default`; that name only works after `profile init` has created it in the same workspace.
-
-Common errors:
-
-- `profile already exists`: a profile by that name is already in `.team/current/profiles/`. Either reuse it (skip `init`) or pick a new name.
-- `profile not found` during quick-start: the role doc references a profile that was never `profile init`-ed in this workspace. Run `team-agent profile init <name> --auth-mode subscription --workspace .` and retry.
-
-### Codex provider notes
-
-Codex: run `codex login` first. Optional `~/.codex/config.toml` profile:
-
-```toml
-[profiles.team-agent]
-model = "gpt-5.5"
-approval_policy = "on-request"
-sandbox_mode = "workspace-write"
-```
-
-Use exact provider model ids, not display names. For Codex workers, the model must match a `slug` from `codex debug models`; for example use `gpt-5.3-codex-spark`, not `GPT-5.3-Codex-Spark`.
-Role docs may omit `model` for subscription workers. Team Agent fills subscription defaults from `TEAM.md` `provider_models`, then built-in provider defaults (`codex: gpt-5.5`, `claude/claude_code: claude-sonnet-4-6`). Use role-level `model` only for intentional per-worker overrides.
-
-Claude: run `claude auth status`; if missing, run `claude auth login`. Team Agent stores Claude worker sessions by passing `--session-id` and resumes with `--resume`.
-Use `provider: claude` or `provider: claude_code` for Claude workers.
-
-If the current leader process was started with `claude --dangerously-skip-permissions` or `codex --dangerously-bypass-approvals-and-sandbox`, Team Agent inherits that permission mode for worker launch, restart, and single-agent repair.
-Role `profile` values are secret-safe references. Do not put API keys in role docs or `TEAM.md`.
-Never read raw provider profile files into model context. Do not use `Read`, `cat`, `sed`, `grep`, editors, or screenshots on `.team/current/profiles/*.env` or `.team/runtime/provider-env/*.env`. Those files may contain live API keys. Use only `team-agent profile show <name> --workspace . --json` or `team-agent profile doctor <name> --workspace . --json` for redacted diagnostics; if a value is missing, ask the human user to edit the local profile file.
-When the user asks for a third-party or compatible API, do not ask them to paste keys into the chat. Generate a local blank profile instead, for example:
-
-```bash
-team-agent profile init deepseek --auth-mode compatible_api --workspace .
-```
-
-Tell the user to fill `.team/current/profiles/deepseek.env` locally:
-
-```env
-AUTH_MODE=compatible_api
-PROFILE_NAME=deepseek
-BASE_URL=
-API_KEY=
-MODEL=
-```
-
-Then reference only `auth_mode: compatible_api` and `profile: deepseek` in role docs. Do not invent or duplicate a role `model` when the profile already has `MODEL=`; if both places define a model they must match exactly. Team Agent loads the profile automatically during quick-start, launch, restart, and start-agent. Compatible API workers inherit the current shell proxy/CA environment by default. Claude compatible API workers use Team Agent managed `CLAUDE_CONFIG_DIR` so user-level Claude subscription settings cannot re-inject Anthropic proxy variables into third-party API sessions. If quick-start reports an ambient proxy blocker, do not silently unset proxy for the whole team; tell the user to choose one path: fix that proxy for `BASE_URL`, put `HTTPS_PROXY=`/`HTTP_PROXY=` in the profile, or put `PROXY_MODE=direct` in the profile to bypass proxy only for that worker. Subscription workers keep their native provider settings and environment. Startup runs a redacted smoke check for compatible API profiles before worker windows are created, so a bad URL/key/model or proxy/base URL connectivity failure is reported to the leader command instead of producing idle workers.
-For diagnosis, run `team-agent profile show deepseek --workspace . --json`; never open the `.env` file to check whether `API_KEY` or `MODEL` is filled.
-
-## Commands
-
-- `team-agent codex ...` starts or attaches a tmux-managed Codex leader in the current directory; arguments after `codex` pass through to Codex.
-- `team-agent claude ...` starts or attaches a tmux-managed Claude leader in the current directory; arguments after `claude` pass through to Claude.
-- `team-agent quick-start .team/current` starts workers from `TEAM.md` and `agents/*.md`. When it prints `ready:` and `ready_signal`, startup is complete; do not run sleep/status/wait loops afterward unless diagnosing a failure.
-- For real workers, `quick-start` requires a current tmux leader pane. If it says the leader must run inside tmux, restart the leader with `team-agent codex`/`team-agent claude` or use an existing tmux-managed layout, then run quick-start again.
-- 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 only for first-time team creation from role docs. If that team already has runtime state, use `team-agent restart . --team <session_name_or_team_name>` to resume it. If restart cannot recover context, explain the loss and wait for explicit user consent before using `team-agent restart . --allow-fresh`; never reset context through quick-start.
-- 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.
-- Positional `TO` has two co-equal forms: an in-team short name, for example `team-agent send reviewer "Review this change"`, and a fully-qualified logical name, `<workspace>::<team>/<agent>`. Use the fully-qualified form across workspaces or when the local team scope is ambiguous.
-- Advanced orchestration callers may add `--presentation-sink leader|casefile|silent --message-class CLASS [--case-id CASE]`. All sinks remain durable and pullable; `casefile`/`silent` suppress only live leader injection. Missing presentation metadata preserves the normal leader-visible behavior.
-- 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.
-- `team-agent status` shows team, worker health, result-store counts, `session_id`, `captured_via`, and attribution confidence. `team-agent status --json` is compact and context-safe by default; use `team-agent status --detail --json` only for raw runtime-state diagnostics.
-- `team-agent status coder` shows one worker.
-- `team-agent approvals [coder]` shows structured pending approval prompts without copying worker terminal pages.
-- `team-agent inbox coder` shows message history only. Final results are not in inbox.
-- `team-agent shutdown --workspace . --keep-logs` stops the tmux session after a final session capture attempt.
-- `team-agent restart .` restarts a stopped team from stored worker sessions. If one workspace has multiple restartable teams, use `team-agent restart . --team <session_name_or_team_name>`.
-- `team-agent start-agent coder --workspace .` repairs one missing worker window without interrupting other workers.
-- `team-agent doctor` checks local dependencies and provider auth hints.
-
-## Restart Semantics
+### Cursor provider notes
 
-`restart` takes one workspace argument. It preserves each worker's original provider. If a verified provider session exists, the worker resumes (`codex resume <id>` or `claude --resume <id>`). Claude sessions are considered resumable only after the provider has written a project transcript for that session; a freshly opened blank Claude window is not recorded as recovered context. If the stored id is stale, the runtime first tries to repair it from verified transcript history. If a stored session cannot be verified or repaired, restart fails closed instead of silently losing context; use `team-agent restart . --allow-fresh` only when the user explicitly accepts a fresh worker context. If multiple stopped teams in the same workspace have restart context, plain `team-agent restart .` fails and lists candidates; rerun with `--team <session_name_or_team_name>`. If no prior session id exists, that worker starts fresh and the event log records `restart.fresh_spawn`. Claude resume must run from the original cwd and the same provider transcript root; Team Agent stores `spawn_cwd` and compatible-API `claude_projects_root` for that.
+Frontmatter: `provider: cursor_agent` (not `cursor`; launcher verb is `team-agent cursor`), `auth_mode: subscription`, `name:` required (omit → `missing front matter field name`). Also required: `role:`, `tools:`, `dangerously_skip_permissions:` (bool). Subscription needs no `profile`.
 
-Startup trust prompts are handled by the runtime/coordinator with bounded probes; do not wait on raw worker screens or manually press Enter for routine startup trust prompts.
+`model:` is required (omit compile-fails; blocks a silent builtin `sonnet-4-thinking`). The flag stays on argv. Same-family catalog ids can change pane chrome. An id not in that provider's catalog silent-falls back (landing not stable; no events/stderr/pane warning). Pick names from the catalog; after spawn, `capture-pane` once for chrome. Do not treat the role field or pane chrome as proof of the live model.
 
-Use `team-agent start-agent <agent_id> --workspace .` only as a narrow repair when one worker window is missing after launch/restart/display failure. It preserves the worker provider, resumes from `session_id` when available, starts fresh when there is no prior session id, and does not restart the rest of the team. If an existing session id cannot resume, it fails closed unless the user explicitly passes `--allow-fresh`.
+One `cursor_agent` per workspace. A second seat (including `add-agent --force` of a different id) fail-closes:
 
-## Adding A New Worker At Runtime
-
-To add a new worker to a running team, write the role doc and run **one command** — do not shutdown/restart, do not regenerate the compiled spec, and do not quick-start an existing team:
-
-```bash
-cat > .team/current/agents/reviewer.md <<'EOF'
----
-name: reviewer
-role: Code Reviewer
-provider: codex
-auth_mode: subscription
-profile: codex-default
-tools:
-  - fs_read
-  - fs_list
-  - mcp_team
----
-
-Review changed files and report findings to leader.
-EOF
-team-agent add-agent reviewer --role-file .team/current/agents/reviewer.md --workspace .
 ```
-
-`add-agent` registers the new worker into the running team's state, launches its window on the existing tmux socket, and leaves every other worker untouched. **Do not shutdown/restart for adding a worker** — it loses every other worker's resumable session. If `add-agent` fails, surface the structured error to the user; do not fall back to shutdown.
-
-Semantic distinction:
-
-- `team-agent add-agent <agent> --role-file <file>` — add a **new** worker not yet in team state.
-- `team-agent clone-agent <source> --as <new>` — reread the source worker's latest role file and start a fresh provider seat. It never copies conversation context. Success is initially honest `capture_state: pending_first_turn` with `session_id`, `new_session_id`, and `backing_path` all null; after the first turn, canonical capture changes the state to `captured` and fills the backing tuple.
-- `team-agent fork-agent <source> --as <new>` — reread the same latest role file and create a distinct, verified provider session that forks the source context. If the provider backing cannot be verified, the command fails and rolls back instead of silently cloning fresh.
-- `team-agent start-agent <agent>` — (re)launch a worker that **already exists** in team state but whose window is missing.
-- `team-agent reset-agent <agent> --discard-session` — keep the same seat and deliberately start it with fresh context.
-- `team-agent restart .` — resume a fully **stopped** team from stored worker sessions.
-- `team-agent quick-start <dir>` — first-time team creation from role docs; for existing teams use `restart`, and use `restart --allow-fresh` only after explicit user consent to discard context.
-
-Clone/fork names are always explicit: run concurrent calls with a different `--as` value for each new seat. Fork success includes a verified new `session_id` and independent backing; a tmux window alone is not fork success. Clone success uses the honest `pending_first_turn` state above until first-turn capture, never a fabricated verified tuple. Updating the source role file affects the next clone/fork without requiring a full-team rebuild. Automatic knowledge write-back from a clone/fork into the source role file is not provided.
-
-Removing a worker at runtime is the symmetric `team-agent remove-agent <agent> --workspace . --confirm`.
-
-## Worker Protocol
-
-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")
-# to another teammate:
-team_orchestrator.send_message(to="<agent_id>", content="short coordination note")
-# to every other team member:
-team_orchestrator.send_message(to="*", content="short broadcast")
-team_orchestrator.report_result(summary="short completion", status="success", tests=[{"command":"command","status":"passed"}])
+error: cursor_agent seat already occupies this workspace
+reason: <workspace>/.cursor/mcp.json is directory-scoped; a second seat overwrites TEAM_AGENT_ID (last-writer)
+action: do not add another CursorAgent in this workspace until per-seat MCP identity is isolated
 ```
 
-For typed orchestration traffic, both `send_message` and `report_result` accept `presentation={"sink":"leader|casefile|silent","class":"message|progress|stage_result|stage_pass|bounce|blocking|final_review|timeout","case_id":"optional-case"}`. If the object is present, `sink` and `class` are required and unknown values fail closed. `casefile` and `silent` are durable-only, not deletion. The fixed critical classes `stage_pass`, `bounce`, `blocking`, `final_review`, and `timeout` always appear on the leader screen even when another sink is requested. Routing uses the typed class, never words in the content or summary.
-
-Do not pass `sender`, `task_id`, `requires_ack`, `schema_version`, or `agent_id` unless doing a low-level compatibility diagnostic. The MCP runtime fills those fields and keeps delivery metadata in runtime state and event logs. If provider env loses the worker id, MCP infers it from active task/message state and falls back to an explicit `unknown` sender instead of treating the worker as leader.
-
-Message targets are team-scoped. Use `leader`, another teammate agent id, or `*` for all other team members. The runtime excludes the sender from `*` broadcasts and never scans unrelated terminal windows for recipients.
-
-`report_result` stores final completion and immediately attempts a leader notification through the verified/fallback delivery path. `team-agent collect` remains the authoritative state-update path. Do not wait for final results through `team-agent inbox`, message ack counts, or repeated plain status polling. `acknowledged_count` only means prior task messages were acknowledged by the worker; it is not a missing-result signal.
-For normal leader dispatch, prefer `team-agent send --watch-result ...`; when it returns a registered watcher notice, the framework will notify the leader at completion.
-
-For long processes, workers must write logs, keep a pid, provide a health check, and stop after a bounded number of retries. QA/reviewer roles must stay within their authorized files and stop on service unavailable, approval prompts, or repeated startup failure.
-
-## Failure Rules
-
-For any non-zero `team-agent` exit, report the command, exit code, last about 20 stderr lines, and affected task or agent when known. Then stop and wait for the user.
-
-Do not retry with changed flags. Do not inspect source code or private runtime state. Do not operate tmux directly except when the user asks for a manual diagnostic. Do not answer provider approval prompts for the user.
-
-If `quick-start` reports `tmux session already exists`, treat it as a team-name collision. The existing session may be an active team; do not terminate it and do not suggest `shutdown` as the normal fix. Change `name:` in `TEAM.md` so the next launch uses a different tmux session name, then run `team-agent quick-start .team/current` again.
-
-Known Team Agent control-plane MCP prompts such as `team_orchestrator.report_result` and `team_orchestrator.send_message` are handled by the coordinator. It uses session-scoped approval, verifies the prompt cleared, retries boundedly, and logs the result. Do not ask the user to approve those routine internal prompts.
-
-When `status` still shows `AWAITING_APPROVAL`, run `team-agent approvals <agent_id>`, show the structured prompt summary and choices, ask the user to decide, and wait.
-
-Do not inspect raw worker terminal output during normal operation. Use `team-agent status`, `team-agent approvals`, `team-agent inbox`, `team-agent collect`, and event logs instead. Raw-screen diagnostics are outside this skill's normal workflow, require explicit user authorization, and are guarded by the CLI; use them only as a one-shot bounded diagnostic, never as a routine workflow step.
+Several cursor seats → one workspace directory each. Same seat, fresh context → `reset-agent --discard-session`.
 
-For "worker reported but leader cannot see completion":
+`clone-agent` copies the source role (provider unchanged). Runtime add: `clone-agent` → `stop-agent` → `remove-agent --confirm` (deletes `.team/dynamic-role-files/`) → write the role file → `add-agent --role-file` → dispatch.
 
-1. Run `team-agent collect` once; this is the final-result intake path.
-2. If no result is collected, inspect `team-agent status --json` field `results`. `uncollected > 0` means the result is already accepted by MCP and waiting in the result store.
-3. Check `.team/logs/events.jsonl` for `mcp.report_result` and `collect.result` before sending another prompt to the worker.
-4. Do not loop on `team-agent inbox` or ack/status counts; that burns context and cannot consume final results.
+- Restart emits `--resume <chatId>` when `store.db`/`meta.json` exist; the gate does not read chat text. Persist anything that must survive restart.
+- Delivery sends one Enter; a second Enter interrupts the turn.
+- After spawn, the pane footer should show `Cursor Agent v<version>`. Do not use `strings` to probe the binary.