feat(agent-workspace): surface memory operator diagnostics

Author: Jacobinwwey

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -306,6 +306,23 @@ Execution anchor:
   - failing references: `24405317254`, `24404975285`,
   - recovered run: `24502592419` (`Migration Gates` all green, including runtime/browser/tauri agent-workspace suites).
 
+## Latest Mainline Increment (2026-04-21 M6.15 Memory Operator Diagnostics Visibility Lane)
+
+- Extended agent-workspace diagnostics so product-memory activity is inspectable instead of being buried under generic `apply_memory_policy` events:
+  - runtime capability events now record `memoryLayer` and `memoryOperation`,
+  - diagnostics snapshot export now emits `memoryPolicySummary`,
+  - server-side diagnostics metadata summary now exposes layer/operation counts for persisted reports.
+- The new operator summary stays bounded and decision-oriented:
+  - total memory policy executions,
+  - readonly vs mutating execution counts,
+  - success vs failure counts,
+  - per-layer counts for `session` / `unit` / `long_term`,
+  - per-operation counts for `read` / `snapshot` / `retrain_plan` / `write` / `evict`.
+- This closes the main observability gap introduced by the new long-term read lane:
+  - long-term visibility is no longer only user-facing,
+  - operator reports can now distinguish `long_term/read` from `session/write`,
+  - managed-memory governance remains inspectable without widening mutation scope.
+
 ## Latest Mainline Increment (2026-04-21 M6.14 Long-Term Memory Read Visibility Lane)
 
 - Extended the agent-workspace memory capability lane with read-only long-term inspection instead of reopening memory-model scope:

docs/diataxis/en/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -27,6 +27,7 @@ First post-checkpoint product-memory slice now landed on `main`:
 
 - agent workspace exposes read-only `long_term` memory snapshot/read actions,
 - managed mutation remains session-scoped by design.
+- operator diagnostics now summarize memory-policy execution by layer and operation, so the new product-memory lane is inspectable instead of opaque.
 
 ## Current Implementation State
 

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -306,6 +306,23 @@
   - 历史失败参考：`24405317254`、`24404975285`，
   - 修复后运行：`24502592419`（`Migration Gates` 全绿，含 runtime/browser/tauri 三个 agent-workspace 套件）。
 
+## 主线最新增量（2026-04-21 M6.15 记忆操作诊断可见性链路）
+
+- agent-workspace diagnostics 已从“只看到通用 `apply_memory_policy`”提升到“可区分具体 memory 行为”：
+  - runtime capability event 现在记录 `memoryLayer` 与 `memoryOperation`，
+  - diagnostics snapshot 导出新增 `memoryPolicySummary`，
+  - server 侧 persisted report 的 metadata summary 现在暴露 layer / operation 计数。
+- 新的 operator summary 保持有界且可决策：
+  - memory policy 总执行数，
+  - readonly / mutating 执行计数，
+  - success / failure 计数，
+  - `session` / `unit` / `long_term` 分层计数，
+  - `read` / `snapshot` / `retrain_plan` / `write` / `evict` 分操作计数。
+- 这一步补上了 long-term read lane 带来的主要可观测性缺口：
+  - long-term 记忆能力不再只是用户侧可见，
+  - operator report 已能区分 `long_term/read` 与 `session/write`，
+  - 记忆治理可观测性增强，但没有扩大 mutation scope。
+
 ## 主线最新增量（2026-04-21 M6.14 长期记忆只读可见性链路）
 
 - agent-workspace memory capability lane 新增长期记忆只读检查能力，但没有重新打开 memory-model 范围：

docs/diataxis/zh/explanation/local-backend-sufficiency-and-escalation-plan.md

@@ -27,6 +27,7 @@
 
 - agent workspace 已暴露只读 `long_term` memory snapshot/read 动作，
 - 托管写入/修正/清理仍然按设计限制在 session 层。
+- operator diagnostics 现在会按 layer / operation 汇总 memory-policy 执行情况，使这条 product-memory 主线可观测、不可黑箱化。
 
 ## 当前实现状态
 

src/agent_workspace.runtime.behavior.test.ts

@@ -23,6 +23,7 @@ type AgentRuntimeModule = {
             lastConversation: Record<string, unknown> | null;
             lastFoundationReadiness: Record<string, unknown> | null;
             lastFailure: Record<string, unknown> | null;
+            memoryPolicySummary: Record<string, unknown>;
             pathState: {
                 visible: boolean;
                 fullscreen: boolean;
@@ -2606,4 +2607,172 @@ describe('agent workspace runtime behavior', () => {
             })
         );
     });
+
+    test('records memory policy diagnostics summary with layer and operation visibility', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        userId: 'agent_user_default',
+                        message: 'Found 1 local knowledge point(s).',
+                        knowledgePoints: [
+                            {
+                                atomId: 'atom-memory-diagnostics-1',
+                                title: 'Memory Diagnostics Candidate',
+                                snippet: 'Track readonly and mutating memory actions.',
+                                score: 0.82,
+                                capabilities: [
+                                    {
+                                        actionId: 'inspect_long_term_memory_read',
+                                        label: 'Long-Term Memory Read',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-memory-diagnostics-1',
+                                            memoryLayer: 'long_term',
+                                            memoryOperation: 'read',
+                                            memoryLimit: 8,
+                                            memoryQuery: 'durable retrieval',
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'apply_memory_policy',
+                                            resultPresentation: 'memory_policy_card',
+                                        },
+                                    },
+                                    {
+                                        actionId: 'write_memory_note',
+                                        label: 'Store Memory Note',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-memory-diagnostics-1',
+                                            memoryLayer: 'session',
+                                            memoryOperation: 'write',
+                                            memoryKey: 'conversation_note:atom-memory-diagnostics-1',
+                                            memoryTags: ['agent_workspace', 'conversation_note'],
+                                            memoryReferences: ['atom-memory-diagnostics-1'],
+                                            memoryPromptMessage: 'Store note for atom-memory-diagnostics-1',
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'apply_memory_policy',
+                                            resultPresentation: 'memory_policy_card',
+                                        },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        layer: 'long_term',
+                        operation: 'read',
+                        entries: [
+                            { key: 'memory:lt:1', value: 'durable retrieval note' },
+                        ],
+                        evictedCount: 0,
+                        stats: {
+                            session: 2,
+                            unit: 1,
+                            longTerm: 6,
+                        },
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        layer: 'session',
+                        operation: 'write',
+                        entries: [
+                            { key: 'conversation_note:atom-memory-diagnostics-1', value: 'Persist this diagnostic note.' },
+                        ],
+                        evictedCount: 0,
+                        mutatedCount: 1,
+                        stats: {
+                            session: 3,
+                            unit: 1,
+                            longTerm: 6,
+                        },
+                    },
+                }),
+            });
+        (global as unknown as Record<string, unknown>).fetch = fetchMock;
+        const promptMock = jest.fn().mockReturnValue('Persist this diagnostic note.');
+        (global as unknown as Record<string, unknown>).prompt = promptMock;
+        (dom!.window as unknown as Record<string, unknown>).prompt = promptMock;
+
+        const runtime = runtimeModule.createAgentWorkspaceRuntime({ defaultUserId: 'agent_user_default' });
+        runtime.init();
+
+        const input = document.getElementById('agent-workspace-input') as HTMLTextAreaElement;
+        const form = document.getElementById('agent-workspace-form') as HTMLFormElement;
+        input.value = 'run memory diagnostics';
+        form.dispatchEvent(new dom!.window.Event('submit', { bubbles: true, cancelable: true }));
+        await flushAsync();
+
+        const actionButtons = Array.from(
+            document.querySelectorAll('.agent-workspace-action-button')
+        ) as HTMLButtonElement[];
+        expect(actionButtons).toHaveLength(2);
+
+        actionButtons[0].click();
+        await flushAsync();
+        actionButtons[1].click();
+        await flushAsync();
+
+        const snapshot = runtime.getDiagnosticsSnapshot();
+        expect(snapshot.memoryPolicySummary).toEqual(
+            expect.objectContaining({
+                executionCount: 2,
+                readonlyExecutions: 1,
+                mutatingExecutions: 1,
+                successCount: 2,
+                failureCount: 0,
+                byLayer: {
+                    session: 1,
+                    unit: 0,
+                    long_term: 1,
+                },
+                byOperation: {
+                    read: 1,
+                    snapshot: 0,
+                    retrain_plan: 0,
+                    write: 1,
+                    evict: 0,
+                },
+                lastEvent: expect.objectContaining({
+                    memoryLayer: 'session',
+                    memoryOperation: 'write',
+                    status: 'success',
+                }),
+            })
+        );
+        expect(
+            snapshot.capabilityEvents.some(
+                (event) => event.memoryLayer === 'long_term' && event.memoryOperation === 'read'
+            )
+        ).toBe(true);
+
+        const exported = JSON.parse(runtime.exportDiagnosticsReport({ format: 'json' }) as string);
+        expect(exported.snapshot.memoryPolicySummary).toEqual(
+            expect.objectContaining({
+                executionCount: 2,
+                readonlyExecutions: 1,
+                mutatingExecutions: 1,
+            })
+        );
+    });
 });