pi-teams 0.2.1 → 0.3.1

package/README.md

@@ -45,22 +45,59 @@ You don't need to learn complex code commands. Just talk to Pi in plain English!
 
 ---
 
-## 🪟 Requirement: tmux
+## 🛠 Available Tools
 
-To show multiple agents on one screen, **pi-teams** requires `tmux` (a terminal multiplexer).
+Pi automatically uses these tools when you give instructions like the examples above.
 
-### 1. Install tmux
+### Team Management
+- `team_create`: Start a new team.
+- `team_delete`: Delete a team and its data.
+- `read_config`: Get details about the team and its members.
+
+### Teammates
+- `spawn_teammate`: Launch a new agent into a `tmux` pane with a role and instructions.
+- `check_teammate`: See if a teammate is still running or has unread messages.
+- `force_kill_teammate`: Stop a teammate and remove them from the team.
+- `process_shutdown_approved`: Orderly shutdown for a finished teammate.
+
+### Task Management
+- `task_create`: Create a new task.
+- `task_list`: List all tasks and their current status.
+- `task_get`: Get full details of a specific task.
+- `task_update`: Update a task's status or owner.
+
+### Messaging
+- `send_message`: Send a message to a teammate or lead.
+- `read_inbox`: Read incoming messages for an agent.
+
+---
+
+## 🤖 Automated Behavior
+
+- **Initial Greeting**: When a teammate is spawned, they will automatically send a message saying they've started and are checking their inbox.
+- **Idle Polling**: Teammates check for new messages every 30 seconds if they are idle.
+- **Context Injection**: Each teammate is given a custom system prompt that defines their role and instructions for the team environment.
+
+---
+
+## 🪟 Requirements: tmux or Zellij
+
+To show multiple agents on one screen, **pi-teams** requires a terminal multiplexer. It supports both **tmux** and **Zellij**.
+
+### Option 1: tmux (Recommended)
+
+#### 1. Install tmux
 - **macOS**: `brew install tmux`
 - **Linux**: `sudo apt install tmux`
 
-### 2. How to run it
+#### 2. How to run it
 Before you start a team, you **must** be inside a tmux session. Simply type:
 ```bash
 tmux
 ```
 Then start `pi` inside that window.
 
-### 3. Navigating Panes (Vanilla tmux)
+#### 3. Navigating Panes (Vanilla tmux)
 When your screen splits into multiple agents, you use "Prefix" commands to move around. By default, the prefix is **`Ctrl+b`**.
 
 - **Switch to next agent**: Press `Ctrl+b` then `o`.
@@ -72,6 +109,13 @@ When your screen splits into multiple agents, you use "Prefix" commands to move
 
 *Note: You can greatly improve this experience by enabling "mouse mode" in your `~/.tmux.conf` file.*
 
+### Option 2: Zellij
+
+If you prefer **Zellij**, simply start `pi` inside a Zellij session. **pi-teams** will detect it via the `ZELLIJ` environment variable and use `zellij run` to spawn teammates in new panes.
+
+- **Switching Panes**: Use `Alt` + `Arrow Keys` (default) to move between agent panes.
+- **Closing Panes**: Use `Ctrl+t` then `p` then `x` (or your configured shortcut) to close a teammate pane if needed, though `force_kill_teammate` is recommended.
+
 ---
 
 ## 📜 Credits & Attribution

package/extensions/index.ts

@@ -6,7 +6,7 @@ import * as teams from "../src/utils/teams";
 import * as tasks from "../src/utils/tasks";
 import * as messaging from "../src/utils/messaging";
 import { Member } from "../src/utils/models";
-import { execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 import path from "node:path";
 import fs from "node:fs";
 
@@ -18,13 +18,17 @@ export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     paths.ensureDirs();
     if (isTeammate) {
+      if (teamName) {
+        const pidFile = path.join(paths.teamDir(teamName), `${agentName}.pid`);
+        fs.writeFileSync(pidFile, process.pid.toString());
+      }
       ctx.ui.notify(`Teammate: ${agentName} (Team: ${teamName})`, "info");
       // Use a shorter, more prominent status at the beginning if possible
       ctx.ui.setStatus("00-pi-teams", `[${agentName.toUpperCase()}]`); 
       
       // Also set the tmux pane title for better visibility
       try {
-        execSync(`tmux select-pane -T "${agentName}"`);
+        spawnSync("tmux", ["select-pane", "-T", agentName]);
       } catch (e) {
         // ignore
       }
@@ -87,13 +91,16 @@ export default function (pi: ExtensionAPI) {
       cwd: Type.String(),
     }),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      if (!teams.teamExists(params.team_name)) {
+      const safeName = paths.sanitizeName(params.name);
+      const safeTeamName = paths.sanitizeName(params.team_name);
+
+      if (!teams.teamExists(safeTeamName)) {
         throw new Error(`Team ${params.team_name} does not exist`);
       }
 
       const member: Member = {
-        agentId: `${params.name}@${params.team_name}`,
-        name: params.name,
+        agentId: `${safeName}@${safeTeamName}`,
+        name: safeName,
         agentType: "teammate",
         model: "sonnet",
         joinedAt: Date.now(),
@@ -104,19 +111,41 @@ export default function (pi: ExtensionAPI) {
         color: "blue",
       };
 
-      await teams.addMember(params.team_name, member);
-      await messaging.sendPlainMessage(params.team_name, "team-lead", params.name, params.prompt, "Initial prompt");
+      await teams.addMember(safeTeamName, member);
+      await messaging.sendPlainMessage(safeTeamName, "team-lead", safeName, params.prompt, "Initial prompt");
 
       const piBinary = process.argv[1] ? `node ${process.argv[1]}` : "pi"; // Assumed on path
-      const cmd = `PI_TEAM_NAME=${params.team_name} PI_AGENT_NAME=${params.name} ${piBinary}`;
       
       let paneId = "";
       try {
-        const tmuxCmd = `tmux split-window -h -dP -F "#{pane_id}" "cd ${params.cwd} && ${cmd}"`;
-        paneId = execSync(tmuxCmd).toString().trim();
-        execSync(`tmux select-layout even-horizontal`);
+        if (process.env.ZELLIJ && !process.env.TMUX) {
+          const zellijArgs = [
+            "run", 
+            "--name", safeName, 
+            "--cwd", params.cwd, 
+            "--close-on-exit",
+            "--", 
+            "env", `PI_TEAM_NAME=${safeTeamName}`, `PI_AGENT_NAME=${safeName}`,
+            "sh", "-c", piBinary
+          ];
+          spawnSync("zellij", zellijArgs);
+          paneId = `zellij_${safeName}`;
+        } else {
+          const tmuxArgs = [
+            "split-window", 
+            "-h", "-dP", 
+            "-F", "#{pane_id}", 
+            "-c", params.cwd, 
+            "env", `PI_TEAM_NAME=${safeTeamName}`, `PI_AGENT_NAME=${safeName}`,
+            "sh", "-c", piBinary
+          ];
+          const result = spawnSync("tmux", tmuxArgs);
+          if (result.status !== 0) throw new Error(`tmux failed with status ${result.status}: ${result.stderr.toString()}`);
+          paneId = result.stdout.toString().trim();
+          spawnSync("tmux", ["select-layout", "even-horizontal"]);
+        }
       } catch (e) {
-        throw new Error(`Failed to spawn tmux pane: ${e}`);
+        throw new Error(`Failed to spawn ${process.env.ZELLIJ && !process.env.TMUX ? "zellij" : "tmux"} pane: ${e}`);
       }
 
       // Update member with paneId
@@ -285,9 +314,23 @@ export default function (pi: ExtensionAPI) {
       const config = await teams.readConfig(params.team_name);
       const member = config.members.find(m => m.name === params.agent_name);
       if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
+      
+      const pidFile = path.join(paths.teamDir(params.team_name), `${params.agent_name}.pid`);
+      if (fs.existsSync(pidFile)) {
+        try {
+          const pid = fs.readFileSync(pidFile, "utf-8").trim();
+          execSync(`kill -9 ${pid}`);
+          fs.unlinkSync(pidFile);
+        } catch (e) {
+          // ignore if process already dead
+        }
+      }
+
       if (member.tmuxPaneId) {
         try {
-          execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+          if (!member.tmuxPaneId.startsWith("zellij_")) {
+            execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+          }
         } catch (e) {
           // ignore
         }
@@ -316,8 +359,13 @@ export default function (pi: ExtensionAPI) {
       let alive = false;
       if (member.tmuxPaneId) {
         try {
-          execSync(`tmux has-session -t ${member.tmuxPaneId}`);
-          alive = true;
+          if (member.tmuxPaneId.startsWith("zellij_")) {
+            // Assume alive if it's zellij for now
+            alive = true;
+          } else {
+            execSync(`tmux has-session -t ${member.tmuxPaneId}`);
+            alive = true;
+          }
         } catch (e) {
           alive = false;
         }
@@ -346,7 +394,11 @@ export default function (pi: ExtensionAPI) {
       if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
       if (member.tmuxPaneId) {
         try {
-          execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+          if (member.tmuxPaneId.startsWith("zellij_")) {
+            // zellij doesn't easily support closing a specific pane by name yet
+          } else {
+            execSync(`tmux kill-pane -t ${member.tmuxPaneId}`);
+          }
         } catch (e) {
           // ignore
         }

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "pi-teams",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": "github:burggraf/pi-teams",
   "author": "Mark Burggraf",
   "license": "MIT",
-  "keywords": ["pi-package"],
+  "keywords": [
+    "pi-package"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
   "main": "extensions/index.ts",
   "files": [
     "extensions",
@@ -23,7 +28,17 @@
   },
   "pi": {
     "image": "https://raw.githubusercontent.com/burggraf/pi-teams/main/pi-team-in-action.png",
-    "extensions": ["extensions/index.ts"],
-    "skills": ["skills"]
+    "extensions": [
+      "extensions/index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }

package/skills/teams.md

@@ -1,27 +1,36 @@
 ---
-description: Coordinate multiple agents working on a project using shared task lists and messaging via tmux or iTerm2.
+description: Coordinate multiple agents working on a project using shared task lists and messaging via tmux or Zellij.
 ---
 
 # Agent Teams
 
-Coordinate multiple agents working on a project using shared task lists and messaging.
+Coordinate multiple agents working on a project using shared task lists and messaging via **tmux** or **Zellij**.
 
 ## Workflow
 
 1.  **Create a team**: Use `team_create(team_name="my-team")`.
 2.  **Spawn teammates**: Use `spawn_teammate` to start additional agents. Give them specific roles and initial prompts.
-3.  **Manage tasks**: Use `task_create` to define work, and `task_update` to assign it to teammates.
+3.  **Manage tasks**: 
+    *   `task_create`: Define work for the team.
+    *   `task_list`: List all tasks to monitor progress or find available work.
+    *   `task_get`: Get full details of a specific task by ID.
+    *   `task_update`: Update a task's status (`pending`, `in_progress`, `completed`, `deleted`) or owner.
 4.  **Communicate**: Use `send_message` to give instructions or receive updates. Teammates should use `read_inbox` to check for messages.
 5.  **Monitor**: Use `check_teammate` to see if they are still running and if they have sent messages back.
+6.  **Cleanup**:
+    *   `force_kill_teammate`: Forcibly stop a teammate and remove them from the team.
+    *   `process_shutdown_approved`: Orderly removal of a teammate after they've finished.
+    *   `team_delete`: Remove a team and all its associated data.
 
 ## Teammate Instructions
 
 When you are spawned as a teammate:
 - Your status bar will show "Teammate: name @ team".
-- Always start by calling `read_inbox` to get your initial instructions.
+- You will automatically start by calling `read_inbox` to get your initial instructions.
 - Regularly check `read_inbox` for updates from the lead.
 - Use `send_message` to "team-lead" to report progress or ask questions.
 - Update your assigned tasks using `task_update`.
+- If you are idle for more than 30 seconds, you will automatically check your inbox for new messages.
 
 ## Best Practices for Teammates
 
@@ -29,3 +38,12 @@ When you are spawned as a teammate:
 - **Frequent Communication**: Send short summaries of your work back to `team-lead` frequently.
 - **Context Matters**: When you finish a task, send a message explaining your results and any new files you created.
 - **Independence**: If you get stuck, try to solve it yourself first, but don't hesitate to ask `team-lead` for clarification.
+- **Orderly Shutdown**: When you've finished all your work and have no more instructions, notify the lead and wait for shutdown approval.
+
+## Best Practices for Team Leads
+
+- **Clear Assignments**: Use `task_create` for all significant work items.
+- **Contextual Prompts**: Provide enough context in `spawn_teammate` for the teammate to understand their specific role.
+- **Task List Monitoring**: Regularly call `task_list` to see the status of all work.
+- **Direct Feedback**: Use `send_message` to provide course corrections or new instructions to teammates.
+- **Read Config**: Use `read_config` to see the full team roster and their current status.

package/src/utils/lock.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { withLock } from "./lock";
+
+describe("withLock", () => {
+  const testDir = path.join(os.tmpdir(), "pi-lock-test-" + Date.now());
+  const lockPath = path.join(testDir, "test");
+  const lockFile = `${lockPath}.lock`;
+
+  beforeEach(() => {
+    if (!fs.existsSync(testDir)) fs.mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("should successfully acquire and release the lock", async () => {
+    const fn = vi.fn().mockResolvedValue("result");
+    const result = await withLock(lockPath, fn);
+
+    expect(result).toBe("result");
+    expect(fn).toHaveBeenCalled();
+    expect(fs.existsSync(lockFile)).toBe(false);
+  });
+
+  it("should fail to acquire lock if already held", async () => {
+    // Manually create lock file
+    fs.writeFileSync(lockFile, "9999");
+
+    const fn = vi.fn().mockResolvedValue("result");
+    
+    // We expect it to fail after timeout (50 * 100ms = 5s)
+    vi.useFakeTimers();
+    
+    const promise = withLock(lockPath, fn);
+    
+    // Fast-forward 6000ms to be safe
+    await vi.advanceTimersByTimeAsync(6000);
+    
+    await expect(promise).rejects.toThrow("Could not acquire lock");
+    expect(fn).not.toHaveBeenCalled();
+    
+    vi.useRealTimers();
+  });
+
+  it("should release lock even if function fails", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("failure"));
+
+    await expect(withLock(lockPath, fn)).rejects.toThrow("failure");
+    expect(fs.existsSync(lockFile)).toBe(false);
+  });
+});

package/src/utils/lock.ts

@@ -3,9 +3,26 @@ import path from "node:path";
 
 export async function withLock<T>(lockPath: string, fn: () => Promise<T>): Promise<T> {
   const lockFile = `${lockPath}.lock`;
+  const LOCK_TIMEOUT = 5000; // 5 seconds of retrying
+  const STALE_LOCK_TIMEOUT = 30000; // 30 seconds for a lock to be considered stale
+  
   let retries = 50;
   while (retries > 0) {
     try {
+      // Check if lock exists and is stale
+      if (fs.existsSync(lockFile)) {
+        const stats = fs.statSync(lockFile);
+        const age = Date.now() - stats.mtimeMs;
+        if (age > STALE_LOCK_TIMEOUT) {
+          // Attempt to remove stale lock
+          try {
+            fs.unlinkSync(lockFile);
+          } catch (e) {
+            // ignore, another process might have already removed it
+          }
+        }
+      }
+      
       fs.writeFileSync(lockFile, process.pid.toString(), { flag: "wx" });
       break;
     } catch (e) {

package/src/utils/messaging.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { appendMessage, readInbox, sendPlainMessage } from "./messaging";
+import * as paths from "./paths";
+
+// Mock the paths to use a temporary directory
+const testDir = path.join(os.tmpdir(), "pi-teams-test-" + Date.now());
+
+describe("Messaging Utilities", () => {
+  beforeEach(() => {
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+    
+    // Override paths to use testDir
+    vi.spyOn(paths, "inboxPath").mockImplementation((teamName, agentName) => {
+      return path.join(testDir, "inboxes", `${agentName}.json`);
+    });
+    vi.spyOn(paths, "teamDir").mockReturnValue(testDir);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("should append a message successfully", async () => {
+    const msg = { from: "sender", text: "hello", timestamp: "now", read: false };
+    await appendMessage("test-team", "receiver", msg);
+    
+    const inbox = await readInbox("test-team", "receiver", false, false);
+    expect(inbox.length).toBe(1);
+    expect(inbox[0].text).toBe("hello");
+  });
+
+  it("should handle concurrent appends (Stress Test)", async () => {
+    const numMessages = 100;
+    const promises = [];
+    for (let i = 0; i < numMessages; i++) {
+      promises.push(sendPlainMessage("test-team", `sender-${i}`, "receiver", `msg-${i}`, `summary-${i}`));
+    }
+    
+    await Promise.all(promises);
+    
+    const inbox = await readInbox("test-team", "receiver", false, false);
+    expect(inbox.length).toBe(numMessages);
+    
+    // Verify all messages are present
+    const texts = inbox.map(m => m.text).sort();
+    for (let i = 0; i < numMessages; i++) {
+      expect(texts).toContain(`msg-${i}`);
+    }
+  });
+
+  it("should mark messages as read", async () => {
+    await sendPlainMessage("test-team", "sender", "receiver", "msg1", "summary1");
+    await sendPlainMessage("test-team", "sender", "receiver", "msg2", "summary2");
+    
+    // Read only unread messages
+    const unread = await readInbox("test-team", "receiver", true, true);
+    expect(unread.length).toBe(2);
+    
+    // Now all should be read
+    const all = await readInbox("test-team", "receiver", false, false);
+    expect(all.length).toBe(2);
+    expect(all.every(m => m.read)).toBe(true);
+  });
+});

package/src/utils/paths.ts

@@ -12,16 +12,24 @@ export function ensureDirs() {
   if (!fs.existsSync(TASKS_DIR)) fs.mkdirSync(TASKS_DIR);
 }
 
+export function sanitizeName(name: string): string {
+  // Allow only alphanumeric characters, hyphens, and underscores.
+  if (/[^a-zA-Z0-9_-]/.test(name)) {
+    throw new Error(`Invalid name: "${name}". Only alphanumeric characters, hyphens, and underscores are allowed.`);
+  }
+  return name;
+}
+
 export function teamDir(teamName: string) {
-  return path.join(TEAMS_DIR, teamName);
+  return path.join(TEAMS_DIR, sanitizeName(teamName));
 }
 
 export function taskDir(teamName: string) {
-  return path.join(TASKS_DIR, teamName);
+  return path.join(TASKS_DIR, sanitizeName(teamName));
 }
 
 export function inboxPath(teamName: string, agentName: string) {
-  return path.join(teamDir(teamName), "inboxes", `${agentName}.json`);
+  return path.join(teamDir(teamName), "inboxes", `${sanitizeName(agentName)}.json`);
 }
 
 export function configPath(teamName: string) {

package/src/utils/security.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { teamDir, inboxPath } from "./paths";
+
+describe("Security Audit - Path Traversal (Prevention Check)", () => {
+  it("should throw an error for path traversal via teamName", () => {
+    const maliciousTeamName = "../../etc";
+    expect(() => teamDir(maliciousTeamName)).toThrow();
+  });
+
+  it("should throw an error for path traversal via agentName", () => {
+    const teamName = "audit-team";
+    const maliciousAgentName = "../../../.ssh/id_rsa";
+    expect(() => inboxPath(teamName, maliciousAgentName)).toThrow();
+  });
+
+  it("should throw an error for path traversal via taskId", () => {
+    const teamName = "audit-team";
+    const maliciousTaskId = "../../../etc/passwd";
+    // We need to import readTask/updateTask or just sanitizeName directly if we want to test the logic
+    // But since we already tested sanitizeName via other paths, this is just for completeness.
+    expect(() => sanitizeName(maliciousTaskId)).toThrow();
+  });
+});
+
+describe("Security Audit - Command Injection (Drafting)", () => {
+  it("should be vulnerable to command injection in spawn_teammate (via parameters)", () => {
+    const maliciousCwd = "; rm -rf / ;";
+    const name = "attacker";
+    const team_name = "audit-team";
+    const piBinary = "pi";
+    const cmd = `PI_TEAM_NAME=${team_name} PI_AGENT_NAME=${name} ${piBinary}`;
+    
+    // Simulating what happens in spawn_teammate (extensions/index.ts)
+    const tmuxCmd = `tmux split-window -h -dP -F "#{pane_id}" "cd ${maliciousCwd} && ${cmd}"`;
+    
+    // The command becomes: tmux split-window -h -dP -F "#{pane_id}" "cd ; rm -rf / ; && PI_TEAM_NAME=audit-team PI_AGENT_NAME=attacker pi"
+    expect(tmuxCmd).toContain("cd ; rm -rf / ; &&");
+  });
+});

package/src/utils/tasks.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createTask, updateTask, readTask, listTasks } from "./tasks";
+import * as paths from "./paths";
+import * as teams from "./teams";
+
+// Mock the paths to use a temporary directory
+const testDir = path.join(os.tmpdir(), "pi-teams-test-" + Date.now());
+
+describe("Tasks Utilities", () => {
+  beforeEach(() => {
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+    
+    // Override paths to use testDir
+    vi.spyOn(paths, "taskDir").mockReturnValue(testDir);
+    vi.spyOn(paths, "configPath").mockReturnValue(path.join(testDir, "config.json"));
+    
+    // Create a dummy team config
+    fs.writeFileSync(path.join(testDir, "config.json"), JSON.stringify({ name: "test-team" }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("should create a task successfully", async () => {
+    const task = await createTask("test-team", "Test Subject", "Test Description");
+    expect(task.id).toBe("1");
+    expect(task.subject).toBe("Test Subject");
+    expect(fs.existsSync(path.join(testDir, "1.json"))).toBe(true);
+  });
+
+  it("should update a task successfully", async () => {
+    await createTask("test-team", "Test Subject", "Test Description");
+    const updated = await updateTask("test-team", "1", { status: "in_progress" });
+    expect(updated.status).toBe("in_progress");
+    
+    const taskData = JSON.parse(fs.readFileSync(path.join(testDir, "1.json"), "utf-8"));
+    expect(taskData.status).toBe("in_progress");
+  });
+
+  it("should list tasks", async () => {
+    await createTask("test-team", "Task 1", "Desc 1");
+    await createTask("test-team", "Task 2", "Desc 2");
+    const tasksList = await listTasks("test-team");
+    expect(tasksList.length).toBe(2);
+    expect(tasksList[0].id).toBe("1");
+    expect(tasksList[1].id).toBe("2");
+  });
+
+  it("should have consistent lock paths (Fixed BUG 2)", async () => {
+    // This test verifies that both updateTask and readTask now use the same lock path
+    // Both should now lock `${taskId}.json.lock`
+    
+    await createTask("test-team", "Bug Test", "Testing lock consistency");
+    const taskId = "1";
+    
+    const taskFile = path.join(testDir, `${taskId}.json`);
+    const commonLockFile = `${taskFile}.lock`;
+    
+    // 1. Holding the common lock
+    fs.writeFileSync(commonLockFile, "9999");
+    
+    // 2. Try updateTask, it should fail
+    vi.useFakeTimers();
+    const updatePromise = updateTask("test-team", taskId, { status: "in_progress" });
+    await vi.advanceTimersByTimeAsync(6000);
+    await expect(updatePromise).rejects.toThrow("Could not acquire lock");
+    vi.useRealTimers();
+
+    // 3. Try readTask, it should fail too
+    vi.useFakeTimers();
+    const readPromise = readTask("test-team", taskId);
+    await vi.advanceTimersByTimeAsync(6000);
+    await expect(readPromise).rejects.toThrow("Could not acquire lock");
+    vi.useRealTimers();
+    
+    fs.unlinkSync(commonLockFile);
+  });
+});

package/src/utils/tasks.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { TaskFile } from "./models";
-import { taskDir } from "./paths";
+import { taskDir, sanitizeName } from "./paths";
 import { teamExists } from "./teams";
 import { withLock } from "./lock";
 
@@ -48,10 +48,10 @@ export async function updateTask(
   updates: Partial<TaskFile>
 ): Promise<TaskFile> {
   const dir = taskDir(teamName);
-  const lockPath = path.join(dir, taskId);
-  const p = path.join(dir, `${taskId}.json`);
+  const safeTaskId = sanitizeName(taskId);
+  const p = path.join(dir, `${safeTaskId}.json`);
 
-  return await withLock(lockPath, async () => {
+  return await withLock(p, async () => {
     if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
     const task: TaskFile = JSON.parse(fs.readFileSync(p, "utf-8"));
     const updated = { ...task, ...updates };
@@ -68,7 +68,8 @@ export async function updateTask(
 
 export async function readTask(teamName: string, taskId: string): Promise<TaskFile> {
   const dir = taskDir(teamName);
-  const p = path.join(dir, `${taskId}.json`);
+  const safeTaskId = sanitizeName(taskId);
+  const p = path.join(dir, `${safeTaskId}.json`);
   if (!fs.existsSync(p)) throw new Error(`Task ${taskId} not found`);
   return await withLock(p, async () => {
     return JSON.parse(fs.readFileSync(p, "utf-8"));