@wrongstack/core 0.282.1 → 0.283.0

package/dist/coordination/index.js

@@ -4974,6 +4974,16 @@ function getKanbanPath(projectRoot, boardId) {
   }
   return resolved;
 }
+function getKanbanEventsPath(projectRoot, boardId) {
+  assertValidBoardId(boardId);
+  const dir = path10.resolve(getKanbanDir(projectRoot));
+  const resolved = path10.resolve(dir, `${boardId}.events.jsonl`);
+  const rel = path10.relative(dir, resolved);
+  if (rel.startsWith("..") || path10.isAbsolute(rel)) {
+    throw invalidBoardId(boardId);
+  }
+  return resolved;
+}
 function isValidBoardId(boardId) {
   return BOARD_ID_RE.test(boardId) && !boardId.includes("..");
 }
@@ -5026,6 +5036,14 @@ async function readBoard(projectRoot, boardRef) {
     throw err;
   }
 }
+async function appendKanbanEvent(projectRoot, boardId, event) {
+  const filePath = getKanbanEventsPath(projectRoot, boardId);
+  await withFileLock(filePath, async () => {
+    await fsp7.mkdir(path10.dirname(filePath), { recursive: true });
+    await fsp7.appendFile(filePath, `${JSON.stringify(event)}
+`, "utf8");
+  });
+}
 async function mutateBoard(projectRoot, boardRef, mutator) {
   const boardId = await resolveBoardRef(projectRoot, boardRef);
   if (!boardId) return null;
@@ -5124,9 +5142,12 @@ async function listBoards(projectRoot) {
   return listBoardSummaries(projectRoot);
 }
 async function updateTaskAssignment(projectRoot, boardId, taskId, patch) {
+  let event;
   const updated = await mutateBoard(projectRoot, boardId, (board) => {
     const task = findTask(board, taskId);
     if (!task) return null;
+    const previousColumnId = task.columnId;
+    const beforeAssignment = task.assignment ? { ...task.assignment } : void 0;
     const nextAssignment = {
       ...task.assignment ?? { status: "assigned" }
     };
@@ -5164,10 +5185,17 @@ async function updateTaskAssignment(projectRoot, boardId, taskId, patch) {
       }
       delete task.completedAt;
     }
+    syncTaskColumnForStatus(board, task, previousColumnId);
     task.updatedAt = nowIso();
     board.updatedAt = task.updatedAt;
+    event = createKanbanEvent(board.id, task, assignmentEventType(task.assignment.status), {
+      before: beforeAssignment,
+      after: { ...task.assignment },
+      note: patch.error ?? patch.lastResult
+    });
     return task;
   });
+  if (updated && event) await emitKanbanEvent(projectRoot, event);
   return updated?.result ? updated.board : null;
 }
 async function claimReadyTask(projectRoot, input = {}) {
@@ -5214,14 +5242,25 @@ function buildAssignment(input) {
     ...input.fallbackProfile !== void 0 ? { fallbackProfile: input.fallbackProfile } : {},
     ...input.fallbackModels !== void 0 ? { fallbackModels: input.fallbackModels } : {},
     ...input.tools !== void 0 ? { tools: input.tools } : {},
-    ...input.allowedCapabilities !== void 0 ? { allowedCapabilities: input.allowedCapabilities } : {}
+    ...input.allowedCapabilities !== void 0 ? { allowedCapabilities: input.allowedCapabilities } : {},
+    ...input.leaseId !== void 0 ? { leaseId: input.leaseId } : {},
+    ...input.claimedAt !== void 0 ? { claimedAt: input.claimedAt } : {},
+    ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
+    ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
+    ...input.attempt !== void 0 ? { attempt: input.attempt } : {},
+    ...input.maxAttempts !== void 0 ? { maxAttempts: input.maxAttempts } : {},
+    ...input.costCeilingUsd !== void 0 ? { costCeilingUsd: input.costCeilingUsd } : {},
+    ...input.retryPolicy !== void 0 ? { retryPolicy: input.retryPolicy } : {},
+    ...input.lastFailureKind !== void 0 ? { lastFailureKind: input.lastFailureKind } : {}
   };
 }
 async function claimReadyTaskOnBoard(projectRoot, boardId, input) {
+  let event;
   const updated = await mutateBoard(projectRoot, boardId, (board) => {
     const candidates = input.taskId ? [findTask(board, input.taskId)].filter((task2) => Boolean(task2)) : board.tasks.filter((task2) => isTaskReadyForWork(board, task2)).sort(compareTasksForWork);
     const task = candidates.find((candidate) => isTaskReadyForWork(board, candidate));
     if (!task) return null;
+    const previousColumnId = task.columnId;
     const current = task.assignment;
     const assignment = buildAssignment({
       ...current?.agentId !== void 0 ? { agentId: current.agentId } : {},
@@ -5233,6 +5272,15 @@ async function claimReadyTaskOnBoard(projectRoot, boardId, input) {
       ...current?.fallbackModels !== void 0 ? { fallbackModels: current.fallbackModels } : {},
       ...current?.tools !== void 0 ? { tools: current.tools } : {},
       ...current?.allowedCapabilities !== void 0 ? { allowedCapabilities: current.allowedCapabilities } : {},
+      ...current?.leaseId !== void 0 ? { leaseId: current.leaseId } : {},
+      ...current?.claimedAt !== void 0 ? { claimedAt: current.claimedAt } : {},
+      ...current?.heartbeatAt !== void 0 ? { heartbeatAt: current.heartbeatAt } : {},
+      ...current?.leaseExpiresAt !== void 0 ? { leaseExpiresAt: current.leaseExpiresAt } : {},
+      ...current?.attempt !== void 0 ? { attempt: current.attempt } : {},
+      ...current?.maxAttempts !== void 0 ? { maxAttempts: current.maxAttempts } : {},
+      ...current?.costCeilingUsd !== void 0 ? { costCeilingUsd: current.costCeilingUsd } : {},
+      ...current?.retryPolicy !== void 0 ? { retryPolicy: current.retryPolicy } : {},
+      ...current?.lastFailureKind !== void 0 ? { lastFailureKind: current.lastFailureKind } : {},
       ...input.agentId !== void 0 ? { agentId: input.agentId } : {},
       ...input.name !== void 0 ? { name: input.name } : {},
       ...input.role !== void 0 ? { role: input.role } : {},
@@ -5242,10 +5290,20 @@ async function claimReadyTaskOnBoard(projectRoot, boardId, input) {
       ...input.fallbackModels !== void 0 ? { fallbackModels: input.fallbackModels } : {},
       ...input.tools !== void 0 ? { tools: input.tools } : {},
       ...input.allowedCapabilities !== void 0 ? { allowedCapabilities: input.allowedCapabilities } : {},
+      ...input.leaseId !== void 0 ? { leaseId: input.leaseId } : {},
+      ...input.claimedAt !== void 0 ? { claimedAt: input.claimedAt } : {},
+      ...input.heartbeatAt !== void 0 ? { heartbeatAt: input.heartbeatAt } : {},
+      ...input.leaseExpiresAt !== void 0 ? { leaseExpiresAt: input.leaseExpiresAt } : {},
+      ...input.attempt !== void 0 ? { attempt: input.attempt } : {},
+      ...input.maxAttempts !== void 0 ? { maxAttempts: input.maxAttempts } : {},
+      ...input.costCeilingUsd !== void 0 ? { costCeilingUsd: input.costCeilingUsd } : {},
+      ...input.retryPolicy !== void 0 ? { retryPolicy: input.retryPolicy } : {},
+      ...input.lastFailureKind !== void 0 ? { lastFailureKind: input.lastFailureKind } : {},
       ...input.assignee !== void 0 ? { assignee: input.assignee } : {},
       status: input.status ?? "queued"
     });
-    assignment.dispatchedAt = assignment.dispatchedAt ?? nowIso();
+    assignment.claimedAt = assignment.claimedAt ?? nowIso();
+    assignment.dispatchedAt = assignment.dispatchedAt ?? assignment.claimedAt;
     task.assignment = assignment;
     if (assignment.agentId ?? assignment.role ?? assignment.name) {
       task.assignedAgent = assignment.agentId ?? assignment.role ?? assignment.name;
@@ -5255,10 +5313,16 @@ async function claimReadyTaskOnBoard(projectRoot, boardId, input) {
     }
     task.status = assignment.status === "running" ? "in_progress" : "ready";
     delete task.completedAt;
+    syncTaskColumnForStatus(board, task, previousColumnId);
     task.updatedAt = nowIso();
     board.updatedAt = task.updatedAt;
+    event = createKanbanEvent(board.id, task, "task.claimed", {
+      before: current ? { ...current } : void 0,
+      after: { ...assignment }
+    });
     return task;
   });
+  if (updated && event) await emitKanbanEvent(projectRoot, event);
   return updated?.result ? { board: updated.board, task: updated.result } : null;
 }
 function compareTasksForWork(a, b) {
@@ -5292,6 +5356,18 @@ function findTask(board, taskId) {
   }
   return matches[0];
 }
+function existingColumnId(board, columnId) {
+  if (!columnId) return void 0;
+  const exact = board.columns.find((column) => column.id === columnId);
+  if (exact) return exact.id;
+  const matches = board.columns.filter((column) => column.id.startsWith(columnId));
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous kanban column id "${columnId}": ${matches.slice(0, 5).map((column) => column.id).join(", ")}`
+    );
+  }
+  return matches[0]?.id;
+}
 function isTaskReadyForWork(board, task) {
   if (!["pending", "ready"].includes(task.status)) return false;
   if (task.assignment && ["queued", "running"].includes(task.assignment.status)) return false;
@@ -5299,6 +5375,60 @@ function isTaskReadyForWork(board, task) {
   if (!areDependenciesMet(board, task.id)) return false;
   return true;
 }
+function createKanbanEvent(boardId, task, type, details = {}) {
+  return {
+    id: randomUUID(),
+    boardId,
+    taskId: task.id,
+    type,
+    ts: nowIso(),
+    ...task.assignment?.agentId !== void 0 ? { actor: task.assignment.agentId } : {},
+    ...task.assignment?.subagentId !== void 0 ? { subagentId: task.assignment.subagentId } : {},
+    ...task.assignment?.runTaskId !== void 0 ? { runTaskId: task.assignment.runTaskId } : {},
+    ...details
+  };
+}
+async function emitKanbanEvent(projectRoot, event) {
+  try {
+    await appendKanbanEvent(projectRoot, event.boardId, event);
+  } catch {
+  }
+}
+function assignmentEventType(status) {
+  return status === "completed" ? "task.assignment.completed" : status === "failed" ? "task.assignment.failed" : status === "running" ? "task.assignment.running" : status === "cancelled" ? "task.assignment.cancelled" : "task.assignment.updated";
+}
+function columnIdForKanbanStatus(board, status) {
+  const preferred = status === "completed" ? ["done", "completed"] : status === "in_progress" ? ["in-progress", "progress", "doing"] : status === "review" || status === "failed" ? ["review"] : status === "blocked" ? ["blocked", "backlog"] : status === "ready" ? ["todo", "ready", "backlog"] : status === "archived" ? ["done", "archive", "backlog"] : ["todo", "backlog"];
+  for (const columnRef of preferred) {
+    const columnId = existingColumnId(board, columnRef);
+    if (columnId) return columnId;
+  }
+  return board.columns[0]?.id;
+}
+function normalizeColumnTaskOrders(board, columnId) {
+  board.tasks.filter((task) => task.columnId === columnId).sort((a, b) => a.order - b.order || a.createdAt.localeCompare(b.createdAt)).forEach((task, index) => {
+    task.order = index;
+  });
+}
+function syncTaskColumnForStatus(board, task, previousColumnId) {
+  const nextColumnId = columnIdForKanbanStatus(board, task.status);
+  if (!nextColumnId || nextColumnId === task.columnId) return;
+  task.columnId = nextColumnId;
+  normalizeColumnTaskOrders(board, previousColumnId);
+  placeTaskInColumn(board, task, nextColumnId, void 0);
+}
+function placeTaskInColumn(board, task, columnId, targetOrder) {
+  const tasks = board.tasks.filter((candidate) => candidate.columnId === columnId && candidate.id !== task.id).sort((a, b) => a.order - b.order || a.createdAt.localeCompare(b.createdAt));
+  const index = clampOrder(targetOrder, tasks.length);
+  tasks.splice(index, 0, task);
+  tasks.forEach((candidate, order) => {
+    candidate.order = order;
+  });
+}
+function clampOrder(order, max) {
+  if (!Number.isFinite(order)) return max;
+  return Math.max(0, Math.min(Math.trunc(order), max));
+}
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -5426,6 +5556,9 @@ function makeLLMClassifier(complete) {
 }
 
 // src/coordination/director-tools.ts
+function nowIso2() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
 function makeSpawnTool(director, roster) {
   const inputSchema = {
     type: "object",
@@ -5983,8 +6116,8 @@ function makeAssignTool(director) {
 function makeKanbanQueueTool(director, roster) {
   return {
     name: "kanban_queue",
-    description: "Claim dependency-ready Kanban tasks and dispatch them into the Director fleet. Preserves per-task provider/model/role/tool routing metadata, assigns each claimed task to a spawned subagent, and can await results while writing completion back to Kanban.",
-    usageHint: 'Use action:"dispatch_ready" with optional boardId/taskId/maxTasks. Set awaitCompletion:true when you want this call to update Kanban to completed/failed before returning; otherwise use await_tasks and kanban mark_assignment later.',
+    description: "Claim dependency-ready Kanban tasks and dispatch them into the Director fleet. Preserves per-task provider/model/role/tool routing metadata, seeds lease metadata (claimedAt, leaseExpiresAt, heartbeatAt), assigns each claimed task to a spawned subagent, instructs workers to call kanban heartbeat_assignment periodically, and can await results while writing completion back to Kanban.",
+    usageHint: 'Use action:"dispatch_ready" with optional boardId/taskId/maxTasks. Set heartbeatIntervalMs (default 60s) and leaseTtlMs (default 5m) to size stale-recovery windows. Set awaitCompletion:true when you want this call to update Kanban to completed/failed before returning; otherwise use await_tasks and kanban mark_assignment later.',
     permission: "auto",
     mutating: true,
     capabilities: [ToolCapabilities.SUBAGENT_SPAWN, ToolCapabilities.FS_WRITE],
@@ -6015,6 +6148,16 @@ function makeKanbanQueueTool(director, roster) {
           minimum: 1,
           description: "Optional per-assigned-task tool-call cap."
         },
+        heartbeatIntervalMs: {
+          type: "number",
+          minimum: 1e3,
+          description: "Suggested heartbeat interval for the worker. Default 60000 (60s). Workers are instructed to call kanban heartbeat_assignment at this cadence."
+        },
+        leaseTtlMs: {
+          type: "number",
+          minimum: 1e3,
+          description: "Lease time-to-live seeded on dispatch. Default 300000 (5m). Workers should refresh via heartbeat_assignment before expiry."
+        },
         agentId: { type: "string" },
         name: { type: "string" },
         role: { type: "string" },
@@ -6037,6 +6180,14 @@ function makeKanbanQueueTool(director, roster) {
       const projectRoot = ctx.projectRoot;
       if (!projectRoot) return { error: "kanban_queue requires ctx.projectRoot." };
       const maxTasks = Math.max(1, Math.min(20, Math.floor(i.maxTasks ?? 1)));
+      const leaseTtlMs = Math.max(1e3, Math.floor(i.leaseTtlMs ?? 5 * 60 * 1e3));
+      const claimedAt = nowIso2();
+      const leaseSeeding = {
+        leaseId: randomUUID(),
+        claimedAt,
+        heartbeatAt: claimedAt,
+        leaseExpiresAt: new Date(Date.now() + leaseTtlMs).toISOString()
+      };
       const candidateTaskIds = i.taskId !== void 0 ? [i.taskId] : i.query ? (await listReadyTasks(projectRoot, {
         ...i.boardId !== void 0 ? { boardId: i.boardId } : {}
       })).filter((candidate) => matchesKanbanQueueQuery(candidate.task, i.query ?? "")).slice(0, maxTasks).map((candidate) => candidate.task.id) : void 0;
@@ -6057,6 +6208,7 @@ function makeKanbanQueueTool(director, roster) {
           ...i.fallbackModels !== void 0 ? { fallbackModels: i.fallbackModels } : {},
           ...i.tools !== void 0 ? { tools: i.tools } : {},
           ...i.allowedCapabilities !== void 0 ? { allowedCapabilities: i.allowedCapabilities } : {},
+          ...leaseSeeding !== void 0 ? leaseSeeding : {},
           status: "queued"
         });
         if (!claim) {
@@ -6065,13 +6217,34 @@ function makeKanbanQueueTool(director, roster) {
         }
         let subagentId;
         let runTaskId;
+        const costCeiling = claim.task.assignment?.costCeilingUsd;
+        if (costCeiling !== void 0) {
+          const remaining = director.getRemainingBudgetUsd();
+          if (remaining !== void 0 && remaining < costCeiling) {
+            await updateTaskAssignment(projectRoot, claim.board.id, claim.task.id, {
+              status: "failed",
+              error: `Cost ceiling ${costCeiling} exceeds remaining budget ${remaining.toFixed(4)}`,
+              lastResult: "Skipped by kanban_queue cost gate (Sprint 3)"
+            });
+            errors.push({
+              taskId: claim.task.id,
+              error: `Cost ceiling ${costCeiling} exceeds remaining budget ${remaining.toFixed(4)}`
+            });
+            continue;
+          }
+        }
         try {
           const config = buildKanbanSubagentConfig(claim.task, i, roster);
           subagentId = await director.spawn(config);
           runTaskId = await director.assign({
             id: randomUUID(),
             subagentId,
-            description: buildKanbanFleetTaskPrompt(claim.board, claim.task),
+            description: buildKanbanFleetTaskPrompt(claim.board, claim.task, {
+              heartbeatIntervalMs: i.heartbeatIntervalMs ?? 6e4,
+              leaseTtlMs,
+              leaseId: leaseSeeding.leaseId,
+              leaseExpiresAt: leaseSeeding.leaseExpiresAt
+            }),
             ...i.maxToolCalls !== void 0 ? { maxToolCalls: i.maxToolCalls } : {},
             ...i.timeoutMs !== void 0 ? { timeoutMs: i.timeoutMs } : {},
             context: {
@@ -6169,7 +6342,9 @@ function normalizeKanbanQueueInput(input) {
     fallbackModels: stringArray(raw.fallbackModels),
     tools: stringArray(raw.tools),
     allowedCapabilities: stringArray(raw.allowedCapabilities),
-    worktree: normalizeWorktreeOverride(raw.worktree)
+    worktree: normalizeWorktreeOverride(raw.worktree),
+    heartbeatIntervalMs: typeof raw.heartbeatIntervalMs === "number" ? raw.heartbeatIntervalMs : void 0,
+    leaseTtlMs: typeof raw.leaseTtlMs === "number" ? raw.leaseTtlMs : void 0
   };
 }
 function buildKanbanSubagentConfig(task, input, roster) {
@@ -6187,7 +6362,8 @@ function buildKanbanSubagentConfig(task, input, roster) {
     ...input.fallbackModels ?? assignment?.fallbackModels ? { fallbackModels: input.fallbackModels ?? assignment?.fallbackModels } : {},
     ...tools ? { tools: ensureKanbanTool(tools) } : {},
     ...input.allowedCapabilities ?? assignment?.allowedCapabilities ? { allowedCapabilities: input.allowedCapabilities ?? assignment?.allowedCapabilities } : {},
-    ...input.worktree !== void 0 ? { worktree: input.worktree } : {}
+    ...input.worktree !== void 0 ? { worktree: input.worktree } : {},
+    ...assignment?.costCeilingUsd !== void 0 ? { maxCostUsd: assignment.costCeilingUsd } : {}
   };
 }
 function ensureKanbanTool(tools) {
@@ -6207,7 +6383,7 @@ function matchesKanbanQueueQuery(task, query) {
     ...task.labels ?? []
   ].filter(Boolean).some((value) => String(value).toLowerCase().includes(normalized));
 }
-function buildKanbanFleetTaskPrompt(board, task) {
+function buildKanbanFleetTaskPrompt(board, task, lease) {
   const dependencyLines = (task.dependsOn ?? []).map((depId) => board.tasks.find((candidate) => candidate.id === depId)).filter((dep) => Boolean(dep)).map((dep) => `- ${dep.title} [${dep.status}] (${dep.id})`);
   const checks = task.successCriteria?.map((check) => `- ${check.description}`).join("\n");
   const metrics = task.goalMetrics?.map(
@@ -6254,9 +6430,24 @@ ${checks}` : "",
     metrics ? `Goal metrics:
 ${metrics}` : "",
     task.labels?.length ? `Labels: ${task.labels.join(", ")}` : "",
+    "Lease contract (Sprint 1):",
+    `- leaseId: ${lease.leaseId}`,
+    `- claimedAt: ${task.assignment?.claimedAt ?? "<unknown>"}`,
+    `- leaseExpiresAt: ${lease.leaseExpiresAt}`,
+    `- expected heartbeatIntervalMs: ${lease.heartbeatIntervalMs}`,
+    `- expected leaseTtlMs: ${lease.leaseTtlMs}`,
+    "",
+    "Retry policy:",
+    `- retryPolicy: ${task.assignment?.retryPolicy ?? task.retryPolicy ?? "<unset>"}`,
+    `- maxAttempts: ${task.assignment?.maxAttempts ?? "<unset>"}`,
+    `- costCeilingUsd: ${task.assignment?.costCeilingUsd ?? task.costCeilingUsd ?? "<unset>"}`,
     "",
     "Work this task end-to-end. If scope is too broad or too small, use the kanban tool to split_task or merge_tasks instead of losing traceability.",
-    `When you start or finish, call kanban with action "mark_assignment", boardId "${board.id}", taskId "${task.id}", and assignmentStatus "running", "completed", or "failed". Include lastResult or error when you finish.`,
+    `When you start, call kanban with action "mark_assignment", boardId "${board.id}", taskId "${task.id}", and assignmentStatus "running". Include subagentId and runTaskId when you have them.`,
+    `To stay alive in the queue, call kanban with action "heartbeat_assignment", boardId "${board.id}", taskId "${task.id}", and heartbeatAt set to the current time. Cadence must be <= heartbeatIntervalMs and well before leaseExpiresAt.`,
+    `When you finish, call kanban with action "mark_assignment", boardId "${board.id}", taskId "${task.id}", and assignmentStatus "completed" or "failed". Include lastResult or error.`,
+    `If you cannot finish in time, call kanban with action "heartbeat_assignment" to extend the lease, or with action "release_task" to release so another worker can claim. Do NOT silently abandon the assignment.`,
+    'On failure the host may call kanban with action "recover_stale" (mode: retry/release/fail); respect its decisions and do not duplicate work in parallel.',
     "When finished, report what changed, what you verified, and any remaining blockers."
   ].filter(Boolean).join("\n");
 }
@@ -8446,6 +8637,15 @@ var Director = class _Director {
   getLeaderContextPressure() {
     return this.leaderContextPressure;
   }
+  /**
+   * Remaining USD budget for the entire fleet (when a cap is configured).
+   * Returns `undefined` when no cap was set (Infinity).
+   */
+  getRemainingBudgetUsd() {
+    if (this.maxFleetCostUsd === Number.POSITIVE_INFINITY) return void 0;
+    const totalCost = this.usage.snapshot().total?.cost ?? 0;
+    return Math.max(0, this.maxFleetCostUsd - totalCost);
+  }
   resolveMaxContext() {
     const resolved = typeof this.maxContext === "function" ? this.maxContext() : this.maxContext;
     return resolved && resolved > 0 ? resolved : 128e3;
@@ -12072,6 +12272,17 @@ var GlobalMailbox = class {
   _messageCacheMtime = -1;
   /** Size of the file when `_messageCache` was populated (extra guard). */
   _messageCacheSize = -1;
+  /**
+   * Serializes reads of the message file so overlapping concurrent
+   * `_readMessagesCached()` calls don't both enter the incremental "file
+   * only grew" branch against the same stale `_messageCacheSize` and
+   * each push the same tail bytes onto the cache (duplicating every
+   * appended message). The chain runs each read to completion before
+   * the next starts, in issue order — readers are read-only and never
+   * conflict with each other on content, only on the cache mutation
+   * that follows the read. Pattern mirrors `DefaultMemoryStore.runSerialized`.
+   */
+  _readChain = Promise.resolve([]);
   /**
    * @param projectDir — `~/.wrongstack/projects/<slug>/`
    * @param events — optional EventBus for real-time TUI/WebUI notifications
@@ -12125,7 +12336,8 @@ var GlobalMailbox = class {
     await fsp7.mkdir(path10.dirname(this.messagePath), { recursive: true });
     await withFileLock(this.messagePath, async () => {
       await fsp7.appendFile(this.messagePath, line, "utf8");
-      this._pushToCache(msg);
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._pushToCache(msg, mtimeMs, size);
     });
     this.publishHqMailboxEvent({
       mailboxId: this.hqMailboxId,
@@ -12169,7 +12381,6 @@ var GlobalMailbox = class {
     for (const a of input.acks) {
       byId.set(a.messageId, a);
     }
-    let cacheSnapshot = null;
     await withFileLock(this.messagePath, async () => {
       const all = await this._readMessagesFresh();
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -12197,9 +12408,9 @@ var GlobalMailbox = class {
         const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
         await fsp7.writeFile(this.messagePath, serialized, "utf8");
       }
-      cacheSnapshot = all;
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache(all, mtimeMs, size);
     });
-    if (cacheSnapshot) this._setMessageCache(cacheSnapshot);
     for (const message of updated) {
       this.publishHqMailboxEvent({
         mailboxId: this.hqMailboxId,
@@ -12223,7 +12434,6 @@ var GlobalMailbox = class {
   }
   async softDelete(mailId, by) {
     let updated = null;
-    let cacheSnapshot = null;
     await withFileLock(this.messagePath, async () => {
       const all = await this._readMessagesFresh();
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -12239,9 +12449,9 @@ var GlobalMailbox = class {
       }
       const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
       await fsp7.writeFile(this.messagePath, serialized, "utf8");
-      cacheSnapshot = all;
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache(all, mtimeMs, size);
     });
-    if (cacheSnapshot) this._setMessageCache(cacheSnapshot);
     if (updated !== null) {
       this.publishHqMailboxEvent({
         mailboxId: this.hqMailboxId,
@@ -12254,7 +12464,6 @@ var GlobalMailbox = class {
   }
   async restore(mailId) {
     let updated = null;
-    let cacheSnapshot = null;
     await withFileLock(this.messagePath, async () => {
       const all = await this._readMessagesFresh();
       for (const m of all) {
@@ -12265,9 +12474,9 @@ var GlobalMailbox = class {
       }
       const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
       await fsp7.writeFile(this.messagePath, serialized, "utf8");
-      cacheSnapshot = all;
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache(all, mtimeMs, size);
     });
-    if (cacheSnapshot) this._setMessageCache(cacheSnapshot);
     if (updated !== null) {
       this.publishHqMailboxEvent({
         mailboxId: this.hqMailboxId,
@@ -12512,8 +12721,9 @@ var GlobalMailbox = class {
   async clearAll() {
     await withFileLock(this.messagePath, async () => {
       await fsp7.writeFile(this.messagePath, "", "utf8");
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache([], mtimeMs, size);
     });
-    this._setMessageCache([]);
   }
   async purgeStale(opts) {
     const COMPLETED_MAX_AGE_MS = opts?.completedMaxAgeMs ?? 864e5;
@@ -12545,7 +12755,8 @@ var GlobalMailbox = class {
         const content = kept.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
         await fsp7.writeFile(this.messagePath, content, "utf8");
       }
-      this._setMessageCache(kept);
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache(kept, mtimeMs, size);
     });
     return {
       completedPurged,
@@ -12632,14 +12843,43 @@ var GlobalMailbox = class {
    * from writers that just took the file lock — the read reflects the
    * authoritative post-lock state and should be served to subsequent
    * queries without re-reading.
+   *
+   * The mtime/size are captured from the stat at read time so the cache
+   * trackers match exactly what was parsed. Writers that subsequently
+   * rewrite the file MUST re-stat after the write and re-promote with the
+   * post-write values (see ackMany / softDelete / restore / purgeStale /
+   * clearAll) — otherwise a concurrent reader misclassifies the rewrite
+   * as a "file only grew" append and corrupts the cache.
    */
   async _readMessagesFresh() {
     const all = await this._readMessages();
-    this._setMessageCache(all);
+    const { mtimeMs, size } = await this._statMessageFile();
+    this._setMessageCache(all, mtimeMs, size);
     return all;
   }
   /**
-   * Read messages, consulting the mtime-bounded in-memory cache first.
+   * Stat the message file, returning its mtimeMs and size. Returns
+   * `-1/-1` when the file does not yet exist (ENOENT) so callers can
+   * still promote a cache snapshot — the next read will re-stat and
+   * fall through to a full re-read. Call from inside the file lock so
+   * the result reflects the post-write on-disk state, not a later
+   * intermediate state from another process.
+   */
+  async _statMessageFile() {
+    try {
+      const st = await fsp7.stat(this.messagePath);
+      return { mtimeMs: st.mtimeMs, size: st.size };
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return { mtimeMs: -1, size: -1 };
+      }
+      throw err;
+    }
+  }
+  /**
+   * Read messages, consulting the mtime-bounded in-memory cache first,
+   * serialized so concurrent callers don't both mutate the cache.
+   *
    * The mailbox file is shared across processes; every `send`/`ack`/
    * `clearAll`/`purgeStale` takes the file lock, so writes are serialized
    * and a changed mtimeMs is a definitive freshness signal. When the
@@ -12650,8 +12890,28 @@ var GlobalMailbox = class {
    * When the file only grew (new messages appended by another process),
    * we read and parse just the tail bytes instead of the entire file.
    * This avoids re-parsing the full 10K-message history on every check.
+   *
+   * SERIALIZATION: the actual work is chained onto `_readChain` so two
+   * overlapping calls can't both pass the `st.size > _messageCacheSize`
+   * incremental check against the same stale tracker and each push the
+   * same tail bytes onto the cache (duplicating every appended message).
+   * Readers don't conflict on file content — only on the cache mutation
+   * that follows the read — so we run them one at a time in issue order.
+   * Errors in the chain are swallowed so a failed read never poisons
+   * subsequent reads; each caller observes and re-throws its own error.
+   */
+  _readMessagesCached() {
+    const run = this._readChain.catch(() => void 0).then(() => this._readMessagesCachedWork());
+    this._readChain = run.catch(() => []);
+    return run;
+  }
+  /**
+   * The un-serialized body of {@link _readMessagesCached}. Reads the
+   * message file with the mtime-bounded cache + incremental-tail
+   * optimization. Must only be called from `_readMessagesCached` so the
+   * cache mutations here don't race a sibling read.
    */
-  async _readMessagesCached() {
+  async _readMessagesCachedWork() {
     try {
       const st = await fsp7.stat(this.messagePath);
       if (this._messageCache !== null && this._messageCacheMtime === st.mtimeMs && this._messageCacheSize === st.size) {
@@ -12680,9 +12940,19 @@ var GlobalMailbox = class {
     }
   }
   /**
-   * Replace the in-memory cache. Caller is responsible for guaranteeing
-   * that `messages` reflects the current on-disk state (e.g. they just
-   * read or wrote it under the file lock).
+   * Replace the in-memory cache, setting the mtime/size trackers
+   * synchronously in the same step. Callers MUST pass the stat of the
+   * on-disk file state that produced `messages`.
+   *
+   * Why both are required (not fire-and-forget): `_readMessagesCached()`
+   * validates the cache against a fresh stat using these two trackers.
+   * If the cache array is updated but the trackers lag behind (e.g. via
+   * a deferred `stat().then(...)`), a concurrent reader landing in that
+   * window sees a mismatched mtime and falls into the incremental
+   * "file only grew" branch — parsing rewritten bytes as an appended
+   * tail and corrupting the cache with duplicates/garbage. So both
+   * values are captured under the file lock and applied synchronously
+   * here, matching the fix already shipped in DefaultMailbox.
    */
   _setMessageCache(messages, mtime, size) {
     if (messages.length > MESSAGE_CACHE_MAX_ENTRIES) {
@@ -12692,25 +12962,27 @@ var GlobalMailbox = class {
       return;
     }
     this._messageCache = messages;
-    if (mtime !== void 0 && size !== void 0) {
-      this._messageCacheMtime = mtime;
-      this._messageCacheSize = size;
-    } else {
-      void fsp7.stat(this.messagePath).then((st) => {
-        this._messageCacheMtime = st.mtimeMs;
-        this._messageCacheSize = st.size;
-      }).catch(() => {
-      });
-    }
+    this._messageCacheMtime = mtime;
+    this._messageCacheSize = size;
   }
   /**
    * Append a single just-sent message to the in-memory cache without
    * re-reading the file. The caller must hold the file lock (or have
-   * just released it after a successful append) so the cache stays
-   * consistent with on-disk state.
+   * just released it after a successful append) and MUST pass the
+   * post-append stat so the mtime/size trackers advance in lock-step
+   * with the pushed content.
+   *
+   * Why the stat is required here: without it, `_messageCacheSize`
+   * stays at the pre-append value. A concurrent `_readMessagesCached()`
+   * then sees `st.size > _messageCacheSize` (the file did grow), takes
+   * the incremental branch, and re-reads the just-appended tail —
+   * pushing the same message onto the cache a second time. Setting the
+   * trackers here closes that window for the local-process append path.
    */
-  _pushToCache(msg) {
-    if (this._messageCache === null) return;
+  _pushToCache(msg, mtime, size) {
+    if (this._messageCache === null) {
+      return;
+    }
     if (this._messageCache.length >= MESSAGE_CACHE_MAX_ENTRIES) {
       this._messageCache = null;
       this._messageCacheMtime = -1;
@@ -12718,6 +12990,8 @@ var GlobalMailbox = class {
       return;
     }
     this._messageCache.push(msg);
+    this._messageCacheMtime = mtime;
+    this._messageCacheSize = size;
   }
   async _ensureRegistry() {
     await fsp7.mkdir(path10.dirname(this.registryPath), { recursive: true });