@akira-tl/forgerelay 0.3.5 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.7] - 2026-08-10
+
+### Added
+
+- Added debug-only runtime resource telemetry for RSS/V8 heap, MCP transport count, running/completed process counts, cached workspaces, and review checkpoint state so long-running deployments can identify which resource class is growing.
+
+### Changed
+
+- Background `bash` completion state is now retained for at most five minutes, completed process handles are released immediately, completed notices are globally bounded, active processes have a global concurrency budget, and per-process retained output is smaller. High-output head/tail truncation no longer materializes whole strings as Unicode code-point arrays, sharply reducing transient heap growth and GC pressure.
+- Abandoned MCP transport sessions and in-memory review checkpoint states now have hard capacity limits. Review state is also released when its logical workspace closes, while persisted Git checkpoint refs remain available for reconstruction.
+- Workspace instruction discovery is now bounded and demand-driven: `open_workspace` scans only the workspace root and direct child directories, while deeper `AGENTS.md` / `CLAUDE.md` files are discovered along paths as the Agent first accesses them. Reads surface newly discovered instructions inline; mutation and shell calls stop before side effects and require a retry after newly discovered local instructions are applied.
+- Workspace/session activity timestamps now use a small in-process write-behind cache. Hot `lastUsedAt` touches are coalesced and flushed to SQLite in one transaction at most every five minutes, with an explicit final flush during normal shutdown; semantic create/close/status writes remain immediate.
+
+### Fixed
+
+- Expired, never-redeemed OAuth authorization codes are opportunistically evicted and cleared on provider shutdown instead of remaining in memory for the lifetime of the server.
+
+## [0.3.6] - 2026-08-10
+
+### Added
+
+- `open_workspace(action="list")` now provides paginated logical-workspace inventory without adding a tenth Core tool. Inventory entries include a compact `project/workspaceId` label, persisted status, derived lifecycle state, checkout/worktree backing metadata, creation/last-used timestamps, idle duration, root validity, current-conversation selection, and filters for workspace ID, status, state, mode, root, and stale-only views.
+
+### Changed
+
+- Workspace bootstrap context is now deduplicated by conversation scope, canonical workspace target, and a content fingerprint instead of by logical `workspaceId`. `context="auto"` remains the default, `context="full"` forces a refresh, and `context="none"` opens or resumes a workspace without returning the full AGENTS/Skills/guide/profile bootstrap.
+- Context-delivery state is persisted independently from logical-workspace selection, so switching or closing one logical handle does not make the same conversation forget already-delivered project context. Changes to loaded instruction contents or relevant Skill, guide, profile, diagnostic, or nested-instruction metadata change the fingerprint and cause `auto` to deliver the refreshed context again.
+- Workspace inventory is read-only with respect to workspace activity timestamps and runs the existing idle-session GC before listing. Persisted `status="active"` continues to mean the session has not been explicitly closed, while the derived `state` distinguishes currently active, stale-but-valid, invalid/missing-root, and closed records.
+
 ## [0.3.5] - 2026-08-10
 
 ### Changed

package/capabilities/shell-processes/GUIDE.md

@@ -28,9 +28,9 @@ processId: <number>
 
 `action="run"` 与 `action="process"` 的参数不要混用。Process ownership 始终绑定原 `workspaceId`；未知或跨 workspace 的 `processId` 会被拒绝。
 
-等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。
+等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。未消费的 completed process notice 最多保留 5 分钟；进程退出时底层 ChildProcess/PTY handle 会立即释放。ForgeRelay 同时对 active process 与 completed notice 数量设置全局资源预算，达到 active process 上限时会拒绝启动新的命令，而不会擅自终止已有长任务。
 
-不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。
+不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。高输出命令会使用有界 head/tail buffer，不能把 ForgeRelay 当作无限历史日志存储。
 
 ## PTY / interactive commands
 

package/dist/db/migrations.js

@@ -29,6 +29,11 @@ const migrations = [
         name: "local-agent-hook-reports",
         up: migrateLocalAgentHookReports,
     },
+    {
+        version: 7,
+        name: "workspace-context-deliveries",
+        up: migrateWorkspaceContextDeliveries,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -189,6 +194,20 @@ function migrateWorkspaceWorktreeBranches(sqlite) {
 function migrateLocalAgentHookReports(sqlite) {
     addColumnIfMissing(sqlite, "local_agent_sessions", "hook_reports_json", "text");
 }
+function migrateWorkspaceContextDeliveries(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_context_deliveries (
+      conversation_scope_id text not null,
+      target_key text not null,
+      context_fingerprint text not null,
+      delivered_at text not null,
+      primary key (conversation_scope_id, target_key)
+    );
+
+    create index if not exists workspace_context_deliveries_delivered_idx
+      on workspace_context_deliveries(delivered_at desc);
+  `);
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/db/schema.js

@@ -41,6 +41,15 @@ export const workspaceConversationBindings = sqliteTable("workspace_conversation
     primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
     index("workspace_conversation_bindings_workspace_idx").on(table.workspaceSessionId),
 ]);
+export const workspaceContextDeliveries = sqliteTable("workspace_context_deliveries", {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    targetKey: text("target_key").notNull(),
+    contextFingerprint: text("context_fingerprint").notNull(),
+    deliveredAt: text("delivered_at").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
+    index("workspace_context_deliveries_delivered_idx").on(table.deliveredAt),
+]);
 export const oauthClients = sqliteTable("oauth_clients", {
     clientId: text("client_id").primaryKey(),
     clientJson: text("client_json").notNull(),

package/dist/logger.js

@@ -113,6 +113,8 @@ function formatPrettyMessage(entry, options) {
         case "mcp_transport_session_close_failed":
         case "mcp_session_close_failed":
             return `transport session ${transportSessionPrefix(entry) ?? "unknown"} close -> ${style("red", "error", options)}`;
+        case "runtime_resources":
+            return formatRuntimeResources(entry);
         case "auth_denied":
             return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
         case "mcp_request_error":
@@ -212,6 +214,20 @@ function stableColorIndex(value) {
     }
     return (hash >>> 0) % WORKSPACE_PROJECT_COLORS.length;
 }
+function formatRuntimeResources(entry) {
+    const rssMb = bytesToMegabytes(numberField(entry.rssBytes));
+    const heapUsedMb = bytesToMegabytes(numberField(entry.heapUsedBytes));
+    const heapTotalMb = bytesToMegabytes(numberField(entry.heapTotalBytes));
+    const transports = numberField(entry.mcpTransports) ?? 0;
+    const running = numberField(entry.processesRunning) ?? 0;
+    const completed = numberField(entry.processesCompleted) ?? 0;
+    const workspaces = numberField(entry.cachedWorkspaces) ?? 0;
+    const reviewStates = numberField(entry.reviewStates) ?? 0;
+    return `runtime rss=${rssMb}MB heap=${heapUsedMb}/${heapTotalMb}MB transports=${transports} processes=${running} running/${completed} completed workspaces=${workspaces} review=${reviewStates}`;
+}
+function bytesToMegabytes(value) {
+    return value === undefined ? 0 : Math.round(value / (1024 * 1024));
+}
 function formatGenericMessage(entry) {
     const event = String(entry.event ?? "log");
     const detail = [entry.reason, entry.error]

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);

package/dist/review-checkpoints.js

@@ -3,26 +3,60 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { git, getGitEligibility, safeWorkspaceRefSegment } from "./git.js";
 const REVIEW_REF_PREFIX = "refs/devspace/review";
-export function createReviewCheckpointManager() {
+const DEFAULT_MAX_REVIEW_WORKSPACE_STATES = 128;
+export function createReviewCheckpointManager(options = {}) {
+    const maxWorkspaceStates = options.maxWorkspaceStates ?? DEFAULT_MAX_REVIEW_WORKSPACE_STATES;
+    if (!Number.isInteger(maxWorkspaceStates) || maxWorkspaceStates < 1) {
+        throw new Error("Review checkpoint workspace-state limit must be a positive integer.");
+    }
     const states = new Map();
     const initializations = new Map();
+    const touchState = (workspaceId) => {
+        const state = states.get(workspaceId);
+        if (!state)
+            return;
+        states.delete(workspaceId);
+        states.set(workspaceId, state);
+    };
+    const trimStates = () => {
+        while (states.size > maxWorkspaceStates) {
+            const oldestWorkspaceId = states.keys().next().value;
+            if (!oldestWorkspaceId)
+                break;
+            states.delete(oldestWorkspaceId);
+        }
+    };
     return {
+        get stateCount() {
+            return states.size;
+        },
+        async releaseWorkspace(workspaceId) {
+            const pending = initializations.get(workspaceId);
+            if (pending)
+                await pending;
+            states.delete(workspaceId);
+        },
         async initializeWorkspace({ workspaceId, root }) {
             const existingState = states.get(workspaceId);
             assertWorkspaceRoot(existingState, workspaceId, root);
             if (existingState?.root === root && existingState.gitRoot !== undefined) {
+                touchState(workspaceId);
                 return;
             }
             const pending = initializations.get(workspaceId);
             if (pending) {
                 await pending;
                 assertWorkspaceRoot(states.get(workspaceId), workspaceId, root);
+                touchState(workspaceId);
+                trimStates();
                 return;
             }
             const initialize = initializeWorkspaceState(states, workspaceId, root);
             initializations.set(workspaceId, initialize);
             try {
                 await initialize;
+                touchState(workspaceId);
+                trimStates();
             }
             finally {
                 if (initializations.get(workspaceId) === initialize) {
@@ -38,6 +72,7 @@ export function createReviewCheckpointManager() {
                 state = states.get(workspaceId);
             }
             assertWorkspaceRoot(state, workspaceId, root);
+            touchState(workspaceId);
             if (!state?.gitRoot) {
                 throw new Error(state?.diagnostic ?? "review.changes requires a Git workspace in this version.");
             }