@hdwebsoft/hdcode-agent-team 0.1.2 → 0.2.0

package/dist/index.js

@@ -3,13 +3,14 @@ import { readdir as readdir2 } from "node:fs/promises";
 import { join as join3 } from "node:path";
 
 // src/utils.ts
-import { readdir, mkdir, rename, unlink, stat } from "node:fs/promises";
+import { readdir, mkdir, rename, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 var TEAM_ROOT = ".team";
 var SAFE_NAME = /^[a-z0-9-]+$/;
-var LOCK_TIMEOUT_MS = 1e4;
-var LOCK_RETRY_MS = 50;
-var LOCK_MAX_RETRIES = 100;
+var LOCK_STALE_MS = 30000;
+var LOCK_RETRY_MIN_MS = 25;
+var LOCK_RETRY_MAX_MS = 100;
+var LOCK_ACQUIRE_TIMEOUT_MS = 1e4;
 function validateName(name, label) {
   if (!SAFE_NAME.test(name)) {
     throw new Error(`Invalid ${label}: "${name}" (must be lowercase alphanumeric + hyphens)`);
@@ -28,7 +29,7 @@ async function exists(path) {
   }
 }
 async function writeJsonAtomic(path, data) {
-  const tmp = path + ".tmp";
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
   await Bun.write(tmp, JSON.stringify(data, null, 2));
   await rename(tmp, path);
 }
@@ -48,32 +49,43 @@ async function listJsonFiles(dir) {
 async function ensureDir(path) {
   await mkdir(path, { recursive: true });
 }
-async function withLock(lockPath, fn) {
-  let acquired = false;
-  for (let i = 0;i < LOCK_MAX_RETRIES; i++) {
-    if (await exists(lockPath)) {
-      const content = await Bun.file(lockPath).text().catch(() => "0");
-      const lockTime = parseInt(content, 10) || 0;
-      if (Date.now() - lockTime > LOCK_TIMEOUT_MS) {
-        await Bun.write(lockPath, Date.now().toString());
-        acquired = true;
-        break;
+function jitter(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+async function isLockStale(lockDir, staleMs) {
+  try {
+    const s = await stat(lockDir);
+    return Date.now() - s.mtimeMs > staleMs;
+  } catch {
+    return true;
+  }
+}
+async function withTeamLock(base, teamName, fn) {
+  const locksRoot = join(base, TEAM_ROOT, ".locks");
+  const lockDir = join(locksRoot, `${teamName}.lock`);
+  await mkdir(locksRoot, { recursive: true });
+  const startedAt = Date.now();
+  while (true) {
+    try {
+      await mkdir(lockDir);
+      try {
+        return await fn();
+      } finally {
+        await rm(lockDir, { recursive: true, force: true }).catch(() => {});
+      }
+    } catch (err) {
+      if (err?.code !== "EEXIST")
+        throw err;
+      if (await isLockStale(lockDir, LOCK_STALE_MS)) {
+        await rm(lockDir, { recursive: true, force: true }).catch(() => {});
+        continue;
       }
-      await Bun.sleep(LOCK_RETRY_MS);
-    } else {
-      await Bun.write(lockPath, Date.now().toString());
-      acquired = true;
-      break;
+      if (Date.now() - startedAt > LOCK_ACQUIRE_TIMEOUT_MS) {
+        throw new Error(`Timed out acquiring team lock for "${teamName}"`);
+      }
+      await Bun.sleep(jitter(LOCK_RETRY_MIN_MS, LOCK_RETRY_MAX_MS));
     }
   }
-  if (!acquired) {
-    throw new Error(`Failed to acquire lock: ${lockPath} (timed out after ${LOCK_MAX_RETRIES * LOCK_RETRY_MS}ms)`);
-  }
-  try {
-    return await fn();
-  } finally {
-    await unlink(lockPath).catch(() => {});
-  }
 }
 
 // src/tasks.ts
@@ -117,6 +129,37 @@ function hasCycle(taskId, blockedBy, allTasks) {
   }
   return false;
 }
+function hasCycleViaBlocks(taskId, blockTargets, blockedBySources, allTasks) {
+  const upstream = new Set;
+  const queue = [...blockedBySources];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (upstream.has(current))
+      continue;
+    upstream.add(current);
+    const task = allTasks.get(current);
+    if (task)
+      queue.push(...task.blockedBy);
+  }
+  for (const targetId of blockTargets) {
+    if (upstream.has(targetId))
+      return true;
+    const targetQueue = [targetId];
+    const visited = new Set;
+    while (targetQueue.length > 0) {
+      const cur = targetQueue.shift();
+      if (visited.has(cur))
+        continue;
+      visited.add(cur);
+      if (upstream.has(cur))
+        return true;
+      const t = allTasks.get(cur);
+      if (t)
+        targetQueue.push(...t.blockedBy);
+    }
+  }
+  return false;
+}
 async function unblockDependents(base, teamName, completedTaskId) {
   const unblocked = [];
   const allTasks = await loadAllTasks(base, teamName);
@@ -164,7 +207,7 @@ async function getActiveTeamsSummary(base) {
 }
 
 // src/tools/team-tools.ts
-import { readdir as readdir3, rm } from "node:fs/promises";
+import { readdir as readdir3, rm as rm2 } from "node:fs/promises";
 import { join as join4 } from "node:path";
 import { tool } from "@opencode-ai/plugin";
 
@@ -232,7 +275,7 @@ function createTeamTools(directory) {
         if (!await exists(join4(dir, "config.json"))) {
           return `Error: Team "${args.teamName}" not found`;
         }
-        await rm(dir, { recursive: true, force: true });
+        await rm2(dir, { recursive: true, force: true });
         return `Team "${args.teamName}" deleted successfully`;
       }
     }),
@@ -311,8 +354,244 @@ function createTeamTools(directory) {
 }
 
 // src/tools/task-tools.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
+import { unlink as unlink2 } from "node:fs/promises";
 import { tool as tool2 } from "@opencode-ai/plugin";
+
+// src/reservations.ts
+import { join as join5 } from "node:path";
+import { randomUUID } from "node:crypto";
+var DEFAULT_TTL_SECONDS = 1800;
+var MAX_TTL_SECONDS = 14400;
+function reservationStorePath(base, teamName) {
+  return join5(teamDir(base, teamName), "reservations.json");
+}
+function emptyStore() {
+  return { version: 1, updatedAt: new Date().toISOString(), reservations: [] };
+}
+async function loadStore(base, teamName) {
+  const path = reservationStorePath(base, teamName);
+  if (!await exists(path))
+    return emptyStore();
+  try {
+    return await readJson(path);
+  } catch {
+    return emptyStore();
+  }
+}
+async function saveStore(base, teamName, store) {
+  store.updatedAt = new Date().toISOString();
+  await writeJsonAtomic(reservationStorePath(base, teamName), store);
+}
+function normalizeRepoPath(input) {
+  let p = input.replace(/\\/g, "/");
+  if (p.startsWith("./"))
+    p = p.slice(2);
+  if (p.startsWith("/"))
+    throw new Error(`Absolute paths not allowed: ${input}`);
+  if (p.includes(".."))
+    throw new Error(`Path traversal not allowed: ${input}`);
+  return p;
+}
+function globToPrefix(glob) {
+  const normalized = glob.replace(/\\/g, "/");
+  if (!normalized.endsWith("/**")) {
+    throw new Error(`Only dir/** globs are supported, got: "${glob}"`);
+  }
+  const prefix = normalized.slice(0, -3);
+  if (!prefix || prefix.includes("*")) {
+    throw new Error(`Invalid glob pattern: "${glob}"`);
+  }
+  return normalizeRepoPath(prefix);
+}
+function isPathInsidePrefix(path, prefix) {
+  return path === prefix || path.startsWith(prefix + "/");
+}
+function pruneExpired(store, now = Date.now()) {
+  const before = store.reservations.length;
+  store.reservations = store.reservations.filter((r) => new Date(r.expiresAt).getTime() > now);
+  return store.reservations.length !== before;
+}
+function findConflicts(req, active) {
+  const conflicts = [];
+  for (const r of active) {
+    if (r.agentId === req.agentId)
+      continue;
+    for (const f of req.files) {
+      if (r.files.includes(f)) {
+        conflicts.push({
+          reservationId: r.id,
+          agentId: r.agentId,
+          taskId: r.taskId,
+          reason: r.reason,
+          matchedFile: f,
+          expiresAt: r.expiresAt
+        });
+      }
+      for (const p of r.prefixes) {
+        if (isPathInsidePrefix(f, p)) {
+          conflicts.push({
+            reservationId: r.id,
+            agentId: r.agentId,
+            taskId: r.taskId,
+            reason: r.reason,
+            matchedPrefix: p,
+            expiresAt: r.expiresAt
+          });
+        }
+      }
+    }
+    for (const newP of req.prefixes) {
+      for (const existFile of r.files) {
+        if (isPathInsidePrefix(existFile, newP)) {
+          conflicts.push({
+            reservationId: r.id,
+            agentId: r.agentId,
+            taskId: r.taskId,
+            reason: r.reason,
+            matchedFile: existFile,
+            expiresAt: r.expiresAt
+          });
+        }
+      }
+      for (const existP of r.prefixes) {
+        if (isPathInsidePrefix(newP, existP) || isPathInsidePrefix(existP, newP)) {
+          conflicts.push({
+            reservationId: r.id,
+            agentId: r.agentId,
+            taskId: r.taskId,
+            reason: r.reason,
+            matchedPrefix: existP,
+            expiresAt: r.expiresAt
+          });
+        }
+      }
+    }
+  }
+  return conflicts;
+}
+async function reserveFiles(base, teamName, opts) {
+  const normalizedFiles = (opts.files || []).map(normalizeRepoPath);
+  const prefixes = (opts.globs || []).map(globToPrefix);
+  if (normalizedFiles.length === 0 && prefixes.length === 0) {
+    return { ok: true };
+  }
+  const ttl = Math.min(opts.ttlSeconds || DEFAULT_TTL_SECONDS, MAX_TTL_SECONDS);
+  const store = await loadStore(base, teamName);
+  pruneExpired(store);
+  const conflicts = findConflicts({ files: normalizedFiles, prefixes, agentId: opts.agentId }, store.reservations);
+  if (conflicts.length > 0) {
+    return { ok: false, conflicts };
+  }
+  const existingIdx = opts.taskId ? store.reservations.findIndex((r) => r.agentId === opts.agentId && r.taskId === opts.taskId) : -1;
+  const now = new Date;
+  const expiresAt = new Date(now.getTime() + ttl * 1000).toISOString();
+  if (existingIdx >= 0) {
+    const existing = store.reservations[existingIdx];
+    for (const f of normalizedFiles) {
+      if (!existing.files.includes(f))
+        existing.files.push(f);
+    }
+    for (const p of prefixes) {
+      if (!existing.prefixes.includes(p))
+        existing.prefixes.push(p);
+    }
+    existing.expiresAt = expiresAt;
+    await saveStore(base, teamName, store);
+    return { ok: true, reservationId: existing.id, expiresAt };
+  }
+  const reservation = {
+    id: `resv_${randomUUID().slice(0, 8)}`,
+    agentId: opts.agentId,
+    ...opts.taskId && { taskId: opts.taskId },
+    ...opts.reason && { reason: opts.reason },
+    files: normalizedFiles,
+    prefixes,
+    createdAt: now.toISOString(),
+    expiresAt
+  };
+  store.reservations.push(reservation);
+  await saveStore(base, teamName, store);
+  return { ok: true, reservationId: reservation.id, expiresAt };
+}
+async function releaseByTask(base, teamName, agentId, taskId) {
+  const store = await loadStore(base, teamName);
+  const released = [];
+  store.reservations = store.reservations.filter((r) => {
+    if (r.agentId === agentId && r.taskId === taskId) {
+      released.push(r.id);
+      return false;
+    }
+    return true;
+  });
+  if (released.length > 0) {
+    await saveStore(base, teamName, store);
+  }
+  return released;
+}
+async function releaseByAgent(base, teamName, agentId) {
+  const store = await loadStore(base, teamName);
+  const released = [];
+  store.reservations = store.reservations.filter((r) => {
+    if (r.agentId === agentId) {
+      released.push(r.id);
+      return false;
+    }
+    return true;
+  });
+  if (released.length > 0) {
+    await saveStore(base, teamName, store);
+  }
+  return released;
+}
+async function releaseById(base, teamName, agentId, reservationId) {
+  const store = await loadStore(base, teamName);
+  const idx = store.reservations.findIndex((r) => r.id === reservationId && r.agentId === agentId);
+  if (idx < 0)
+    return false;
+  store.reservations.splice(idx, 1);
+  await saveStore(base, teamName, store);
+  return true;
+}
+async function checkFile(base, teamName, path, agentId) {
+  const normalized = normalizeRepoPath(path);
+  const store = await loadStore(base, teamName);
+  pruneExpired(store);
+  const holders = [];
+  for (const r of store.reservations) {
+    if (r.files.includes(normalized)) {
+      holders.push({
+        reservationId: r.id,
+        agentId: r.agentId,
+        taskId: r.taskId,
+        reason: r.reason,
+        expiresAt: r.expiresAt,
+        matchedBy: "file",
+        value: normalized
+      });
+      continue;
+    }
+    for (const p of r.prefixes) {
+      if (isPathInsidePrefix(normalized, p)) {
+        holders.push({
+          reservationId: r.id,
+          agentId: r.agentId,
+          taskId: r.taskId,
+          reason: r.reason,
+          expiresAt: r.expiresAt,
+          matchedBy: "prefix",
+          value: p
+        });
+        break;
+      }
+    }
+  }
+  const reserved = holders.length > 0;
+  const canEdit = !reserved || !!agentId && holders.every((h) => h.agentId === agentId);
+  return { reserved, canEdit, holders };
+}
+
+// src/tools/task-tools.ts
 function parseStringArray(raw, label) {
   if (!raw.trimStart().startsWith("[")) {
     return raw.split(",").map((s) => s.trim()).filter(Boolean);
@@ -339,17 +618,16 @@ function createTaskTools(directory) {
         activeForm: tool2.schema.string().optional().describe("Spinner text when in_progress"),
         addBlocks: tool2.schema.string().optional().describe('JSON array of task IDs this task blocks, e.g. ["3","4"]'),
         addBlockedBy: tool2.schema.string().optional().describe('JSON array of task IDs that block this task, e.g. ["1"]'),
-        metadata: tool2.schema.string().optional().describe("JSON object of arbitrary metadata")
+        metadata: tool2.schema.string().optional().describe('JSON object of arbitrary metadata (use fileScope key for file reservation: {"fileScope": {"files": [...], "globs": [...]}})')
       },
       async execute(args) {
         const dir = teamDir(directory, args.teamName);
-        if (!await exists(join5(dir, "config.json"))) {
+        if (!await exists(join6(dir, "config.json"))) {
           return `Error: Team "${args.teamName}" not found`;
         }
-        const tasksDir = join5(dir, "tasks");
+        const tasksDir = join6(dir, "tasks");
         await ensureDir(tasksDir);
-        const tasksLockPath = join5(tasksDir, ".lock");
-        return withLock(tasksLockPath, async () => {
+        return withTeamLock(directory, args.teamName, async () => {
           let addBlocks = [];
           let addBlockedBy = [];
           let metadata;
@@ -386,6 +664,9 @@ function createTaskTools(directory) {
           if (addBlockedBy.length > 0 && hasCycle(id, addBlockedBy, taskMap)) {
             return `Error: Circular dependency detected for task ${id}`;
           }
+          if (addBlocks.length > 0 && hasCycleViaBlocks(id, addBlocks, addBlockedBy, taskMap)) {
+            return `Error: Circular dependency detected for task ${id}`;
+          }
           const task = {
             id,
             subject: args.subject,
@@ -396,7 +677,7 @@ function createTaskTools(directory) {
             blockedBy: addBlockedBy,
             ...metadata && { metadata }
           };
-          await writeJsonAtomic(join5(tasksDir, `${id}.json`), task);
+          await writeJsonAtomic(join6(tasksDir, `${id}.json`), task);
           for (const targetId of addBlockedBy) {
             const targetPath = taskFilePath(directory, args.teamName, targetId);
             const target = await readJson(targetPath);
@@ -418,7 +699,7 @@ function createTaskTools(directory) {
       }
     }),
     task_update: tool2({
-      description: "Update task fields, manage dependencies, auto-unblock. Status transitions: pending→in_progress, in_progress→completed. On completion: auto-unblocks dependents. Returns {task, unblocked[]}.",
+      description: "Update task fields, manage dependencies, auto-unblock. Status transitions: pending→in_progress, in_progress→completed. On in_progress with fileScope metadata: auto-reserves files. On completed: auto-releases. Returns {task, unblocked[]}.",
       args: {
         teamName: tool2.schema.string().describe("Team name"),
         taskId: tool2.schema.string().describe("Task ID (integer string)"),
@@ -433,12 +714,10 @@ function createTaskTools(directory) {
       },
       async execute(args) {
         const dir = teamDir(directory, args.teamName);
-        if (!await exists(join5(dir, "config.json"))) {
+        if (!await exists(join6(dir, "config.json"))) {
           return `Error: Team "${args.teamName}" not found`;
         }
-        const tasksDir = join5(dir, "tasks");
-        const tasksLockPath = join5(tasksDir, ".lock");
-        return withLock(tasksLockPath, async () => {
+        return withTeamLock(directory, args.teamName, async () => {
           const tPath = taskFilePath(directory, args.teamName, args.taskId);
           if (!await exists(tPath)) {
             return `Error: Task "${args.taskId}" not found in team "${args.teamName}"`;
@@ -469,6 +748,27 @@ function createTaskTools(directory) {
                 return `Error: Cannot start task with unresolved blockers: ${activeBlockers.join(", ")}`;
               }
             }
+            if (args.status === "in_progress") {
+              const fileScope = task.metadata?.fileScope;
+              if (fileScope) {
+                const agentId = args.owner || task.owner || "unknown";
+                const reserveResult = await reserveFiles(directory, args.teamName, {
+                  agentId,
+                  taskId: task.id,
+                  files: fileScope.files,
+                  globs: fileScope.globs
+                });
+                if (!reserveResult.ok) {
+                  return `Error: Cannot start task — file reservation conflict: ${JSON.stringify(reserveResult.conflicts)}`;
+                }
+              }
+            }
+            if (args.status === "completed") {
+              const agentId = args.owner || task.owner;
+              if (agentId) {
+                await releaseByTask(directory, args.teamName, agentId, task.id);
+              }
+            }
             task.status = args.status;
           }
           if (args.subject !== undefined)
@@ -492,6 +792,11 @@ function createTaskTools(directory) {
             const result = parseStringArray(args.addBlocks, "addBlocks");
             if (typeof result === "string")
               return result;
+            const allTasks = await loadAllTasks(directory, args.teamName);
+            const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+            if (hasCycleViaBlocks(task.id, result, task.blockedBy, taskMap)) {
+              return `Error: Circular dependency detected — cannot add blocks`;
+            }
             for (const targetId of result) {
               if (!task.blocks.includes(targetId)) {
                 task.blocks.push(targetId);
@@ -510,6 +815,11 @@ function createTaskTools(directory) {
             const result = parseStringArray(args.addBlockedBy, "addBlockedBy");
             if (typeof result === "string")
               return result;
+            const allTasks = await loadAllTasks(directory, args.teamName);
+            const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+            if (hasCycle(task.id, result, taskMap)) {
+              return `Error: Circular dependency detected — cannot add blockedBy`;
+            }
             for (const targetId of result) {
               if (!task.blockedBy.includes(targetId)) {
                 task.blockedBy.push(targetId);
@@ -533,6 +843,47 @@ function createTaskTools(directory) {
         });
       }
     }),
+    task_delete: tool2({
+      description: "Delete a task and clean up all bidirectional dependency links. Removes this task from blocks[] and blockedBy[] of all related tasks. Auto-releases file reservations.",
+      args: {
+        teamName: tool2.schema.string().describe("Team name"),
+        taskId: tool2.schema.string().describe("Task ID to delete")
+      },
+      async execute(args) {
+        const dir = teamDir(directory, args.teamName);
+        if (!await exists(join6(dir, "config.json"))) {
+          return `Error: Team "${args.teamName}" not found`;
+        }
+        return withTeamLock(directory, args.teamName, async () => {
+          const tPath = taskFilePath(directory, args.teamName, args.taskId);
+          if (!await exists(tPath)) {
+            return `Error: Task "${args.taskId}" not found in team "${args.teamName}"`;
+          }
+          const task = await readJson(tPath);
+          if (task.owner) {
+            await releaseByTask(directory, args.teamName, task.owner, task.id);
+          }
+          for (const blockerId of task.blockedBy) {
+            const blockerPath = taskFilePath(directory, args.teamName, blockerId);
+            if (await exists(blockerPath)) {
+              const blocker = await readJson(blockerPath);
+              blocker.blocks = blocker.blocks.filter((id) => id !== args.taskId);
+              await writeJsonAtomic(blockerPath, blocker);
+            }
+          }
+          for (const blockedId of task.blocks) {
+            const blockedPath = taskFilePath(directory, args.teamName, blockedId);
+            if (await exists(blockedPath)) {
+              const blocked = await readJson(blockedPath);
+              blocked.blockedBy = blocked.blockedBy.filter((id) => id !== args.taskId);
+              await writeJsonAtomic(blockedPath, blocked);
+            }
+          }
+          await unlink2(tPath);
+          return `Task "${args.taskId}" deleted and all dependency links cleaned up`;
+        });
+      }
+    }),
     task_get: tool2({
       description: "Get a single task by ID.",
       args: {
@@ -554,7 +905,7 @@ function createTaskTools(directory) {
       },
       async execute(args) {
         const dir = teamDir(directory, args.teamName);
-        if (!await exists(join5(dir, "config.json"))) {
+        if (!await exists(join6(dir, "config.json"))) {
           return `Error: Team "${args.teamName}" not found`;
         }
         const tasks = await loadAllTasks(directory, args.teamName);
@@ -566,7 +917,7 @@ function createTaskTools(directory) {
 }
 
 // src/tools/message-tools.ts
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { tool as tool3 } from "@opencode-ai/plugin";
 function createMessageTools(directory) {
   return {
@@ -588,14 +939,13 @@ function createMessageTools(directory) {
       },
       async execute(args) {
         const dir = teamDir(directory, args.teamName);
-        const configPath = join6(dir, "config.json");
+        const configPath = join7(dir, "config.json");
         if (!await exists(configPath)) {
           return `Error: Team "${args.teamName}" not found`;
         }
         const sender = args.from || "team-lead";
-        const inboxesDir = join6(dir, "inboxes");
+        const inboxesDir = join7(dir, "inboxes");
         await ensureDir(inboxesDir);
-        const inboxesLockPath = join6(inboxesDir, ".lock");
         const message = {
           from: sender,
           text: args.content,
@@ -606,11 +956,11 @@ function createMessageTools(directory) {
         const config = await readJson(configPath);
         if (args.type === "broadcast") {
           const recipients = [];
-          return withLock(inboxesLockPath, async () => {
+          return withTeamLock(directory, args.teamName, async () => {
             for (const member of config.members) {
               if (member.name === sender)
                 continue;
-              const inboxPath = join6(inboxesDir, `${member.name}.json`);
+              const inboxPath = join7(inboxesDir, `${member.name}.json`);
               await appendToInbox(inboxPath, message);
               recipients.push(member.name);
             }
@@ -625,8 +975,8 @@ function createMessageTools(directory) {
           if (!member) {
             return `Error: Recipient "${args.recipient}" not found in team "${args.teamName}"`;
           }
-          return withLock(inboxesLockPath, async () => {
-            const inboxPath = join6(inboxesDir, `${member.name}.json`);
+          return withTeamLock(directory, args.teamName, async () => {
+            const inboxPath = join7(inboxesDir, `${member.name}.json`);
             await appendToInbox(inboxPath, message);
             return JSON.stringify({ sent: true, recipients: [member.name] }, null, 2);
           });
@@ -643,34 +993,150 @@ function createMessageTools(directory) {
       },
       async execute(args) {
         const dir = teamDir(directory, args.teamName);
-        if (!await exists(join6(dir, "config.json"))) {
+        if (!await exists(join7(dir, "config.json"))) {
           return `Error: Team "${args.teamName}" not found`;
         }
         const agentName = args.agent.includes("@") ? args.agent.split("@")[0] : args.agent;
-        const inboxPath = join6(dir, "inboxes", `${agentName}.json`);
+        const inboxPath = join7(dir, "inboxes", `${agentName}.json`);
+        if (args.markRead) {
+          return withTeamLock(directory, args.teamName, async () => {
+            const allMessages = await readInbox(inboxPath);
+            const sinceDate = args.since ? new Date(args.since) : null;
+            let changed = false;
+            for (const m of allMessages) {
+              if (sinceDate && new Date(m.timestamp) <= sinceDate)
+                continue;
+              if (!m.read) {
+                m.read = true;
+                changed = true;
+              }
+            }
+            if (changed) {
+              await writeJsonAtomic(inboxPath, allMessages);
+            }
+            let filtered = allMessages;
+            if (sinceDate) {
+              filtered = allMessages.filter((m) => new Date(m.timestamp) > sinceDate);
+            }
+            filtered.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+            return filtered.length > 0 ? JSON.stringify(filtered, null, 2) : "No messages found";
+          });
+        }
         let messages = await readInbox(inboxPath);
         if (args.since) {
           const sinceDate = new Date(args.since);
           messages = messages.filter((m) => new Date(m.timestamp) > sinceDate);
         }
-        if (args.markRead && messages.length > 0) {
-          const allMessages = await readInbox(inboxPath);
-          const sinceDate = args.since ? new Date(args.since) : null;
-          let changed = false;
-          for (const m of allMessages) {
-            if (sinceDate && new Date(m.timestamp) <= sinceDate)
-              continue;
-            if (!m.read) {
-              m.read = true;
-              changed = true;
-            }
+        messages.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        return messages.length > 0 ? JSON.stringify(messages, null, 2) : "No messages found";
+      }
+    })
+  };
+}
+
+// src/tools/reservation-tools.ts
+import { join as join8 } from "node:path";
+import { tool as tool4 } from "@opencode-ai/plugin";
+function createReservationTools(directory) {
+  return {
+    file_reserve: tool4({
+      description: "Reserve file paths or directory globs (dir/**) before editing code. Prevents other agents from editing the same files. Returns reservation ID or conflict details. Reservations auto-expire after TTL.",
+      args: {
+        teamName: tool4.schema.string().describe("Team name"),
+        agentId: tool4.schema.string().describe("Agent name reserving the files"),
+        taskId: tool4.schema.string().optional().describe("Task ID (for auto-release on task completion)"),
+        reason: tool4.schema.string().optional().describe("Why these files are being reserved"),
+        files: tool4.schema.string().optional().describe('JSON array of exact file paths, e.g. ["src/auth.ts","src/api/users.ts"]'),
+        globs: tool4.schema.string().optional().describe('JSON array of dir/** globs, e.g. ["src/api/**","src/lib/**"]'),
+        ttlSeconds: tool4.schema.number().optional().describe("TTL in seconds (default 1800, max 14400)")
+      },
+      async execute(args) {
+        const dir = teamDir(directory, args.teamName);
+        if (!await exists(join8(dir, "config.json"))) {
+          return `Error: Team "${args.teamName}" not found`;
+        }
+        let files;
+        let globs;
+        if (args.files) {
+          try {
+            files = JSON.parse(args.files);
+            if (!Array.isArray(files))
+              return "Error: files must be a JSON array";
+          } catch {
+            return "Error: Invalid files JSON";
           }
-          if (changed) {
-            await writeJsonAtomic(inboxPath, allMessages);
+        }
+        if (args.globs) {
+          try {
+            globs = JSON.parse(args.globs);
+            if (!Array.isArray(globs))
+              return "Error: globs must be a JSON array";
+          } catch {
+            return "Error: Invalid globs JSON";
           }
         }
-        messages.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-        return messages.length > 0 ? JSON.stringify(messages, null, 2) : "No messages found";
+        return withTeamLock(directory, args.teamName, async () => {
+          try {
+            const result = await reserveFiles(directory, args.teamName, {
+              agentId: args.agentId,
+              taskId: args.taskId,
+              reason: args.reason,
+              files,
+              globs,
+              ttlSeconds: args.ttlSeconds
+            });
+            return JSON.stringify(result, null, 2);
+          } catch (err) {
+            return `Error: ${err.message}`;
+          }
+        });
+      }
+    }),
+    file_release: tool4({
+      description: "Release file reservations. Can release by reservation ID, by task ID, or release all reservations for an agent.",
+      args: {
+        teamName: tool4.schema.string().describe("Team name"),
+        agentId: tool4.schema.string().describe("Agent name releasing the reservation"),
+        reservationId: tool4.schema.string().optional().describe("Specific reservation ID to release"),
+        taskId: tool4.schema.string().optional().describe("Release all reservations for this task")
+      },
+      async execute(args) {
+        const dir = teamDir(directory, args.teamName);
+        if (!await exists(join8(dir, "config.json"))) {
+          return `Error: Team "${args.teamName}" not found`;
+        }
+        return withTeamLock(directory, args.teamName, async () => {
+          if (args.reservationId) {
+            const ok = await releaseById(directory, args.teamName, args.agentId, args.reservationId);
+            return ok ? JSON.stringify({ ok: true, releasedReservationIds: [args.reservationId] }, null, 2) : `Error: Reservation "${args.reservationId}" not found or not owned by "${args.agentId}"`;
+          }
+          if (args.taskId) {
+            const released2 = await releaseByTask(directory, args.teamName, args.agentId, args.taskId);
+            return JSON.stringify({ ok: true, releasedReservationIds: released2 }, null, 2);
+          }
+          const released = await releaseByAgent(directory, args.teamName, args.agentId);
+          return JSON.stringify({ ok: true, releasedReservationIds: released }, null, 2);
+        });
+      }
+    }),
+    file_check: tool4({
+      description: "Check if a file is reserved by another agent before editing. Returns reservation status and whether the caller can edit. Lock-free read — safe to call frequently.",
+      args: {
+        teamName: tool4.schema.string().describe("Team name"),
+        path: tool4.schema.string().describe("File path to check (repo-relative, e.g. src/auth.ts)"),
+        agentId: tool4.schema.string().optional().describe("Caller's agent name (to determine canEdit)")
+      },
+      async execute(args) {
+        const dir = teamDir(directory, args.teamName);
+        if (!await exists(join8(dir, "config.json"))) {
+          return `Error: Team "${args.teamName}" not found`;
+        }
+        try {
+          const result = await checkFile(directory, args.teamName, args.path, args.agentId);
+          return JSON.stringify(result, null, 2);
+        } catch (err) {
+          return `Error: ${err.message}`;
+        }
       }
     })
   };
@@ -696,7 +1162,8 @@ Use team_status(teamName) to get full details. Continue any in-progress tasks.
     tool: {
       ...createTeamTools(directory),
       ...createTaskTools(directory),
-      ...createMessageTools(directory)
+      ...createMessageTools(directory),
+      ...createReservationTools(directory)
     }
   };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hdwebsoft/hdcode-agent-team",
-  "version": "0.1.2",
-  "description": "OpenCode plugin for multi-agent team coordination — per-agent inboxes, task management with dependency tracking, and file locking.",
+  "version": "0.2.0",
+  "description": "OpenCode plugin for multi-agent team coordination — per-agent inboxes, task management with dependency tracking, file reservation/locking, and atomic mkdir-based concurrency control.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -29,7 +29,9 @@
     "multi-agent",
     "task-management",
     "inbox",
-    "coordination"
+    "coordination",
+    "file-reservation",
+    "concurrency"
   ],
   "author": "HDWebSoft",
   "license": "MIT",