@akira-tl/forgerelay 0.3.5 → 0.3.7

package/docs/chatgpt-coding-workflow.md

@@ -18,6 +18,60 @@ existing ID explicitly when the user wants to resume that logical workspace.
 A Git worktree directory is a separate physical workspace target from its source
 checkout, and each conversation can still have its own logical handle for it.
 
+### Bootstrap context and workspace inventory
+
+Normal coding still starts with the shortest path:
+
+```text
+open_workspace(path="~/project")
+```
+
+The default `context="auto"` keeps the first useful bootstrap while avoiding
+replay. ForgeRelay tracks delivered context by conversation plus canonical
+workspace target and a content fingerprint, not by logical `workspaceId`. If the
+same conversation opens or resumes another logical handle for the same physical
+project and the fingerprint is unchanged, the response keeps only lightweight
+workspace metadata. If loaded instruction contents or relevant Skill, Capability
+guide, profile, diagnostic, or nested-instruction metadata changes, the next
+automatic open returns the refreshed bootstrap.
+
+Two explicit controls are available for exceptional cases:
+
+```text
+open_workspace(workspaceId="ws_...", context="full")
+open_workspace(workspaceId="ws_...", context="none")
+```
+
+`full` forces a bootstrap refresh. `none` opens/resumes the workspace without
+returning the full project context and does not record the current fingerprint as
+already delivered. Context-delivery state is independent from logical-workspace
+selection, so closing or switching one handle does not make the conversation
+forget unchanged project context it already received.
+
+Do not enumerate workspace state on every normal open. When the user wants to
+continue an earlier task, choose among logical workspaces, or clean up accumulated
+state, use the same Core tool in inventory mode:
+
+```text
+open_workspace(action="list")
+open_workspace(action="list", root="~/project")
+open_workspace(action="list", staleOnly=true)
+```
+
+Inventory is paginated, defaults to 50 entries, and caps each page at 100. It can
+filter by `workspaceId`, persisted `status`, derived `state`, `mode`, canonical
+root/source root, or stale-only state. Entries include a compact label such as
+`project/ws_...`, checkout/worktree backing metadata, timestamps, idle duration,
+root validity, and whether that logical workspace is currently selected by this
+conversation. Listing is observational and does not refresh `lastUsedAt`.
+
+Treat persisted status and derived state separately. `status="active"` means the
+record has not been explicitly closed. A valid recent record has `state="active"`;
+a valid active record idle for more than two days has `state="stale"`; an active
+record whose root is missing or unusable has `state="invalid"`; and an explicitly
+finalized persisted record has `state="closed"`. Ask the user before cleanup, then
+use the existing `close_workspace` lifecycle on the selected `workspaceId`.
+
 ## Checkout-first behavior
 
 Checkout mode is the default:
@@ -103,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
 
@@ -131,8 +191,9 @@ worktrees, subagents, artifact/change-review workflows, Host/OAuth/MCP App
 integration, and long-running shell/PTY/process behavior. Optional guides are
 advertised only when their feature is enabled; for example, disabled subagents
 and artifact/change-review features do not add those descriptors to bootstrap
-context. Reopening a workspace in the same Host context does not repeat the
-descriptors, but the previously advertised guides remain valid.
+context. Bootstrap replay follows the conversation/canonical-target context
+fingerprint described above, so changing logical `workspaceId` alone does not
+repeat unchanged descriptors; previously advertised guides remain valid.
 
 The fingerprint is also a stale-Host-schema diagnostic. If `open_workspace`
 reports a capability such as `filesystem.rename-move` but the Host's current
@@ -223,12 +284,14 @@ Workspace IDs are logical conversation handles rather than physical-directory
 identities. The same conversation keeps a stable ID for a project, while another
 conversation normally receives a different ID pointing at the same checkout or
 worktree. `open_workspace` can explicitly resume a known `workspaceId`, and a
-fresh logical ID is created only when the user asks for one. When a project has
-other logical workspaces idle for more than two days, `open_workspace` reports
-all of them so the user can choose to resume or clean them up. `close_workspace`
-is the single public close operation: checkout-backed workspaces release the logical
-handle, while managed-worktree-backed workspaces require `commitMessage` and run the
-safe commit / fast-forward-only integration / cleanup lifecycle.
+fresh logical ID is created only when the user asks for one. The normal open path
+may still include `staleWorkspaces` as a passive reminder for same-target handles
+idle for more than two days; use `open_workspace(action="list")` for complete,
+filtered inventory when continuation or cleanup actually requires it.
+`close_workspace` is the single public close operation: checkout-backed workspaces
+release the logical handle, while managed-worktree-backed workspaces require
+`commitMessage` and run the safe commit / fast-forward-only integration / cleanup
+lifecycle.
 
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply

package/docs/configuration.md

@@ -163,12 +163,43 @@ receives a different ID for the same physical checkout/worktree. Pass
 `workspaceId` to `open_workspace` to explicitly resume an existing handle in the
 current conversation. `newWorkspace: true` allocates a new logical handle without
 creating another checkout or Git worktree and should be used only on explicit user
-request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
-the user can choose whether to resume or release them. `close_workspace` removes a
-checkout-backed logical handle without deleting checkout 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.
+request.
+
+Bootstrap delivery is tracked separately from the selected logical workspace.
+`open_workspace` defaults to `context="auto"`: ForgeRelay fingerprints the current
+project context and returns the full AGENTS/Skills/Capability-guide/profile bootstrap
+only when that conversation has not already received the current fingerprint for
+the canonical workspace target. `context="full"` forces a refresh;
+`context="none"` opens or resumes the logical workspace without returning the full
+bootstrap and does not mark the current fingerprint as delivered. Closing or
+switching a logical workspace therefore does not by itself cause unchanged project
+context to be injected again, while changed context produces a new fingerprint and
+is delivered on the next `auto` open.
+
+Use `open_workspace(action="list")` only when the Agent needs to continue an older
+logical workspace, choose among multiple handles, or organize workspace state. The
+inventory is paginated (50 records by default, at most 100) and can filter by
+workspace ID, persisted status, derived state, mode, canonical root/source root, or
+stale-only state. Reading inventory does not refresh `lastUsedAt`. Persisted
+`status="active"` means the record has not been explicitly closed; the derived
+`state` distinguishes `active`, `stale`, `invalid`, and `closed`. A missing checkout
+or externally removed managed-worktree root can therefore remain diagnostically
+`status="active"` while appearing as `state="invalid"`. The existing
+`staleWorkspaces` field remains a passive same-workspace reminder for old handles;
+`action="list"` is the formal on-demand inventory path.
+
+`close_workspace` removes a checkout-backed logical handle without deleting checkout
+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
@@ -176,7 +207,10 @@ result contains `running: true` and a canonical `processId`. Reuse the same `bas
 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.
@@ -325,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

@@ -170,7 +170,29 @@ capability
 - 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
 - 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
 - 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
-- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+- 0.3.5 完成 canonical MCP surface 与 fresh-Host 主验收后，0.3 的 progressive-disclosure 主体设计视为稳定；后续 0.3.x 只接收验收暴露出的兼容性或 lifecycle 补丁，0.4 仍回到原定 LSP code intelligence v1。
+
+### 0.3.6 — Workspace bootstrap 与 inventory 补丁
+
+0.3.6 处理 0.3.5 fresh-Host 验收后暴露的 Workspace 上下文与 logical-workspace 管理问题，不增加新的常驻 MCP tool，也不改变 0.4 的 LSP 主路线：
+
+- `open_workspace` 的 bootstrap 去重从 logical `workspaceId` 身份提升为 conversation scope + canonical workspace target + context fingerprint；同一 conversation 切换到同一物理 checkout/worktree 的其他 logical workspace 时，只要 AGENTS、Skills、Capability guide/profile 等相关上下文没有变化，就不重复注入完整 bootstrap；
+- `open_workspace` 提供 `context="auto" | "full" | "none"`。`auto` 默认只在当前 fingerprint 尚未交付或已变化时返回完整上下文，`full` 强制刷新，`none` 只取得 workspace handle/metadata 且不会把该 fingerprint 标记为已交付；
+- context-delivery 状态与 conversation 当前绑定的 logical workspace 分离持久化，因此关闭或切换 logical handle 不会让 Agent 在同一 conversation 中忘记已经收到的项目上下文；delivery 状态继续服从有限生命周期清理，而不是永久缓存；
+- `open_workspace(action="list")` 成为按需 logical-workspace inventory 入口，不增加 `list_workspaces`/`workspace.list` 第十个 Core tool；普通开发仍直接使用默认 `action="open"`，只有续接旧任务、选择 workspace 或整理状态时才读取 inventory；
+- 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。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.5",
+  "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",

package/scripts/debug/accept.mjs

@@ -223,13 +223,16 @@ try {
   assert.equal(historicalTemplate.text, template.text);
   pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
 
+  const workspaceConversationMeta = { "openai/session": "acceptance-workspace" };
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
     path: checkoutWorkspace,
-  });
+  }, workspaceConversationMeta);
   const workspaceId = opened.structuredContent.workspaceId;
   assert.match(workspaceId, /^ws_/);
+  assert.equal(opened.structuredContent.action, "open");
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
+  assert.equal(typeof opened.structuredContent.contextFingerprint, "string");
   assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
     version: packageJson.version,
     toolMode: "full",
@@ -254,6 +257,56 @@ try {
   ]);
   assert.equal(capabilityCatalog[0].available, true);
   assert.equal(capabilityCatalog[0].guide.name, "lifecycle-hooks");
+
+  const freshLogical = callTool(oauth.accessToken, sessionId, 84, "open_workspace", {
+    path: checkoutWorkspace,
+    newWorkspace: true,
+  }, workspaceConversationMeta);
+  const freshLogicalId = freshLogical.structuredContent.workspaceId;
+  assert.notEqual(freshLogicalId, workspaceId);
+  assert.equal(freshLogical.structuredContent.action, "open");
+  assert.equal(
+    freshLogical.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  assert.equal(freshLogical.structuredContent.agentsFiles, undefined);
+  assert.equal(freshLogical.structuredContent.capabilityGuides, undefined);
+
+  const workspaceInventory = callTool(oauth.accessToken, sessionId, 85, "open_workspace", {
+    action: "list",
+    root: checkoutWorkspace,
+  }, workspaceConversationMeta);
+  assert.equal(workspaceInventory.structuredContent.action, "list");
+  assert.equal(workspaceInventory.structuredContent.summary.matching, 2);
+  const inventoryEntries = workspaceInventory.structuredContent.workspaces;
+  assert.equal(inventoryEntries.length, 2);
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === freshLogicalId)?.current,
+    true,
+  );
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === workspaceId)?.current,
+    false,
+  );
+
+  const closedFreshLogical = callTool(oauth.accessToken, sessionId, 86, "close_workspace", {
+    workspaceId: freshLogicalId,
+  });
+  assert.equal(closedFreshLogical.isError, undefined);
+  const resumedOriginal = callTool(oauth.accessToken, sessionId, 87, "open_workspace", {
+    workspaceId,
+  }, workspaceConversationMeta);
+  assert.equal(resumedOriginal.structuredContent.workspaceId, workspaceId);
+  assert.equal(resumedOriginal.structuredContent.agentsFiles, undefined);
+  assert.equal(
+    resumedOriginal.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  pass(
+    "workspace context + inventory",
+    `${workspaceId} -> ${freshLogicalId} -> list -> close -> resume without bootstrap replay`,
+  );
+
   const directCapability = callTool(oauth.accessToken, sessionId, 79, "capability", {
     workspaceId,
     name: "hooks.check",
@@ -590,12 +643,16 @@ function mcpRequest(accessToken, sessionId, request) {
   return { response, message: parseMcpMessage(response.body, request.id) };
 }
 
-function callTool(accessToken, sessionId, id, name, args) {
+function callTool(accessToken, sessionId, id, name, args, meta) {
   const message = mcpRequest(accessToken, sessionId, {
     jsonrpc: "2.0",
     id,
     method: "tools/call",
-    params: { name, arguments: args },
+    params: {
+      name,
+      arguments: args,
+      ...(meta ? { _meta: meta } : {}),
+    },
   }).message;
   assert.equal(message.id, id);
   assert.ok(message.result, `tool ${name} did not return a result`);