@akira-tl/forgerelay 0.2.5 → 0.3.0

package/docs/chatgpt-coding-workflow.md

@@ -9,14 +9,14 @@ checkout.
 `open_workspace` returns a `workspaceId`. Continue using that ID for later tools
 in the same directory.
 
-Workspace identity follows the canonical opened directory rather than the
-conversation/request identity. Reopening the same checkout reuses the same
-active workspace even from another conversation. Conversation metadata is used
-only to decide whether bootstrap context such as project instructions should be
-repeated to that conversation.
+`workspaceId` is a logical conversation handle, not the physical-directory
+identity. Reopening the same checkout in the same conversation keeps that
+logical ID stable. A different conversation normally receives a different
+`workspaceId` even when it points at the same checkout or worktree; pass an
+existing ID explicitly when the user wants to resume that logical workspace.
 
-A Git worktree directory is a separate workspace identity from its source
-checkout.
+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.
 
 ## Checkout-first behavior
 
@@ -108,6 +108,37 @@ being injected eagerly. Read the relevant nested file before working under that
 `FORGERELAY_AGENT_DIR` is not an instruction source; it remains only a compatibility
 skill-discovery path.
 
+## MCP capability loading
+
+ForgeRelay keeps callable MCP tools and explanatory capability documentation
+separate. `tools/list` remains the source of truth for what the current server
+actually exposes; 0.3 does not hide callable tools behind documentation.
+
+`open_workspace` adds two lightweight discovery surfaces:
+
+- `capabilityFingerprint` is returned on every open/resume and includes the
+  ForgeRelay version, active tool mode, and stable semantic capability names;
+- `capabilityGuides` is returned with bootstrap context and contains compact
+  descriptors for ForgeRelay-owned, versioned guides that can be loaded with
+  the normal `read` tool.
+
+Do not preload every capability guide. Read a guide only when the current task
+needs that domain. Built-in guides cover lifecycle Hooks, advanced managed
+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.
+
+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
+MCP tool snapshot does not expose `rename`, the server and Host metadata are out
+of sync. Refresh/reconnect the MCP integration or start a Host context that
+reloads `tools/list`; do not conclude that the running ForgeRelay server lacks
+that capability. ForgeRelay can report its own version/capabilities but cannot
+force the Host to discard a cached tool schema.
+
 ## Agent Skills
 
 ForgeRelay discovers standard Agent Skills from:
@@ -134,7 +165,11 @@ config directory plus:
 ```
 
 The workspace result exposes only compact profile metadata so the host can
-choose a provider/profile without loading full provider launch details.
+choose a provider/profile without loading full provider launch details. Read the
+ForgeRelay-owned `subagents` capability guide when delegation is actually needed;
+0.3 no longer auto-loads the historical bundled `subagent-delegation` Skill for
+new setups. Existing user-authored or previously seeded Skills remain normal
+user configuration and are not deleted.
 
 The current model-facing delegation workflow is:
 
@@ -168,16 +203,18 @@ The exact lifecycle tools available depend on the active server configuration.
 In minimal mode, normal shell inspection commands such as `rg`, `find`, and `ls`
 can be used rather than dedicated MCP search tools. `bash` waits in the foreground
 for at most 300 seconds. If the command is still running, ForgeRelay returns a
-process `sessionId` without killing it. The Agent can use `write_stdin` to poll,
+canonical `processId` without killing it. The Agent can use `write_stdin` to poll,
 wait again, interact, or explicitly send Ctrl-C, or continue other work; once the
 command finishes, its completion is attached to a later tool result using the
-same workspace ID.
+same workspace ID. The former process `sessionId` remains a deprecated alias in
+0.2.x for compatibility with existing clients.
 
 `FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
 
 Experimental `FORGERELAY_TOOL_MODE=codex` provides a smaller Codex-shaped
 surface including direct `rename`/`delete` path mutations alongside `apply_patch`,
-`exec_command`, and `write_stdin`.
+`exec_command`, and `write_stdin`. `rename` is the unified move/rename primitive
+for both files and directories; ForgeRelay does not expose a separate `move` tool.
 
 Workspace IDs are logical conversation handles rather than physical-directory
 identities. The same conversation keeps a stable ID for a project, while another
@@ -192,10 +229,16 @@ be released that way and must be finalized with `close_worktree`.
 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
 a blanket ban to package managers, generators, formatters, or similar commands
-that write files. The Agent contract still prohibits shell mutation of
-security- or privilege-sensitive operating-system files and credential material,
-and requires an explicit user request before changing configuration files
-through `bash` or `exec_command`.
+that write files. They may also perform external device or hardware mutations
+when the user's current request explicitly asks for the actual device-changing
+operation. A check, audit, probe, backup, verification, dry-run, or build-only
+request does not implicitly authorize a later persistent device write, and
+ForgeRelay does not assume a particular flashing protocol or transport.
+
+The Agent contract still prohibits shell mutation of security- or
+privilege-sensitive operating-system files and credential material, and requires
+an explicit user request before changing configuration files through `bash` or
+`exec_command`.
 
 ## Change review UI
 

package/docs/configuration.md

@@ -123,6 +123,35 @@ MCP clients discover metadata from:
 explicit tool mode is unset. The corresponding legacy `DEVSPACE_*` names are
 also accepted.
 
+The selected mode controls the real `tools/list` surface. ForgeRelay does not
+hide callable tools behind capability documentation. In every mode,
+`open_workspace` returns a `capabilityFingerprint` containing the package
+version, tool mode, and stable semantic capability names. The fingerprint also
+reports enabled optional domains such as subagent profile discovery, native
+artifact download, MCP App UI, or aggregate `show_changes` review when those
+features are actually available; it remains a semantic summary rather than a
+copy of `tools/list`.
+
+Bootstrap responses also return `capabilityGuides`, which are compact descriptors
+for built-in ForgeRelay documentation that the Agent can explicitly load with
+`read` when a task needs that domain. Current built-in domains cover lifecycle
+Hooks, managed worktrees, subagents, artifact/change-review workflows, Host/OAuth/
+MCP App integration, and long-running shell/PTY/process behavior. Optional-domain
+descriptors such as `subagents` and `artifacts-review` are advertised only when
+the corresponding feature is enabled, so disabled features do not add bootstrap
+context.
+
+There is no separate progressive-disclosure configuration switch. Capability
+Guide discovery is built in, while actual tool exposure continues to be
+controlled by `FORGERELAY_TOOL_MODE` and feature-specific settings. If the
+fingerprint reports a capability that is missing from the Host's current tool
+snapshot, treat that as stale Host MCP metadata: reconnect/refresh the integration
+or use a Host context that reloads `tools/list`. The ForgeRelay process cannot
+force a Host to invalidate its cached schema.
+
+`rename` is the canonical move/rename primitive for files and directories; there
+is no separate `move` MCP tool.
+
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
@@ -132,16 +161,17 @@ 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. Sessions idle for more than two days are returned in `staleWorkspaces` so
+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
 logical handle without deleting checkout files; it refuses to remove the last
 handle anchoring a physical worktree.
 
 `bash` has no execution-timeout input. It waits in the foreground for at most 300
 seconds; if the process is still alive, the result contains `running: true` and a
-`sessionId`. `write_stdin` can poll or interact with that session for up to another
-300 seconds per call. ForgeRelay does not kill a process merely because a wait
-window expires. Completed background processes are delivered once with a later
+canonical `processId`. `write_stdin` can poll or interact with that process for up
+to another 300 seconds per call. The former `sessionId` field remains a deprecated
+alias during the 0.2.x compatibility window. 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.
 
 ## Widgets
@@ -315,7 +345,8 @@ When subagents are enabled, profiles are discovered from:
 - active legacy config directory `~/.devspace/agents/*.md` when reused;
 - project `.devspace/agents/*.md` for migration compatibility.
 
-The bundled `subagent-delegation` skill teaches the current CLI workflow:
+The ForgeRelay-owned `subagents` capability guide teaches the current CLI
+workflow on demand:
 
 ```bash
 forgerelay agents ls
@@ -323,6 +354,11 @@ forgerelay agents run <profile-or-provider-or-id> "<prompt>"
 forgerelay agents show <id>
 ```
 
+0.3 no longer auto-discovers or seeds the package's historical bundled
+`subagent-delegation` Skill for new setups. An existing or user-authored Skill
+with that name remains an ordinary Skill and is still discovered from the normal
+Skill paths when subagents are enabled; ForgeRelay does not delete or rewrite it.
+
 ## Logging
 
 | Variable | Default |
@@ -333,14 +369,15 @@ forgerelay agents show <id>
 | `FORGERELAY_LOG_ASSETS` | `0` |
 | `FORGERELAY_LOG_TOOL_CALLS` | `1` |
 | `FORGERELAY_LOG_SHELL_COMMANDS` | `1` in `pretty`, `0` in `json` |
-| `FORGERELAY_TRUST_PROXY` | `0` |
+| `FORGERELAY_TRUST_PROXY` | auto: `1` only for loopback bind + non-loopback public URL; otherwise `0` |
 
 `pretty` is the human-facing local console format. It uses terminal-aware color,
 short timestamps, workspace-first context, and compact operation results while
 keeping HTTP request records off by default. Project names receive stable
 per-project colors and logical `ws_...` identifiers remain visible; transient MCP
-transport session IDs and normal session lifecycle events are shown only at
-`debug` level. Shell command previews are enabled
+transport session IDs and normal transport lifecycle events are shown only at
+`debug` level, where they are labeled as `transport` rather than workspace/process
+identity. Shell command previews are enabled
 in this mode and truncated to 120 characters; set
 `FORGERELAY_LOG_SHELL_COMMANDS=0` when command arguments may contain secrets.
 
@@ -349,6 +386,14 @@ overridden, JSON mode preserves request logging and omits shell command previews
 `FORGERELAY_LOG_REQUESTS` and `FORGERELAY_LOG_SHELL_COMMANDS` always override
 these format-specific defaults when set.
 
+When ForgeRelay binds to loopback (`127.0.0.1`, `::1`, or `localhost`) but is
+configured with a non-loopback public URL, it automatically trusts exactly one
+upstream proxy hop. This matches the normal tunnel/reverse-proxy topology and
+keeps OAuth rate limiting aligned with Express client-IP resolution. Set
+`FORGERELAY_TRUST_PROXY=0` to disable this inference, or `=1` to enable one-hop
+trust explicitly. ForgeRelay never auto-enables proxy trust when binding to
+`0.0.0.0` or another directly reachable interface.
+
 ## Environment-only example
 
 ```bash

package/docs/debugging.md

@@ -59,10 +59,10 @@ The acceptance checks:
 3. unauthenticated `/mcp` rejection;
 4. dynamic OAuth client registration, PKCE Owner-password approval, and access-token exchange;
 5. MCP `initialize`, including package/server version consistency and the shell mutation safety contract;
-6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-session schema, and MCP App tool metadata;
+6. `tools/list` for the full debug tool surface, including `close_workspace`, `write_stdin`, canonical `processId` plus the deprecated `sessionId` compatibility alias, the non-blanket `bash` mutation policy, no kill-timeout input, the 300-second foreground-wait contract, workspace resume/stale-workspace schema, and MCP App tool metadata;
 7. the full MCP App template chain: `resources/list`, `resources/templates/list`, current content-hashed `resources/read`, legacy/historical template compatibility reads, `text/html;profile=mcp-app`, CSP resource domains, and an HTTP fetch of the JavaScript asset referenced by the template;
-8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessSessionManager`, and a deliberate failed `edit`;
-9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP session, plus rejection of an arbitrary path outside the workspace/temp roots;
+8. a real checkout workspace with `write`, `read`, `rename`, `delete`, foreground `bash` through `ProcessManager`, and a deliberate failed `edit`;
+9. OS temp-directory `write` → `read` → `edit` → `rename` → `delete` over the same real MCP transport session, plus rejection of an arbitrary path outside the workspace/temp roots;
 10. a temporary Git repository with managed worktree creation, file modification, and `close_worktree`;
 11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；
 12. deterministic local subagent error path，不联系任何模型 provider；

package/docs/roadmap.md

@@ -99,10 +99,36 @@ Hooks v1 的目标是给用户和 Agent 一个很小、自动、可组合的生
 - `workspaceId` 是唯一持久的逻辑工作身份，跨请求和 transport 重连保持连续；
 - `requestId` 只追踪单次 HTTP/JSON-RPC 请求，不持久化；
 - MCP 协议层 session 在内部和 debug 输出中明确称为 `transportSessionId`，业务状态不得依赖它；
-- 后台命令句柄逐步迁移为 `processId` / process handle；若公开 schema 改名需要兼容窗口，则在明确的版本边界完成；
+- 后台命令句柄以 `processId` / process handle 为 canonical 名称，旧 `sessionId` 在 0.2.x 保留 deprecated alias 兼容窗口；
 - 为 stateless MCP transport 做准备，同时保留旧协议兼容 adapter，避免把 transport 生命周期重新提升成 ForgeRelay 会话模型。
 
-## 0.3 — LSP code intelligence v1
+## 0.3 — MCP loading 与渐进式能力披露
+
+0.3 的目标是缩小 MCP 首次加载时注入给 Agent 的上下文，同时保持工具可调用性、安全边界和 Host 编排权不变。ForgeRelay 不再把所有低频能力说明都塞进 server instructions 或工具 description，而是把模型接口拆成三层：
+
+- `tools/list` 继续暴露真实可调用 primitive，并只携带调用该工具所必需的简洁语义；
+- `open_workspace` 返回紧凑的 server/capability 摘要与版本指纹，帮助 Agent 发现能力，并识别 Host 持有旧 tool schema snapshot 的情况；
+- ForgeRelay-owned capability guide 提供低频能力的完整说明，由 Agent 在任务相关时显式 `read`，而不是首次连接时自动注入。
+
+首版优先复用现有 Skill-style 的 advertised path / `read` 授权机制，而不是新增第二套文档加载协议。Capability guide 与 Skill 的语义所有权保持区分：Skill 描述用户、项目或生态工作流；capability guide 描述 ForgeRelay 自身、与版本绑定的产品能力。
+
+Core Capability Contract 必须始终内联保留至少这些信息：
+
+- `workspaceId` 生命周期与 workspace 复用规则；
+- 常用文件读写改、`rename` 同时承担 move/rename、删除的核心语义；
+- shell 以本地用户权限执行且不是 OS sandbox；
+- `processId` / `write_stdin` 的基本长进程语义；
+- Hook 阻断结果必须对 Agent 可见；
+- 关键 mutation/safety invariant；
+- `close_workspace` 与 `close_worktree` 的区别。
+
+适合按需读取的首批领域包括：生命周期 Hooks、managed worktree 高级流程、subagents、artifact/review 工作流、debug/MCP App、OAuth/deployment，以及 shell/PTTY/process 的低频边界情况。首个实现切片迁移 Hooks 与 managed worktree 高级说明；第二切片继续覆盖 subagents、artifact/review、Host/OAuth/MCP App integration 与 shell/PTTY/process，并把历史 bundled `subagent-delegation` Skill 的默认自动发现迁回 ForgeRelay-owned capability guide。必要安全语义始终保留在 core contract 或真实 tool schema/description 中。
+
+Capability/version fingerprint 必须是轻量、语义化、稳定的摘要，不复制完整 `tools/list`。当 server 报告的能力与 Host 当前暴露的 tool snapshot 明显不一致时，Agent 应能判断为 Host metadata stale，并建议刷新 MCP 或开启新会话，而不是错误断言 ForgeRelay 缺少能力。
+
+0.3 不隐藏 callable tool，不增加隐式 autonomous workflow，也不把 Host Refresh/session 行为归到 ForgeRelay。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
+
+## 0.4 — LSP code intelligence v1
 
 LSP is moderate implementation complexity if ForgeRelay does not become a
 language-server installer.
@@ -110,7 +136,7 @@ language-server installer.
 The first version should launch only language servers already available on the
 user's machine or explicitly configured by the user/project.
 
-During 0.3 development, MCP App UI hardening can land alongside the LSP work when
+During 0.4 development, MCP App UI hardening can land alongside the LSP work when
 it does not distort the code-intelligence scope. In particular, evaluate a more
 self-contained template/bootstrap bundle, reduce avoidable external chunk fetches,
 and keep the current content-hash/compatibility-resource contract intact. This is
@@ -144,7 +170,7 @@ Candidate servers include `typescript-language-server`/tsserver, Pyright,
 `rust-analyzer`, `gopls`, and `clangd`, but ForgeRelay should treat server
 commands/configuration as external dependencies.
 
-## 0.4 — First-class subagent MCP
+## 0.5 — First-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions.
 The next step is to remove the current `bash -> forgerelay agents ...` indirection

package/docs/security.md

@@ -28,6 +28,17 @@ Filesystem-oriented tools canonicalize existing path segments before access so
 symlinks inside either the workspace or OS temp directory cannot escape to
 arbitrary filesystem locations.
 
+`read` has one narrow additional path class for explicitly advertised documents.
+`open_workspace` may advertise a Skill entry file or a ForgeRelay capability
+Guide outside the normal workspace/temp roots. Only that advertised entry file is
+readable initially; after it is read, files inside that advertised document's
+own directory may be read as supporting material. This does not expand write,
+edit, rename, delete, shell working-directory, or workspace-open roots.
+
+Capability Guides are ForgeRelay-owned, versioned package documentation. Their
+paths are surfaced by the running server rather than guessed by the Agent. This
+keeps progressive disclosure from becoming a general arbitrary-file read escape.
+
 ## Owner-password OAuth
 
 New installations store local configuration in:
@@ -100,13 +111,19 @@ for dynamically crossing such a boundary.
 The Agent-facing shell contract therefore does not ban every command that can
 change files. Commands may modify ordinary project files when that is a natural
 part of the user's requested development task, including package managers,
-generators, formatters, and similar tooling. The contract does prohibit shell
-mutation of security- or privilege-sensitive operating-system files and
-credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, PAM or
-authentication policy, SSH private keys, and equivalent privileged targets.
-Configuration files may be changed through shell only when the user's request
-explicitly calls for that configuration change rather than merely making it a
-convenient implementation detail.
+generators, formatters, and similar tooling. Shell commands may also perform
+external device or hardware mutations when the user's current request explicitly
+asks for the actual device-changing operation. ForgeRelay does not assume a
+particular flashing protocol, transport, device path, or firmware workflow. A
+check, audit, probe, backup, verification, dry-run, or build-only request must not
+be treated as authorization for a later persistent hardware write.
+
+The contract does prohibit shell mutation of security- or privilege-sensitive
+operating-system files and credential material such as `/etc/sudoers`,
+`/etc/passwd`, `/etc/shadow`, PAM or authentication policy, SSH private keys, and
+equivalent privileged targets. Configuration files may be changed through shell
+only when the user's request explicitly calls for that configuration change
+rather than merely making it a convenient implementation detail.
 
 This is an Agent execution policy, not an OS-level sandbox or command parser.
 Operators that need a stronger project-specific runtime gate can use blocking
@@ -124,8 +141,9 @@ Do not describe ForgeRelay as a sandboxed coding environment.
 
 Shell execution has a 300-second foreground wait ceiling, not a 300-second
 process lifetime. When `bash` is still running after that window, ForgeRelay
-returns a process `sessionId` and leaves the process alive. `write_stdin` can poll,
-wait, interact, or explicitly interrupt it. An asynchronously completed process
+returns a canonical `processId` and leaves the process alive. `write_stdin` can
+poll, wait, interact, or explicitly interrupt it. The former process `sessionId`
+remains a deprecated compatibility alias during 0.2.x. An asynchronously completed process
 is reported on a later tool result for the same logical workspace ID, including
 error-result paths, and is never broadcast to another workspace ID. Explicitly
 resuming the same workspace ID in another conversation intentionally transfers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -24,6 +24,7 @@
     "examples",
     "scripts",
     "skills",
+    "capabilities",
     "README.md",
     "CHANGELOG.md",
     "NOTICE.md"
@@ -34,14 +35,14 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
-    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json",
+    "build": "npm run clean && npm run build:app && tsc -p tsconfig.build.json && node scripts/ensure-cli-executable.mjs",
     "build:app": "vite build",
     "dev": "node scripts/debug/serve.mjs",
     "debug:serve": "node scripts/debug/serve.mjs",
     "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/mcp-app-template.test.ts && tsx src/hooks.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/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",
     "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

@@ -93,6 +93,9 @@ try {
   assert.match(serverInstructions, /Shell commands may modify ordinary project files/);
   assert.match(serverInstructions, /\/etc\/sudoers/);
   assert.match(serverInstructions, /configuration files through shell only when the user's request explicitly calls for that configuration change/);
+  assert.match(serverInstructions, /managed-worktrees capability guide/);
+  assert.ok(serverInstructions.length < 3_000, `server instructions should stay compact, got ${serverInstructions.length} characters`);
+  assert.doesNotMatch(serverInstructions, /fast-forwards the original target branch/);
   assert.doesNotMatch(serverInstructions, /Do not create or modify files with bash/);
   pass(
     "MCP initialize",
@@ -118,18 +121,30 @@ try {
     assert.ok(toolNames.includes(expected), `missing debug tool ${expected}`);
   }
   const bashTool = tools.find((tool) => tool.name === "bash");
-  assert.match(bashTool?.description ?? "", /may modify ordinary project files/);
-  assert.match(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.match(bashTool?.description ?? "", /local user's authority/);
+  assert.doesNotMatch(bashTool?.description ?? "", /may modify ordinary project files/);
+  assert.doesNotMatch(bashTool?.description ?? "", /\/etc\/sudoers/);
+  assert.doesNotMatch(bashTool?.description ?? "", /external device or hardware mutations/);
   assert.doesNotMatch(bashTool?.description ?? "", /Do not use bash to create, move, rename, or delete project files/);
   assert.equal(bashTool?.inputSchema?.properties?.timeout, undefined);
   assert.match(bashTool?.description ?? "", /waits up to 300 seconds/);
   assert.match(bashTool?.description ?? "", /write_stdin/);
   const writeStdinTool = tools.find((tool) => tool.name === "write_stdin");
   assert.equal(writeStdinTool?.inputSchema?.properties?.yieldTimeMs?.maximum, 300000);
+  assert.match(
+    writeStdinTool?.inputSchema?.properties?.processId?.description ?? "",
+    /Canonical process identifier/,
+  );
+  assert.match(
+    writeStdinTool?.inputSchema?.properties?.sessionId?.description ?? "",
+    /Deprecated alias for processId/,
+  );
   const openWorkspaceTool = tools.find((tool) => tool.name === "open_workspace");
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.workspaceId);
   assert.ok(openWorkspaceTool?.inputSchema?.properties?.newWorkspace);
   assert.ok(openWorkspaceTool?.outputSchema?.properties?.staleWorkspaces);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityFingerprint);
+  assert.ok(openWorkspaceTool?.outputSchema?.properties?.capabilityGuides);
   const templateUri = bashTool?._meta?.ui?.resourceUri;
   assert.match(
     templateUri ?? "",
@@ -195,7 +210,35 @@ try {
   assert.match(workspaceId, /^ws_/);
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
-  pass("open_workspace", `${workspaceId} -> ${opened.structuredContent.root}`);
+  assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
+    version: packageJson.version,
+    toolMode: "full",
+    capabilities: [
+      "workspace.close",
+      "worktree.managed",
+      "filesystem.rename-move",
+      "filesystem.delete",
+      "process.write-stdin",
+      "hooks.lifecycle",
+      "capability-guides.read",
+      "inspection.search-tools",
+      "ui.mcp-app",
+    ],
+  });
+  const capabilityGuides = opened.structuredContent.capabilityGuides;
+  assert.deepEqual(capabilityGuides.map((guide) => guide.name), [
+    "lifecycle-hooks",
+    "managed-worktrees",
+    "host-integration",
+    "shell-processes",
+  ]);
+  const hooksGuide = callTool(oauth.accessToken, sessionId, 78, "read", {
+    workspaceId,
+    path: capabilityGuides[0].path,
+  });
+  assert.match(hooksGuide.structuredContent.result, /BeforeTool/);
+  assert.match(hooksGuide.structuredContent.result, /BeforeWorktreeClose/);
+  pass("open_workspace", `${workspaceId} -> fingerprint + ${capabilityGuides.length} capability guides`);
 
   const written = callTool(oauth.accessToken, sessionId, 4, "write", {
     workspaceId,
@@ -217,7 +260,7 @@ try {
   });
   assert.match(shell.structuredContent.result, /debug-bash-ok/);
   assert.equal(shell.structuredContent.running, false);
-  pass("bash", "foreground command completed through ProcessSessionManager");
+  pass("bash", "foreground command completed through ProcessManager");
 
   const failedEdit = callTool(oauth.accessToken, sessionId, 7, "edit", {
     workspaceId,

package/scripts/ensure-cli-executable.mjs

@@ -0,0 +1,12 @@
+import { chmodSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+if (process.platform !== "win32") {
+  const cliPath = fileURLToPath(new URL("../dist/cli.js", import.meta.url));
+  const currentMode = statSync(cliPath).mode;
+  chmodSync(cliPath, currentMode | 0o111);
+
+  if ((statSync(cliPath).mode & 0o111) === 0) {
+    throw new Error(`ForgeRelay CLI is not executable after build: ${cliPath}`);
+  }
+}