@mininglamp-oss/cc-channel-octo 1.0.3-dev.203dc5f → 1.0.3-dev.3332be0

package/dist/group-md.d.ts

@@ -0,0 +1,76 @@
+/**
+ * GROUP.md / THREAD.md resolution: server-first fetch with a never-lose
+ * local-file fallback, behind a feature flag.
+ *
+ * `resolveGroupInstructions` is the single entry point the message pipeline
+ * calls to obtain the trusted per-conversation instruction block injected into
+ * the agent's system prompt.
+ *
+ * 🔴 Thread vs group are MUTUALLY EXCLUSIVE (老板拍板口径, #88 P3). The entry
+ * point routes on channelId shape:
+ *   - A thread (`<groupNo>____<shortId>`, CommunityTopic) resolves its OWN
+ *     THREAD.md only. It NEVER falls back to — nor stacks — the parent group's
+ *     GROUP.md, and it NEVER reads or writes the group's `groupMdCache` (which
+ *     is keyed by the parent groupNo). See `resolveThreadInstructions`.
+ *   - A plain group (`<groupNo>`, no separator) resolves its GROUP.md exactly as
+ *     before — the group branch below is byte-for-byte the pre-P3 behavior.
+ *
+ * The bug this fixes (XIN-224): the old resolver collapsed EVERY channelId to
+ * its parent groupNo via `extractParentGroupNo`, so with `serverMd` on a thread
+ * message was injected the parent group's GROUP.md — violating the redline that
+ * a thread injects only its own THREAD.md.
+ *
+ * Group-branch resolution order (unchanged):
+ *   1. Feature flag OFF (default) or no cache wired → pure local file
+ *      (`loadGroupConfig`). Byte-identical to the pre-P2 behavior.
+ *   2. Feature flag ON:
+ *        a. serve a cached server GROUP.md if present and not past its TTL (keyed
+ *           by the group number). The cache is IN-MEMORY ONLY (no disk), so the
+ *           only way content reaches this trusted system-prompt channel is a
+ *           live, authenticated fetch — never a forgeable on-disk artifact
+ *           (review #172 🔴; see group-md-cache.ts);
+ *        b. otherwise fetch from the server (server-first). On success with
+ *           non-empty content, cache it and use it;
+ *        c. on ANY failure (404 "no GROUP.md", network, timeout, empty content)
+ *           fall back to the local file. The local-file path is never lost.
+ *
+ * Thread-branch resolution order (P3-1) mirrors the group branch, keyed by the
+ * COMPOSITE `<groupNo>::<shortId>` (see `resolveThreadInstructions`), gated on
+ * the independent `threadMd` flag; when the flag is off a thread still resolves
+ * its local `<shortId>.md` (already the correct non-stacking behavior).
+ *
+ * Trust: server content stands on its own trust root — an authenticated
+ * `getGroupMd` / `getThreadMd` over the bot token against the SSRF-validated
+ * `apiUrl` — NOT on the OS-permission trust the local `groupConfigDir` file
+ * relies on. By caching only in memory we never let server content masquerade
+ * as (or be confused with) a trusted local file on disk.
+ *
+ * Never throws — a server error degrades to local, a local miss degrades to
+ * "no custom instructions".
+ */
+import type { GroupMdCache, ThreadMdCache } from './group-md-cache.js';
+export interface ResolveGroupInstructionsParams {
+    /** Operator local-instruction directory (the existing fallback source). */
+    groupConfigDir?: string;
+    /** Feature flag: when false/undefined, server GROUP.md fetch is skipped. */
+    serverMd?: boolean;
+    /**
+     * P3-1 feature flag: when true, a THREAD channel resolves its THREAD.md
+     * server-first (GET /v1/bot/groups/{groupNo}/threads/{shortId}/md) before its
+     * local `<shortId>.md`. When false/undefined (default) a thread resolves ONLY
+     * its local file — which is already the correct non-stacking behavior, so the
+     * flag gates the NEW server-read capability, not the bug fix. Independent of
+     * `serverMd` (which governs the group server-read path).
+     */
+    threadMd?: boolean;
+    apiUrl: string;
+    botToken: string;
+    /** Full channelId (may be a `<groupNo>____<shortId>` thread composite). */
+    channelId: string;
+    /** Server GROUP.md cache (group branch). Omitted (or flag off) → pure local. */
+    cache?: GroupMdCache;
+    /** Server THREAD.md cache (thread branch). Omitted (or flag off) → pure local. */
+    threadCache?: ThreadMdCache;
+    signal?: AbortSignal;
+}
+export declare function resolveGroupInstructions(params: ResolveGroupInstructionsParams): Promise<string | undefined>;

package/dist/group-md.js

@@ -0,0 +1,187 @@
+/**
+ * GROUP.md / THREAD.md resolution: server-first fetch with a never-lose
+ * local-file fallback, behind a feature flag.
+ *
+ * `resolveGroupInstructions` is the single entry point the message pipeline
+ * calls to obtain the trusted per-conversation instruction block injected into
+ * the agent's system prompt.
+ *
+ * 🔴 Thread vs group are MUTUALLY EXCLUSIVE (老板拍板口径, #88 P3). The entry
+ * point routes on channelId shape:
+ *   - A thread (`<groupNo>____<shortId>`, CommunityTopic) resolves its OWN
+ *     THREAD.md only. It NEVER falls back to — nor stacks — the parent group's
+ *     GROUP.md, and it NEVER reads or writes the group's `groupMdCache` (which
+ *     is keyed by the parent groupNo). See `resolveThreadInstructions`.
+ *   - A plain group (`<groupNo>`, no separator) resolves its GROUP.md exactly as
+ *     before — the group branch below is byte-for-byte the pre-P3 behavior.
+ *
+ * The bug this fixes (XIN-224): the old resolver collapsed EVERY channelId to
+ * its parent groupNo via `extractParentGroupNo`, so with `serverMd` on a thread
+ * message was injected the parent group's GROUP.md — violating the redline that
+ * a thread injects only its own THREAD.md.
+ *
+ * Group-branch resolution order (unchanged):
+ *   1. Feature flag OFF (default) or no cache wired → pure local file
+ *      (`loadGroupConfig`). Byte-identical to the pre-P2 behavior.
+ *   2. Feature flag ON:
+ *        a. serve a cached server GROUP.md if present and not past its TTL (keyed
+ *           by the group number). The cache is IN-MEMORY ONLY (no disk), so the
+ *           only way content reaches this trusted system-prompt channel is a
+ *           live, authenticated fetch — never a forgeable on-disk artifact
+ *           (review #172 🔴; see group-md-cache.ts);
+ *        b. otherwise fetch from the server (server-first). On success with
+ *           non-empty content, cache it and use it;
+ *        c. on ANY failure (404 "no GROUP.md", network, timeout, empty content)
+ *           fall back to the local file. The local-file path is never lost.
+ *
+ * Thread-branch resolution order (P3-1) mirrors the group branch, keyed by the
+ * COMPOSITE `<groupNo>::<shortId>` (see `resolveThreadInstructions`), gated on
+ * the independent `threadMd` flag; when the flag is off a thread still resolves
+ * its local `<shortId>.md` (already the correct non-stacking behavior).
+ *
+ * Trust: server content stands on its own trust root — an authenticated
+ * `getGroupMd` / `getThreadMd` over the bot token against the SSRF-validated
+ * `apiUrl` — NOT on the OS-permission trust the local `groupConfigDir` file
+ * relies on. By caching only in memory we never let server content masquerade
+ * as (or be confused with) a trusted local file on disk.
+ *
+ * Never throws — a server error degrades to local, a local miss degrades to
+ * "no custom instructions".
+ */
+import { getGroupMd, getThreadMd } from './octo/api.js';
+import { extractParentGroupNo, extractThreadShortId, isThreadChannelId } from './octo/channel-id.js';
+import { loadGroupConfig, MAX_GROUP_CONFIG_BYTES } from './group-config.js';
+/**
+ * Trim and byte-bound server-provided GROUP.md the same way loadGroupConfig
+ * bounds a local file, so an oversized server payload can't blow the prompt
+ * budget. Returns undefined for empty/whitespace-only content.
+ */
+function boundInstructions(content) {
+    let text = content;
+    if (Buffer.byteLength(text, 'utf-8') > MAX_GROUP_CONFIG_BYTES) {
+        const buf = Buffer.from(text, 'utf-8').subarray(0, MAX_GROUP_CONFIG_BYTES);
+        // The slice may end mid-codepoint; trim a trailing replacement char.
+        text = buf.toString('utf-8').replace(/�+$/, '') + '\n[… group config truncated]';
+    }
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export async function resolveGroupInstructions(params) {
+    // 🔴 Thread and group are mutually exclusive. A thread resolves ONLY its own
+    // THREAD.md and must never touch the parent group's GROUP.md nor its cache.
+    if (isThreadChannelId(params.channelId)) {
+        return resolveThreadInstructions(params);
+    }
+    return resolveGroupBranch(params);
+}
+/**
+ * Plain-group branch — byte-for-byte the pre-P3 `resolveGroupInstructions`
+ * behavior (server-first GROUP.md + in-memory cache keyed by groupNo + never-
+ * lose local `<groupNo>.md` fallback). Reached only for non-thread channelIds.
+ */
+async function resolveGroupBranch(params) {
+    const { groupConfigDir, serverMd, apiUrl, botToken, channelId, cache, signal } = params;
+    const local = () => loadGroupConfig(groupConfigDir, channelId);
+    // Flag off (or no cache to dedupe fetches) → pure local file, unchanged behavior.
+    if (!serverMd || !cache)
+        return local();
+    const groupNo = extractParentGroupNo(channelId);
+    // a) fresh cached server GROUP.md wins. The cache is in-memory only and TTL-
+    //    bounded, so an expired entry reads as a miss and falls through to a
+    //    re-fetch below (staleness backstop; item B adds event-driven refresh).
+    const cached = cache.get(groupNo);
+    if (cached) {
+        const bounded = boundInstructions(cached.content);
+        if (bounded)
+            return bounded;
+        // Cached-but-empty (shouldn't normally happen) → fall through to local.
+        return local();
+    }
+    // b) server-first fetch.
+    try {
+        const md = await getGroupMd({ apiUrl, botToken, groupNo, signal });
+        const bounded = boundInstructions(md?.content ?? '');
+        if (bounded) {
+            const entry = {
+                content: md.content,
+                version: typeof md.version === 'number' ? md.version : 0,
+                updated_at: md.updated_at ?? null,
+                updated_by: md.updated_by,
+            };
+            cache.set(groupNo, entry);
+            return bounded;
+        }
+        // Server reachable but no/empty GROUP.md → local fallback.
+        return local();
+    }
+    catch (err) {
+        // c) 404 / network / timeout — never-lose local fallback.
+        console.error(`[cc-channel-octo] group-md: server fetch for ${groupNo} failed, falling back to local: ${String(err)}`);
+        return local();
+    }
+}
+/**
+ * Thread branch (P3-1) — resolves a CommunityTopic thread's OWN THREAD.md.
+ *
+ * 🔴 By construction this branch NEVER reads or writes the group `cache`
+ * (keyed by parent groupNo) and NEVER calls `getGroupMd`, so a thread can never
+ * be injected — or have cached — its parent group's GROUP.md.
+ *
+ * Resolution mirrors the group branch, keyed by the COMPOSITE `groupNo::shortId`:
+ *   - `threadMd` off (or no thread cache) → local `<shortId>.md` only
+ *     (`loadGroupConfig` is already thread-aware). This is the correct
+ *     non-stacking behavior even with the new server capability disabled.
+ *   - `threadMd` on:
+ *       a. serve a fresh cached THREAD.md (in-memory only, TTL-bounded);
+ *       b. else server-first `getThreadMd`, cache non-empty content and use it;
+ *       c. on ANY failure / empty → never-lose local `<shortId>.md` fallback.
+ */
+async function resolveThreadInstructions(params) {
+    const { groupConfigDir, threadMd, apiUrl, botToken, channelId, threadCache, signal } = params;
+    // Local fallback keeps the FULL channelId — loadGroupConfig routes a thread to
+    // its own `<shortId>.md`, never the parent group's `<groupNo>.md`.
+    const local = () => loadGroupConfig(groupConfigDir, channelId);
+    // Flag off (or no thread cache) → pure local `<shortId>.md`. Already correct
+    // non-stacking behavior — the flag only gates the server-read capability.
+    if (!threadMd || !threadCache)
+        return local();
+    const groupNo = extractParentGroupNo(channelId);
+    const shortId = extractThreadShortId(channelId);
+    // A malformed thread channelId (`<groupNo>____` with no shortId) can't be
+    // server-keyed — degrade to local rather than fetch a group-scoped path.
+    if (!shortId)
+        return local();
+    // a) fresh cached server THREAD.md wins. Composite-keyed, in-memory only,
+    //    TTL-bounded (expired → miss → re-fetch below).
+    const cached = threadCache.get(groupNo, shortId);
+    if (cached) {
+        const bounded = boundInstructions(cached.content);
+        if (bounded)
+            return bounded;
+        // Cached-but-empty (shouldn't normally happen) → fall through to local.
+        return local();
+    }
+    // b) server-first fetch of this thread's own THREAD.md.
+    try {
+        const md = await getThreadMd({ apiUrl, botToken, groupNo, shortId, signal });
+        const bounded = boundInstructions(md?.content ?? '');
+        if (bounded) {
+            const entry = {
+                content: md.content,
+                version: typeof md.version === 'number' ? md.version : 0,
+                updated_at: md.updated_at ?? null,
+                updated_by: md.updated_by,
+            };
+            threadCache.set(groupNo, shortId, entry);
+            return bounded;
+        }
+        // Server reachable but no/empty THREAD.md → local fallback.
+        return local();
+    }
+    catch (err) {
+        // c) 404 / network / timeout — never-lose local fallback.
+        console.error(`[cc-channel-octo] thread-md: server fetch for ${groupNo}::${shortId} failed, falling back to local: ${String(err)}`);
+        return local();
+    }
+}
+//# sourceMappingURL=group-md.js.map

package/dist/group-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-md.js","sourceRoot":"","sources":["../src/group-md.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -13,6 +13,8 @@ import { SessionRouter } from './session-router.js';
 import { GroupContext } from './group-context.js';
 import { StreamRelay } from './stream-relay.js';
 import type { BotMessage } from './octo/types.js';
+import { GroupMdCache, ThreadMdCache } from './group-md-cache.js';
+import { GroupMdWriteback, ThreadMdWriteback } from './group-md-writeback.js';
 import { CronStore } from './cron-store.js';
 /**
  * Resolve a single bot's concrete Config by its configId (config.json
@@ -33,7 +35,7 @@ export type BotStack = ManagedBot;
  * agent query → stream → persist. Exported so tests can drive the real pipeline
  * (not a replica) — `main()` is the only production caller.
  */
-export declare function handleMessage(msg: BotMessage, config: ReturnType<typeof loadConfig>, store: SessionStore, router: SessionRouter, groupContext: GroupContext, streamRelay: StreamRelay, botId: string, cronStore?: CronStore): Promise<void>;
+export declare function handleMessage(msg: BotMessage, config: ReturnType<typeof loadConfig>, store: SessionStore, router: SessionRouter, groupContext: GroupContext, streamRelay: StreamRelay, botId: string, cronStore?: CronStore, groupMdCache?: GroupMdCache, groupMdWriteback?: GroupMdWriteback, threadMdCache?: ThreadMdCache, threadMdWriteback?: ThreadMdWriteback): Promise<void>;
 /** Max length of the rendered tool-params string in a 🔧 progress notice. */
 export declare const MAX_TOOL_PARAM_CHARS = 120;
 /**

package/dist/index.js

@@ -15,7 +15,7 @@ import { OctoGateway } from './gateway.js';
 import { SessionRouter } from './session-router.js';
 import { GroupContext } from './group-context.js';
 import { queryAgent } from './agent-bridge.js';
-import { sanitizeDisplayName, escapeSectionMarkers, sanitizePromptBody } from './prompt-safety.js';
+import { sanitizeDisplayName, escapeSectionMarkers, sanitizePromptBody, formatSenderLabel } from './prompt-safety.js';
 import { cleanupExpiredCwds, resolveMemoryDir, resolveSessionCwd } from './cwd-resolver.js';
 import { StreamRelay } from './stream-relay.js';
 import { sendMessage, sendReadReceipt, getChannelMessages, getUploadCredentials } from './octo/api.js';
@@ -23,10 +23,14 @@ import { ChannelType, MessageType } from './octo/types.js';
 import { resolveContent, tryResolveFile, resolveHistoricalMessagePlaceholder } from './inbound.js';
 import { downloadInboundImage, MAX_IMAGES_PER_MESSAGE } from './media-inbound.js';
 import { handleCommand } from './commands.js';
-import { loadGroupConfig } from './group-config.js';
+import { resolveGroupInstructions } from './group-md.js';
+import { GroupMdCache, ThreadMdCache, DEFAULT_GROUP_MD_TTL_MS } from './group-md-cache.js';
+import { GroupMdWriteback, ThreadMdWriteback } from './group-md-writeback.js';
 import { CronStore } from './cron-store.js';
 import { CronScheduler } from './cron-scheduler.js';
 import { createCronToolServer, CRON_TOOL_SERVER_NAME } from './cron-tool.js';
+import { createGroupMdToolServer, GROUP_MD_TOOL_SERVER_NAME, createThreadMdToolServer, THREAD_MD_TOOL_SERVER_NAME, } from './group-md-tool.js';
+import { isThreadChannelId } from './octo/channel-id.js';
 import { buildInlinedFileBody, truncateUtf8ByBytes, assembleUserMessage, MAX_USER_LLM_BYTES } from './file-inline-wrap.js';
 import { join } from 'node:path';
 import { mkdirSync, realpathSync } from 'node:fs';
@@ -177,6 +181,34 @@ async function startBot(config, multi) {
         // --- Group context ---
         const groupContext = new GroupContext(adapter, config.context.maxContextChars);
         groupContext.loadAllFromDb();
+        // --- P2-A: server GROUP.md cache. IN-MEMORY ONLY (no disk) — the resolved
+        // GROUP.md is injected as a TRUSTED system-prompt block, and a disk cache the
+        // gateway user can write would be a chat-injection → trusted-prompt poisoning
+        // vector that survives restart (review #172 🔴; see group-md-cache.ts). TTL
+        // bounds staleness (review #172 🟡). Decoupled from the P1 GroupContext
+        // caches; created unconditionally (cheap, only populated when serverMd is on). ---
+        const groupMdCache = new GroupMdCache(config.serverMdTtlMs ?? DEFAULT_GROUP_MD_TTL_MS);
+        // --- P3-1: server THREAD.md cache. Same IN-MEMORY-ONLY security model as the
+        // group cache above, but keyed by the COMPOSITE `groupNo::shortId` so one
+        // group's threads never collide (defensive even though shortId is a globally
+        // unique snowflake today). Created unconditionally (cheap; only populated when
+        // config.threadMd is on). Kept SEPARATE from groupMdCache so the thread branch
+        // can never read or write a parent-group GROUP.md entry (老板拍板互斥口径). ---
+        const threadMdCache = new ThreadMdCache(config.serverMdTtlMs ?? DEFAULT_GROUP_MD_TTL_MS);
+        // --- P2-C: GROUP.md write-back coordinator. Shared across turns so its
+        // per-groupNo write lock actually serializes concurrent agent turns writing
+        // the same group (a per-turn instance would defeat the lock). Updates the
+        // SAME in-memory groupMdCache above on a successful PUT — no new disk surface.
+        // Cheap to construct unconditionally; only exercised when the write-back tool
+        // is registered (config.mdWriteback). ---
+        const groupMdWriteback = new GroupMdWriteback(groupMdCache);
+        // --- P3-2: THREAD.md write-back coordinator. Thread analogue of
+        // groupMdWriteback, shared across turns so its per-`groupNo::shortId` write
+        // lock serializes concurrent turns writing the same thread. Updates the SAME
+        // in-memory threadMdCache above on a successful PUT (no disk surface). Cheap
+        // to construct unconditionally; only exercised when the thread write-back
+        // tool is registered (config.mdWriteback on a thread channel). ---
+        const threadMdWriteback = new ThreadMdWriteback(threadMdCache);
         // --- #115: cron (opt-in). ---
         if (config.sdk.cron && config.botId) {
             cronStore = new CronStore(join(config.baseDir, config.botId, 'cron.json'));
@@ -223,7 +255,11 @@ async function startBot(config, multi) {
             console.warn(`[cc-channel-octo] ${label}Could not prefetch media CDN host (inbound media limited to apiUrl host): ${err instanceof Error ? err.message : String(err)}`);
         }
         // --- Session router ---
-        const router = new SessionRouter(config, gateway.botId, gateway.ownerUid);
+        // P2-B / P3-2: the router holds both md caches so a server GROUP.md or
+        // THREAD.md change event invalidates the affected entry (re-fetched
+        // authoritatively next turn — never trusting the event payload). No-op when
+        // the corresponding flag (serverMd / threadMd) is off.
+        const router = new SessionRouter(config, gateway.botId, gateway.ownerUid, groupMdCache, threadMdCache);
         // --- Active handler tracking (Q6: in-flight drain on shutdown) ---
         const activeHandlers = new Set();
         // Install the message handler NOW (before the socket opens). The socket is
@@ -238,7 +274,7 @@ async function startBot(config, multi) {
             // group message could be cached into group context as un-processed chatter).
             if (msg.from_uid === gateway.botId)
                 return;
-            const p = handleMessage(msg, config, store, router, groupContext, streamRelay, gateway.botId, cronStore)
+            const p = handleMessage(msg, config, store, router, groupContext, streamRelay, gateway.botId, cronStore, groupMdCache, groupMdWriteback, threadMdCache, threadMdWriteback)
                 .catch((err) => {
                 console.error(`[cc-channel-octo] ${label}Unhandled message handler error:`, err instanceof Error ? err.message : err);
             })
@@ -259,7 +295,7 @@ async function startBot(config, multi) {
                 onFire: (msg) => {
                     if (gateway.draining)
                         return Promise.resolve();
-                    const p = handleMessage(msg, config, store, router, groupContext, streamRelay, gateway.botId, cronStore)
+                    const p = handleMessage(msg, config, store, router, groupContext, streamRelay, gateway.botId, cronStore, groupMdCache, groupMdWriteback, threadMdCache, threadMdWriteback)
                         .finally(() => { activeHandlers.delete(p); });
                     activeHandlers.add(p);
                     return p;
@@ -307,7 +343,7 @@ async function startBot(config, multi) {
  * agent query → stream → persist. Exported so tests can drive the real pipeline
  * (not a replica) — `main()` is the only production caller.
  */
-export async function handleMessage(msg, config, store, router, groupContext, streamRelay, botId, cronStore) {
+export async function handleMessage(msg, config, store, router, groupContext, streamRelay, botId, cronStore, groupMdCache, groupMdWriteback, threadMdCache, threadMdWriteback) {
     const channelId = msg.channel_id ?? '';
     const channelType = msg.channel_type ?? ChannelType.DM;
     const isGroup = channelType === ChannelType.Group || channelType === ChannelType.CommunityTopic;
@@ -546,10 +582,30 @@ export async function handleMessage(msg, config, store, router, groupContext, st
             // persists the raw user content without the quote prefix to avoid prefix
             // duplication on conversation replay.
             //
-            // The final user message is assembled AFTER history is built (below), so
-            // the one-time history block + group-context delta can be prepended and
-            // the whole payload capped together. See the assembly near queryAgent.
-            const userBody = quotePrefix + bodyText;
+            // Sender-identity prefix (groups only): the `[Current message — respond to
+            // this ONLY]` anchor previously carried an anonymous body, so a shared-group
+            // Claude Code / Claw agent could not tell WHICH member sent the request
+            // being replied to (the anchor block itself has no sender field, unlike
+            // `[Recent group messages]` where each line already prefixes `name(uid)：`).
+            // We prepend `name(uid)：` — sanitized via formatSenderLabel — to align the
+            // current-message identity semantics with the historical block, so the
+            // agent has a single, uniform convention for identifying speakers across
+            // the whole prompt. DM channels stay anonymous: there's exactly one human
+            // party, adding the prefix would be pure noise. The prefix is persisted
+            // via appendUser below too — otherwise a session-replay would drop identity
+            // from history while keeping it on current, defeating the whole point.
+            //
+            // Resolve the displayName via GroupContext so the wire's from_name (which
+            // is optional and, when present, sometimes just echoes the uid) is
+            // upgraded to the roster displayName learned via refreshMembers. Without
+            // this, human users whose wire payload lacks from_name render as
+            // `uid：body` instead of `name(uid)：body`, breaking the promised uniform
+            // shape.
+            const resolvedName = isGroup && msg.channel_id
+                ? groupContext.resolveDisplayName(msg.channel_id, msg.from_uid, msg.from_name)
+                : undefined;
+            const senderPrefix = isGroup ? `${formatSenderLabel(msg.from_uid, resolvedName)}：` : '';
+            const userBody = quotePrefix + senderPrefix + bodyText;
             // G4: Backfill history from API when local cache is empty for groups.
             // Only triggered on first interaction with a group (cold start) to avoid
             // duplicate API calls; checked via a sentinel marker stored in-memory.
@@ -710,11 +766,35 @@ export async function handleMessage(msg, config, store, router, groupContext, st
                 const memoryDir = resolveMemoryDir(memBase, sessionCtx);
                 sessionOpts = { ...(sessionOpts ?? {}), memoryDir };
             }
-            // v1.0 GROUP.md: inject operator-provided per-group instructions (from
-            // config.groupConfigDir/<channelId>.md) into the system prompt. Only for
-            // groups — DMs key on the peer uid, not a shared channel.
+            // External MCP servers declared in config (sdk.mcpServers): seed the map
+            // FIRST so the per-turn in-process servers below (cron, GROUP.md write-back)
+            // merge on top and win any name clash — those are bound to this turn's
+            // session coords and must not be shadowed by a same-named external server.
+            if (config.sdk.mcpServers && Object.keys(config.sdk.mcpServers).length > 0) {
+                sessionOpts = {
+                    ...(sessionOpts ?? {}),
+                    mcpServers: { ...(sessionOpts?.mcpServers ?? {}), ...config.sdk.mcpServers },
+                };
+            }
+            // GROUP.md: inject operator-provided per-group instructions into the
+            // system prompt. Only for groups — DMs key on the peer uid, not a shared
+            // channel. P2-A: a plain group resolves GROUP.md server-first (GET
+            // /v1/bot/groups/{groupNo}/md, cached) with a never-lose fallback to the
+            // local `groupConfigDir/<channelId>.md` file (gated behind `config.serverMd`).
+            // P3-1: a thread (CommunityTopic) resolves its OWN THREAD.md ONLY — the
+            // resolver routes on channelId shape and NEVER stacks the parent group's
+            // GROUP.md for a thread (server thread read gated behind `config.threadMd`).
             if (isGroup) {
-                const groupInstructions = loadGroupConfig(config.groupConfigDir, channelId);
+                const groupInstructions = await resolveGroupInstructions({
+                    groupConfigDir: config.groupConfigDir,
+                    serverMd: config.serverMd,
+                    threadMd: config.threadMd,
+                    apiUrl: config.apiUrl,
+                    botToken: config.botToken,
+                    channelId,
+                    cache: groupMdCache,
+                    threadCache: threadMdCache,
+                });
                 if (groupInstructions) {
                     sessionOpts = { ...(sessionOpts ?? {}), groupInstructions };
                 }
@@ -732,9 +812,44 @@ export async function handleMessage(msg, config, store, router, groupContext, st
                 const cronServer = createCronToolServer(cronStore, coords, router.getOwnerUid());
                 sessionOpts = {
                     ...(sessionOpts ?? {}),
-                    mcpServers: { [CRON_TOOL_SERVER_NAME]: cronServer },
+                    mcpServers: { ...(sessionOpts?.mcpServers ?? {}), [CRON_TOOL_SERVER_NAME]: cronServer },
                 };
             }
+            // P2-C / P3-2: when md write-back is on, inject the write-back MCP tool
+            // bound to THIS message's channel coords and gated to the bot owner uid.
+            // Only for group-like channels — a DM has no shared md. The tool is chosen
+            // by channel SHAPE and the two are MUTUALLY EXCLUSIVE (#88 P3 redline):
+            //   - a THREAD (CommunityTopic composite `<groupNo>____<shortId>`) gets the
+            //     thread tool, which writes the thread's OWN THREAD.md
+            //     (PUT /threads/{shortId}/md) — never the parent group's GROUP.md. This
+            //     is the XIN-230 follow-up: the write side now matches the P3-1 read
+            //     side instead of collapsing a thread to its parent groupNo.
+            //   - a plain GROUP gets the GROUP.md tool, unchanged (P2-C).
+            // Each borrows its shared writeback coordinator so the per-key write lock
+            // and the cache it refreshes are process-wide, not per-turn.
+            if (config.mdWriteback && isGroup) {
+                const coords = {
+                    channelId,
+                    fromUid: msg.from_uid,
+                    fromName: msg.from_name,
+                };
+                if (isThreadChannelId(channelId)) {
+                    if (threadMdWriteback) {
+                        const threadMdServer = createThreadMdToolServer({ writeback: threadMdWriteback, apiUrl: config.apiUrl, botToken: config.botToken }, coords, router.getOwnerUid());
+                        sessionOpts = {
+                            ...(sessionOpts ?? {}),
+                            mcpServers: { ...(sessionOpts?.mcpServers ?? {}), [THREAD_MD_TOOL_SERVER_NAME]: threadMdServer },
+                        };
+                    }
+                }
+                else if (groupMdWriteback) {
+                    const groupMdServer = createGroupMdToolServer({ writeback: groupMdWriteback, apiUrl: config.apiUrl, botToken: config.botToken }, coords, router.getOwnerUid());
+                    sessionOpts = {
+                        ...(sessionOpts ?? {}),
+                        mcpServers: { ...(sessionOpts?.mcpServers ?? {}), [GROUP_MD_TOOL_SERVER_NAME]: groupMdServer },
+                    };
+                }
+            }
             const rawChunks = queryAgent(userContentForLLM, config, sessionCtx, onToolUse, sessionOpts);
             // Tee the generator: collect full text while streaming to Octo
             const collected = [];