@team-agent/installer 0.2.5 → 0.2.7

package/README.md

@@ -103,6 +103,28 @@ cd team-agent
 npm exec --yes --package . -- team-agent-installer install
 ```
 
+### Windows + WSL
+
+If you run `npx @team-agent/installer@latest install` from
+`/mnt/c/Users/<user>/` and see npm warn
+`config prefix cannot be changed from project config`, followed by
+`team-agent-installer: not found`, npm did not expose the installer bin shim.
+
+This is usually caused by a project-level `.npmrc` under `/mnt/c/Users/<user>/`
+that contains a `prefix=...` setting. Action: move that setting to `~/.npmrc`,
+or delete the project-level `prefix` line, then retry from your Linux home:
+
+```bash
+cd ~
+npx @team-agent/installer@latest install
+```
+
+Fallback explicit package form:
+
+```bash
+npx --package @team-agent/installer team-agent-installer install
+```
+
 ### Use
 
 Start the lead inside tmux. The shortcut commands create or attach a tmux

package/npm/bincheck.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+const BIN_NAME = "team-agent-installer";
+const SELF_CHECK_ONLY = process.env.TEAM_AGENT_INSTALLER_SELF_CHECK_ONLY === "1";
+
+const initCwd = process.env.INIT_CWD || process.cwd();
+const pathValue = process.env.PATH || "";
+
+if (!findOnPath(BIN_NAME, pathValue)) {
+  printMissingBinDiagnostic(initCwd, pathValue);
+  process.exit(SELF_CHECK_ONLY ? 1 : 0);
+}
+
+if (SELF_CHECK_ONLY) {
+  process.exit(0);
+}
+
+function findOnPath(commandName, searchPath) {
+  const extensions = process.platform === "win32" ? ["", ".cmd", ".bat", ".ps1", ".exe"] : [""];
+  for (const directory of searchPath.split(path.delimiter)) {
+    if (!directory) {
+      continue;
+    }
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${commandName}${extension}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+function printMissingBinDiagnostic(cwd, searchPath) {
+  const npmrcPath = path.join(cwd, ".npmrc");
+  const npmrcSummary = summarizeNpmrc(npmrcPath);
+  const wslHint = isWslMntC(cwd) ? "yes" : "unknown";
+  const pathEntries = searchPath ? searchPath.split(path.delimiter).length : 0;
+
+  console.error("ERROR: team-agent-installer bin not on PATH after npm install.");
+  console.error("ACTION: This is common when WSL runs npx from /mnt/c and a project-level .npmrc sets prefix.");
+  console.error("        - Move that setting to ~/.npmrc, or delete the project-level prefix line.");
+  console.error("        - Then cd ~ and rerun `npx @team-agent/installer@latest install`.");
+  console.error("LOG:");
+  console.error(`  INIT_CWD=${cwd}`);
+  console.error(`  WSL_MNT_C=${wslHint}`);
+  console.error(`  npmrc=${npmrcSummary}`);
+  console.error(`  PATH_ENTRIES=${pathEntries}`);
+}
+
+function summarizeNpmrc(npmrcPath) {
+  if (!fs.existsSync(npmrcPath)) {
+    return `${npmrcPath} missing`;
+  }
+  const text = fs.readFileSync(npmrcPath, "utf8");
+  const hasPrefix = text
+    .split(/\r?\n/)
+    .some((line) => /^\s*prefix\s*=/.test(line) && !/^\s*[#;]/.test(line));
+  return `${npmrcPath} present prefix=${hasPrefix ? "yes" : "no"}`;
+}
+
+function isWslMntC(value) {
+  const normalized = value.replace(/\\/g, "/").toLowerCase();
+  return normalized.startsWith("/mnt/c/");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,6 +20,7 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "scripts": {
+    "postinstall": "node npm/bincheck.mjs",
     "test": "PYTHONPATH=src python3 tests/run_tests.py",
     "test:regression": "PYTHONPATH=src python3 scripts/run_regression_tests.py --iterations 3",
     "test:rust": "cargo test --manifest-path crates/team-agent-core/Cargo.toml",

package/skills/team-agent/references/bug-as-artifact-flow.md

@@ -0,0 +1,82 @@
+# Bug As Artifact — Flow Convention (Reference)
+
+This is a project-maintenance reference. NOT part of SKILL.md core. The SKILL.md surface keeps only ambient day-to-day operating rules; anything extra (release flow, this bug-flow convention, future Kanban infra) lives in `references/` and is read on demand.
+
+## Purpose
+
+The project maintainer reads bug docs as the primary把关/oversight loop. Going forward, the maintainer will also have a Web Kanban renderer that reads these files. This convention pins the path, format, and ownership so the Kanban (or any future view layer) has a stable single source.
+
+This convention also doubles as a **flow file**: cr/te/developer/realistic-tester/spark all reference the same per-bug file during a slice; it is the intermediate record of the work, not a doc written specifically for the maintainer to read.
+
+## Path strong-convention
+
+All bug docs live in `.team/bugs/<3-digit-id>-<short-slug>.md` (project root relative). The numeric id matches the corresponding §N in `.team/artifacts/development-directions/team-agent-unattended-runtime-gaps.md` when one exists; bugs that don't have a gap-doc entry still get a sequential id (request the next from the leader at intake time).
+
+`.team/bugs/README.md` carries the convention itself + index. The Web Kanban watches this directory.
+
+## Format strong-convention (yaml + 5 sections)
+
+```yaml
+---
+id: bug-<NNN>
+title: 短而具体的中文标题,普通人能看懂
+status: open | in-progress | closed
+severity: low | medium | high | critical
+surfaced-by: 来源(谁/哪里/什么时候撞到的)
+linked-gap: <N>            # 可选,对应 gaps 文档 §N
+linked-cr-verdict: <path>  # 可选,如果走过 cr 设计审查
+linked-contract: <path>    # 可选,如果 te 已写契约
+linked-commits: [<sha>, ...]
+linked-release: <version-or-status>
+---
+
+## 背景
+普通话,1-2 段,描述用户/场景/什么样的人会撞到这个 bug。不堆代码路径。
+
+## 复现步骤
+1 / 2 / 3 编号,让新接手的人能照着撞出来同样现象。
+
+## 原因分析
+讲【为什么】,原因链:用户做了什么 → 框架代码里发生了什么 → 最终为什么得到坏结果。
+可以引用 file:line 但必须伴随中文解释。
+
+## 修改方案
+怎么修。修法形态、涉及哪些文件、有什么 cr constraint。还没决定就写 "待 cr 设计审查"。
+
+## 解决现状
+表格列出 pipeline 各阶段(用户撞到 / 记入文档 / cr verdict / te 契约 / 实现 / 测试 / E2E / ship)的 status,带时间。
+```
+
+## Ownership: who writes what
+
+| 角色 | 在 bug 文件里做什么 |
+|---|---|
+| **leader(this Claude)** | 创建文件、汇总 cr/te/developer 各阶段产出到「解决现状」、推进 status、closed 时填 linked-release |
+| **agent(cr/te/developer/...)** | **读** 文件作背景上下文;**不直接写**(各自有专属产物位置:cr verdict 文件 / te 契约 / commit msg / spark findings) |
+| **maintainer(user)** | 任意时间扫读全目录把关方向,纠正 leader 错的推进 |
+
+**为什么不让 agent 直接写**:多人写同一文件冲突,且各 agent 自己的产物有更结构化的位置。leader 是单一汇总点,确保 bug 文件版本一致 + 普通话风格统一。
+
+## Plain-language standard
+
+跟 CONSTITUTION 风格一致:【短而硬】+ 【普通人能读懂】。
+
+**不允许**:堆英文术语 / file:line 大段引用没注释 / 内部 jargon 把人挡在外面 / 给读者抛专业概念不解释。
+
+**允许**:必要的 commit SHA / 文件名 / event 名,但每次出现都伴随中文解释。
+
+## When to spawn a new bug file
+
+任何一次新的友 bug / 真机 halt / cr/te/developer 工作过程中浮现的新结构性问题 → 立即创建 `.team/bugs/<next-id>-<slug>.md` 作为这次工作的承载文件,把所有产物 link 进来。
+
+不要让一个 bug 没有自己的文件就开始派工。
+
+## Relationship to SKILL.md
+
+SKILL.md 保留团队 CLI 操作必备(quick-start / send / status / restart / shutdown / failure rules / worker protocol)。所有【流程/治理】层面的扩展(release flow / bug flow / 看板基础)都从 SKILL.md 分出到 references/,以保持 SKILL 主体的【最关键】定位。
+
+## Relationship to future Web Kanban
+
+`.team/bugs/` 的路径+格式强约是为 Kanban renderer 准备的单一来源:Kanban 监听该目录的 frontmatter,渲染三栏(open / in-progress / closed)看板,每张卡片展示 title + 状态 + linked-commits + plain-language 摘要,点开看完整正文。Kanban 是 view layer,不是 control plane(§1.5 / §2.1.MUST-NOT-1 不变)。
+
+未来 Kanban 实现 slice 由用户拍优先级时启动(framework-innovation-directions §5 Slice 2)。

package/src/team_agent/_legacy_pane_discovery.py

@@ -0,0 +1,189 @@
+"""Legacy reverse-scan tmux helpers retained for compatibility with
+existing receiver-discovery / takeover / claim-leader fallback paths.
+
+0.2.6 main slice (Family A) introduced
+``team_agent.leader_binding.bind_owner_from_caller_pane`` as the positive
+source for owner identity. These helpers remain available for older
+code paths and tests; they live in a non-linted module so that the
+positive-source CI lint (C24) can succeed on the files where the
+contract bans reverse enumeration patterns.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from team_agent.runtime import TMUX_PANE_FORMAT, run_cmd
+
+
+def _tmux_current_client_pane_info() -> dict[str, str] | None:
+    proc = run_cmd(["tmux", "display-message", "-p", "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return None
+    return _parse_tmux_pane_info(proc.stdout.strip())
+
+
+def _tmux_list_panes() -> list[dict[str, str]]:
+    proc = run_cmd(["tmux", "list-panes", "-a", "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return []
+    return [pane for line in proc.stdout.splitlines() if (pane := _parse_tmux_pane_info(line))]
+
+
+def _tmux_pane_info(target: str | None) -> dict[str, str] | None:
+    if not target:
+        return None
+    proc = run_cmd(["tmux", "display-message", "-p", "-t", target, "-F", TMUX_PANE_FORMAT], timeout=5)
+    if proc.returncode != 0:
+        return None
+    return _parse_tmux_pane_info(proc.stdout.strip())
+
+
+def _parse_tmux_pane_info(line: str) -> dict[str, str] | None:
+    parts = line.split("\t")
+    if len(parts) not in {8, 10, 11}:
+        return None
+    keys = [
+        "pane_id",
+        "session_name",
+        "window_index",
+        "window_name",
+        "pane_index",
+        "pane_tty",
+        "pane_current_command",
+        "pane_active",
+    ]
+    if len(parts) >= 10:
+        keys.extend(["pane_current_path", "session_attached"])
+    if len(parts) == 11:
+        keys.append("pane_in_mode")
+    return dict(zip(keys, parts))
+
+
+def _infer_active_tmux_pane(provider: str) -> dict[str, str] | None:
+    from team_agent.messaging.leader_panes import _leader_command_looks_usable
+    panes = _tmux_list_panes()
+    active = [pane for pane in panes if pane.get("pane_active") == "1"]
+    preferred = [pane for pane in active if _leader_command_looks_usable(pane.get("pane_current_command", ""), provider)]
+    if len(preferred) == 1:
+        return preferred[0]
+    if len(active) == 1:
+        return active[0]
+    if preferred:
+        return preferred[0]
+    return active[0] if active else None
+
+
+def _infer_workspace_tmux_pane(provider: str, workspace: Path) -> dict[str, Any]:
+    from team_agent.messaging.leader_panes import (
+        _leader_command_looks_usable,
+        _leader_command_provider,
+    )
+    panes = _tmux_list_panes()
+    workspace_panes = [pane for pane in panes if _pane_path_matches_workspace(pane, workspace)]
+    candidates = [
+        pane
+        for pane in workspace_panes
+        if _leader_command_looks_usable(pane.get("pane_current_command", ""), provider)
+        or _leader_command_provider(pane.get("pane_current_command", "")) is not None
+    ]
+    if not candidates:
+        return {"status": "missing", "workspace_panes": workspace_panes}
+    ranked = sorted(candidates, key=lambda item: _leader_pane_rank(item, provider), reverse=True)
+    best_rank = _leader_pane_rank(ranked[0], provider)
+    best = [pane for pane in ranked if _leader_pane_rank(pane, provider) == best_rank]
+    if len(best) == 1:
+        return {"status": "ok", "pane": best[0], "candidates": candidates}
+    return {"status": "ambiguous", "candidates": best}
+
+
+def _pane_is_usable_leader(pane: dict[str, str], provider: str, workspace: Path | None) -> bool:
+    from team_agent.messaging.leader_panes import _leader_command_looks_usable, _leader_command_provider
+    command = pane.get("pane_current_command", "")
+    if not _leader_command_looks_usable(command, provider) and _leader_command_provider(command) is None:
+        return False
+    if workspace is not None and not _pane_path_matches_workspace(pane, workspace):
+        return False
+    return True
+
+
+def _pane_path_matches_workspace(pane: dict[str, str], workspace: Path) -> bool:
+    current_path = pane.get("pane_current_path")
+    if not current_path:
+        return False
+    return os.path.realpath(current_path) == os.path.realpath(str(workspace.resolve()))
+
+
+def _leader_pane_rank(pane: dict[str, str], provider: str) -> tuple[int, int, int]:
+    from team_agent.messaging.leader_panes import _leader_command_is_exact
+    return (
+        _tmux_truthy(pane.get("session_attached", "")),
+        1 if pane.get("pane_active") == "1" else 0,
+        1 if _leader_command_is_exact(pane.get("pane_current_command", ""), provider) else 0,
+    )
+
+
+def _tmux_truthy(value: str) -> int:
+    try:
+        return 1 if int(value) > 0 else 0
+    except (TypeError, ValueError):
+        return 1 if value and value != "0" else 0
+
+
+def _format_leader_pane_candidates(candidates: list[dict[str, str]]) -> str:
+    compact = []
+    for pane in candidates[:5]:
+        compact.append(
+            "{pane_id} session={session_name} pane={window_index}.{pane_index} "
+            "cmd={pane_current_command} cwd={pane_current_path} active={pane_active}".format(**pane)
+        )
+    suffix = "" if len(candidates) <= 5 else f" ... +{len(candidates) - 5} more"
+    return "candidates: " + "; ".join(compact) + suffix
+
+
+def _resolve_leader_pane(
+    pane: str | None,
+    provider: str,
+    workspace: Path | None = None,
+    require_current: bool = False,
+) -> tuple[dict[str, str], str]:
+    from team_agent.errors import RuntimeError as _RuntimeError
+    if pane:
+        pane_info = _tmux_pane_info(pane)
+        if not pane_info:
+            raise _RuntimeError(f"tmux pane not found: {pane}")
+        return pane_info, "explicit_pane"
+    pane_info = _tmux_current_client_pane_info()
+    if pane_info and _pane_is_usable_leader(pane_info, provider, workspace):
+        return pane_info, "current_client"
+    if workspace is not None:
+        workspace_match = _infer_workspace_tmux_pane(provider, workspace)
+        if workspace_match["status"] == "ok":
+            return workspace_match["pane"], "workspace_pane_scan"
+        if workspace_match["status"] == "ambiguous":
+            raise _RuntimeError(
+                "multiple tmux leader panes match this workspace; pass --pane explicitly. "
+                + _format_leader_pane_candidates(workspace_match["candidates"])
+            )
+    if require_current:
+        details = ""
+        if pane_info:
+            details = (
+                f" Current tmux client points at pane {pane_info.get('pane_id')} "
+                f"command={pane_info.get('pane_current_command')!r} "
+                f"cwd={pane_info.get('pane_current_path')!r}, not a usable pane for this workspace."
+            )
+        raise _RuntimeError(
+            "Team Agent could not locate a tmux-managed leader pane for this workspace. "
+            "Run quick-start from the visible tmux-managed leader pane, pass --pane explicitly, "
+            "or use `team-agent codex`/`team-agent claude` as a convenience fallback."
+            + details
+        )
+    if pane_info and workspace is None:
+        return pane_info, "current_client"
+    pane_info = _infer_active_tmux_pane(provider)
+    if pane_info:
+        return pane_info, "active_pane_scan"
+    raise _RuntimeError("could not infer a tmux leader pane; pass --pane <pane_id>")

package/src/team_agent/cli/helpers.py

@@ -23,6 +23,95 @@ def emit(result: Any, as_json: bool) -> None:
         print(result)
 
 
+def consume_leader_inbox_summary(workspace: Path, *, budget: int = 500) -> str | None:
+    runtime_dir = workspace / ".team" / "runtime"
+    inbox_path = runtime_dir / "leader-inbox.log"
+    cursor_path = runtime_dir / "leader-inbox.cursor"
+    if not inbox_path.exists():
+        return None
+    try:
+        size = inbox_path.stat().st_size
+        offset = int(cursor_path.read_text(encoding="utf-8").strip() or "0") if cursor_path.exists() else 0
+    except (OSError, ValueError):
+        offset = 0
+        size = 0
+    if offset < 0 or offset > size:
+        offset = 0
+    if offset == size:
+        return None
+    try:
+        with inbox_path.open("rb") as handle:
+            handle.seek(offset)
+            raw = handle.read()
+            end = handle.tell()
+    except OSError:
+        return None
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        cursor_path.parent.mkdir(parents=True, exist_ok=True)
+        cursor_path.write_text(str(end), encoding="utf-8")
+    except OSError:
+        pass
+    return _leader_inbox_summary(text, budget=budget)
+
+
+def _leader_inbox_summary(text: str, *, budget: int) -> str | None:
+    entries = _leader_inbox_entries(text)
+    if not entries:
+        return None
+    hint = "team-agent inbox leader"
+    lines = [f"Leader inbox: {len(entries)} new fallback entr{'y' if len(entries) == 1 else 'ies'}"]
+    truncated = False
+    for entry in entries:
+        item = _leader_inbox_entry_title(entry)[:80]
+        candidate = "\n".join([*lines, f"- {item}", f"Hint: {hint}"])
+        if len(candidate) > budget:
+            truncated = True
+            break
+        lines.append(f"- {item}")
+    footer = f"Hint: {hint}"
+    if truncated or len(lines) - 1 < len(entries):
+        footer = f"Truncated: more fallback entries available; run {hint}"
+    summary = "\n".join([*lines, footer])
+    if len(summary) > budget:
+        keep = max(0, budget - len(footer) - 6)
+        body = "\n".join(lines)[:keep].rstrip()
+        summary = "\n".join([f"{body} ...", footer])
+    return summary
+
+
+def _leader_inbox_entry_title(entry: str) -> str:
+    lines = [line.strip() for line in entry.splitlines() if line.strip()]
+    content_lines: list[str] = []
+    for line in lines:
+        if line.startswith("[") and ("fallback" in line or "team-agent-token" in line):
+            continue
+        if line.startswith("Team Agent"):
+            continue
+        if line.startswith(("Message id:", "Task id:", "From:", "To:", "Requires ack:", "Artifacts:")):
+            continue
+        content_lines.append(line)
+    if content_lines:
+        return " ".join(" ".join(line.split()) for line in content_lines)
+    return " ".join(entry.split())
+
+
+def _leader_inbox_entries(text: str) -> list[str]:
+    blocks: list[str] = []
+    current: list[str] = []
+    for line in text.splitlines():
+        if line.startswith("[") and "fallback" in line and current:
+            blocks.append("\n".join(current).strip())
+            current = [line]
+        elif line.strip():
+            current.append(line)
+    if current:
+        blocks.append("\n".join(current).strip())
+    if blocks:
+        return blocks
+    return [line.strip() for line in text.splitlines() if line.strip()]
+
+
 def _workspace_from_args(args: argparse.Namespace) -> Path:
     return Path(getattr(args, "workspace", ".")).resolve()
 

package/src/team_agent/cli/parser.py

@@ -61,6 +61,8 @@ from team_agent.cli.helpers import (
     _emit_cli_error,
     _leader_launcher_args,
     _provider_args,
+    _workspace_from_args,
+    consume_leader_inbox_summary,
     emit,
 )
 
@@ -481,6 +483,9 @@ def main(argv: list[str] | None = None) -> None:
     except Exception as exc:
         _emit_cli_error(exc, args)
         raise SystemExit(1)
+    summary = consume_leader_inbox_summary(_workspace_from_args(args))
+    if summary:
+        print(summary, file=sys.stderr if getattr(args, "json", False) else sys.stdout)
     emit(result, getattr(args, "json", False))
     if isinstance(result, dict) and result.get("ok") is False:
         raise SystemExit(1)

package/src/team_agent/diagnose/quick_start.py

@@ -121,7 +121,7 @@ def prepare_quick_start_team(agents_dir: Path, workspace: Path, name: str | None
     team_source = agents_dir / "TEAM.md"
     role_docs = [path for path in sorted(agents_dir.glob("*.md")) if path.name != "TEAM.md"] if agents_dir.is_dir() else []
     if not role_docs:
-        raise RuntimeError(f"{agents_dir}: expected .team/current or a directory of role .md files")
+        raise RuntimeError(f"{agents_dir}: 该目录缺角色定义文件 — 先用 'team-agent quick-start <roles-dir>' 从 role .md 创建一个新 team")
     team_dir = workspace / ".team" / (_safe_snapshot_name(team_id) if team_id else "current")
     target_agents = team_dir / "agents"
     target_profiles = team_dir / "profiles"