fix(session): enforce readable note size budget

Author: vicary

docs/SmokeTests.md

@@ -277,7 +277,10 @@ the change that introduces it; do not assume one here, and do not invent a new
   `{ action: "deleted", id
   }`, exact single-note reads via
   `session_notes_read({ id })`, `{ note: null }` for unknown ids, and
-  status-less response shapes.
+  status-less response shapes. Non-empty `session_notes_write` calls that would
+  make the eventual `session_notes_read` JSON exceed the shared 32 KB serialized
+  response budget must be rejected before storage, while delete operations with
+  empty text remain valid.
 - **Artifacts/evidence to save:** Full `deno test` output; failing test names if
   any; bounded serialized examples for each tool response; any type-check output
   from `deno task check`.
@@ -585,11 +588,13 @@ the change that introduces it; do not assume one here, and do not invent a new
   ```
 
 - **Expected result:** PASS. At minimum, automated coverage must continue to
-  enforce the locked bounded-response budget, artifact spillover rules, bytes
-  saved/accounting expectations, and no-unbounded-growth invariants already
-  owned by the runtime and corpus tests. Any future latency or storage-growth
-  numeric threshold added to the suite must be asserted in these existing test
-  surfaces unless a separately justified harness is approved.
+  enforce the locked 32 KB bounded-response budget, artifact spillover rules,
+  bytes saved/accounting expectations, and no-unbounded-growth invariants
+  already owned by the runtime and corpus tests. `session_notes_read` remains
+  under the normal runtime guard, so accepted notes must stay readable within
+  that shared limit. Any future latency or storage-growth numeric threshold
+  added to the suite must be asserted in these existing test surfaces unless a
+  separately justified harness is approved.
 - **Artifacts/evidence to save:** Full test output; any serialized payload-size
   assertions; corpus/artifact/stats counters relevant to storage growth; any
   threshold-failure logs added in future colocated tests.

docs/superpowers/plans/2026-03-20-context-mode-mcp-first-implementation.md

@@ -101,7 +101,7 @@ execution.
 - `session_execute`, `session_execute_file`, and `session_batch_execute` return
   a bounded human-readable summary plus references, never an unbounded raw
   payload.
-- Tool response body budget: 8 KB maximum serialized response payload per
+- Tool response body budget: 32 KB maximum serialized response payload per
   `session_*` call.
 - Large execution/fetch/file artifacts are stored locally and referenced by
   artifact or corpus ID.
@@ -281,8 +281,8 @@ Write failing tests first in `src/services/session-mcp-runtime.test.ts` and
 - each tool schema rejects calls without `root_session_id`
 - initial stub handlers return minimal valid responses for all 8 registered
   tools
-- response payloads are capped to the exact 8 KB response budget
-- at least one large-output case crossing the 8 KB boundary falls back to local
+- response payloads are capped to the exact 32 KB response budget
+- at least one large-output case crossing the 32 KB boundary falls back to local
   artifact storage/reference instead of returning an oversized inline payload
 - `session_batch_execute` executes sequentially in request order
 - `src/index.ts` wires runtime initialization and teardown in-process

src/services/session-mcp-runtime.test.ts

@@ -158,6 +158,21 @@ class DoctorRedisRuntime {
 
 const textEncoder = new TextEncoder();
 
+const createOversizedSessionNoteText = (): string => {
+  const timestamp = "2026-04-11T10:00:00.000Z";
+  const emptyPayloadBytes = textEncoder.encode(JSON.stringify({
+    note: {
+      id: crypto.randomUUID(),
+      text: "",
+      created_at: timestamp,
+      updated_at: timestamp,
+    },
+  })).byteLength;
+  return "x".repeat(
+    SESSION_MCP_RESPONSE_BUDGET_BYTES - emptyPayloadBytes + 1,
+  );
+};
+
 const toolContext = {
   sessionID: "session-123",
   messageID: "message-123",
@@ -973,6 +988,62 @@ describe("session-mcp-runtime", () => {
     }
   });
 
+  it("rejects oversized note writes before storage and suggests splitting notes", async () => {
+    const redis = new RedisClient({ endpoint: "redis://unused" });
+    const runtime = createSessionMcpRuntime({
+      redisClient: redis,
+      sessionTtlSeconds: 60,
+    } as never);
+    const oversizedText = createOversizedSessionNoteText();
+
+    try {
+      await assertRejects(
+        () =>
+          runtime.tools.session_notes_write.execute(
+            {
+              text: oversizedText,
+            },
+            toolContext,
+          ),
+        Error,
+        "multiple cross-referencing session notes",
+      );
+    } finally {
+      await runtime.dispose();
+    }
+  });
+
+  it("applies the shared response budget guard to session_notes_read", async () => {
+    const oversizedText = "x".repeat(SESSION_MCP_RESPONSE_BUDGET_BYTES + 1_024);
+    const runtime = createSessionMcpRuntime({
+      notesService: {
+        readNote: () =>
+          Promise.resolve({
+            note: {
+              id: "note-oversized",
+              text: oversizedText,
+              created_at: "2026-04-11T10:00:00.000Z",
+              updated_at: "2026-04-11T10:00:00.000Z",
+            },
+          }),
+      } as never,
+    } as never);
+
+    try {
+      await assertRejects(
+        () =>
+          runtime.tools.session_notes_read.execute(
+            { id: "note-oversized" },
+            toolContext,
+          ),
+        Error,
+        `session_notes_read response exceeded ${SESSION_MCP_RESPONSE_BUDGET_BYTES} bytes`,
+      );
+    } finally {
+      await runtime.dispose();
+    }
+  });
+
   it("resolves rootless search and note writes from the canonical tool context session", async () => {
     const redis = new RedisClient({ endpoint: "redis://unused" });
     const manager = new SessionManager(
@@ -2124,7 +2195,7 @@ describe("session-mcp-runtime", () => {
     }
   });
 
-  it("caps serialized responses to the exact 8 KB budget", async () => {
+  it("caps serialized responses to the exact 32 KB budget", async () => {
     const runtime = createSessionMcpRuntime();
 
     try {
@@ -2145,7 +2216,7 @@ describe("session-mcp-runtime", () => {
     }
   });
 
-  it("falls back to a local artifact reference when inline output crosses 8 KB", async () => {
+  it("falls back to a local artifact reference when inline output crosses 32 KB", async () => {
     const runtime = createSessionMcpRuntime({
       handlers: {
         session_execute: () =>
@@ -2272,11 +2343,11 @@ describe("session-mcp-runtime", () => {
           Promise.resolve({
             status: "ok",
             summary: "SESSION TTL REPORT\n" +
-              "session ttl keeps local corpus search warm\n".repeat(400),
+              "session ttl keeps local corpus search warm\n".repeat(900),
             exit_code: 0,
             timed_out: false,
             truncated: false,
-            bytes_captured: SESSION_MCP_RESPONSE_BUDGET_BYTES + 4_096,
+            bytes_captured: SESSION_MCP_RESPONSE_BUDGET_BYTES + 8_192,
           }),
       },
     } as never);
@@ -2668,11 +2739,11 @@ describe("session-mcp-runtime", () => {
         session_execute: (request: { command: string }) =>
           Promise.resolve({
             status: "ok",
-            summary: `${request.command}: ` + "x".repeat(6_000),
+            summary: `${request.command}: ` + "x".repeat(18_000),
             exit_code: 0,
             timed_out: false,
             truncated: false,
-            bytes_captured: 6_010,
+            bytes_captured: 18_010,
           }),
       },
     } as never);
@@ -2819,11 +2890,11 @@ describe("session-mcp-runtime", () => {
         session_execute: (request: { command: string }) =>
           Promise.resolve({
             status: "ok",
-            summary: `${request.command}: ` + "x".repeat(7_000),
+            summary: `${request.command}: ` + "x".repeat(18_000),
             exit_code: 0,
             timed_out: false,
             truncated: false,
-            bytes_captured: 7_010,
+            bytes_captured: 18_010,
           }),
       },
     } as never);

src/services/session-mcp-runtime.ts

@@ -39,7 +39,7 @@ import type { NormalizedMemoryResult } from "../types/index.ts";
 import { readFile as readFileNode } from "node:fs/promises";
 import path from "node:path";
 
-export const SESSION_MCP_RESPONSE_BUDGET_BYTES = 8 * 1024;
+export const SESSION_MCP_RESPONSE_BUDGET_BYTES = 32 * 1024;
 const SESSION_SEARCH_RESULT_LIMIT = 5;
 const SEARCH_RESULT_CREATED_AT_FALLBACK = "1970-01-01T00:00:00.000Z";
 
@@ -422,6 +422,15 @@ const createBoundedSessionIndexError = (
 const isWithinBudget = (value: string): boolean =>
   byteLength(value) <= SESSION_MCP_RESPONSE_BUDGET_BYTES;
 
+const serializeSessionNoteReadResponse = (
+  note: {
+    id: string;
+    text: string;
+    created_at: string;
+    updated_at: string;
+  },
+): string => serialize({ note });
+
 const resolveSessionIndexPath = (
   requestPath: string,
   context: ToolContext,
@@ -852,6 +861,25 @@ export const createSessionMcpRuntime = (
     },
     session_notes_write: async (request, context) => {
       const rootSessionId = await resolveCanonicalRootSessionId(context);
+      if (request.text !== "") {
+        const timestamp = new Date().toISOString();
+        const existingNote = request.replace && request.replace !== "*"
+          ? (await notes.readNotes(rootSessionId, request.replace)).notes[0]
+          : undefined;
+        const previewNote = {
+          id: request.replace && request.replace !== "*"
+            ? request.replace
+            : crypto.randomUUID(),
+          text: request.text,
+          created_at: existingNote?.created_at ?? timestamp,
+          updated_at: timestamp,
+        };
+        if (!isWithinBudget(serializeSessionNoteReadResponse(previewNote))) {
+          throw new Error(
+            "session_notes_write note would exceed the shared response budget when read back; break the content into multiple cross-referencing session notes.",
+          );
+        }
+      }
       return await notes.writeNote(rootSessionId, request.text, {
         replace: request.replace,
       });