Bound retained workspaces and expose runtime memory

src/config.test.ts

@@ -28,6 +28,12 @@ assert.equal(loadConfig(baseEnv).devspaceAgentsDir, join(emptyConfigDir, "agents
 assert.equal(loadConfig(baseEnv).subagents, false);
 assert.equal(loadConfig(baseEnv).artifactsEnabled, false);
 assert.equal(loadConfig(baseEnv).artifactMaxFileBytes, 100 * 1024 * 1024);
+assert.equal(loadConfig(baseEnv).heapSnapshotThresholdBytes, undefined);
+assert.equal(
+  loadConfig({ ...baseEnv, DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES: "1073741824" })
+    .heapSnapshotThresholdBytes,
+  1024 * 1024 * 1024,
+);
 assert.equal(loadConfig({ ...baseEnv, DEVSPACE_ARTIFACTS: "1" }).artifactsEnabled, true);
 assert.equal(
   loadConfig({ ...baseEnv, DEVSPACE_ARTIFACT_MAX_FILE_BYTES: "123" }).artifactMaxFileBytes,
@@ -67,6 +73,10 @@ assert.throws(
   () => loadConfig({ ...baseEnv, DEVSPACE_TOOL_MODE: "invalid" }),
   /Invalid DEVSPACE_TOOL_MODE: invalid/,
 );
+assert.throws(
+  () => loadConfig({ ...baseEnv, DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES: "0" }),
+  /Invalid DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES: 0/,
+);
 
 assert.deepEqual(loadConfig(baseEnv).logging, {
   level: "info",

src/config.ts

@@ -24,6 +24,7 @@ export interface ServerConfig {
   worktreeRoot: string;
   artifactsEnabled: boolean;
   artifactMaxFileBytes: number;
+  heapSnapshotThresholdBytes?: number;
   skillsEnabled: boolean;
   skillPaths: string[];
   devspaceSkillsDir: string;
@@ -243,6 +244,14 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
       DEFAULT_ARTIFACT_MAX_FILE_BYTES,
       "DEVSPACE_ARTIFACT_MAX_FILE_BYTES",
     ),
+    heapSnapshotThresholdBytes:
+      env.DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES === undefined
+        ? undefined
+        : parsePositiveInteger(
+            env.DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES,
+            1,
+            "DEVSPACE_HEAP_SNAPSHOT_THRESHOLD_BYTES",
+          ),
     skillsEnabled: env.DEVSPACE_SKILLS === undefined ? true : parseBoolean(env.DEVSPACE_SKILLS),
     skillPaths: parsePathList(env.DEVSPACE_SKILL_PATHS),
     devspaceSkillsDir: devspaceSkillsDir(env),

src/heap-snapshot-guard.ts

@@ -0,0 +1,88 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeHeapSnapshot } from "node:v8";
+
+const DEFAULT_CHECK_INTERVAL_MS = 5 * 60 * 1_000;
+const SNAPSHOT_PREFIX = "devspace-heap-";
+const SNAPSHOT_SUFFIX = ".heapsnapshot";
+
+export interface HeapSnapshotGuardOptions {
+  stateDir: string;
+  thresholdBytes: number;
+  intervalMs?: number;
+  memoryUsage?: () => Pick<NodeJS.MemoryUsage, "rss">;
+  now?: () => Date;
+  writeSnapshot?: (filename: string) => string;
+  onError?: (error: unknown) => void;
+}
+
+export interface HeapSnapshotGuard {
+  checkNow(): string | undefined;
+  stop(): void;
+}
+
+export function startHeapSnapshotGuard(
+  options: HeapSnapshotGuardOptions,
+): HeapSnapshotGuard {
+  const thresholdBytes = positiveInteger(options.thresholdBytes, "thresholdBytes");
+  const intervalMs = positiveInteger(
+    options.intervalMs ?? DEFAULT_CHECK_INTERVAL_MS,
+    "intervalMs",
+  );
+  const diagnosticsDir = join(options.stateDir, "diagnostics");
+  const memoryUsage = options.memoryUsage ?? process.memoryUsage;
+  const now = options.now ?? (() => new Date());
+  const writeSnapshot = options.writeSnapshot ?? writeHeapSnapshot;
+  let captured = hasExistingSnapshot(diagnosticsDir);
+  let timer: NodeJS.Timeout | undefined;
+
+  const stop = () => {
+    if (!timer) return;
+    clearInterval(timer);
+    timer = undefined;
+  };
+
+  const checkNow = (): string | undefined => {
+    if (captured || memoryUsage().rss < thresholdBytes) return undefined;
+
+    try {
+      mkdirSync(diagnosticsDir, { recursive: true, mode: 0o700 });
+      chmodSync(diagnosticsDir, 0o700);
+      const timestamp = now().toISOString().replaceAll(":", "-");
+      const filename = join(
+        diagnosticsDir,
+        `${SNAPSHOT_PREFIX}${timestamp}-${process.pid}${SNAPSHOT_SUFFIX}`,
+      );
+      const writtenPath = writeSnapshot(filename);
+      chmodSync(writtenPath, 0o600);
+      captured = true;
+      stop();
+      return writtenPath;
+    } catch (error) {
+      options.onError?.(error);
+      return undefined;
+    }
+  };
+
+  checkNow();
+  if (!captured) {
+    timer = setInterval(checkNow, intervalMs);
+    timer.unref();
+  }
+
+  return { checkNow, stop };
+}
+
+function hasExistingSnapshot(diagnosticsDir: string): boolean {
+  if (!existsSync(diagnosticsDir)) return false;
+  return readdirSync(diagnosticsDir).some(
+    (name) => name.startsWith(SNAPSHOT_PREFIX) && name.endsWith(SNAPSHOT_SUFFIX),
+  );
+}
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+  return value;
+}

src/process-sessions.ts

@@ -222,6 +222,10 @@ export class ProcessSessionManager {
     this.completedSessionTtlMs = options.completedSessionTtlMs ?? COMPLETED_SESSION_TTL_MS;
   }
 
+  get size(): number {
+    return this.sessions.size;
+  }
+
   async start(input: StartCommandInput): Promise<ProcessSnapshot> {
     const session = this.createSession(input);
     this.sessions.set(session.id, session);

src/server.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
 import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -8,10 +9,11 @@ import { promisify } from "node:util";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { loadConfig, type ServerConfig } from "./config.js";
+import { startHeapSnapshotGuard } from "./heap-snapshot-guard.js";
 import type { LocalAgentProviderAvailability } from "./local-agent-availability.js";
 import { createReviewCheckpointManager } from "./review-checkpoints.js";
 import { ProcessSessionManager } from "./process-sessions.js";
-import { createMcpServer } from "./server.js";
+import { createMcpServer, createServer } from "./server.js";
 import { SqliteWorkspaceStore } from "./workspace-store.js";
 import { WorkspaceRegistry } from "./workspaces.js";
 
@@ -183,6 +185,119 @@ test("checkout reuse and context suppression survive a registry restart", async
   }
 });
 
+test("heap snapshot guard captures one diagnostic after the configured threshold", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "devspace-heap-guard-test-"));
+  let rss = 512;
+  let writes = 0;
+  const guard = startHeapSnapshotGuard({
+    stateDir: root,
+    thresholdBytes: 1_024,
+    intervalMs: 60_000,
+    memoryUsage: () => ({ rss }),
+    now: () => new Date("2026-08-21T05:00:00.000Z"),
+    writeSnapshot: (filename) => {
+      writes += 1;
+      writeFileSync(filename, "snapshot");
+      return filename;
+    },
+  });
+  t.after(() => {
+    guard.stop();
+    return rm(root, { recursive: true, force: true });
+  });
+
+  assert.equal(guard.checkNow(), undefined);
+  rss = 2_048;
+  const snapshotPath = guard.checkNow();
+  assert.ok(snapshotPath);
+  assert.equal(existsSync(snapshotPath), true);
+  assert.equal(writes, 1);
+  assert.equal(guard.checkNow(), undefined);
+  assert.equal(writes, 1);
+
+  const restoredGuard = startHeapSnapshotGuard({
+    stateDir: root,
+    thresholdBytes: 1_024,
+    intervalMs: 60_000,
+    memoryUsage: () => ({ rss }),
+    writeSnapshot: (filename) => {
+      writes += 1;
+      writeFileSync(filename, "unexpected");
+      return filename;
+    },
+  });
+  restoredGuard.stop();
+  assert.equal(restoredGuard.checkNow(), undefined);
+  assert.equal(writes, 1);
+});
+
+test("health endpoint reports bounded runtime state without exposing paths", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "devspace-health-test-"));
+  const config = loadConfig({
+    DEVSPACE_CONFIG_DIR: join(root, ".config"),
+    DEVSPACE_STATE_DIR: join(root, ".state"),
+    DEVSPACE_ALLOWED_ROOTS: root,
+    DEVSPACE_WORKTREE_ROOT: join(root, ".worktrees"),
+    DEVSPACE_AGENT_DIR: join(root, "agent"),
+    DEVSPACE_OAUTH_OWNER_TOKEN: "test-owner-token-that-is-long-enough",
+    DEVSPACE_LOG_LEVEL: "silent",
+    PORT: "1",
+  });
+  const running = createServer(config, { incomingArtifactAdapters: [] });
+  const httpServer = running.app.listen(0, "127.0.0.1");
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once("listening", resolve);
+    httpServer.once("error", reject);
+  });
+  t.after(async () => {
+    await new Promise<void>((resolve, reject) => {
+      httpServer.close((error) => (error ? reject(error) : resolve()));
+    });
+    await running.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const address = httpServer.address();
+  assert.ok(address && typeof address === "object");
+  const response = await fetch(`http://127.0.0.1:${address.port}/healthz`);
+  assert.equal(response.status, 200);
+  const body = (await response.json()) as {
+    ok: boolean;
+    name: string;
+    memory: Record<string, number>;
+    sessions: {
+      mcp: number;
+      process: number;
+      workspaceCache: {
+        cachedWorkspaces: number;
+        maxCachedWorkspaces: number;
+        workspaceIdleTimeoutMs: number;
+        oldestIdleMs: number;
+      };
+      persistedWorkspaces: number;
+      conversationBindings: number;
+    };
+  };
+
+  assert.equal(body.ok, true);
+  assert.equal(body.name, "devspace");
+  assert.ok(body.memory.rssBytes > 0);
+  assert.ok(body.memory.heapUsedBytes > 0);
+  assert.deepEqual(body.sessions, {
+    mcp: 0,
+    process: 0,
+    workspaceCache: {
+      cachedWorkspaces: 0,
+      maxCachedWorkspaces: 32,
+      workspaceIdleTimeoutMs: 60 * 60 * 1_000,
+      oldestIdleMs: 0,
+    },
+    persistedWorkspaces: 0,
+    conversationBindings: 0,
+  });
+  assert.equal(JSON.stringify(body).includes(root), false);
+});
+
 interface ServerFixture {
   client: Client;
   project: string;