@myspec/mcp-server 0.1.5-next.62 → 0.1.5-next.63

package/README.md

@@ -89,8 +89,8 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 |---|---|---|
 | `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects |
 | `get_project` | `project_id` | Project + active sessions + files + attachments |
-| `get_spec_file` | `file_id`, optional `include_download_url` | File metadata; with `include_download_url=N` also returns a download URL targeting revision `N` |
-| `read_spec_file` | `file_id`, optional `revision` | UTF-8 content of the file (errors for binary or files > 1 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
+| `get_spec_file` | `file_id`, optional `include_download_url` | File metadata, including `content_version` (see [Concurrent edits](#concurrent-edits-content_version)); with `include_download_url=N` also returns a download URL targeting revision `N` |
+| `read_spec_file` | `file_id`, optional `revision` | UTF-8 content of the file, plus `content_version` when reading the latest revision (errors for binary or files > 1 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT` |
 | `download_spec_file` | `file_id`, `destination_path`, optional `revision`, optional `overwrite` | Downloads the file's raw bytes to `destination_path` (absolute or cwd-relative; an existing directory gets the basename appended). Handles binary files and files up to 50 MiB. Refuses to replace an existing file unless `overwrite=true`. Returns only metadata (`saved_path`, `bytes_written`, `revision_number`) — **not** the content, so a large file can be saved locally and read in chunks |
 | `list_spec_file` | `project_id`, optional `path`, optional `trashed` | Lists a project's spec files (`file_id`, `file_path`, `file_type`, `file_size_bytes`, `revision_count`, `session_id`, `updated_at`). Filter to a directory with `path` (exact file or everything under it; `""`/`"/"`/omit = all). `trashed=true` lists the Trash Bin instead of live files |
 | `move_spec_file_to_trash` | `file_id` | Moves a spec file to the Trash Bin (recoverable — hidden from listings and AI-agent tools, restorable indefinitely). Not a permanent delete |
@@ -112,6 +112,31 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 - Omit or `0` → metadata only.
 - Any positive integer → adds a signed `download_url` and `expires_at`. Attachments do not have revisions, so the integer value is just an on/off flag.
 
+### Concurrent edits: `content_version`
+
+Several people (and AI sessions) can work the same project at once, so a spec file
+can change between the moment you read it and the moment you write it back.
+
+`get_spec_file` and `read_spec_file` return `content_version`, an opaque token for
+the content they returned. Pass it to `update_spec_file` as `expected_version`:
+
+- If nothing changed, the update succeeds and the file's version advances.
+- If someone else saved in the meantime, the update is **rejected** — their version
+  is kept, nothing of theirs is overwritten — and the error names who changed it and
+  what to do: re-read, decide how the two changes combine, then update again.
+
+Omitting `expected_version` falls back to the file's version as of the update call,
+which only detects a change racing that one call. Always pass the token from the read
+your new content was based on.
+
+Notes:
+
+- `content_version` is **not** `revision_count`: a revision revert decrements the
+  count, so the same count can describe different content.
+- It is omitted rather than zeroed when the platform does not report one, and
+  `read_spec_file` omits it for a historical `revision` because it describes the
+  file's current content, not the revision you asked for.
+
 ## Claude Desktop config snippet
 
 ```json

package/dist/index.js

@@ -873,6 +873,153 @@ async function withRetry(fn, config = DEFAULT_RETRY_CONFIG, shouldRetry = defaul
   };
 }
 
+// ../../packages/platform-client/shared/errors.ts
+var PLATFORM_ERROR_BRAND = "__myspecPlatformError";
+var KNOWN_CONFLICT_REASONS = [
+  "revision_mismatch",
+  "path_taken",
+  "precondition_required",
+  "precondition_malformed"
+];
+var PlatformHttpError = class extends Error {
+  status;
+  details;
+  /** Populated once the request layer knows them; useful in logs. */
+  method;
+  path;
+  /** How many attempts were made before giving up. */
+  attempts;
+  constructor(message, status, details) {
+    super(message);
+    this.name = "PlatformHttpError";
+    this.status = status;
+    this.details = details;
+    Object.defineProperty(this, PLATFORM_ERROR_BRAND, {
+      value: true,
+      enumerable: false
+    });
+  }
+};
+var PlatformConflictError = class extends PlatformHttpError {
+  conflict;
+  constructor(message, status, details, conflict) {
+    super(message, status, details);
+    this.name = "PlatformConflictError";
+    this.conflict = conflict;
+  }
+};
+var PlatformPreconditionRequiredError = class extends PlatformHttpError {
+  constructor(message, details) {
+    super(message, 428, details);
+    this.name = "PlatformPreconditionRequiredError";
+  }
+};
+function isPlatformHttpError(err) {
+  return typeof err === "object" && err !== null && err[PLATFORM_ERROR_BRAND] === true;
+}
+function conflictOf(err) {
+  if (err instanceof PlatformConflictError) {
+    return err.conflict;
+  }
+  if (statusOf(err) !== 409) {
+    return void 0;
+  }
+  const ownDetails = err.details;
+  const own = typeof ownDetails === "object" && ownDetails !== null && !Array.isArray(ownDetails) ? ownDetails : void 0;
+  const fromMessage = err instanceof Error ? parseHttpErrorDetails(err.message) : void 0;
+  return toConflictDetails(
+    own || fromMessage ? { ...fromMessage ?? {}, ...own ?? {} } : void 0
+  );
+}
+function isPlatformPreconditionRequiredError(err) {
+  return isPlatformHttpError(err) && err.status === 428;
+}
+function statusOf(err) {
+  if (typeof err !== "object" || err === null) {
+    return void 0;
+  }
+  const status = err.status;
+  if (typeof status === "number") {
+    return status;
+  }
+  const message = err.message;
+  if (typeof message === "string") {
+    const match = /HTTP (\d{3}):/.exec(message);
+    if (match) {
+      return Number(match[1]);
+    }
+  }
+  return void 0;
+}
+function parseHttpErrorDetails(message) {
+  const start = message.lastIndexOf("[details: ");
+  if (start === -1) {
+    return void 0;
+  }
+  const jsonStart = start + "[details: ".length;
+  for (let end = message.lastIndexOf("]"); end > jsonStart; end = message.lastIndexOf("]", end - 1)) {
+    try {
+      const parsed = JSON.parse(message.slice(jsonStart, end));
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function numberField(details, key) {
+  const value = details?.[key];
+  return typeof value === "number" ? value : void 0;
+}
+function stringField(details, key) {
+  const value = details?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+function toConflictDetails(details) {
+  const rawReason = stringField(details, "reason");
+  const reason = KNOWN_CONFLICT_REASONS.includes(rawReason) ? rawReason : "unknown";
+  return {
+    reason,
+    currentVersion: numberField(details, "current_version"),
+    expectedVersion: numberField(details, "expected_version"),
+    currentRevision: numberField(details, "current_revision"),
+    currentChecksum: stringField(details, "current_checksum"),
+    changedBy: stringField(details, "last_changed_by"),
+    changedByKind: stringField(details, "last_changed_by_kind"),
+    changedAt: stringField(details, "last_modified_at")
+  };
+}
+function createPlatformError(message, status, details) {
+  if (status === 409) {
+    return new PlatformConflictError(message, status, details, toConflictDetails(details));
+  }
+  if (status === 428) {
+    return new PlatformPreconditionRequiredError(message, details);
+  }
+  return new PlatformHttpError(message, status, details);
+}
+function truncate(text) {
+  const MAX_ERROR_LENGTH = 500;
+  return text.length > MAX_ERROR_LENGTH ? text.slice(0, MAX_ERROR_LENGTH) + "... [truncated]" : text;
+}
+async function throwFromResponse(response, fallbackMessage) {
+  const rawBody = await response.text().catch(() => "");
+  let message = fallbackMessage;
+  let details;
+  if (rawBody) {
+    try {
+      const parsed = JSON.parse(rawBody);
+      details = parsed.details;
+      const suffix = details ? ` [details: ${JSON.stringify(details)}]` : "";
+      message = truncate(parsed.message ?? rawBody) + suffix;
+    } catch {
+      message = truncate(rawBody);
+    }
+  }
+  throw createPlatformError(`HTTP ${response.status}: ${message}`, response.status, details);
+}
+
 // ../../packages/shared/logger.ts
 var LOG_LEVEL_PRIORITY = {
   debug: 0,
@@ -1002,6 +1149,12 @@ var BaseHttpClient = class {
         path: path4,
         attempts: result.attempts
       });
+      if (isPlatformHttpError(error)) {
+        error.method = method;
+        error.path = path4;
+        error.attempts = result.attempts;
+        throw error;
+      }
       const wrapped = new Error(
         `${method} ${path4} failed after ${result.attempts} attempts: ${error.message}`
       );
@@ -1030,23 +1183,7 @@ var BaseHttpClient = class {
         signal: controller.signal
       });
       if (!response.ok) {
-        let errorMessage2;
-        const rawBody = await response.text().catch(() => "");
-        if (rawBody) {
-          try {
-            const errorBody = JSON.parse(rawBody);
-            const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
-            errorMessage2 = (errorBody.message ?? JSON.stringify(errorBody)) + details;
-          } catch {
-            const MAX_ERROR_LENGTH = 500;
-            errorMessage2 = rawBody.length > MAX_ERROR_LENGTH ? rawBody.slice(0, MAX_ERROR_LENGTH) + "... [truncated]" : rawBody;
-          }
-        } else {
-          errorMessage2 = "Unknown error";
-        }
-        const error = new Error(`HTTP ${response.status}: ${errorMessage2}`);
-        error.status = response.status;
-        throw error;
+        await throwFromResponse(response, "Unknown error");
       }
       const contentLength = response.headers.get("Content-Length");
       if (contentLength === "0" || response.status === 204) {
@@ -1137,6 +1274,7 @@ function transformSpecFileResponse(raw) {
     fileSizeBytes: raw.file_size_bytes,
     checksum: raw.checksum,
     revisionCount: raw.revision_count,
+    contentVersion: raw.content_version,
     createdAt: new Date(raw.created_at),
     updatedAt: new Date(raw.updated_at),
     trashedAt: raw.trashed_at ? new Date(raw.trashed_at) : void 0,
@@ -1207,6 +1345,9 @@ function transformSpecSessionResponse(raw) {
   };
 }
 
+// ../../packages/platform-client/project/types/lock.types.ts
+var SPEC_FILE_LOCK_TTL_MS = 2 * 6e4;
+
 // ../../packages/platform-client/project/http/attachment.http-client.ts
 var UPLOAD_TIMEOUT_MS = 3e4;
 var HttpAttachmentClient = class {
@@ -1333,11 +1474,41 @@ var HttpAttachmentClient = class {
 };
 
 // ../../packages/platform-client/project/http/file.http-client.ts
+var HEADER_EXPECTED_VERSION = "X-Expected-Version";
+var HEADER_ACTOR_KIND = "X-Actor-Kind";
+function parseVersionETag(etag) {
+  if (!etag) {
+    return void 0;
+  }
+  const parsed = Number(etag.replace(/"/g, "").trim());
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
 var HttpFileClient = class {
   httpClient;
   constructor(httpClient) {
     this.httpClient = httpClient;
   }
+  /**
+   * Headers for the raw binary routes.
+   *
+   * BaseHttpClient is JSON-only, so uploadContent/saveManualRevision hand-roll
+   * their fetch. Centralised here so the write precondition is attached
+   * identically on both — a path that quietly omits it would look guarded while
+   * writing blind, which is the worst possible failure for this mechanism.
+   */
+  binaryWriteHeaders(jwtToken, opts) {
+    const headers = {
+      "Content-Type": "application/octet-stream",
+      Authorization: `Bearer ${jwtToken}`
+    };
+    if (opts?.expectedVersion !== void 0) {
+      headers[HEADER_EXPECTED_VERSION] = String(opts.expectedVersion);
+    }
+    if (opts?.actorKind) {
+      headers[HEADER_ACTOR_KIND] = opts.actorKind;
+    }
+    return headers;
+  }
   async initiateUpload(request, jwtToken) {
     const body = {
       project_id: request.projectId,
@@ -1353,11 +1524,15 @@ var HttpFileClient = class {
       "/project/v1/files/initiate",
       body,
       jwtToken,
-      {}
+      request.expectedVersion !== void 0 ? { headers: { [HEADER_EXPECTED_VERSION]: String(request.expectedVersion) } } : {}
     );
-    return { fileId: response.file_id };
+    return {
+      fileId: response.file_id,
+      revision: response.revision,
+      contentVersion: response.content_version
+    };
   }
-  async uploadContent(fileId, content, jwtToken) {
+  async uploadContent(fileId, content, jwtToken, opts) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}/content`;
     const blob = new Blob([content], {
@@ -1365,28 +1540,22 @@ var HttpFileClient = class {
     });
     const response = await fetch(url, {
       method: "PUT",
-      headers: {
-        "Content-Type": "application/octet-stream",
-        Authorization: `Bearer ${jwtToken}`
-      },
+      headers: this.binaryWriteHeaders(jwtToken, opts),
       body: blob
     });
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
-      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
-      throw new Error(
-        `HTTP ${response.status}: ${errorBody.message ?? "Upload failed"}${details}`
-      );
+      await throwFromResponse(response, "Upload failed");
     }
     const result = await response.json();
     return {
       fileId: result.file_id,
       fileRevisionId: result.file_revision_id,
       fileUri: result.file_uri,
-      revisionNumber: result.revision_number
+      revisionNumber: result.revision_number,
+      contentVersion: result.content_version
     };
   }
-  async saveManualRevision(fileId, content, jwtToken) {
+  async saveManualRevision(fileId, content, jwtToken, opts) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}/revisions`;
     const blob = new Blob([content], {
@@ -1394,18 +1563,11 @@ var HttpFileClient = class {
     });
     const response = await fetch(url, {
       method: "POST",
-      headers: {
-        "Content-Type": "application/octet-stream",
-        Authorization: `Bearer ${jwtToken}`
-      },
+      headers: this.binaryWriteHeaders(jwtToken, opts),
       body: blob
     });
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
-      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
-      throw new Error(
-        `HTTP ${response.status}: ${errorBody.message ?? "Save failed"}${details}`
-      );
+      await throwFromResponse(response, "Save failed");
     }
     const result = await response.json();
     return {
@@ -1414,7 +1576,8 @@ var HttpFileClient = class {
       // The manual-revision endpoint does not return a current file URI (the FE only
       // needs the revision id + number); keep the response shape stable with ''.
       fileUri: "",
-      revisionNumber: result.revision_number
+      revisionNumber: result.revision_number,
+      contentVersion: result.content_version
     };
   }
   async getFile(fileId, jwtToken) {
@@ -1448,6 +1611,23 @@ var HttpFileClient = class {
     };
   }
   async downloadContent(fileId, jwtToken) {
+    return (await this.downloadContentWithVersion(fileId, jwtToken)).content;
+  }
+  /**
+   * Downloads content together with the concurrency token it was read at.
+   *
+   * Use this, not {@link downloadContent}, when the bytes are going to be edited
+   * and written back. The platform sets `ETag: "<contentVersion>"` on this
+   * response precisely so the two arrive together; fetching the content and then
+   * calling `getFile` for the version is two round trips with a window in
+   * between where they disagree — and basing a write on a version that does not
+   * match the content you edited is the bug the precondition exists to prevent.
+   *
+   * `contentVersion` is undefined when the platform sent no usable ETag (an
+   * older deployment). A caller that needs a guarded write should treat that as
+   * "unknown" rather than substituting a guess.
+   */
+  async downloadContentWithVersion(fileId, jwtToken) {
     const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
     const url = `${baseUrl}/project/v1/files/${fileId}`;
     const response = await fetch(url, {
@@ -1458,14 +1638,13 @@ var HttpFileClient = class {
       }
     });
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
-      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
-      throw new Error(
-        `HTTP ${response.status}: ${errorBody.message ?? "Download failed"}${details}`
-      );
+      await throwFromResponse(response, "Download failed");
     }
     const buffer = await response.arrayBuffer();
-    return new Uint8Array(buffer);
+    return {
+      content: new Uint8Array(buffer),
+      contentVersion: parseVersionETag(response.headers.get("ETag"))
+    };
   }
   async listFiles(projectId, jwtToken, opts) {
     const queryParams = new URLSearchParams();
@@ -1572,11 +1751,7 @@ var HttpFileClient = class {
       }
     });
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
-      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
-      throw new Error(
-        `HTTP ${response.status}: ${errorBody.message ?? "Download failed"}${details}`
-      );
+      await throwFromResponse(response, "Download failed");
     }
     const buffer = await response.arrayBuffer();
     return new Uint8Array(buffer);
@@ -1840,7 +2015,7 @@ var PlatformClient = class {
     try {
       return await this.withTokenRetry((jwt, c) => c.attachment.getById(attachmentId, jwt));
     } catch (err) {
-      if (statusOf(err) === 404) {
+      if (statusOf2(err) === 404) {
         return null;
       }
       throw err;
@@ -1947,19 +2122,37 @@ var PlatformClient = class {
         jwt
       )
     );
-    await this.withTokenRetry(
-      (jwt, c) => c.file.uploadContent(initiated.fileId, args.content, jwt)
+    const written = await this.withTokenRetry(
+      (jwt, c) => c.file.uploadContent(initiated.fileId, args.content, jwt, {
+        // Phase 1 just set this file's version; Phase 2 must be based on it, or a
+        // second uploader racing us between the two phases silently wins the PUT.
+        ...initiated.contentVersion === void 0 ? {} : { expectedVersion: initiated.contentVersion },
+        actorKind: "ai"
+      })
     );
-    return this.getFileMetadata(initiated.fileId);
+    return withWrittenVersion(await this.getFileMetadata(initiated.fileId), written.contentVersion);
   }
   /**
    * Saves a new revision (overwrite) of an existing spec file by id. The
    * platform computes the checksum server-side. Returns the file's updated
    * metadata (including the bumped revision count).
+   *
+   * `expectedVersion` is the file's `contentVersion` as last read. The platform
+   * rejects the write with 409 if the file has moved past it, which is what stops
+   * an MCP overwrite from silently discarding an edit someone made in the webapp
+   * since. Omitting it is a blind write.
+   *
+   * The write is attributed to an AI actor: an MCP client is an assistant acting
+   * on the user's behalf, so a human editing the same file wins any race.
    */
-  async saveSpecFileRevision(fileId, content) {
-    await this.withTokenRetry((jwt, c) => c.file.saveManualRevision(fileId, content, jwt));
-    return this.getFileMetadata(fileId);
+  async saveSpecFileRevision(fileId, content, opts = {}) {
+    const written = await this.withTokenRetry(
+      (jwt, c) => c.file.saveManualRevision(fileId, content, jwt, {
+        ...opts.expectedVersion === void 0 ? {} : { expectedVersion: opts.expectedVersion },
+        actorKind: "ai"
+      })
+    );
+    return withWrittenVersion(await this.getFileMetadata(fileId), written.contentVersion);
   }
   /**
    * Finds a project's spec file by exact file_path, paging through the list.
@@ -2009,7 +2202,7 @@ var PlatformClient = class {
     try {
       return await call(jwt, clients);
     } catch (err) {
-      if (statusOf(err) === 401) {
+      if (statusOf2(err) === 401) {
         const refreshed = await this.tokenManager.forceRefresh();
         return await call(refreshed, clients);
       }
@@ -2020,7 +2213,10 @@ var PlatformClient = class {
 function sha256Prefixed(content) {
   return "sha256:" + createHash("sha256").update(content).digest("hex");
 }
-function statusOf(err) {
+function withWrittenVersion(meta, contentVersion) {
+  return contentVersion === void 0 ? meta : { ...meta, contentVersion };
+}
+function statusOf2(err) {
   if (typeof err !== "object" || err === null) {
     return void 0;
   }
@@ -2385,6 +2581,25 @@ var getProjectTool = {
 
 // src/server/tools/get_spec_file.ts
 import { z as z7 } from "zod";
+
+// src/server/tools/spec-file-output.ts
+function specFileSummary(file) {
+  return {
+    id: file.id,
+    project_id: file.projectId,
+    session_id: file.sessionId,
+    file_path: file.filePath,
+    file_type: file.fileType,
+    file_size_bytes: file.fileSizeBytes,
+    checksum: file.checksum,
+    revision_count: file.revisionCount,
+    ...file.contentVersion === void 0 ? {} : { content_version: file.contentVersion },
+    created_at: file.createdAt,
+    updated_at: file.updatedAt
+  };
+}
+
+// src/server/tools/get_spec_file.ts
 var inputSchema7 = {
   file_id: z7.string().min(1).describe("UUID of the file"),
   include_download_url: z7.number().int().nonnegative().optional().describe(
@@ -2397,18 +2612,7 @@ var getSpecFileTool = {
   inputSchema: inputSchema7,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
-    const base = {
-      id: meta.id,
-      project_id: meta.projectId,
-      session_id: meta.sessionId,
-      file_type: meta.fileType,
-      file_path: meta.filePath,
-      file_size_bytes: meta.fileSizeBytes,
-      checksum: meta.checksum,
-      revision_count: meta.revisionCount,
-      created_at: meta.createdAt,
-      updated_at: meta.updatedAt
-    };
+    const base = specFileSummary(meta);
     const requested = args.include_download_url ?? 0;
     if (requested <= 0) {
       return jsonResult(base);
@@ -2551,6 +2755,7 @@ var moveSpecFileToTrashTool = {
 
 // src/server/tools/read_spec_file.ts
 import { promises as fs3 } from "fs";
+import { createHash as createHash2 } from "crypto";
 import { z as z11 } from "zod";
 var MAX_READ_BYTES = 1 * 1024 * 1024;
 var inputSchema11 = {
@@ -2564,7 +2769,8 @@ var readSpecFileTool = {
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
-    if (targetRevision === meta.revisionCount && meta.fileSizeBytes > MAX_READ_BYTES) {
+    const isLatestRevision = targetRevision === meta.revisionCount;
+    if (isLatestRevision && meta.fileSizeBytes > MAX_READ_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, meta.fileSizeBytes));
     }
     const cacheRoot = resolveDownloadRoot();
@@ -2581,11 +2787,11 @@ var readSpecFileTool = {
         `read_spec_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
       );
     }
+    const cached = await pathExists(cachePath) ? await fs3.readFile(cachePath) : null;
+    const cacheHit = cached !== null && (!isLatestRevision || sha256Prefixed2(cached) === meta.checksum);
     let bytes;
-    let cacheHit = false;
-    if (await pathExists(cachePath)) {
-      bytes = await fs3.readFile(cachePath);
-      cacheHit = true;
+    if (cacheHit) {
+      bytes = cached;
     } else {
       const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
       bytes = downloaded.bytes;
@@ -2613,6 +2819,12 @@ var readSpecFileTool = {
     return jsonResult({
       file_id: meta.id,
       revision_number: targetRevision,
+      // Pass this back as update_spec_file's expected_version so an edit made by
+      // someone else since this read is reported instead of overwritten. It
+      // describes the file's CURRENT content, so it is emitted only when that is
+      // what was read — beside a historical revision it would invite an update
+      // that overwrites everything written since.
+      ...isLatestRevision && meta.contentVersion !== void 0 ? { content_version: meta.contentVersion } : {},
       file_path: meta.filePath,
       file_type: meta.fileType,
       cache_path: maskHomedir(cachePath),
@@ -2632,6 +2844,9 @@ function isBinary(bytes) {
   }
   return false;
 }
+function sha256Prefixed2(content) {
+  return "sha256:" + createHash2("sha256").update(content).digest("hex");
+}
 
 // src/server/tools/restore_spec_file_from_trash.ts
 import { z as z12 } from "zod";
@@ -2754,22 +2969,6 @@ async function resolveSpecContent(input, maxBytes = MAX_LOCAL_SPEC_FILE_BYTES) {
   return { bytes: new Uint8Array(raw) };
 }
 
-// src/server/tools/spec-file-output.ts
-function specFileSummary(file) {
-  return {
-    id: file.id,
-    project_id: file.projectId,
-    session_id: file.sessionId,
-    file_path: file.filePath,
-    file_type: file.fileType,
-    file_size_bytes: file.fileSizeBytes,
-    checksum: file.checksum,
-    revision_count: file.revisionCount,
-    created_at: file.createdAt,
-    updated_at: file.updatedAt
-  };
-}
-
 // src/server/tools/update_spec_file.ts
 var inputSchema15 = {
   file_id: z15.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
@@ -2780,11 +2979,14 @@ var inputSchema15 = {
   ),
   local_file_path: z15.string().min(1).optional().describe(
     "Path to a local file whose bytes become the new revision; the server reads it directly. Provide this OR content (exactly one). Absolute paths are most reliable; a relative path resolves against the MCP server working directory. Point this only at an intended spec file \u2014 its bytes are uploaded to the project as-is; never use it for secrets or unrelated files."
+  ),
+  expected_version: z15.number().int().nonnegative().optional().describe(
+    "The content_version the new body was based on, from the get_spec_file or read_spec_file you worked from. The update is rejected with an actionable error if someone else changed the file since. Omit only when overwriting unconditionally is genuinely intended \u2014 the project may be configured to reject unversioned updates."
   )
 };
 var updateSpecFileTool = {
   name: "update_spec_file",
-  description: "Overwrite an existing spec file by saving a new revision. Provide the new body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly); use `content` for text generated in-memory. Reference the file by file_id or by (project_id + file_path).",
+  description: "Overwrite an existing spec file by saving a new revision. Provide the new body inline via `content` or by pointing at a local file with `local_file_path` \u2014 exactly one is required. Prefer `local_file_path` when the body is already an existing local file (the server reads it directly); use `content` for text generated in-memory. Reference the file by file_id or by (project_id + file_path). Pass `expected_version` from the get_spec_file you based the new body on so a concurrent edit by someone else is reported instead of silently overwritten.",
   inputSchema: inputSchema15,
   handler: async (args, ctx) => {
     const resolved = await resolveSpecContent({
@@ -2794,13 +2996,13 @@ var updateSpecFileTool = {
     if (resolved.error || !resolved.bytes) {
       return errorResult(resolved.error ?? "Failed to resolve file content.");
     }
-    let fileId;
+    let target;
     if (args.file_id) {
       const meta = await ctx.client.getFileMetadata(args.file_id).catch(() => null);
       if (!meta) {
         return errorResult(`No spec file found with id ${args.file_id}.`);
       }
-      fileId = meta.id;
+      target = meta;
     } else if (args.project_id && args.file_path) {
       const match = await ctx.client.findSpecFileByPath(args.project_id, args.file_path);
       if (!match) {
@@ -2808,17 +3010,46 @@ var updateSpecFileTool = {
           `No spec file found at ${args.file_path} in project ${args.project_id}.`
         );
       }
-      fileId = match.id;
+      target = match;
     } else {
       return errorResult("Provide either file_id, or both project_id and file_path.");
     }
-    const file = await ctx.client.saveSpecFileRevision(fileId, resolved.bytes);
-    return jsonResult({ file: specFileSummary(file) });
+    const expectedVersion = args.expected_version;
+    try {
+      const file = await ctx.client.saveSpecFileRevision(target.id, resolved.bytes, {
+        ...expectedVersion === void 0 ? {} : { expectedVersion }
+      });
+      return jsonResult({ file: specFileSummary(file) });
+    } catch (err) {
+      if (isPlatformPreconditionRequiredError(err)) {
+        return errorResult(
+          `${target.filePath} was NOT updated: this project requires every update to declare the version it was based on. Read the file with get_spec_file (or read_spec_file), then call update_spec_file again passing its content_version as expected_version.`
+        );
+      }
+      const conflict = conflictOf(err);
+      if (!conflict || !isVersionRace(conflict)) {
+        throw err;
+      }
+      return errorResult(conflictMessage(target.filePath, conflict));
+    }
   }
 };
+function isVersionRace(conflict) {
+  return conflict.reason === "revision_mismatch" || conflict.reason === "unknown";
+}
+function conflictMessage(filePath, conflict) {
+  const who = conflict.changedByKind === "ai" ? "an AI session" : (
+    // changedBy is a user id, not a display name — attribute, do not name.
+    conflict.changedBy ? `another user (id ${conflict.changedBy})` : "someone else"
+  );
+  const when = conflict.changedAt ? ` at ${conflict.changedAt}` : "";
+  const rev = conflict.currentRevision === void 0 ? "" : ` It is now at revision ${String(conflict.currentRevision)}.`;
+  const version = conflict.currentVersion === void 0 ? "" : ` (It was at version ${String(conflict.currentVersion)} when your write was rejected.)`;
+  return `${filePath} was NOT updated: ${who} changed it${when} since you read it.${rev} Their version was kept \u2014 nothing of theirs was overwritten. Re-read the file with get_spec_file (or read_spec_file), decide how your change should combine with theirs, then update again passing the content_version that re-read returns as expected_version.${version} Do not simply resend the same content \u2014 you would undo their work.`;
+}
 
 // src/server/tools/upload_attachment.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { lstat, readFile as readFile2 } from "fs/promises";
 import { basename, extname, isAbsolute as isAbsolute2 } from "path";
 import { z as z16 } from "zod";
@@ -2994,7 +3225,7 @@ var uploadAttachmentTool = {
     }
     const fileName = args.file_name ?? basename(args.file_path);
     const mimeType = args.mime_type ?? inferMimeFromName(fileName);
-    const checksum = `sha256:${createHash2("sha256").update(buf).digest("hex")}`;
+    const checksum = `sha256:${createHash3("sha256").update(buf).digest("hex")}`;
     const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     const existing = await ctx.client.listAttachments(args.project_id);
     const nameMatches = existing.filter((a) => a.name === fileName);
@@ -3415,7 +3646,7 @@ function ripgrepIgnoreGlobs() {
 }
 
 // src/reverse/pack-codebase.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { mkdtemp, readFile as readFile3, rm } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -3542,7 +3773,7 @@ function computeOutputId(inputs) {
     i: inputs.includePatterns ?? "",
     x: inputs.ignorePatterns ?? ""
   });
-  const digest = createHash3("sha256").update(payload).digest("hex").slice(0, 12);
+  const digest = createHash4("sha256").update(payload).digest("hex").slice(0, 12);
   return `pack-${digest}`;
 }
 function readPage(cache, outputId, page) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.1.5-next.62",
+  "version": "0.1.5-next.63",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {