@akira-tl/forgerelay 0.3.6 → 0.4.0

package/dist/lsp/language-server-config.js

@@ -0,0 +1,313 @@
+import { access, readFile, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+export class LanguageServerConfigurationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LanguageServerConfigurationError";
+    }
+}
+const definitionSchema = z.object({
+    enabled: z.boolean().optional(),
+    command: z.string().min(1).optional(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    languages: z.array(z.string().min(1)).min(1).optional(),
+    extensions: z.array(z.string().regex(/^\./)).min(1).optional(),
+    languageIdByExtension: z.record(z.string().regex(/^\./), z.string().min(1)).optional(),
+    projectMarkers: z.array(z.string().min(1)).optional(),
+}).strict();
+const configSchema = z.record(z.string().min(1), definitionSchema);
+const BUILTIN_DEFINITIONS = {
+    typescript: {
+        executableCandidates: ["typescript-language-server"],
+        args: ["--stdio"],
+        languages: ["typescript", "typescriptreact", "javascript", "javascriptreact"],
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+        languageIdByExtension: {
+            ".ts": "typescript",
+            ".tsx": "typescriptreact",
+            ".js": "javascript",
+            ".jsx": "javascriptreact",
+            ".mjs": "javascript",
+            ".cjs": "javascript",
+        },
+        projectMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+    },
+    pyright: {
+        executableCandidates: ["pyright-langserver"],
+        args: ["--stdio"],
+        languages: ["python"],
+        extensions: [".py", ".pyi"],
+        languageIdByExtension: { ".py": "python", ".pyi": "python" },
+        projectMarkers: ["pyrightconfig.json", "pyproject.toml", "setup.cfg", "setup.py"],
+    },
+    "rust-analyzer": {
+        executableCandidates: ["rust-analyzer"],
+        languages: ["rust"],
+        extensions: [".rs"],
+        languageIdByExtension: { ".rs": "rust" },
+        projectMarkers: ["Cargo.toml"],
+    },
+    gopls: {
+        executableCandidates: ["gopls"],
+        languages: ["go"],
+        extensions: [".go"],
+        languageIdByExtension: { ".go": "go" },
+        projectMarkers: ["go.work", "go.mod"],
+    },
+    clangd: {
+        executableCandidates: ["clangd"],
+        languages: ["c", "cpp", "objective-c", "objective-cpp"],
+        extensions: [".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".m", ".mm"],
+        languageIdByExtension: {
+            ".c": "c",
+            ".cc": "cpp",
+            ".cpp": "cpp",
+            ".cxx": "cpp",
+            ".h": "cpp",
+            ".hh": "cpp",
+            ".hpp": "cpp",
+            ".hxx": "cpp",
+            ".m": "objective-c",
+            ".mm": "objective-cpp",
+        },
+        projectMarkers: ["compile_commands.json", "compile_flags.txt", ".clangd"],
+    },
+};
+export async function resolveLanguageProject(input) {
+    const workspaceRoot = await canonicalWorkspaceRoot(input.workspaceRoot);
+    const sourcePath = await resolveWorkspaceSourcePath(workspaceRoot, input.sourcePath);
+    const projectConfig = await loadProjectLanguageServerConfig(workspaceRoot);
+    const globalConfig = parseLanguageServerConfig(input.globalConfig ?? {}, "global ForgeRelay config");
+    const definitions = await effectiveDefinitions(globalConfig, projectConfig, input.env ?? process.env);
+    const extension = extname(sourcePath).toLowerCase();
+    const candidates = [];
+    for (const definition of definitions) {
+        if (!definition.extensions.includes(extension))
+            continue;
+        const projectRoot = await findLanguageProjectRoot(workspaceRoot, dirname(sourcePath), definition.projectMarkers);
+        if (!projectRoot)
+            continue;
+        candidates.push({ definition, projectRoot });
+    }
+    if (candidates.length === 0) {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `No available Language-server definition matches ${relative(workspaceRoot, sourcePath) || "."}.`);
+    }
+    const sourceRank = { builtin: 0, global: 1, project: 2 };
+    const highestRank = Math.max(...candidates.map((candidate) => sourceRank[candidate.definition.source]));
+    const highest = candidates.filter((candidate) => sourceRank[candidate.definition.source] === highestRank);
+    const deepestLength = Math.max(...highest.map((candidate) => candidate.projectRoot.length));
+    const nearest = highest.filter((candidate) => candidate.projectRoot.length === deepestLength);
+    if (nearest.length !== 1) {
+        throw new LanguageServerConfigurationError("code.configuration_ambiguous", `Multiple Language-server definitions match ${relative(workspaceRoot, sourcePath)} at the same priority: ${nearest.map((candidate) => candidate.definition.id).join(", ")}.`);
+    }
+    return nearest[0];
+}
+export async function loadProjectLanguageServerConfig(workspaceRoot) {
+    const path = join(workspaceRoot, ".forgerelay", "language-servers.json");
+    try {
+        return parseLanguageServerConfig(JSON.parse(await readFile(path, "utf8")), path);
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return {};
+        if (error instanceof LanguageServerConfigurationError)
+            throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Unable to load Language-server configuration at ${path}: ${reason}`);
+    }
+}
+export function parseLanguageServerConfig(value, label) {
+    const parsed = configSchema.safeParse(value ?? {});
+    if (!parsed.success) {
+        const details = parsed.error.issues
+            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+            .join("; ");
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Invalid Language-server configuration in ${label}: ${details}`);
+    }
+    return parsed.data;
+}
+async function effectiveDefinitions(globalConfig, projectConfig, env) {
+    const ids = new Set([
+        ...Object.keys(BUILTIN_DEFINITIONS),
+        ...Object.keys(globalConfig),
+        ...Object.keys(projectConfig),
+    ]);
+    const definitions = [];
+    for (const id of ids) {
+        const builtin = BUILTIN_DEFINITIONS[id];
+        const global = globalConfig[id];
+        const project = projectConfig[id];
+        const source = project
+            ? "project"
+            : global
+                ? "global"
+                : "builtin";
+        const merged = {
+            id,
+            source,
+            ...(builtin ?? {}),
+            ...(global ?? {}),
+            ...(project ?? {}),
+            env: {
+                ...(builtin?.env ?? {}),
+                ...(global?.env ?? {}),
+                ...(project?.env ?? {}),
+            },
+            languageIdByExtension: {
+                ...(builtin?.languageIdByExtension ?? {}),
+                ...(global?.languageIdByExtension ?? {}),
+                ...(project?.languageIdByExtension ?? {}),
+            },
+        };
+        if (merged.enabled === false)
+            continue;
+        const languages = merged.languages ?? [];
+        const extensions = merged.extensions?.map((entry) => entry.toLowerCase()) ?? [];
+        if (languages.length === 0 || extensions.length === 0)
+            continue;
+        const languageIdByExtension = normalizeLanguageIds(id, merged, languages, extensions);
+        let command = merged.command;
+        if (!command && builtin?.executableCandidates) {
+            command = await findExecutable(builtin.executableCandidates, env);
+            if (!command)
+                continue;
+        }
+        if (!command) {
+            throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} requires a command.`);
+        }
+        const normalized = {
+            id,
+            command,
+            args: merged.args ?? [],
+            env: merged.env ?? {},
+            languages,
+            extensions,
+            languageIdByExtension,
+            projectMarkers: merged.projectMarkers ?? [],
+            source,
+        };
+        definitions.push({
+            ...normalized,
+            fingerprint: createHash("sha256").update(JSON.stringify(normalized)).digest("hex"),
+        });
+    }
+    return definitions;
+}
+function normalizeLanguageIds(id, definition, languages, extensions) {
+    const mapping = Object.fromEntries(Object.entries(definition.languageIdByExtension ?? {})
+        .map(([extension, languageId]) => [extension.toLowerCase(), languageId]));
+    for (let index = 0; index < extensions.length; index += 1) {
+        const extension = extensions[index];
+        if (mapping[extension])
+            continue;
+        if (languages.length === 1) {
+            mapping[extension] = languages[0];
+            continue;
+        }
+        if (languages.length === extensions.length) {
+            mapping[extension] = languages[index];
+            continue;
+        }
+        throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} must map extension ${extension} to a languageId when multiple language IDs do not align one-to-one with extensions.`);
+    }
+    for (const [extension, languageId] of Object.entries(mapping)) {
+        if (!extensions.includes(extension))
+            continue;
+        if (!languages.includes(languageId)) {
+            throw new LanguageServerConfigurationError("code.configuration_invalid", `Language-server definition ${id} maps ${extension} to unknown languageId ${languageId}.`);
+        }
+    }
+    return mapping;
+}
+async function findLanguageProjectRoot(workspaceRoot, startDirectory, markers) {
+    if (markers.length === 0)
+        return workspaceRoot;
+    let current = startDirectory;
+    while (isWithin(workspaceRoot, current)) {
+        for (const marker of markers) {
+            try {
+                await access(join(current, marker));
+                return current;
+            }
+            catch {
+                // Try the next marker or parent directory.
+            }
+        }
+        if (current === workspaceRoot)
+            break;
+        current = dirname(current);
+    }
+    return undefined;
+}
+async function canonicalWorkspaceRoot(inputPath) {
+    try {
+        return await realpath(resolve(inputPath));
+    }
+    catch {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence Workspace root does not exist: ${inputPath}`);
+    }
+}
+async function resolveWorkspaceSourcePath(workspaceRoot, inputPath) {
+    const candidate = resolve(workspaceRoot, inputPath);
+    if (!isWithin(workspaceRoot, candidate)) {
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path must remain inside the Workspace: ${inputPath}`);
+    }
+    try {
+        const [canonicalRoot, canonicalCandidate] = await Promise.all([
+            realpath(workspaceRoot),
+            realpath(candidate),
+        ]);
+        if (!isWithin(canonicalRoot, canonicalCandidate)) {
+            throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path resolves outside the Workspace: ${inputPath}`);
+        }
+        return canonicalCandidate;
+    }
+    catch (error) {
+        if (error instanceof LanguageServerConfigurationError)
+            throw error;
+        throw new LanguageServerConfigurationError("code.language_service_unavailable", `Code-intelligence source path does not exist: ${inputPath}`);
+    }
+}
+async function findExecutable(candidates, env) {
+    for (const candidate of candidates) {
+        if (isAbsolute(candidate)) {
+            if (await executable(candidate))
+                return candidate;
+            continue;
+        }
+        const pathEntries = (env.PATH ?? "").split(delimiter).filter(Boolean);
+        const extensions = process.platform === "win32"
+            ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+            : [""];
+        for (const directory of pathEntries) {
+            for (const extension of extensions) {
+                const path = join(directory, process.platform === "win32" ? `${candidate}${extension}` : candidate);
+                if (await executable(path))
+                    return path;
+            }
+        }
+    }
+    return undefined;
+}
+async function executable(path) {
+    try {
+        await access(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/lsp/position-encoding.js

@@ -0,0 +1,88 @@
+import { PositionEncodingKind } from "vscode-languageserver-protocol";
+import { CodeIntelligenceError } from "./code-intelligence-error.js";
+export function lspPositionFromUser(text, line, column, encoding) {
+    if (!Number.isInteger(line) || line < 1 || !Number.isInteger(column) || column < 1) {
+        throw new CodeIntelligenceError("code.invalid_position", `Code-intelligence positions are 1-based positive integers; received line=${line}, column=${column}.`);
+    }
+    const lines = text.split(/\r?\n/);
+    const sourceLine = lines[line - 1];
+    if (sourceLine === undefined) {
+        throw new CodeIntelligenceError("code.invalid_position", `Line ${line} is outside the document (${lines.length} lines).`);
+    }
+    const codePoints = Array.from(sourceLine);
+    const codePointIndex = column - 1;
+    if (codePointIndex > codePoints.length) {
+        throw new CodeIntelligenceError("code.invalid_position", `Column ${column} is outside line ${line} (${codePoints.length + 1} valid insertion positions).`);
+    }
+    const prefix = codePoints.slice(0, codePointIndex).join("");
+    return {
+        line: line - 1,
+        character: encodedLength(prefix, encoding),
+    };
+}
+export function wholeDocumentRange(text, encoding) {
+    const lines = text.split(/\r?\n/);
+    const lastLine = Math.max(0, lines.length - 1);
+    return {
+        start: { line: 0, character: 0 },
+        end: {
+            line: lastLine,
+            character: encodedLength(lines[lastLine] ?? "", encoding),
+        },
+    };
+}
+export function rangeFromLsp(text, range, encoding) {
+    return {
+        start: positionFromLsp(text, range.start, encoding),
+        end: positionFromLsp(text, range.end, encoding),
+    };
+}
+function positionFromLsp(text, position, encoding) {
+    const lines = text.split(/\r?\n/);
+    const sourceLine = lines[position.line];
+    if (sourceLine === undefined) {
+        throw new CodeIntelligenceError("code.invalid_position", `Language server returned line ${position.line} outside a ${lines.length}-line document.`);
+    }
+    return {
+        line: position.line + 1,
+        column: decodedCodePointOffset(sourceLine, position.character, encoding) + 1,
+    };
+}
+function encodedLength(text, encoding) {
+    if (encoding === PositionEncodingKind.UTF8)
+        return Buffer.byteLength(text, "utf8");
+    if (encoding === PositionEncodingKind.UTF32)
+        return Array.from(text).length;
+    return text.length;
+}
+function decodedCodePointOffset(text, encodedOffset, encoding) {
+    if (!Number.isInteger(encodedOffset) || encodedOffset < 0) {
+        throw new CodeIntelligenceError("code.invalid_position", `Language server returned invalid character offset ${encodedOffset}.`);
+    }
+    if (encoding === PositionEncodingKind.UTF32) {
+        if (encodedOffset > Array.from(text).length) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+        }
+        return encodedOffset;
+    }
+    if (encoding === PositionEncodingKind.UTF16) {
+        if (encodedOffset > text.length) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+        }
+        return Array.from(text.slice(0, encodedOffset)).length;
+    }
+    let bytes = 0;
+    let codePoints = 0;
+    for (const character of text) {
+        if (bytes === encodedOffset)
+            return codePoints;
+        bytes += Buffer.byteLength(character, "utf8");
+        codePoints += 1;
+        if (bytes > encodedOffset) {
+            throw new CodeIntelligenceError("code.invalid_position", `Language server returned UTF-8 offset ${encodedOffset} inside a code point.`);
+        }
+    }
+    if (bytes === encodedOffset)
+        return codePoints;
+    throw new CodeIntelligenceError("code.invalid_position", `Language server returned character offset ${encodedOffset} outside its line.`);
+}

package/dist/mcp-sessions.js

@@ -1,8 +1,14 @@
 export class McpTransportRegistry {
     transports = new Map();
     now;
+    maxTransports;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
+        this.maxTransports = options.maxTransports ?? Number.POSITIVE_INFINITY;
+        if (this.maxTransports !== Number.POSITIVE_INFINITY &&
+            (!Number.isInteger(this.maxTransports) || this.maxTransports < 1)) {
+            throw new Error("MCP transport limit must be a positive integer.");
+        }
     }
     get size() {
         return this.transports.size;
@@ -12,6 +18,30 @@ export class McpTransportRegistry {
             transport,
             lastActivityAt: this.now(),
         });
+        const excess = [];
+        while (this.transports.size > this.maxTransports) {
+            let oldestTransportSessionId;
+            let oldestActivityAt = Number.POSITIVE_INFINITY;
+            for (const [candidateSessionId, entry] of this.transports) {
+                if (candidateSessionId === transportSessionId && this.transports.size > 1)
+                    continue;
+                if (entry.lastActivityAt >= oldestActivityAt)
+                    continue;
+                oldestTransportSessionId = candidateSessionId;
+                oldestActivityAt = entry.lastActivityAt;
+            }
+            if (!oldestTransportSessionId)
+                break;
+            const oldest = this.transports.get(oldestTransportSessionId);
+            this.transports.delete(oldestTransportSessionId);
+            if (oldest) {
+                excess.push({
+                    transportSessionId: oldestTransportSessionId,
+                    transport: oldest.transport,
+                });
+            }
+        }
+        return closeTransports(excess);
     }
     get(transportSessionId) {
         const entry = this.transports.get(transportSessionId);

package/dist/oauth-provider.js

@@ -116,6 +116,7 @@ export class SingleUserOAuthProvider {
             }));
             return;
         }
+        this.pruneExpiredAuthorizationCodes();
         const code = `code-${randomUUID()}`;
         this.codes.set(code, {
             clientId: client.client_id,
@@ -177,9 +178,17 @@ export class SingleUserOAuthProvider {
         this.oauthStore.deleteRefreshToken(hashed);
     }
     close() {
+        this.codes.clear();
         this.oauthStore.close();
     }
+    pruneExpiredAuthorizationCodes(nowMs = Date.now()) {
+        for (const [code, record] of this.codes) {
+            if (record.expiresAtMs < nowMs)
+                this.codes.delete(code);
+        }
+    }
     validCodeRecord(client, authorizationCode) {
+        this.pruneExpiredAuthorizationCodes();
         const record = this.codes.get(authorizationCode);
         if (!record || record.clientId !== client.client_id || record.expiresAtMs < Date.now()) {
             throw new InvalidGrantError("Invalid authorization code");

package/dist/process-sessions.js

@@ -7,8 +7,10 @@ const MAX_START_YIELD_MS = 300_000;
 const MAX_COMMAND_YIELD_MS = 300_000;
 const MAX_POLL_YIELD_MS = 300_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
-const DEFAULT_BUFFER_CHARACTERS = 1_000_000;
-const COMPLETED_PROCESS_TTL_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_BUFFER_CHARACTERS = 256_000;
+const DEFAULT_MAX_ACTIVE_PROCESSES = 64;
+const DEFAULT_MAX_COMPLETED_PROCESSES = 128;
+const COMPLETED_PROCESS_TTL_MS = 5 * 60 * 1_000;
 const DEFAULT_COLUMNS = 80;
 const DEFAULT_ROWS = 24;
 function boundedInteger(value, fallback, maximum) {
@@ -56,21 +58,55 @@ function processEnvironment(input) {
     };
 }
 function codePointLength(value) {
-    return Array.from(value).length;
-}
-function sliceCodePoints(value, start, end) {
-    return Array.from(value).slice(start, end).join("");
+    let characters = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff &&
+            index + 1 < value.length) {
+            const nextCodeUnit = value.charCodeAt(index + 1);
+            if (nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff)
+                index += 1;
+        }
+        characters += 1;
+    }
+    return characters;
 }
 function takeHead(value, count) {
     if (count <= 0)
         return "";
-    return sliceCodePoints(value, 0, count);
+    let index = 0;
+    let characters = 0;
+    while (index < value.length && characters < count) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff &&
+            index + 1 < value.length) {
+            const nextCodeUnit = value.charCodeAt(index + 1);
+            index += nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff ? 2 : 1;
+        }
+        else {
+            index += 1;
+        }
+        characters += 1;
+    }
+    return value.slice(0, index);
 }
 function takeTail(value, count) {
     if (count <= 0)
         return "";
-    const characters = Array.from(value);
-    return characters.slice(Math.max(0, characters.length - count)).join("");
+    let index = value.length;
+    let characters = 0;
+    while (index > 0 && characters < count) {
+        index -= 1;
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff &&
+            index > 0) {
+            const previousCodeUnit = value.charCodeAt(index - 1);
+            if (previousCodeUnit >= 0xd800 && previousCodeUnit <= 0xdbff)
+                index -= 1;
+        }
+        characters += 1;
+    }
+    return value.slice(index);
 }
 function splitBudget(maxCharacters) {
     return {
@@ -97,20 +133,29 @@ export class HeadTailBuffer {
     append(output) {
         if (!output)
             return;
+        const outputCharacters = codePointLength(output);
         const previousTotal = this.totalCharacters;
-        this.totalCharacters += codePointLength(output);
+        this.totalCharacters += outputCharacters;
         if (this.totalCharacters <= this.maxCharacters) {
             this.head += output;
             return;
         }
         const budget = splitBudget(this.maxCharacters);
         if (previousTotal <= this.maxCharacters) {
-            const fullOutput = this.head + output;
-            this.head = takeHead(fullOutput, budget.head);
-            this.tail = takeTail(fullOutput, budget.tail);
+            const previousHead = this.head;
+            this.head = previousTotal >= budget.head
+                ? takeHead(previousHead, budget.head)
+                : previousHead + takeHead(output, budget.head - previousTotal);
+            this.tail = outputCharacters >= budget.tail
+                ? takeTail(output, budget.tail)
+                : takeTail(previousHead, budget.tail - outputCharacters) + output;
+            return;
+        }
+        if (outputCharacters >= budget.tail) {
+            this.tail = takeTail(output, budget.tail);
             return;
         }
-        this.tail = takeTail(this.tail + output, budget.tail);
+        this.tail = takeTail(this.tail, budget.tail - outputCharacters) + output;
     }
     hasOutput() {
         return this.totalCharacters > 0;
@@ -145,13 +190,24 @@ function truncateOutput(output, maxCharacters) {
 export class ProcessManager {
     processes = new Map();
     completedByWorkspace = new Map();
+    completedProcessIds = [];
     maxBufferCharacters;
+    maxActiveProcesses;
+    maxCompletedProcesses;
     completedProcessTtlMs;
     maxStartYieldMs;
     monotonicNow;
     nextProcessId = 1;
     constructor(options = {}) {
         this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
+        this.maxActiveProcesses = options.maxActiveProcesses ?? DEFAULT_MAX_ACTIVE_PROCESSES;
+        if (!Number.isInteger(this.maxActiveProcesses) || this.maxActiveProcesses < 1) {
+            throw new Error("Active process limit must be a positive integer.");
+        }
+        this.maxCompletedProcesses = options.maxCompletedProcesses ?? DEFAULT_MAX_COMPLETED_PROCESSES;
+        if (!Number.isInteger(this.maxCompletedProcesses) || this.maxCompletedProcesses < 1) {
+            throw new Error("Completed process limit must be a positive integer.");
+        }
         this.completedProcessTtlMs = options.completedProcessTtlMs
             ?? options.completedSessionTtlMs
             ?? COMPLETED_PROCESS_TTL_MS;
@@ -159,6 +215,9 @@ export class ProcessManager {
         this.monotonicNow = options.monotonicNow ?? (() => performance.now());
     }
     async start(input) {
+        if (this.stats().running >= this.maxActiveProcesses) {
+            throw new Error(`Active process limit reached (${this.maxActiveProcesses}). Poll, interrupt, or wait for an existing process before starting another.`);
+        }
         const processEntry = this.createProcess(input);
         this.processes.set(processEntry.id, processEntry);
         try {
@@ -214,6 +273,17 @@ export class ProcessManager {
     activeWorkspaceIds() {
         return new Set([...this.processes.values()].map((processEntry) => processEntry.workspaceId));
     }
+    stats() {
+        let running = 0;
+        let completed = 0;
+        for (const processEntry of this.processes.values()) {
+            if (processEntry.running)
+                running += 1;
+            else
+                completed += 1;
+        }
+        return { total: this.processes.size, running, completed };
+    }
     takeCompleted(workspaceId, maxOutputTokens, excludeProcessId) {
         const processIds = this.completedByWorkspace.get(workspaceId) ?? [];
         if (processIds.length === 0)
@@ -250,6 +320,7 @@ export class ProcessManager {
         }
         this.processes.clear();
         this.completedByWorkspace.clear();
+        this.completedProcessIds.length = 0;
     }
     async waitForExit(processEntry, yieldTimeMs) {
         let timer;
@@ -352,16 +423,24 @@ export class ProcessManager {
         processEntry.running = false;
         processEntry.exitCode = exitCode;
         processEntry.signal = signal;
+        processEntry.process = undefined;
         processEntry.resolveExit();
+        processEntry.cleanupTimer = setTimeout(() => this.removeProcess(processEntry.id), this.completedProcessTtlMs);
+        processEntry.cleanupTimer.unref();
         if (processEntry.background) {
             const completed = this.completedByWorkspace.get(processEntry.workspaceId) ?? [];
             if (!completed.includes(processEntry.id)) {
                 completed.push(processEntry.id);
                 this.completedByWorkspace.set(processEntry.workspaceId, completed);
+                this.completedProcessIds.push(processEntry.id);
+            }
+            while (this.completedProcessIds.length > this.maxCompletedProcesses) {
+                const oldestProcessId = this.completedProcessIds[0];
+                if (oldestProcessId === undefined)
+                    break;
+                this.removeProcess(oldestProcessId);
             }
         }
-        processEntry.cleanupTimer = setTimeout(() => this.removeProcess(processEntry.id), this.completedProcessTtlMs);
-        processEntry.cleanupTimer.unref();
     }
     append(processEntry, output) {
         processEntry.buffer.append(output);
@@ -396,6 +475,9 @@ export class ProcessManager {
         if (processEntry?.cleanupTimer)
             clearTimeout(processEntry.cleanupTimer);
         this.processes.delete(processId);
+        const completedIndex = this.completedProcessIds.indexOf(processId);
+        if (completedIndex >= 0)
+            this.completedProcessIds.splice(completedIndex, 1);
         if (!processEntry)
             return;
         const completed = this.completedByWorkspace.get(processEntry.workspaceId);