dsh-compact-relay 0.3.6 → 0.4.0

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) });

package/lib/adapters/prompt.js

@@ -1,27 +1,74 @@
 /**
- * 模型入口（0.3.4）——「当前在可压缩区间」的动态提示。
+ * 模型入口（0.3.4 / 0.4 P0-1）——「当前可以记一个压缩节点」的动态提示。
  *
  * BUG-010：0.3.1 的 `mark_stage` 工具在 427 个真实会话里 0 次调用。根因不是模型
  * 不听话，而是工具描述承诺「系统会告诉你容量」但系统从没说过 —— 条件不可判断。
- * 现在宿主每轮把一条 runtime context 注入 system prompt，告诉模型当前容量落在
- * 可压缩区间；模型据此判断「刚完成一个自然节点」时该不该调 `mark_compress_point`。
+ * 0.3.4 起宿主每轮把一条 runtime context 注入 system prompt，告诉模型当前容量。
+ *
+ * 0.4 P0-1（Win 173 会话里 cue 注入 18 次、工具仍 0 调用）：
+ *  1. 文案 v2 与区间 v2 在 core/compress-cue.js（4 类完成信号 + 被拒零副作用）；
+ *  2. **注入门控**在本文件（方案 §3.2）：只有全部满足才注入——
+ *     a) 容量落在 cue 区间（10%–40%，且不越过压缩线，见 cueBandOf）；
+ *     b) 距上次注入 ≥ CUE_MIN_TURNS 轮（本轮按 text 回调调用次数计，纯内存不落盘）；
+ *     c) 一轮内最多一次（连续调用时 b 天然保证）；
+ *  3. 实际注入一次就 `deps.diag.bumpCueInjected()`（供 P0-2 诊断包看数），
+ *     只记次数、不记提示原文（隐私口径与 P0-2 一致）。
  *
  * 约束：
  *  - `systemPrompt.context` 的 text 回调必须是**同步**函数 → 只读
  *    `dsh/state-hub.js` 维护的内存缓存，不 await、不 measure；
  *  - 拿不到会话/缓存/阈值就返回空串（宿主不会展示空 context）；
- *  - 全程 try/catch：提示是锦上添花，任何异常都不能影响宿主组装 prompt。
+ *  - 全程 try/catch：提示是锦上添花，任何异常都不能影响宿主组装 prompt；
+ *  - 本文件（adapters）不 import lib/dsh/：计数走 deps.diag 既有注入。
  */
 import {
   COMPRESS_CUE_NAME,
   COMPRESS_CUE_ORDER,
   compressCueText,
+  cueBandOf,
 } from '../core/compress-cue.js';
-import { compressionMinRatio } from '../core/policy.js';
+import { CUE_MIN_TURNS, compressionMinRatio } from '../core/policy.js';
 
 /** 供测试/文档引用的 context 名称。 */
 export { COMPRESS_CUE_NAME };
 
+/**
+ * 每会话的注入节奏（进程内，不新增持久状态）：
+ *   calls             text 回调被调用次数（≈轮数）
+ *   lastInjectedCall  上次真正注入发生在第几次调用（null = 还没注入过）
+ *
+ * 进程内 Map 只服务宿主生命周期；上限 200 个会话，避免长期运行无限增长。
+ */
+const MAX_TRACKED_SESSIONS = 200;
+const cueTurns = new Map();
+
+/**
+ * 取（并前移）某会话的注入节奏计数。
+ * @param {string} sessionId
+ * @returns {{calls:number, lastInjectedCall:number|null}}
+ */
+function cueTurnOf(sessionId) {
+  let turn = cueTurns.get(sessionId);
+  if (turn === undefined) {
+    turn = { calls: 0, lastInjectedCall: null };
+    cueTurns.set(sessionId, turn);
+    if (cueTurns.size > MAX_TRACKED_SESSIONS) {
+      const oldest = cueTurns.keys().next().value;
+      cueTurns.delete(oldest);
+    }
+  }
+  turn.calls += 1;
+  return turn;
+}
+
+/**
+ * 测试用：清空注入节奏（相当于宿主重启）。生产路径不需要调用。
+ * @returns {void}
+ */
+export function resetCueTurns() {
+  cueTurns.clear();
+}
+
 /**
  * 计算某个 agent 本轮该显示的动态提示（同步、异常安全）。
  * @param {{context?:object, deps?:object, hub?:object}} input
@@ -42,14 +89,28 @@ export function compressCueFor({ context, deps, hub } = {}) {
     if (!Number.isFinite(thresholds.compactRatio)) return '';
     if (!Number.isFinite(cached.ratio) || !Number.isFinite(cached.window) || cached.window <= 0) return '';
 
-    // 最小线是「配置值 vs 动态下限（保留尾部 + 最小可压 token）/窗口」的较大者（纯函数）。
-    const minRatio = compressionMinRatio(thresholds, deps?.cfg?.retention, cached.window);
-    return compressCueText({
+    // 每次 text 回调（≈一轮）都计数：即使本轮不注入，也要推进轮次，限频才有意义。
+    const turn = cueTurnOf(sessionId);
+
+    // 门控 a：区间 = max(10%, 动态最小线) ≤ ratio < min(40%, 压缩线)。
+    const dynamicMinRatio = compressionMinRatio(thresholds, deps?.cfg?.retention, cached.window);
+    const band = cueBandOf({ compactRatio: thresholds.compactRatio, dynamicMinRatio });
+    if (!(cached.ratio >= band.minRatio && cached.ratio < band.maxRatio)) return '';
+
+    // 门控 b/c：距上次注入 ≥ CUE_MIN_TURNS 轮（同一轮内多次调用必然不足）。
+    if (turn.lastInjectedCall !== null && turn.calls - turn.lastInjectedCall < CUE_MIN_TURNS) return '';
+
+    const text = compressCueText({
       ratio: cached.ratio,
-      minRatio,
-      compactRatio: thresholds.compactRatio,
+      minRatio: band.minRatio,
+      maxRatio: band.maxRatio,
       compressHint: cached.compressHint ?? null,
     });
+    if (text === '') return '';
+
+    turn.lastInjectedCall = turn.calls;
+    deps?.diag?.bumpCueInjected?.();
+    return text;
   } catch {
     return '';
   }

package/lib/adapters/tool.js

@@ -8,6 +8,11 @@
  * 模型无法判断条件 → 427 个真实会话 0 次调用。0.3.4 起由宿主每轮注入可压缩区间
  * 提示（lib/adapters/prompt.js），工具描述只描述「它自己会做什么」：
  * 服务端工具会返回当前容量并复核区间，太低/到线都拒绝且不改历史。
+ *
+ * 0.4 P0-1（方案 §3.3）：Win 173 会话 cue 注入 18 次、工具 0 调用 → 描述 v2：
+ *  - 明确「用户和模型都可以调用」（不只是模型的自发动作）；
+ *  - 「被拒不需要致歉」：拒绝零副作用、不改历史、不需要重试或道歉（降低调用心理成本）；
+ *  - 给出典型调用时机；把「不需要每个小步骤都调用」弱化后挪到句尾，不再抢在条件前面。
  */
 import { markCompressHint } from '../actions/compress-hint.js';
 import engine from '../dsh/engine.js';
@@ -22,10 +27,10 @@ export function registerTool(ctx, deps) {
       name: 'mark_compress_point',
       description:
         '记录一个「压缩节点」：在指示灯环上标出「这里适合把前面的旧历史压成摘要」。' +
-        '在你刚完成一个明确的任务/阶段、并且认为之后可以安全地压缩旧历史继续往下做时调用。' +
-        '不确定当前是否合适时也可以调用：工具会返回当前上下文容量并做判断，' +
-        '容量太低（压缩不划算）或已经到压缩线（直接建议用户压缩即可）会被拒绝，拒绝不会改动任何历史。' +
-        '不需要每个小步骤都调用。每次判断只记一条，压缩或交接后旧记录自动失效。',
+        '用户和模型都可以调用；不确定时调用是安全的：工具会自己判断容量，太早或已到压缩线会拒绝，' +
+        '被拒不需要致歉、不会改动历史、也不影响会话，不需要重试。' +
+        '典型调用时机：阶段完成（功能已实现并验证 / 文档已交付 / 问题已定位并修复）、准备交接前、长任务中途确认可回退点。' +
+        '调用后工具会返回当前容量与判断结果；每次判断只记一条，压缩或交接后旧记录自动失效。小步骤不用调用。',
       parameters: {},
       output: {
         schema: { type: 'string' },