@myspec/mcp-server 0.3.0-next.90 → 0.4.0-next.100

package/dist/index.js

@@ -255,6 +255,7 @@ async function exchangeCode(userAuthUrl, code, fetchImpl) {
 }
 
 // src/auth/credentials-store.ts
+import { randomUUID } from "crypto";
 import { promises as fs } from "fs";
 import os from "os";
 import path from "path";
@@ -359,15 +360,26 @@ async function loadSettings(target) {
     throw err;
   }
 }
+async function readSettingsUserAuthUrl(settingsPath = defaultSettingsPath()) {
+  const settings = await loadSettings(settingsPath);
+  return settings?.userAuthUrl;
+}
 async function writeJsonFile(target, data, opts) {
   const dir = path.dirname(target);
   await fs.mkdir(dir, { recursive: true, mode: 448 });
   if (process.platform !== "win32") {
     await fs.chmod(dir, 448);
   }
-  await fs.writeFile(target, JSON.stringify(data, null, 2), { mode: 384 });
-  if (opts.secret && process.platform !== "win32") {
-    await fs.chmod(target, 384);
+  const tmp = `${target}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2), { mode: 384 });
+    if (opts.secret && process.platform !== "win32") {
+      await fs.chmod(tmp, 384);
+    }
+    await fs.rename(tmp, target);
+  } catch (err) {
+    await unlinkIfExists(tmp);
+    throw err;
   }
 }
 async function unlinkIfExists(target) {
@@ -584,6 +596,37 @@ var TokenManager = class {
   now;
   cached = null;
   refreshInFlight = null;
+  /**
+   * The in-flight disk read, shared by every concurrent caller.
+   *
+   * `refresh` below has always deduped; this did not, so N concurrent platform
+   * calls each issued their own `store.load()` before any of them populated
+   * `cached`. That is N redundant reads on every cold call, and it is what made
+   * a torn read reachable at all: one caller could be refreshing (and so
+   * rewriting the credential files) while the others were still reading them.
+   *
+   * The atomic write in credentials-store.ts is the real guarantee. This is the
+   * other half — it removes the redundant reads rather than merely surviving
+   * them.
+   */
+  loadInFlight = null;
+  /**
+   * Bumped by clear(), so a read that started before it cannot publish its
+   * result to `cached` afterwards.
+   *
+   * Scope, precisely: the caller already awaiting that read still receives the
+   * pre-clear credentials as its own return value and proceeds with them —
+   * nothing can retract a value from a call already in flight. What the guard
+   * buys is that the value stops there instead of being cached, so no
+   * SUBSEQUENT caller is handed credentials the user asked us to forget.
+   *
+   * Dropping `loadInFlight` alone would not achieve even that: the awaiting
+   * caller resumes after the clear and would assign `cached` itself.
+   * Pre-existing — the old code assigned `cached` straight after an un-deduped
+   * `await` — but the fix belongs with the dedupe rather than left as a claim
+   * the comment cannot back up.
+   */
+  loadGeneration = 0;
   /**
    * Set once the exchange endpoint rejects the API token outright.
    *
@@ -616,17 +659,25 @@ var TokenManager = class {
   }
   async clear() {
     this.cached = null;
+    this.loadInFlight = null;
+    this.loadGeneration += 1;
     await this.store.clear();
   }
   async ensureLoaded() {
     if (this.cached) {
       return this.cached;
     }
-    const loaded = await this.store.load();
+    const generation = this.loadGeneration;
+    this.loadInFlight ??= this.store.load().finally(() => {
+      this.loadInFlight = null;
+    });
+    const loaded = await this.loadInFlight;
     if (!loaded) {
       throw new NeedsLoginError();
     }
-    this.cached = loaded;
+    if (generation === this.loadGeneration) {
+      this.cached = loaded;
+    }
     return loaded;
   }
   async refresh(creds) {
@@ -679,7 +730,7 @@ var TokenManager = class {
     if (response.status === 401 || response.status === 403) {
       const reason = response.status === 403 ? "the token owner no longer has access to its organization" : "the token is invalid, disabled, or expired";
       const rejection = new ApiTokenRejectedError(
-        `API token exchange failed: ${reason}. Create a new API token in MySpec and set it as MYSPEC_API_TOKEN (or write it to the apiToken field of your credentials file).`
+        `API token exchange failed at ${url}: ${reason}. Check that URL names the environment the token was created in. With MYSPEC_API_TOKEN it comes from MYSPEC_USER_AUTH_URL (or --user-auth-url), then userAuthUrl in ~/.myspec/settings.json, defaulting to https://auth.myspec.dev; with an apiToken in oauth_creds.json it comes from that settings.json value alone, which only \`npx @myspec/mcp-server login --user-auth-url <url>\` rewrites. If the host is right, create a new API token in MySpec and set it as MYSPEC_API_TOKEN (or write it to the apiToken field of your credentials file).`
       );
       this.apiTokenRejection = rejection;
       throw rejection;
@@ -689,7 +740,7 @@ var TokenManager = class {
       throw new HttpStatusError(
         response.status,
         body,
-        `Token exchange failed: ${url} returned 404, so no exchange endpoint is there. Check that URL names the environment the token was created in. With MYSPEC_API_TOKEN it comes from MYSPEC_USER_AUTH_URL (or --user-auth-url), defaulting to https://auth.myspec.dev. Otherwise it comes from userAuthUrl in ~/.myspec/settings.json, which only \`npx @myspec/mcp-server login --user-auth-url <url>\` rewrites \u2014 the flag and the variable do not redirect a file-configured exchange on their own, and userAuthUrl in oauth_creds.json is ignored entirely.`
+        `Token exchange failed: ${url} returned 404, so no exchange endpoint is there. Check that URL names the environment the token was created in. With MYSPEC_API_TOKEN it comes from MYSPEC_USER_AUTH_URL (or --user-auth-url), then userAuthUrl in ~/.myspec/settings.json, defaulting to https://auth.myspec.dev. Otherwise it comes from that same settings.json value, which only \`npx @myspec/mcp-server login --user-auth-url <url>\` rewrites \u2014 the flag and the variable do not redirect a file-configured exchange on their own, and userAuthUrl in oauth_creds.json is ignored entirely.`
       );
     }
     if (!response.ok) {
@@ -1333,6 +1384,26 @@ var PlatformPreconditionRequiredError = class extends PlatformHttpError {
     this.name = "PlatformPreconditionRequiredError";
   }
 };
+var QUOTA_EXCEEDED_CODE = "quota_exceeded";
+var PlatformQuotaError = class extends PlatformHttpError {
+  /** The platform's machine-readable code, e.g. `quota_exceeded`. */
+  code;
+  constructor(message, status, details, code) {
+    super(message, status, details);
+    this.name = "PlatformQuotaError";
+    this.code = code;
+  }
+};
+function isPlatformQuotaError(err) {
+  if (statusOf(err) !== 429) {
+    return false;
+  }
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+  const code = err.code;
+  return typeof code === "string" && code.toLowerCase() === QUOTA_EXCEEDED_CODE;
+}
 function isPlatformHttpError(err) {
   return typeof err === "object" && err !== null && err[PLATFORM_ERROR_BRAND] === true;
 }
@@ -1409,13 +1480,16 @@ function toConflictDetails(details) {
     changedAt: stringField(details, "last_modified_at")
   };
 }
-function createPlatformError(message, status, details) {
+function createPlatformError(message, status, details, code) {
   if (status === 409) {
     return new PlatformConflictError(message, status, details, toConflictDetails(details));
   }
   if (status === 428) {
     return new PlatformPreconditionRequiredError(message, details);
   }
+  if (status === 429 && typeof code === "string" && code.toLowerCase() === QUOTA_EXCEEDED_CODE) {
+    return new PlatformQuotaError(message, status, details, code.toLowerCase());
+  }
   return new PlatformHttpError(message, status, details);
 }
 function truncate(text) {
@@ -1426,17 +1500,19 @@ async function throwFromResponse(response, fallbackMessage) {
   const rawBody = await response.text().catch(() => "");
   let message = fallbackMessage;
   let details;
+  let code;
   if (rawBody) {
     try {
       const parsed = JSON.parse(rawBody);
       details = parsed.details;
+      code = typeof parsed.error === "string" ? parsed.error : void 0;
       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);
+  throw createPlatformError(`HTTP ${response.status}: ${message}`, response.status, details, code);
 }
 
 // ../../packages/shared/logger.ts
@@ -1644,6 +1720,10 @@ var BaseHttpClient = class {
       this.logger.debug("Retrying after abort/timeout", { error: error.message });
       return true;
     }
+    if (isPlatformQuotaError(error)) {
+      this.logger.debug("Not retrying quota rejection", { status: 429 });
+      return false;
+    }
     const httpError = error;
     if (httpError.status !== void 0) {
       const shouldRetry = RETRYABLE_STATUS_CODES.includes(httpError.status);
@@ -1700,6 +1780,9 @@ function transformSpecFileResponse(raw) {
     deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
   };
 }
+function toRevisionAuthorKind(raw) {
+  return raw === "ai" ? "ai" : "human";
+}
 function transformFileRevisionResponse(raw) {
   return {
     id: raw.id,
@@ -1710,6 +1793,7 @@ function transformFileRevisionResponse(raw) {
     fileSizeBytes: raw.file_size_bytes,
     checksum: raw.checksum,
     changedBy: raw.changed_by,
+    changedByKind: toRevisionAuthorKind(raw.changed_by_kind),
     createdAt: new Date(raw.created_at)
   };
 }
@@ -2387,6 +2471,32 @@ var PlatformClient = class {
     };
     return this.withTokenRetry((jwt, c) => c.session.listSpecSessions(projectId, jwt, merged));
   }
+  async getSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.getSpecSession(sessionId, jwt));
+  }
+  /**
+   * Writes ONLY the session's `context` field (rename's read-merge-write).
+   * Deliberately narrow: status, chatHistory and the counters stay
+   * unreachable from the MCP surface. The platform permits context-only
+   * updates on archived sessions, so rename works there too.
+   */
+  async updateSpecSessionContext(sessionId, context) {
+    return this.withTokenRetry((jwt, c) => c.session.updateSpecSession(sessionId, { context }, jwt));
+  }
+  /** Idempotent: re-archiving keeps the original archivedAt. */
+  async archiveSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.archiveSpecSession(sessionId, jwt));
+  }
+  async unarchiveSpecSession(sessionId) {
+    return this.withTokenRetry((jwt, c) => c.session.unarchiveSpecSession(sessionId, jwt));
+  }
+  /**
+   * Soft-deletes a spec session. The platform rejects this unless the session
+   * is already archived, surfacing a validation error the caller reports.
+   */
+  async deleteSpecSession(sessionId) {
+    await this.withTokenRetry((jwt, c) => c.session.deleteSpecSession(sessionId, jwt));
+  }
   async listFiles(projectId, opts = {}) {
     return this.withTokenRetry((jwt, c) => c.file.listFiles(projectId, jwt, opts));
   }
@@ -2660,6 +2770,14 @@ function jsonResult(value) {
 function errorResult(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
+function imageResult(dataBase64, mimeType, metadata) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(metadata, null, 2) },
+      { type: "image", data: dataBase64, mimeType }
+    ]
+  };
+}
 
 // src/server/tools/archive_project.ts
 import { z } from "zod";
@@ -2691,16 +2809,63 @@ var archiveProjectTool = {
   }
 };
 
-// src/server/tools/create_project.ts
+// src/server/tools/archive_spec_session.ts
 import { z as z2 } from "zod";
+
+// src/server/tools/session-output.ts
+function sessionNotFound(err, sessionId) {
+  return statusOf(err) === 404 ? errorResult(`Session ${sessionId} not found.`) : null;
+}
+function sessionMetadata(s) {
+  return {
+    id: s.id,
+    project_id: s.projectId,
+    org: s.org,
+    user_id: s.userId,
+    status: s.status,
+    message_count: s.messageCount,
+    token_count: s.tokenCount,
+    started_at: s.startedAt,
+    completed_at: s.completedAt ?? null,
+    archived_at: s.archivedAt ?? null,
+    created_at: s.createdAt,
+    updated_at: s.updatedAt
+  };
+}
+
+// src/server/tools/archive_spec_session.ts
 var inputSchema2 = {
-  name: z2.string().describe("Name of the project to create."),
-  description: z2.string().optional().describe("Optional project description.")
+  session_id: z2.string().min(1).describe("UUID of the spec session to archive")
+};
+var archiveSpecSessionTool = {
+  name: "archive_spec_session",
+  description: "Archive a spec session. Archiving is the confirmation step required before delete_spec_session, and is reversible via unarchive_spec_session. Idempotent: archiving an already-archived session succeeds and keeps the original archived_at.",
+  inputSchema: inputSchema2,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.archiveSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ session: sessionMetadata(session) });
+  }
+};
+
+// src/server/tools/create_project.ts
+import { z as z3 } from "zod";
+var inputSchema3 = {
+  name: z3.string().describe("Name of the project to create."),
+  description: z3.string().optional().describe("Optional project description.")
 };
 var createProjectTool = {
   name: "create_project",
   description: "Create a new project. Returns the created project id and metadata.",
-  inputSchema: inputSchema2,
+  inputSchema: inputSchema3,
   handler: async (args, ctx) => {
     const name = args.name.trim();
     if (name === "") {
@@ -2715,14 +2880,14 @@ var createProjectTool = {
 };
 
 // src/server/tools/delete_project.ts
-import { z as z3 } from "zod";
-var inputSchema3 = {
-  project_id: z3.string().min(1).describe("UUID of the project to delete.")
+import { z as z4 } from "zod";
+var inputSchema4 = {
+  project_id: z4.string().min(1).describe("UUID of the project to delete.")
 };
 var deleteProjectTool = {
   name: "delete_project",
   description: "Soft-delete a project. Only a project that is already archived can be deleted. If the project is still active, this tool refuses and you must NOT archive it on the user's behalf to make the deletion go through \u2014 instead, reconfirm with the user whether deleting the project is truly intended.",
-  inputSchema: inputSchema3,
+  inputSchema: inputSchema4,
   handler: async (args, ctx) => {
     let status;
     try {
@@ -2747,9 +2912,38 @@ var deleteProjectTool = {
   }
 };
 
+// src/server/tools/delete_spec_session.ts
+import { z as z5 } from "zod";
+var inputSchema5 = {
+  session_id: z5.string().min(1).describe("UUID of the spec session to delete")
+};
+var deleteSpecSessionTool = {
+  name: "delete_spec_session",
+  description: "Soft-delete a spec session. Only an ARCHIVED session can be deleted \u2014 archive it first with archive_spec_session. This tool never archives on your behalf: archiving is the user's confirmation step, and collapsing the two-step destructive flow would remove the only checkpoint the platform provides. Check archived_at via get_spec_session to see whether delete is permitted.",
+  inputSchema: inputSchema5,
+  handler: async (args, ctx) => {
+    try {
+      await ctx.client.deleteSpecSession(args.session_id);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (/must be archived/i.test(message)) {
+        return errorResult(
+          `Session ${args.session_id} was NOT deleted: session must be archived before it can be deleted. Archive it first with archive_spec_session \u2014 after reconfirming with the user that deleting this session is intended.`
+        );
+      }
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ deleted: true, session_id: args.session_id });
+  }
+};
+
 // src/server/tools/download_spec_file.ts
 import path3 from "path";
-import { z as z4 } from "zod";
+import { z as z6 } from "zod";
 
 // src/server/download-path.ts
 import { randomBytes as randomBytes2 } from "crypto";
@@ -2883,18 +3077,18 @@ async function writeBytesAtomically(target, bytes) {
 
 // src/server/tools/download_spec_file.ts
 var MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
-var inputSchema4 = {
-  file_id: z4.string().min(1).describe("UUID of the file"),
-  revision: z4.number().int().positive().optional().describe("Specific revision number to download (defaults to the latest revision)."),
-  destination_path: z4.string().min(1).optional().describe(
+var inputSchema6 = {
+  file_id: z6.string().min(1).describe("UUID of the file"),
+  revision: z6.number().int().positive().optional().describe("Specific revision number to download (defaults to the latest revision)."),
+  destination_path: z6.string().min(1).optional().describe(
     "Local path to save the file to. Optional: omit it to save the file under `.specs/` in the MCP server's working directory, mirroring its remote path (`specs/add-oauth/proposal.md` \u2192 `.specs/add-oauth/proposal.md`). When given, it is absolute or relative to that working directory; a relative path rooted at `specs/` is redirected to `.specs/`, so pass an absolute path to save into a literal `specs/` directory. If it points to an existing directory (or ends with a path separator), the spec file's basename is appended."
   ),
-  overwrite: z4.boolean().optional().describe("Overwrite the destination file if it already exists (default: false).")
+  overwrite: z6.boolean().optional().describe("Overwrite the destination file if it already exists (default: false).")
 };
 var downloadSpecFileTool = {
   name: "download_spec_file",
   description: "Download a spec file's raw bytes to a local file. By default it lands under `.specs/` in the MCP server's working directory, mirroring the file's remote path \u2014 pass `destination_path` only to save it somewhere else. Unlike read_spec_file, this handles binary files and files up to 50 MiB, and the response returns only metadata (saved path, size, revision) \u2014 not the content. Use it to save a large or binary file locally, then search or read it in chunks with other tools.",
-  inputSchema: inputSchema4,
+  inputSchema: inputSchema6,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
@@ -2992,15 +3186,15 @@ function buildOversizeMessage(fileId, byteLength) {
 }
 
 // src/server/tools/get_attachment.ts
-import { z as z5 } from "zod";
-var inputSchema5 = {
-  attachment_id: z5.string().min(1).describe("UUID of the attachment"),
-  include_download_url: z5.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
+import { z as z7 } from "zod";
+var inputSchema7 = {
+  attachment_id: z7.string().min(1).describe("UUID of the attachment"),
+  include_download_url: z7.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
 };
 var getAttachmentTool = {
   name: "get_attachment",
   description: "Get attachment metadata. With `include_download_url>0`, also returns a signed `download_url`.",
-  inputSchema: inputSchema5,
+  inputSchema: inputSchema7,
   handler: async (args, ctx) => {
     const attachment = await ctx.client.getAttachmentMetadata(args.attachment_id);
     if (!attachment) {
@@ -3029,14 +3223,14 @@ var getAttachmentTool = {
 };
 
 // src/server/tools/get_project.ts
-import { z as z6 } from "zod";
-var inputSchema6 = {
-  project_id: z6.string().min(1).describe("UUID of the project to fetch")
+import { z as z8 } from "zod";
+var inputSchema8 = {
+  project_id: z8.string().min(1).describe("UUID of the project to fetch")
 };
 var getProjectTool = {
   name: "get_project",
   description: "Get details for a project including all active spec sessions, files (id + metadata), and attachments (id + metadata).",
-  inputSchema: inputSchema6,
+  inputSchema: inputSchema8,
   handler: async (args, ctx) => {
     const [project, sessions, files, attachments] = await Promise.all([
       ctx.client.getProject(args.project_id),
@@ -3082,7 +3276,7 @@ var getProjectTool = {
 };
 
 // src/server/tools/get_spec_file.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 
 // src/server/tools/spec-file-output.ts
 function specFileSummary(file) {
@@ -3102,16 +3296,16 @@ function specFileSummary(file) {
 }
 
 // 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(
+var inputSchema9 = {
+  file_id: z9.string().min(1).describe("UUID of the file"),
+  include_download_url: z9.number().int().nonnegative().optional().describe(
     "Revision number to include a download URL for. Returns a signed, time-limited URL for that revision (latest or historical) that needs no credentials. Omit or 0 to skip."
   )
 };
 var getSpecFileTool = {
   name: "get_spec_file",
   description: "Get spec file metadata. With `include_download_url=N`, also returns a signed, time-limited download URL for revision N (latest or historical). The URL is self-authenticating, so no credentials are returned.",
-  inputSchema: inputSchema7,
+  inputSchema: inputSchema9,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const base = specFileSummary(meta);
@@ -3135,19 +3329,209 @@ var getSpecFileTool = {
   }
 };
 
+// src/server/tools/get_spec_session.ts
+import { z as z10 } from "zod";
+
+// src/util/bytes.ts
+function encodeBase64(bytes) {
+  const CHUNK = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+function isBinary(bytes) {
+  return bytes.includes(0);
+}
+function decodeUtf8Strict(bytes) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function utf8ByteLength(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+// src/server/session-context.ts
+var MAX_CONTEXT_RESPONSE_BYTES = 1 * 1024 * 1024;
+var SESSION_SUMMARY_MAX_LENGTH = 500;
+function jsonTypeOf(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return t;
+  }
+  return "object";
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function introspectContext(context) {
+  if (context === null || context === void 0) {
+    return { session_summary: null, context_size_bytes: 0, context_keys: [] };
+  }
+  const sizeBytes = contextSizeBytes(context);
+  if (!isPlainObject(context)) {
+    const type = jsonTypeOf(context);
+    return {
+      session_summary: null,
+      context_size_bytes: sizeBytes,
+      context_keys: [],
+      ...type !== "object" && type !== "null" ? { context_type: type } : {}
+    };
+  }
+  const summary = context.sessionSummary;
+  return {
+    session_summary: typeof summary === "string" ? summary : null,
+    context_size_bytes: sizeBytes,
+    context_keys: Object.entries(context).map(([key, value]) => ({
+      key,
+      size_bytes: value === void 0 ? 0 : utf8ByteLength(JSON.stringify(value))
+    }))
+  };
+}
+function contextSizeBytes(context) {
+  if (context === null || context === void 0) {
+    return 0;
+  }
+  return utf8ByteLength(JSON.stringify(context));
+}
+function mergeSessionSummary(context, sessionSummary) {
+  if (context === null || context === void 0) {
+    return { ok: true, context: { sessionSummary } };
+  }
+  if (isPlainObject(context)) {
+    return { ok: true, context: { ...context, sessionSummary } };
+  }
+  return { ok: false, actualType: jsonTypeOf(context) };
+}
+
+// src/server/tools/get_spec_session.ts
+var inputSchema10 = {
+  session_id: z10.string().min(1).describe("UUID of the spec session"),
+  include_context: z10.boolean().optional().describe(
+    "When true, include the whole context JSONB (subject to a 1 MiB ceiling \u2014 above it the tool errors with the actual size). Default false: the response instead carries context_size_bytes and context_keys so you can see the size and shape before asking."
+  )
+};
+var getSpecSessionTool = {
+  name: "get_spec_session",
+  description: "Get one spec session's metadata: status, counters, timestamps, archived_at (delete eligibility), session_summary, plus context_size_bytes and context_keys describing the context without returning it. Set include_context=true for the full context (1 MiB ceiling). The chat transcript is never returned.",
+  inputSchema: inputSchema10,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.getSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    const summary = introspectContext(session.context);
+    const base = {
+      ...sessionMetadata(session),
+      session_summary: summary.session_summary,
+      context_size_bytes: summary.context_size_bytes,
+      context_keys: summary.context_keys,
+      ...summary.context_type === void 0 ? {} : { context_type: summary.context_type }
+    };
+    if (args.include_context !== true) {
+      return jsonResult(base);
+    }
+    const size = contextSizeBytes(session.context);
+    if (size > MAX_CONTEXT_RESPONSE_BYTES) {
+      return errorResult(
+        `Session ${session.id} context is ${String(size)} bytes, above the ${String(MAX_CONTEXT_RESPONSE_BYTES)}-byte include_context ceiling. Structured JSON is not truncated; use context_keys to locate what you need, or read the session in the MySpec webapp.`
+      );
+    }
+    return jsonResult({ ...base, context: session.context ?? null });
+  }
+};
+
+// src/server/tools/list_attachments.ts
+import { z as z11 } from "zod";
+
+// src/util/list-paging.ts
+function clampLimit(limit, defaultLimit, maxLimit) {
+  const requested = limit ?? defaultLimit;
+  return Math.min(Math.max(1, requested), maxLimit);
+}
+function sliceWindow(items, limit, offset) {
+  const total = items.length;
+  const start = Math.min(Math.max(0, offset), total);
+  const slice = items.slice(start, start + limit);
+  const end = start + slice.length;
+  return {
+    items: [...slice],
+    total,
+    limit,
+    offset: start,
+    ...end < total ? { next_offset: end } : {}
+  };
+}
+function nextOffsetOf(offset, returned, total) {
+  const end = offset + returned;
+  return end < total ? end : void 0;
+}
+
+// src/server/tools/list_attachments.ts
+var LIST_DEFAULT = 50;
+var LIST_MAX = 200;
+var inputSchema11 = {
+  project_id: z11.string().min(1).describe("UUID of the project whose attachments to list."),
+  limit: z11.number().int().positive().optional().describe(
+    `Max attachments to return (default ${String(LIST_DEFAULT)}, capped at ${String(LIST_MAX)}).`
+  ),
+  offset: z11.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+};
+var listAttachmentsTool = {
+  name: "list_attachments",
+  description: "List a project's attachments (metadata only, always including file_size_bytes so a caller can check the size before read_attachment). Returns `total` and, when more records remain, `next_offset`.",
+  inputSchema: inputSchema11,
+  handler: async (args, ctx) => {
+    const all = await ctx.client.listAttachments(args.project_id);
+    const limit = clampLimit(args.limit, LIST_DEFAULT, LIST_MAX);
+    const window = sliceWindow(all, limit, args.offset ?? 0);
+    return jsonResult({
+      project_id: args.project_id,
+      attachments: window.items.map((a) => ({
+        id: a.id,
+        name: a.name,
+        mime_type: a.mimeType,
+        file_size_bytes: a.fileSizeBytes,
+        checksum: a.checksum,
+        created_at: a.createdAt
+      })),
+      total: window.total,
+      limit: window.limit,
+      offset: window.offset,
+      ...window.next_offset === void 0 ? {} : { next_offset: window.next_offset }
+    });
+  }
+};
+
 // src/server/tools/list_projects.ts
-import { z as z8 } from "zod";
-var inputSchema8 = {
-  query: z8.string().optional().describe(
+import { z as z12 } from "zod";
+var inputSchema12 = {
+  query: z12.string().optional().describe(
     "Search term to filter projects by name. Omit to list all projects."
   ),
-  limit: z8.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
-  offset: z8.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+  limit: z12.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
+  offset: z12.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
 };
 var listProjectsTool = {
   name: "list_projects",
   description: "List or search MySpec projects accessible to the authenticated user.",
-  inputSchema: inputSchema8,
+  inputSchema: inputSchema12,
   handler: async (args, ctx) => {
     const result = await ctx.client.listProjects({
       query: args.query,
@@ -3170,21 +3554,21 @@ var listProjectsTool = {
 };
 
 // src/server/tools/list_spec_file.ts
-import { z as z9 } from "zod";
+import { z as z13 } from "zod";
 var PAGE_SIZE = 100;
-var inputSchema9 = {
-  project_id: z9.string().min(1).describe("UUID of the project whose spec files to list."),
-  path: z9.string().optional().describe(
+var inputSchema13 = {
+  project_id: z13.string().min(1).describe("UUID of the project whose spec files to list."),
+  path: z13.string().optional().describe(
     'Directory prefix to filter by, e.g. ".spec" or ".spec/design". Matches the exact file and everything under that directory. Pass "", "/", or omit to list all files.'
   ),
-  trashed: z9.boolean().optional().describe(
+  trashed: z13.boolean().optional().describe(
     "When true, list files in the project Trash Bin instead. When false or omitted, list only live files (trashed files excluded)."
   )
 };
 var listSpecFileTool = {
   name: "list_spec_file",
   description: 'List a project\'s spec files with id, path, and metadata (revision count, file size of the latest revision, file type, owning session, last update). Filter to a directory with `path` (exact file or everything under it; pass "", "/", or omit for all). Set `trashed=true` to list files in the Trash Bin instead of live files.',
-  inputSchema: inputSchema9,
+  inputSchema: inputSchema13,
   handler: async (args, ctx) => {
     const trashed = args.trashed ?? false;
     const files = trashed ? await ctx.client.listTrashedFiles(args.project_id) : await listAllLiveFiles(ctx.client, args.project_id);
@@ -3240,34 +3624,255 @@ function isUnderPath(filePath, prefix) {
   return filePath === prefix || filePath.startsWith(prefix + "/");
 }
 
+// src/server/tools/list_spec_sessions.ts
+import { z as z14 } from "zod";
+var LIST_DEFAULT2 = 10;
+var LIST_MAX2 = 20;
+var inputSchema14 = {
+  project_id: z14.string().min(1).describe("UUID of the project whose spec sessions to list."),
+  archive_filter: z14.enum(["active", "archived", "all"]).optional().describe("Which sessions to list: 'active' (default), 'archived', or 'all'."),
+  status: z14.enum(["generating", "pending_input", "completed"]).optional().describe("Filter by session status."),
+  query: z14.string().optional().describe("Search term matched against the session summary."),
+  limit: z14.number().int().positive().optional().describe(
+    `Max sessions to return (default ${String(LIST_DEFAULT2)}, capped at ${String(LIST_MAX2)}).`
+  ),
+  offset: z14.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+};
+var listSpecSessionsTool = {
+  name: "list_spec_sessions",
+  description: `List a project's spec sessions (metadata plus session_summary and context_size_bytes \u2014 never the context itself or the chat transcript). Filter with archive_filter ('active'/'archived'/'all'), status, and query (searches the session summary). Capped at ${String(LIST_MAX2)} per page; returns \`total\` and \`next_offset\`.`,
+  inputSchema: inputSchema14,
+  handler: async (args, ctx) => {
+    const limit = clampLimit(args.limit, LIST_DEFAULT2, LIST_MAX2);
+    const offset = args.offset ?? 0;
+    const result = await ctx.client.listProjectSessions(args.project_id, {
+      archiveFilter: args.archive_filter ?? "active",
+      ...args.status === void 0 ? {} : { status: args.status },
+      ...args.query === void 0 ? {} : { query: args.query },
+      limit,
+      offset
+    });
+    const next = nextOffsetOf(offset, result.sessions.length, result.total);
+    return jsonResult({
+      project_id: args.project_id,
+      sessions: result.sessions.map((s) => {
+        const summary = introspectContext(s.context);
+        return {
+          ...sessionMetadata(s),
+          session_summary: summary.session_summary,
+          context_size_bytes: summary.context_size_bytes
+        };
+      }),
+      total: result.total,
+      limit,
+      offset,
+      ...next === void 0 ? {} : { next_offset: next }
+    });
+  }
+};
+
 // src/server/tools/move_spec_file_to_trash.ts
-import { z as z10 } from "zod";
-var inputSchema10 = {
-  file_id: z10.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
+import { z as z15 } from "zod";
+var inputSchema15 = {
+  file_id: z15.string().min(1).describe("UUID of the spec file to move to the Trash Bin.")
 };
 var moveSpecFileToTrashTool = {
   name: "move_spec_file_to_trash",
   description: "Move a spec file to the Trash Bin. This is recoverable \u2014 the file is hidden from the default file list and AI-agent tools but kept restorable indefinitely via `restore_spec_file_from_trash`. It is NOT a permanent delete.",
-  inputSchema: inputSchema10,
+  inputSchema: inputSchema15,
   handler: async (args, ctx) => {
     await ctx.client.trashFile(args.file_id);
     return jsonResult({ trashed: true, file_id: args.file_id });
   }
 };
 
+// src/server/tools/read_attachment.ts
+import { z as z16 } from "zod";
+
+// src/util/paginate-lines.ts
+var MAX_LINES_PER_CALL = 2e3;
+var MAX_RESPONSE_BYTES = 1 * 1024 * 1024;
+function normalizeNewlines(text) {
+  const withoutBom = text.startsWith("\uFEFF") ? text.slice(1) : text;
+  return withoutBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function splitIntoLines(text) {
+  const parts = text.split("\n");
+  if (parts.length > 0 && parts[parts.length - 1] === "") {
+    parts.pop();
+  }
+  return parts;
+}
+function truncateToBytes(value, maxBytes) {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= maxBytes) {
+    return value;
+  }
+  const decoded = new TextDecoder("utf-8").decode(encoded.subarray(0, maxBytes));
+  return decoded.replace(/�+$/, "");
+}
+function paginateText(text, offsetArg, limitArg) {
+  const lines = splitIntoLines(normalizeNewlines(text));
+  const totalLines = lines.length;
+  const rawOffset = offsetArg ?? 1;
+  const offset = rawOffset === 0 ? 1 : rawOffset;
+  if (offset < 1) {
+    return {
+      ok: false,
+      error: `Invalid offset ${String(rawOffset)}; offset is 1-based and must be >= 1.`
+    };
+  }
+  if (totalLines === 0) {
+    return {
+      ok: true,
+      window: {
+        content: "",
+        start_line: 1,
+        end_line: 0,
+        read_lines: 0,
+        total_lines: 0,
+        truncated: false
+      }
+    };
+  }
+  if (offset > totalLines) {
+    return {
+      ok: false,
+      error: `Offset ${String(rawOffset)} is past the end of the file (total ${String(totalLines)} lines).`
+    };
+  }
+  const effectiveLimit = Math.min(Math.max(1, limitArg ?? MAX_LINES_PER_CALL), MAX_LINES_PER_CALL);
+  const startIdx = offset - 1;
+  const lineWindowEnd = Math.min(startIdx + effectiveLimit, totalLines);
+  const out = [];
+  let usedBytes = 0;
+  let index = startIdx;
+  let byteCeilingHit = false;
+  for (; index < lineWindowEnd; index++) {
+    const line = lines[index] ?? "";
+    const lineBytes = utf8ByteLength(line);
+    const separatorBytes = out.length > 0 ? 1 : 0;
+    if (usedBytes + separatorBytes + lineBytes > MAX_RESPONSE_BYTES) {
+      if (out.length === 0) {
+        out.push(
+          `${truncateToBytes(line, MAX_RESPONSE_BYTES)}\u2026 [truncated, ${String(lineBytes)} bytes total]`
+        );
+      }
+      byteCeilingHit = true;
+      break;
+    }
+    usedBytes += separatorBytes + lineBytes;
+    out.push(line);
+  }
+  const endLine = startIdx + out.length;
+  const truncated = byteCeilingHit || endLine < totalLines;
+  return {
+    ok: true,
+    window: {
+      content: out.join("\n"),
+      start_line: offset,
+      end_line: endLine,
+      read_lines: out.length,
+      total_lines: totalLines,
+      truncated,
+      ...truncated && endLine < totalLines ? { next_offset: endLine + 1 } : {}
+    }
+  };
+}
+
+// src/server/tools/read_attachment.ts
+var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
+var IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp"
+]);
+var TEXT_MIME_TYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/xml",
+  "application/x-yaml",
+  "application/yaml",
+  "image/svg+xml"
+]);
+var GENERIC_MIME_TYPES = /* @__PURE__ */ new Set(["application/octet-stream", ""]);
+var inputSchema16 = {
+  attachment_id: z16.string().min(1).describe("UUID of the attachment to read"),
+  offset: z16.number().int().nonnegative().optional().describe(
+    "1-based line number to start reading from (text attachments only; default 1; 0 is an alias for 1)."
+  ),
+  limit: z16.number().int().positive().optional().describe("Max lines to return (text attachments only; default 2000, capped at 2000).")
+};
+var readAttachmentTool = {
+  name: "read_attachment",
+  description: `Return an attachment's content inline. UTF-8 text is paginated by line (offset/limit, 1 MiB per response). Images (png, jpeg, gif, webp) are returned whole as an MCP image block \u2014 never paginated \u2014 up to the ${String(MAX_ATTACHMENT_MB)} MiB attachment limit; a 10 MiB image is roughly 13.4 MiB of base64, so check file_size_bytes (from get_attachment or list_attachments) before reading a large one. Other binary types (pdf, docx, xlsx, \u2026) cannot be read here; view them in the MySpec webapp.`,
+  inputSchema: inputSchema16,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getAttachmentMetadata(args.attachment_id);
+    if (!meta) {
+      return errorResult(`Attachment ${args.attachment_id} not found.`);
+    }
+    const mime = meta.mimeType;
+    if (IMAGE_MIME_TYPES.has(mime)) {
+      if (meta.fileSizeBytes > MAX_ATTACHMENT_BYTES) {
+        return errorResult(
+          `Attachment ${meta.id} is ${String(meta.fileSizeBytes)} bytes, above the ${String(MAX_ATTACHMENT_MB)} MiB image ceiling.`
+        );
+      }
+      const bytes2 = await ctx.client.downloadAttachment(meta.id);
+      if (bytes2.byteLength > MAX_ATTACHMENT_BYTES) {
+        return errorResult(
+          `Attachment ${meta.id} is ${String(bytes2.byteLength)} bytes, above the ${String(MAX_ATTACHMENT_MB)} MiB image ceiling.`
+        );
+      }
+      return imageResult(encodeBase64(bytes2), mime, {
+        attachment_id: meta.id,
+        file_name: meta.name,
+        mime_type: mime,
+        file_size_bytes: bytes2.byteLength
+      });
+    }
+    const declaredText = mime.startsWith("text/") || TEXT_MIME_TYPES.has(mime);
+    const generic = GENERIC_MIME_TYPES.has(mime);
+    if (!declaredText && !generic) {
+      return errorResult(
+        `Attachment ${meta.id} has MIME type ${mime}, which is neither UTF-8 text nor a supported image type (png, jpeg, gif, webp). View it in the MySpec webapp, or use get_attachment with include_download_url=1 for a signed URL to download it locally.`
+      );
+    }
+    const bytes = await ctx.client.downloadAttachment(meta.id);
+    const text = isBinary(bytes) ? null : decodeUtf8Strict(bytes);
+    if (text === null) {
+      return errorResult(
+        `Attachment ${meta.id} (MIME type ${mime}) is not valid UTF-8 text and is not a supported image type. View it in the MySpec webapp, or use get_attachment with include_download_url=1 for a signed URL to download it locally.`
+      );
+    }
+    const paginated = paginateText(text, args.offset, args.limit);
+    if (!paginated.ok) {
+      return errorResult(paginated.error);
+    }
+    return jsonResult({
+      attachment_id: meta.id,
+      file_name: meta.name,
+      mime_type: mime,
+      file_size_bytes: meta.fileSizeBytes,
+      ...paginated.window
+    });
+  }
+};
+
 // 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";
+import { z as z17 } from "zod";
 var MAX_READ_BYTES = 1 * 1024 * 1024;
-var inputSchema11 = {
-  file_id: z11.string().min(1).describe("UUID of the file"),
-  revision: z11.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+var inputSchema17 = {
+  file_id: z17.string().min(1).describe("UUID of the file"),
+  revision: z17.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
 };
 var readSpecFileTool = {
   name: "read_spec_file",
   description: "Return a spec file's UTF-8 content. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision. Fails for binary files or files larger than 1 MiB \u2014 use download_spec_file to save those to a local file instead.",
-  inputSchema: inputSchema11,
+  inputSchema: inputSchema17,
   handler: async (args, ctx) => {
     const meta = await ctx.client.getFileMetadata(args.file_id);
     const targetRevision = args.revision ?? meta.revisionCount;
@@ -3305,7 +3910,7 @@ var readSpecFileTool = {
     if (bytes.byteLength > MAX_READ_BYTES) {
       return errorResult(buildOversizeMessage2(args.file_id, bytes.byteLength));
     }
-    if (isBinary(bytes)) {
+    if (isBinary2(bytes)) {
       return errorResult(
         `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use download_spec_file to save it to a local file.`
       );
@@ -3338,7 +3943,7 @@ var readSpecFileTool = {
 function buildOversizeMessage2(fileId, byteLength) {
   return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use download_spec_file to save it to a local file and read it in chunks.`;
 }
-function isBinary(bytes) {
+function isBinary2(bytes) {
   for (const byte of bytes) {
     if (byte === 0) {
       return true;
@@ -3350,15 +3955,59 @@ function sha256Prefixed2(content) {
   return "sha256:" + createHash2("sha256").update(content).digest("hex");
 }
 
+// src/server/tools/rename_spec_session.ts
+import { z as z18 } from "zod";
+var inputSchema18 = {
+  session_id: z18.string().min(1).describe("UUID of the spec session to rename"),
+  session_summary: z18.string().min(1).max(SESSION_SUMMARY_MAX_LENGTH).describe(
+    `New human-readable session title (max ${String(SESSION_SUMMARY_MAX_LENGTH)} characters). Stored as context.sessionSummary \u2014 the field the webapp displays and searches.`
+  )
+};
+var renameSpecSessionTool = {
+  name: "rename_spec_session",
+  description: "Rename a spec session by updating its context.sessionSummary \u2014 the session's human-readable title (there is no first-class name field). Permitted on both active and archived sessions. All other context keys are preserved untouched.",
+  inputSchema: inputSchema18,
+  handler: async (args, ctx) => {
+    if (args.session_summary.length > SESSION_SUMMARY_MAX_LENGTH) {
+      return errorResult(
+        `session_summary is ${String(args.session_summary.length)} characters; the limit is ${String(SESSION_SUMMARY_MAX_LENGTH)}.`
+      );
+    }
+    let session;
+    try {
+      session = await ctx.client.getSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    const merged = mergeSessionSummary(session.context, args.session_summary);
+    if (!merged.ok) {
+      return errorResult(
+        `Session ${args.session_id} was NOT renamed: its context is a JSON ${merged.actualType}, not an object. This shape is unexpected, the tool cannot know what it encodes, and overwriting it would be unrecoverable. Inspect the session in the MySpec webapp.`
+      );
+    }
+    const updated = await ctx.client.updateSpecSessionContext(args.session_id, merged.context);
+    const summary = introspectContext(updated.context);
+    return jsonResult({
+      renamed: true,
+      session_id: updated.id,
+      session_summary: summary.session_summary
+    });
+  }
+};
+
 // src/server/tools/restore_spec_file_from_trash.ts
-import { z as z12 } from "zod";
-var inputSchema12 = {
-  file_id: z12.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
+import { z as z19 } from "zod";
+var inputSchema19 = {
+  file_id: z19.string().min(1).describe("UUID of the spec file to restore from the Trash Bin.")
 };
 var restoreSpecFileFromTrashTool = {
   name: "restore_spec_file_from_trash",
   description: "Restore a spec file from the Trash Bin back to the active file list, reversing `move_spec_file_to_trash`. The file becomes visible again to the default file list and AI-agent tools.",
-  inputSchema: inputSchema12,
+  inputSchema: inputSchema19,
   handler: async (args, ctx) => {
     await ctx.client.restoreFile(args.file_id);
     return jsonResult({ restored: true, file_id: args.file_id });
@@ -3366,34 +4015,58 @@ var restoreSpecFileFromTrashTool = {
 };
 
 // src/server/tools/unarchive_project.ts
-import { z as z13 } from "zod";
-var inputSchema13 = {
-  project_id: z13.string().min(1).describe("UUID of the project to unarchive.")
+import { z as z20 } from "zod";
+var inputSchema20 = {
+  project_id: z20.string().min(1).describe("UUID of the project to unarchive.")
 };
 var unarchiveProjectTool = {
   name: "unarchive_project",
   description: 'Unarchive a project (sets status to "active"). Idempotent: unarchiving an already-active project succeeds.',
-  inputSchema: inputSchema13,
+  inputSchema: inputSchema20,
   handler: async (args, ctx) => {
     const project = await ctx.client.unarchiveProject(args.project_id);
     return jsonResult({ project: projectSummary(project) });
   }
 };
 
+// src/server/tools/unarchive_spec_session.ts
+import { z as z21 } from "zod";
+var inputSchema21 = {
+  session_id: z21.string().min(1).describe("UUID of the spec session to unarchive")
+};
+var unarchiveSpecSessionTool = {
+  name: "unarchive_spec_session",
+  description: "Unarchive a spec session, returning it to the active list.",
+  inputSchema: inputSchema21,
+  handler: async (args, ctx) => {
+    let session;
+    try {
+      session = await ctx.client.unarchiveSpecSession(args.session_id);
+    } catch (err) {
+      const notFound = sessionNotFound(err, args.session_id);
+      if (notFound) {
+        return notFound;
+      }
+      throw err;
+    }
+    return jsonResult({ session: sessionMetadata(session) });
+  }
+};
+
 // src/server/tools/update_project.ts
-import { z as z14 } from "zod";
-var inputSchema14 = {
-  project_id: z14.string().min(1).describe("UUID of the project to update."),
-  name: z14.string().min(1).optional().describe("New project name."),
-  description: z14.string().optional().describe("New project description."),
-  project_type: z14.enum(["greenfield", "brownfield", "auto"]).optional().describe(
+import { z as z22 } from "zod";
+var inputSchema22 = {
+  project_id: z22.string().min(1).describe("UUID of the project to update."),
+  name: z22.string().min(1).optional().describe("New project name."),
+  description: z22.string().optional().describe("New project description."),
+  project_type: z22.enum(["greenfield", "brownfield", "auto"]).optional().describe(
     "Codebase type. 'greenfield' or 'brownfield' sets it explicitly; 'auto' clears it so the workflow decides. Omit to leave unchanged."
   )
 };
 var updateProjectTool = {
   name: "update_project",
   description: "Update a project's metadata (name, description, project_type). Returns the updated metadata.",
-  inputSchema: inputSchema14,
+  inputSchema: inputSchema22,
   handler: async (args, ctx) => {
     if (args.name === void 0 && args.description === void 0 && args.project_type === void 0) {
       return errorResult(
@@ -3416,7 +4089,7 @@ var updateProjectTool = {
 };
 
 // src/server/tools/update_spec_file.ts
-import { z as z15 } from "zod";
+import { z as z23 } from "zod";
 
 // src/server/tools/spec-content-source.ts
 import { readFile, stat } from "fs/promises";
@@ -3472,24 +4145,24 @@ async function resolveSpecContent(input, maxBytes = MAX_LOCAL_SPEC_FILE_BYTES) {
 }
 
 // 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)."),
-  project_id: z15.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
-  file_path: z15.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
-  content: z15.string().min(1).optional().describe(
+var inputSchema23 = {
+  file_id: z23.string().min(1).optional().describe("UUID of the spec file to overwrite. Provide this or (project_id + file_path)."),
+  project_id: z23.string().min(1).optional().describe("UUID of the project. Required (with file_path) when file_id is not given."),
+  file_path: z23.string().min(1).optional().describe("Path of the spec file. Required (with project_id) when file_id is not given."),
+  content: z23.string().min(1).optional().describe(
     "Full UTF-8 replacement content, saved as a new revision. Provide this OR local_file_path (exactly one). Use for in-memory / generated content."
   ),
-  local_file_path: z15.string().min(1).optional().describe(
+  local_file_path: z23.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(
+  expected_version: z23.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). 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,
+  inputSchema: inputSchema23,
   handler: async (args, ctx) => {
     const resolved = await resolveSpecContent({
       content: args.content,
@@ -3554,9 +4227,9 @@ function conflictMessage(filePath, conflict) {
 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";
+import { z as z24 } from "zod";
 var DEFAULT_MIME = "application/octet-stream";
-var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
+var MAX_ATTACHMENT_MB2 = MAX_ATTACHMENT_BYTES / (1024 * 1024);
 var STRUCTURED_EXTENSION_MIME = {
   ".pdf": "application/pdf",
   ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -3659,23 +4332,23 @@ function inferMimeFromName(name) {
   }
   return DEFAULT_MIME;
 }
-var inputSchema16 = {
-  project_id: z16.string().min(1).describe("UUID of the project to attach the file to."),
-  file_path: z16.string().min(1).describe(
+var inputSchema24 = {
+  project_id: z24.string().min(1).describe("UUID of the project to attach the file to."),
+  file_path: z24.string().min(1).describe(
     "Absolute path to the local file to upload. The MCP server reads this path from its own host."
   ),
-  file_name: z16.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
-  mime_type: z16.string().min(1).optional().describe(
+  file_name: z24.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
+  mime_type: z24.string().min(1).optional().describe(
     "Override the MIME type sent to the platform. The platform re-detects from content, so this is only a hint. If omitted, inferred from the file extension \u2014 structured (.pdf, .docx, .xlsx) keep their canonical MIME; common UTF-8 text formats (.xml, .json, .yaml, .html, .csv, .md, source code, ...) are sent as text/plain."
   ),
-  override: z16.boolean().optional().describe(
+  override: z24.boolean().optional().describe(
     "When true, any existing (non-deleted) attachment on the project whose recorded filename exactly matches `file_name` (or the path basename) is soft-deleted before the new upload, so the new attachment keeps the original name instead of getting an auto-dedup `(1)` suffix. The platform has no in-place content-replace API, so the new upload always gets a new `attachment_id`; any replaced ids are returned as `overridden_attachment_ids` (array, possibly empty) so callers can refresh stored references. Defaults to false (let the platform auto-dedup)."
   )
 };
 var uploadAttachmentTool = {
   name: "upload_attachment",
-  description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB)} MB. Supported content: PDF, DOCX, XLSX, images (PNG, JPEG, GIF, WEBP), and any UTF-8 text file (XML, JSON, YAML, HTML, SVG, Markdown, CSV, source code, ...). Other binary files are rejected by the platform.`,
-  inputSchema: inputSchema16,
+  description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB2)} MB. Supported content: PDF, DOCX, XLSX, images (PNG, JPEG, GIF, WEBP), and any UTF-8 text file (XML, JSON, YAML, HTML, SVG, Markdown, CSV, source code, ...). Other binary files are rejected by the platform.`,
+  inputSchema: inputSchema24,
   handler: async (args, ctx) => {
     if (!isAbsolute2(args.file_path)) {
       return errorResult(`file_path must be an absolute path; got "${args.file_path}".`);
@@ -3708,7 +4381,7 @@ var uploadAttachmentTool = {
     }
     if (stats.size > MAX_ATTACHMENT_BYTES) {
       return errorResult(
-        `File size ${String(stats.size)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+        `File size ${String(stats.size)} bytes exceeds the ${String(MAX_ATTACHMENT_MB2)} MB attachment limit.`
       );
     }
     let buf;
@@ -3727,7 +4400,7 @@ var uploadAttachmentTool = {
     }
     if (buf.byteLength > MAX_ATTACHMENT_BYTES) {
       return errorResult(
-        `File size ${String(buf.byteLength)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+        `File size ${String(buf.byteLength)} bytes exceeds the ${String(MAX_ATTACHMENT_MB2)} MB attachment limit.`
       );
     }
     const fileName = args.file_name ?? basename(args.file_path);
@@ -3799,7 +4472,7 @@ var uploadAttachmentTool = {
 };
 
 // src/server/tools/upload_spec_file.ts
-import { z as z17 } from "zod";
+import { z as z25 } from "zod";
 
 // src/server/spec-path.ts
 var MAX_SPEC_DIR_DEPTH = 3;
@@ -3852,23 +4525,23 @@ var SPEC_FILE_TYPES = [
   "proposal",
   "openspec-spec"
 ];
-var inputSchema17 = {
-  project_id: z17.string().min(1).describe("UUID of the project to upload the file into."),
-  file_path: z17.string().min(1).describe(
+var inputSchema25 = {
+  project_id: z25.string().min(1).describe("UUID of the project to upload the file into."),
+  file_path: z25.string().min(1).describe(
     'Path of the new spec file, rooted at "specs" or "openspec" with at most 3 directory levels below the root (e.g. specs/changes/add-oauth-login/proposal.md).'
   ),
-  content: z17.string().min(1).optional().describe(
+  content: z25.string().min(1).optional().describe(
     "Full UTF-8 text content of the spec file. Provide this OR local_file_path (exactly one). Use for in-memory / generated content."
   ),
-  local_file_path: z17.string().min(1).optional().describe(
+  local_file_path: z25.string().min(1).optional().describe(
     "Path to a local file whose bytes become the spec file body; 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."
   ),
-  file_type: z17.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
+  file_type: z25.enum(SPEC_FILE_TYPES).optional().describe("Spec file type. Omit to derive from the filename (e.g. proposal.md \u2192 proposal).")
 };
 var uploadSpecFileTool = {
   name: "upload_spec_file",
   description: "Upload a new, session-less spec file into a project. Provide the file 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, avoiding sending large content through the model); use `content` for text generated in-memory. Rejects if a file already exists at the same path (use update_spec_file to overwrite).",
-  inputSchema: inputSchema17,
+  inputSchema: inputSchema25,
   handler: async (args, ctx) => {
     const pathError = validateSpecFilePath(args.file_path);
     if (pathError) {
@@ -3921,6 +4594,14 @@ function buildServer(deps) {
   registerTool(server, updateSpecFileTool, deps.client);
   registerTool(server, moveSpecFileToTrashTool, deps.client);
   registerTool(server, restoreSpecFileFromTrashTool, deps.client);
+  registerTool(server, listAttachmentsTool, deps.client);
+  registerTool(server, readAttachmentTool, deps.client);
+  registerTool(server, listSpecSessionsTool, deps.client);
+  registerTool(server, getSpecSessionTool, deps.client);
+  registerTool(server, renameSpecSessionTool, deps.client);
+  registerTool(server, archiveSpecSessionTool, deps.client);
+  registerTool(server, unarchiveSpecSessionTool, deps.client);
+  registerTool(server, deleteSpecSessionTool, deps.client);
   return server;
 }
 async function startStdioServer(deps) {
@@ -4074,7 +4755,7 @@ async function canonicaliseRoot(root) {
 import { promises as fs4 } from "fs";
 import { join as join2, relative } from "path";
 import { spawn } from "child_process";
-import { z as z18 } from "zod";
+import { z as z26 } from "zod";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 // src/reverse/ignore.ts
@@ -4171,7 +4852,7 @@ var PackCache = class {
       if (oldestKey === void 0) break;
       this.entries.delete(oldestKey);
     }
-    const lines = splitIntoLines(content);
+    const lines = splitIntoLines2(content);
     const pages = planPages(lines);
     const entry = {
       outputId,
@@ -4199,7 +4880,7 @@ var PackCache = class {
     }
   }
 };
-function splitIntoLines(text) {
+function splitIntoLines2(text) {
   const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
   const parts = normalized.split("\n");
   if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
@@ -4379,37 +5060,37 @@ var READ_FILE_MAX_LINES = 2e3;
 var LIST_DIR_HARD_CAP = 5e3;
 var LIST_DIR_DEFAULT_CAP = 1e3;
 var GREP_MAX_MATCHES_DEFAULT = 200;
-var listDirInput = z18.object({
-  path: z18.string(),
-  recursive: z18.boolean().optional(),
-  maxEntries: z18.number().int().positive().optional(),
-  includeIgnored: z18.boolean().optional()
+var listDirInput = z26.object({
+  path: z26.string(),
+  recursive: z26.boolean().optional(),
+  maxEntries: z26.number().int().positive().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var readFileInput = z18.object({
-  path: z18.string(),
-  offset: z18.number().int().nonnegative().optional(),
-  limit: z18.number().int().positive().optional(),
-  includeIgnored: z18.boolean().optional()
+var readFileInput = z26.object({
+  path: z26.string(),
+  offset: z26.number().int().nonnegative().optional(),
+  limit: z26.number().int().positive().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var grepInput = z18.object({
-  pattern: z18.string().describe(
+var grepInput = z26.object({
+  pattern: z26.string().describe(
     "Search pattern. Interpreted as a regular expression by default (ripgrep syntax), e.g. `foo|bar` or `[Rr]ole`. Set `isRegex: false` to match the pattern as an exact literal string instead."
   ),
-  path: z18.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
-  isRegex: z18.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
-  caseSensitive: z18.boolean().optional(),
-  maxMatches: z18.number().int().positive().optional(),
-  contextLines: z18.number().int().nonnegative().optional(),
-  includeIgnored: z18.boolean().optional()
+  path: z26.string().optional().describe("File or directory under --root to search. Defaults to the whole root."),
+  isRegex: z26.boolean().optional().describe("Treat `pattern` as a regex (default true). Set false for literal-string search."),
+  caseSensitive: z26.boolean().optional(),
+  maxMatches: z26.number().int().positive().optional(),
+  contextLines: z26.number().int().nonnegative().optional(),
+  includeIgnored: z26.boolean().optional()
 });
-var packCodebaseInput = z18.object({
-  subpath: z18.string().optional(),
-  includePatterns: z18.string().optional(),
-  ignorePatterns: z18.string().optional()
+var packCodebaseInput = z26.object({
+  subpath: z26.string().optional(),
+  includePatterns: z26.string().optional(),
+  ignorePatterns: z26.string().optional()
 });
-var packCodebaseReadPageInput = z18.object({
-  outputId: z18.string(),
-  page: z18.number().int().positive()
+var packCodebaseReadPageInput = z26.object({
+  outputId: z26.string(),
+  page: z26.number().int().positive()
 });
 function structuredError(error, message, extra) {
   const payload = { error, message, ...extra ?? {} };
@@ -4525,19 +5206,19 @@ async function handleRead(args, opts) {
       `Binary content detected in ${args.path}; line-based pagination doesn't apply. Skip this file or use local_fs_grep on neighbouring text files.`
     );
   }
-  const text = normalizeNewlines(raw.toString("utf-8"));
-  const lines = splitIntoLines2(text);
+  const text = normalizeNewlines2(raw.toString("utf-8"));
+  const lines = splitIntoLines3(text);
   const page = paginateLines(lines, args.offset, args.limit);
   if ("error" in page) {
     return structuredError("invalid_offset", page.error);
   }
   return structuredOk(page);
 }
-function normalizeNewlines(s) {
+function normalizeNewlines2(s) {
   const noBom = s.charCodeAt(0) === 65279 ? s.slice(1) : s;
   return noBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
 }
-function splitIntoLines2(text) {
+function splitIntoLines3(text) {
   const parts = text.split("\n");
   if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
   return parts;
@@ -4850,7 +5531,7 @@ function registerLocalFsTools(server, opts) {
     },
     {
       name: "local_pack_codebase",
-      description: "Pack the entire local codebase (under the granted --root) into a single XML bundle using `npx repomix@latest --style xml --compress`. Prefer this over many `local_fs_read_file` calls when you need broad codebase context. Output is paginated at ~2500 lines per page; a `<file>` block is never split across a page boundary, but the `<files>` root wrapper spans pages (its opener is on the first files page and its closer on the last) \u2014 always keep reading while `hasMore` is true rather than stopping at a `</files>`. The response includes `outputId`, `page`, `totalPages`, `totalLines`, `pageLines`, `hasMore`, and a `nextPage` hint. Use `local_pack_codebase_read_page` to fetch subsequent pages by `outputId`. Repeat calls with the same `subpath`/`includePatterns`/`ignorePatterns` return the same `outputId` and are served instantly from the 30-minute cache without re-running repomix.",
+      description: "Pack the local codebase (under the granted --root) into a single compressed XML bundle (embedded repomix, `--style xml --compress`; file bodies use `\u22EE----` delimiters). Prefer this over many `local_fs_read_file` calls when you need broad codebase context. Output is paginated at ~2500 lines per page; a `<file>` block is never split across a page boundary, but the `<files>` root wrapper spans pages (its opener is on the first files page and its closer on the last) \u2014 never treat a missing `</files>` as truncation. The response includes `outputId`, `page`, `totalPages`, `totalLines`, `pageLines`, `hasMore`, and a `nextPage` hint; page 1 opens with the full directory structure. Fetch further pages with `local_pack_codebase_read_page` while `totalPages` is small; for a large pack (roughly 10+ pages) do NOT page through everything \u2014 use page 1 as the repo map, then re-pack narrowed with `subpath`/`includePatterns` or switch to `local_fs_grep`/`local_fs_read_file` for targeted reads. Repeat calls with the same `subpath`/`includePatterns`/`ignorePatterns` return the same `outputId` and are served instantly from the 30-minute cache without re-running repomix.",
       inputSchema: jsonSchemaFromZod(packCodebaseInput),
       handler: async (args) => {
         try {
@@ -4863,7 +5544,7 @@ function registerLocalFsTools(server, opts) {
     },
     {
       name: "local_pack_codebase_read_page",
-      description: "Read a specific page of a previously packed codebase output. Provide the `outputId` returned by `local_pack_codebase` and the 1-indexed `page` to fetch. Each page is up to ~2500 lines of XML; no `<file>` block is split across pages, but the `<files>` root wrapper spans pages \u2014 keep fetching while `hasMore` is true, do not stop at a `</files>`. Cache entries expire after 30 minutes; on cache miss, re-run `local_pack_codebase` (same args return the same outputId \u2014 re-pack is cheap, served from cache).",
+      description: "Read a specific page of a previously packed codebase output. Provide the `outputId` returned by `local_pack_codebase` and the 1-indexed `page` to fetch. Each page is up to ~2500 lines of the compressed XML bundle; no `<file>` block is split across pages, but the `<files>` root wrapper spans pages \u2014 never treat a missing `</files>` as truncation. Cache entries expire after 30 minutes; on cache miss, re-run `local_pack_codebase` (same args return the same outputId \u2014 re-pack is cheap, served from cache).",
       inputSchema: jsonSchemaFromZod(packCodebaseReadPageInput),
       handler: (args) => {
         try {
@@ -4937,7 +5618,7 @@ function jsonSchemaFromZod(schema) {
   return zodToJson(schema);
 }
 function zodToJson(schema) {
-  if (schema instanceof z18.ZodObject) {
+  if (schema instanceof z26.ZodObject) {
     const shape = schema.shape;
     const properties = {};
     const required = [];
@@ -4952,19 +5633,19 @@ function zodToJson(schema) {
     if (required.length > 0) out.required = required;
     return out;
   }
-  if (schema instanceof z18.ZodOptional) {
+  if (schema instanceof z26.ZodOptional) {
     return zodToJson(schema.unwrap());
   }
-  if (schema instanceof z18.ZodString) {
+  if (schema instanceof z26.ZodString) {
     return { type: "string" };
   }
-  if (schema instanceof z18.ZodNumber) {
+  if (schema instanceof z26.ZodNumber) {
     return { type: "number" };
   }
-  if (schema instanceof z18.ZodBoolean) {
+  if (schema instanceof z26.ZodBoolean) {
     return { type: "boolean" };
   }
-  if (schema instanceof z18.ZodEnum) {
+  if (schema instanceof z26.ZodEnum) {
     return { type: "string", enum: schema.options };
   }
   return { type: "string" };
@@ -5407,21 +6088,59 @@ async function resolveReverseAgentUrl(sources) {
     throw err;
   }
 }
+function ignoringSettings(settingsPath, reason) {
+  return `myspec-mcp: ignoring the userAuthUrl in ${settingsPath} for the MYSPEC_API_TOKEN exchange URL \u2014 ${reason}.`;
+}
+function usableAuthUrl(candidate, settingsPath, warn) {
+  if (candidate === void 0) {
+    return void 0;
+  }
+  try {
+    resolveConfig({ env: {}, storedUserAuthUrl: candidate });
+    return candidate;
+  } catch (err) {
+    if (!(err instanceof ConfigError)) {
+      throw err;
+    }
+    warn(ignoringSettings(settingsPath, err.message));
+    return void 0;
+  }
+}
 async function buildCredentialsStore(opts = {}) {
   const env = opts.env ?? process.env;
-  const fileStore = opts.fileStore ?? createFileCredentialsStore();
+  const settingsPath = opts.settingsPath ?? defaultSettingsPath();
+  const fileStore = opts.fileStore ?? createFileCredentialsStore({ settingsPath });
+  const warn = opts.warn ?? ((message) => {
+    process.stderr.write(message + "\n");
+  });
   const usingEnvApiToken = hasEnvApiToken(env);
   const tolerate = opts.toleratesUnreadableFile ?? usingEnvApiToken;
   const stored = tolerate ? await fileStore.load().catch(() => null) : await fileStore.load();
+  const overridden = (opts.cliUserAuthUrl ?? env.MYSPEC_USER_AUTH_URL) !== void 0;
+  const fromSettings = usingEnvApiToken && !overridden && stored?.userAuthUrl === void 0 ? await readSettingsUserAuthUrl(settingsPath).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(ignoringSettings(settingsPath, `it could not be read (${message})`));
+    return void 0;
+  }) : void 0;
   const config = resolveConfig({
     env,
     cliUserAuthUrl: opts.cliUserAuthUrl,
-    storedUserAuthUrl: stored?.userAuthUrl
+    // Validated on its own before it joins the chain, for the same reason the
+    // unreadable file above is forgiven: parseSettings only requires a
+    // non-empty string, so a hand-written `htps://…` or a bare host in a
+    // settings.json that is not even the credential would otherwise turn a
+    // pure-env install that used to start on the prod default into a
+    // ConfigError exit — and one that never names the file it came from.
+    storedUserAuthUrl: stored?.userAuthUrl ?? usableAuthUrl(fromSettings, settingsPath, warn)
   });
   return {
     store: createEnvApiTokenStore({
       fileStore,
-      envConfig: readEnvApiToken(config.userAuthUrl, env)
+      // `warn` rather than the default sink, so the "cannot be sent as a
+      // header" warning lands wherever the caller's other warnings do.
+      envConfig: readEnvApiToken(config.userAuthUrl, env, warn),
+      settingsPath,
+      warn
     }),
     config,
     usingEnvApiToken