@xrkseek/harness 0.4.0-rc.4 → 0.4.1

package/node_modules/@xrkseek/preset-harness/dist/preset.js

@@ -2,28 +2,29 @@ import { createAgent } from "@xrkseek/core-agent";
 import { createMemorySessionStore, readSessionEvents, } from "@xrkseek/core-session";
 import { prepareFaceSessionReferences } from "@xrkseek/xrk-session-reference/prepare-face";
 import { createSystemPromptAssembler, } from "@xrkseek/core-system-prompt";
-import { createReadTracker, createStdTools, createToolPipeline, createToolRegistry, createWriteIntentGuard, extractPathArg, SUBAGENT_ROUTING_PROMPT_TEXT, } from "@xrkseek/core-tools";
+import { createReadTracker, createStdTools, createToolPipeline, createToolRegistry, createWriteIntentGuard, extractPathArg, SUBAGENT_ROUTING_PROMPT_TEXT, SESSION_QUERY_ROUTING_PROMPT_TEXT, } from "@xrkseek/core-tools";
 import { createFsLocalProvider, createFsTools, createReadImageTool, formatFsRoutingPrompt, formatShellRoutingPrompt, } from "@xrkseek/exec-fs";
 import { formatWebFetchGuidance, formatWebSearchGuidance, formatBrowserGuidance, createDefaultWebAccess, createWebTools, createBrowserTools, createBrowserSession, } from "@xrkseek/exec-web";
 import { COMPUTER_USE_PROMPT_TEXT, createComputerUseTools, createDefaultComputerUseAccess, } from "@xrkseek/exec-computer-use";
 import { VOICE_PROMPT_TEXT, createDefaultVoiceAccess, createVoiceTools, } from "@xrkseek/exec-voice";
 import { IMAGE_GEN_PROMPT_TEXT, createDefaultImageGenAccess, createImageGenTools, } from "@xrkseek/exec-image-gen";
 import { VIDEO_GEN_PROMPT_TEXT, createDefaultVideoGenAccess, createVideoGenTools, } from "@xrkseek/exec-video-gen";
-import { CURATED_MEMORY_PROMPT_TEXT, createCuratedMemoryStore, createCuratedMemoryTools, writeReusableNotesAfterTurn, } from "@xrkseek/exec-memory";
+import { CURATED_MEMORY_PROMPT_TEXT, createCuratedMemoryStore, createCuratedMemoryTools, writeReusableNotesAfterTurn, consolidateCuratedMemoryPhase1, } from "@xrkseek/exec-memory";
 import { LSP_PROMPT_TEXT, createDefaultLspAccess, createLspTools, } from "@xrkseek/exec-lsp";
 import { PTY_PROMPT_TEXT, createDefaultPtyAccess, createPtyTools, } from "@xrkseek/exec-pty";
-import { createSandboxStack, createSandboxWrapGuard, } from "@xrkseek/exec-sandbox";
+import { createSandboxStack, createSandboxWrapGuard, createHardlineArgvPre, } from "@xrkseek/exec-sandbox";
 import { CRON_PROMPT_TEXT, createCronTools, } from "@xrkseek/server-cron";
 import { createBashTools, createLocalShell, createSessionScopedShell, toJobView, JOBS_PROMPT_TEXT, } from "@xrkseek/exec-shell";
 import { createLocalSubprocess } from "@xrkseek/exec-subprocess";
-import { createRunCodeTool, createWorkerCodeRuntime, } from "@xrkseek/code-runtime";
+import { createRegistryCodeToolBridge, createRunCodeTool, createWorkerCodeRuntime, } from "@xrkseek/code-runtime";
+import { appendContextFragments, createAdditionalContextFragment, createContextFragmentPipeline, fragmentsToPrepareContexts, } from "@xrkseek/context-fragments";
 import { createReplayAdapter } from "@xrkseek/llm-replay";
-import { createPolicyToolPre, createSessionReadOnlyToolPre, } from "@xrkseek/policy";
-import { effectiveSandboxMode, shouldConfineSandbox, } from "@xrkseek/protocol";
-import { createLifecycleWebhookNotifier, createPolicyEngineFromPlugins, createShellHookPre, defaultLifecycleWebhookPaths, defaultShellHookPaths, loadLifecycleWebhooks, loadShellHookCommands, wireCompositionHooks, wireCompositionTools, wireCompositionPrompts, } from "@xrkseek/server-loader";
+import { createPolicyToolPre, createSessionReadOnlyToolPre, createWritePathSecurityPre, createWritePathSecurityPost, } from "@xrkseek/policy";
+import { effectiveSandboxMode, flattenText, isHumanUserMessageSource, shouldConfineSandbox, } from "@xrkseek/protocol";
+import { createLifecycleWebhookNotifier, createPolicyEngineFromPlugins, createShellHookPost, createShellHookPre, createShellLifecycleHooks, defaultLifecycleWebhookPaths, defaultShellHookPaths, loadLifecycleWebhooks, loadShellHooksConfig, wireCompositionHooks, wireCompositionTools, wireCompositionPrompts, } from "@xrkseek/server-loader";
 import { createDefaultSessionTelemetryAccess, wrapStoreForSessionTelemetry, } from "@xrkseek/session-telemetry";
 import path from "node:path";
-import { createWorkspaceInjector, createWorkspaceToolOutputPersist, createSkillTools, createSlashResolver, loadOfficeRecipes, mergeRecipesById, appendWorkspaceInjectsIfChanged, resolveProductHome, SKILL_TOOL_GUIDANCE, } from "@xrkseek/workspace";
+import { createWorkspaceInjector, createWorkspaceToolOutputPersist, createSkillTools, createProposeSkillTool, createSlashResolver, loadOfficeRecipes, mergeRecipesById, appendWorkspaceInjectsIfChanged, resolveProductHome, noteLearningLoopTurn, consumeLearningLoopNudge, learningLoopNudgeText, SKILL_TOOL_GUIDANCE, } from "@xrkseek/workspace";
 export const presetId = "harness";
 function ensureSession(store, id) {
     if (id) {
@@ -48,7 +49,9 @@ function toInjectOptions(root, opt, displayTitle) {
         ...(displayTitle?.trim() ? { displayTitle: displayTitle.trim() } : {}),
     };
 }
-function wrapStoreForLifecycleWebhooks(store, notifier, sessionId) {
+function wrapStoreForLifecycleWebhooks(store, notifier, sessionId, shellLifecycle) {
+    if (!notifier && !shellLifecycle)
+        return store;
     return {
         create: (id) => store.create(id),
         get: (id) => store.get(id),
@@ -62,20 +65,41 @@ function wrapStoreForLifecycleWebhooks(store, notifier, sessionId) {
             ? { isLoaded: (id) => store.isLoaded(id) }
             : {}),
         append(id, event) {
+            if (id === sessionId && event.type === "context/compaction") {
+                shellLifecycle?.fire("PreCompact", {
+                    turn_id: event.turnId,
+                    reason: event.reason,
+                    trigger: event.reason,
+                });
+            }
             const logged = store.append(id, event);
             if (id === sessionId) {
                 if (event.type === "turn/start") {
-                    notifier.fire({
+                    notifier?.fire({
                         hookEventName: "turn/start",
                         turnId: event.turnId,
                     });
+                    shellLifecycle?.fire("UserPromptSubmit", {
+                        turn_id: event.turnId,
+                    });
                 }
                 else if (event.type === "turn/end") {
-                    notifier.fire({
+                    notifier?.fire({
                         hookEventName: "turn/end",
                         turnId: event.turnId,
                         extra: { reason: event.reason },
                     });
+                    shellLifecycle?.fire("Stop", {
+                        turn_id: event.turnId,
+                        reason: event.reason,
+                    });
+                }
+                else if (event.type === "context/compaction") {
+                    shellLifecycle?.fire("PostCompact", {
+                        turn_id: event.turnId,
+                        reason: event.reason,
+                        trigger: event.reason,
+                    });
                 }
             }
             return logged;
@@ -109,6 +133,7 @@ export function createHarnessComposition(options) {
                 telOpt?.sink ??
                     createDefaultSessionTelemetryAccess({
                         ...(telOpt?.env !== undefined ? { env: telOpt.env } : {}),
+                        ...(telOpt?.product !== undefined ? { product: telOpt.product } : {}),
                         ...(telOpt?.fetchImpl !== undefined
                             ? { fetchImpl: telOpt.fetchImpl }
                             : {}),
@@ -145,8 +170,37 @@ export function createHarnessComposition(options) {
             });
         }
     }
-    if (lifecycleNotifier) {
-        store = wrapStoreForLifecycleWebhooks(store, lifecycleNotifier, sessionId);
+    let shellLifecycle;
+    let shellHooksConfig = {};
+    if (options.shellHooks !== false) {
+        const shellOpt = typeof options.shellHooks === "object" ? options.shellHooks : undefined;
+        shellHooksConfig =
+            shellOpt?.config ??
+                (shellOpt?.commands
+                    ? { PreToolUse: shellOpt.commands }
+                    : loadShellHooksConfig(shellOpt?.paths ??
+                        defaultShellHookPaths(options.workspaceRoot, resolveProductHome())));
+        const hasLifecycle = (shellHooksConfig.UserPromptSubmit?.length ?? 0) > 0 ||
+            (shellHooksConfig.Stop?.length ?? 0) > 0 ||
+            (shellHooksConfig.PreCompact?.length ?? 0) > 0 ||
+            (shellHooksConfig.PostCompact?.length ?? 0) > 0 ||
+            (shellHooksConfig.SubagentStart?.length ?? 0) > 0 ||
+            (shellHooksConfig.SubagentStop?.length ?? 0) > 0 ||
+            (shellHooksConfig.SessionStart?.length ?? 0) > 0;
+        if (hasLifecycle) {
+            shellLifecycle = createShellLifecycleHooks({
+                config: shellHooksConfig,
+                cwd: () => options.workspaceRoot,
+                sessionId,
+                ...(shellOpt?.defaultTimeoutMs !== undefined
+                    ? { defaultTimeoutMs: shellOpt.defaultTimeoutMs }
+                    : {}),
+                ...(shellOpt?.runner !== undefined ? { runner: shellOpt.runner } : {}),
+            });
+        }
+    }
+    if (lifecycleNotifier || shellLifecycle) {
+        store = wrapStoreForLifecycleWebhooks(store, lifecycleNotifier, sessionId, shellLifecycle);
     }
     const sandbox = options.sandbox ??
         createSandboxStack({
@@ -157,6 +211,9 @@ export function createHarnessComposition(options) {
             ...(options.sandboxDockerImage !== undefined
                 ? { dockerImage: options.sandboxDockerImage }
                 : {}),
+            ...(options.sandboxDockerNetwork !== undefined
+                ? { dockerNetwork: options.sandboxDockerNetwork }
+                : {}),
             ...(options.sandboxWindowsHelper !== undefined
                 ? { windowsHelper: options.sandboxWindowsHelper }
                 : {}),
@@ -166,6 +223,9 @@ export function createHarnessComposition(options) {
             ...(options.sandboxWindowsNetwork !== undefined
                 ? { windowsNetwork: options.sandboxWindowsNetwork }
                 : {}),
+            ...(options.sandboxProduct !== undefined
+                ? { product: options.sandboxProduct }
+                : {}),
             ...(options.remoteExecution ? { remoteExecution: true } : {}),
         });
     const sandboxMode = effectiveSandboxMode(readSessionEvents(store, sessionId), "workspace-write");
@@ -214,13 +274,24 @@ export function createHarnessComposition(options) {
     })) {
         tools.register(tool);
     }
+    tools.register(createProposeSkillTool({
+        resolveWorkspaceRoot: () => options.workspaceRoot,
+    }));
     if (options.webTools !== false) {
         const access = typeof options.webTools === "object"
             ? options.webTools
             : createDefaultWebAccess(options.webSearch ? { search: options.webSearch } : {});
         for (const tool of createWebTools(access))
             tools.register(tool);
-        const browser = createBrowserSession({ fetch: access.fetch });
+        const makeBrowser = () => createBrowserSession({
+            fetch: access.fetch,
+            ...(options.browserProduct
+                ? { product: options.browserProduct }
+                : {}),
+        });
+        const browser = options.browserRuntime
+            ? options.browserRuntime.getOrCreate(sessionId, makeBrowser)
+            : makeBrowser();
         for (const tool of createBrowserTools(browser, options.attachments
             ? {
                 saveScreenshot: (png) => options.attachments.saveImage({
@@ -236,9 +307,17 @@ export function createHarnessComposition(options) {
     if (options.computerUseTools !== false) {
         const service = typeof options.computerUseTools === "object"
             ? options.computerUseTools
-            : createDefaultComputerUseAccess().service;
+            : createDefaultComputerUseAccess({
+                ...(options.computerUseEnv
+                    ? { env: options.computerUseEnv }
+                    : {}),
+                ...(options.computerUseProduct
+                    ? { product: options.computerUseProduct }
+                    : {}),
+            }).service;
         for (const tool of createComputerUseTools({
             ...(service ? { service } : {}),
+            ...(options.computerUseEnv ? { env: options.computerUseEnv } : {}),
         })) {
             tools.register(tool);
         }
@@ -246,9 +325,18 @@ export function createHarnessComposition(options) {
     if (options.voiceTools !== false) {
         const service = typeof options.voiceTools === "object"
             ? options.voiceTools
-            : createDefaultVoiceAccess().service;
+            : createDefaultVoiceAccess({
+                ...(options.voiceEnv ? { env: options.voiceEnv } : {}),
+                ...(options.voiceProduct
+                    ? { product: options.voiceProduct }
+                    : {}),
+            }).service;
         for (const tool of createVoiceTools({
             ...(service ? { service } : {}),
+            ...(options.voiceEnv ? { env: options.voiceEnv } : {}),
+            ...(options.voiceProduct
+                ? { product: options.voiceProduct }
+                : {}),
         })) {
             tools.register(tool);
         }
@@ -264,9 +352,18 @@ export function createHarnessComposition(options) {
     if (options.imageGenTools !== false) {
         const service = typeof options.imageGenTools === "object"
             ? options.imageGenTools
-            : createDefaultImageGenAccess().service;
+            : createDefaultImageGenAccess({
+                ...(options.imageGenEnv ? { env: options.imageGenEnv } : {}),
+                ...(options.imageGenProduct
+                    ? { product: options.imageGenProduct }
+                    : {}),
+            }).service;
         for (const tool of createImageGenTools({
             ...(service ? { service } : {}),
+            ...(options.imageGenEnv ? { env: options.imageGenEnv } : {}),
+            ...(options.imageGenProduct
+                ? { product: options.imageGenProduct }
+                : {}),
             ...(options.attachments ? { attachments: options.attachments } : {}),
         })) {
             tools.register(tool);
@@ -275,9 +372,18 @@ export function createHarnessComposition(options) {
     if (options.videoGenTools !== false) {
         const service = typeof options.videoGenTools === "object"
             ? options.videoGenTools
-            : createDefaultVideoGenAccess().service;
+            : createDefaultVideoGenAccess({
+                ...(options.videoGenEnv ? { env: options.videoGenEnv } : {}),
+                ...(options.videoGenProduct
+                    ? { product: options.videoGenProduct }
+                    : {}),
+            }).service;
         for (const tool of createVideoGenTools({
             ...(service ? { service } : {}),
+            ...(options.videoGenEnv ? { env: options.videoGenEnv } : {}),
+            ...(options.videoGenProduct
+                ? { product: options.videoGenProduct }
+                : {}),
             ...(options.attachments ? { attachments: options.attachments } : {}),
         })) {
             tools.register(tool);
@@ -319,9 +425,6 @@ export function createHarnessComposition(options) {
             tools.register(tool);
         }
     }
-    if (options.presentation === "code" || options.codeRuntime) {
-        tools.register(createRunCodeTool(options.codeRuntime ?? createWorkerCodeRuntime()));
-    }
     wireCompositionTools(tools, {
         ...(options.extraTools ? { extraTools: options.extraTools } : {}),
         ...(options.plugins ? { plugins: options.plugins } : {}),
@@ -340,31 +443,42 @@ export function createHarnessComposition(options) {
                     : {}),
             },
     });
+    // Code Mode after the live registry + pipeline exist so nested
+    // `await tools.name(args)` re-enters the same waterfall (policy/settle).
+    if (options.presentation === "code" || options.codeRuntime) {
+        const runtime = options.codeRuntime ?? createWorkerCodeRuntime();
+        tools.register(createRunCodeTool(runtime, createRegistryCodeToolBridge(tools, { pipeline })));
+    }
     const policyEngine = createPolicyEngineFromPlugins({
         ...(options.policy !== undefined ? { engine: options.policy } : {}),
         ...(options.plugins !== undefined ? { plugins: options.plugins } : {}),
     });
+    // Fail-closed floors **before** policy (Hermes hardline / security-guidance shape).
+    pipeline.onPre(createHardlineArgvPre());
+    pipeline.onPre(createWritePathSecurityPre());
     if (policyEngine) {
         pipeline.onPre(createPolicyToolPre(policyEngine));
     }
     // Live read-only gate (session knobs), not create-time snapshot.
     pipeline.onPre(createSessionReadOnlyToolPre(() => effectiveSandboxMode(readSessionEvents(store, sessionId)) ===
         "read-only"));
-    // Shell PreToolUse (hooks.json) — after policy / read-only; before kind:hooks.
+    // Shell hooks.json — PreToolUse + PostToolUse after policy / read-only; before kind:hooks.
     if (options.shellHooks !== false) {
         const shellOpt = typeof options.shellHooks === "object" ? options.shellHooks : undefined;
-        const shellCommands = shellOpt?.commands ??
-            loadShellHookCommands(shellOpt?.paths ??
-                defaultShellHookPaths(options.workspaceRoot, resolveProductHome()));
-        if (shellCommands.length > 0) {
-            pipeline.onPre(createShellHookPre({
-                commands: shellCommands,
-                cwd: () => options.workspaceRoot,
-                ...(shellOpt?.defaultTimeoutMs !== undefined
-                    ? { defaultTimeoutMs: shellOpt.defaultTimeoutMs }
-                    : {}),
-                ...(shellOpt?.runner !== undefined ? { runner: shellOpt.runner } : {}),
-            }));
+        const preCommands = shellHooksConfig.PreToolUse ?? [];
+        const postCommands = shellHooksConfig.PostToolUse ?? [];
+        const shared = {
+            cwd: () => options.workspaceRoot,
+            ...(shellOpt?.defaultTimeoutMs !== undefined
+                ? { defaultTimeoutMs: shellOpt.defaultTimeoutMs }
+                : {}),
+            ...(shellOpt?.runner !== undefined ? { runner: shellOpt.runner } : {}),
+        };
+        if (preCommands.length > 0) {
+            pipeline.onPre(createShellHookPre({ commands: preCommands, ...shared }));
+        }
+        if (postCommands.length > 0) {
+            pipeline.onPost(createShellHookPost({ commands: postCommands, ...shared }));
         }
     }
     // kind:hooks — after policy / read-only / shell; before guards + builtin post.
@@ -375,9 +489,11 @@ export function createHarnessComposition(options) {
         pipeline.onGuard(createSandboxWrapGuard(sandbox));
         pipeline.onGuard(createWriteIntentGuard({
             hasRead: (p) => tracker.hasRead(p),
-            writeToolNames: ["apply_edit", "write_file"],
+            writeToolNames: ["apply_edit", "write_file", "apply_patch"],
         }));
     }
+    // Advisory write-path content patterns (append to tool result; before lifecycle post).
+    pipeline.onPost(createWritePathSecurityPost());
     if (lifecycleNotifier) {
         const notifier = lifecycleNotifier;
         pipeline.onPost(async (ctx) => {
@@ -417,6 +533,32 @@ export function createHarnessComposition(options) {
         order: 0,
         content: () => persona,
     });
+    prompts.register({
+        id: "language",
+        order: 1,
+        content: () => options.locale === "zh"
+            ? [
+                "# Language",
+                "界面语言为简体中文。",
+                "- 一律使用简体中文进行思考（thinking / reasoning / 规划 / 工具调用前的判断）以及最终回复。不得用英文起笔推理。",
+                "- 保持原样、不要翻译：代码、命令、文件路径、API 与工具名、参数键名、标识符、日志原文、报错文本。",
+                "- 引用工具输出时保留原文，解释部分用中文。",
+                "- 用户主动用英文提问时仍可用英文回复，但界面为中文期间默认中文。",
+            ].join("\n")
+            : options.locale === "en"
+                ? [
+                    "# Language",
+                    "The UI language is English.",
+                    "- Reason (thinking, planning, pre-tool narration) and reply in English.",
+                    "- Keep code, commands, file paths, tool and parameter names, identifiers and raw tool output verbatim.",
+                ].join("\n")
+                : [
+                    "# Language",
+                    "No explicit UI locale was configured.",
+                    "- Reason and reply in the same natural language as the user's latest message: if the user writes Chinese, think and answer in Chinese.",
+                    "- Keep code, commands, file paths, tool and parameter names, identifiers and raw tool output verbatim.",
+                ].join("\n"),
+    });
     if (curatedMemory) {
         // Policy is always present (even with empty files) so a new session does not
         // treat leftover MEMORY.md WIP as a task queue — Codex-style isolation.
@@ -499,6 +641,13 @@ export function createHarnessComposition(options) {
         order: 112,
         content: () => SKILL_TOOL_GUIDANCE,
     });
+    prompts.register({
+        id: "tool:propose_skill",
+        order: 112.5,
+        content: () => availableToolNames().has("propose_skill")
+            ? "After a complex multi-step task that produced a reusable procedure, call `propose_skill` with a class-level SKILL.md draft. The user must approve before anything is written under `.agents/skills`."
+            : "",
+    });
     if (options.lspTools !== false) {
         prompts.register({
             id: "tool:lsp",
@@ -554,6 +703,11 @@ export function createHarnessComposition(options) {
             content: () => SUBAGENT_ROUTING_PROMPT_TEXT,
         });
     }
+    prompts.register({
+        id: "tool:session-query",
+        order: 108,
+        content: () => SESSION_QUERY_ROUTING_PROMPT_TEXT,
+    });
     wireCompositionPrompts(prompts, {
         ...(options.plugins ? { plugins: options.plugins } : {}),
         reservedIds: [
@@ -564,6 +718,7 @@ export function createHarnessComposition(options) {
             "tool:shell-routing",
             "tool:jobs",
             ...(options.subagentRouting !== false ? ["tool:subagent"] : []),
+            "tool:session-query",
             ...(options.webTools !== false
                 ? ["tool:web_search", "tool:web_fetch", "tool:browser"]
                 : []),
@@ -581,21 +736,58 @@ export function createHarnessComposition(options) {
             ? { productDir: injectOpts.productDir }
             : {}),
     });
+    // Fragment pipeline is opt-out; empty by default. Layered apart from
+    // durable workspace inject (beforeUserMessage runs inject then fragments).
+    const contextFragments = options.contextFragments === false
+        ? undefined
+        : typeof options.contextFragments === "object"
+            ? options.contextFragments
+            : createContextFragmentPipeline({
+                ...(options.contextFragmentBudgetChars !== undefined
+                    ? { budgetChars: options.contextFragmentBudgetChars }
+                    : {}),
+            });
+    if (contextFragments && options.contextFragmentProviders) {
+        for (const provider of options.contextFragmentProviders) {
+            contextFragments.register(provider);
+        }
+    }
+    if (contextFragments) {
+        contextFragments.register({
+            id: "learning-loop-nudge",
+            phases: ["turn-start"],
+            produce({ sessionId: sid }) {
+                if (!consumeLearningLoopNudge(sid))
+                    return [];
+                return [
+                    createAdditionalContextFragment({
+                        key: "learning_loop",
+                        value: learningLoopNudgeText(),
+                        phase: "turn-start",
+                        priority: -5,
+                    }),
+                ];
+            },
+        });
+    }
     return {
         id: presetId,
-        description: "XRK Harness: fs + shell + sandbox + web + browser + computer_use + voice + image_gen + lsp + pty + workspace inject",
+        description: "XRK Harness: fs + shell + sandbox + web + browser + computer_use + voice + image_gen + lsp + pty + workspace inject + context fragments",
         workspaceRoot: options.workspaceRoot,
         fs,
         workspace,
+        ...(contextFragments ? { contextFragments } : {}),
         tools,
         pipeline,
         llm,
         store,
         sessionId,
         prompts,
+        ...(shellLifecycle ? { shellLifecycle } : {}),
         async createAgent() {
             const useAssemble = options.assemble !== false;
             const injectOn = shouldInject(options.assemble, options.workspaceInject);
+            const wireBeforeUserMessage = injectOn || contextFragments !== undefined;
             const productDir = injectOpts.productDir ?? path.join(injectOpts.root, ".xrk");
             let recipes = [];
             if (useAssemble && options.slashRecipes !== false) {
@@ -651,38 +843,67 @@ export function createHarnessComposition(options) {
                         // Legacy path: freeze once (no per-step tool visibility).
                         system: await prompts.assemble(),
                     }),
-                ...(injectOn
+                ...(wireBeforeUserMessage
                     ? {
                         beforeUserMessage: async (ctx) => {
-                            await appendWorkspaceInjectsIfChanged({
-                                ...ctx,
-                                injectOptions: injectOpts,
-                                injector: workspace,
-                            });
-                        },
-                    }
-                    : {}),
-                ...(curatedMemory
-                    ? {
-                        afterTurn: ({ userText, assistantText, turnId }) => {
-                            const memoryToolWrote = readSessionEvents(store, sessionId).some((event) => event.type === "tool/call" &&
-                                event.turnId === turnId &&
-                                event.call.name === "memory");
-                            writeReusableNotesAfterTurn(curatedMemory, {
-                                userText: userText ?? "",
-                                assistantText,
-                                memoryToolWrote,
-                            });
+                            if (injectOn) {
+                                await appendWorkspaceInjectsIfChanged({
+                                    ...ctx,
+                                    injectOptions: injectOpts,
+                                    injector: workspace,
+                                });
+                            }
+                            if (contextFragments) {
+                                await appendContextFragments({
+                                    store: ctx.store,
+                                    sessionId: ctx.sessionId,
+                                    turnId: ctx.turnId,
+                                    now: ctx.now,
+                                    pipeline: contextFragments,
+                                    phase: "turn-start",
+                                });
+                            }
                         },
                     }
                     : {}),
-                prepareUserContent: ({ content, text, signal }) => prepareFaceSessionReferences({
-                    targetSessionId: sessionId,
-                    content,
-                    text,
-                    readEvents: (id) => readSessionEvents(store, id),
-                    ...(signal ? { signal } : {}),
-                }),
+                afterTurn: ({ userText, assistantText, turnId, toolOk, toolFailed }) => {
+                    noteLearningLoopTurn(sessionId, toolOk + toolFailed);
+                    if (!curatedMemory)
+                        return;
+                    const memoryToolWrote = readSessionEvents(store, sessionId).some((event) => event.type === "tool/call" &&
+                        event.turnId === turnId &&
+                        event.call.name === "memory");
+                    void writeReusableNotesAfterTurn(curatedMemory, {
+                        userText: userText ?? "",
+                        assistantText,
+                        memoryToolWrote,
+                    });
+                },
+                prepareUserContent: async ({ content, text, signal }) => {
+                    const prepared = prepareFaceSessionReferences({
+                        targetSessionId: sessionId,
+                        content,
+                        text,
+                        readEvents: (id) => readSessionEvents(store, id),
+                        resolveCwd: () => options.workspaceRoot,
+                        maxReferenceBytes: 65_536,
+                        ...(signal ? { signal } : {}),
+                    });
+                    if (!contextFragments)
+                        return prepared;
+                    const collected = await contextFragments.collect("user-message", {
+                        sessionId,
+                        userText: text,
+                        ...(signal ? { signal } : {}),
+                    });
+                    return {
+                        ...prepared,
+                        contexts: [
+                            ...prepared.contexts,
+                            ...fragmentsToPrepareContexts(collected),
+                        ],
+                    };
+                },
                 ...(options.resolveImage
                     ? { resolveImage: options.resolveImage }
                     : {}),
@@ -724,6 +945,8 @@ export function createHarnessComposition(options) {
                 sessionId,
                 presentation: options.presentation ?? "tools",
                 workspaceInject: options.workspaceInject !== false,
+                contextFragments: contextFragments !== undefined,
+                contextFragmentProviders: contextFragments?.list().map((p) => p.id) ?? [],
                 slashRecipes: options.slashRecipes !== false,
                 plugins: (options.plugins ?? []).map((p) => p.id),
                 policy: Boolean(createPolicyEngineFromPlugins({
@@ -735,6 +958,27 @@ export function createHarnessComposition(options) {
             };
         },
         async dispose() {
+            // Session-end Phase1: fold leftover human notes into MEMORY.md (disk only).
+            if (curatedMemory) {
+                try {
+                    const userTexts = [];
+                    for (const event of readSessionEvents(store, sessionId)) {
+                        if (event.type !== "user/message")
+                            continue;
+                        if (!isHumanUserMessageSource(event.source))
+                            continue;
+                        const text = flattenText(event.content).trim();
+                        if (text)
+                            userTexts.push(text);
+                    }
+                    if (userTexts.length > 0) {
+                        void consolidateCuratedMemoryPhase1(curatedMemory, { userTexts });
+                    }
+                }
+                catch {
+                    /* best-effort — dispose must continue */
+                }
+            }
             if (!sharedShell)
                 await rootShell.dispose();
             if (telemetrySink) {