@openchambery/web 1.18.1 → 1.18.2-beta.10

package/server/lib/config-sync/scripts.js

@@ -0,0 +1,264 @@
+import path from 'node:path';
+
+import {
+  OPENCODE_AGENTS_ROOT_PROBE_MARKER,
+  OPENCODE_AGENTS_SYNC_BACKUP_DIR,
+  OPENCODE_AUTH_FILE_PROBE_MARKER,
+  OPENCODE_AUTH_SYNC_BACKUP_DIR,
+  OPENCODE_CONFIG_SYNC_ALLOWLIST,
+  OPENCODE_CONFIG_SYNC_BACKUP_DIR,
+  OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS,
+} from './constants.js';
+
+const shellQuote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
+
+/**
+ * Sanitize syncRunId for use as a single path segment under backup roots.
+ * @param {string} syncRunId
+ */
+export const sanitizeSyncRunIdForPath = (syncRunId) => {
+  const trimmed = String(syncRunId || '').trim();
+  if (!trimmed) throw new Error('syncRunId is required for generational backup');
+  if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+    throw new Error('syncRunId contains unsupported characters for backup paths');
+  }
+  return trimmed;
+};
+
+/**
+ * Emit POSIX lines that create `<$backupVar>/<syncRunId>` as `$runVar` and prune older generations.
+ * Does not wipe the entire backup root — only replaces the current run dir and
+ * deletes generations beyond the retention limit (failed runs keep their scene).
+ *
+ * @param {{ backupVar: string, runVar: string, quotedRunId: string, generations: number }} args
+ * @returns {string[]}
+ */
+const generationalBackupSetupLines = ({ backupVar, runVar, quotedRunId, generations }) => [
+  `mkdir -p "$${backupVar}"`,
+  `${runVar}="$${backupVar}"/${quotedRunId}`,
+  `rm -rf -- "$${runVar}"`,
+  `mkdir -p "$${runVar}"`,
+  `(cd "$${backupVar}" && ls -1t 2>/dev/null | awk 'NR>${generations} {print}' | while IFS= read -r old; do`,
+  '  [ -n "$old" ] || continue',
+  `  [ "$old" = ${quotedRunId} ] && continue`,
+  `  rm -rf -- "$${backupVar}/$old"`,
+  'done) || true',
+];
+
+/**
+ * Build the remote POSIX prepare script: generational backup, delete stale counterparts, print SYNC_READY.
+ * Backups land under `<backupRoot>/<syncRunId>/…`. Older generations beyond
+ * {@link OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS} are pruned; prepare no longer
+ * `rm -rf`s the entire backup root at start.
+ *
+ * @param {{ files: { path: string }[], directories: { path: string }[], deletes: string[], agentsRoot?: { fileCount: number, bytes: number } | null, authFile?: { bytes: number } | null }} plan
+ * @param {{ syncRunId: string, generations?: number }} options
+ * @returns {string}
+ */
+export const buildRemoteSyncPrepareScript = (plan, options) => {
+  const syncRunId = sanitizeSyncRunIdForPath(options?.syncRunId);
+  const generations = Number.isFinite(options?.generations) && Number(options.generations) > 0
+    ? Math.trunc(Number(options.generations))
+    : OPENCODE_CONFIG_SYNC_BACKUP_GENERATIONS;
+  const backupDir = OPENCODE_CONFIG_SYNC_BACKUP_DIR;
+  const directoryDeleteNames = new Set();
+  for (const dirSpec of OPENCODE_CONFIG_SYNC_ALLOWLIST.directories) {
+    directoryDeleteNames.add(dirSpec.path);
+    if (typeof dirSpec.legacy === 'string' && dirSpec.legacy) {
+      directoryDeleteNames.add(dirSpec.legacy);
+    }
+  }
+
+  const quotedRunId = shellQuote(syncRunId);
+  const lines = [
+    'set -e',
+    'CFG="$HOME/.config/opencode"',
+    'mkdir -p "$CFG"',
+    `BK="$CFG/${backupDir}"`,
+    ...generationalBackupSetupLines({
+      backupVar: 'BK',
+      runVar: 'RUN_BK',
+      quotedRunId,
+      generations,
+    }),
+  ];
+
+  const backupPaths = [
+    ...(Array.isArray(plan?.files) ? plan.files.map((entry) => entry.path) : []),
+    ...(Array.isArray(plan?.directories) ? plan.directories.map((entry) => entry.path) : []),
+  ];
+
+  for (const rel of backupPaths) {
+    const quoted = shellQuote(rel);
+    const dirname = path.posix.dirname(rel);
+    const quotedDir = shellQuote(dirname === '.' ? '' : dirname);
+    lines.push(`if [ -e "$CFG"/${quoted} ]; then`);
+    if (dirname === '.' || dirname === '') {
+      lines.push('  mkdir -p "$RUN_BK"');
+    } else {
+      lines.push(`  mkdir -p "$RUN_BK"/${quotedDir}`);
+    }
+    lines.push(`  cp -a "$CFG"/${quoted} "$RUN_BK"/${quoted}`);
+    lines.push('fi');
+  }
+
+  for (const rel of Array.isArray(plan?.deletes) ? plan.deletes : []) {
+    const quoted = shellQuote(rel);
+    if (directoryDeleteNames.has(rel)) {
+      lines.push(`rm -rf -- "$CFG"/${quoted}`);
+    } else {
+      lines.push(`rm -f -- "$CFG"/${quoted}`);
+    }
+  }
+
+  if (plan?.agentsRoot) {
+    lines.push(`AGENTS_BK="$HOME/${OPENCODE_AGENTS_SYNC_BACKUP_DIR}"`);
+    lines.push(...generationalBackupSetupLines({
+      backupVar: 'AGENTS_BK',
+      runVar: 'AGENTS_RUN_BK',
+      quotedRunId,
+      generations,
+    }));
+    lines.push('if [ -e "$HOME/.agents" ]; then');
+    lines.push('  cp -a "$HOME/.agents" "$AGENTS_RUN_BK/agents"');
+    lines.push('fi');
+    lines.push('rm -rf -- "$HOME/.agents"');
+  }
+
+  if (plan?.authFile) {
+    lines.push(`AUTH_BK="$HOME/${OPENCODE_AUTH_SYNC_BACKUP_DIR}"`);
+    lines.push(...generationalBackupSetupLines({
+      backupVar: 'AUTH_BK',
+      runVar: 'AUTH_RUN_BK',
+      quotedRunId,
+      generations,
+    }));
+    lines.push('if [ -e "$HOME/.local/share/opencode/auth.json" ]; then');
+    lines.push('  cp -a "$HOME/.local/share/opencode/auth.json" "$AUTH_RUN_BK/auth.json"');
+    lines.push('fi');
+  }
+
+  lines.push("printf 'SYNC_READY\\n'");
+  return lines.join('\n');
+};
+
+/**
+ * Build the remote existence probe script for the sync preview.
+ * @param {string[]} uniqueProbePaths
+ * @returns {string}
+ */
+export const buildRemoteSyncProbeScript = (uniqueProbePaths) => {
+  const lines = (Array.isArray(uniqueProbePaths) ? uniqueProbePaths : []).map((rel) => {
+    const quoted = shellQuote(rel);
+    return `[ -e "$HOME/.config/opencode"/${quoted} ] && printf '%s\\n' ${quoted}`;
+  });
+  lines.push(
+    `[ -e "$HOME/.agents" ] && printf '%s\\n' ${shellQuote(OPENCODE_AGENTS_ROOT_PROBE_MARKER)}`,
+  );
+  lines.push(
+    `[ -e "$HOME/.local/share/opencode/auth.json" ] && printf '%s\\n' ${shellQuote(OPENCODE_AUTH_FILE_PROBE_MARKER)}`,
+  );
+  lines.push('exit 0');
+  return lines.join('\n');
+};
+
+/**
+ * Finalize script: confirm generational backup dir exists for this syncRunId and print SYNC_DONE.
+ * @param {{ syncRunId: string }} options
+ */
+export const buildRemoteSyncFinalizeScript = (options) => {
+  const syncRunId = sanitizeSyncRunIdForPath(options?.syncRunId);
+  const quotedRunId = shellQuote(syncRunId);
+  return [
+    'set -e',
+    `BK="$HOME/.config/opencode/${OPENCODE_CONFIG_SYNC_BACKUP_DIR}"/${quotedRunId}`,
+    'if [ ! -d "$BK" ]; then',
+    "  printf 'SYNC_FINALIZE_MISSING_BACKUP\\n' >&2",
+    '  exit 1',
+    'fi',
+    "printf 'SYNC_DONE\\n'",
+  ].join('\n');
+};
+
+/**
+ * Build a remote inventory script that prints a JSON object describing which
+ * allowlist paths exist on the remote (for pull planning). Uses only POSIX sh.
+ * Output is a single JSON line prefixed by SYNC_INVENTORY=.
+ * @returns {string}
+ */
+export const buildRemoteSyncInventoryScript = () => {
+  const filePaths = [
+    ...OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.flat(),
+    ...OPENCODE_CONFIG_SYNC_ALLOWLIST.singleFiles,
+  ];
+  const dirPaths = OPENCODE_CONFIG_SYNC_ALLOWLIST.directories.map((entry) => entry.path);
+  const lines = [
+    'set -e',
+    'CFG="$HOME/.config/opencode"',
+    'FILES=""',
+    'DIRS=""',
+  ];
+  for (const rel of filePaths) {
+    const quoted = shellQuote(rel);
+    lines.push(`if [ -f "$CFG"/${quoted} ]; then`);
+    lines.push(`  BYTES="$(wc -c < "$CFG"/${quoted} | tr -d ' ')"`);
+    lines.push(`  FILES="$FILES{\\"path\\":${JSON.stringify(rel)},\\"bytes\\":$BYTES},"`);
+    lines.push('fi');
+  }
+  for (const rel of dirPaths) {
+    const quoted = shellQuote(rel);
+    lines.push(`if [ -d "$CFG"/${quoted} ]; then`);
+    lines.push(`  COUNT="$(find "$CFG"/${quoted} -type f ! -path '*/node_modules/*' ! -name '*.backup' 2>/dev/null | wc -l | tr -d ' ')"`);
+    lines.push(`  BYTES="$(find "$CFG"/${quoted} -type f ! -path '*/node_modules/*' ! -name '*.backup' -exec wc -c {} + 2>/dev/null | awk 'END{print $1+0}')"`);
+    lines.push(`  DIRS="$DIRS{\\"path\\":${JSON.stringify(rel)},\\"fileCount\\":$COUNT,\\"bytes\\":$BYTES},"`);
+    lines.push('fi');
+  }
+  lines.push('AGENTS="null"');
+  lines.push('if [ -d "$HOME/.agents" ]; then');
+  lines.push("  ACOUNT=\"$(find \"$HOME/.agents\" -type f ! -path '*/node_modules/*' ! -name '*.backup' 2>/dev/null | wc -l | tr -d ' ')\"");
+  lines.push("  ABYTES=\"$(find \"$HOME/.agents\" -type f ! -path '*/node_modules/*' ! -name '*.backup' -exec wc -c {} + 2>/dev/null | awk 'END{print $1+0}')\"");
+  lines.push('  AGENTS="{\\"fileCount\\":$ACOUNT,\\"bytes\\":$ABYTES}"');
+  lines.push('fi');
+  lines.push('AUTH="null"');
+  lines.push('if [ -f "$HOME/.local/share/opencode/auth.json" ]; then');
+  lines.push('  AUBYTES="$(wc -c < "$HOME/.local/share/opencode/auth.json" | tr -d \' \')"');
+  lines.push('  AUTH="{\\"bytes\\":$AUBYTES}"');
+  lines.push('fi');
+  lines.push('FILES="${FILES%,}"');
+  lines.push('DIRS="${DIRS%,}"');
+  lines.push('printf \'SYNC_INVENTORY={"files":[%s],"directories":[%s],"agentsRoot":%s,"authFile":%s}\\n\' "$FILES" "$DIRS" "$AGENTS" "$AUTH"');
+  lines.push('exit 0');
+  return lines.join('\n');
+};
+
+/**
+ * Stream a remote tar.gz of selected config paths to stdout.
+ * @param {{ files?: { path: string }[], directories?: { path: string }[] }} plan
+ */
+export const buildRemoteConfigTarScript = (plan) => {
+  const entries = [
+    ...(Array.isArray(plan?.files) ? plan.files.map((entry) => entry.path) : []),
+    ...(Array.isArray(plan?.directories) ? plan.directories.map((entry) => entry.path) : []),
+  ];
+  if (entries.length === 0) {
+    return "printf '' ; exit 0";
+  }
+  const quotedEntries = entries.map((rel) => shellQuote(rel)).join(' ');
+  return [
+    'set -e',
+    'CFG="$HOME/.config/opencode"',
+    `cd "$CFG" && tar -h -czf - ${quotedEntries}`,
+  ].join('\n');
+};
+
+export const buildRemoteAgentsTarScript = () => [
+  'set -e',
+  'cd "$HOME" && tar -h -czf - .agents',
+].join('\n');
+
+export const buildRemoteAuthTarScript = () => [
+  'set -e',
+  'cd "$HOME/.local/share/opencode" && tar -h -czf - auth.json',
+].join('\n');
+
+export { shellQuote };

package/server/lib/config-sync/selections.js

@@ -0,0 +1,112 @@
+import { OPENCODE_CONFIG_SYNC_ALLOWLIST } from './constants.js';
+
+/**
+ * @typedef {{
+ *   fileGroups: boolean[],
+ *   singleFiles: boolean[],
+ *   directories: boolean[],
+ *   agentsRoot: boolean,
+ *   authFile: boolean,
+ * }} SyncSelections
+ */
+
+/**
+ * Default: everything selected except authFile (credentials stay opt-in).
+ * @param {{ includeAuthFile?: boolean }} [options]
+ * @returns {SyncSelections}
+ */
+export const buildDefaultSyncSelections = (options = {}) => ({
+  fileGroups: OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.map(() => true),
+  singleFiles: OPENCODE_CONFIG_SYNC_ALLOWLIST.singleFiles.map(() => true),
+  directories: OPENCODE_CONFIG_SYNC_ALLOWLIST.directories.map(() => true),
+  agentsRoot: true,
+  authFile: options.includeAuthFile === true,
+});
+
+/**
+ * Normalize a partial selections object against the allowlist shape.
+ * @param {Partial<SyncSelections> | null | undefined} raw
+ * @param {{ includeAuthFile?: boolean }} [options]
+ * @returns {SyncSelections}
+ */
+export const normalizeSyncSelections = (raw, options = {}) => {
+  const defaults = buildDefaultSyncSelections(options);
+  if (!raw || typeof raw !== 'object') return defaults;
+
+  const fileGroups = OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.map((_, index) => (
+    Array.isArray(raw.fileGroups) ? raw.fileGroups[index] !== false : defaults.fileGroups[index]
+  ));
+  const singleFiles = OPENCODE_CONFIG_SYNC_ALLOWLIST.singleFiles.map((_, index) => (
+    Array.isArray(raw.singleFiles) ? raw.singleFiles[index] !== false : defaults.singleFiles[index]
+  ));
+  const directories = OPENCODE_CONFIG_SYNC_ALLOWLIST.directories.map((_, index) => (
+    Array.isArray(raw.directories) ? raw.directories[index] !== false : defaults.directories[index]
+  ));
+
+  return {
+    fileGroups,
+    singleFiles,
+    directories,
+    agentsRoot: raw.agentsRoot !== false,
+    authFile: raw.authFile === true,
+  };
+};
+
+/**
+ * Filter a full plan down to the selected allowlist groups.
+ * Mutual-exclusion within a fileGroup is preserved (plan already picked a winner).
+ * @param {object} plan
+ * @param {SyncSelections} selections
+ */
+export const filterPlanBySelections = (plan, selections) => {
+  const selected = normalizeSyncSelections(selections, { includeAuthFile: selections?.authFile === true });
+  const selectedFileNames = new Set();
+  const selectedDeleteNames = new Set();
+
+  OPENCODE_CONFIG_SYNC_ALLOWLIST.fileGroups.forEach((group, index) => {
+    if (!selected.fileGroups[index]) return;
+    for (const name of group) {
+      selectedFileNames.add(name);
+      selectedDeleteNames.add(name);
+    }
+  });
+  OPENCODE_CONFIG_SYNC_ALLOWLIST.singleFiles.forEach((name, index) => {
+    if (!selected.singleFiles[index]) return;
+    selectedFileNames.add(name);
+  });
+
+  const selectedDirNames = new Set();
+  const selectedDirLegacy = new Set();
+  OPENCODE_CONFIG_SYNC_ALLOWLIST.directories.forEach((dirSpec, index) => {
+    if (!selected.directories[index]) return;
+    selectedDirNames.add(dirSpec.path);
+    selectedDeleteNames.add(dirSpec.path);
+    if (typeof dirSpec.legacy === 'string' && dirSpec.legacy) {
+      selectedDirLegacy.add(dirSpec.legacy);
+      selectedDeleteNames.add(dirSpec.legacy);
+    }
+  });
+
+  const files = (Array.isArray(plan?.files) ? plan.files : []).filter((entry) => selectedFileNames.has(entry.path));
+  const directories = (Array.isArray(plan?.directories) ? plan.directories : []).filter((entry) => selectedDirNames.has(entry.path));
+  const deletes = (Array.isArray(plan?.deletes) ? plan.deletes : []).filter((name) => selectedDeleteNames.has(name) || selectedDirLegacy.has(name));
+  const agentsRoot = selected.agentsRoot ? (plan?.agentsRoot ?? null) : null;
+  const authFile = selected.authFile ? (plan?.authFile ?? null) : null;
+
+  let totalBytes = 0;
+  for (const entry of files) totalBytes += Number(entry.bytes) || 0;
+  for (const entry of directories) totalBytes += Number(entry.bytes) || 0;
+  if (agentsRoot) totalBytes += Number(agentsRoot.bytes) || 0;
+  if (authFile) totalBytes += Number(authFile.bytes) || 0;
+
+  return {
+    ...plan,
+    files,
+    directories,
+    deletes,
+    agentsRoot,
+    authFile,
+    totalBytes,
+    selections: selected,
+  };
+};

package/server/lib/config-sync/tar.js

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Collect stdout from a local `tar …` into a Buffer.
+ *
+ * Callers buffer the entire archive in memory; TargetExecutor.putTar accepts
+ * Buffer | Uint8Array only.
+ *
+ * @param {string[]} tarArgs
+ * @param {{ windowsHide?: boolean }} [spawnOptions]
+ * @returns {Promise<Buffer>}
+ */
+export const collectLocalTarBuffer = (tarArgs, spawnOptions = {}) => new Promise((resolve, reject) => {
+  const child = spawn('tar', tarArgs, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...(spawnOptions.windowsHide ? { windowsHide: true } : {}),
+  });
+  /** @type {Buffer[]} */
+  const chunks = [];
+  let stderr = '';
+  child.stdout?.on('data', (chunk) => {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+  child.stderr?.on('data', (chunk) => {
+    stderr += chunk.toString();
+  });
+  child.on('error', reject);
+  child.on('close', (code) => {
+    if (code !== 0) {
+      reject(new Error((stderr || 'Local tar failed').trim()));
+      return;
+    }
+    resolve(Buffer.concat(chunks));
+  });
+});

package/server/lib/config-sync/target-id.js

@@ -0,0 +1,24 @@
+/** @param {string} instanceId */
+export const syncTargetIdForSshInstance = (instanceId) => {
+  const id = String(instanceId || '').trim();
+  if (!id) throw new Error('SSH instance id is required');
+  return `ssh:${id}`;
+};
+
+/** @param {string} hostId */
+export const syncTargetIdForDirectHost = (hostId) => {
+  const id = String(hostId || '').trim();
+  if (!id) throw new Error('Desktop host id is required');
+  return `host:${id}`;
+};
+
+/**
+ * @param {string} serverId relay host signing-key fingerprint
+ * Mirrored in packages/ui/src/lib/relay/relay-config-sync.ts (browser bundle cannot
+ * import this server module); keep both sides in sync when changing the prefix.
+ */
+export const syncTargetIdForRelayServer = (serverId) => {
+  const id = String(serverId || '').trim();
+  if (!id) throw new Error('Relay serverId is required');
+  return `relay:${id}`;
+};

package/server/lib/event-stream/DOCUMENTATION.md

@@ -9,7 +9,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - `packages/web/server/lib/event-stream/global-ws-bridge.js`: browser-facing global WS bridge that subscribes clients to the shared global hub.
 - `packages/web/server/lib/event-stream/directory-ws-bridge.js`: browser-facing per-directory WS bridge that owns one scoped upstream reader per connection.
 - `packages/web/server/lib/event-stream/protocol.js`: path constants, SSE envelope parsing, and WebSocket frame serialization helpers.
-- `packages/web/server/lib/event-stream/diff-summary.js`: pure outbound FileDiff summarization (drops patch/before/after/from/to; keeps file/status/additions/deletions).
+- `packages/web/server/lib/event-stream/diff-summary.js`: pure outbound FileDiff helpers. L1 message/session `summary.diffs` project to `diffCount`/`hasDiffs` (array removed). `session.diff` event frames still keep file/status/additions/deletions and drop patch bodies. `summarizeFileDiff(s)` remains for explicit L2-style file lists.
 - `packages/web/server/lib/event-stream/upstream-reader.js`: reusable upstream SSE reader with event-id tracking, stall recovery, and reconnect handling.
 - `packages/web/server/lib/event-stream/runtime.js`: thin WebSocket server runtime for upgrade handling and path dispatch to the global/directory bridges.
 - `packages/web/server/lib/event-stream/protocol.test.js`: unit tests for protocol helpers.
@@ -26,7 +26,7 @@ The following APIs are exported by their owning modules. `event-stream/index.js`
 - `MESSAGE_STREAM_WS_HEARTBEAT_INTERVAL_MS`: heartbeat interval for browser-facing WS connections.
 - `parseSseEventEnvelope(block)`: parses an SSE block into `{ eventId, directory, payload }`.
 - `sendMessageStreamWsFrame(socket, payload)`: serializes and sends a JSON WS frame.
-- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId` and `directory`. Outbound `session.diff` and message/session `summary.diffs` are summarized to file/status/additions/deletions only (no full patch bodies).
+- `sendMessageStreamWsEvent(socket, payload, options)`: sends an event frame with optional `eventId` and `directory`. Outbound `session.diff` keeps file/status/additions/deletions only (no full patch bodies). Message/session `summary.diffs` are L1-projected to `diffCount`/`hasDiffs` (file array removed).
 
 ### Runtime helpers
 - `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.

package/server/lib/event-stream/diff-summary.js

@@ -1,9 +1,12 @@
 // ---------------------------------------------------------------------------
-// Outbound FileDiff summarization for message-stream fan-out.
+// Outbound FileDiff summarization for message-stream fan-out and Host L1.
 //
-// Mirrors packages/ui/src/sync/sanitize.ts summarizeFileDiff(s) so Host never
-// pushes full patch/before/after/from/to blobs over Relay/WS (>64KB frames).
-// Pure JS — do not import UI TypeScript from the server package.
+// L1 (ordinary first-packet / SSE / exact message GET):
+//   project `info.summary.diffs` arrays to `{ diffCount, hasDiffs }` and remove
+//   the file array entirely. Never ship patch bodies on these paths.
+//
+// Explicit L2/L3 APIs may still use summarizeFileDiff(s) for file-list / patch
+// responses. Pure JS — do not import UI TypeScript from the server package.
 // ---------------------------------------------------------------------------
 
 /** Lightweight FileDiff fields safe for outbound event frames (preview only). */
@@ -25,6 +28,9 @@ const hasHeavyDiffBody = (diff) => {
  * Reduce a FileDiff / SnapshotFileDiff to preview-safe scalars only.
  * Drops patch / before / after / from / to and any other large body fields.
  * Already-summary objects keep identity.
+ *
+ * Retained for explicit L2 file-list APIs; L1 message paths must use
+ * `projectMessageSummaryDiffCounts` instead and never keep a file array.
  */
 export function summarizeFileDiff(diff) {
   if (!diff || typeof diff !== 'object' || Array.isArray(diff)) {
@@ -62,7 +68,14 @@ export function summarizeFileDiffs(diffs) {
   return changed ? next : diffs;
 }
 
-const summarizeSummaryDiffs = (owner) => {
+/**
+ * L1 projection: replace `summary.diffs` with count/marker scalars.
+ * Keeps every other lightweight summary field. Identity when unchanged.
+ *
+ * @param {unknown} owner message info / session info / summary-bearing object
+ * @returns {unknown}
+ */
+export const projectMessageSummaryDiffCounts = (owner) => {
   if (!owner || typeof owner !== 'object' || Array.isArray(owner)) {
     return owner;
   }
@@ -72,30 +85,36 @@ const summarizeSummaryDiffs = (owner) => {
     return owner;
   }
 
-  if (!Array.isArray(summary.diffs)) {
+  if (!Object.prototype.hasOwnProperty.call(summary, 'diffs')) {
     return owner;
   }
 
-  const stripped = summarizeFileDiffs(summary.diffs);
-  if (stripped === summary.diffs) {
-    return owner;
-  }
+  const diffs = summary.diffs;
+  const diffCount = Array.isArray(diffs) ? diffs.length : 0;
+  const hasDiffs = diffCount > 0;
+
+  const nextSummary = { ...summary };
+  delete nextSummary.diffs;
+  nextSummary.diffCount = diffCount;
+  nextSummary.hasDiffs = hasDiffs;
 
   return {
     ...owner,
-    summary: {
-      ...summary,
-      diffs: stripped,
-    },
+    summary: nextSummary,
   };
 };
 
+/** @deprecated Prefer projectMessageSummaryDiffCounts — L1 removes the file array. */
+export const summarizeMessageDiffSnapshots = projectMessageSummaryDiffCounts;
+
 /**
  * Summarize FileDiff bodies on outbound event payloads.
  *
  * Handles:
  * - `session.diff` with legacy `properties.diff` or current `data.diff`
+ *   (keeps file/status/additions/deletions; drops patch bodies)
  * - message/session objects carrying `summary.diffs` under properties/data info
+ *   (L1: projects to diffCount/hasDiffs and removes the array)
  *
  * Non-diff events keep identity.
  */
@@ -154,7 +173,7 @@ export function summarizeOutboundEventPayload(payload) {
 
       // Common shape: properties.info.summary.diffs
       if (body.info && typeof body.info === 'object' && !Array.isArray(body.info)) {
-        const nextInfo = summarizeSummaryDiffs(body.info);
+        const nextInfo = projectMessageSummaryDiffCounts(body.info);
         if (nextInfo !== body.info) {
           next = {
             ...next,
@@ -169,7 +188,7 @@ export function summarizeOutboundEventPayload(payload) {
       }
 
       // Rare: properties.summary.diffs directly on the properties/data body
-      const nextBody = summarizeSummaryDiffs(body);
+      const nextBody = projectMessageSummaryDiffCounts(body);
       if (nextBody !== body) {
         next = {
           ...next,

package/server/lib/event-stream/diff-summary.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+  projectMessageSummaryDiffCounts,
   summarizeFileDiff,
   summarizeFileDiffs,
   summarizeOutboundEventPayload,
@@ -48,6 +49,45 @@ describe('summarizeFileDiffs', () => {
   });
 });
 
+describe('projectMessageSummaryDiffCounts', () => {
+  it('replaces summary.diffs with diffCount/hasDiffs and drops the array', () => {
+    const owner = {
+      id: 'msg_1',
+      summary: {
+        title: 'turn',
+        diffs: [
+          { file: 'a.ts', additions: 1, deletions: 0, patch: '@@' },
+          { file: 'b.ts', additions: 2, deletions: 1 },
+        ],
+      },
+    };
+
+    const next = projectMessageSummaryDiffCounts(owner);
+    expect(next).not.toBe(owner);
+    expect(next.summary).toEqual({
+      title: 'turn',
+      diffCount: 2,
+      hasDiffs: true,
+    });
+    expect(next.summary.diffs).toBeUndefined();
+  });
+
+  it('projects empty arrays to diffCount 0 / hasDiffs false', () => {
+    const owner = {
+      summary: { diffs: [] },
+    };
+    expect(projectMessageSummaryDiffCounts(owner).summary).toEqual({
+      diffCount: 0,
+      hasDiffs: false,
+    });
+  });
+
+  it('keeps identity when summary has no diffs key', () => {
+    const owner = { summary: { title: 'x', diffCount: 3, hasDiffs: true } };
+    expect(projectMessageSummaryDiffCounts(owner)).toBe(owner);
+  });
+});
+
 describe('summarizeOutboundEventPayload', () => {
   it('summarizes session.diff properties.diff', () => {
     const payload = {
@@ -97,7 +137,7 @@ describe('summarizeOutboundEventPayload', () => {
     }]);
   });
 
-  it('summarizes message.updated info.summary.diffs', () => {
+  it('projects message.updated info.summary.diffs to L1 count/marker', () => {
     const payload = {
       type: 'message.updated',
       properties: {
@@ -116,11 +156,11 @@ describe('summarizeOutboundEventPayload', () => {
     };
 
     const next = summarizeOutboundEventPayload(payload);
-    expect(next.properties.info.summary.diffs).toEqual([{
-      file: 'a.ts',
-      additions: 1,
-      deletions: 0,
-    }]);
+    expect(next.properties.info.summary).toEqual({
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    expect(next.properties.info.summary.diffs).toBeUndefined();
   });
 
   it('returns identity for session.status', () => {

package/server/lib/event-stream/protocol.test.js

@@ -223,7 +223,7 @@ describe('event stream protocol helpers', () => {
     expect(rawPayload.length).toBeLessThan(64 * 1024);
   });
 
-  it('summarizes message.updated summary.diffs patches on outbound frames', () => {
+  it('projects message.updated summary.diffs to L1 count/marker on outbound frames', () => {
     let rawPayload = null;
     const socket = {
       readyState: 1,
@@ -254,13 +254,13 @@ describe('event stream protocol helpers', () => {
 
     expect(sent).toBe(true);
     const frame = JSON.parse(rawPayload);
-    expect(frame.payload.properties.info.summary.diffs).toEqual([{
-      file: 'a.ts',
-      status: 'modified',
-      additions: 2,
-      deletions: 1,
-    }]);
+    expect(frame.payload.properties.info.summary).toEqual({
+      diffCount: 1,
+      hasDiffs: true,
+    });
+    expect(frame.payload.properties.info.summary.diffs).toBeUndefined();
     expect(JSON.stringify(frame)).not.toContain('patch');
+    expect(JSON.stringify(frame)).not.toContain('a.ts');
   });
 
   it('leaves ordinary session.status events unchanged', () => {