dsh-subagent-profile 0.1.0 → 0.2.0

package/index.mjs

@@ -1,4 +1,4 @@
-// index.mjs — dsh-subagent-profile host half (formal plugin bundle).
+// index.mjs — dsh-subagent-profile host side (formal plugin bundle).
 // Converted from prototype/subagent-profile/host.plugin.js (the dynamic-plugin
 // `code.host` body) with import slimming: the inline foldConsumedWork /
 // accountsForClaim / lastAssistantContent / uuid / AbortController-shim are
@@ -8,21 +8,21 @@
 // in README.md.
 
 import { randomUUID } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { foldConsumedWork } from '@deepseek-ai/dsh-agent';
 import {
   appendDelegatedPolicyOverrides,
   assertSubagentMaxDepth,
   captureDelegatedPolicyOverrides,
-  finalAssistantOutput,
+  createUserMessage,
+  defineTool,
+  readResult,
   resolveChildAgentOptions,
   resolveChildDepth,
-} from '@deepseek-ai/dsh-subagent';
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
-import { defineTool } from '@deepseek-ai/dsh-tools';
+} from './lib/shims.mjs';
+import { textFrom, stopReasonError, withPartialText, sanitizeProfile, GUIDANCE_PREFIX, assertHardLimits, computeContinuableAllow, pruneBlocks, assertResultSchemaConsistency } from './lib/pure.mjs';
 
 export const name = 'dsh-subagent-profile';
 export const inject = ['subagents', 'tools', 'agents'];
@@ -196,67 +196,52 @@ function persistEnabled(enabled) {
 
 // --- module-level helpers (kept inline; the packages do not export them) ---
 
-function textFrom(blocks) {
-  return (Array.isArray(blocks) ? blocks : [])
-    .filter((block) => block && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
-    .map((block) => block.text)
-    .join('');
-}
-
-// Shipped toStopReason: map a turn-end reason to the seam's terminal vocabulary.
-function toStopReason(reason) {
-  switch (reason?.kind) {
-    case 'completed': return 'completed';
-    case 'max-tokens': return 'max-tokens';
-    case 'aborted': return 'aborted';
-    case 'blocked': return 'refusal';
-    default: return 'error';
-  }
-}
+// F5: runtime-derived cost guard. Two parts (SPEC §7.3):
+//   ① always-on hard caps (assertHardLimits, in lib/pure.mjs) — maxTokens /
+//      maxDepth are hard delegation caps, independent of the `llm` service, so
+//      they must NOT stop applying when `llm` is absent (the old `if (llm ===
+//      undefined) return` skipped them).
+//   ② llm capability — validates provider / model / reasoningEffort against the
+//      live provider directory. When the `llm` service is absent OR its provider
+//      directory is empty (an adapter without discovery), capability cannot be
+//      verified: per `allowFailOpen` (SPEC §12.1 migration switch) either
+//      fail-open compat (warn + skip; v1 数据迁移中) or fail-loud reject. A
+//      profile that requests none of provider/model/reasoningEffort has nothing
+//      to verify and always passes (valid in a headless deployment).
+// Used by both the provider's authoritative check and the dispatch tool's
+// pre-check. `allowFailOpen`/`logger` are injected because this function is
+// module-scoped and cannot reach the apply closure's `allowFailOpen`/`ctx.logger`.
+async function assertCostGuard(parent, profile, allowFailOpen, logger) {
+  // ① 硬上限 always-on（不依赖 llm）。
+  assertHardLimits(profile.maxTokens, profile.maxDepth);
 
-// readResult: shipped shape. The terminal turn reason comes from the imported
-// foldConsumedWork; the selected output comes from the imported
-// finalAssistantOutput (last non-empty assistant message, else joined
-// text-delta chunks, else undefined -> []).
-function readResult(child, boundary, cancelled) {
-  const own = child.session.events.slice(boundary);
-  const end = foldConsumedWork(own).end;
-  const recorded = toStopReason(end?.data.reason);
-  const stopReason = cancelled && recorded !== 'completed' ? 'aborted' : recorded;
-  return { output: finalAssistantOutput(own) ?? [], stopReason };
-}
+  // ② 仅当 profile 请求了需核验能力面的字段时才进入 llm 校验（无头/headless 部署下
+  //    persona-only / toolFilter-only 的 profile 合法，不应被 fail-loud 拒绝）。
+  const needsLlm = ['provider', 'model', 'reasoningEffort'].some(
+    (key) => typeof profile[key] === 'string' && profile[key].length > 0
+  );
+  if (!needsLlm) return;
 
-// Shipped stopReasonError + withPartialText wording (dsh-tool-subagent L55-75).
-function stopReasonError(result) {
-  switch (result.stopReason) {
-    case 'completed': return;
-    case 'aborted': return 'dispatch: subagent run was cancelled';
-    case 'error': return 'dispatch: subagent run failed';
-    case 'max-tokens': return 'dispatch: subagent run hit its token limit before finishing';
-    case 'refusal': return 'dispatch: subagent declined the task';
-    default: return `dispatch: subagent run ended abnormally (${String(result.stopReason)})`;
+  const llm = parent.ctx.get('llm');
+  // ③ 目录为空检测：llm 存在但其 provider 目录为空（无发现能力）→ 无法核验。
+  let emptyDirectory = false;
+  if (llm !== undefined) {
+    try {
+      const providers = await llm.listProviders();
+      emptyDirectory = (providers ?? []).length === 0;
+    } catch {
+      emptyDirectory = true;
+    }
+  }
+  if (llm === undefined || emptyDirectory) {
+    if (allowFailOpen === true) {
+      logger.warn('llm 不可用：fail-open 兼容模式（v1 数据迁移中，建议保存一次配置以升级到 fail-loud）');
+      return;
+    }
+    throw new Error('dispatch: 模型能力不可验证：fail-loud 拒绝（可在配置中显式开启兼容模式）');
   }
-}
-
-function withPartialText(error, output) {
-  const text = (Array.isArray(output) ? output : [])
-    .filter((block) => block && block.type === 'text')
-    .map((block) => block.text)
-    .join('');
-  return text.length === 0 ? error : `${error}\nPartial output before the run ended:\n${text}`;
-}
-
-// F5: conservative delegation caps for maxTokens / maxDepth.
-const MAX_TOKENS = 65536;
-const MAX_DEPTH = 3;
 
-// F5: runtime-derived cost guard. Reads the optional `llm` service (undefined =>
-// guard skipped) and validates provider / model / reasoningEffort against the
-// live provider directory, plus the maxTokens/maxDepth caps. Used by both the
-// provider's authoritative check and the dispatch tool's pre-check.
-async function assertCostGuard(parent, profile) {
-  const llm = parent.ctx.get('llm');
-  if (llm === undefined) return;
+  // ④ provider 注册校验（目录非空时才能判定「不在目录」）。
   if (typeof profile.provider === 'string' && profile.provider.length > 0) {
     const providers = await llm.listProviders();
     if (!(providers ?? []).some((provider) => provider && provider.id === profile.provider)) {
@@ -265,13 +250,14 @@ async function assertCostGuard(parent, profile) {
   }
   const effectiveProvider = profile.provider !== undefined ? profile.provider : parent.options.provider;
   const effectiveModel = profile.model !== undefined ? profile.model : parent.options.model;
+  // ⑤ model 校验。resolveModelInfo does not reject unknown models (catalog
+  //    membership is advisory), so validate against the advertised catalog
+  //    instead. An EMPTY catalog (adapter without discovery) cannot be verified
+  //    and is skipped — 目录级空集已在 ③ 走 allowFailOpen 分支，此处仅兜底
+  //    per-provider 空目录。A non-empty catalog that does not advertise the model
+  //    fails loud. An unverifiable lookup (listModels(undefined) when no provider
+  //    is known) becomes a clean fail-loud error instead of leaking "undefined".
   if (typeof profile.model === 'string' && profile.model.length > 0) {
-    // resolveModelInfo does not reject unknown models (catalog membership is
-    // advisory), so validate against the advertised catalog instead. An EMPTY
-    // catalog (adapter without discovery) cannot be verified and is skipped; a
-    // non-empty catalog that does not advertise the model fails loud. An
-    // unverifiable lookup (listModels(undefined) when no provider is known)
-    // becomes a clean fail-loud error instead of leaking "undefined".
     let models;
     try {
       models = await llm.listModels(effectiveProvider);
@@ -280,12 +266,11 @@ async function assertCostGuard(parent, profile) {
     }
     const listed = models ?? [];
     const known = listed.length > 0 && listed.some((model) => model && (model.id === profile.model || model.name === profile.model));
-    // Throw only when the catalog is non-empty AND the model is not in it; an
-    // empty catalog (adapter without discovery) is skipped, not rejected.
     if (listed.length > 0 && !known) {
       throw new Error(`dispatch: model "${profile.model}" is not advertised by provider "${String(effectiveProvider)}"`);
     }
   }
+  // ⑥ reasoningEffort 校验。
   if (typeof profile.reasoningEffort === 'string' && profile.reasoningEffort.length > 0) {
     try {
       await llm.resolveCallConfig({ provider: effectiveProvider, model: effectiveModel, reasoningEffort: profile.reasoningEffort });
@@ -293,19 +278,17 @@ async function assertCostGuard(parent, profile) {
       throw new Error(`dispatch: reasoningEffort "${profile.reasoningEffort}" is not supported by provider "${String(effectiveProvider)}" model "${String(effectiveModel)}": ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  if (typeof profile.maxTokens === 'number' && profile.maxTokens > MAX_TOKENS) {
-    throw new Error(`dispatch: maxTokens ${profile.maxTokens} exceeds the delegation cap ${MAX_TOKENS}`);
-  }
-  if (typeof profile.maxDepth === 'number' && profile.maxDepth > MAX_DEPTH) {
-    throw new Error(`dispatch: maxDepth ${profile.maxDepth} exceeds the delegation cap ${MAX_DEPTH}`);
-  }
 }
 
 // Settle one background one-shot run into a job outcome with the same
 // observability metadata the foreground path reports. Non-completed stop reasons
 // become failed (aborted => killed, shipped vocabulary) with partial output
 // attached; hard failures never reject the job.
-async function settleStart(start, signal, meta) {
+// `prune` is the result-recycle pre-clipper (§8.2): the caller (dispatch
+// execute) injects a closure that calls the host toolResultPruner.pruneContent
+// before textFrom; defaulting to identity keeps the background path safe when no
+// pruner is available.
+async function settleStart(start, signal, meta, prune = (blocks) => blocks) {
   let run;
   try {
     run = await start;
@@ -314,7 +297,7 @@ async function settleStart(start, signal, meta) {
     if (failure !== undefined) {
       return { status: result.stopReason === 'aborted' ? 'killed' : 'failed', detail: withPartialText(failure, result.output), ...meta };
     }
-    return { status: 'completed', output: textFrom(result.output), ...meta };
+    return { status: 'completed', output: textFrom(prune(result.output)), ...meta };
   } catch (error) {
     return signal.aborted ? { status: 'killed', ...meta } : { status: 'failed', detail: String(error), ...meta };
   } finally {
@@ -460,32 +443,73 @@ export async function apply(ctx) {
   // add/remove HTTP routes rewrite the file. Persistence is an enhancement, not
   // a hard dependency: any failure only warns and the builtin seeds work.
   const profilesFile = join(dshHome(), 'subagent-profiles.json');
+  // V2 migration switch (SPEC §7.3 / §12.1): whether the cost guard may fail-open
+  // when the `llm` service is absent. Defaults to FALSE (fail-loud, SPEC §7.3
+  // 评审遗留裁定: 全新部署 fail-loud); only a v1 data file being read sets it to
+  // true (v1 迁移 fail-open 兼容). A v2 envelope carries its own stored value.
+  // Task 4 (cost-guard narrow) reads this flag.
+  let allowFailOpen = false;
   function loadProfiles() {
     if (!existsSync(profilesFile)) return;
     try {
       const parsed = JSON.parse(readFileSync(profilesFile, 'utf8'));
-      if (!Array.isArray(parsed)) return;
+      // Two file shapes (SPEC §12.1): v1 = a bare array; v2 = { version:2,
+      // profiles:[...], allowFailOpen:<bool> }.
+      let entries;
+      let version;
+      if (Array.isArray(parsed)) {
+        entries = parsed;
+        version = 1;
+      } else if (parsed !== null && typeof parsed === 'object' && Array.isArray(parsed.profiles)) {
+        entries = parsed.profiles;
+        version = parsed.version ?? 2;
+        // v2 缺 allowFailOpen 字段时按 fail-open 兼容（显式 false 才关闭）；
+        // 全新部署默认已定：fail-loud（初始 allowFailOpen=false，见上方声明），
+        // 读入 v2 文件按其存储值读取并保持。
+        allowFailOpen = parsed.allowFailOpen !== false;
+      } else {
+        ctx.logger.warn('[dsh-subagent-profile] persisted profile file has an unrecognized shape; ignoring');
+        return;
+      }
+      // v1 (or an unversioned array): migrate in memory, keep fail-open compat.
+      if (version !== 2) {
+        allowFailOpen = true;
+        ctx.logger.warn('[dsh-subagent-profile] v1 数据：fail-open 兼容模式');
+      }
       let loaded = 0;
-      for (const entry of parsed) {
-        if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) continue;
-        if (entry.deleted === true) {
-          if (entry.builtin === true) {
-            profiles.delete(entry.id);
-            deletedBuiltins.add(entry.id);
+      let skipped = 0;
+      for (const raw of entries) {
+        if (!raw || typeof raw !== 'object' || typeof raw.id !== 'string' || raw.id.length === 0) {
+          skipped++;
+          ctx.logger.warn('[dsh-subagent-profile] skipping malformed profile entry:', raw === null ? String(raw) : typeof raw);
+          continue;
+        }
+        // Per-entry sanitize (strict=false): over-limit fields are dropped
+        // (field removed) + warned; an over-length persona is KEPT + warned
+        // (never silently truncated). A bad entry is skipped (fail-soft).
+        const { clean, warnings } = sanitizeProfile(raw, { strict: false });
+        for (const warning of warnings) {
+          ctx.logger.warn(`[dsh-subagent-profile] profile "${raw.id}" ${warning.field} 被跳过或提示：${warning.reason}`);
+        }
+        if (clean.deleted === true) {
+          if (clean.builtin === true) {
+            profiles.delete(clean.id);
+            deletedBuiltins.add(clean.id);
           }
           continue;
         }
-        const existing = profiles.get(entry.id);
+        const existing = profiles.get(clean.id);
         if (existing !== undefined && existing.builtin === true) {
-          profiles.set(entry.id, { ...entry, builtin: true, persisted: true });
+          profiles.set(clean.id, { ...clean, builtin: true, persisted: true });
         } else {
-          profiles.set(entry.id, { ...entry, persisted: true });
+          profiles.set(clean.id, { ...clean, persisted: true });
         }
         loaded++;
       }
       // Silent success: report how many persisted profiles came in (skipped
       // when none — a missing/empty file is the normal first boot).
       if (loaded > 0) ctx.logger.info(`[dsh-subagent-profile] loaded ${loaded} persisted profile(s)`);
+      if (skipped > 0) ctx.logger.warn(`[dsh-subagent-profile] skipped ${skipped} malformed profile entry(ies)`);
     } catch (error) {
       ctx.logger.warn('[dsh-subagent-profile] persisted profile load failed:', error instanceof Error ? error.message : String(error));
     }
@@ -507,25 +531,40 @@ export async function apply(ctx) {
     ctx.logger.warn('[dsh-subagent-profile] preset sync failed:', error instanceof Error ? error.message : String(error));
   }
 
-  /** Persist every `persisted: true` profile plus builtin-delete tombstones — fail-soft. */
+  /**
+   * Persist every `persisted: true` profile plus builtin-delete tombstones.
+   * Atomic write (SPEC §12.2): write `<profilesFile>.tmp` in the same directory,
+   * then `renameSync` over the target (a crash leaves the old file intact, never
+   * a truncated one). Fail-visible (D5/B1): a failure does NOT throw and does NOT
+   * roll back the in-memory `profiles` Map — it returns `{ persisted: false }` so
+   * the caller can signal "已保存但未持久化" while the in-memory state keeps
+   * driving this process. Always writes the v2 envelope shape.
+   */
   function persistProfiles() {
-    try {
-      const entries = [];
-      for (const profile of profiles.values()) {
-        if (profile.persisted !== true) continue;
-        const clean = {};
-        for (const [key, value] of Object.entries(profile)) {
-          if (value === undefined || key === 'persisted') continue;
-          clean[key] = value;
-        }
-        entries.push(clean);
-      }
-      for (const id of deletedBuiltins) {
-        entries.push({ id, builtin: true, deleted: true });
+    const entries = [];
+    for (const profile of profiles.values()) {
+      if (profile.persisted !== true) continue;
+      const clean = {};
+      for (const [key, value] of Object.entries(profile)) {
+        if (value === undefined || key === 'persisted') continue;
+        clean[key] = value;
       }
-      writeFileSync(profilesFile, JSON.stringify(entries, null, 2), 'utf8');
+      entries.push(clean);
+    }
+    for (const id of deletedBuiltins) {
+      entries.push({ id, builtin: true, deleted: true });
+    }
+    const payload = { version: 2, profiles: entries, allowFailOpen };
+    const tmp = `${profilesFile}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+      renameSync(tmp, profilesFile);
+      return { persisted: true };
     } catch (error) {
+      // Best-effort cleanup of the partial tmp file (rename never ran).
+      try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
       ctx.logger.warn('[dsh-subagent-profile] persisted profile write failed:', error instanceof Error ? error.message : String(error));
+      return { persisted: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
 
@@ -553,6 +592,16 @@ export async function apply(ctx) {
       });
       req.on('error', reject);
     });
+    // D5/B1 write-failure contract: the write routes return HTTP 200 with
+    // `persisted` always present; when the disk write failed, persistWarning
+    // explains "已保存但未持久化" (in-memory state drives this process, the
+    // disk did not update). The client renders that as the amber warning.
+    const persistOk = (res, payload, persist) => json(res, 200, {
+      ok: true,
+      ...payload,
+      persisted: persist.persisted,
+      ...(persist.persisted ? {} : { persistWarning: '已保存但未持久化' }),
+    });
     const listClean = () => [...profiles.values()].map((profile) => {
       const clean = {};
       for (const [key, value] of Object.entries(profile)) if (value !== undefined && key !== 'persisted') clean[key] = value;
@@ -677,32 +726,44 @@ export async function apply(ctx) {
           if (typeof profile.id !== 'string' || profile.id.length === 0) {
             return json(res, 400, { ok: false, error: 'subagent-profiles: profile id must be a non-empty string' });
           }
-          const existing = profiles.get(profile.id);
-          const seed = BUILTIN_SEEDS.find((s) => s.id === profile.id);
+          // 写路径上限（SPEC §7.2）：strict=true —— 超限/非法字段直接 400 拒绝，
+          // 与 loadProfiles（strict=false 迁移宽松读取）的行为区分。列被拒字段与中文原因。
+          const { clean, warnings } = sanitizeProfile(profile, { strict: true });
+          if (warnings.length > 0) {
+            const detail = warnings.map((w) => `${w.field}：${w.reason}`).join('；');
+            return json(res, 400, { ok: false, error: `写入被拒绝：${detail}` });
+          }
+          const hadToolFilter = profile.toolFilter !== undefined;
+          const existing = profiles.get(clean.id);
+          const seed = BUILTIN_SEEDS.find((s) => s.id === clean.id);
           const isBuiltin = (existing !== undefined && existing.builtin === true) || seed !== undefined;
           // Merge (not replace): start from the existing profile — or its seed
           // when it was deleted — so fields not present in the form (e.g. a
-          // builtin's persona/preset) survive an edit or a re-add.
-          const clean = { ...(existing ?? seed ?? {}) };
-          clean.id = profile.id;
+          // builtin's persona/preset) survive an edit or a re-add. `clean` is the
+          // sanitized request body, so a field absent from the request is absent
+          // from clean and the existing value is preserved (merge semantics).
+          const merged = { ...(existing ?? seed ?? {}) };
+          merged.id = clean.id;
           for (const key of ['name', 'description', 'preset', 'provider', 'model', 'reasoningEffort', 'persona', 'enabled']) {
-            if (profile[key] === undefined) continue;       // 未传：保留 existing 原值
-            if (profile[key] === '' || profile[key] === null) { delete clean[key]; continue; }  // 空：清除字段
-            clean[key] = profile[key];
+            if (clean[key] === undefined) continue;       // 未传：保留 existing 原值
+            if (clean[key] === '' || clean[key] === null) { delete merged[key]; continue; }  // 空：清除字段
+            merged[key] = clean[key];
           }
-          // toolFilter 特殊处理：前端改成多选下拉后总是传数组，空数组 = 清除
-          if (profile.toolFilter !== undefined) {
-            const tf = profile.toolFilter;
-            const allow = Array.isArray(tf.allow) ? tf.allow.map((s) => String(s).trim()).filter(Boolean) : [];
-            const deny = Array.isArray(tf.deny) ? tf.deny.map((s) => String(s).trim()).filter(Boolean) : [];
-            if (allow.length > 0 || deny.length > 0) clean.toolFilter = { ...(allow.length > 0 ? { allow } : {}), ...(deny.length > 0 ? { deny } : {}) };
-            else delete clean.toolFilter;
+          // toolFilter 特殊处理：前端改成多选下拉后总是传数组，空数组 = 清除。
+          // 请求未传 toolFilter 时保留 existing 原值（merge 语义）；传了但被
+          // sanitize 归一为空（如 allow/deny 均空）则清除。
+          if (hadToolFilter) {
+            const tf = clean.toolFilter;
+            if (tf !== undefined && ((Array.isArray(tf.allow) && tf.allow.length > 0) || (Array.isArray(tf.deny) && tf.deny.length > 0))) {
+              merged.toolFilter = { ...(Array.isArray(tf.allow) && tf.allow.length > 0 ? { allow: tf.allow } : {}), ...(Array.isArray(tf.deny) && tf.deny.length > 0 ? { deny: tf.deny } : {}) };
+            } else {
+              delete merged.toolFilter;
+            }
           }
-          if (clean.enabled !== undefined) clean.enabled = clean.enabled === false ? false : true;
-          profiles.set(profile.id, { ...clean, ...(isBuiltin ? { builtin: true } : {}), persisted: true });
-          deletedBuiltins.delete(profile.id);
-          persistProfiles();
-          return json(res, 200, { ok: true, id: profile.id });
+          if (merged.enabled !== undefined) merged.enabled = merged.enabled === false ? false : true;
+          profiles.set(merged.id, { ...merged, ...(isBuiltin ? { builtin: true } : {}), persisted: true });
+          deletedBuiltins.delete(merged.id);
+          return persistOk(res, { id: merged.id }, persistProfiles());
         }
         if (req.method === 'POST' && sub === '/remove') {
           const body = await readBody(req);
@@ -713,8 +774,7 @@ export async function apply(ctx) {
           }
           profiles.delete(id);
           if (existing.builtin === true) deletedBuiltins.add(id);
-          persistProfiles();
-          return json(res, 200, { ok: true, id });
+          return persistOk(res, { id }, persistProfiles());
         }
         if (req.method === 'POST' && sub === '/reset') {
           const body = await readBody(req);
@@ -725,16 +785,14 @@ export async function apply(ctx) {
           }
           profiles.set(id, { ...seed });
           deletedBuiltins.delete(id);
-          persistProfiles();
-          return json(res, 200, { ok: true, id });
+          return persistOk(res, { id }, persistProfiles());
         }
         if (req.method === 'POST' && sub === '/reset-all') {
           for (const seed of BUILTIN_SEEDS) {
             profiles.set(seed.id, { ...seed });
             deletedBuiltins.delete(seed.id);
           }
-          persistProfiles();
-          return json(res, 200, { ok: true, count: BUILTIN_SEEDS.length });
+          return persistOk(res, { count: BUILTIN_SEEDS.length }, persistProfiles());
         }
         if (req.method === 'POST' && sub === '/set-profile-enabled') {
           const body = await readBody(req);
@@ -747,12 +805,13 @@ export async function apply(ctx) {
           // Persist unconditionally (not just for builtins): a runtime-registered
           // profile's enable/disable must also survive a restart.
           existing.persisted = true;
-          persistProfiles();
-          return json(res, 200, { ok: true, id, enabled: existing.enabled });
+          return persistOk(res, { id, enabled: existing.enabled }, persistProfiles());
         }
         json(res, 404, { ok: false, error: `未知路由 ${sub}` });
       } catch (error) {
-        json(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) });
+        // 通用 500 不回显内部错误信息（防泄漏），详情只进宿主日志。
+        ctx.logger.error('[dsh-subagent-profile] settings route error:', error instanceof Error ? (error.stack ?? error.message) : String(error));
+        json(res, 500, { ok: false, error: '内部错误，详情见宿主日志' });
       }
     };
     scope.effect(() => {
@@ -792,23 +851,79 @@ export async function apply(ctx) {
   // section `text` accepts a function, as the shipped tool-subagent proves).
   const pluginSystemPrompt = ctx.get('systemPrompt');
   if (pluginSystemPrompt !== undefined) {
+    // §8.1 系统提示门控：两段 profile-mode section **只在当前席 Agent 是编排者
+    // 预设（orchestrator）**时注入，从而消除从 standard/code/minimal 等不派发
+    // 会话上的每请求固定泄漏。
+    //
+    // —— 门控判据（以源码为准确认，见 test/README.md）——
+    // 主判据（preset 特征）：`composedPreset(agentCtx) === 'orchestrator'`。这是
+    // 判别「是否编排者会话」的可靠信号：dispatch 工具由本 host 行注册、经
+    // dsh-tools `schemas(scope)` 的 global 继承起点对**每个** agent 恒可见，因此
+    // 「schemas(agent) 含 dispatch」在宿主架构下恒真，**不能**作为主判据（规格
+    // 评审意见：schemas 判据降为否决）。
+    // 否决（防御，防假阳性）：若 `schemas(agent)` **明确不含** dispatch → 必空。
+    // 生产环境恒含 dispatch（host-global），此否决在正常路径不触发；它只防御任何
+    // 让 dispatch 从 agent 视野消失的宿主行为。
+    // 回退：拿不到 agentPresets（composedPreset 不可用）时无法判别当前 Agent 的
+    // 组成，保守不注入（无泄漏风险）。
+    //
+    // section.text(context) 由宿主以 assembleContextFor(agent, signal) =
+    // { agent, scope: agent, signal } 调用（@deepseek-ai/dsh-agent），因此 text()
+    // 能拿到 context.agent；Agent 实例带 .ctx（dsh-agent-presets 的
+    // composedPreset(agentCtx) 正以 agentCtx 作为期望入参），故主判据优先取
+    // context.agent.ctx。
+    const sectionGatePasses = (context) => {
+      if (!enabled) return false;
+      // 否决（防御性）：schemas(agent) 明确不含 dispatch → 必空。
+      if (context !== undefined && context.agent !== undefined) {
+        const schemas = ctx.tools.schemas(context.agent);
+        if (Array.isArray(schemas) && !schemas.some((s) => s && s.name === 'dispatch')) {
+          return false;
+        }
+      }
+      // 主判据：preset 特征 —— composedPreset(agentCtx) === 'orchestrator'。
+      const agentPresets = ctx.get('agentPresets');
+      if (agentPresets !== undefined && typeof agentPresets.composedPreset === 'function') {
+        const agentCtx = context !== undefined && context.agent !== undefined && context.agent.ctx !== undefined
+          ? context.agent.ctx
+          : ctx;
+        try { return agentPresets.composedPreset(agentCtx) === 'orchestrator'; }
+        catch { return false; }
+      }
+      // 无 agentPresets → 无法判别 → 保守不注入。
+      return false;
+    };
     pluginSystemPrompt.section({
       name: 'dispatch:profiles',
       order: 116.5,
-      text: () => {
-        if (!enabled) return '';
+      text: (context) => {
+        if (!sectionGatePasses(context)) return '';
         const rows = [...profiles.values()]
           .filter((p) => p.enabled !== false)
-          .map((p) => `- ${p.id}: ${p.description}${p.preset !== undefined ? ` (preset: ${p.preset})` : ''}`);
-        return rows.length === 0 ? '' : `Available dispatch profiles (dispatch.profile):\n${rows.join('\n')}`;
+          .map((p) => {
+            // 引号引用：description 套引号；为空时显示占位符（不套引号）。压平
+            // 在存储层完成（sanitizeProfile），此处仅负责显示层包裹。
+            const desc = typeof p.description === 'string' && p.description.length > 0 ? `"${p.description}"` : '(无描述)';
+            return `- ${p.id}: ${desc}${p.preset !== undefined ? ` (preset: ${p.preset})` : ''}`;
+          });
+        if (rows.length === 0) return '';
+        // §8.3 一行行为规则（进门控 profiles section，非常开 persona）：用相对
+        // 锚点降低「几分钟内可自查完的小任务」被派发的概率（SPEC §8.1 残留分歧
+        // 已定：行为规则注入点取门控 profiles section）。
+        const note = '- 别把 1-2 步即可自查/可搜完的小事委派出去 —— 几分钟内能自查完的直接做。';
+        return `Available dispatch profiles (dispatch.profile):\n${rows.join('\n')}\n${note}`;
       }
     });
     // Announce the self-installed orchestrator preset so the current agent
-    // knows the mode exists and can point the user to it.
+    // knows the mode exists and can point the user to it. §8.1: gated the same
+    // way — only a dispatch-capable agent sees it.
     pluginSystemPrompt.section({
       name: 'orchestrator:mode',
       order: 117,
-      text: '本机已安装 dsh-subagent-profile 插件的「编排者模式」agent preset：新建会话的预设选择器中可选「编排者模式」。该模式把 Agent 定位为主协调者——拆解任务后按场景用 dispatch（内置 swap-standard=标准编码、researcher=调研检索，可在「子 Agent 方案」设置页自定义）与 subagent/subagent_fork/workflow 委派给子 Agent，再整合结果。preset 文件由插件维护于 ~/.dsh/.agent-presets，安装/升级时自动同步；用户提到「编排者模式 / orchestrator / 主协调模式」时即指本预设，请据此协作。'
+      text: (context) => {
+        if (!sectionGatePasses(context)) return '';
+        return '本机已安装 dsh-subagent-profile 插件的「编排者模式」agent preset：新建会话的预设选择器中可选「编排者模式」。该模式把 Agent 定位为主协调者——拆解任务后按场景用 dispatch（内置 swap-standard=标准编码、researcher=调研检索，可在「子 Agent 方案」设置页自定义）与 subagent/subagent_fork/workflow 委派给子 Agent，再整合结果。preset 文件由插件维护于 ~/.dsh/.agent-presets，安装/升级时自动同步；用户提到「编排者模式 / orchestrator / 主协调模式」时即指本预设，请据此协作。';
+      }
     });
   }
 
@@ -836,8 +951,9 @@ export async function apply(ctx) {
       if (typeof profile.preset === 'string' && profile.preset !== 'inherit' && !whitelist.has(profile.preset)) {
         throw new Error(`dispatch: preset "${profile.preset}" is not in the target-preset whitelist`);
       }
-      // F5: authoritative cost guard (runtime-derived; skipped when llm is absent).
-      await assertCostGuard(parent, profile);
+      // F5: authoritative cost guard (runtime-derived; hard caps always applied,
+      // llm capability gated by allowFailOpen — SPEC §7.3).
+      await assertCostGuard(parent, profile, allowFailOpen, ctx.logger);
       // Delegation depth: shipped helpers — assert the cap value, then resolve
       // the child depth (parent floor + 1) and enforce the cap.
       assertSubagentMaxDepth(profile.maxDepth);
@@ -924,9 +1040,16 @@ export async function apply(ctx) {
           if (systemPrompt !== undefined) {
             systemPrompt.context({ name: 'subagent:delegation', order: 120, text: DELEGATION_CONTEXT });
           }
-          // ④ Persona shadow (overrides deployment:persona at order 0).
+          // ④ Persona shadow (overrides deployment:persona at order 0). The
+          // guidance marker is prefixed when the persona is non-empty (双防线):
+          // the injected text is `${GUIDANCE_PREFIX}${persona}`, exactly the
+          // length the sanitizeProfile cap validates (wrappedLength).
           if (profile.persona !== undefined && systemPrompt !== undefined) {
-            systemPrompt.section({ name: 'deployment:persona', order: 0, text: profile.persona });
+            systemPrompt.section({
+              name: 'deployment:persona',
+              order: 0,
+              text: profile.persona.length > 0 ? `${GUIDANCE_PREFIX}${profile.persona}` : profile.persona,
+            });
           }
           // ⑤ Reasoning-effort injection into every child request.
           if (profile.reasoningEffort !== undefined) {
@@ -1004,7 +1127,7 @@ export async function apply(ctx) {
   //    runtime (disappearing from the model's tool list) without a restart.
   const dispatchTool = defineTool({
     name: 'dispatch',
-    description: 'Dispatch a subtask to a derived subagent, optionally overriding its preset, model, provider, reasoning effort, persona, tool whitelist, token budget, or recursion depth. Foreground waits for the result; run_in_background: true starts a background job (single turn); continuable: true starts a durable subagent whose conversation stays available for later turns via the send_message tool.',
+    description: 'Dispatch a subtask to a derived subagent, optionally overriding its preset, model, provider, reasoning effort, persona, tool whitelist, token budget, or recursion depth. Foreground waits for the result; run_in_background: true starts a background job (single turn); continuable: true starts a durable subagent whose conversation stays available for later turns via the send_message tool. 前瞻：continuable 模式忽略 preset 换用与 reasoningEffort（结果以 ignored 提示）。',
     parameters: {
       profile: { type: 'string', description: 'Optional profile id from the profile registry (built-ins: swap-standard, researcher, plus any you define in the settings page); omit to inherit the parent preset and tools as-is.' },
       preset: { type: 'string', description: 'Explicit target preset override; must be a system-trust preset of this runtime.' },
@@ -1028,6 +1151,10 @@ export async function apply(ctx) {
       maxDepth: { type: 'number', description: 'Absolute delegation-depth cap for this child.' },
       run_in_background: { type: 'boolean', description: '异步 one-shot：走 jobs.start 包 start()，返回 jobId；仍单轮即弃，非 continuable' },
       continuable: { type: 'boolean', description: 'Start a durable continuable subagent instead of a one-shot: returns a subagentId immediately and keeps the child conversation available for later turns via the send_message tool. Defaults to false.' },
+      // §8.2 信封模式 = opt-in（仅「中段即交付物」的任务用）。首切片**仅预留**：
+      // 工具 schema 暴露此参数作字段契约，execute 当前不消费它（结构化信封回收
+      // 在 V2.0-中期启用）。见 execute 内注释。
+      envelope: { type: 'boolean', description: '预留：结构化信封回收（V2.0 中期启用，当前不生效）' },
       prompt: { type: 'string', required: true, description: 'The complete, self-contained task for the child (it does not see this conversation).' }
     },
     output: {
@@ -1035,6 +1162,10 @@ export async function apply(ctx) {
         // D: observability metadata on every result. OneOf covers the
         // background variant (kind/jobId) and the foreground variant (output),
         // both closed and both carrying the effective delegation values.
+        // R1: `ignored` was added to ALL three branches (with the shared `preset`
+        // / `provider` / `model` / `reasoningEffort` / `profile`), keeping the
+        // closed oneOf consistent — assertResultSchemaConsistency(dispatchTool
+        // .output.schema) in apply() fires if any 分支 忘补该字段.
         oneOf: [
           {
             type: 'object',
@@ -1046,7 +1177,8 @@ export async function apply(ctx) {
               preset: { type: 'string' },
               provider: { type: 'string' },
               model: { type: 'string' },
-              reasoningEffort: { type: 'string' }
+              reasoningEffort: { type: 'string' },
+              ignored: { type: 'array', items: { type: 'string' } }
             }
           },
           {
@@ -1059,7 +1191,8 @@ export async function apply(ctx) {
               preset: { type: 'string' },
               provider: { type: 'string' },
               model: { type: 'string' },
-              reasoningEffort: { type: 'string' }
+              reasoningEffort: { type: 'string' },
+              ignored: { type: 'array', items: { type: 'string' } }
             }
           },
           {
@@ -1071,19 +1204,26 @@ export async function apply(ctx) {
               preset: { type: 'string' },
               provider: { type: 'string' },
               model: { type: 'string' },
-              reasoningEffort: { type: 'string' }
+              reasoningEffort: { type: 'string' },
+              ignored: { type: 'array', items: { type: 'string' } }
             }
           }
         ]
       },
-      render: (_args, value) => [{
-        type: 'text',
-        text: value.kind === 'background'
-          ? `[dispatch] background job ${value.jobId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}`
+      render: (_args, value) => {
+        // §8.4: continuable 丢弃 preset 换用与 reasoningEffort —— 渲染行把
+        // `ignored` 列表回显出来（`reasoningEffort=<值>(ignored)`，再加 ignored 项
+        // 明细），让模型「看见」被丢弃项；background/foreground 无忽略项时该后缀为空。
+        const ignored = value.ignored !== undefined && value.ignored.length > 0
+          ? `(ignored: ${value.ignored.join(', ')})`
+          : '';
+        const text = value.kind === 'background'
+          ? `[dispatch] background job ${value.jobId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}`
           : value.kind === 'continuable'
-            ? `[dispatch] started subagent ${value.subagentId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}`
-            : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}\n\n${value.output}`
-      }]
+            ? `[dispatch] started subagent ${value.subagentId} · profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}`
+            : `[dispatch] profile=${value.profile} · preset=${value.preset} · provider=${value.provider} · model=${value.model} · reasoningEffort=${value.reasoningEffort}${ignored}\n\n${value.output}`;
+        return [{ type: 'text', text }];
+      }
     },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
@@ -1107,8 +1247,9 @@ export async function apply(ctx) {
         const parentComposed = parentPresets !== undefined ? parentPresets.composedPreset(parent.ctx) : undefined;
         if (merged.preset === parentComposed) merged.preset = 'inherit';
       }
-      // F5: cost guard (runtime-derived; skipped when llm is absent).
-      await assertCostGuard(parent, merged);
+      // F5: cost guard (runtime-derived; hard caps always applied, llm capability
+      // gated by allowFailOpen — SPEC §7.3).
+      await assertCostGuard(parent, merged, allowFailOpen, ctx.logger);
       // D: effective delegation values for observability.
       const meta = {
         profile: args.profile ?? '(inline)',
@@ -1127,6 +1268,13 @@ export async function apply(ctx) {
         ...(merged.toolFilter !== undefined ? { toolFilter: merged.toolFilter } : {}),
         ...(merged.maxDepth !== undefined ? { maxDepth: merged.maxDepth } : {})
       };
+      // §8.2 结果回收默认剪枝：在 textFrom(result.output) 之前复用宿主
+      // toolResultPruner.pruneContent 预剪。`pruneResultOutput` 每次现取
+      // ctx.get('toolResultPruner') 以反映服务就绪状态；pruner 缺失时
+      // pruneBlocks 回退为不剪（剪枝是增强、非硬依赖）。envelope 参数虽已在
+      // 工具 schema 暴露（预留，V2.0-中期启用结构化信封回收），但 execute
+      // **不消费**它——本首切片只实现「剪枝默认」，不做信封注入。
+      const pruneResultOutput = (blocks) => pruneBlocks(blocks, ctx.get('toolResultPruner'));
       // Decision-level log: resolved effective delegation inputs, after the
       // cost guard and after request assembly, before dispatch.
       ctx.logger.info('[dsh-subagent-profile] dispatch:', JSON.stringify({
@@ -1144,6 +1292,13 @@ export async function apply(ctx) {
       // later turns. Treated first so a caller asking for both background and
       // continuable gets the continuable child.
       if (args.continuable === true) {
+        // 安全 P0-b（SPEC §7.1 第 2 条）：provider `start` 的 !enabled 检查只拦
+        // `start`，不拦 `startContinuable` —— 这里显式补上。当前 syncTool 会在
+        // 禁用时注销 dispatch 工具（间接门），此处是防御性兜底：禁用后
+        // dispatch(continuable:true) 必须 fail-loud，不得静默派生子树。
+        if (!enabled) {
+          throw new Error('dispatch: 插件已禁用（设置 → 子 Agent 方案 重新启用）');
+        }
         if (args.run_in_background === true) {
           ctx.logger.warn('[dsh-subagent-profile] dispatch: both continuable and run_in_background are true; continuable takes precedence');
         }
@@ -1154,28 +1309,55 @@ export async function apply(ctx) {
         if (merged.reasoningEffort !== undefined) {
           ctx.logger.warn(`[dsh-subagent-profile] continuable mode cannot set reasoningEffort; ignoring "${merged.reasoningEffort}"`);
         }
+        // 安全 P0-b（SPEC §7.1 第 1 条）：预加工 toolFilter 为闭集 allow。continuable
+        // 走宿主 applyChildComposition→tools.restrict，prepareContinuable 返回 {}，
+        // 插件侧无法重算父∩子交集，故在此把 allow 预加工为闭集传到 request。
+        //
+        // 假设：continuable 继承父预设（preset swap 被忽略，见上方 warn）⇒
+        // 子工具集 ≈ 父工具集，故 父集 − run_code − deny 可安全作为 restrict 的
+        // allow。失效：任何导致子工具集与父工具集不一致的宿主行为变化（非仅
+        // preset swap——例如未来允许 swap preset、组合不同工具集等），父集都可能
+        // 含子集上不存在之工具 → tools.restrict 会抛「未知工具」→ 本缓解自动降级
+        // 为 fail-loud（保守安全）——此时必须替换为真交集（父∩子）。
+        const parentNames = new Set(parent.ctx.tools.schemas(parent).map((schema) => schema.name));
+        const effectiveAllow = computeContinuableAllow(parentNames, merged.toolFilter);
         const hasAgentOptions = merged.provider !== undefined || merged.model !== undefined || merged.maxTokens !== undefined;
+        const continuableRequest = {
+          prompt: [{ type: 'text', text: args.prompt }],
+          parent,
+          ...(hasAgentOptions ? { agentOptions: {
+            ...(merged.provider !== undefined ? { provider: merged.provider } : {}),
+            ...(merged.model !== undefined ? { model: merged.model } : {}),
+            ...(merged.maxTokens !== undefined ? { maxTokens: merged.maxTokens } : {})
+          } } : {}),
+          ...(merged.persona !== undefined ? { persona: merged.persona } : {}),
+          // 恒传闭集 allow（覆盖原 merged.toolFilter 透传）；空集在
+          // computeContinuableAllow 内 fail-loud。
+          toolFilter: { allow: effectiveAllow },
+          ...(merged.maxDepth !== undefined ? { maxDepth: merged.maxDepth } : {})
+        };
         const { childId } = await ctx.subagents.startContinuable({
           provider: 'profile',
           label: String(args.prompt ?? '').slice(0, 60),
-          request: {
-            prompt: [{ type: 'text', text: args.prompt }],
-            parent,
-            ...(hasAgentOptions ? { agentOptions: {
-              ...(merged.provider !== undefined ? { provider: merged.provider } : {}),
-              ...(merged.model !== undefined ? { model: merged.model } : {}),
-              ...(merged.maxTokens !== undefined ? { maxTokens: merged.maxTokens } : {})
-            } } : {}),
-            ...(merged.persona !== undefined ? { persona: merged.persona } : {}),
-            ...(merged.toolFilter !== undefined ? { toolFilter: merged.toolFilter } : {}),
-            ...(merged.maxDepth !== undefined ? { maxDepth: merged.maxDepth } : {})
-          },
+          request: continuableRequest,
           signal: exec.signal
         });
         // Continuable drops the profile's preset swap and reasoningEffort (the
         // child inherits the parent preset), so the observability meta must
         // report what actually took effect, not the requested-but-ignored values.
-        return { kind: 'continuable', subagentId: childId, profile: meta.profile, preset: 'inherit', provider: meta.provider, model: meta.model };
+        // §8.4 可见性修复：`reasoningEffort` 回显**请求值**（经 meta.reasoningEffort，
+        // 即 merged.reasoningEffort ?? '(default)'），`preset:'inherit'` 是真实生效值；
+        // `ignored` 明确列出被丢弃项，让模型「看见」被忽略的字段。
+        return {
+          kind: 'continuable',
+          subagentId: childId,
+          profile: meta.profile,
+          preset: 'inherit',
+          provider: meta.provider,
+          model: meta.model,
+          reasoningEffort: meta.reasoningEffort,
+          ignored: ['preset', 'reasoningEffort']
+        };
       }
       // A: background one-shot (job) path — jobs.start wraps start() with a
       // native AbortController (a Node global in a bundle; the dynamic-plugin
@@ -1194,7 +1376,7 @@ export async function apply(ctx) {
             const controller = new AbortController();
             return {
               cancel: (reason) => controller.abort(reason ?? 'dispatch: background subagent task killed'),
-              done: settleStart(ctx.subagents.start('profile', { ...request, signal: controller.signal }), controller.signal, meta)
+              done: settleStart(ctx.subagents.start('profile', { ...request, signal: controller.signal }), controller.signal, meta, pruneResultOutput)
             };
           }
         });
@@ -1213,9 +1395,14 @@ export async function apply(ctx) {
       // partial output text (withPartialText style).
       const failure = stopReasonError(result);
       if (failure !== undefined) throw new Error(withPartialText(failure, result.output));
-      return { output: textFrom(result.output), ...meta };
+      return { output: textFrom(pruneResultOutput(result.output)), ...meta };
     }
   });
+  // R1（共享规则）lock: the closed oneOf result schema must carry an identical
+  // shared meta key set across all three branches. Fires only at apply time; a
+  // future meta-field add that forgets one 分支 throws here (once), so the
+  // model-side schema never silently rejects a分支.
+  assertResultSchemaConsistency(dispatchTool.output.schema);
   // Register the tool only while enabled; unregister it the moment the switch
   // turns off so it disappears from the model's tool list without a restart.
   let disposeTool;