trekoon 0.4.1 → 0.4.3

package/src/board/routes.ts

@@ -1,9 +1,10 @@
 import { type Database } from "bun:sqlite";
 
-import { safeErrorMessage } from "../commands/error-utils";
-import { MutationService } from "../domain/mutation-service";
+import { redactSensitive, safeErrorMessage } from "../commands/error-utils";
+import { MutationService, PreconditionFailedError } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
 import { DomainError } from "../domain/types";
+import { type BoardEventBus } from "./event-bus";
 import { buildBoardSnapshot, buildBoardSnapshotDelta } from "./snapshot";
 
 interface SnapshotDeltaSelection {
@@ -19,6 +20,7 @@ interface BoardRouteContext {
   readonly db: Database;
   readonly cwd: string;
   readonly token: string;
+  readonly eventBus?: BoardEventBus;
 }
 
 interface BoardRouteError {
@@ -82,7 +84,7 @@ function readCookieToken(request: Request): string | null {
   return null;
 }
 
-function extractToken(request: Request, url: URL): string | null {
+function extractHeaderOrCookieToken(request: Request): string | null {
   const authorization: string | null = request.headers.get("authorization");
   if (authorization?.startsWith("Bearer ")) {
     return authorization.slice("Bearer ".length).trim();
@@ -93,11 +95,6 @@ function extractToken(request: Request, url: URL): string | null {
     return headerToken.trim();
   }
 
-  const queryToken: string | null = url.searchParams.get("token");
-  if (queryToken && queryToken.trim().length > 0) {
-    return queryToken.trim();
-  }
-
   return readCookieToken(request);
 }
 
@@ -106,6 +103,40 @@ function isSqliteBusyMessage(message: string): boolean {
   return normalized.includes("database is locked") || normalized.includes("database schema is locked");
 }
 
+const REDACT_DETAILS_MAX_DEPTH = 16;
+
+export function redactDetailLeaves(
+  value: unknown,
+  seen: WeakSet<object> = new WeakSet<object>(),
+  depth = 0,
+): unknown {
+  if (typeof value === "string") {
+    return redactSensitive(value);
+  }
+  if (depth >= REDACT_DETAILS_MAX_DEPTH) {
+    return "[MaxDepth]";
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    return value.map((item) => redactDetailLeaves(item, seen, depth + 1));
+  }
+  if (value !== null && typeof value === "object") {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      out[redactSensitive(key)] = redactDetailLeaves(child, seen, depth + 1);
+    }
+    return out;
+  }
+  return value;
+}
+
 function toBoardRouteError(error: unknown, requestLabel: string): BoardRouteError {
   if (error instanceof DomainError) {
     const status =
@@ -116,11 +147,20 @@ function toBoardRouteError(error: unknown, requestLabel: string): BoardRouteErro
           : error.code === "invalid_dependency" || error.code === "dependency_blocked"
             ? 409
           : 400;
+    // Secrets occasionally ride DomainError when an upstream layer interpolates
+    // a request body or header into the message/details (P1 finding 10).
+    // Run the canonical redactor over the message and recursively over every
+    // string-valued leaf of `details` before serialising to the wire so we
+    // never leak Bearer/Basic credentials, JWTs, or keyed `token=...` shapes.
+    const redactedMessage = redactSensitive(error.message);
+    const redactedDetails = error.details === undefined
+      ? undefined
+      : (redactDetailLeaves(error.details) as Record<string, unknown>);
     return {
       status,
       code: error.code,
-      message: error.message,
-      ...(error.details === undefined ? {} : { details: error.details }),
+      message: redactedMessage,
+      ...(redactedDetails === undefined ? {} : { details: redactedDetails }),
     };
   }
 
@@ -153,12 +193,233 @@ function describeBoardError(mutations: MutationService, error: unknown, requestL
     return routeError;
   }
 
+  // describeError can echo user-supplied values straight from a DomainError
+  // (status_transition_invalid returns error.message verbatim, dependency
+  // descriptions interpolate ids). Run the same redact pass over the
+  // friendlier message so secrets don't slip past the wire-level sanitiser.
   return {
     ...routeError,
-    message: readableMessage,
+    message: redactSensitive(readableMessage),
   };
 }
 
+function publishSnapshotDeltaIfPresent(
+  eventBus: BoardEventBus | undefined,
+  data: Record<string, unknown>,
+): void {
+  if (!eventBus) {
+    return;
+  }
+
+  const delta = readSnapshotDelta(data);
+  if (delta) {
+    eventBus.publishSnapshotDelta(delta);
+    eventBus.markInProcessWrite();
+  }
+}
+
+function formatSseEvent(eventName: string, data: unknown, id?: number): string {
+  const idLine = id === undefined ? "" : `id: ${id}\n`;
+  return `${idLine}event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+// SSE backpressure thresholds (P1 finding 5).
+// A client that connects but never reads can otherwise grow the per-stream
+// queue without bound. The stream controller already exposes queue pressure
+// through `desiredSize`; once it goes negative we stop enqueueing sparse
+// deltas and retain one pending full-snapshot frame for the next drain.
+const SSE_STALL_MS = 30_000; // 30 s without consumption under pressure → drop.
+const SSE_BACKPRESSURE_CHECK_MS = 1_000;
+
+function openSnapshotStream(
+  request: Request,
+  domain: TrackerDomain,
+  eventBus: BoardEventBus | undefined,
+): Response {
+  if (!eventBus) {
+    return jsonResponse(503, {
+      ok: false,
+      error: {
+        code: "stream_unavailable",
+        message: "Snapshot stream is not available on this server",
+      },
+    });
+  }
+
+  const encoder = new TextEncoder();
+  const initialSnapshot = buildBoardSnapshot(domain);
+  let unsubscribe: (() => void) | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let backpressureTimer: ReturnType<typeof setInterval> | null = null;
+
+  let lastConsumeAt = Date.now();
+  let closed = false;
+  let pendingFrame: string | null = null;
+  let onAbort: (() => void) | null = null;
+
+  const cleanupTimers = (): void => {
+    if (onAbort) {
+      request.signal.removeEventListener("abort", onAbort);
+      onAbort = null;
+    }
+    if (unsubscribe) {
+      unsubscribe();
+      unsubscribe = null;
+    }
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (backpressureTimer) {
+      clearInterval(backpressureTimer);
+      backpressureTimer = null;
+    }
+  };
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller): void {
+      const enqueueRaw = (chunk: string): void => {
+        if (closed) {
+          return;
+        }
+        try {
+          controller.enqueue(encoder.encode(chunk));
+        } catch {
+          // Controller closed; cleanup happens via cancel.
+        }
+      };
+
+      const isBackpressured = (): boolean => (controller.desiredSize ?? 1) < 0;
+
+      const queueFullSnapshot = (id: number): void => {
+        // Sparse per-mutation deltas are not cumulative, so merging them can
+        // silently drop changes. Under backpressure, retain a fresh full
+        // snapshot frame instead; EventSource clients can converge from it
+        // without relying on every skipped delta.
+        pendingFrame = formatSseEvent("snapshot", { snapshot: buildBoardSnapshot(domain) }, id);
+      };
+
+      const flushPendingFrame = (): void => {
+        if (!pendingFrame || closed || isBackpressured()) {
+          return;
+        }
+        const frame = pendingFrame;
+        pendingFrame = null;
+        enqueueRaw(frame);
+      };
+
+      const closeWithError = (reason: string): void => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        try {
+          const errorFrame = formatSseEvent("stream_error", { code: "backpressure", reason });
+          controller.enqueue(encoder.encode(errorFrame));
+        } catch {
+          // Already closed.
+        }
+        cleanupTimers();
+        try {
+          controller.close();
+        } catch {
+          // Already closed.
+        }
+      };
+
+      const handleSnapshotDelta = (id: number, snapshotDelta: Record<string, unknown>): void => {
+        if (closed) {
+          return;
+        }
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
+          return;
+        }
+        flushPendingFrame();
+        if (isBackpressured()) {
+          queueFullSnapshot(id);
+          return;
+        }
+        enqueueRaw(formatSseEvent("snapshotDelta", { snapshotDelta }, id));
+      };
+
+      // Initial snapshot so late-joining tabs converge immediately.
+      enqueueRaw(formatSseEvent("snapshot", { snapshot: initialSnapshot }));
+
+      unsubscribe = eventBus.subscribe((event) => {
+        if (event.type === "snapshotDelta") {
+          handleSnapshotDelta(event.id, event.snapshotDelta);
+        }
+      });
+
+      // Heartbeats keep proxies and stale-connection detectors happy.
+      heartbeatTimer = setInterval(() => {
+        if ((controller.desiredSize ?? 1) < 0) {
+          return;
+        }
+        enqueueRaw(": heartbeat\n\n");
+      }, 15000);
+
+      // Backpressure watchdog: if the consumer has not pulled within
+      // SSE_STALL_MS while the stream is under pressure, close with an
+      // error frame so EventSource reconnects and receives a fresh snapshot.
+      backpressureTimer = setInterval(() => {
+        if (closed) {
+          return;
+        }
+        const stalled = (controller.desiredSize ?? 1) < 0 && Date.now() - lastConsumeAt > SSE_STALL_MS;
+        if (stalled) {
+          closeWithError(`no consumer pull within ${SSE_STALL_MS}ms`);
+        }
+      }, SSE_BACKPRESSURE_CHECK_MS);
+
+      onAbort = (): void => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        cleanupTimers();
+        try {
+          controller.close();
+        } catch {
+          // Already closed.
+        }
+      };
+
+      if (request.signal.aborted) {
+        onAbort();
+        return;
+      }
+      request.signal.addEventListener("abort", onAbort);
+    },
+    pull(controller): void {
+      lastConsumeAt = Date.now();
+      if (pendingFrame && !closed && (controller.desiredSize ?? 1) >= 0) {
+        const frame = pendingFrame;
+        pendingFrame = null;
+        try {
+          controller.enqueue(encoder.encode(frame));
+        } catch {
+          // Controller closed.
+        }
+      }
+    },
+    cancel(): void {
+      closed = true;
+      cleanupTimers();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "cache-control": "no-store",
+      "content-type": "text/event-stream; charset=utf-8",
+      "x-accel-buffering": "no",
+    },
+  });
+}
+
 function buildMutationResponse(_domain: TrackerDomain, data: Record<string, unknown>, status = 200): Response {
   return jsonResponse(status, {
     ok: true,
@@ -301,6 +562,56 @@ function readOptionalNullableString(body: Record<string, unknown>, field: string
   return value;
 }
 
+function parseIfMatchHeader(request: Request): number | null {
+  const raw = request.headers.get("if-match");
+  if (raw === null) {
+    return null;
+  }
+
+  // RFC 7232 §3.1 allows a strong ETag (`"<value>"`) or a weak ETag
+  // (`W/"<value>"`). Trekoon does not differentiate strong from weak
+  // semantics — the entity version token is exact either way — so we
+  // accept both shapes. The wildcard `*` is intentionally NOT supported:
+  // it would mean "any current representation matches" and would defeat
+  // the whole purpose of the optimistic-concurrency check, so we surface
+  // it as 400 invalid_input below rather than treating it as a no-op.
+  const stripped = raw.trim().replace(/^W\//iu, "");
+  const trimmed = stripped.replace(/^"+|"+$/g, "");
+  if (!/^(0|[1-9]\d*)$/u.test(trimmed)) {
+    throw new DomainError({
+      code: "invalid_input",
+      message:
+        "If-Match header must be a non-negative integer version token (RFC 7232 strong or W/-prefixed weak ETag); the `*` wildcard is not supported",
+      details: { header: "If-Match", value: raw },
+    });
+  }
+
+  return Number(trimmed);
+}
+
+interface PreconditionFailedDetails {
+  readonly entityKind: "epic" | "task" | "subtask";
+  readonly entityId: string;
+  readonly currentVersion: number;
+  readonly providedVersion: number;
+}
+
+function preconditionFailedResponse(details: PreconditionFailedDetails): Response {
+  return jsonResponse(409, {
+    ok: false,
+    error: {
+      code: "precondition_failed",
+      message: "If-Match version does not match current version",
+      details: {
+        entityKind: details.entityKind,
+        entityId: details.entityId,
+        currentVersion: details.currentVersion,
+        providedVersion: details.providedVersion,
+      },
+    },
+  });
+}
+
 function readIdempotencyKey(request: Request, body: Record<string, unknown>): string | null {
   const headerKey = request.headers.get("x-trekoon-idempotency-key");
   if (typeof headerKey === "string" && headerKey.trim().length > 0) {
@@ -319,7 +630,27 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
     const requestLabel = `${request.method} ${url.pathname}`;
-    const requestToken = extractToken(request, url);
+    if (url.searchParams.has("token")) {
+      return jsonResponse(401, {
+        ok: false,
+        error: {
+          code: "unauthorized",
+          message: "Board API requests must authenticate with the session cookie or authorization header",
+        },
+      });
+    }
+    const requestToken = url.pathname === "/api/snapshot/stream"
+      ? readCookieToken(request)
+      : extractHeaderOrCookieToken(request);
+    // Plain `!==` instead of a constant-time compare is a deliberate choice
+    // (System Hardening 0.4.2, finding 32). The board server only binds to
+    // 127.0.0.1, the session token is a 256-bit cryptographically-random
+    // value rotated per board-server lifetime, and the comparison happens
+    // against an in-memory string — there is no remote-timing side-channel
+    // realistic enough to attack. Adopting `crypto.timingSafeEqual` would
+    // also require handling length-mismatch as a separate non-leaking case.
+    // Re-evaluate this decision if the board server ever listens on a
+    // non-loopback interface or uses a low-entropy / static token.
     if (requestToken !== context.token) {
       return jsonResponse(401, {
         ok: false,
@@ -332,6 +663,27 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
 
     const domain = new TrackerDomain(context.db);
     const mutations = new MutationService(context.db, context.cwd);
+    const eventBus = context.eventBus;
+
+    const respondWithMutation = (
+      domainArg: TrackerDomain,
+      data: Record<string, unknown>,
+      status = 200,
+    ): Response => {
+      publishSnapshotDeltaIfPresent(eventBus, data);
+      return buildMutationResponse(domainArg, data, status);
+    };
+
+    const respondWithMutationDelta = (
+      domainArg: TrackerDomain,
+      data: Record<string, unknown>,
+      selection: SnapshotDeltaSelection,
+      status = 200,
+    ): Response => {
+      const enrichedData = { ...data, snapshotDelta: buildSnapshotDelta(domainArg, selection) };
+      publishSnapshotDeltaIfPresent(eventBus, enrichedData);
+      return buildMutationResponse(domainArg, enrichedData, status);
+    };
 
     try {
       if (request.method === "GET" && url.pathname === "/api/snapshot") {
@@ -343,15 +695,26 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         });
       }
 
+      if (request.method === "GET" && url.pathname === "/api/snapshot/stream") {
+        return openSnapshotStream(request, domain, eventBus);
+      }
+
         const epicCascadeMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)\/cascade$/u) : null;
         if (epicCascadeMatch) {
+          const epicId = epicCascadeMatch[1] ?? "";
           const body = await parseJsonBody(request);
           const status = readRequiredString(body, "status");
-          const plan = mutations.updateEpicStatusCascade(epicCascadeMatch[1] ?? "", status);
-          return buildMutationDeltaResponse(domain, {
+          const ifMatch = parseIfMatchHeader(request);
+          // CAS path: precondition is enforced inside the write transaction
+          // (see PreconditionFailedError catch below). Missing-header path
+          // preserves back-compat with clients that don't send If-Match.
+          const plan = ifMatch !== null
+            ? mutations.updateEpicStatusCascadeWithIfMatch(epicId, ifMatch, status)
+            : mutations.updateEpicStatusCascade(epicId, status);
+          return respondWithMutationDelta(domain, {
             plan,
           }, {
-            epicIds: [epicCascadeMatch[1] ?? ""],
+            epicIds: [epicId],
             taskIds: plan.orderedChanges.filter((change) => change.kind === "task").map((change) => change.id),
             subtaskIds: plan.orderedChanges.filter((change) => change.kind === "subtask").map((change) => change.id),
           });
@@ -359,38 +722,53 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
 
       const epicMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/epics\/([^/]+)$/u) : null;
         if (epicMatch) {
+        const epicId = epicMatch[1] ?? "";
         const body = await parseJsonBody(request);
-        const epic = mutations.updateEpic(epicMatch[1] ?? "", {
+        const ifMatch = parseIfMatchHeader(request);
+        const epicInput = {
           title: readOptionalString(body, "title"),
           description: readOptionalString(body, "description"),
           status: readOptionalString(body, "status"),
-        });
-          return buildMutationDeltaResponse(domain, { epic }, { epicIds: [epic.id] });
+        };
+        const epic = ifMatch !== null
+          ? mutations.updateEpicWithIfMatch(epicId, ifMatch, epicInput)
+          : mutations.updateEpic(epicId, epicInput);
+          return respondWithMutationDelta(domain, { epic }, { epicIds: [epic.id] });
         }
 
       const taskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/tasks\/([^/]+)$/u) : null;
       if (taskMatch) {
+        const taskId = taskMatch[1] ?? "";
         const body = await parseJsonBody(request);
-          const task = mutations.updateTask(taskMatch[1] ?? "", {
-            title: readOptionalString(body, "title"),
-            description: readOptionalString(body, "description"),
-            status: readOptionalString(body, "status"),
-            owner: readOptionalNullableString(body, "owner"),
-          });
-          return buildMutationDeltaResponse(domain, { task }, { epicIds: [task.epicId], taskIds: [task.id] });
+        const ifMatch = parseIfMatchHeader(request);
+        const taskInput = {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+          owner: readOptionalNullableString(body, "owner"),
+        };
+        const task = ifMatch !== null
+          ? mutations.updateTaskWithIfMatch(taskId, ifMatch, taskInput)
+          : mutations.updateTask(taskId, taskInput);
+          return respondWithMutationDelta(domain, { task }, { epicIds: [task.epicId], taskIds: [task.id] });
         }
 
       const subtaskMatch = request.method === "PATCH" ? url.pathname.match(/^\/api\/subtasks\/([^/]+)$/u) : null;
       if (subtaskMatch) {
+        const subtaskId = subtaskMatch[1] ?? "";
         const body = await parseJsonBody(request);
-          const subtask = mutations.updateSubtask(subtaskMatch[1] ?? "", {
-            title: readOptionalString(body, "title"),
-            description: readOptionalString(body, "description"),
-            status: readOptionalString(body, "status"),
-            owner: readOptionalNullableString(body, "owner"),
-          });
+        const ifMatch = parseIfMatchHeader(request);
+        const subtaskInput = {
+          title: readOptionalString(body, "title"),
+          description: readOptionalString(body, "description"),
+          status: readOptionalString(body, "status"),
+          owner: readOptionalNullableString(body, "owner"),
+        };
+        const subtask = ifMatch !== null
+          ? mutations.updateSubtaskWithIfMatch(subtaskId, ifMatch, subtaskInput)
+          : mutations.updateSubtask(subtaskId, subtaskInput);
           const task = domain.getTaskOrThrow(subtask.taskId);
-          return buildMutationDeltaResponse(domain, { subtask }, { epicIds: [task.epicId], taskIds: [task.id], subtaskIds: [subtask.id] });
+          return respondWithMutationDelta(domain, { subtask }, { epicIds: [task.epicId], taskIds: [task.id], subtaskIds: [subtask.id] });
         }
 
       if (request.method === "POST" && url.pathname === "/api/subtasks") {
@@ -413,7 +791,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               subtaskIds: [subtask.id],
             }),
           };
-          return buildMutationResponse(domain, responseData, 201);
+          return respondWithMutation(domain, responseData, 201);
         }
 
         const result = mutations.createSubtaskAtomicallyWithIdempotency({
@@ -442,7 +820,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         const replaySubtaskId = readRecordId(result.responseData.subtask);
         const replayTaskId = replaySubtaskId ? domain.getSubtask(replaySubtaskId)?.taskId ?? null : null;
         const replayEpicId = replayTaskId ? domain.getTask(replayTaskId)?.epicId ?? null : null;
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, {
             epicIds: replayEpicId ? [replayEpicId] : [],
             taskIds: replayTaskId ? [replayTaskId] : [],
@@ -470,7 +848,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
                 deletedDependencyIds,
               }),
             };
-            return buildMutationResponse(domain, responseData, 200);
+            return respondWithMutation(domain, responseData, 200);
           }
 
           const result = mutations.deleteSubtaskAtomicallyWithIdempotency({
@@ -493,7 +871,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
             }),
           });
           const replaySnapshotDelta = readSnapshotDelta(result.responseData);
-          return buildMutationResponse(domain, result.state === "replay"
+          return respondWithMutation(domain, result.state === "replay"
             ? withFreshReplaySnapshotDelta(domain, result.responseData, {
               epicIds: readRecordIds(replaySnapshotDelta?.epics),
               taskIds: readRecordIds(replaySnapshotDelta?.tasks),
@@ -519,7 +897,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               dependencyIds: [dependency.id],
             }),
           };
-          return buildMutationResponse(domain, responseData, 201);
+          return respondWithMutation(domain, responseData, 201);
         }
 
         const result = mutations.addDependencyAtomicallyWithIdempotency({
@@ -563,7 +941,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
             dependencyIds: replayDependencyId ? [replayDependencyId] : [],
           }
           : { dependencyIds: [] };
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, replaySelection)
           : result.responseData, result.status);
       }
@@ -598,7 +976,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
               deletedDependencyIds: existingDependencyIds,
             }),
           };
-          return buildMutationResponse(domain, responseData, 200);
+          return respondWithMutation(domain, responseData, 200);
         }
 
         const result = mutations.removeDependencyAtomicallyWithIdempotency({
@@ -622,7 +1000,7 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
           }),
         });
         const replaySnapshotDelta = readSnapshotDelta(result.responseData);
-        return buildMutationResponse(domain, result.state === "replay"
+        return respondWithMutation(domain, result.state === "replay"
           ? withFreshReplaySnapshotDelta(domain, result.responseData, {
             taskIds: compactIds([domain.getTask(sourceId)?.id ?? "", domain.getTask(dependsOnId)?.id ?? ""]),
             subtaskIds: compactIds([domain.getSubtask(sourceId)?.id ?? "", domain.getSubtask(dependsOnId)?.id ?? ""]),
@@ -639,6 +1017,18 @@ export function createBoardApiHandler(context: BoardRouteContext): (request: Req
         },
       });
     } catch (error: unknown) {
+      // PreconditionFailedError is a typed signal from the *WithIfMatch
+      // CAS variants. It carries the freshly-fetched currentVersion so
+      // the 409 payload is always consistent with the post-rollback state.
+      if (error instanceof PreconditionFailedError) {
+        return preconditionFailedResponse({
+          entityKind: error.entityKind,
+          entityId: error.entityId,
+          currentVersion: error.currentVersion,
+          providedVersion: error.providedVersion,
+        });
+      }
+
       const routeError = describeBoardError(mutations, error, requestLabel);
       return jsonResponse(routeError.status, {
         ok: false,