@akira-tl/forgerelay 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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

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/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.");
             }

package/dist/server.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { access, realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
@@ -42,6 +43,7 @@ import { formatLocalAgentProviderAvailabilitySummary, getLocalAgentProviderAvail
 // transport. Bound stale transport-session retention so abandoned transports do
 // not accumulate for the life of the process.
 const MCP_TRANSPORT_IDLE_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+const MAX_MCP_TRANSPORT_SESSIONS = 64;
 const FORGERELAY_VERSION = readForgeRelayVersion();
 const MCP_TRANSPORT_CLEANUP_INTERVAL_MS = 5 * 60 * 1_000;
 const WRITE_TOOL_ANNOTATIONS = {
@@ -92,6 +94,30 @@ function workspaceLogContext(workspace, _transportSessionId) {
         workspace: workspaceLogLabel(workspace.root, workspace.id),
     };
 }
+function formatDiscoveredWorkspaceInstructions(files, workspaceRoot) {
+    return [
+        "Workspace instructions discovered for this path. Apply them to follow-up work under their directories:",
+        ...files.flatMap((file) => [
+            `--- ${formatAgentsPath(file.path, workspaceRoot)} ---`,
+            file.content.trimEnd(),
+        ]),
+    ].join("\n");
+}
+async function assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, paths) {
+    const discovered = new Map();
+    for (const path of paths) {
+        const absolutePath = resolve(workspace.root, path);
+        for (const file of await workspaces.discoverPathInstructions(workspace, absolutePath)) {
+            discovered.set(file.path, file);
+        }
+    }
+    if (discovered.size === 0)
+        return;
+    throw new Error([
+        formatDiscoveredWorkspaceInstructions([...discovered.values()], workspace.root),
+        "Apply these instructions, then retry this tool call. No mutation or command was executed.",
+    ].join("\n"));
+}
 function formatVisibleAgent(agent) {
     const model = agent.model ? `, model ${agent.model}` : "";
     const thinking = agent.thinking ? `, thinking ${agent.thinking}` : "";
@@ -608,6 +634,7 @@ function registerProcessTools(server, config, workspaces, processSessions, hooks
                 operation: async () => {
                     const startedAt = performance.now();
                     const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                    await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
                     const snapshot = await processSessions.start({
                         workspaceId,
                         command: cmd,
@@ -1337,14 +1364,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     if (!commitMessage) {
                         throw new Error(`Managed-worktree-backed workspace ${workspaceId} requires commitMessage when closing.`);
                     }
-                    const busyWorkspaceIds = workspaces
-                        .workspaceIdsForPhysicalWorkspace(workspace)
+                    const physicalWorkspaceIds = workspaces.workspaceIdsForPhysicalWorkspace(workspace);
+                    const busyWorkspaceIds = physicalWorkspaceIds
                         .filter((id) => processSessions.activeWorkspaceIds().has(id));
                     if (busyWorkspaceIds.length > 0) {
                         throw new Error(`Cannot close this worktree-backed workspace while logical workspace processes are still running or awaiting completion delivery: ${busyWorkspaceIds.join(", ")}.`);
                     }
                     const startedAt = performance.now();
                     const closed = await workspaces.closeWorktree(workspaceId, commitMessage);
+                    await Promise.all(physicalWorkspaceIds.map((id) => reviewCheckpoints.releaseWorkspace(id)));
                     const result = [
                         `Closed managed-worktree-backed workspace ${workspaceId}.`,
                         `Merged ${closed.branch} into ${closed.targetBranch} by fast-forward.`,
@@ -1384,6 +1412,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     throw new Error(`Workspace ${workspaceId} still owns a running process or an unconsumed process completion. Poll or consume it before closing this workspace.`);
                 }
                 workspaces.closeWorkspace(workspaceId);
+                await reviewCheckpoints.releaseWorkspace(workspaceId);
                 const result = `Closed checkout-backed workspace ${workspaceId}. Physical project files were not removed.`;
                 return {
                     content: [textBlock(result)],
@@ -1417,7 +1446,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 .optional()
                 .describe("Maximum number of lines to read."),
         },
-        outputSchema: resultOutputSchema(),
+        outputSchema: resultOutputSchema({
+            agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
+        }),
         ...toolWidgetDescriptorMeta(config, "read"),
         annotations: { readOnlyHint: true },
     }, async ({ workspaceId, ...input }, extra) => {
@@ -1430,6 +1461,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             operation: async () => {
                 const startedAt = performance.now();
                 const readPath = workspaces.resolveReadPath(workspace, input.path);
+                const discoveredInstructions = (await workspaces.discoverPathInstructions(workspace, readPath.absolutePath)).filter((file) => file.path !== readPath.absolutePath);
                 const response = await readFileTool({ ...input, path: readPath.absolutePath }, {
                     cwd: workspace.root,
                     root: workspace.root,
@@ -1444,6 +1476,12 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     return response;
                 }
                 workspaces.markReadPathLoaded(workspace, readPath);
+                const discoveredInstructionContent = discoveredInstructions.length > 0
+                    ? textBlock(formatDiscoveredWorkspaceInstructions(discoveredInstructions, workspace.root))
+                    : undefined;
+                const content = discoveredInstructionContent
+                    ? [discoveredInstructionContent, ...response.content]
+                    : response.content;
                 const summary = {
                     ...textSummary(response.content),
                     offset: input.offset ?? 1,
@@ -1458,6 +1496,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 });
                 return {
                     ...response,
+                    content,
                     _meta: {
                         tool: toolNames.read,
                         card: {
@@ -1468,7 +1507,15 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         },
                     },
                     structuredContent: {
-                        result: contentText(response.content),
+                        result: contentText(content),
+                        ...(discoveredInstructions.length > 0
+                            ? {
+                                agentsFiles: discoveredInstructions.map((file) => ({
+                                    path: formatAgentsPath(file.path, workspace.root),
+                                    content: file.content,
+                                })),
+                            }
+                            : {}),
                     },
                 };
             },
@@ -1500,6 +1547,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 changedPaths: (result) => toolResultIsError(result) ? [] : [input.path],
                 operation: async () => {
                     const startedAt = performance.now();
+                    await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [input.path]);
                     const response = await writeFileTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
@@ -1582,6 +1630,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 changedPaths: (result) => toolResultIsError(result) ? [] : [input.path],
                 operation: async () => {
                     const startedAt = performance.now();
+                    await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [input.path]);
                     const response = await editFileTool(input, {
                         cwd: workspace.root,
                         root: workspace.root,
@@ -1657,6 +1706,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             operation: async () => {
                 const startedAt = performance.now();
                 try {
+                    await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [path, newPath]);
                     await renamePath({ path, newPath }, {
                         cwd: workspace.root,
                         allowedRoots: workspaces.fileToolRoots(workspace),
@@ -1728,6 +1778,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             operation: async () => {
                 const startedAt = performance.now();
                 try {
+                    await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [path]);
                     const deleted = await deletePath({ path, recursive }, {
                         cwd: workspace.root,
                         allowedRoots: workspaces.fileToolRoots(workspace),
@@ -1938,6 +1989,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     operation: async () => {
                         const startedAt = performance.now();
                         const cwd = workspaces.resolveWorkingDirectory(workspace, workingDirectory);
+                        await assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, [cwd]);
                         const snapshot = await processSessions.start({
                             workspaceId,
                             command,
@@ -2041,7 +2093,9 @@ export function createServer(config = loadConfig(), options = {}) {
         host: config.host,
         ...(allowedHosts ? { allowedHosts } : {}),
     });
-    const transports = new McpTransportRegistry();
+    const transports = new McpTransportRegistry({
+        maxTransports: MAX_MCP_TRANSPORT_SESSIONS,
+    });
     const mcpUrl = new URL("/mcp", config.publicBaseUrl);
     const resourceServerUrl = resourceUrlFromServerUrl(mcpUrl);
     const oauthProvider = new SingleUserOAuthProvider(config.oauth, mcpUrl, config.stateDir);
@@ -2071,7 +2125,7 @@ export function createServer(config = loadConfig(), options = {}) {
                 continue;
             }
             closedCount += 1;
-            if (reason === "idle_timeout") {
+            if (reason !== "server_shutdown") {
                 logEvent(config.logging, "debug", "mcp_transport_session_closed", {
                     reason,
                     transportSessionIdPrefix: transportSessionIdPrefix(result.transportSessionId),
@@ -2085,12 +2139,31 @@ export function createServer(config = loadConfig(), options = {}) {
             });
         }
     };
+    const logRuntimeResources = () => {
+        const memory = process.memoryUsage();
+        const processStats = processSessions.stats();
+        logEvent(config.logging, "debug", "runtime_resources", {
+            rssBytes: memory.rss,
+            heapUsedBytes: memory.heapUsed,
+            heapTotalBytes: memory.heapTotal,
+            externalBytes: memory.external,
+            arrayBuffersBytes: memory.arrayBuffers,
+            mcpTransports: transports.size,
+            processesTotal: processStats.total,
+            processesRunning: processStats.running,
+            processesCompleted: processStats.completed,
+            cachedWorkspaces: workspaces.cachedWorkspaceCount,
+            reviewStates: reviewCheckpoints.stateCount,
+        });
+    };
     const transportCleanupTimer = setInterval(() => {
         void transports
             .closeIdle(MCP_TRANSPORT_IDLE_TIMEOUT_MS)
-            .then((results) => logTransportCloseResults("idle_timeout", results));
+            .then((results) => logTransportCloseResults("idle_timeout", results))
+            .finally(logRuntimeResources);
     }, MCP_TRANSPORT_CLEANUP_INTERVAL_MS);
     transportCleanupTimer.unref();
+    logRuntimeResources();
     if (config.logging.trustProxy) {
         app.set("trust proxy", 1);
     }
@@ -2182,8 +2255,11 @@ export function createServer(config = loadConfig(), options = {}) {
                 transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
                     onsessioninitialized: (newTransportSessionId) => {
-                        if (transport)
-                            transports.register(newTransportSessionId, transport);
+                        if (transport) {
+                            void transports
+                                .register(newTransportSessionId, transport)
+                                .then((results) => logTransportCloseResults("capacity_limit", results));
+                        }
                         logEvent(config.logging, "debug", "mcp_transport_session_created", {
                             requestId,
                             transportSessionIdPrefix: transportSessionIdPrefix(newTransportSessionId),

package/dist/workspace-store.js

@@ -1,13 +1,32 @@
 import { and, desc, eq } from "drizzle-orm";
 import { openDatabase } from "./db/client.js";
 import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessions, } from "./db/schema.js";
+const DEFAULT_TOUCH_FLUSH_INTERVAL_MS = 5 * 60 * 1_000;
 export class SqliteWorkspaceStore {
     database;
-    constructor(stateDir) {
+    now;
+    touchFlushTimer;
+    pendingSessionTouches = new Map();
+    pendingConversationTouches = new Map();
+    constructor(stateDir, options = {}) {
         this.database = openDatabase(stateDir);
+        this.now = options.now ?? (() => new Date());
+        const touchFlushIntervalMs = options.touchFlushIntervalMs ?? DEFAULT_TOUCH_FLUSH_INTERVAL_MS;
+        if (!Number.isInteger(touchFlushIntervalMs) || touchFlushIntervalMs < 1) {
+            throw new Error("Workspace touch flush interval must be a positive integer.");
+        }
+        this.touchFlushTimer = setInterval(() => {
+            try {
+                this.flushTouches();
+            }
+            catch (error) {
+                console.warn(`ForgeRelay workspace touch flush failed: ${errorMessage(error)}`);
+            }
+        }, touchFlushIntervalMs);
+        this.touchFlushTimer.unref();
     }
     createSession(input) {
-        const now = new Date().toISOString();
+        const now = this.now().toISOString();
         const session = {
             id: input.id,
             root: input.root,
@@ -47,19 +66,18 @@ export class SqliteWorkspaceStore {
             .from(workspaceSessions)
             .where(eq(workspaceSessions.id, id))
             .get();
-        return row ? rowToWorkspaceSession(row) : undefined;
+        if (!row)
+            return undefined;
+        return applySessionTouch(rowToWorkspaceSession(row), this.pendingSessionTouches.get(id));
     }
     touchSession(id) {
-        this.database.db
-            .update(workspaceSessions)
-            .set({ lastUsedAt: new Date().toISOString() })
-            .where(eq(workspaceSessions.id, id))
-            .run();
+        this.pendingSessionTouches.set(id, this.now().toISOString());
     }
     setSessionStatus(id, status) {
+        this.pendingSessionTouches.delete(id);
         this.database.db
             .update(workspaceSessions)
-            .set({ status, lastUsedAt: new Date().toISOString() })
+            .set({ status, lastUsedAt: this.now().toISOString() })
             .where(eq(workspaceSessions.id, id))
             .run();
     }
@@ -77,9 +95,13 @@ export class SqliteWorkspaceStore {
             : conditions.length === 1
                 ? query.where(conditions[0]).all()
                 : query.where(and(...conditions)).all();
-        return rows.map(rowToWorkspaceSession);
+        return rows
+            .map(rowToWorkspaceSession)
+            .map((session) => applySessionTouch(session, this.pendingSessionTouches.get(session.id)))
+            .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
     }
     deleteSession(id) {
+        this.pendingSessionTouches.delete(id);
         this.database.db
             .delete(workspaceSessions)
             .where(eq(workspaceSessions.id, id))
@@ -90,7 +112,8 @@ export class SqliteWorkspaceStore {
             .select()
             .from(workspaceConversationBindings)
             .all()
-            .map(rowToWorkspaceConversationBinding);
+            .map(rowToWorkspaceConversationBinding)
+            .map((binding) => applyConversationTouch(binding, this.pendingConversationTouches.get(conversationTouchKey(binding.conversationScopeId, binding.targetKey))?.lastUsedAt));
     }
     getConversationBinding(conversationScopeId, targetKey) {
         const row = this.database.db
@@ -98,10 +121,13 @@ export class SqliteWorkspaceStore {
             .from(workspaceConversationBindings)
             .where(and(eq(workspaceConversationBindings.conversationScopeId, conversationScopeId), eq(workspaceConversationBindings.targetKey, targetKey)))
             .get();
-        return row ? rowToWorkspaceConversationBinding(row) : undefined;
+        if (!row)
+            return undefined;
+        const binding = rowToWorkspaceConversationBinding(row);
+        return applyConversationTouch(binding, this.pendingConversationTouches.get(conversationTouchKey(conversationScopeId, targetKey))?.lastUsedAt);
     }
     setConversationBinding(input) {
-        const now = new Date().toISOString();
+        const now = this.now().toISOString();
         const row = this.database.db
             .insert(workspaceConversationBindings)
             .values({
@@ -126,16 +152,18 @@ export class SqliteWorkspaceStore {
         if (!row) {
             throw new Error("Conversation workspace binding upsert returned no row.");
         }
+        this.pendingConversationTouches.delete(conversationTouchKey(input.conversationScopeId, input.targetKey));
         return rowToWorkspaceConversationBinding(row);
     }
     touchConversationBinding(conversationScopeId, targetKey) {
-        this.database.db
-            .update(workspaceConversationBindings)
-            .set({ lastUsedAt: new Date().toISOString() })
-            .where(and(eq(workspaceConversationBindings.conversationScopeId, conversationScopeId), eq(workspaceConversationBindings.targetKey, targetKey)))
-            .run();
+        this.pendingConversationTouches.set(conversationTouchKey(conversationScopeId, targetKey), {
+            conversationScopeId,
+            targetKey,
+            lastUsedAt: this.now().toISOString(),
+        });
     }
     deleteConversationBinding(conversationScopeId, targetKey) {
+        this.pendingConversationTouches.delete(conversationTouchKey(conversationScopeId, targetKey));
         this.database.db
             .delete(workspaceConversationBindings)
             .where(and(eq(workspaceConversationBindings.conversationScopeId, conversationScopeId), eq(workspaceConversationBindings.targetKey, targetKey)))
@@ -184,13 +212,62 @@ export class SqliteWorkspaceStore {
             .where(and(eq(workspaceContextDeliveries.conversationScopeId, conversationScopeId), eq(workspaceContextDeliveries.targetKey, targetKey)))
             .run();
     }
+    get pendingTouchCount() {
+        return this.pendingSessionTouches.size + this.pendingConversationTouches.size;
+    }
+    flushTouches() {
+        if (this.pendingTouchCount === 0)
+            return;
+        const sessionTouches = [...this.pendingSessionTouches.entries()];
+        const conversationTouches = [...this.pendingConversationTouches.values()];
+        const updateSession = this.database.sqlite.prepare("UPDATE workspace_sessions SET last_used_at = ? WHERE id = ?");
+        const updateConversation = this.database.sqlite.prepare("UPDATE workspace_conversation_bindings SET last_used_at = ? WHERE conversation_scope_id = ? AND target_key = ?");
+        const flush = this.database.sqlite.transaction(() => {
+            for (const [workspaceId, lastUsedAt] of sessionTouches) {
+                updateSession.run(lastUsedAt, workspaceId);
+            }
+            for (const touch of conversationTouches) {
+                updateConversation.run(touch.lastUsedAt, touch.conversationScopeId, touch.targetKey);
+            }
+        });
+        flush();
+        for (const [workspaceId, lastUsedAt] of sessionTouches) {
+            if (this.pendingSessionTouches.get(workspaceId) === lastUsedAt) {
+                this.pendingSessionTouches.delete(workspaceId);
+            }
+        }
+        for (const touch of conversationTouches) {
+            const key = conversationTouchKey(touch.conversationScopeId, touch.targetKey);
+            if (this.pendingConversationTouches.get(key)?.lastUsedAt === touch.lastUsedAt) {
+                this.pendingConversationTouches.delete(key);
+            }
+        }
+    }
     close() {
-        this.database.close();
+        clearInterval(this.touchFlushTimer);
+        try {
+            this.flushTouches();
+        }
+        finally {
+            this.database.close();
+        }
     }
 }
 export function createWorkspaceStore(stateDir) {
     return new SqliteWorkspaceStore(stateDir);
 }
+function applySessionTouch(session, lastUsedAt) {
+    return lastUsedAt ? { ...session, lastUsedAt } : session;
+}
+function applyConversationTouch(binding, lastUsedAt) {
+    return lastUsedAt ? { ...binding, lastUsedAt } : binding;
+}
+function conversationTouchKey(conversationScopeId, targetKey) {
+    return JSON.stringify([conversationScopeId, targetKey]);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function rowToWorkspaceSession(row) {
     return {
         id: row.id,

package/dist/workspaces.js

@@ -11,6 +11,7 @@ import { loadLocalAgentProfiles, } from "./local-agent-profiles.js";
 const WORKSPACE_STALE_REMINDER_MS = 2 * 24 * 60 * 60 * 1_000;
 const WORKSPACE_SESSION_IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1_000;
 const WORKSPACE_GC_INTERVAL_MS = 60 * 60 * 1_000;
+const INITIAL_INSTRUCTION_DISCOVERY_DEPTH = 1;
 export class WorkspaceRegistry {
     config;
     store;
@@ -24,6 +25,9 @@ export class WorkspaceRegistry {
         this.hooks = new HookRunner(config.hooks, config.logging);
         this.pruneIdleWorkspaceSessions(new Set(), true);
     }
+    get cachedWorkspaceCount() {
+        return this.workspaces.size;
+    }
     async openWorkspace(input, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
         const workspaceInput = typeof input === "string" ? { path: input } : input;
@@ -631,8 +635,11 @@ export class WorkspaceRegistry {
         Object.assign(workspace, this.loadSkillsForWorkspace(workspace.root));
         workspace.capabilityGuides = loadCapabilityGuides(this.config);
         workspace.agentProfiles = await loadLocalAgentProfiles(this.config, workspace.root);
-        const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
-        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        workspace.scannedInstructionDirs.clear();
+        workspace.knownInstructionPathsByDir.clear();
+        workspace.loadedInstructionRealPaths.clear();
+        const agentsFiles = await this.loadInitialAgentsFiles(workspace);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace, agentsFiles);
         const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
@@ -686,6 +693,9 @@ export class WorkspaceRegistry {
             agentProfiles: [],
             activatedSkillDirs: new Set(),
             activatedCapabilityGuideDirs: new Set(),
+            scannedInstructionDirs: new Set(),
+            knownInstructionPathsByDir: new Map(),
+            loadedInstructionRealPaths: new Set(),
         };
         if (touch)
             this.store?.touchSession(session.id);
@@ -782,6 +792,9 @@ export class WorkspaceRegistry {
             agentProfiles: await loadLocalAgentProfiles(this.config, input.root),
             activatedSkillDirs: new Set(),
             activatedCapabilityGuideDirs: new Set(),
+            scannedInstructionDirs: new Set(),
+            knownInstructionPathsByDir: new Map(),
+            loadedInstructionRealPaths: new Set(),
         };
         this.store?.createSession({
             id: workspace.id,
@@ -807,8 +820,8 @@ export class WorkspaceRegistry {
                 targetBranch: workspace.worktree?.targetBranch,
             },
         });
-        const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
-        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        const agentsFiles = await this.loadInitialAgentsFiles(workspace);
+        const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace, agentsFiles);
         const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
@@ -837,11 +850,9 @@ export class WorkspaceRegistry {
         }
         return assertAllowedPath(root, this.config.allowedRoots);
     }
-    async loadInitialAgentsFiles(root) {
-        const resolvedRoot = (await tryRealpath(root)) ?? root;
+    async loadInitialAgentsFiles(workspace) {
         const systemInstructionsPath = resolve(this.config.systemInstructionsPath);
         const loadedFiles = [];
-        const loadedRealPaths = new Set();
         const systemInstructions = await readSystemInstructions(systemInstructionsPath);
         const systemInstructionsRealPath = await tryRealpath(systemInstructionsPath);
         if (systemInstructions !== undefined) {
@@ -849,52 +860,125 @@ export class WorkspaceRegistry {
                 path: systemInstructionsPath,
                 content: systemInstructions,
             });
-            if (systemInstructionsRealPath)
-                loadedRealPaths.add(systemInstructionsRealPath);
-        }
-        for (const fileName of CONTEXT_FILE_NAMES) {
-            const path = join(root, fileName);
-            const content = await readResolvedProjectContextFile(path, resolvedRoot);
-            if (content === undefined)
-                continue;
-            const realPath = await tryRealpath(path);
-            if (realPath && loadedRealPaths.has(realPath))
-                continue;
-            loadedFiles.push({
-                path,
-                content,
-            });
-            if (realPath)
-                loadedRealPaths.add(realPath);
+            if (systemInstructionsRealPath) {
+                workspace.loadedInstructionRealPaths.add(systemInstructionsRealPath);
+            }
         }
+        await this.discoverInstructionTree(workspace, workspace.root, INITIAL_INSTRUCTION_DISCOVERY_DEPTH);
+        loadedFiles.push(...await this.loadKnownInstructionsInDirectory(workspace, workspace.root));
         return loadedFiles;
     }
-    async findAvailableAgentsFiles(root, loadedFiles) {
+    async findAvailableAgentsFiles(workspace, loadedFiles) {
         const loadedPaths = new Set(loadedFiles.map((file) => resolve(file.path)));
-        const loadedRealPaths = new Set();
-        for (const file of loadedFiles) {
-            const realPath = await tryRealpath(file.path);
-            if (realPath)
-                loadedRealPaths.add(realPath);
-        }
         const discovered = [];
-        const agentDir = resolve(this.config.agentDir);
-        await walkWorkspace(root, async (path, entry) => {
-            if (isPathInsideRoot(path, agentDir))
-                return;
-            if (!entry.isFile())
-                return;
-            if (!CONTEXT_FILE_NAMES.has(entry.name))
-                return;
-            if (loadedPaths.has(path))
-                return;
-            const realPath = await tryRealpath(path);
-            if (realPath && loadedRealPaths.has(realPath))
-                return;
-            discovered.push({ path });
-        });
+        for (const paths of workspace.knownInstructionPathsByDir.values()) {
+            for (const path of paths) {
+                if (loadedPaths.has(path))
+                    continue;
+                const realPath = await tryRealpath(path);
+                if (realPath && workspace.loadedInstructionRealPaths.has(realPath))
+                    continue;
+                discovered.push({ path });
+            }
+        }
         return discovered.sort((a, b) => a.path.localeCompare(b.path));
     }
+    async discoverPathInstructions(workspace, inputPath) {
+        const absolutePath = resolve(inputPath);
+        if (!isPathInsideRoot(absolutePath, workspace.root))
+            return [];
+        const targetDirectory = dirname(absolutePath);
+        const relationship = relative(workspace.root, targetDirectory);
+        if (relationship === ".." ||
+            relationship.startsWith(`..${sep}`) ||
+            resolve(targetDirectory) === resolve(this.config.agentDir) ||
+            isPathInsideRoot(targetDirectory, resolve(this.config.agentDir))) {
+            return [];
+        }
+        const directories = [resolve(workspace.root)];
+        if (relationship) {
+            let current = resolve(workspace.root);
+            for (const segment of relationship.split(sep).filter(Boolean)) {
+                if (SKIPPED_CONTEXT_DIRS.has(segment))
+                    break;
+                current = join(current, segment);
+                directories.push(current);
+            }
+        }
+        const loaded = [];
+        for (const directory of directories) {
+            await this.discoverInstructionTree(workspace, directory, 0);
+            loaded.push(...await this.loadKnownInstructionsInDirectory(workspace, directory));
+        }
+        return loaded;
+    }
+    async discoverInstructionTree(workspace, directory, remainingDepth) {
+        const resolvedDirectory = resolve(directory);
+        if (workspace.scannedInstructionDirs.has(resolvedDirectory))
+            return;
+        workspace.scannedInstructionDirs.add(resolvedDirectory);
+        if (resolvedDirectory !== resolve(workspace.root) &&
+            isPathInsideRoot(resolvedDirectory, resolve(this.config.agentDir))) {
+            return;
+        }
+        let entries;
+        try {
+            entries = await opendir(resolvedDirectory);
+        }
+        catch {
+            return;
+        }
+        const instructionPaths = [];
+        const childDirectories = [];
+        for await (const entry of entries) {
+            const path = join(resolvedDirectory, entry.name);
+            if (entry.isFile() && CONTEXT_FILE_NAMES.has(entry.name)) {
+                instructionPaths.push(path);
+                continue;
+            }
+            if (remainingDepth > 0 &&
+                entry.isDirectory() &&
+                !SKIPPED_CONTEXT_DIRS.has(entry.name)) {
+                childDirectories.push(path);
+            }
+        }
+        workspace.knownInstructionPathsByDir.set(resolvedDirectory, instructionPaths.sort((left, right) => left.localeCompare(right)));
+        if (remainingDepth <= 0)
+            return;
+        for (const childDirectory of childDirectories) {
+            await this.discoverInstructionTree(workspace, childDirectory, remainingDepth - 1);
+        }
+    }
+    async loadKnownInstructionsInDirectory(workspace, directory) {
+        const resolvedDirectory = resolve(directory);
+        const paths = workspace.knownInstructionPathsByDir.get(resolvedDirectory) ?? [];
+        const loaded = [];
+        const resolvedRoot = (await tryRealpath(workspace.root)) ?? resolve(workspace.root);
+        const realDirectory = (await tryRealpath(resolvedDirectory)) ?? resolvedDirectory;
+        for (const path of paths) {
+            const realPath = await tryRealpath(path);
+            if (!realPath)
+                continue;
+            if (!isPathInsideRoot(realPath, resolvedRoot))
+                continue;
+            if (dirname(realPath) !== realDirectory)
+                continue;
+            if (workspace.loadedInstructionRealPaths.has(realPath))
+                continue;
+            let content;
+            try {
+                content = await readFile(realPath, "utf8");
+            }
+            catch (error) {
+                if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+                    continue;
+                throw error;
+            }
+            workspace.loadedInstructionRealPaths.add(realPath);
+            loaded.push({ path, content });
+        }
+        return loaded;
+    }
 }
 function resolveBootstrapContextVisibility(mode, contextAlreadyDelivered) {
     if (mode === "full")
@@ -998,9 +1082,6 @@ export function formatAgentsPath(path, workspaceRoot) {
     }
     return relationship.split(sep).join("/");
 }
-function isProjectRootInstructionPath(path, root) {
-    return isPathInsideRoot(path, root) && dirname(path) === root;
-}
 async function readSystemInstructions(path) {
     try {
         return await readFile(path, "utf8");
@@ -1012,20 +1093,6 @@ async function readSystemInstructions(path) {
         throw error;
     }
 }
-async function readResolvedProjectContextFile(path, root) {
-    try {
-        const resolvedPath = await realpath(path);
-        if (!isProjectRootInstructionPath(resolvedPath, root))
-            return undefined;
-        return await readFile(resolvedPath, "utf8");
-    }
-    catch (error) {
-        if (isErrnoException(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
-            return undefined;
-        }
-        throw error;
-    }
-}
 async function tryRealpath(path) {
     try {
         return await realpath(path);
@@ -1034,25 +1101,6 @@ async function tryRealpath(path) {
         return undefined;
     }
 }
-async function walkWorkspace(directory, visit) {
-    let entries;
-    try {
-        entries = await opendir(directory);
-    }
-    catch {
-        return;
-    }
-    for await (const entry of entries) {
-        const path = join(directory, entry.name);
-        if (entry.isDirectory()) {
-            if (!SKIPPED_CONTEXT_DIRS.has(entry.name)) {
-                await walkWorkspace(path, visit);
-            }
-            continue;
-        }
-        await visit(path, entry);
-    }
-}
 function isErrnoException(error) {
     return error instanceof Error && "code" in error;
 }

package/docs/chatgpt-coding-workflow.md

@@ -157,10 +157,16 @@ CLAUDE.md
 CLAUDE.MD
 ```
 
-Nested project instruction files are returned as available paths rather than all
-being injected eagerly. Read the relevant nested file before working under that path.
-`FORGERELAY_AGENT_DIR` is not an instruction source; it remains only a compatibility
-skill-discovery path.
+To keep broad workspaces such as `~` fast, initial nested-instruction discovery is
+bounded to direct child directories instead of recursively walking the whole tree.
+Deeper `AGENTS.md` / `CLAUDE.md` files are discovered lazily along a path the first
+time the Agent accesses it, and already-scanned directories are cached for the life
+of that workspace handle. A `read` result carries any newly discovered local
+instructions before the requested file content. Side-effecting file tools and shell
+commands discover instructions before execution; if new local instructions are
+found, ForgeRelay returns them and requires the Agent to retry, so the side effect
+does not occur before the relevant instructions are known. `FORGERELAY_AGENT_DIR`
+is not an instruction source; it remains only a compatibility skill-discovery path.
 
 ## MCP capability loading
 

package/docs/configuration.md

@@ -193,13 +193,24 @@ files. For a managed-worktree-backed workspace, `close_workspace` requires
 `commitMessage` and runs the existing safe worktree finalize lifecycle: close Hooks,
 commit when needed, fast-forward-only integration, cleanup, and alias invalidation.
 
+Hot workspace/session activity timestamps are coalesced in memory and flushed to the
+SQLite state database in a transaction at most every five minutes; normal shutdown
+performs a final explicit flush. Reads within the running ForgeRelay process see the
+latest in-memory timestamps immediately. Workspace creation, close/status changes,
+context-delivery checkpoints, and other semantic state transitions remain immediate
+persistent writes. A hard process crash may therefore lose only the most recent
+activity timestamp window, not the existence or closed/open state of a workspace.
+
 Regular `bash` has no execution-timeout input. `action="run"` (the default) waits
 in the foreground for at most 300 seconds; if the process is still alive, the
 result contains `running: true` and a canonical `processId`. Reuse the same `bash`
 with `action="process"` to poll/wait, send `input`, resize a PTY, or set
 `interrupt:true`; each wait can be up to 300 seconds. ForgeRelay does not kill a
 process merely because a wait window expires. Completed background processes are
-delivered once with a later tool result for the same logical workspace ID.
+delivered once with a later tool result for the same logical workspace ID. An
+unconsumed completed-process notice is retained for at most five minutes, and
+ForgeRelay also bounds active and completed process counts so repeated background
+commands cannot grow server memory without limit.
 
 Codex mode retains `write_stdin` only as an experimental compatibility adapter;
 regular Agent workflows should use the single `bash` process lifecycle.
@@ -348,8 +359,12 @@ Arrays or empty values are not accepted. Symbolic links are followed, so the
 runtime entry may point at a canonical source elsewhere on disk.
 
 Project-root `AGENTS.md` / `CLAUDE.md` files remain project context and are
-loaded separately. `FORGERELAY_AGENT_DIR` does not select a global instruction
-file; it remains a compatibility path for Agent Skills.
+loaded separately. Initial nested-instruction discovery checks only direct child
+directories; deeper instruction files are discovered lazily when a workspace path
+is first accessed. Reads surface newly discovered instructions inline, while
+side-effecting file/shell operations stop before execution and require a retry if
+that access discovers new local instructions. `FORGERELAY_AGENT_DIR` does not
+select a global instruction file; it remains a compatibility path for Agent Skills.
 
 ## Skills and subagents
 

package/docs/roadmap.md

@@ -183,6 +183,17 @@ capability
 - inventory 区分持久化 `status` 与派生 `state`：`status="active"` 表示尚未显式关闭，`state` 再区分 active、stale、invalid 与 closed；missing root 或外部删除的 managed worktree 可以保持可诊断的 active record，同时显示为 invalid；
 - inventory 查看本身不刷新 workspace `lastUsedAt`，支持过滤与分页，并继续让现有 `close_workspace` 承担用户确认后的实际清理/finalize lifecycle。
 
+### 0.3.7 — 资源生命周期与 Workspace I/O 性能补丁
+
+0.3.7 处理长时间运行实例在高请求量、高输出 `bash`、大量 logical workspace 与宽根目录下的资源放大问题，不改变 canonical 9-tool surface：
+
+- completed background process 的 Agent 可消费状态最多保留 5 分钟；底层 ChildProcess/PTY handle 在退出时立即释放，completed notice 数量与 active process 数量都有硬上限，并缩小单 process 输出驻留预算；
+- 高输出 head/tail buffer 保留 Unicode code-point 语义，但不再通过 `Array.from(整段输出)` 构造巨型临时数组，降低 V8 heap 扩容与 GC 压力；
+- MCP transport registry 与 review checkpoint state 加入容量边界；正常 transport close/workspace close 仍立即释放，异常遗弃对象不能再无限累积；OAuth 过期 authorization code 也会主动淘汰；
+- `open_workspace` 的 instruction discovery 首轮只检查 root 与直接子目录，不再递归整棵 workspace。更深层 `AGENTS.md` / `CLAUDE.md` 在 Agent 首次访问对应路径时沿祖先目录惰性发现，并缓存已扫描目录；read 可直接携带新发现指令，write/edit/rename/delete/bash 等副作用调用则在执行前返回指令并要求重试；
+- Workspace SQLite 继续作为本地持久化真源，不引入 Redis/PostgreSQL/Docker。高频 session/conversation `lastUsedAt` touch 进入内存 write-behind cache，最多每 5 分钟事务批量 flush，normal shutdown 再显式 flush；create/close/status 等语义性状态仍同步持久化；
+- debug runtime telemetry 定期报告 RSS/heap、transport、process、workspace cache 与 review state 数量，为后续真实实例资源趋势提供可观测性。
+
 必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
 
 ## 0.4 — LSP code intelligence v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -42,7 +42,7 @@
     "debug:accept": "node scripts/debug/accept.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/skills.test.ts && tsx src/workspace-store.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",