@akira-tl/forgerelay 0.3.4 → 0.3.6

package/dist/workspaces.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
@@ -27,8 +27,9 @@ export class WorkspaceRegistry {
     async openWorkspace(input, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
         const workspaceInput = typeof input === "string" ? { path: input } : input;
+        const bootstrapContext = workspaceInput.context ?? "auto";
         if (workspaceInput.workspaceId) {
-            return this.resumeWorkspace(workspaceInput.workspaceId, openOptions.conversationScopeId);
+            return this.resumeWorkspace(workspaceInput.workspaceId, openOptions.conversationScopeId, bootstrapContext);
         }
         if (!workspaceInput.path) {
             throw new Error("open_workspace requires either path or workspaceId.");
@@ -37,24 +38,138 @@ export class WorkspaceRegistry {
         if (mode === "worktree") {
             return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
         }
-        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false);
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false, bootstrapContext);
     }
-    async resumeWorkspace(workspaceId, conversationScopeId) {
+    async listWorkspaces(input = {}, openOptions = {}) {
+        this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
+        const now = Date.now();
+        const sessions = this.store
+            ? this.store.listSessions()
+            : [...this.workspaces.values()].map((workspace) => ({
+                id: workspace.id,
+                root: workspace.root,
+                status: "active",
+                mode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+                baseRef: workspace.worktree?.baseRef,
+                baseSha: workspace.worktree?.baseSha,
+                branch: workspace.worktree?.branch,
+                targetBranch: workspace.worktree?.targetBranch,
+                managed: workspace.worktree?.managed ?? false,
+                createdAt: "",
+                lastUsedAt: "",
+            }));
+        const currentWorkspaceIds = new Set(openOptions.conversationScopeId && this.store
+            ? this.store
+                .listConversationBindings()
+                .filter((binding) => binding.conversationScopeId === openOptions.conversationScopeId)
+                .map((binding) => binding.workspaceSessionId)
+            : []);
+        const rootKey = input.root
+            ? await canonicalPath(assertAllowedPath(input.root, [...this.config.allowedRoots, this.config.worktreeRoot]))
+            : undefined;
+        const entries = await Promise.all(sessions.map(async (session) => {
+            const rootValid = await this.validSessionRoot(session) !== undefined;
+            const lastUsedAt = Date.parse(session.lastUsedAt);
+            const idleMs = Number.isFinite(lastUsedAt) ? Math.max(0, now - lastUsedAt) : 0;
+            const state = session.status !== "active"
+                ? "closed"
+                : !rootValid
+                    ? "invalid"
+                    : idleMs >= WORKSPACE_STALE_REMINDER_MS
+                        ? "stale"
+                        : "active";
+            const projectRoot = session.sourceRoot ?? session.root;
+            return {
+                label: `${basename(resolve(projectRoot)) || "workspace"}/${session.id}`,
+                workspaceId: session.id,
+                root: session.root,
+                status: session.status,
+                state,
+                mode: session.mode,
+                sourceRoot: session.sourceRoot,
+                branch: session.branch,
+                targetBranch: session.targetBranch,
+                managed: session.managed,
+                createdAt: session.createdAt,
+                lastUsedAt: session.lastUsedAt,
+                idleMs,
+                rootValid,
+                current: currentWorkspaceIds.has(session.id),
+            };
+        }));
+        const filtered = [];
+        for (let index = 0; index < sessions.length; index += 1) {
+            const session = sessions[index];
+            const entry = entries[index];
+            if (!session || !entry)
+                continue;
+            if (input.workspaceId && entry.workspaceId !== input.workspaceId)
+                continue;
+            if (input.status && entry.status !== input.status)
+                continue;
+            if (input.state && entry.state !== input.state)
+                continue;
+            if (input.mode && entry.mode !== input.mode)
+                continue;
+            if (input.staleOnly && entry.state !== "stale")
+                continue;
+            if (rootKey) {
+                const sessionRootKey = await canonicalPath(session.root);
+                const sourceRootKey = session.sourceRoot ? await canonicalPath(session.sourceRoot) : undefined;
+                if (sessionRootKey !== rootKey && sourceRootKey !== rootKey)
+                    continue;
+            }
+            filtered.push(entry);
+        }
+        const summary = filtered.reduce((counts, entry) => {
+            counts[entry.state] += 1;
+            return counts;
+        }, { active: 0, stale: 0, invalid: 0, closed: 0 });
+        const offset = Math.max(0, input.offset ?? 0);
+        const limit = Math.min(100, Math.max(1, input.limit ?? 50));
+        return {
+            workspaces: filtered.slice(offset, offset + limit),
+            summary: {
+                total: entries.length,
+                matching: filtered.length,
+                ...summary,
+            },
+            page: {
+                offset,
+                limit,
+                hasMore: offset + limit < filtered.length,
+            },
+        };
+    }
+    async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
         const workspace = this.getWorkspace(workspaceId);
         const context = await this.reusedWorkspaceContext(workspace);
         if (!conversationScopeId || !this.store) {
-            return { ...context, includeBootstrapContext: true };
+            return {
+                ...context,
+                includeBootstrapContext: bootstrapContext !== "none",
+            };
         }
         const targetKeys = await this.workspaceTargetKeys(workspace);
-        const alreadyBound = targetKeys.some((targetKey) => this.store?.getConversationBinding(conversationScopeId, targetKey)?.workspaceSessionId === workspace.id);
+        const contextAlreadyDelivered = targetKeys.some((targetKey) => this.store?.getContextDelivery(conversationScopeId, targetKey)?.contextFingerprint ===
+            context.contextFingerprint);
+        const includeBootstrapContext = resolveBootstrapContextVisibility(bootstrapContext, contextAlreadyDelivered);
         for (const targetKey of targetKeys) {
             this.store.setConversationBinding({
                 conversationScopeId,
                 targetKey,
                 workspaceSessionId: workspace.id,
             });
+            if (includeBootstrapContext) {
+                this.store.setContextDelivery({
+                    conversationScopeId,
+                    targetKey,
+                    contextFingerprint: context.contextFingerprint,
+                });
+            }
         }
-        return { ...context, includeBootstrapContext: !alreadyBound };
+        return { ...context, includeBootstrapContext };
     }
     async listStaleWorkspaces(workspace) {
         if (!this.store)
@@ -206,12 +321,12 @@ export class WorkspaceRegistry {
         }
         return { ...result, hookReports };
     }
-    async openReusableCheckout(path, conversationScopeId, newWorkspace) {
+    async openReusableCheckout(path, conversationScopeId, newWorkspace, bootstrapContext) {
         const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
         const projectKey = await canonicalPath(allowedPath);
         const targetKey = JSON.stringify(["checkout", projectKey, null]);
         if (!newWorkspace) {
-            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey);
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey, bootstrapContext);
             if (boundContext)
                 return boundContext;
         }
@@ -220,7 +335,7 @@ export class WorkspaceRegistry {
             const freshContext = reusableWorkspace
                 ? await this.cloneWorkspaceContext(reusableWorkspace)
                 : await this.openCheckoutWorkspace(path);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
         }
         const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
         const context = await this.openOnce(operationKey, async () => {
@@ -231,18 +346,19 @@ export class WorkspaceRegistry {
                 ? this.cloneWorkspaceContext(reusableWorkspace)
                 : this.reusedWorkspaceContext(reusableWorkspace);
         });
-        return this.withConversationContext(context, conversationScopeId, targetKey);
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
     async openReusableWorktree(input, conversationScopeId) {
         const path = input.path;
         if (!path)
             throw new Error("Worktree mode requires path.");
+        const bootstrapContext = input.context ?? "auto";
         const managedPath = this.tryManagedWorktreePath(path);
         if (managedPath) {
             const worktreeKey = await canonicalPath(managedPath);
             const targetKey = JSON.stringify(["worktree-path", worktreeKey]);
             if (!input.newWorkspace) {
-                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey);
+                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey, bootstrapContext);
                 if (boundContext)
                     return boundContext;
             }
@@ -251,7 +367,7 @@ export class WorkspaceRegistry {
                 if (!reusableWorkspace) {
                     throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
                 }
-                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey);
+                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey, bootstrapContext);
             }
             const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
             const context = await this.openOnce(operationKey, async () => {
@@ -263,7 +379,7 @@ export class WorkspaceRegistry {
                     ? this.cloneWorkspaceContext(reusableWorkspace)
                     : this.reusedWorkspaceContext(reusableWorkspace);
             });
-            return this.withConversationContext(context, conversationScopeId, targetKey);
+            return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
         const resolvedBase = await resolveManagedWorktreeBase({
             sourcePath: path,
@@ -274,13 +390,13 @@ export class WorkspaceRegistry {
         const targetKey = JSON.stringify(["worktree", sourceKey, resolvedBase.targetBranch]);
         if (input.newWorktree) {
             const context = await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(context, conversationScopeId, targetKey);
+            return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
         if (!input.newWorkspace) {
             const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session) => session.mode === "worktree" &&
                 session.sourceRoot !== undefined &&
                 await canonicalPath(session.sourceRoot) === sourceKey &&
-                session.targetBranch === resolvedBase.targetBranch);
+                session.targetBranch === resolvedBase.targetBranch, bootstrapContext);
             if (boundContext)
                 return boundContext;
         }
@@ -289,7 +405,7 @@ export class WorkspaceRegistry {
             const freshContext = reusableWorkspace
                 ? await this.cloneWorkspaceContext(reusableWorkspace)
                 : await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
         }
         const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
         const context = await this.openOnce(operationKey, async () => {
@@ -300,7 +416,7 @@ export class WorkspaceRegistry {
                 ? this.cloneWorkspaceContext(reusableWorkspace)
                 : this.reusedWorkspaceContext(reusableWorkspace);
         });
-        return this.withConversationContext(context, conversationScopeId, targetKey);
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
     async openOnce(operationKey, open) {
         const pending = this.pendingOpens.get(operationKey);
@@ -338,7 +454,7 @@ export class WorkspaceRegistry {
             ? JSON.stringify(["conversation", conversationScopeId, targetKey])
             : targetKey;
     }
-    async boundConversationContext(conversationScopeId, targetKey, mode, matches) {
+    async boundConversationContext(conversationScopeId, targetKey, mode, matches, bootstrapContext) {
         if (!conversationScopeId || !this.store)
             return undefined;
         const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
@@ -359,24 +475,30 @@ export class WorkspaceRegistry {
             return undefined;
         }
         const context = await this.reusedWorkspaceContext(this.getWorkspace(session.id));
-        this.store.touchConversationBinding(conversationScopeId, targetKey);
-        return { ...context, includeBootstrapContext: false };
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
-    withConversationContext(context, conversationScopeId, targetKey) {
+    withConversationContext(context, conversationScopeId, targetKey, bootstrapContext) {
         if (!conversationScopeId || !this.store) {
-            return { ...context, includeBootstrapContext: true };
-        }
-        const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
-        if (binding?.workspaceSessionId === context.workspace.id) {
-            this.store.touchConversationBinding(conversationScopeId, targetKey);
-            return { ...context, includeBootstrapContext: false };
+            return {
+                ...context,
+                includeBootstrapContext: bootstrapContext !== "none",
+            };
         }
+        const delivery = this.store.getContextDelivery(conversationScopeId, targetKey);
+        const includeBootstrapContext = resolveBootstrapContextVisibility(bootstrapContext, delivery?.contextFingerprint === context.contextFingerprint);
         this.store.setConversationBinding({
             conversationScopeId,
             targetKey,
             workspaceSessionId: context.workspace.id,
         });
-        return { ...context, includeBootstrapContext: true };
+        if (includeBootstrapContext) {
+            this.store.setContextDelivery({
+                conversationScopeId,
+                targetKey,
+                contextFingerprint: context.contextFingerprint,
+            });
+        }
+        return { ...context, includeBootstrapContext };
     }
     pruneIdleWorkspaceSessions(protectedWorkspaceIds, force = false) {
         if (!this.store)
@@ -397,6 +519,13 @@ export class WorkspaceRegistry {
                 this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
             }
         }
+        for (const delivery of this.store.listContextDeliveries()) {
+            const deliveredAt = Date.parse(delivery.deliveredAt);
+            if (Number.isFinite(deliveredAt) &&
+                now - deliveredAt >= WORKSPACE_SESSION_IDLE_TTL_MS) {
+                this.store.deleteContextDelivery(delivery.conversationScopeId, delivery.targetKey);
+            }
+        }
         const boundWorkspaceIds = new Set(this.store.listConversationBindings().map((binding) => binding.workspaceSessionId));
         const worktreeAnchors = new Map();
         for (const session of activeSessions) {
@@ -499,13 +628,17 @@ export class WorkspaceRegistry {
         });
     }
     async reusedWorkspaceContext(workspace) {
+        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);
+        const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            contextFingerprint,
             hookReports: [],
             workspaceReused: true,
             includeBootstrapContext: true,
@@ -676,10 +809,12 @@ export class WorkspaceRegistry {
         });
         const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
         const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            contextFingerprint,
             hookReports,
             workspaceReused: false,
             includeBootstrapContext: true,
@@ -761,6 +896,51 @@ export class WorkspaceRegistry {
         return discovered.sort((a, b) => a.path.localeCompare(b.path));
     }
 }
+function resolveBootstrapContextVisibility(mode, contextAlreadyDelivered) {
+    if (mode === "full")
+        return true;
+    if (mode === "none")
+        return false;
+    return !contextAlreadyDelivered;
+}
+function bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles) {
+    const payload = {
+        agentsFiles: agentsFiles
+            .map((file) => ({ path: resolve(file.path), content: file.content }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
+        availableAgentsFiles: availableAgentsFiles
+            .map((file) => resolve(file.path))
+            .sort((left, right) => left.localeCompare(right)),
+        skills: workspace.skills
+            .map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            filePath: resolve(skill.filePath),
+            disableModelInvocation: skill.disableModelInvocation ?? false,
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath)),
+        skillDiagnostics: workspace.skillDiagnostics,
+        capabilityGuides: workspace.capabilityGuides
+            .map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            filePath: resolve(guide.filePath),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+        agentProfiles: workspace.agentProfiles
+            .map((profile) => ({
+            name: profile.name,
+            description: profile.description,
+            provider: profile.provider,
+            model: profile.model,
+            thinking: profile.thinking,
+            filePath: resolve(profile.filePath),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    };
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
 async function canonicalPath(path) {
     const missingSegments = [];
     let candidate = path;

package/docs/artifact-exchange.md

@@ -14,11 +14,12 @@ The legacy `DEVSPACE_ARTIFACTS` variable remains a fallback during migration.
 ## Workflow
 
 1. Open the destination project with `open_workspace`.
-2. Call `download_artifact` with the native file value supplied by the MCP host,
-   the existing `workspaceId`, and a workspace-relative destination path.
+2. Call the `capability` Gateway with `name="artifact.download"`, `action="run"`,
+   the existing `workspaceId`, the native file value in the Gateway's top-level
+   `file` slot, and a workspace-relative destination in `arguments.path`.
 3. Use the returned normalized path with ordinary ForgeRelay file tools.
 
-The tool creates missing parent directories and refuses to overwrite an existing
+The capability creates missing parent directories and refuses to overwrite an existing
 destination.
 
 ## Input boundary

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:
@@ -131,8 +185,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
@@ -209,7 +264,9 @@ killing it. Reuse `bash(action="process", processId=...)` to poll/wait, send inp
 resize a PTY, or interrupt the existing process; or continue other work and consume
 the one-shot completion notice from a later result in the same workspace.
 
-`FORGERELAY_TOOL_MODE=full` adds dedicated search/directory tools.
+`FORGERELAY_TOOL_MODE=full` is retained as a compatibility value and exposes the
+same canonical 9-tool surface as `minimal`; use `bash` for search and directory
+inspection.
 
 Experimental `FORGERELAY_TOOL_MODE=codex` keeps its Codex-shaped compatibility
 surface, including direct `rename`/`delete` path mutations alongside `apply_patch`,
@@ -221,12 +278,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
@@ -247,8 +306,8 @@ an explicit user request before changing configuration files through `bash` or
 By default `FORGERELAY_WIDGETS=full` attaches ChatGPT Apps-compatible UI to the
 normal workspace/file/edit/shell tools.
 
-`FORGERELAY_WIDGETS=changes` exposes aggregate `show_changes` behavior and keeps
-widget usage focused on workspace/change review.
+`FORGERELAY_WIDGETS=changes` enables aggregate `review.changes` Capability results
+and keeps widget usage focused on workspace/change review.
 
 `FORGERELAY_WIDGETS=off` disables widget UI.
 

package/docs/configuration.md

@@ -78,7 +78,7 @@ FORGERELAY_ARTIFACTS=1 npx @akira-tl/forgerelay serve
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `FORGERELAY_ARTIFACTS` | `0` | Expose `download_artifact` for trusted native files. |
+| `FORGERELAY_ARTIFACTS` | `0` | Advertise the `artifact.download` Capability for trusted native files. |
 | `FORGERELAY_ARTIFACT_MAX_FILE_BYTES` | `104857600` | Maximum streamed size of one file (100 MiB). |
 
 The same settings may be persisted as `artifactsEnabled` and
@@ -115,20 +115,22 @@ MCP clients discover metadata from:
 
 | Value | Behavior |
 | --- | --- |
-| `minimal` | Default. Exposes `open_workspace`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, `bash`, and `capability`. |
-| `full` | Adds dedicated `grep`, `glob`, and `ls` tools. |
-| `codex` | Experimental Codex-shaped compatibility surface using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `capability`. |
+| `minimal` | Default canonical surface: `open_workspace`, `capability`, `close_workspace`, `read`, `write`, `edit`, `rename`, `delete`, and `bash`. |
+| `full` | Compatibility value. Uses the same canonical 9-tool surface as `minimal`; search and directory inspection go through `bash`. |
+| `codex` | Experimental Codex-shaped compatibility adapter using `open_workspace`, `close_workspace`, `read`, `rename`, `delete`, `apply_patch`, `exec_command`, `write_stdin`, and `capability`. It does not define the ForgeRelay canonical interface. |
 
 `FORGERELAY_MINIMAL_TOOLS` remains a compatibility-style boolean alias when the
 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,
+`minimal` and `full` now resolve to the same regular 9-tool `tools/list`; `full`
+is retained only as a configuration-compatibility value. `codex` selects a
+separate compatibility adapter. ForgeRelay does not hide core 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
+artifact download, MCP App UI, or aggregate `review.changes` when those
 features are actually available; it remains a semantic summary rather than a
 copy of `tools/list`.
 
@@ -142,8 +144,8 @@ 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
+Guide discovery is built in, while optional low-frequency actions are advertised
+through the workspace Capability catalog instead of adding top-level tools. 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
@@ -161,12 +163,35 @@ 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.
 
 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
@@ -186,7 +211,7 @@ regular Agent workflows should use the single `bash` process lifecycle.
 | Value | Behavior |
 | --- | --- |
 | `full` | Default. Attach UI to exposed workspace/file/edit/shell tools. |
-| `changes` | Attach UI to `open_workspace` and aggregate `show_changes`. |
+| `changes` | Attach UI to `open_workspace` and Capability Gateway review results from `review.changes`. |
 | `off` | Disable widget UI. |
 
 ## Lifecycle hooks

package/docs/debugging.md

@@ -59,9 +59,9 @@ 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 unified `close_workspace`, absence of regular `write_stdin` / `close_worktree`, canonical `bash` `action="run"` / `action="process"` plus `processId`, the non-blanket shell mutation policy, no kill-timeout input, workspace resume/stale-workspace schema, and MCP App tool metadata;
+6. `tools/list` for the exact canonical 9-tool regular surface, including unified `close_workspace`, the single `capability` Gateway, canonical `bash` `action="run"` / `action="process"` plus `processId`, absence of retired dedicated aliases/search tools, the non-blanket shell mutation policy, 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`, the unique app domain plus 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`, `bash` long-process `run` → `processId` → `process`, and a deliberate failed `edit`;
+8. a real Git checkout workspace with Capability catalog/describe/read/run, `review.changes`, `write`, `read`, `rename`, `delete`, foreground `bash`, `bash` long-process `run` → `processId` → `process`, and a deliberate failed `edit`; on Linux the catalog/describe path also verifies `artifact.download` native-file transport metadata;
 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_workspace` worktree finalization;
 11. 本地 bare remote 上的 release-tag-push Hook：成功 Hook 必须先运行再允许 `v0.2.0` push，失败 Hook 必须在 remote mutation 前阻断 `v0.2.1`；