@akira-tl/forgerelay 1.3.2 → 1.3.4

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [1.3.4] - 2026-10-29
+
+### Added
+
+- 新增只读 `workspace.conversation-health` Capability：仅使用 ForgeRelay 可观察的 Host Turn、持久 Workspace checkpoint、Task 与 Git 状态给出 `healthy`、`checkpoint-recommended` 或 `rotation-recommended` 建议，不推测 Host token、上下文窗口利用率或模型内部状态。
+- 默认策略在当前对话作用域与 Workspace 累积 12 个 Host Turn 时建议建立 checkpoint，在 24 个 Host Turn 时建议轮换到新对话；checkpoint 创建后的 8 个 Host Turn 内视为近期恢复边界。交接信息保持有界，只包含未完成 Task 头部、最新 checkpoint 元数据和 Git 摘要；Relay 与 Composite 显式 member 路径保持同样语义。
+
+## [1.3.3] - 2026-10-15
+
+### Fixed
+
+- `open_workspace` 现在明确区分 Host 顶层 Core tool、`capabilityCatalog` 与 `capabilityFingerprint`：`minimal` / `full` 的核心工具仍由 Host 当前 `tools/list` snapshot 决定，不再允许仅因 fingerprint/catalog 未列出 `write`、`edit` 或 `bash` 就把 ForgeRelay 判断为只读；模型可见标签也改为明确的 Capability catalog 与 semantic feature fingerprint 表述。
+
 ## [1.3.2] - 2026-10-08
 
 ### Security

package/capabilities/workspace/workspace-conversation-health/GUIDE.md

@@ -0,0 +1,36 @@
+# Workspace Conversation Health
+
+`workspace.conversation-health` is a low-frequency, read-only advisory capability for deciding when a long-lived Host conversation should checkpoint or rotate while durable Workspace state remains canonical.
+
+## Policy
+
+The current deterministic policy uses only ForgeRelay-observable state:
+
+- recommend a checkpoint at 12 Host Turns when no recent persistent checkpoint exists;
+- recommend conversation rotation at 24 Host Turns;
+- treat a checkpoint as recent for 8 Host Turns after its creation.
+
+These thresholds are policy constants, not estimates of model token usage, context-window utilization, memory pressure, or reasoning state.
+
+The result exposes the policy thresholds, Host Turn counts, bounded active Task summaries, the latest persistent checkpoint when available, and bounded Git state for Git-backed Workspaces.
+
+## Recommended actions
+
+- `continue` — the current conversation is still within the advisory threshold.
+- `checkpoint` — create a named `workspace.checkpoint` before continuing.
+- `checkpoint-and-rotate` — create a fresh persistent checkpoint, then move to a fresh Host conversation.
+- `rotate` — a recent checkpoint already exists; move to a fresh Host conversation and reopen the same Workspace.
+
+The capability never creates a checkpoint, closes a Host conversation, stores the Host transcript, or forces rotation.
+
+## Durable handoff
+
+A fresh Host conversation should call `open_workspace` for the same canonical Workspace and resume from durable state. Workspace Tasks, persistent checkpoints, Git state, and Project status artifacts remain the source of truth; the previous Host transcript is not required for recovery.
+
+Task handoff metadata is summary-only and excludes Task content. Checkpoint metadata is bounded and excludes patches or file contents.
+
+## Relay and Composite Workspaces
+
+For a relayed Workspace, the capability executes on the remote Execution ForgeRelay so Host Turn, Task, checkpoint, and Git observations come from the Workspace owner.
+
+A Composite Workspace has no single filesystem conversation-health state. Pass an explicit `member`; the capability evaluates that member's Execution Workspace.

package/dist/activity/history/host-turn-store.js

@@ -34,6 +34,16 @@ export class HostTurnStore {
        limit 1`).get(conversationScopeId, workspaceId);
         return row ? rowToTurn(row) : undefined;
     }
+    countForConversationWorkspace(conversationScopeId, workspaceId, after) {
+        const row = after
+            ? this.database.sqlite.prepare(`select count(*) as count
+           from activity_host_turns
+           where conversation_scope_id = ? and workspace_id = ? and created_at > ?`).get(conversationScopeId, workspaceId, after)
+            : this.database.sqlite.prepare(`select count(*) as count
+           from activity_host_turns
+           where conversation_scope_id = ? and workspace_id = ?`).get(conversationScopeId, workspaceId);
+        return Number(row?.count ?? 0);
+    }
     deleteWorkspace(workspaceId) {
         this.database.sqlite.prepare("delete from activity_host_turns where workspace_id = ?").run(workspaceId);
     }

package/dist/activity/history/query-service.js

@@ -24,6 +24,12 @@ export class ActivityQueryService {
     currentTurnId(conversationScopeId, workspaceId) {
         return this.turns.current(conversationScopeId, workspaceId)?.turnId;
     }
+    countTurns(conversationScopeId, workspaceId, after) {
+        return this.turns.countForConversationWorkspace(conversationScopeId, workspaceId, after);
+    }
+    turnWorkspaceId(turnId) {
+        return this.turns.get(turnId)?.workspaceId;
+    }
     state(turnId, knownRevision) {
         this.requireTurn(turnId);
         const aggregate = this.audit.turnState(turnId);

package/dist/mcp/panel/app.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { access } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
@@ -14,11 +15,16 @@ export function createActivityPanelApp(config, fallbackRevision) {
     const identity = currentIdentity(config, fallbackRevision);
     const domain = new URL(config.publicBaseUrl).origin;
     const csp = activityPanelCsp(config);
+    const openAiWidgetCsp = openAiCompatibilityCsp(csp);
     return {
         uri: identity.uri,
         resourceMetadata: {
             description: "ForgeRelay unified Workspace and Activity UI for one Host Turn.",
-            _meta: { ui: { domain, csp } },
+            _meta: {
+                ui: { domain, csp },
+                "openai/widgetDomain": domain,
+                "openai/widgetCSP": openAiWidgetCsp,
+            },
         },
         toolMeta: config.widgets === "off"
             ? { _meta: {} }
@@ -28,6 +34,8 @@ export function createActivityPanelApp(config, fallbackRevision) {
                         resourceUri: identity.uri,
                         visibility: ["model", "app"],
                     },
+                    "openai/outputTemplate": identity.uri,
+                    "openai/widgetAccessible": true,
                 },
             },
         readResource: (requestedUri, transportSessionId) => readActivityPanelAppResource(config, fallbackRevision, requestedUri, transportSessionId),
@@ -70,11 +78,18 @@ function activityPanelCsp(config) {
         connectDomains: publicOrigins,
     };
 }
+function openAiCompatibilityCsp(csp) {
+    return {
+        resource_domains: csp.resourceDomains,
+        connect_domains: csp.connectDomains,
+    };
+}
 async function readActivityPanelAppResource(config, fallbackRevision, requestedUri, transportSessionId) {
     const identity = currentIdentity(config, fallbackRevision);
     const entry = readActivityPanelAppManifestEntry(uiManifestUrl());
     const domain = new URL(config.publicBaseUrl).origin;
     const csp = activityPanelCsp(config);
+    const openAiWidgetCsp = openAiCompatibilityCsp(csp);
     try {
         await assertMcpAppAssets(entry);
         const result = {
@@ -84,6 +99,10 @@ async function readActivityPanelAppResource(config, fallbackRevision, requestedU
                     text: activityPanelAppHtml(config, entry),
                     _meta: {
                         ui: { domain, csp },
+                        // ChatGPT compatibility aliases remain useful for older/mobile hosts
+                        // that have not fully converged on the MCP Apps standard metadata.
+                        "openai/widgetDomain": domain,
+                        "openai/widgetCSP": openAiWidgetCsp,
                         // MCP Apps defines these values under `_meta.ui`. Inspector 2.3.0
                         // still reads them directly from the content-item metadata, so mirror
                         // them until that installed-host compatibility gap is retired.
@@ -112,25 +131,34 @@ async function readActivityPanelAppResource(config, fallbackRevision, requestedU
 function activityPanelAppHtml(config, entry) {
     const baseUrl = `${config.publicBaseUrl.replace(/\/+$/, "")}/mcp-app-assets`;
     const assetUrl = (assetPath) => `${baseUrl}/${assetPath.replace(/^\/+/, "")}`;
-    const stylesheets = (entry.css ?? [])
-        .map((stylesheet) => `    <link rel="stylesheet" crossorigin href="${assetUrl(stylesheet)}" />`)
-        .join("\n");
+    const entryDirectory = entry.file.includes("/")
+        ? entry.file.slice(0, entry.file.lastIndexOf("/") + 1)
+        : "";
+    const styles = (entry.css ?? [])
+        .map((stylesheet) => readUiAssetText(stylesheet).replace(/<\/style/gi, "<\\/style"))
+        .join("\\n");
+    const script = readUiAssetText(entry.file)
+        .replace(/import\((["'`])\.\/([^"'`]+)\1\)/g, (_match, quote, relativePath) => `import(${quote}${assetUrl(`${entryDirectory}${relativePath}`)}${quote})`)
+        .replace(/<\/script/gi, "<\\/script");
     return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ForgeRelay Activity Panel</title>
-    <script type="module" crossorigin src="${assetUrl(entry.file)}"></script>
-${stylesheets}
+    <style>${styles}</style>
   </head>
   <body>
     <main id="app" class="shell">
       <section class="empty">Waiting for Activity Panel state.</section>
     </main>
+    <script type="module">${script}</script>
   </body>
 </html>`;
 }
+function readUiAssetText(assetPath) {
+    return readFileSync(new URL(`../../../dist/ui/${assetPath}`, import.meta.url), "utf8");
+}
 async function assertMcpAppAssets(entry) {
     const candidates = [entry.file, ...(entry.css ?? [])].map((assetPath) => new URL(`../../../dist/ui/${assetPath}`, import.meta.url));
     for (const candidate of candidates)

package/dist/mcp/panel/mcp-app-template.js

@@ -4,7 +4,7 @@ export const ACTIVITY_PANEL_APP_MANIFEST_ENTRY = "activity-panel-app.html";
 // Host caches are keyed by the ui:// resource URI, so the revision must cover
 // both bundle assets and the HTML/resource contract that serves them. Bump this
 // whenever either side changes so a Host never reuses stale UI bytes.
-export const MCP_APP_RESOURCE_TEMPLATE_REVISION = "5";
+export const MCP_APP_RESOURCE_TEMPLATE_REVISION = "7";
 export function activityPanelAppUriForRevision(revision) {
     return `ui://forgerelay/activity-panel-app-${encodeURIComponent(revision)}.html`;
 }

package/dist/mcp/server/core/capabilities/workspace-checkpoint-runtime.js

@@ -0,0 +1,34 @@
+export function createWorkspaceCheckpointCapabilityRuntime(store) {
+    return {
+        available: true,
+        run: async (input, context) => {
+            const root = context.workspaceRoot;
+            if (!root)
+                throw new Error("Workspace checkpoint requires a filesystem-backed Workspace.");
+            switch (input.operation) {
+                case "create":
+                    return {
+                        value: {
+                            workspaceId: context.workspaceId,
+                            checkpoint: await store.create(context.workspaceId, root, input.name),
+                            ignoredFilesIncluded: false,
+                        },
+                    };
+                case "list":
+                    return { value: await store.list(context.workspaceId, root, input) };
+                case "inspect":
+                    return { value: await store.inspect(context.workspaceId, root, input.checkpointId) };
+                case "restore.preflight":
+                    return {
+                        value: await store.preflightRestore(context.workspaceId, root, input.checkpointId),
+                    };
+                case "restore":
+                    return {
+                        value: await store.restore(context.workspaceId, root, input.checkpointId, input.expectedCurrentSnapshot),
+                    };
+                case "delete":
+                    return { value: await store.delete(context.workspaceId, root, input.checkpointId) };
+            }
+        },
+    };
+}

package/dist/mcp/server/core/capabilities/workspace-checkpoint.js

@@ -27,3 +27,20 @@ export const workspaceCheckpointInputSchema = z.discriminatedUnion("operation",
         checkpointId: z.string().regex(/^cp_[a-f0-9]{10}$/),
     }).strict(),
 ]);
+export function workspaceCheckpointCapabilityDefinitions(dependency, availability) {
+    if (!dependency)
+        return [];
+    return [{
+            name: "workspace.checkpoint",
+            description: [
+                "Create, list, inspect, safely restore, or delete immutable Git-backed checkpoints",
+                "owned by the current persistent Workspace.",
+            ].join(" "),
+            guideName: "workspace-checkpoints",
+            readGuideBeforeFirstUse: true,
+            batchPolicy: "unsupported",
+            inputSchema: workspaceCheckpointInputSchema,
+            availability: (context) => availability(context, dependency.available, dependency.unavailableReason),
+            run: async (input, context, options) => dependency.run(input, context, options),
+        }];
+}

package/dist/mcp/server/core/capabilities/workspace-conversation-health.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const workspaceConversationHealthInputSchema = z.object({}).strict();
+export function workspaceConversationHealthCapabilityDefinitions(dependency, availability) {
+    if (!dependency)
+        return [];
+    return [{
+            name: "workspace.conversation-health",
+            description: [
+                "Inspect deterministic conversation-aging signals and bounded durable handoff metadata",
+                "for the current Workspace.",
+            ].join(" "),
+            guideName: "workspace-conversation-health",
+            readGuideBeforeFirstUse: true,
+            batchPolicy: "unsupported",
+            inputSchema: workspaceConversationHealthInputSchema,
+            availability: (context) => availability(context, dependency.available, dependency.unavailableReason),
+            run: async (_input, context, options) => dependency.run(context, options),
+        }];
+}

package/dist/mcp/server/core/capabilities.js

@@ -58,6 +58,12 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Immutable persistent Git-backed checkpoints owned by the current Workspace.",
         whenToRead: "Read before creating, listing, inspecting, or deleting Workspace checkpoints.",
     },
+    {
+        name: "workspace-conversation-health",
+        directory: "workspace/workspace-conversation-health",
+        description: "Deterministic Host conversation aging guidance and bounded durable handoff metadata.",
+        whenToRead: "Read before using workspace.conversation-health for checkpoint or conversation-rotation guidance.",
+    },
     {
         name: "batch-execution",
         description: "One-call execution of multiple independent ForgeRelay core operations.",
@@ -109,6 +115,7 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "workspace.tasks",
         "workspace.recovery",
         "workspace.checkpoint",
+        "workspace.conversation-health",
     ];
     if (config.toolMode !== "codex") {
         capabilities.push("batch.execute");

package/dist/mcp/server/core/capability-registry.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "../../../lsp/code-intelligence-types.js";
 import { batchExecuteInputSchema, } from "../../operations/batch/types.js";
-import { workspaceCheckpointInputSchema, } from "./capabilities/workspace-checkpoint.js";
+import { workspaceCheckpointCapabilityDefinitions, } from "./capabilities/workspace-checkpoint.js";
+import { workspaceConversationHealthCapabilityDefinitions, } from "./capabilities/workspace-conversation-health.js";
 import { externalMcpCapabilityDefinitions, } from "./capabilities/external-mcp.js";
 export class CapabilityError extends Error {
     code;
@@ -306,18 +307,8 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (input, context, options) => dependencies.workspaceRecovery.run(input, context, options),
                 }]
             : []),
-        ...(dependencies.workspaceCheckpoint
-            ? [{
-                    name: "workspace.checkpoint",
-                    description: "Create, list, inspect, safely restore, or delete immutable Git-backed checkpoints owned by the current persistent Workspace.",
-                    guideName: "workspace-checkpoints",
-                    readGuideBeforeFirstUse: true,
-                    batchPolicy: "unsupported",
-                    inputSchema: workspaceCheckpointInputSchema,
-                    availability: (context) => filesystemWorkspaceAvailability(context, dependencies.workspaceCheckpoint?.available ?? false, dependencies.workspaceCheckpoint?.unavailableReason),
-                    run: async (input, context, options) => dependencies.workspaceCheckpoint.run(input, context, options),
-                }]
-            : []),
+        ...workspaceCheckpointCapabilityDefinitions(dependencies.workspaceCheckpoint, filesystemWorkspaceAvailability),
+        ...workspaceConversationHealthCapabilityDefinitions(dependencies.workspaceConversationHealth, filesystemWorkspaceAvailability),
         ...(dependencies.workspaceTasks
             ? [{
                     name: "workspace.tasks",

package/dist/mcp/server/operations/runtime/operation-runtime.js

@@ -510,6 +510,8 @@ export function createOperationRuntime(options) {
                             sessionId: context.sessionId,
                             batch: context.batch,
                             activityId: activityContext.activityId,
+                            turnId: activityContext.turnId,
+                            conversationScopeId: context.conversationScopeId,
                         });
                         changedPaths = execution.changedPaths ?? [];
                         const transientContent = execution.content;

package/dist/mcp/server/workspace/runtime/conversation-health-relay.js

@@ -0,0 +1,30 @@
+import { rebaseConversationHealthAge, } from "../../../../workspaces/state/conversation-health.js";
+import { textBlock } from "../../core/tool-support.js";
+export function rebaseRemoteCompositeConversationHealth(response, compositeWorkspaceId, conversationScopeId, activityQueries) {
+    if (response.isError === true)
+        return response;
+    const structured = response.structuredContent;
+    if (!structured || typeof structured !== "object")
+        return response;
+    const result = structured.result;
+    if (!result || typeof result !== "object")
+        return response;
+    const health = result;
+    const latestCheckpoint = health.latestCheckpoint;
+    const hostTurnCount = activityQueries.countTurns(conversationScopeId, compositeWorkspaceId);
+    const turnsSinceLatestCheckpoint = latestCheckpoint
+        ? activityQueries.countTurns(conversationScopeId, compositeWorkspaceId, latestCheckpoint.createdAt)
+        : hostTurnCount;
+    const rebased = rebaseConversationHealthAge(health, {
+        hostTurnCount,
+        turnsSinceLatestCheckpoint,
+    });
+    return {
+        ...response,
+        content: [textBlock(`Capability workspace.conversation-health completed.\n${JSON.stringify(rebased, null, 2)}`)],
+        structuredContent: {
+            ...structured,
+            result: rebased,
+        },
+    };
+}

package/dist/mcp/server/workspace/runtime/workspace-open-presentation.js

@@ -12,7 +12,7 @@ import { logToolCall, workspaceLogContext } from "../../core/tool-support.js";
 import { buildExecutionShellContext } from "../../../server-instructions.js";
 import { workspaceColorFor, workspaceIdentityName } from "../../../../workspace-colors.js";
 export const workspaceTaskUsageInstruction = "Use workspace.tasks proactively for work that spans multiple steps or sessions: create or update Tasks to preserve useful next steps and current state, and read its summary when resuming relevant unfinished work. Do not query it mechanically on every open_workspace call.";
-export const capabilityDiscoveryInstruction = "For capability describe/run, use only names present in capabilityCatalog. capabilityFingerprint.capabilities is a semantic feature fingerprint, not a callable registry; capabilityGuides are documentation descriptors, not callable capabilities.";
+export const capabilityDiscoveryInstruction = "Core MCP tools are separate from capabilityCatalog and capabilityFingerprint; the Host's current tools/list snapshot determines which top-level tools can be called. In toolMode=minimal or full, ForgeRelay's regular core surface is open_workspace, capability, close_workspace, read, write, edit, rename, delete, and bash. Do not infer that write, edit, or bash are unavailable merely because they are absent from capabilityCatalog or capabilityFingerprint. If an expected core tool is missing from the Host tool snapshot, treat the Host MCP metadata as stale or incomplete rather than describing ForgeRelay as read-only. For capability describe/run, use only names present in capabilityCatalog. capabilityFingerprint.capabilities is a semantic feature fingerprint, not a callable registry; capabilityGuides are documentation descriptors, not callable capabilities.";
 export async function presentLocalWorkspaceOpen(options, input, contextData) {
     const { config, forgerelayVersion: FORGERELAY_VERSION, workspaces, workspaceTasks, reviewCheckpoints, capabilityRegistry, subagentProviders, hooks, rememberWorkspacePanelState, } = options;
     const { path, workspaceId, mode, baseRef, targetBranch, newWorktree, newWorkspace, context } = input;
@@ -155,7 +155,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
                     ? `Available skills: ${visibleSkills.map((skill) => skill.name).join(", ")}`
                     : undefined,
                 capabilityCatalog.length > 0
-                    ? `Optional capabilities: ${capabilityCatalog.map((entry) => entry.name).join(", ")}`
+                    ? `Capability catalog entries: ${capabilityCatalog.map((entry) => entry.name).join(", ")}`
                     : undefined,
                 visibleCapabilityGuides.length > 0
                     ? `Capability guides: ${visibleCapabilityGuides.map((guide) => guide.name).join(", ")}`
@@ -175,7 +175,7 @@ export async function presentLocalWorkspaceOpen(options, input, contextData) {
                 staleWorkspaces.length > 0
                     ? `This Workspace has been idle for more than 2 days: ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. It remains available to resume or explicitly close; do not clean it up automatically.`
                     : undefined,
-                `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
+                `ForgeRelay semantic feature fingerprint (${capabilityFingerprint.version}): ${capabilityFingerprint.capabilities.join(", ")}`,
                 instruction,
                 resourceUpdate?.text,
             ].filter(Boolean).join("\n"),

package/dist/mcp/server/workspace/runtime/workspace-open.js

@@ -503,7 +503,7 @@ async function handleOpenWorkspace(options, input, requestContext) {
                 ? `Available skills: ${relayedSkills.map((skill) => String(skill.name ?? "")).filter(Boolean).join(", ")}`
                 : undefined,
             relayedCapabilities.length > 0
-                ? `Optional capabilities: ${relayedCapabilities.map((entry) => String(entry.name ?? "")).filter(Boolean).join(", ")}`
+                ? `Capability catalog entries: ${relayedCapabilities.map((entry) => String(entry.name ?? "")).filter(Boolean).join(", ")}`
                 : undefined,
             opened.instruction,
         ].filter(Boolean).join("\n");

package/dist/mcp/server/workspace/runtime/workspace-tools.js

@@ -4,6 +4,7 @@ import { mcpHandlerRequestContext } from "../../../request-context.js";
 import { CapabilityError } from "../../core/capability-registry.js";
 import { attachHookReports, runToolWithHooks } from "../../../hooks/hooks.js";
 import { toolNames } from "../../../server-instructions.js";
+import { rebaseRemoteCompositeConversationHealth } from "./conversation-health-relay.js";
 import { formatAgentsPath } from "../../../../workspaces.js";
 import { activityRelationFor, activityRequestFor, runActivityToolWithHooks, } from "../../core/activity-support.js";
 import { capabilityContextFor, compositeCapabilityContext, workspaceHookInvocation, } from "../../core/capability-support.js";
@@ -176,12 +177,17 @@ export function registerWorkspaceAuxiliaryTools(options) {
         const executionWorkspaceId = target.executionWorkspaceId;
         const executionContext = await prepareExecutionContext(target, requestContext);
         if (remoteWorkspaces.has(executionWorkspaceId)) {
-            const response = await remoteWorkspaces.capability(executionWorkspaceId, {
+            let response = await remoteWorkspaces.capability(executionWorkspaceId, {
                 name,
                 action,
                 ...(capabilityArguments !== undefined ? { arguments: capabilityArguments } : {}),
                 ...(file !== undefined ? { file } : {}),
             }, hostScopeIdFor(requestContext));
+            if (action === "run"
+                && name === "workspace.conversation-health"
+                && target.compositeWorkspaceId) {
+                response = rebaseRemoteCompositeConversationHealth(response, target.compositeWorkspaceId, hostScopeIdFor(requestContext), activityQueries);
+            }
             return action === "run" && name !== "workspace.tasks"
                 ? presentSemanticWorkResult(response, target, hostScopeIdFor(requestContext))
                 : presentExecutionResult(response, target);

package/dist/server.js

@@ -30,6 +30,8 @@ import { formatPathForPrompt } from "./workspaces/resources/skills.js";
 import { WorkspaceTaskReminderTracker } from "./workspaces/tasks/workspace-task-reminders.js";
 import { WorkspaceTaskStore } from "./workspaces/tasks/workspace-tasks.js";
 import { WorkspaceCheckpointStore } from "./workspaces/state/workspace-checkpoints.js";
+import { inspectConversationHealth } from "./workspaces/state/conversation-health.js";
+import { createWorkspaceCheckpointCapabilityRuntime, } from "./mcp/server/core/capabilities/workspace-checkpoint-runtime.js";
 import { compactCompositeWorkspacePresentation, compactRelayedWorkspacePresentation, compactWorkspacePresentation, } from "./workspaces/presentation/workspace-presentation.js";
 import { formatAgentsPath } from "./workspaces.js";
 import { summarizeSubagentProfile } from "./subagents/profiles.js";
@@ -148,32 +150,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 value: await workspaces.runManagedWorktreeRecovery(context.workspaceId, input.operation),
             }),
         },
-        workspaceCheckpoint: {
+        workspaceCheckpoint: createWorkspaceCheckpointCapabilityRuntime(workspaceCheckpoints),
+        workspaceConversationHealth: {
             available: true,
-            run: async (input, context) => {
-                const root = requireCapabilityWorkspaceRoot(context);
-                switch (input.operation) {
-                    case "create":
-                        return {
-                            value: {
-                                workspaceId: context.workspaceId,
-                                checkpoint: await workspaceCheckpoints.create(context.workspaceId, root, input.name),
-                                ignoredFilesIncluded: false,
-                            },
-                        };
-                    case "list":
-                        return { value: await workspaceCheckpoints.list(context.workspaceId, root, input) };
-                    case "inspect":
-                        return { value: await workspaceCheckpoints.inspect(context.workspaceId, root, input.checkpointId) };
-                    case "restore.preflight":
-                        return { value: await workspaceCheckpoints.preflightRestore(context.workspaceId, root, input.checkpointId) };
-                    case "restore":
-                        return {
-                            value: await workspaceCheckpoints.restore(context.workspaceId, root, input.checkpointId, input.expectedCurrentSnapshot),
-                        };
-                    case "delete":
-                        return { value: await workspaceCheckpoints.delete(context.workspaceId, root, input.checkpointId) };
+            run: async (context, runOptions) => {
+                const conversationScopeId = runOptions.conversationScopeId;
+                if (!conversationScopeId) {
+                    throw new CapabilityError("capability_unavailable", "workspace.conversation-health requires a resolved Host conversation scope.");
                 }
+                return {
+                    value: await inspectConversationHealth({ activityQueries, workspaceTasks, workspaceCheckpoints }, {
+                        workspaceId: context.workspaceId,
+                        workspaceRoot: requireCapabilityWorkspaceRoot(context),
+                        conversationScopeId,
+                        conversationWorkspaceId: runOptions.turnId
+                            ? activityQueries.turnWorkspaceId(runOptions.turnId) ?? context.workspaceId
+                            : context.workspaceId,
+                    }),
+                };
             },
         },
         workspaceTasks: {

package/dist/workspaces/state/conversation-health.js

@@ -0,0 +1,124 @@
+import { getGitEligibility, git } from "../git/git.js";
+export const CONVERSATION_HEALTH_POLICY = {
+    checkpointTurnThreshold: 12,
+    rotationTurnThreshold: 24,
+    checkpointFreshTurnWindow: 8,
+};
+export async function inspectConversationHealth(dependencies, input) {
+    const conversationWorkspaceId = input.conversationWorkspaceId ?? input.workspaceId;
+    const hostTurnCount = dependencies.activityQueries.countTurns(input.conversationScopeId, conversationWorkspaceId);
+    const gitState = await inspectGitState(input.workspaceRoot);
+    const latestCheckpoint = gitState
+        ? (await dependencies.workspaceCheckpoints.latest(input.workspaceId, input.workspaceRoot)).checkpoint
+        : undefined;
+    const turnsSinceLatestCheckpoint = latestCheckpoint
+        ? dependencies.activityQueries.countTurns(input.conversationScopeId, conversationWorkspaceId, latestCheckpoint.createdAt)
+        : hostTurnCount;
+    const policyDecision = evaluateConversationHealth({
+        hostTurnCount,
+        turnsSinceLatestCheckpoint,
+        checkpointAvailable: Boolean(gitState),
+        checkpointPresent: Boolean(latestCheckpoint),
+    });
+    const taskHeaders = dependencies.workspaceTasks.inspectHeaders(input.workspaceId);
+    return {
+        workspaceId: input.workspaceId,
+        ...policyDecision,
+        policy: CONVERSATION_HEALTH_POLICY,
+        metrics: {
+            hostTurnCount,
+            turnsSinceLatestCheckpoint,
+        },
+        ...(latestCheckpoint ? { latestCheckpoint } : {}),
+        activeTasks: (taskHeaders?.lists ?? [])
+            .filter((list) => list.state === "active")
+            .flatMap((list) => list.tasks.flatMap((task) => task.status === "completed"
+            ? []
+            : [{
+                    listId: list.id,
+                    listName: list.name,
+                    id: task.id,
+                    status: task.status,
+                    subject: task.subject,
+                }]))
+            .slice(0, 20),
+        ...(gitState ? { git: gitState } : {}),
+    };
+}
+export function evaluateConversationHealth(input) {
+    const checkpointRecent = input.checkpointPresent
+        && input.turnsSinceLatestCheckpoint
+            <= CONVERSATION_HEALTH_POLICY.checkpointFreshTurnWindow;
+    if (input.hostTurnCount >= CONVERSATION_HEALTH_POLICY.rotationTurnThreshold) {
+        if (!input.checkpointAvailable) {
+            return {
+                status: "rotation-recommended",
+                reasons: [
+                    "host_turn_count_rotation_threshold",
+                    "checkpoint_unavailable",
+                ],
+                recommendedAction: "rotate",
+            };
+        }
+        return {
+            status: "rotation-recommended",
+            reasons: [
+                "host_turn_count_rotation_threshold",
+                checkpointRecent ? "checkpoint_recent" : "checkpoint_stale",
+            ],
+            recommendedAction: checkpointRecent ? "rotate" : "checkpoint-and-rotate",
+        };
+    }
+    if (input.checkpointAvailable
+        && input.hostTurnCount >= CONVERSATION_HEALTH_POLICY.checkpointTurnThreshold
+        && !checkpointRecent) {
+        return {
+            status: "checkpoint-recommended",
+            reasons: [
+                "host_turn_count_checkpoint_threshold",
+                input.checkpointPresent ? "checkpoint_stale" : "checkpoint_missing",
+            ],
+            recommendedAction: "checkpoint",
+        };
+    }
+    return {
+        status: "healthy",
+        reasons: checkpointRecent ? ["checkpoint_recent"] : [],
+        recommendedAction: "continue",
+    };
+}
+export function rebaseConversationHealthAge(result, input) {
+    return {
+        ...result,
+        ...evaluateConversationHealth({
+            ...input,
+            checkpointAvailable: result.git !== undefined,
+            checkpointPresent: result.latestCheckpoint !== undefined,
+        }),
+        policy: CONVERSATION_HEALTH_POLICY,
+        metrics: {
+            hostTurnCount: input.hostTurnCount,
+            turnsSinceLatestCheckpoint: input.turnsSinceLatestCheckpoint,
+        },
+    };
+}
+async function inspectGitState(workspaceRoot) {
+    const eligibility = await getGitEligibility(workspaceRoot);
+    if (!eligibility.ok || !eligibility.gitRoot)
+        return undefined;
+    const [headResult, branchResult, statusResult] = await Promise.all([
+        git(eligibility.gitRoot, ["rev-parse", "HEAD"]),
+        git(eligibility.gitRoot, ["branch", "--show-current"]),
+        git(eligibility.gitRoot, ["status", "--porcelain=v1", "--untracked-files=normal"], { maxBuffer: 2 * 1024 * 1024 }),
+    ]);
+    const statusLines = statusResult.stdout
+        .split("\n")
+        .filter((line) => line.length > 0);
+    const branch = branchResult.stdout.trim();
+    return {
+        head: headResult.stdout.trim(),
+        ...(branch ? { branch } : {}),
+        dirty: statusLines.length > 0,
+        changedFiles: statusLines.length,
+    };
+}

package/dist/workspaces/state/workspace-checkpoints.js

@@ -107,6 +107,21 @@ export class WorkspaceCheckpointStore {
             ignoredFilesIncluded: false,
         };
     }
+    async latest(workspaceId, workspaceRoot) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const repository = await resolveRepository(workspaceRoot);
+        const state = this.tryReadState(id);
+        if (state)
+            await assertSameRepository(state.gitCommonDir, repository.gitCommonDir, id);
+        const checkpoint = state?.checkpoints.at(-1);
+        if (checkpoint)
+            await assertCheckpointRef(state.gitCommonDir, id, checkpoint);
+        return {
+            workspaceId: id,
+            ...(checkpoint ? { checkpoint: cloneCheckpoint(checkpoint) } : {}),
+            ignoredFilesIncluded: false,
+        };
+    }
     async inspect(workspaceId, workspaceRoot, checkpointId) {
         const id = normalizeWorkspaceId(workspaceId);
         const cpId = normalizeCheckpointId(checkpointId);

package/dist/workspaces/tasks/workspace-tasks.js

@@ -91,6 +91,11 @@ export class WorkspaceTaskStore {
     readHeaders(workspaceId, listId) {
         return taskHeaders(this.ensureWorkspace(workspaceId), listId);
     }
+    inspectHeaders(workspaceId) {
+        const id = normalizeWorkspaceId(workspaceId);
+        const loaded = this.tryReadState(id);
+        return loaded ? taskHeaders(snapshot(loaded.state, loaded.fingerprint)) : undefined;
+    }
     readTaskDetail(workspaceId, listId, taskId) {
         return taskDetail(this.ensureWorkspace(workspaceId), listId, taskId);
     }

package/docs/configuration.md

@@ -453,7 +453,12 @@ 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 `review.changes` when those
 features are actually available; it remains a semantic summary rather than a
-copy of `tools/list`.
+copy of `tools/list`. Neither `capabilityFingerprint` nor `capabilityCatalog`
+is evidence that an omitted Core tool is unavailable. The Host's current
+`tools/list` snapshot is authoritative for top-level callability; in
+`minimal` and `full`, the expected regular Core surface remains
+`open_workspace`, `capability`, `close_workspace`, `read`, `write`,
+`edit`, `rename`, `delete`, and `bash`.
 
 Bootstrap responses also return `capabilityGuides`, which are compact descriptors
 for built-in ForgeRelay documentation that the Agent can explicitly load with
@@ -466,11 +471,14 @@ context.
 
 There is no separate progressive-disclosure configuration switch. Capability
 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
-force a Host to invalidate its cached schema.
+through the workspace Capability catalog instead of adding top-level tools. If an
+expected Core tool is missing from the Host's current tool snapshot, or the
+fingerprint reports a semantic feature that the Host metadata does not reflect,
+treat that as stale or incomplete Host MCP metadata: reconnect/refresh the
+integration or use a Host context that reloads `tools/list`. Do not describe
+ForgeRelay as read-only merely because `write`, `edit`, or `bash` is absent
+from the fingerprint or Capability catalog. The ForgeRelay process cannot force
+a Host to invalidate its cached schema.
 
 ### LSP code intelligence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",