@zhushanwen/pi-session-manager 0.1.16 → 0.2.0

package/src/index.ts

@@ -1,7 +1,12 @@
 // src/index.ts — @zhushanwen/pi-session-manager
 // 6 个 session 管理工具，通过 ctx.ui.select(SESSION_MANAGER_MARKER) 通道与 runtime handler 通信。
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	SessionCompactEvent,
+	SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
 import {
 	SESSION_MANAGER_MARKER,
 	callMarkerRpc,
@@ -13,6 +18,9 @@ import {
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 import { Type, type Static, type TObject } from "typebox";
 
+import { ensureLedgerBound, runLedgerCompactionCheck } from "./notify-ledger.ts";
+import { createWatchCoordinator } from "./watch-coordinator.ts";
+
 // 模块级 logger（default export 首行 setPiHandle 注入后自动走 appendEntry 持久化，
 // 注入前/失败降级文件日志——见 extension-logger 三层通道设计）
 const logger = getLogger("session-manager");
@@ -47,8 +55,11 @@ const AbortSessionParams = Type.Object({
 
 // ── select 通道辅助 ──
 
-/** select 超时（ms）：工具等待 runtime handler respond 的最大时间（create/history 走长链路放宽） */
-const SELECT_TIMEOUT_MS: Record<SessionManagerAction, number> = {
+/** select 超时（ms）：工具等待 runtime handler respond 的最大时间（create/history 走长链路放宽）。
+ *  watch 刻意缺席（notify-once D2：不传 timeout、fire-and-forget 长挂——P1 实测 `if
+ *  (opts?.timeout)` 才设 timer）。形制 = `Exclude<SessionManagerAction, "watch">`：
+ *  协议 action 集 6→7 后漏配键即编译期红（计划 blocker #1 的修复形态）。 */
+const SELECT_TIMEOUT_MS: Record<Exclude<SessionManagerAction, "watch">, number> = {
 	create: 60_000,
 	send: 30_000,
 	history: 60_000,
@@ -60,7 +71,10 @@ const SELECT_TIMEOUT_MS: Record<SessionManagerAction, number> = {
 /**
  * 通过 select 通道向 runtime handler 发送 session 管理请求（传输核走 protocol 的
  * callMarkerRpc 原语，D8）。回包为 handler respond 的 JSON 字符串（value 恒 raw）；
- * 失败四态（cancelled/timeout/channel-error/non-json）由 executeTool 统一折叠 isError。
+ * 失败四态（cancelled/timeout/channel-error/non-json）由 executeTool 统一 throw——
+ * pi agent-loop 仅在 execute throw 时置 isError:true，返回值里的 isError 字段被丢弃
+ * （pi-agent-core dist/agent-loop.js:453-483 executePreparedToolCall：正常 return
+ * 硬编码 isError:false、catch 置 true——0.84.4 实读 :468/:470-476；语义登记 PS-56）。
  * 通道异常与非 JSON 回包的留痕由原语经注入的 log 承担。
  */
 function callSessionManager(
@@ -81,51 +95,63 @@ function callSessionManager(
 		ui: { select: ctx.ui.select.bind(ctx.ui) },
 	};
 	return callMarkerRpc(guiCtx, SESSION_MANAGER_MARKER, payload, {
-		timeout: SELECT_TIMEOUT_MS[action],
+		// watch 不传 timeout（D2/P1：无 timer 长挂不死，任意晚的 respond 按 id 精确 resolve；PS-59）
+		timeout: action === "watch" ? undefined : SELECT_TIMEOUT_MS[action],
 		log: (msg, detail) => logger.error(`[session-manager] ${msg}`, detail),
 	});
 }
 
+/** notifyId 生成（notify-once D2）：`sm-` + UUID4——与协议 isSessionManagerNotifyId
+ *  同形态（runtime 受理点按该形态判 arm）。 */
+function newNotifyId(): string {
+	return `sm-${crypto.randomUUID()}`;
+}
+
+/** 运行时守卫（读侧不信任外部格式）：结果是否 JSON object——形状断言前的类型 guard。 */
+function asResultRecord(v: unknown): Record<string, unknown> | undefined {
+	return typeof v === "object" && v !== null && !Array.isArray(v)
+			? (v as Record<string, unknown>)
+			: undefined;
+}
+
 /**
  * 统一的 execute 包装：调用 select 通道并解析结果。
  * 返回标准 AgentToolResult 形状；select 取消/超时/异常/非 JSON 回包是错误路径，
- * 必须带 isError: true（extension-conventions「禁止错误成功模式」——
- * 调用方 agent 需能区分成功与失败以决定重试/放弃）。
+ * 必须 throw（extension-conventions「禁止错误成功模式」——pi 契约里 execute 只有
+ * throw 才被置 isError:true，返回值携带 isError 字段会被 agent-loop 丢弃
+ * （agent-loop.js:453-483，PS-56），ask-user/scheduler/session-reader 的 W4 throw
+ * 范式同款；调用方 agent 需能区分成功与失败以决定重试/放弃）。
  */
 async function executeTool(
 	ctx: ExtensionContext,
 	action: SessionManagerAction,
 	params: Record<string, unknown>,
-): Promise<{ isError?: boolean; content: Array<{ type: "text"; text: string }>; details: undefined }> {
+	onResult?: (ctx: ExtensionContext, params: Record<string, unknown>, result: unknown) => void,
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: undefined }> {
 	const result = await callSessionManager(ctx, action, params);
 	if (!result.ok) {
 		// 行为微变①（D8，有意——对齐 plugin-bridge 形态）：非 JSON 回包从「catch 后
-		// parsed=undefined 静默当成功文本返回」改为 isError + 提示文本（留痕由原语
+		// parsed=undefined 静默当成功文本返回」改为 throw + 提示文本（留痕由原语
 		// 经注入的 logger.error 承担）；其余三态维持原 cancelled/timeout 折叠文案。
 		const text =
 			result.reason === "non-json"
 				? `Session manager ${action}: non-JSON response from runtime (protocol mismatch — redeploy same-version runtime + extension; see extension logs).`
 				: `Session manager ${action}: cancelled or timed out.`;
-		return {
-			isError: true,
-			content: [{ type: "text" as const, text }],
-			details: undefined,
-		};
+		throw new Error(text);
 	}
 	const raw = result.value;
 	// 合法性已由原语检测（ok:true ⇒ 同一字符串 JSON.parse 必成功），parse 只为字段检测。
 	// runtime 错误闭环（respond({error}) 走同一 select 通道）——检测与文本拼接单源于
-	// protocol 的 isChannelErrorResult / formatChannelErrorText（D8）：命中即 isError: true
+	// protocol 的 isChannelErrorResult / formatChannelErrorText（D8）：命中即 throw
 	//（extension-conventions「禁止错误成功模式」：agent 需能区分成功与同步失败以决定
 	// 重试/放弃，不能靠读 content 文本自行判错）。
 	const parsed: unknown = JSON.parse(raw);
 	if (isChannelErrorResult(parsed)) {
-		return {
-			isError: true,
-			content: [{ type: "text" as const, text: formatChannelErrorText(parsed) }],
-			details: undefined,
-		};
+		throw new Error(formatChannelErrorText(parsed));
 	}
+	// 成功路径副作用编排（notify-once U4）：send/create 的 willNotify arm（register + 开表）、
+	// label 缓存回填（list）——错误路径已 throw，天然不触发。
+	onResult?.(ctx, params, parsed);
 	return {
 		content: [{ type: "text" as const, text: raw }],
 		details: undefined,
@@ -143,6 +169,8 @@ interface SessionToolConfig<S extends TObject> {
 	action: SessionManagerAction
 	/** schema params → 协议 params 的映射（undefined 字段由 JSON.stringify 丢弃） */
 	toParams: (params: Static<S>) => Record<string, unknown>
+	/** 成功结果钩子（仅非错误通道结果触发）——notify-once 的 arm/label 缓存编排 */
+	onResult?: (ctx: ExtensionContext, params: Record<string, unknown>, result: unknown) => void
 }
 
 /**
@@ -163,7 +191,7 @@ function registerSessionTool<S extends TObject>(pi: ExtensionAPI, cfg: SessionTo
 			_onUpdate: unknown,
 			ctx: ExtensionContext,
 		) {
-			return executeTool(ctx, cfg.action, cfg.toParams(params));
+			return executeTool(ctx, cfg.action, cfg.toParams(params), cfg.onResult);
 		},
 	});
 }
@@ -172,22 +200,75 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 	// logger 持久化通道接入（appendEntry custom entry，不进 LLM 上下文）
 	setPiHandle(pi);
 
+	// watch 桥编排（notify-once U4）：工具结果 arm / watch 应答两层攒批 record /
+	// session_start 重启收口腿共用同一闭包状态（label 缓存 + 死亡新闻槽 + 攒批队列）。
+	const coordinator = createWatchCoordinator({
+		pi,
+		callWatch: (ctx, notifyId) => callSessionManager(ctx, "watch", { notifyId }),
+	});
+
+	// 重启收口腿（D7③）：父 pi 死亡后永无 unregister 的活跃 type 'session' register
+	// 逐条重开 watch（入参 = entry id 即 notifyId），应答经 watch 处理链静默注销，
+	// 活跃集回归基线；每 entry 独立 handler（禁串行 await）在 coordinator 内保证。
+	// ledger 装配纪律①②（D3）：session_start 无条件 bind + recoverFromSession 成对
+	//（唯一装配方形态，与 subagent-workflow bindLedgerHostAndRecover 同款——先装配，
+	// 收口腿/watch 应答到达时消费面已就绪）。
+	pi.on("session_start", (_event: SessionStartEvent, ctx: ExtensionContext) => {
+		ensureLedgerBound(pi, ctx);
+		coordinator.recoverStaleRegisters(ctx);
+	});
+	// compactionCheck 接线（D3 装配纪律④，P-B4 降级——subagent-workflow 同款先例）
+	pi.on("session_compact", (_event: SessionCompactEvent, _ctx: ExtensionContext) => {
+		runLedgerCompactionCheck();
+	});
+
 	registerSessionTool(pi, {
 		name: "create_managed_session",
 		label: "Create Managed Session",
-		description: "Create a new agent-managed session in the specified working directory. Optionally provide an initial prompt, which is sent immediately (new sessions are always idle, so it is delivered directly). Returns a session ID and initial status. Requires the taiji desktop runtime; standalone pi CLI will time out.",
+		description:
+			"Create a new agent-managed session in the specified working directory. Optionally provide an initial prompt, which is sent immediately (new sessions are always idle, so it is delivered directly). Returns a session ID, initial status and willNotify: when a prompt is provided, exactly one completion notification is delivered to this session after that run finishes (see pending_notifications, type 'session'); without a prompt willNotify is false and no completion notification is sent. Terminal session death is notified once regardless. Requires the taiji desktop runtime; standalone pi CLI will time out.",
 		parameters: CreateManagedSessionParams,
 		action: "create",
-		toParams: (p) => ({ cwd: p.cwd, label: p.label, prompt: p.prompt }),
+		toParams: (p) => ({
+			cwd: p.cwd,
+			label: p.label,
+			prompt: p.prompt,
+			// 债权只可能在带 prompt 时产生（G1）——无 prompt 不携带 notifyId（缺省即不 arm）
+			notifyId: p.prompt !== undefined ? newNotifyId() : undefined,
+		}),
+		onResult: (ctx, params, result) => {
+			const r = asResultRecord(result);
+			if (!r || typeof r.sessionId !== "string") return;
+			const rawLabel =
+				typeof params.label === "string" && params.label !== "" ? params.label : undefined;
+			const name = rawLabel ?? r.sessionId;
+			coordinator.noteLabel(r.sessionId, name);
+			const notifyId = params.notifyId;
+			if (r.willNotify === true && typeof notifyId === "string") {
+				coordinator.armSessionNotify(ctx, notifyId, name);
+			}
+			if (typeof r.lifetimeNotifyId === "string") {
+				coordinator.armSessionNotify(ctx, r.lifetimeNotifyId, name);
+			}
+		},
 	});
 
 	registerSessionTool(pi, {
 		name: "send_to_session",
 		label: "Send to Session",
-		description: "Send a prompt/message to an existing managed session. The message is asynchronously queued: if the target session is busy (generating/compacting/running bash) it is delivered at its next turn boundary, and {queued: true} is returned immediately. On synchronous failure the tool returns an error result (isError) with a hint (check get_session_status, then retry). Requires the taiji desktop runtime; standalone pi CLI will time out.",
+		description:
+			"Send a prompt/message to an existing managed session. The message is asynchronously queued: if the target session is busy (generating/compacting/running bash) it is delivered at its next turn boundary, and {queued: true} is returned immediately. Returns willNotify: exactly one completion notification is delivered to this session when the queued message is consumed and that run finishes (several queued messages merge into a single notification with a count). On synchronous failure the tool call fails with an error (check get_session_status, then retry). Requires the taiji desktop runtime; standalone pi CLI will time out.",
 		parameters: SendToSessionParams,
 		action: "send",
-		toParams: (p) => ({ sessionId: p.sessionId, prompt: p.prompt }),
+		toParams: (p) => ({ sessionId: p.sessionId, prompt: p.prompt, notifyId: newNotifyId() }),
+		onResult: (ctx, params, result) => {
+			const r = asResultRecord(result);
+			if (!r || r.willNotify !== true) return;
+			const notifyId = params.notifyId;
+			const sessionId = params.sessionId;
+			if (typeof notifyId !== "string" || typeof sessionId !== "string") return;
+			coordinator.armSessionNotify(ctx, notifyId, coordinator.labelFor(sessionId));
+		},
 	});
 
 	registerSessionTool(pi, {
@@ -206,6 +287,20 @@ export default function sessionManagerExtension(pi: ExtensionAPI): void {
 		parameters: ListMySessionsParams,
 		action: "list",
 		toParams: () => ({}),
+		// label 缓存回填（D9 正常路径 label 源的兜底——进程重启后 create 缓存丢失，
+		// send 的文案/register name 退化为 sessionId 前先经 list 恢复真 label）
+		onResult: (_ctx, _params, result) => {
+			const r = asResultRecord(result);
+			if (!r || !Array.isArray(r.sessions)) return;
+			for (const item of r.sessions) {
+				const s = asResultRecord(item);
+				if (!s || typeof s.id !== "string") continue;
+				coordinator.noteLabel(
+					s.id,
+					typeof s.label === "string" && s.label !== "" ? s.label : s.id,
+				);
+			}
+		},
 	});
 
 	registerSessionTool(pi, {

package/src/notify-content.ts

@@ -0,0 +1,77 @@
+// src/notify-content.ts — managed session 完成/死亡通知文案与 details 构造（notify-once D9/U4）。
+//
+// buildBackflowContent 迁入（U3 裁决：completion-backflow 废弃后 extension 是唯一消费方，
+// extension 不能反向 import runtime 包）。形状保持现 backflow 文案：
+//   Managed session "<label>" (<sid>) finished with status "<status>"[ (exit code: N)].[ (fulfills N request(s))]
+//   Stderr: <tail 400 字截尾>        （stderr 非空时）
+//   Full transcript: <sessionFilePath>（watch respond payload 已携该字段——u-protocol
+//     d69583684；runtime 查得到即携、查不到不携，不携时整行省略语义不变）。
+//
+// label 两路径（U4）：正常路径 = 工具入参 label（create 入参 / send 经 labelCache 回填）；
+// 重启收口腿 = pending:register 三键的 name。两条路径都汇入本函数的 params.label，
+// deathSeq 后 kind 不再决定文案（D3 例外2 内容确定性）。
+
+/** managed session 完成通知的送达 customType（D9）。与 packages/shared
+ *  COMPLETE_NOTIFY_CUSTOM_TYPES 追加值、core extractNotifyRecords 分支字面量三处同值，
+ *  改名需三处同步（shared 为渲染侧 SSOT，本包不能 import @taiji/shared——非依赖）。 */
+export const MANAGED_SESSION_NOTIFY_CUSTOM_TYPE = "managed-session-notify";
+
+/** stderr 摘要上限（截尾，迁移自 completion-backflow——诊断价值 > 完整性，防爆量撑爆文案） */
+const STDERR_TAIL_LIMIT = 400;
+
+export interface ManagedNotifyContentParams {
+	/** 会话标签（两路径汇入点，见文件头） */
+	label: string;
+	/** 子会话 id（watch respond payload 回带） */
+	sessionId: string;
+	/** 通知状态（settle: completed/failed/stopped；death: exited/deleted） */
+	status: string;
+	/** 本批销账的债权笔数（D3 合批 fulfills N；0/undefined → 不出行；纯死亡通知无债权） */
+	fulfills?: number;
+	/** transcript 指针行数据源（watch respond payload.sessionFilePath——u-protocol d69583684；
+	 *  runtime 查不到不携 → 缺席时整行省略） */
+	sessionFilePath?: string;
+	/** death 应答携带（D6 meta，exit 腿诊断通路复刻） */
+	exitCode?: number | null;
+	stderrTail?: string;
+}
+
+/**
+ * 构造通知正文（对齐 notifier buildLlmContent 模式：label/status + 指针行）。
+ * 纯函数，零 I/O——U6_UNIT 同族测试随迁（原 completion-backflow.test.ts 的纯函数组）。
+ */
+export function buildManagedNotifyContent(params: ManagedNotifyContentParams): string {
+	const exitNote =
+		params.exitCode !== undefined ? ` (exit code: ${params.exitCode ?? "null"})` : "";
+	const fulfillsNote =
+		params.fulfills !== undefined && params.fulfills > 0
+			? ` (fulfills ${params.fulfills} request${params.fulfills === 1 ? "" : "s"})`
+			: "";
+	let content = `Managed session "${params.label}" (${params.sessionId}) finished with status "${params.status}"${exitNote}.${fulfillsNote}`;
+	if (params.stderrTail && params.stderrTail.trim() !== "") {
+		const tail =
+			params.stderrTail.length > STDERR_TAIL_LIMIT
+				? params.stderrTail.slice(-STDERR_TAIL_LIMIT)
+				: params.stderrTail;
+		content += `\nStderr: ${tail.trim()}`;
+	}
+	if (params.sessionFilePath) {
+		content += `\nFull transcript: ${params.sessionFilePath}`;
+	}
+	return content;
+}
+
+/**
+ * record 的投递 details（ledger record 第三参）——core `extractNotifyRecords`
+ * 的 `managed-session-notify` 分支读 `notifyId`（去重键）与 `reason`（outcome 映射
+ * completed→success / failed→failed / 其余 neutral，D9）。其余字段为诊断冗余。
+ */
+export interface ManagedNotifyDetails {
+	/** 本批 record 的幂等键 = 批内首个响应的 notifyId（≤1 record/批由合批边界保证） */
+	notifyId: string;
+	sessionId: string;
+	reason: string;
+	/** 批内销账笔数（runtime fulfillsN 直供，缺省回退批长——见 watch-coordinator） */
+	fulfills: number;
+	label: string;
+}

package/src/notify-ledger.ts

@@ -0,0 +1,121 @@
+// src/notify-ledger.ts — notify-ledger（B-ledger）装配与 record 消费（notify-once D3 装配纪律）。
+//
+// canonical 消费面（D-10 领地补录后落地）：@zhushanwen/subagent-core 的
+// getBoundNotifyLedger / bindNotifyLedgerHost——Symbol.for 进程级单例槽跨扩展 bundle
+// 共享同一 ledger 实体（C-ext-06），本包不再持有任何槽镜像。
+//
+// 装配纪律（D3）对照（session_start 无条件重装配方，与 subagent-workflow
+// bindLedgerHostAndRecover 同款；旧「查槽短路」形态已废）：
+//   ① session_start 无条件 bindNotifyLedgerHost(host).recoverFromSession() 成对——host
+//      捕获当次 session 的 pi/ctx，不查槽短路（与 subagent-core 每次 session_start 重
+//      bind 的设计假设对齐：槽上永不残留捕获旧 ctx 的 host）；
+//   ② recover 吸收 session 文件全部既有条目（G3 重启重放即 recoverFromSession 语义）；
+//   ③ 双 bind 收敛：后 bind 者 dispose 前实例 + recover → 单实例全量态，前者的已落盘
+//      条目无损（record 先 appendEntry 落盘后内存更新——notify-ledger-discipline 用例钉住）。
+//      收敛由 subagent-core bindNotifyLedgerHost 的 dispose 旧实例语义保证，装配方无需
+//      自查槽（subagent-core 侧 bind 用模块级单例 handler + boundLedger 引用切换，
+//      重 bind 不累积物理监听）；
+//   ④ compactionCheck 同批接线（session_compact handler，P-B4 降级——
+//      subagent-workflow 同款先例；两侧对同一槽实例重复调用为幂等 no-op）；
+//   ⑤ 消费点恒经 getBoundNotifyLedger() 动态查槽，禁缓存实例引用——后 bind 方 dispose
+//      旧实例后缓存引用的 record() 静默 return false 零日志，对半概率丢全部通知。
+//
+// 唯一装配方形态（拓扑假设）：taiji runtime 每 session 重 spawn pi 进程，进程内无
+// session 替换——session_start 触发时本包是该 session ledger 的唯一装配方（与
+// subagent-workflow 共存时按 ③ 收敛）。stale ctx 面因此收窄，sendDelivery 的
+// guardStaleCtx 为防御性兜底（异常形态留痕归因，非正常路径承重）。
+//
+// 槽空降级（record 时点仍无实例：session_start 未跑 / bind 失败）：warn 留痕 + false
+//（STANDARDS §11.1 通知类接入点降级，非静默吞）。
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindNotifyLedgerHost, getBoundNotifyLedger } from "@zhushanwen/subagent-core";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { createPiNotifyLedgerHost } from "@zhushanwen/pi-notify-ledger-host";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+import {
+	MANAGED_SESSION_NOTIFY_CUSTOM_TYPE,
+	type ManagedNotifyDetails,
+} from "./notify-content.ts";
+
+const logger = getLogger("session-manager");
+
+/**
+ * 装配纪律 ①②（session_start 调用）：无条件 bind + recover 成对。
+ * host 五端口的 pi 接线（appendEntry / getEntries / isIdle / agent_settled /
+ * sendMessage + 送达 stale 防御）收敛在共享工厂 @zhushanwen/pi-notify-ledger-host
+ * ——与 subagent-workflow 同一工厂（同一槽的两处装配方，host 接口一致才能互换
+ * 消费），本包以 component/logger/warn 前缀参数化（label = session-manager:*、
+ * stale warn 文案带 "[session-manager] " 前缀，归因不串包）。
+ * 装配失败不阻断 session_start（record 侧走槽空降级）。
+ */
+export function ensureLedgerBound(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	try {
+		// ①② bind + recover 成对（G3 重启重放 = recoverFromSession 既有语义；
+		// 双 bind 收敛 = subagent-core dispose 旧实例语义，见文件头 ③）
+		bindNotifyLedgerHost(
+			createPiNotifyLedgerHost(pi, ctx, {
+				component: "session-manager",
+				logger,
+				staleWarnPrefix: "[session-manager] ",
+			}),
+		).recoverFromSession();
+	} catch (err) {
+		logger.warn("[session-manager] notify ledger bind failed (record degrades until next session_start)", {
+			error: toErrorMessage(err),
+		});
+	}
+}
+
+/**
+ * 记账一条通知（B-ledger ① record，deliveryCustomType 走 managed-session-notify 外部通道，
+ * 逐条投递不合批——合批已在 watch-coordinator 微窗内重建批身份，D3 裁决4）。
+ * 装配纪律⑤：每次调用即到即读查槽，禁存实例引用；槽空 → warn 降级 + false。
+ */
+export function recordManagedNotify(
+	notifyId: string,
+	content: string,
+	details: ManagedNotifyDetails,
+): boolean {
+	const ledger = getBoundNotifyLedger();
+	if (!ledger) {
+		logger.warn(
+			"[session-manager] notify ledger not bound — notification dropped (ensureLedgerBound 未跑或 bind 失败；下次 session_start 重试装配)",
+			{ notifyId },
+		);
+		return false;
+	}
+	try {
+		return ledger.record(notifyId, content, details, {
+			deliveryCustomType: MANAGED_SESSION_NOTIFY_CUSTOM_TYPE,
+		});
+	} catch (err) {
+		// 写入异常（stale ctx / appendEntry 失败）按接入点降级：不拖垮 watch 应答编排
+		//（unregister 照常），warn 留痕可归因
+		logger.warn("[session-manager] notify ledger record failed", {
+			notifyId,
+			error: toErrorMessage(err),
+		});
+		return false;
+	}
+}
+
+/**
+ * compactionCheck 接线（装配纪律④，P-B4 降级——subagent-workflow session_compact 同款）：
+ * 检测 ledger/ack entry 被 compaction 清除时按内存态补写（未清除即 0，幂等 no-op）。
+ */
+export function runLedgerCompactionCheck(): void {
+	try {
+		const rewritten = getBoundNotifyLedger()?.compactionCheck() ?? 0;
+		if (rewritten > 0) {
+			logger.warn(
+				`[session-manager] notify ledger entries lost to compaction; rewrote ${rewritten} from memory`,
+			);
+		}
+	} catch (err) {
+		logger.warn("[session-manager] notify ledger compactionCheck failed", {
+			error: toErrorMessage(err),
+		});
+	}
+}