dsh-compact-relay 0.0.0-stage → 0.3.2

package/lib/actions/handoff.js

@@ -0,0 +1,304 @@
+/**
+ * 交接新会话（/handoff，代码里沿用 handoff/HO 命名）—— M3 正式版
+ * （照 REFERENCES §1.6 WeiYe6 路线，按 DSH 0.2 API 落地）。
+ *
+ * 流程（REQUIREMENTS §三，交接部分）：
+ *   1. 先压缩旧会话一次（复用 M2 的 betterCompact 本体，不二压政策不变）；
+ *   2. 让模型看着压缩后的完整 surface 写九段交接单（不是压缩摘要；程序段由代码收集）；
+ *   3. 写盘到 cfg.handoffDir（默认 ~/.dsh/handoffs）/handoff-<时间>.md；
+ *   4. 在同一工作区建新会话（同 preset、同模型），把交接单注入并起第一轮；
+ *   5. 返回新会话 id，客户端据此自动切过去。
+ *
+ * 失败语义：
+ *   - 压缩失败但可继续（结构/范围问题）→ 降级为「不压缩，直接写文档」并记日志；
+ *   - 压缩 busy / 用户取消 → 直接中止（会话可能正在跑）；
+ *   - 文档生成不合格 → 不建新会话（无副作用，只多一次模型调用）；
+ *   - 新会话建好但注入失败 → 报错里带 childId，用户可从侧栏手动打开。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { actionError } from '../core/errors.js';
+import { handoffFileName, renderHandoffDoc } from '../core/handoff-doc.js';
+import { betterCompactLocked } from './better-compact.js';
+import { compressHint, countSummaries, livePinnedSeqs, surfaceSeqs } from '../dsh/session-view.js';
+import { measurePressure } from '../dsh/pressure.js';
+import { buildSiteSnapshot } from '../dsh/site-info.js';
+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 { surfaceMessages } from '../dsh/prefix.js';
+import { handoffTitlePlanOf, createHandoffSession, sourceTitleOf } from '../dsh/sessions.js';
+import { writeRelayRecord } from '../dsh/relay.js';
+import { withLock } from './lock.js';
+
+/**
+ * 压缩阶段：能压就压，压不了就带着原因往下走。
+ * @returns {Promise<{outcome: object|null, warning: string|null}>}
+ */
+async function compactFirst(deps, { agent, signal, commandId, log }) {
+  try {
+    return { outcome: await betterCompactLocked(deps, { agent, signal, commandId }), warning: null };
+  } catch (error) {
+    const code = error !== null && typeof error === 'object' ? error.code : undefined;
+    // 只有「事务开始前/未提交」的失败能降级继续（结构、范围、摘要、内容变化）。
+    // commit/persistence 说明历史可能已被改写但没落盘，再写交接单会给出与真实历史不符的文档，
+    // 所以直接中止交接（2026-10-19 debug 实测：旧实现会报「压缩失败已跳过」却已替换历史）。
+    if (code === 'busy' || code === 'cancelled' || code === 'commit' || code === 'persistence') throw error;
+    const warning = error instanceof Error ? error.message : String(error);
+    log?.warn?.(`compact-relay: 交接前压缩失败，按当前历史继续：${warning}`);
+    return { outcome: null, warning };
+  }
+}
+
+/**
+ * 收集交接单需要的全部会话事实（A1）：压力/现场快照/摘要数/锁定/改过的文件/程序段。
+ * @returns {Promise<{session:object, measured:object, now:Date, site:object, summaries:number, pinnedSeqs:number[], changedFiles:string[], programSections:Record<string,string>}>}
+ */
+async function collectHandoffFacts(deps, agent) {
+  const session = agent.session;
+  const measured = await measurePressure(deps.ctx, agent, { windowFallback: deps.cfg.contextWindowFallback }).catch(
+    () => ({ tokens: null }),
+  );
+  const now = new Date();
+  const site = buildSiteSnapshot({ session, now });
+  const summaries = countSummaries(session);
+  const pinnedSeqs = livePinnedSeqs(session);
+  const changedFiles = changedFilesOf(session);
+  const programSections = buildHandoffProgramSections({
+    compressHint: compressHint(session),
+    summaries,
+    pressure: measured.tokens,
+    pins: { count: pinnedSeqs.length, seqs: pinnedSeqs },
+    changedFiles,
+    site,
+  });
+  return { session, measured, now, site, summaries, pinnedSeqs, changedFiles, programSections };
+}
+
+/**
+ * @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 }) {
+  if (agent === undefined || agent === null) throw actionError('handoff', '当前没有打开的会话，无法交接');
+  const session = agent.session;
+  if (session === undefined) throw actionError('handoff', '没有活动会话，无法交接');
+
+  return withLock(deps.lock, agent.id, async () => {
+    // P1-4：交接登记进 inflight，client 的取消按钮才能真正 abort 模型调用。
+    const controller =
+      deps.inflight !== undefined && typeof deps.inflight.begin === 'function'
+        ? deps.inflight.begin(agent.id, 'handoff')
+        : null;
+    const combined =
+      controller?.signal === undefined
+        ? signal
+        : signal === undefined
+          ? controller.signal
+          : AbortSignal.any([controller.signal, signal]);
+
+    try {
+      // P2-2：先做可失败的 preflight（目录可写），再动历史（压缩）。
+      try {
+        fs.mkdirSync(deps.cfg.handoffDir, { recursive: true });
+        fs.accessSync(deps.cfg.handoffDir, fs.constants.W_OK);
+      } catch (error) {
+        throw actionError(
+          'handoff',
+          `交接单目录不可写（${deps.cfg.handoffDir}）：${error instanceof Error ? error.message : String(error)}`,
+          error,
+        );
+      }
+
+      // 1) 先压缩旧会话一次（best effort）。
+      const { outcome: compactOutcome, warning: compactWarning } = await compactFirst(deps, {
+        agent,
+        signal: combined,
+        commandId,
+        log: deps.log,
+      });
+      combined?.throwIfAborted?.();
+
+      // 2) 收集事实（A1 程序段）+ 预算/文档头用的压力。
+      const facts = await collectHandoffFacts(deps, agent);
+
+      // 3) 让模型写七段（压缩后的完整 surface 为输入），程序段由 writer 拼成九段。
+      const generated = await generateHandoffDoc({
+        ctx: deps.ctx,
+        engine: deps.engine,
+        agent,
+        maxTokens: deps.cfg.handoff.maxTokens,
+        inputTokens: facts.measured.tokens,
+        timeoutMs: deps.cfg.timeouts?.llmMs,
+        signal: combined,
+        programSections: facts.programSections,
+      });
+      combined?.throwIfAborted?.();
+
+      // 3.5) 就绪检查：九段缺段/占位阻断；路径核对只警告，不阻断。
+      const readiness = checkHandoffReadiness({
+        sections: generated.sections,
+        surfaceText: JSON.stringify(surfaceMessages(facts.session)),
+        changedFiles: facts.changedFiles,
+        messageCount: surfaceSeqs(facts.session).length,
+      });
+      if (!readiness.ok) {
+        throw actionError('handoff', `交接单就绪检查未通过：缺少或为空的小节：${readiness.missing.join('、')}`);
+      }
+      for (const warning of readiness.warnings) deps.log?.warn?.(`compact-relay: 交接单就绪警告：${warning}`);
+
+      // 4) 写盘：文档头带元信息，九段正文 = 模型 7 段 + 程序 2 段。
+      const file = path.join(deps.cfg.handoffDir, handoffFileName(facts.now));
+      const doc = renderHandoffDoc({
+        generated: generated.text,
+        sourceSessionId: facts.session.id,
+        sourceTitle: sourceTitleOf(deps.ctx, facts.session),
+        now: facts.now,
+        pressure: facts.measured.tokens,
+        summaries: facts.summaries,
+        file,
+        // M6：把「宿主刚重启过 / 工作区分支 / 有没有后台任务在跑」写进文档头，
+        // 免得接手者按一份出厂即过时的「下一步」干活。
+        site: facts.site,
+      });
+      try {
+        fs.writeFileSync(file, doc, 'utf8');
+      } catch (error) {
+        throw actionError(
+          'handoff',
+          `交接单写盘失败（${deps.cfg.handoffDir}）：${error instanceof Error ? error.message : String(error)}`,
+          error,
+        );
+      }
+
+      // 5) 新会话：同工作区 / 同 preset / 同模型，注入交接单并起第一轮。
+      //    A5：标题序号优先读父会话里的 relay 记录（不依赖解析标题文案）。
+      const titlePlan = handoffTitlePlanOf(deps.ctx, session);
+      let created;
+      try {
+        created = await createHandoffSession({
+          ctx: deps.ctx,
+          engine: deps.engine,
+          session,
+          agent,
+          doc,
+          title: titlePlan.title,
+          log: deps.log,
+        });
+      } catch (error) {
+        // 建会话失败 → 清掉刚写的交接单，避免留孤儿文件（P2-2）。
+        try {
+          fs.unlinkSync(file);
+        } catch {
+          /* 清不掉也别盖住原始错误 */
+        }
+        throw error;
+      }
+
+      // A5：把接力链写成父会话里的结构化记录；写失败不阻断交接（标题解析仍可兜底）。
+      const relayWrote = writeRelayRecord(deps.engine, session, {
+        parentSessionId: session.id,
+        childId: created.childId,
+        index: titlePlan.index,
+        path: file,
+        planId: compactOutcome?.planId ?? null,
+        at: Date.now(),
+        title: titlePlan.title,
+        baseTitle: titlePlan.baseTitle,
+      });
+      if (!relayWrote) deps.log?.warn?.('compact-relay: 接力链记录写入失败，下次交接将回退到标题解析');
+
+      // BUG-004：失败原因可能是「摘要模型调用了工具」这类可操作信息，以前只写「日志有记录」
+      // （用户看不到 host 日志）；这里带上短原因 + 可手动 /bc 的建议。
+      const briefWarning =
+        compactWarning === null
+          ? ''
+          : compactWarning.length > 120
+            ? `${compactWarning.slice(0, 119)}…`
+            : compactWarning;
+      const compactNote =
+        compactOutcome !== null && compactOutcome.compacted === true
+          ? `已将 ${compactOutcome.shadowedSeqs.length} 条旧会话压成 1 条摘要；`
+          : compactOutcome !== null
+            ? '没有可压缩内容，交接单基于完整历史；'
+            : compactWarning !== null
+              ? `压缩失败已跳过（${briefWarning}）；需要的话可先手动 /bc 再交接；`
+              : '';
+
+      return {
+        ok: true,
+        childId: created.childId,
+        path: file,
+        readiness,
+        started: created.started,
+        message:
+          `交接完成：${compactNote}` +
+          `交接单已存至 ${file}；` +
+          `新会话（${created.childId}）已就绪` +
+          (created.started ? '，正在切换。' : '，正在切换（首轮未自动启动，可在新会话里发一条消息继续）。') +
+          // A5 兜底：结构化 childId 没传下来时，客户端可从文本里提取。
+          `\n#child=${created.childId}`,
+      };
+    } catch (error) {
+      // 取消统一收口；已提交/落盘状态不明的错误不许谎报「没改」。
+      if (
+        combined?.aborted === true &&
+        error?.code !== 'cancelled' &&
+        error?.code !== 'commit' &&
+        error?.code !== 'persistence'
+      ) {
+        throw actionError('cancelled', '已取消交接；已完成的压缩不会回滚。', error);
+      }
+      throw error;
+    } finally {
+      if (controller !== null && typeof deps.inflight.finish === 'function') {
+        deps.inflight.finish(agent.id, controller);
+      }
+    }
+  });
+}
+
+/**
+ * 交接预览（A1b）：生成九段草稿 + 就绪清单，但不写盘、不建会话、不改历史。
+ *
+ * 注意：真实交接会先 best-effort 压缩再重新生成，所以这里只代表「按当前历史
+ * 交接会写成什么样」；确认后仍走 handoff() 的完整流程。
+ * @param {{ctx:object, cfg:object, engine:object, log?:object}} deps
+ * @param {{agent:object, signal?:AbortSignal}} input
+ */
+export async function previewHandoff(deps, { agent, signal }) {
+  if (agent === undefined || agent === null) throw actionError('handoff', '当前没有打开的会话，无法预览交接');
+  const session = agent.session;
+  if (session === undefined) throw actionError('handoff', '没有活动会话，无法预览交接');
+
+  const facts = await collectHandoffFacts(deps, agent);
+  const generated = await generateHandoffDoc({
+    ctx: deps.ctx,
+    engine: deps.engine,
+    agent,
+    maxTokens: deps.cfg.handoff.maxTokens,
+    inputTokens: facts.measured.tokens,
+    timeoutMs: deps.cfg.timeouts?.llmMs,
+    signal,
+    programSections: facts.programSections,
+  });
+  const readiness = checkHandoffReadiness({
+    sections: generated.sections,
+    surfaceText: JSON.stringify(surfaceMessages(facts.session)),
+    changedFiles: facts.changedFiles,
+    messageCount: surfaceSeqs(facts.session).length,
+  });
+  if (!readiness.ok) {
+    throw actionError('handoff', `交接单就绪检查未通过：缺少或为空的小节：${readiness.missing.join('、')}`);
+  }
+  return {
+    ok: true,
+    draft: generated.text,
+    readiness,
+    pressure: facts.measured.tokens,
+    summaries: facts.summaries,
+    changedFiles: facts.changedFiles,
+    attempts: generated.attempts,
+  };
+}

package/lib/actions/inflight.js

@@ -0,0 +1,75 @@
+/**
+ * 进行中动作登记表（M6）—— 让 HTTP 层能取消正在跑的压缩。
+ *
+ * 与 actions/lock.js 的单飞锁分工：
+ *   - lock：防并发，决定「能不能开始」；
+ *   - inflight：登记 AbortController，决定「正在跑的这个能不能被取消」。
+ *
+ * 取消只是 abort；事务层会补一条 compaction/end(error)，历史不变。
+ */
+import { actionError } from '../core/errors.js';
+
+const keyOf = (sessionId) => (typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : null);
+
+export function createInflight() {
+  /** @type {Map<string, {controller:AbortController, kind:string}>} */
+  const entries = new Map();
+
+  return {
+    /**
+     * 登记一次动作；同会话已有登记则抛 busy（外层锁会再兜一层）。
+     * @param {string|undefined} sessionId
+     * @param {string} [kind]
+     * @returns {AbortController|null}
+     */
+    begin(sessionId, kind = 'compact') {
+      const key = keyOf(sessionId);
+      if (key === null) return null;
+      if (entries.has(key)) throw actionError('busy', '这个会话已经有压缩/交接在跑');
+      const controller = new AbortController();
+      entries.set(key, { controller, kind: typeof kind === 'string' && kind.length > 0 ? kind : 'compact' });
+      return controller;
+    },
+    /**
+     * 结束登记（只清自己那一份，避免误清后来的一轮）。
+     * @param {string|undefined} sessionId
+     * @param {AbortController|null} controller
+     */
+    finish(sessionId, controller) {
+      const key = keyOf(sessionId);
+      if (key === null) return;
+      const entry = entries.get(key);
+      if (entry !== undefined && entry.controller === controller) entries.delete(key);
+    },
+    /**
+     * 请求取消；返回是否真的找到了在跑的动作。
+     * @param {string|undefined} sessionId
+     * @returns {boolean}
+     */
+    cancel(sessionId) {
+      const key = keyOf(sessionId);
+      if (key === null) return false;
+      const entry = entries.get(key);
+      if (entry === undefined) return false;
+      entry.controller.abort();
+      return true;
+    },
+    /**
+     * @param {string|undefined} sessionId
+     * @returns {boolean}
+     */
+    isActive(sessionId) {
+      const key = keyOf(sessionId);
+      return key !== null && entries.has(key);
+    },
+    /**
+     * @param {string|undefined} sessionId
+     * @returns {string|null}
+     */
+    kindOf(sessionId) {
+      const key = keyOf(sessionId);
+      const entry = key === null ? undefined : entries.get(key);
+      return entry === undefined ? null : entry.kind;
+    },
+  };
+}

package/lib/actions/lock.js

@@ -0,0 +1,44 @@
+/**
+ * 每会话单飞锁 —— 压缩/交接/测试共用。
+ *
+ * 同一会话同时只允许一个改历史的动作；
+ * 指示灯里的 busy 状态也从这里读，不各写一套。
+ */
+import { actionError } from '../core/errors.js';
+
+/** @returns {{tryAcquire:(id:string)=>boolean, release:(id:string)=>void, isBusy:(id?:string|null)=>boolean}} */
+export function createLock() {
+  const active = new Set();
+  return {
+    tryAcquire(id) {
+      if (active.has(id)) return false;
+      active.add(id);
+      return true;
+    },
+    release(id) {
+      active.delete(id);
+    },
+    isBusy(id) {
+      return typeof id === 'string' && id.length > 0 && active.has(id);
+    },
+  };
+}
+
+/**
+ * @template T
+ * @param {{tryAcquire:(id:string)=>boolean, release:(id:string)=>void}} lock
+ * @param {string|undefined} sessionId
+ * @param {() => Promise<T>} job
+ * @returns {Promise<T>}
+ */
+export async function withLock(lock, sessionId, job) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) return job();
+  if (!lock.tryAcquire(sessionId)) {
+    throw actionError('busy', '这个会话已经有压缩/交接在跑');
+  }
+  try {
+    return await job();
+  } finally {
+    lock.release(sessionId);
+  }
+}

package/lib/actions/native-compaction.js

@@ -0,0 +1,35 @@
+/**
+ * DSH 原生自动压缩开关（0.3.1）—— actions 层包装。
+ *
+ * 真正的读写逻辑在 dsh/native-compaction.js；这里只做参数校验与返回结构，
+ * 让 adapters/http 不直接碰 dsh/（A9 架构守卫）。
+ */
+import { readNativeCompaction, setNativeAutoCompaction } from '../dsh/native-compaction.js';
+
+/**
+ * 读当前原生压缩配置（设置页/状态用）。
+ * @returns {{autoEnabled:boolean, thresholdRatio:number}}
+ */
+export function nativeCompactionInfo() {
+  const current = readNativeCompaction();
+  return { autoEnabled: current.autoEnabled, thresholdRatio: current.thresholdRatio };
+}
+
+/**
+ * 关闭/恢复 DSH 原生自动压缩。
+ * @param {{enabled:boolean}} input
+ * @returns {{autoEnabled:boolean, thresholdRatio:number, backup:string|null, file:string, message:string}}
+ */
+export function setNativeAutoCompactionEnabled({ enabled } = {}) {
+  if (typeof enabled !== 'boolean') throw new Error('缺少 enabled（true=恢复原生自动压缩，false=关闭）');
+  const outcome = setNativeAutoCompaction(enabled);
+  return {
+    autoEnabled: outcome.autoEnabled,
+    thresholdRatio: outcome.thresholdRatio,
+    backup: outcome.backup,
+    file: outcome.file,
+    message: outcome.autoEnabled
+      ? `已恢复 DSH 原生自动压缩（当前原生阈值 ${(outcome.thresholdRatio * 100).toFixed(0)}%）；重启 DSH 后生效`
+      : `已关闭 DSH 原生自动压缩（备份：${outcome.backup ?? '无'}）；重启 DSH 后生效`,
+  };
+}

package/lib/actions/pin.js

@@ -0,0 +1,208 @@
+/**
+ * 锁定重要消息（M6，内部代号「钉住」/pin）—— 用户指定「必须原样保留、不被压缩」的消息。
+ *
+ * 入口：
+ *   - `/pin`（钉最近一轮）/ `/pin list`（列最近 10 条 + 已钉集合）
+ *   - `/pin <序号>`（钉列表里的第 n 条）/ `/pin clear`
+ *   - `/unpin`（清空全部）
+ *   - 指示灯菜单「锁定重要消息 / 解锁消息（N 条）」（HTTP action pin-toggle）
+ *
+ * 只写 plugin record：不进模型上下文、不占 token；压缩选段会避开被锁定的消息。
+ */
+import { actionError } from '../core/errors.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 可能是数组或字符串）。
+ * @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;
+}
+
+/**
+ * 最近 N 条 surface 消息（新→旧），编号 1 开始。
+ * @param {object} session
+ * @param {number} [limit]
+ */
+export function pinCandidates(session, limit = 10) {
+  const seqs = surfaceSeqs(session);
+  const picked = [];
+  for (let index = seqs.length - 1; index >= 0 && picked.length < limit; index -= 1) {
+    const seq = seqs[index];
+    const event = typeof session.eventAt === 'function' ? session.eventAt(seq) : undefined;
+    if (event === undefined || event === null) continue;
+    picked.push({
+      index: picked.length + 1,
+      seq,
+      type: event.type,
+      role: TYPE_LABEL[event.type] ?? '其他',
+      preview: previewOf(event),
+    });
+  }
+  return picked;
+}
+
+function pinnedOf(session) {
+  return latestPinnedSeqs(sessionLog(session));
+}
+
+function writePins(deps, session, seqs) {
+  const normalized = normalizePinnedSeqs(seqs);
+  deps.engine.appendPluginRecord(session, PIN_RECORD_TYPE, { seqs: normalized, at: Date.now() });
+  return normalized;
+}
+
+/**
+ * 锁定最近一轮对话（最后一条 user/message；没有就退回最后一条 surface 消息）。
+ * @param {{engine:object}} deps
+ * @param {{agent:object}} input
+ */
+export function pinLastTurn(deps, { agent } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('pin', '当前没有打开的会话，无法锁定消息');
+  // P3-03：只把「还活着」的锁定带进新快照；过期的 seq 顺手清掉，不让快照越滚越脏。
+  const current = livePinnedSeqs(session);
+
+  let seq = null;
+  const seqs = surfaceSeqs(session);
+  // 优先锁「人真正说的上一句」：v4 里 runtime-context / time-context / checkpoint
+  // 也是 user/message，直接取最后一条会锁到合成消息（2026-10-19 debug 实测）。
+  for (let index = seqs.length - 1; index >= 0; index -= 1) {
+    const event = typeof session.eventAt === 'function' ? session.eventAt(seqs[index]) : undefined;
+    if (event?.type === 'user/message' && event.data?.source?.kind === 'user') {
+      seq = seqs[index];
+      break;
+    }
+  }
+  if (seq === null) {
+    // 老会话/测试 mock 没有 source 信息：退回「最后一条 user/message」，再退回最后一条 surface。
+    for (let index = seqs.length - 1; index >= 0; index -= 1) {
+      const event = typeof session.eventAt === 'function' ? session.eventAt(seqs[index]) : undefined;
+      if (event?.type === 'user/message') {
+        seq = seqs[index];
+        break;
+      }
+    }
+  }
+  if (seq === null && seqs.length > 0) seq = seqs[seqs.length - 1];
+  if (seq === null) throw actionError('pin', '当前会话还没有可锁定的消息');
+
+  const pinned = writePins(deps, session, [...current, seq]);
+  return {
+    pinned,
+    added: seq,
+    message: `已锁定最近一轮会话（共 ${pinned.length} 条）；后续压缩将原样保留。`,
+  };
+}
+
+/**
+ * 按 `/pin list` 的编号锁定某条消息（1 = 最新）。
+ * @param {{engine:object}} deps
+ * @param {{agent:object, index:number}} input
+ */
+export function pinByIndex(deps, { agent, index } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('pin', '没有活动会话，无法锁定消息');
+  const wanted = Number(index);
+  if (!Number.isInteger(wanted) || wanted < 1) throw actionError('pin', '序号须为正整数，例如 /pin 3');
+  const candidates = pinCandidates(session, 10);
+  const candidate = candidates.find((entry) => entry.index === wanted);
+  if (candidate === undefined) {
+    throw actionError('pin', `只能从最近 ${candidates.length} 条消息中选择（用 /pin list 查看序号）`);
+  }
+  const current = livePinnedSeqs(session);
+  const pinned = writePins(deps, session, [...current, candidate.seq]);
+  return {
+    pinned,
+    added: candidate.seq,
+    message: `已锁定 1 条消息（${candidate.role}：${candidate.preview}）；当前共锁定 ${pinned.length} 条。`,
+  };
+}
+
+/**
+ * 清空全部锁定。
+ * @param {{engine:object}} deps
+ * @param {{agent:object}} input
+ */
+export function unpinAll(deps, { agent } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('pin', '当前没有打开的会话，无法解锁消息');
+  const current = pinnedOf(session);
+  // 本来就是空集合：不要为「清空空集合」再写一条记录（白触发 SSE/落盘）。
+  if (current.length === 0) {
+    return { pinned: [], cleared: 0, message: '当前没有锁定的消息。' };
+  }
+  // P3-03：和 readState 的展示口径对齐——只数「当前 surface 里还活着」的锁定。
+  // 快照里的 seq 可能已被原生压缩/清屏带走，那些只是过期记录，不该算进「解锁了几条」。
+  const live = livePinnedSeqs(session);
+  writePins(deps, session, []);
+  return {
+    pinned: [],
+    cleared: live.length,
+    message:
+      live.length === 0
+        ? '已清理过期的锁定记录（原快照里的消息已不在当前会话中），后续压缩不受影响。'
+        : `已全部解锁（原 ${live.length} 条），后续压缩可正常合并这些消息。`,
+  };
+}
+
+/**
+ * 列表：最近 10 条可钉消息 + 当前已钉集合。
+ * @param {{}} deps
+ * @param {{agent:object}} input
+ */
+export function listPins(deps, { agent } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('pin', '没有活动会话');
+  const candidates = pinCandidates(session, 10);
+  const pinned = pinnedOf(session);
+  const lines = candidates.map((entry) => `${entry.index}. ${entry.role}：${entry.preview}`);
+  return {
+    pinned,
+    candidates,
+    message:
+      (candidates.length === 0
+        ? '当前会话还没有可锁定的消息。'
+        : `最近 ${candidates.length} 条消息（输入 /pin <序号> 锁定指定消息）：\n${lines.join('\n')}`) +
+      `\n当前已锁定：${pinned.length === 0 ? '无' : `${pinned.length} 条`}`,
+  };
+}
+
+/**
+ * 菜单用：有锁定就清空，没有就锁最近一轮。
+ *
+ * P3-03：判断必须和 readState 的展示同口径（`livePinnedSeqs`）。只看日志里的最新
+ * 快照时，快照 seq 已被压缩/清屏带走的场景会让菜单显示「锁定重要消息」（未锁），
+ * 点下去却走 unpinAll → 用户看到的是「明明没锁却被解锁」。
+ * @param {{engine:object}} deps
+ * @param {{agent:object}} input
+ */
+export function togglePin(deps, { agent } = {}) {
+  const session = agent?.session;
+  if (session === null || session === undefined) throw actionError('pin', '没有活动会话');
+  return livePinnedSeqs(session).length > 0 ? unpinAll(deps, { agent }) : pinLastTurn(deps, { agent });
+}