@tmustier/pi-agent-teams 0.2.0 → 0.3.0

package/README.md

@@ -79,6 +79,7 @@ Or drive it manually:
 /tw                                        # open the interactive widget panel
 
 /team shutdown alice                       # graceful shutdown (handshake)
+/team shutdown                             # stop all teammates (leader session remains active)
 /team cleanup                              # remove team artifacts when done
 ```
 
@@ -105,6 +106,7 @@ Or let the model drive it with the delegate tool:
 | --- | --- |
 | `/swarm [task]` | Tell the agent to spawn a team and work on a task |
 | `/tw` | Open the interactive widget panel |
+| `/team-widget` | Open the interactive widget panel (alias for `/tw`) |
 
 ### Team management
 
@@ -122,7 +124,7 @@ All management commands live under `/team`.
 | `/team broadcast <msg>` | Message all teammates |
 | `/team stop <name> [reason]` | Abort current work (resets task to pending) |
 | `/team shutdown <name> [reason]` | Graceful shutdown (handshake) |
-| `/team shutdown` | Shutdown leader + all teammates |
+| `/team shutdown` | Stop all teammates (leader session remains active) |
 | `/team kill <name>` | Force-terminate |
 | `/team cleanup [--force]` | Delete team artifacts |
 | `/team id` | Print team/task-list IDs and paths |
@@ -166,13 +168,22 @@ All management commands live under `/team`.
 
 ## Development
 
+### Quality gate
+
+```bash
+npm run check
+```
+
+Runs strict TypeScript typechecking (`npm run typecheck`) and ESLint (`npm run lint`).
+
 ### Smoke test (no API keys)
 
 ```bash
-node scripts/smoke-test.mjs
+npm run smoke-test
+# or: npx tsx scripts/smoke-test.mts
 ```
 
-Filesystem-level test of the task store, mailbox, and team config.
+Filesystem-level smoke test of the task store, mailbox, team config, and protocol parsers.
 
 ### E2E RPC test (spawns pi + one teammate)
 

package/docs/claude-parity.md

@@ -40,11 +40,11 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 | Display modes | In-process selection (Shift+Up/Down); split panes (tmux/iTerm) | ❌ | Pi has a widget + commands, but no terminal-level comrade navigation/panes. | P2 |
 | Delegate mode | Lead restricted to coordination-only tools | ✅ | `/team delegate [on|off]` toggles; `pi.on("tool_call")` blocks `bash/edit/write`; `PI_TEAMS_DELEGATE_MODE=1` env. Widget shows `[delegate]`. | P1 |
 | Plan approval | Comrade can be "plan required" and needs lead approval to implement | ✅ | `/team spawn <name> plan` sets `PI_TEAMS_PLAN_REQUIRED=1`; worker restricted to read-only tools; submits plan via `plan_approval_request`; `/team plan approve|reject <name>`. | P1 |
-| Shutdown handshake | Lead requests shutdown; comrade can approve/reject | ✅ | Full protocol: `shutdown_request` → `shutdown_approved` or `shutdown_rejected` (when worker is busy). `/team shutdown <name>` (graceful) + `/team kill` (force). | P1 |
+| Shutdown handshake | Lead requests shutdown; comrade can approve/reject | ✅ | Full protocol: `shutdown_request` → `shutdown_approved` or `shutdown_rejected` (when worker is busy). `/team shutdown <name>` (graceful) + `/team kill <name>` (force). | P1 |
 | Cleanup team | “Clean up the team” removes shared resources after comrades stopped | ✅ | `/team cleanup [--force]` deletes only `<teamsRoot>/<teamId>` after safety checks. | P1 |
 | Hooks / quality gates | `ComradeIdle`, `TaskCompleted` hooks | ❌ | Add optional hook runner in leader on idle/task-complete events (script execution + exit-code gating). | P2 |
 | Task list UX | Ctrl+T toggle; show all/clear tasks by asking | 🟡 | Widget + `/team task list` show blocked/deps; `/team task show <id>`; `/team task clear [completed|all]`. No Ctrl+T toggle yet. | P0 |
-| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | ✅ | `PI_TEAMS_TASK_LIST_ID` env on leader + worker; `/team task use <taskListId>` switches the leader (and newly spawned workers). Existing workers need a restart to pick up changes. Persisted in config.json. | P1 |
+| Shared task list across sessions | `CLAUDE_CODE_TASK_LIST_ID=...` | ✅ | `PI_TEAMS_TASK_LIST_ID` env is **worker-side** (for manually started workers). The leader switches task lists via `/team task use <taskListId>` (persisted in `config.json`). Newly spawned workers inherit the new task list ID; existing workers need a restart to pick up changes. | P1 |
 
 ## Prioritized roadmap
 
@@ -66,7 +66,7 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 4) **Shutdown handshake** ✅
    - Full protocol: `shutdown_request` → `shutdown_approved` / `shutdown_rejected`
    - Worker rejects when busy (streaming + active task), auto-approves when idle
-   - Leader command: `/team shutdown <name> [reason...]` (graceful), `/team kill` as force
+   - Leader command: `/team shutdown <name> [reason...]` (graceful), `/team kill <name>` as force
 
 5) **Plan approval** ✅
    - `/team spawn <name> [fresh|branch] [shared|worktree] plan` sets `PI_TEAMS_PLAN_REQUIRED=1`
@@ -109,7 +109,9 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 
 ## Where changes would land (code map)
 
-- Leader orchestration + commands + tool: `extensions/teams/leader.ts`
+- Leader orchestration: `extensions/teams/leader.ts`
+- Leader `/team` command dispatch: `extensions/teams/leader-team-command.ts`
+- Leader LLM tool (`teams`): `extensions/teams/leader-teams-tool.ts`
 - Worker mailbox polling + self-claim + protocols: `extensions/teams/worker.ts`
 - Task store + locking: `extensions/teams/task-store.ts`, `extensions/teams/fs-lock.ts`
 - Mailbox store + locking: `extensions/teams/mailbox.ts`
@@ -120,5 +122,5 @@ Legend: ✅ implemented • 🟡 partial • ❌ missing
 
 - Keep tests hermetic by setting `PI_TEAMS_ROOT_DIR` to a temp directory.
 - Extend:
-  - `scripts/smoke-test.mjs` for filesystem-only behaviors (deps, claiming, locking)
+  - `scripts/smoke-test.mts` (run via `npm run smoke-test`) for filesystem-only behaviors (deps, claiming, locking)
   - `scripts/e2e-rpc-test.mjs` for protocol flows (shutdown handshake, plan approval)

package/docs/smoke-test-plan.md

@@ -12,9 +12,10 @@ Exercises all core primitives directly via `tsx`:
 
 ```bash
 npx tsx scripts/smoke-test.mts
+# or: npm run smoke-test
 ```
 
-**What it tests** (60 assertions):
+**What it tests** (overview):
 
 | Module           | Coverage                                                        |
 |------------------|-----------------------------------------------------------------|
@@ -24,10 +25,10 @@ npx tsx scripts/smoke-test.mts
 | `task-store.ts`  | CRUD, `startAssignedTask`, `completeTask`, `claimNextAvailable`,|
 |                  | `unassignTasksForAgent`, dependencies, `clearTasks`             |
 | `team-config.ts` | `ensureTeamConfig` (idempotent), `upsertMember`, `setMemberStatus`, `loadTeamConfig` |
-| `protocol.ts`    | All 11 message parsers (valid + invalid JSON + wrong type)      |
-| Pi CLI           | `pi --version` executes                                        |
+| `protocol.ts`    | Structured message parsers (valid + invalid JSON + wrong type)  |
+| Pi CLI           | `pi --version` executes (skipped in CI if `pi` not on PATH)     |
 
-**Expected result:** `PASSED: 60  FAILED: 0`
+**Expected result:** `PASSED: <n>  FAILED: 0`
 
 ## 2. Extension Loading Test
 
@@ -103,6 +104,14 @@ Ask the model:
 
 **Expected:** agent1 goes offline, widget updates.
 
+Optional: stop all teammates without ending the leader session:
+
+```
+/team shutdown
+```
+
+**Expected:** all teammates stop; leader remains active until you exit it (e.g. ctrl+d).
+
 ## 4. Worker-side Smoke (verifying child process)
 
 To test the worker role directly:

package/eslint.config.js

@@ -0,0 +1,74 @@
+// @ts-check
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+	{
+		ignores: [
+			"node_modules/**",
+			"dist/**",
+			"build/**",
+			"coverage/**",
+			".artifacts/**",
+			".research/**",
+			".resume-sessions/**",
+		],
+	},
+
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+
+	{
+		files: ["extensions/**/*.ts", "scripts/**/*.ts", "scripts/**/*.mts"],
+		rules: {
+			// ━━ Project invariants (AGENTS.md) ━━
+			"@typescript-eslint/no-explicit-any": "error",
+			"@typescript-eslint/no-non-null-assertion": "error",
+			"@typescript-eslint/ban-ts-comment": [
+				"error",
+				{
+					"ts-ignore": true,
+					"ts-expect-error": true,
+					"ts-nocheck": true,
+					"ts-check": false,
+				},
+			],
+
+			// Imports/types
+			"@typescript-eslint/consistent-type-imports": [
+				"error",
+				{ prefer: "type-imports", disallowTypeAnnotations: false },
+			],
+
+			// General correctness
+			eqeqeq: ["error", "always"],
+
+			// Prefer TS-aware unused-vars
+			"no-unused-vars": "off",
+			"@typescript-eslint/no-unused-vars": [
+				"warn",
+				{
+					argsIgnorePattern: "^_",
+					varsIgnorePattern: "^_",
+					caughtErrorsIgnorePattern: "^_",
+				},
+			],
+		},
+	},
+
+	// Scripts/tests: console is expected
+	{
+		files: ["scripts/**/*.ts", "scripts/**/*.mts"],
+		rules: {
+			"no-console": "off",
+		},
+	},
+
+	// Extension source: discourage stray console.log
+	{
+		files: ["extensions/**/*.ts"],
+		rules: {
+			"no-console": "warn",
+		},
+	},
+);

package/extensions/teams/activity-tracker.ts

@@ -68,7 +68,7 @@ export class TranscriptTracker {
 		if (ev.type === "tool_execution_end") {
 			const starts = this.toolStarts.get(name);
 			const startTs = starts?.get(ev.toolCallId);
-			const durationMs = startTs != null ? now - startTs : 0;
+			const durationMs = startTs === undefined ? 0 : now - startTs;
 			starts?.delete(ev.toolCallId);
 			log.push({ kind: "tool_end", toolName: ev.toolName, durationMs, timestamp: now });
 			return;
@@ -135,7 +135,7 @@ export class TranscriptTracker {
 			// Flush all complete lines, keep the last (potentially incomplete) part
 			for (let i = 0; i < parts.length - 1; i++) {
 				const part = parts[i];
-				if (part == null) continue;
+				if (part === undefined) continue;
 				const trimmed = part.trimEnd();
 				if (trimmed) log.push({ kind: "text", text: trimmed, timestamp });
 			}

package/extensions/teams/leader-lifecycle-commands.ts

@@ -144,8 +144,11 @@ export async function handleTeamShutdownCommand(opts: {
 	leadName: string;
 	style: TeamsStyle;
 	getCurrentCtx: () => ExtensionContext | null;
+	stopAllTeammates: (ctx: ExtensionContext, reason: string) => Promise<void>;
+	refreshTasks: () => Promise<void>;
+	renderWidget: () => void;
 }): Promise<void> {
-	const { ctx, rest, teammates, leadName, style, getCurrentCtx } = opts;
+	const { ctx, rest, teammates, leadName, style, getCurrentCtx, stopAllTeammates, refreshTasks, renderWidget } = opts;
 	const strings = getTeamsStrings(style);
 	const nameRaw = rest[0];
 
@@ -216,21 +219,32 @@ export async function handleTeamShutdownCommand(opts: {
 		return;
 	}
 
-	// /team shutdown (no args) = shutdown leader + all teammates
-	// Only prompt in interactive TTY mode. In RPC mode, confirm() would require
-	// the host to send extension_ui_response messages.
+	// /team shutdown (no args) = stop all teammates but keep the leader session alive
+	if (teammates.size === 0) {
+		ctx.ui.notify(`No ${strings.memberTitle.toLowerCase()}s to shut down`, "info");
+		return;
+	}
+
 	if (process.stdout.isTTY && process.stdin.isTTY) {
 		const msg =
 			style === "soviet"
-				? `Dissolve the ${strings.teamNoun} and dismiss all ${strings.memberTitle.toLowerCase()}s?`
-				: "Shutdown this team and stop all teammates?";
-		const ok = await ctx.ui.confirm("Shutdown", msg);
+				? `Dismiss all ${strings.memberTitle.toLowerCase()}s from the ${strings.teamNoun}?`
+				: `Stop all ${String(teammates.size)} teammate${teammates.size === 1 ? "" : "s"}?`;
+		const ok = await ctx.ui.confirm("Shutdown team", msg);
 		if (!ok) return;
 	}
-	// In RPC mode, shutdown is deferred until the next input line is handled.
-	// Teammates are stopped in the session_shutdown handler.
-	ctx.ui.notify("Shutdown requested", "info");
-	ctx.shutdown();
+
+	const reason =
+		style === "soviet"
+			? `The ${strings.teamNoun} is dissolved by the chairman`
+			: "Stopped by /team shutdown";
+	await stopAllTeammates(ctx, reason);
+	await refreshTasks();
+	renderWidget();
+	ctx.ui.notify(
+		`Team ended: all ${strings.memberTitle.toLowerCase()}s stopped (leader session remains active)`,
+		"info",
+	);
 }
 
 export async function handleTeamStopCommand(opts: {
@@ -244,7 +258,6 @@ export async function handleTeamStopCommand(opts: {
 	renderWidget: () => void;
 }): Promise<void> {
 	const { ctx, rest, teammates, leadName, style, refreshTasks, getTasks, renderWidget } = opts;
-	const strings = getTeamsStrings(style);
 
 	const nameRaw = rest[0];
 	const reason = rest.slice(1).join(" ").trim();
@@ -300,7 +313,7 @@ export async function handleTeamKillCommand(opts: {
 	refreshTasks: () => Promise<void>;
 	renderWidget: () => void;
 }): Promise<void> {
-	const { ctx, rest, teammates, taskListId, leadName, style, refreshTasks, renderWidget } = opts;
+	const { ctx, rest, teammates, taskListId, leadName: _leadName, style, refreshTasks, renderWidget } = opts;
 	const strings = getTeamsStrings(style);
 
 	const nameRaw = rest[0];

package/extensions/teams/leader-messaging-commands.ts

@@ -71,7 +71,6 @@ export async function handleTeamDmCommand(opts: {
 	style: TeamsStyle;
 }): Promise<void> {
 	const { ctx, rest, leadName, style } = opts;
-	const strings = getTeamsStrings(style);
 
 	const nameRaw = rest[0];
 	const msg = rest.slice(1).join(" ").trim();

package/extensions/teams/leader-plan-commands.ts

@@ -4,7 +4,7 @@ import { sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";
 import { TEAM_MAILBOX_NS } from "./protocol.js";
 import type { TeamsStyle } from "./teams-style.js";
-import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
+import { formatMemberDisplayName } from "./teams-style.js";
 
 export async function handleTeamPlanCommand(opts: {
 	ctx: ExtensionCommandContext;

package/extensions/teams/leader-spawn-command.ts

@@ -1,32 +1,16 @@
-import type { ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { pickComradeNames } from "./names.js";
 import type { TeammateRpc } from "./teammate-rpc.js";
 import type { TeamsStyle } from "./teams-style.js";
 import { formatMemberDisplayName, getTeamsStrings, isSovietStyle } from "./teams-style.js";
-
-export type ContextMode = "fresh" | "branch";
-export type WorkspaceMode = "shared" | "worktree";
-
-export type SpawnTeammateResult =
-	| {
-			ok: true;
-			name: string;
-			mode: ContextMode;
-			workspaceMode: WorkspaceMode;
-			note?: string;
-			warnings: string[];
-	  }
-	| { ok: false; error: string };
+import type { ContextMode, WorkspaceMode, SpawnTeammateFn } from "./spawn-types.js";
 
 export async function handleTeamSpawnCommand(opts: {
 	ctx: ExtensionCommandContext;
 	rest: string[];
 	teammates: Map<string, TeammateRpc>;
 	style: TeamsStyle;
-	spawnTeammate: (
-		ctx: ExtensionContext,
-		opts: { name: string; mode?: ContextMode; workspaceMode?: WorkspaceMode; planRequired?: boolean },
-	) => Promise<SpawnTeammateResult>;
+	spawnTeammate: SpawnTeammateFn;
 }): Promise<void> {
 	const { ctx, rest, teammates, style, spawnTeammate } = opts;
 	const strings = getTeamsStrings(style);

package/extensions/teams/leader-task-commands.ts

@@ -3,7 +3,7 @@ import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { getTeamDir } from "./paths.js";
-import { TEAM_MAILBOX_NS } from "./protocol.js";
+import { taskAssignmentPayload } from "./protocol.js";
 import {
 	addTaskDependency,
 	clearTasks,
@@ -17,7 +17,16 @@ import {
 } from "./task-store.js";
 import { ensureTeamConfig } from "./team-config.js";
 import type { TeamsStyle } from "./teams-style.js";
-import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
+import { formatMemberDisplayName } from "./teams-style.js";
+
+function parseAssigneePrefix(text: string): { assignee?: string; text: string } {
+	const m = text.match(/^([a-zA-Z0-9_-]+):\s*(.+)$/);
+	if (!m) return { text };
+	const assignee = m[1];
+	const rest = m[2];
+	if (!assignee || !rest) return { text };
+	return { assignee, text: rest };
+}
 
 export async function handleTeamTaskCommand(opts: {
 	ctx: ExtensionCommandContext;
@@ -29,8 +38,6 @@ export async function handleTeamTaskCommand(opts: {
 	getTasks: () => TeamTask[];
 	refreshTasks: () => Promise<void>;
 	renderWidget: () => void;
-	parseAssigneePrefix: (text: string) => { assignee?: string; text: string };
-	taskAssignmentPayload: (task: TeamTask, assignedBy: string) => unknown;
 }): Promise<void> {
 	const {
 		ctx,
@@ -42,10 +49,7 @@ export async function handleTeamTaskCommand(opts: {
 		getTasks,
 		refreshTasks,
 		renderWidget,
-		parseAssigneePrefix,
-		taskAssignmentPayload,
 	} = opts;
-	const strings = getTeamsStrings(style);
 
 	const [taskSub, ...taskRest] = rest;
 	const teamId = ctx.sessionManager.getSessionId();