dsh-compact-relay 0.3.6 → 0.4.1

package/lib/actions/diagnostics.js

@@ -0,0 +1,130 @@
+/**
+ * 诊断信息动作（dcr 0.4 P0-2）—— HTTP 适配层与（将来的）命令入口共用的唯一组装实现。
+ *
+ * 为什么放在 actions 层：仓库 A9 架构红线是「adapters 不能直接 import dsh/」，
+ * 而诊断产物的构造（白名单裁剪 + 脱敏 + 尺寸上限）在 dsh/diagnostics.js。
+ * 这里只做「取数 + 裁剪」：deps.cfg / settings.view() / readState / deps.diag.snapshot()，
+ * 然后把白名单输入交给 dsh 层构造，适配层只负责协议转换。
+ *
+ * 只读、幂等、无副作用：不写文件、不写日志、不改任何插件状态。
+ */
+import os from 'node:os';
+import { buildDiagnostics, renderIssueUrl } from '../dsh/diagnostics.js';
+import { readState } from './state.js';
+
+/** 运行时环境事实（只取进程/系统信息，不读会话、不读路径）。 */
+function runtimeOf() {
+  let osRelease = null;
+  try {
+    if (typeof os.release === 'function') osRelease = os.release();
+  } catch {
+    osRelease = null;
+  }
+  let locale = null;
+  try {
+    locale = Intl.DateTimeFormat().resolvedOptions().locale;
+  } catch {
+    locale = null;
+  }
+  return {
+    // 现有代码没有稳定的 DSH 版本来源：不猜，保持 null（方案 §4）。
+    dshVersion: null,
+    node: typeof process.version === 'string' ? process.version : null,
+    platform: typeof process.platform === 'string' ? process.platform : null,
+    arch: typeof process.arch === 'string' ? process.arch : null,
+    osRelease,
+    locale,
+  };
+}
+
+/**
+ * 配置白名单：阈值/保留量/超时/颜色 + 两个「是否被用户改过」的布尔。
+ * 交接目录与自定义链接**只出改没改，绝不出值**（方案 §2）。
+ */
+function configOf(deps) {
+  const cfg = deps.cfg !== null && typeof deps.cfg === 'object' ? deps.cfg : {};
+  let view = null;
+  try {
+    view = typeof deps.settings?.view === 'function' ? deps.settings.view() : null;
+  } catch {
+    view = null;
+  }
+  const current = view !== null && view.config !== null && typeof view.config === 'object' ? view.config : null;
+  const defaults = view !== null && view.defaults !== null && typeof view.defaults === 'object' ? view.defaults : null;
+  const changed = (read) => (current === null || defaults === null ? false : read(current) !== read(defaults));
+  const timeouts = cfg.timeouts !== null && typeof cfg.timeouts === 'object' ? cfg.timeouts : {};
+  return {
+    version: view !== null && typeof view.version === 'string' ? view.version : null,
+    config: {
+      thresholds: {
+        compactRatio: cfg.thresholds?.compactRatio,
+        handoffRatio: cfg.thresholds?.handoffRatio,
+        maxSummaries: cfg.thresholds?.maxSummaries,
+      },
+      retention: { recentTailTokens: cfg.retention?.recentTailTokens },
+      // 仓库只有一个模型调用超时（llmMs）；契约的分项字段没有独立来源时复用它。
+      timeouts: {
+        compactMs: timeouts.compactMs ?? timeouts.llmMs,
+        handoffMs: timeouts.handoffMs ?? timeouts.llmMs,
+      },
+      colors: { mode: cfg.colors?.mode, autoAdapt: cfg.colors?.autoAdapt },
+      handoffDirCustomized: changed((value) => value.handoffDir),
+      linksCustomized: changed((value) => `${value.links?.tutorial ?? ''}\u0000${value.links?.feedback ?? ''}`),
+    },
+  };
+}
+
+/** 把 readState 快照裁成契约白名单；无活动会话返回 null（契约里 state 整块 null）。 */
+function stateOf(state) {
+  if (state === null || typeof state !== 'object' || typeof state.sessionId !== 'string') return null;
+  const range = state.compactRange !== null && typeof state.compactRange === 'object' ? state.compactRange : null;
+  const native = state.native !== null && typeof state.native === 'object' ? state.native : null;
+  return {
+    window: state.window,
+    tokens: state.pressure,
+    ratio: state.ratio,
+    summaries: state.summaries,
+    pins: state.pins !== null && typeof state.pins === 'object' ? state.pins.count : state.pins,
+    advice: state.advice,
+    compactRange: range === null ? null : { nodes: range.nodes, tokens: range.tokens },
+    nativeAuto: native === null ? null : { enabled: native.autoEnabled, lineRatio: native.thresholdRatio },
+  };
+}
+
+/**
+ * 组装一份诊断信息（HTTP 端点 / 未来命令入口共用）。
+ *
+ * @param {{ctx:object, cfg:object, settings?:object, diag?:object}} deps
+ * @param {{sessionId?:string}} [input]
+ * @returns {Promise<{schema:string, version:string|null, generatedAt:string, markdown:string, json:object, issueUrl:string}>}
+ */
+export async function readDiagnostics(deps, { sessionId } = {}) {
+  const meta = configOf(deps);
+  const runtime = runtimeOf();
+  // 无活动会话时 readState 仍返回合法对象（sessionId=null）→ 契约里 state 整块 null。
+  let state = null;
+  try {
+    state = stateOf(await readState(deps, { sessionId }));
+  } catch {
+    state = null;
+  }
+  const snapshot = deps.diag?.snapshot?.() ?? {};
+  const built = buildDiagnostics({
+    version: meta.version,
+    runtime,
+    config: meta.config,
+    state,
+    counters: snapshot.counters,
+    latency: snapshot.latency,
+    errors: snapshot.errors,
+  });
+  return {
+    schema: built.json.schema,
+    version: meta.version,
+    generatedAt: built.json.generatedAt,
+    markdown: built.markdown,
+    json: built.json,
+    // issue URL 由宿主拼（短字段），客户端只负责 window.open。
+    issueUrl: renderIssueUrl({ version: meta.version, runtime }),
+  };
+}

package/lib/actions/handoff.js

@@ -18,7 +18,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { actionError } from '../core/errors.js';
+import { pinAnchorOf } from '../core/pin-anchors.js';
 import { handoffFileName, renderHandoffDoc } from '../core/handoff-doc.js';
+import { applyHandoffEdits, editableHandoffView, normalizeHandoffEdits } from '../core/handoff-edit.js';
+import { composeHandoffText } from '../core/handoff-spec.js';
 import { betterCompactLocked } from './better-compact.js';
 import { compressHint, countSummaries, livePinnedSeqs, surfaceSeqs } from '../dsh/session-view.js';
 import { measurePressure } from '../dsh/pressure.js';
@@ -27,6 +30,7 @@ import { generateHandoffDoc } from '../dsh/handoff-writer.js';
 import { buildHandoffProgramSections } from '../core/handoff-facts.js';
 import { checkHandoffReadiness } from '../core/readiness.js';
 import { changedFilesOf } from '../dsh/session-files.js';
+import { errorCodeOf, localIso } from '../dsh/diag-counters.js';
 import { surfaceMessages } from '../dsh/prefix.js';
 import { handoffTitlePlanOf, createHandoffSession, sourceTitleOf } from '../dsh/sessions.js';
 import { writeRelayRecord } from '../dsh/relay.js';
@@ -39,7 +43,8 @@ import { beginInflight, cancelErrorOf, combinedSignal, finishInflight } from './
  */
 async function compactFirst(deps, { agent, signal, commandId, log }) {
   try {
-    return { outcome: await betterCompactLocked(deps, { agent, signal, commandId }), warning: null };
+    // P1-3：交接内部的压缩不单独记账（避免一次 /handoff 记两条）；由交接记录统一反映。
+    return { outcome: await betterCompactLocked(deps, { agent, signal, commandId, ledgerRecord: false }), warning: null };
   } catch (error) {
     const code = error !== null && typeof error === 'object' ? error.code : undefined;
     // 只有「事务开始前/未提交」的失败能降级继续（结构、范围、摘要、内容变化）。
@@ -54,7 +59,7 @@ async function compactFirst(deps, { agent, signal, commandId, log }) {
 
 /**
  * 收集交接单需要的全部会话事实（A1）：压力/现场快照/摘要数/锁定/改过的文件/程序段。
- * @returns {Promise<{session:object, measured:object, now:Date, site:object, summaries:number, pinnedSeqs:number[], changedFiles:string[], programSections:Record<string,string>}>}
+ * @returns {Promise<{session:object, measured:object, now:Date, site:object, summaries:number, pinnedSeqs:number[], pinnedAnchors:Array<{seq:number,role:string,snippet:string}>, changedFiles:string[], programSections:Record<string,string>}>}
  */
 async function collectHandoffFacts(deps, agent) {
   const session = agent.session;
@@ -65,27 +70,63 @@ async function collectHandoffFacts(deps, agent) {
   const site = buildSiteSnapshot({ session, now });
   const summaries = countSummaries(session);
   const pinnedSeqs = livePinnedSeqs(session);
+  // 0.4 P1-2：pin 保留契约锚点 = seq + 角色 + 一句摘要（≤60 字符，不贴原文全文）。
+  const pinnedAnchors = pinnedSeqs
+    .map((seq) => {
+      const event = typeof session.eventAt === 'function' ? session.eventAt(seq) : undefined;
+      return event === undefined || event === null ? null : pinAnchorOf(event);
+    })
+    .filter((anchor) => anchor !== null);
   const changedFiles = changedFilesOf(session);
   const programSections = buildHandoffProgramSections({
     compressHint: compressHint(session),
     summaries,
     pressure: measured.tokens,
-    pins: { count: pinnedSeqs.length, seqs: pinnedSeqs },
+    pins: { count: pinnedSeqs.length, seqs: pinnedSeqs, anchors: pinnedAnchors },
     changedFiles,
     site,
   });
-  return { session, measured, now, site, summaries, pinnedSeqs, changedFiles, programSections };
+  return { session, measured, now, site, summaries, pinnedSeqs, pinnedAnchors, changedFiles, programSections };
 }
 
 /**
+ * 交接新会话（/handoff、菜单「交接新会话」、命令卡）—— 对外入口 = 诊断埋点采集点。
+ *
+ * 0.4 P0-2：只在这里数「交接成功/失败 / 耗时 / 错误码」，失败原因只记 code，
+ * 不记 message（message 可能带交接单路径/会话内容）。行为与文案不变。
+ *
+ * @param {{ctx:object, cfg:object, lock:object, engine:object, log?:object, diag?:object}} deps
+ * @param {{agent:object, signal?:AbortSignal, commandId?:string, edits?:Record<string,string>}} input
+ *   edits 只允许 `{约束?:string, 下一步?:string}`（P2-1；非法字段抛 code='edits'）
+ */
+export async function handoff(deps, { agent, signal, commandId, edits } = {}) {
+  const startedAt = Date.now();
+  try {
+    const outcome = await runHandoff(deps, { agent, signal, commandId, edits });
+    deps.diag?.bumpAction('handoff', true);
+    return outcome;
+  } catch (error) {
+    deps.diag?.bumpAction('handoff', false);
+    deps.diag?.recordError(errorCodeOf(error), 'handoff');
+    throw error;
+  } finally {
+    deps.diag?.recordDuration('handoff', Date.now() - startedAt);
+  }
+}
+
+/**
+ * 交接流程本体。
  * @param {{ctx:object, cfg:object, lock:object, engine:object, log?:object}} deps
  * @param {{agent:object, signal?:AbortSignal, commandId?:string}} input
  */
-export async function handoff(deps, { agent, signal, commandId }) {
+async function runHandoff(deps, { agent, signal, commandId, edits }) {
   if (agent === undefined || agent === null) throw actionError('handoff', '当前没有打开的会话，无法交接');
   const session = agent.session;
   if (session === undefined) throw actionError('handoff', '没有活动会话，无法交接');
 
+  // 0.4 P2-1：先校验用户编辑（只允许「约束」「下一步」），非法字段在压缩/写盘之前就拒绝。
+  const normalizedEdits = normalizeHandoffEdits(edits);
+
   return withLock(deps.lock, agent.id, async () => {
     // P1-4：交接登记进 inflight，client 的取消按钮才能真正 abort 模型调用。
     const controller = beginInflight(deps, agent.id, 'handoff');
@@ -104,6 +145,12 @@ export async function handoff(deps, { agent, signal, commandId }) {
         );
       }
 
+      // 0.4 P1-3：轻账本——先记下「压前占用」（交接内部的压缩会改变之后的压力读数）。
+      const startedAt = Date.now();
+      const beforeMeasured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback }).catch(
+        () => null,
+      );
+
       // 1) 先压缩旧会话一次（best effort）。
       const { outcome: compactOutcome, warning: compactWarning } = await compactFirst(deps, {
         agent,
@@ -129,9 +176,14 @@ export async function handoff(deps, { agent, signal, commandId }) {
       });
       combined?.throwIfAborted?.();
 
+      // 3.2) 0.4 P2-1：套用「约束 / 下一步」两段的用户编辑（预览→确认链路）。
+      // 只覆盖这两段；程序/模型生成的其余七段原样保留（前后端都不接受其它字段）。
+      const editedSections = applyHandoffEdits(generated.sections, normalizedEdits);
+      const editedText = composeHandoffText(editedSections);
+
       // 3.5) 就绪检查：九段缺段/占位阻断；路径核对只警告，不阻断。
       const readiness = checkHandoffReadiness({
-        sections: generated.sections,
+        sections: editedSections,
         surfaceText: JSON.stringify(surfaceMessages(facts.session)),
         changedFiles: facts.changedFiles,
         messageCount: surfaceSeqs(facts.session).length,
@@ -141,10 +193,11 @@ export async function handoff(deps, { agent, signal, commandId }) {
       }
       for (const warning of readiness.warnings) deps.log?.warn?.(`compact-relay: 交接单就绪警告：${warning}`);
 
-      // 4) 写盘：文档头带元信息，九段正文 = 模型 7 段 + 程序 2 段。
+      // 4) 写盘：文档头带元信息，九段正文 = 模型 7 段 + 程序 2 段 + 用户编辑的两段。
+      const titlePlan = handoffTitlePlanOf(deps.ctx, session);
       const file = path.join(deps.cfg.handoffDir, handoffFileName(facts.now));
       const doc = renderHandoffDoc({
-        generated: generated.text,
+        generated: editedText,
         sourceSessionId: facts.session.id,
         sourceTitle: sourceTitleOf(deps.ctx, facts.session),
         now: facts.now,
@@ -154,6 +207,8 @@ export async function handoff(deps, { agent, signal, commandId }) {
         // M6：把「宿主刚重启过 / 工作区分支 / 有没有后台任务在跑」写进文档头，
         // 免得接手者按一份出厂即过时的「下一步」干活。
         site: facts.site,
+        // 0.4 P2-2：文档头直接写「第 N 次交接」，接手者不用解析标题。
+        ordinal: titlePlan.index,
       });
       try {
         fs.writeFileSync(file, doc, 'utf8');
@@ -167,7 +222,6 @@ export async function handoff(deps, { agent, signal, commandId }) {
 
       // 5) 新会话：同工作区 / 同 preset / 同模型，注入交接单并起第一轮。
       //    A5：标题序号优先读父会话里的 relay 记录（不依赖解析标题文案）。
-      const titlePlan = handoffTitlePlanOf(deps.ctx, session);
       let created;
       try {
         created = await createHandoffSession({
@@ -190,13 +244,18 @@ export async function handoff(deps, { agent, signal, commandId }) {
       }
 
       // A5：把接力链写成父会话里的结构化记录；写失败不阻断交接（标题解析仍可兜底）。
+      // 0.4 P2-2：canonical 字段 parentId/childId/ordinal/at/atIso 补齐；旧字段 parentSessionId/index 保留兼容。
+      const relayAt = Date.now();
       const relayWrote = writeRelayRecord(deps.engine, session, {
-        parentSessionId: session.id,
+        parentId: session.id,
         childId: created.childId,
+        ordinal: titlePlan.index,
+        at: relayAt,
+        atIso: localIso(new Date(relayAt)),
+        parentSessionId: session.id,
         index: titlePlan.index,
         path: file,
         planId: compactOutcome?.planId ?? null,
-        at: Date.now(),
         title: titlePlan.title,
         baseTitle: titlePlan.baseTitle,
       });
@@ -219,6 +278,22 @@ export async function handoff(deps, { agent, signal, commandId }) {
               ? `压缩失败已跳过（${briefWarning}）；需要的话可先手动 /bc 再交接；`
               : '';
 
+      // 0.4 P1-3：交接成功记一条轻账本（只记数值/路径；不含消息/摘要/交接单正文）。
+      try {
+        deps.ledger?.record?.({
+          kind: 'handoff',
+          durationMs: Date.now() - startedAt,
+          beforeTokens: beforeMeasured === null ? null : beforeMeasured.tokens,
+          afterTokens: facts.measured.tokens,
+          beforeRatio: beforeMeasured === null ? null : beforeMeasured.ratio,
+          afterRatio: facts.measured.ratio,
+          pinHits: { inRange: compactOutcome?.pinnedKept ?? 0, total: facts.pinnedSeqs.length },
+          handoff: { path: file, childId: created.childId, started: created.started === true },
+        });
+      } catch {
+        /* 账本静默降级：不能影响交接结果 */
+      }
+
       return {
         ok: true,
         childId: created.childId,
@@ -278,6 +353,10 @@ export async function previewHandoff(deps, { agent, signal }) {
   return {
     ok: true,
     draft: generated.text,
+    // 0.4 P2-1：预览里只暴露「约束」「下一步」两段给客户端编辑（其余段不可改）。
+    editable: editableHandoffView(generated.sections),
+    // 0.4 P2-2：本次将是第几次交接（链式序号；首次 1）。
+    ordinal: handoffTitlePlanOf(deps.ctx, session).index,
     readiness,
     pressure: facts.measured.tokens,
     summaries: facts.summaries,

package/lib/actions/pin.js

@@ -10,37 +10,18 @@
  * 只写 plugin record：不进模型上下文、不占 token；压缩选段会避开被锁定的消息。
  */
 import { actionError } from '../core/errors.js';
+import { messageSnippetOf, roleLabelOf } from '../core/pin-anchors.js';
 import { PIN_RECORD_TYPE, latestPinnedSeqs, normalizePinnedSeqs } from '../core/pins.js';
 import { livePinnedSeqs, sessionLog, surfaceSeqs } from '../dsh/session-view.js';
 
-const TYPE_LABEL = {
-  'system/message': '系统',
-  'user/message': '用户',
-  'assistant/message': '助手',
-  'tool/result': '工具',
-};
-
 /**
  * 从事件里抠一段可读预览（消息 content 可能是数组或字符串）。
+ * 0.4 P1-1/P1-2：摘要/角色判定抽到 core/pin-anchors.js，与「建议锁定」「交接单锚点」共用一份。
  * @param {object|undefined} event
  * @returns {string}
  */
 function previewOf(event) {
-  // DSH v4：user/message 的 data 本身就是消息（{role,content,source}），
-  // 只有 system/assistant/tool 包在 data.message 里。2026-10-19 debug 实测：
-  // 只读 data.message 会让 /pin list 里所有用户消息显示「（无文本）」。
-  const content = event?.data?.content ?? event?.data?.message?.content;
-  let text = '';
-  if (typeof content === 'string') text = content;
-  else if (Array.isArray(content)) {
-    text = content
-      .filter((block) => block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
-      .map((block) => block.text)
-      .join(' ');
-  }
-  text = text.replace(/\s+/gu, ' ').trim();
-  if (text.length === 0) return '（无文本）';
-  return text.length > 60 ? `${text.slice(0, 59)}…` : text;
+  return messageSnippetOf(event) || '（无文本）';
 }
 
 /**
@@ -59,7 +40,7 @@ export function pinCandidates(session, limit = 10) {
       index: picked.length + 1,
       seq,
       type: event.type,
-      role: TYPE_LABEL[event.type] ?? '其他',
+      role: roleLabelOf(event.type),
       preview: previewOf(event),
     });
   }
@@ -73,6 +54,8 @@ function pinnedOf(session) {
 function writePins(deps, session, seqs) {
   const normalized = normalizePinnedSeqs(seqs);
   deps.engine.appendPluginRecord(session, PIN_RECORD_TYPE, { seqs: normalized, at: Date.now() });
+  // 0.4 P0-2：诊断计数只记「成功锁定」；/pin 与菜单 toggle 共用这里，toggle 锁一次记一次。
+  if (normalized.length > 0) deps.diag?.bumpPin();
   return normalized;
 }
 

package/lib/actions/state.js

@@ -7,11 +7,12 @@
 import { paletteForBothSchemes } from '../core/colors.js';
 import { adviceFor, ratioOf, thresholdsForWindow } from '../core/policy.js';
 import { tokenOf } from '../core/tokens.js';
-import { measurePressure } from '../dsh/pressure.js';
+import { measurePressure, routeBudgetOf } from '../dsh/pressure.js';
 import { selectCompactableRange } from '../dsh/select-range.js';
 import { compressHint as compressHintOf, countSummaries, lastCheckpointSurfaceSeq, livePinnedSeqs, liveSessionOf, pickAgent, surfaceSeqs } from '../dsh/session-view.js';
 import { compressHintIsActive } from '../core/compress-hint.js';
-import { readNativeCompaction } from '../dsh/native-compaction.js';
+import { readNativeCompaction, resolveNativePolicy } from '../dsh/native-compaction.js';
+import { nativeLineOf } from '../core/native-line.js';
 import { relayRecordOf } from '../dsh/relay.js';
 
 /**
@@ -109,11 +110,39 @@ export async function readState(deps, { sessionId, agent } = {}) {
     .sort((a, b) => a.ratio - b.ratio);
 
   // 0.3.1：模型的「这里适合压缩」判断（比最后一次压缩/交接 checkpoint 新才算数）。
-  const checkpointSeq = target === null ? undefined : lastCheckpointSurfaceSeq(target.session);
+  // 0.4 BUG-013：第二个参数（isCheckpointSource）以前漏传，session-view 里的
+  // TypeError 被 try/catch 吞掉 → 永远找不到 checkpoint → 压缩/交接后旧 hint 不失效
+  // （环上残留旧断点，还会用旧 ratio 抑制 cue）。这里显式传 engine 的判定函数。
+  const checkpointSeq =
+    target === null ? undefined : lastCheckpointSurfaceSeq(target.session, deps.engine?.isCompactCheckpointSource);
   const hint = target === null ? null : compressHintOf(target.session);
   const activeHint = compressHintIsActive(hint, checkpointSeq) ? { ratio: hint.ratio, at: hint.at, seq: hint.seq } : null;
   // 0.3.1：DSH 原生自动压缩配置（读 profile 的 cordis.patch.yml + DSH 默认值）。
-  const nativeCfg = readNativeCompaction();
+  // 0.4 P2-3：deps.nativeConfig 仅给单测注入用；生产不传，仍读本机 profile。
+  const nativeCfg = deps.nativeConfig ?? readNativeCompaction();
+
+  // 0.4 P2-3：算「真实触发线」而不是窗口比例：
+  //   thresholdTokens = floor(min(W × rate, W − 输出预留 − headroom))，触发点 = thresholdTokens / W。
+  // 输出预留取 requestHeader.config.maxTokens（其次适配器 defaultMaxTokens），headroom 与
+  // 路由级 thresholdRatio 来自 compaction-basic 配置（modelPolicies 按 provider+model 覆盖）。
+  let nativePolicy = resolveNativePolicy(nativeCfg, null);
+  let nativeLine = null;
+  let nativeBudget = null;
+  if (target !== null && target.session !== undefined) {
+    try {
+      nativeBudget = await routeBudgetOf(deps.ctx, target.session, picked ?? undefined, measured.window);
+      nativePolicy = resolveNativePolicy(nativeCfg, nativeBudget.route);
+      nativeLine = nativeLineOf({
+        contextWindow: nativeBudget.contextWindow,
+        reservedCompletionTokens: nativeBudget.reservedCompletionTokens,
+        thresholdRatio: nativePolicy.thresholdRatio,
+        headroomTokens: nativePolicy.headroomTokens,
+      });
+    } catch {
+      nativeLine = null;
+      nativeBudget = null;
+    }
+  }
 
   return {
     revision: ++stateRevision,
@@ -140,6 +169,19 @@ export async function readState(deps, { sessionId, agent } = {}) {
     // 0.3.1：模型判断的「适合压缩」断点位置（没有或已失效为 null）。
     compressHint: activeHint,
     // 0.3.1：DSH 原生自动压缩（环上的报警最高阈值 / 设置页开关的数据源）。
-    native: { autoEnabled: nativeCfg.autoEnabled, thresholdRatio: nativeCfg.thresholdRatio },
+    // 0.4 P2-3：额外下发真实触发线（ratio 为 thresholdTokens / window；算不出时 null，
+    // 客户端回落 thresholdRatio 的窗口比例，老客户端不受影响）。
+    native: {
+      autoEnabled: nativeCfg.autoEnabled,
+      thresholdRatio: nativePolicy.thresholdRatio,
+      ratio: nativeLine !== null && nativeLine.ok === true ? nativeLine.ratio : null,
+      thresholdTokens: nativeLine !== null && nativeLine.ok === true ? nativeLine.thresholdTokens : null,
+      contextWindow: nativeBudget?.contextWindow ?? null,
+      reservedCompletionTokens: nativeBudget?.reservedCompletionTokens ?? null,
+      headroomTokens: nativePolicy.headroomTokens,
+      overridden: nativePolicy.overridden === true,
+      route: nativeBudget?.route ?? null,
+      unavailable: nativeLine !== null && nativeLine.ok !== true ? nativeLine.reason : null,
+    },
   };
 }

package/lib/adapters/http.js

@@ -5,6 +5,7 @@
  */
 import { betterCompact, cancelBetterCompact, previewBetterCompact } from '../actions/better-compact.js';
 import { readCompactDiffs } from '../actions/compact-diff.js';
+import { readDiagnostics } from '../actions/diagnostics.js';
 import { handoff, previewHandoff } from '../actions/handoff.js';
 import { listHandoffDocs, readHandoffDoc } from '../actions/handoff-docs.js';
 import { togglePin } from '../actions/pin.js';
@@ -129,6 +130,21 @@ function fallbackRejection(webCtx, req) {
   return undefined;
 }
 
+/**
+ * 设置端点响应 = 设置视图 + 轻账本累计（0.4 P1-3；客户端「累计」一行数字的数据源）。
+ * 读账本失败/没有 ledger 时 `ledger: null`（客户端显示引导文案，不影响设置页）。
+ */
+export function settingsPayloadOf(deps) {
+  const view = deps.settings.view();
+  let ledger = null;
+  try {
+    ledger = typeof deps.ledger?.summary === 'function' ? deps.ledger.summary() : null;
+  } catch {
+    ledger = null;
+  }
+  return { ...view, ledger };
+}
+
 function denyAuth(res, rejection) {
   const status = rejection === 401 ? 401 : 403;
   return send(res, status, {
@@ -259,7 +275,7 @@ export function registerHttp(webCtx, deps) {
           const rejection = hostRejection(webCtx, req);
           if (rejection !== undefined) return denyAuth(res, rejection);
           if (req.method === 'GET') {
-            return send(res, 200, { ok: true, ...deps.settings.view() });
+            return send(res, 200, { ok: true, ...settingsPayloadOf(deps) });
           }
           if (req.method !== 'POST') return send(res, 405, { ok: false, message: '只支持 GET/POST' });
           if (!sameOrigin(req)) return send(res, 403, { ok: false, message: '拒绝跨站请求' });
@@ -274,13 +290,13 @@ export function registerHttp(webCtx, deps) {
             return send(res, 400, { ok: false, message: '请求体必须是 JSON 对象' });
           }
           if (parsed.reset === true) {
-            const view = deps.settings.reset();
+            deps.settings.reset();
             deps.hub?.refreshAll?.();
-            return send(res, 200, { ok: true, ...view });
+            return send(res, 200, { ok: true, ...settingsPayloadOf(deps) });
           }
-          const view = deps.settings.save(parsed);
+          deps.settings.save(parsed);
           deps.hub?.refreshAll?.();
-          return send(res, 200, { ok: true, ...view });
+          return send(res, 200, { ok: true, ...settingsPayloadOf(deps) });
         } catch (error) {
           try {
             const status = error?.statusCode === 413 ? 413 : 400;
@@ -302,6 +318,47 @@ export function registerHttp(webCtx, deps) {
   });
   webCtx.effect(() => settingsStop, 'compact-relay: settings endpoint');
 
+  // 0.4 P0-2：诊断信息（只读、幂等、无副作用）——本机生成、白名单、已脱敏。
+  // 只提供 GET；没有 POST/上传通道（方案 §5.4、§10）。
+  const diagnosticsStop = webCtx.webServer.register({
+    kind: 'exact',
+    path: '/api/compact-relay-diagnostics',
+    handler: (req, res) => {
+      void (async () => {
+        try {
+          const rejection = hostRejection(webCtx, req);
+          if (rejection !== undefined) return denyAuth(res, rejection);
+          if (req.method !== 'GET') return send(res, 405, { ok: false, message: '只支持 GET' });
+          const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+          const sessionId = url.searchParams.get('sessionId') ?? undefined;
+          // 组装在 actions 层（adapters 不直接碰 dsh/，见 A9 架构守卫）。
+          const payload = await readDiagnostics(deps, { sessionId });
+          return send(res, 200, { ok: true, ...payload });
+        } catch (error) {
+          // 只回短文案，不把内部正文/堆栈回给浏览器（方案 §5.4）。
+          const code = error !== null && typeof error === 'object' ? error.code : undefined;
+          try {
+            deps.log?.warn?.(`compact-relay: 生成诊断信息失败${typeof code === 'string' ? `（${code}）` : ''}`);
+          } catch {
+            /* 日志失败不影响响应 */
+          }
+          try {
+            send(res, 500, {
+              ok: false,
+              message:
+                code === 'toolarge'
+                  ? '诊断信息超过 64KB 上限，请先减少错误记录后再试'
+                  : '生成诊断信息失败（详情见插件日志）',
+            });
+          } catch {
+            /* 连接可能已断 */
+          }
+        }
+      })();
+    },
+  });
+  webCtx.effect(() => diagnosticsStop, 'compact-relay: diagnostics endpoint');
+
   const actionStop = webCtx.webServer.register({
     kind: 'exact',
     path: '/api/compact-relay-action',
@@ -312,7 +369,8 @@ export function registerHttp(webCtx, deps) {
           if (rejection !== undefined) return denyAuth(res, rejection);
           if (req.method !== 'POST') return send(res, 405, { ok: false, message: '只支持 POST' });
           if (!sameOrigin(req)) return send(res, 403, { ok: false, message: '拒绝跨站请求' });
-          const body = await readBody(req);
+          // 0.4 P2-1：handoff 可以带「约束/下一步」两段编辑（各 ≤4000 字符），body 上限放宽到 48KB。
+          const body = await readBody(req, 48 * 1024);
           let parsed;
           try {
             parsed = JSON.parse(body === '' ? '{}' : body);
@@ -388,7 +446,8 @@ export function registerHttp(webCtx, deps) {
             return send(res, 200, outcome);
           }
           if (parsed.action === 'handoff') {
-            const outcome = await handoff(deps, { agent });
+            // 0.4 P2-1：`edits` 只允许「约束」「下一步」两段（多余的段/非法类型由 actions 拒绝）。
+            const outcome = await handoff(deps, { agent, edits: parsed.edits });
             return send(res, 200, {
               ok: true,
               message: outcome.message,
@@ -412,6 +471,10 @@ export function registerHttp(webCtx, deps) {
             if (code === 'timeout' || code === 'budget') {
               return send(res, 500, { ok: false, code, message: errorText(error) });
             }
+            // 0.4 P2-1：交接编辑字段非法（改了程序生成段/超长/类型错）→ 400，明确告诉用户哪些段不能改。
+            if (code === 'edits') {
+              return send(res, 400, { ok: false, code, message: errorText(error) });
+            }
             // 忙（正在压缩/交接）回 409，和「没有活动会话」同属可重试状态。
             if (code === 'busy') {
               return send(res, 409, { ok: false, code, message: errorText(error) });