@shgroup/dsh-serenity-hooks 1.34.0 → 1.34.2

package/lib/autopilot-trajectory-D9Znxo75.js

@@ -0,0 +1,782 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { i as hostSessions, t as hostAgents } from "./access-fiehjxV6.js";
+import { r as cccRootForCwd } from "./ccc-roots-Bd_SjEs7.js";
+import { p as sessionEvents } from "./trajectory-ops-mrXK0H0I.js";
+import { r as readLastBound } from "./trajectory-bound-Cax1p9ut.js";
+import { _ as shouldWake, a as TICK_MS, d as isAutopilotSession, g as resolveTargetMd, i as MIN_INTERVAL_HOURS, l as fetchBiasContent, m as readSelfGeneratedMotivation, n as DEFAULT_AVOID_HOURS, p as readAutopilotSettings, s as beijingHour, u as inAllowedWakeWindow } from "./autopilot-core-DCRkiWEe.js";
+import { t as readSimpleSettings } from "./settings-section-DTYZjwUs.js";
+import { basename, dirname } from "node:path";
+import { statSync } from "node:fs";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region src/clock-runtime.ts
+/**
+* clock-runtime.ts — **时钟运行时工厂**（S142 §38 复审候选 C6b，路径 **P2**）
+*
+* 本仓有**两条各自独立运行**的 5min 时钟：
+*   · 唤醒调度器（`wake-scheduler.ts`，一次性唤醒，D58）
+*   · autopilot 时钟（`autopilot-trajectory.ts`，周期自唤醒，D59）
+* 二者的**业务判据完全不同**（谁来扫 / 扫什么 / 投递给谁 / 按什么周期），但**引擎骨架逐字同形**
+* ——进程态 + 快照 + 复位 + `startTimer` + tick 外壳 + 事件接线 + disposer + `timer.unref()`。
+* 本条把**引擎**抽到本工厂，**各钟仍各持自己的定时器与自己的串行链**。
+*
+* ───────────────────────────────────────────────────────────────────────────
+* 🔴 硬约束一：**两条时钟绝不可共用"排队执行"的链**（这是 P2 与 P1 的分界判据）
+*
+* autopilot 每轮要跑该 CCC 的**偏见脚本**（`fetchBiasContent`，超时 60s），可能阻塞数十秒；
+* 若与唤醒调度器共用一条串行链，会把另一条一起**卡住**（一次性唤醒被无关的偏见脚本拖住）。
+* ⇒ 本工厂把 `chain` 作为**每实例私有状态**：`createClock()` 调用一次 = 一条独立的串行域。
+*    实例之间**零共享**（无模块级单例、无共享 Promise、无共享 map）。
+* ⚠️ 若日后有人把 `chain` 提到模块级"省一次分配"，**两条时钟的隔离即刻失效**——不许。
+*
+* 🔴 硬约束二：**武装门只判全局闸**（`gate()`），**不判"本次有无目标"**
+*
+* 2026-09-14 F 段实测缺陷：旧实现把"有 live CCC"当**武装前置条件**，而宿主刚重启时 live 会话
+* 必为空，且**"恢复旧会话"不触发 `session/created`**（只有新建会）⇒ 启动瞬间判定落空 =
+* **时钟永久不武装**（实测 6.6h 零 tick）。⇒ 现在「**全局闸开即武装**」，"有无目标"降级为
+* tick 内的廉价判定。**武装与"本次有无目标"是两件事，本工厂不得把二者耦合。**
+*
+* 🔴 硬约束三：**两条闸必须继续分开传**（v1.34 S-1 解耦）
+*
+* 唤醒调度器 `wakeSchedulerEnabled`（**缺省开**）｜autopilot `autopilotWakeEnabled`
+* （**缺省关**）——取值方向相反。工厂取 `gate` **回调**（每次现读），**不做**任何合并或缓存。
+*
+* ───────────────────────────────────────────────────────────────────────────
+* 两条时钟**逐项语义差**（`ClockOptions` 的每个可配项都对应下表一行，不是随意的灵活性）：
+*
+* | 项 | 唤醒调度器 | autopilot | 工厂表达 |
+* |----|-----------|-----------|---------|
+* | `chain` | 有（全局串行） | 有（全局串行） | **总是私有**（硬约束一） |
+* | `lastTickLog` | 有（逐行摘要） | **无** | `logFrom` 不给 = 不记 |
+* | `ticks` 记账 | 工厂在 body **完成后**记 | **本钟**在同步段记 | `bodyCountsTick` + `begin` |
+* | body 返回类型 | `string[]`（人读摘要） | `void` | 泛型 `T` |
+* | 启动日志 | 固定串 | 含启用 CCC 计数 | `startLog: () => string` |
+* | body 异常兜底 | 留痕 + `console.warn` | 同 | 工厂统一（**吞异常不改语义**） |
+*
+* ───────────────────────────────────────────────────────────────────────────
+* **本工厂是"加法式"重构**（P2 的性质）：不新增任何判定逻辑，只把同形骨架收成一份代码；
+* 两个模块仍各自导出 `wakeSchedulerState()` / `autopilotClockState()` 与各自的
+* `__reset…ForTest()`，**对外可观测面（字段名与语义）零变化**——`acc-diag` ①b 段、
+* `container-status.ts:containerClocks()` 与面板都在读它们（见该文件 :225–250 的设计红线）。
+*
+* 为什么**不**取 P1（真合并成一个 `setInterval` + 两条策略）——2026-09-15 所有者裁决：
+* P1 只多省 ~20 行，却要把 `armed` 拆成"宿主 + 每策略"两层、并强行分开串行域，
+* 即**动两条正在跑的时钟的骨架**；**不值当**（裁决原文见 SESSION §12.8②）。
+*/
+/**
+* 挂事件 → 触发 `start()`（**每个事件一次 try/catch 吞异常**：事件通道缺失不阻断时钟）。
+*
+* 为什么吞异常：宿主（headless profile 等）可能没有事件通道；**启动时已 `start()` 过一次**，
+* 事件只是"跟上面板开关 / 新会话"的热启动补丁，缺它不该让整个装配抛错。
+* @param on 宿主的 `on`（可能不存在）
+* @param ctx `on` 的 `this`（宿主 API 常要求绑定）
+* @param clock 目标时钟
+* @param events 事件名列表（回调恒为 `() => clock.start()`）
+*/
+function attachClockEvents(ctx, clock, events) {
+	const on = ctx?.on;
+	if (typeof on !== "function") return;
+	for (const name of events) try {
+		on.call(ctx, name, () => clock.start());
+	} catch {}
+}
+/**
+* 建一条时钟（**每钟各调一次**——本工厂**不是**单例，调用次数 = 时钟条数）。
+*
+* 顺序忠实于既有实现：`start()` 先武装并立即跑一次 tick → 再挂事件。
+* 拆卸由调用方经 `registerDisposer(ctx, label, clock.dispose)` 落到宿主的 `ctx.effect`。
+* @param opts 见 {@link ClockOptions}（每项对应一条既有的语义差）
+* @returns 该钟的 `{start, dispose, snapshot, reset}`
+*/
+function createClock(opts) {
+	const runtime = {
+		armed: false,
+		armedAt: null,
+		lastTickAt: null,
+		ticks: 0,
+		lastSkipReason: null
+	};
+	if (opts.logFrom) runtime.lastTickLog = [];
+	const st = {
+		timer: null,
+		chain: Promise.resolve(),
+		runtime,
+		wired: false,
+		opts
+	};
+	/** 记一次 tick（工厂内部与 body 共用同一实现——只有一处会计逻辑） */
+	const countTick = () => {
+		runtime.lastTickAt = Date.now();
+		runtime.ticks += 1;
+	};
+	/** 逐行打印（`logFrom` 缺省 ⇒ 本钟无 tick 日志，整段为死代码路径） */
+	const emit = (lines) => {
+		if (!opts.logFrom) return;
+		for (const line of lines) console.log(`${opts.logFrom.prefix}${line}`);
+	};
+	const tick = () => {
+		if (!opts.gate()) {
+			runtime.lastSkipReason = opts.gateOffReason;
+			return;
+		}
+		if (opts.begin) try {
+			opts.begin();
+		} catch (err) {
+			console.warn(`[serenity-hooks] ✗ tick 前置异常: ${String(err?.message ?? err)}（${opts.label}）`);
+			return;
+		}
+		st.chain = st.chain.then(async () => {
+			try {
+				const value = await opts.body();
+				if (!opts.bodyCountsTick) countTick();
+				if (opts.logFrom) {
+					runtime.lastTickLog = opts.logFrom.lines(value);
+					emit(runtime.lastTickLog);
+				}
+			} catch (err) {
+				const msg = `✗ tick 异常: ${String(err?.message ?? err)}`;
+				if (opts.logFrom) runtime.lastTickLog = [msg];
+				console.warn(`[serenity-hooks] ${msg}（${opts.label}）`);
+			}
+		});
+	};
+	/**
+	* 幂等启动 + 武装门：**已武装 → 原样返回**（防重复起定时器）；
+	* **闸关 → 不武装**（零资源占用）；闸开则**无条件**武装（硬约束二：不判"有无目标"）。
+	*/
+	const start = () => {
+		if (st.timer) return;
+		if (opts.events && !st.wired) {
+			st.wired = true;
+			attachClockEvents(opts.ctx, api, opts.events);
+		}
+		if (!opts.gate()) return;
+		st.timer = setInterval(tick, TICK_MS);
+		st.timer.unref();
+		runtime.armed = true;
+		runtime.armedAt = Date.now();
+		console.log(opts.startLog());
+		if (opts.immediate !== false) tick();
+	};
+	const dispose = () => {
+		if (st.timer) {
+			clearInterval(st.timer);
+			st.timer = null;
+		}
+		runtime.armed = false;
+		runtime.armedAt = null;
+		opts.onDispose?.();
+	};
+	const api = {
+		start,
+		dispose,
+		snapshot: () => ({
+			enabled: opts.gate(),
+			...runtime,
+			...runtime.lastTickLog ? { lastTickLog: [...runtime.lastTickLog] } : {}
+		}),
+		noteSkipReason: (reason) => {
+			runtime.lastSkipReason = reason;
+		},
+		countTick,
+		enqueue: (work) => {
+			st.chain = st.chain.then(work, () => void 0).then(() => void 0, (err) => {
+				console.warn(`[serenity-hooks] ✗ 串行任务异常（${opts.label}）: ${String(err?.message ?? err)}`);
+			});
+		},
+		reset: () => {
+			if (st.timer) {
+				clearInterval(st.timer);
+				st.timer = null;
+			}
+			runtime.armed = false;
+			runtime.armedAt = null;
+			runtime.lastTickAt = null;
+			runtime.ticks = 0;
+			runtime.lastSkipReason = null;
+			if (opts.logFrom) runtime.lastTickLog = [];
+			st.wired = false;
+			opts.onReset?.();
+		}
+	};
+	return api;
+}
+//#endregion
+//#region src/host/effect.ts
+/** 已告警的标签（进程级去重：重复装配/多测试替身不刷屏，但绝不静默） */
+const warnedLabels = /* @__PURE__ */ new Set();
+/**
+* 登记一个卸载时执行的清理。
+* @param ctx 宿主插件上下文
+* @param label 日志标签（定位是哪个资源未装配）
+* @param cleanup 卸载时执行；抛错被吞掉（不阻断其它清理）
+* @returns 是否成功装配（false = 宿主无 `ctx.effect`，已告警）
+*/
+function registerDisposer(ctx, label, cleanup) {
+	const effect = ctx?.effect;
+	if (typeof effect !== "function") {
+		if (!warnedLabels.has(label)) {
+			warnedLabels.add(label);
+			console.warn(`[serenity-hooks] ✗ 资源拆卸未装配（${label}）：ctx.effect 不可用（宿主契约缺失）`);
+		}
+		return false;
+	}
+	try {
+		effect.call(ctx, () => () => {
+			try {
+				cleanup();
+			} catch (err) {
+				console.warn(`[serenity-hooks] ✗ 资源清理失败（${label}）: ${String(err?.message ?? err)}`);
+			}
+		}, `dsh-serenity-hooks: ${label}`);
+		return true;
+	} catch (err) {
+		console.warn(`[serenity-hooks] ✗ 资源拆卸注册失败（${label}）: ${String(err?.message ?? err)}`);
+		return false;
+	}
+}
+//#endregion
+//#region src/autopilot-trajectory.ts
+var autopilot_trajectory_exports = /* @__PURE__ */ __exportAll({
+	AUDIT_HISTORY_MAX: () => 50,
+	autopilotClockState: () => autopilotClockState,
+	autopilotGloballyEnabled: () => autopilotGloballyEnabled,
+	autopilotRuntimeFacts: () => autopilotRuntimeFacts,
+	autopilotWakeInFlight: () => autopilotWakeInFlight,
+	buildWakeMessage: () => buildWakeMessage,
+	collectAutopilotCccs: () => collectAutopilotCccs,
+	diagLive: () => diagLive,
+	getAutopilotStatus: () => getAutopilotStatus,
+	listLiveSessions: () => listLiveSessions,
+	performAutopilotWake: () => performAutopilotWake,
+	recordWake: () => recordWake,
+	registerAutopilot: () => registerAutopilot,
+	wakeHistoryFor: () => wakeHistoryFor
+});
+const PLUGIN_SOURCE = {
+	kind: "plugin",
+	plugin: "dsh-serenity-hooks"
+};
+/** 唤起消息（四段式：轨迹焦点[CCC 定义，稳定] / 身份锚定 / 先验偏见[自生动机+偏见内容] / 任务）——注入前台会话，用户可见 */
+function buildWakeMessage(opts) {
+	const intervalLabel = opts.intervalHours >= 1 ? `${opts.intervalHours} 小时` : `约 ${Math.round(opts.intervalHours * 60)} 分钟`;
+	const lines = [];
+	if (opts.topPrompt) {
+		lines.push(`[轨迹焦点] ${opts.topPrompt}`);
+		lines.push("");
+	}
+	lines.push(`[Autopilot Trajectory · 唤起] — 距上次轨迹活动已满 ${intervalLabel}，自动继续。`, "", `身份锚定：继续 ${opts.sessionName} 的 trajectory（SESSION.md: ${opts.mdPath}）。`, "先验偏见：");
+	if (opts.motivation) lines.push(`  · 自生动机：${opts.motivation}`);
+	if (opts.biasContent) lines.push(`  · 偏见内容：${opts.biasContent}`);
+	if (!opts.motivation && !opts.biasContent) lines.push("  · （无——本轮纯自主探索）");
+	lines.push("", "任务：执行一轮自主认知（探索/反事实检验），把产出写入 SESSION.md", "「自主探索日志」段，并预写「下一轮动机」段。完成后自然结束。");
+	return lines.join("\n");
+}
+/** 审计历史（root → 最近唤醒记录；进程生命周期；上限 AUDIT_HISTORY_MAX/CCC） */
+const wakeHistory = /* @__PURE__ */ new Map();
+/** 追加审计记录（ring 截断） */
+function recordWake(root, rec) {
+	const list = wakeHistory.get(root) ?? [];
+	list.push(rec);
+	if (list.length > 50) list.splice(0, list.length - 50);
+	wakeHistory.set(root, list);
+}
+/** 读审计历史（root 的最近记录；无 → []） */
+function wakeHistoryFor(root) {
+	return [...wakeHistory.get(root) ?? []];
+}
+/**
+* 执行一次唤起（时钟 tick 与面板「立即唤起」共用）：
+* - force=false（时钟）：完整校验——enabled / 目标命中 / --auto 标志 / 窗口 / 间隔 / 偏见脚本
+* - force=true（手动调试，用户在场）：跳过窗口/间隔，仍校验 enabled / 目标命中 / --auto / 偏见脚本
+*   （v1.27.12 移除每日唤起预算——force 无预算可跳，时钟也不受限）
+* 成功 → 注入前台会话（agent.steer，用户可见）；返回结果供调用方（tick 打日志 / 面板显示 / 审计）。
+*/
+async function performAutopilotWake(ctx, root, settings, opts = {}) {
+	if (!settings?.enabled) return {
+		ok: false,
+		detail: "Autopilot Trajectory 未启用（enabled=false）"
+	};
+	const mdPath = resolveTargetMd(root, settings);
+	if (!mdPath) return {
+		ok: false,
+		detail: "目标会话未命中（session 未配置或 AGENT_SESSIONS 无匹配）"
+	};
+	if (!isAutopilotSession(mdPath)) return {
+		ok: false,
+		detail: "目标会话目录无 --auto 标志（AGENT_SESSIONS/<date>--<desc>--auto/）"
+	};
+	if (!opts.force) {
+		const now = Date.now();
+		if (!inAllowedWakeWindow(now, settings.avoidWakeHours)) return {
+			ok: false,
+			detail: "当前在北京高峰避开窗口内（不唤起）"
+		};
+		try {
+			const mtime = statSync(mdPath).mtimeMs;
+			const hours = Math.max(MIN_INTERVAL_HOURS, settings.intervalHours ?? 12);
+			if (now - mtime < hours * 36e5) return {
+				ok: false,
+				detail: `距上次轨迹活动不足 ${hours}h（等待中）`
+			};
+		} catch {
+			return {
+				ok: false,
+				detail: "SESSION.md 读取失败（statSync）"
+			};
+		}
+	}
+	const agent = resolveTargetAgent(ctx, mdPath);
+	if (!agent) return {
+		ok: false,
+		detail: `目标会话 agent 不可得——${diagnoseTargetUnavailable(ctx, mdPath) ?? "目标会话未打开或命名未生效"}`
+	};
+	const provider = settings.biasProvider?.trim() || "autopilot-bias.ts";
+	const biasRes = await fetchBiasContent(root, provider);
+	if (biasRes.error) return {
+		ok: false,
+		detail: `偏见内容缺失：${biasRes.error}`
+	};
+	const motivation = readSelfGeneratedMotivation(mdPath);
+	const message = buildWakeMessage({
+		sessionName: basename(dirname(mdPath)),
+		mdPath,
+		intervalHours: Math.max(MIN_INTERVAL_HOURS, settings.intervalHours ?? 12),
+		topPrompt: settings.topPrompt?.trim() || null,
+		motivation,
+		biasContent: biasRes.text
+	});
+	agent.steer(createUserMessage({
+		content: [{
+			type: "text",
+			text: message
+		}],
+		source: PLUGIN_SOURCE
+	}));
+	return {
+		ok: true,
+		detail: `已唤起 ${basename(dirname(mdPath))}（偏见提供者 ${provider}）`
+	};
+}
+/**
+* **周期自唤醒全局闸**（v1.34 更名收窄，原 `autopilotEnabled`）：关 = 定时器不武装 + tick 不唤起。
+*
+* 语义边界（用户 2026-09-15 裁决 S-1）：**只管周期自唤醒** —— 一次性唤醒（`container_trajectory wake-later`）
+* 归 `wakeSchedulerEnabled`，两者**互不连带**（旧实现共用一闸是缺陷，见 wake-scheduler 注释）。
+*
+* 读取顺序（迁移期，不回写）：`autopilotWakeEnabled`（新键）→ `autopilotEnabled`（旧键）→ false。
+* 用 `??` 而非 `||` 的理由：**新键显式 false 必须能覆盖旧键 true**（否则"关不掉"）。
+* 抽成模块级函数是为了让 {@link autopilotClockState}（诊断）与 tick 读**同一判据**。
+*
+* v1.34.1（⑥ C6a）：**导出**——CCC 工具面（`container_admin autopilot status`）与条件链
+* （{@link autopilotRuntimeFacts}）必须读**这一份**闸值。旧独立脚本读不到它 ⇒ 闸关着也印
+* 「✅ 唤起条件全部满足」（8 项分歧之首，见 SESSION §12.13 与现状稿 §4.4）。
+*/
+function autopilotGloballyEnabled() {
+	try {
+		const s = readSimpleSettings();
+		return s.autopilotWakeEnabled ?? s.autopilotEnabled ?? false;
+	} catch {
+		return false;
+	}
+}
+/**
+* 🔴 **本钟的串行域**（C6b 硬约束）：`clock.chain` 是**本实例私有**的——
+* 与唤醒调度器的串行链**零共享**。本钟每轮要跑 CCC 的偏见脚本（`fetchBiasContent`，
+* 超时 60s），可能阻塞数十秒；共用链会把另一条钟一起卡住（这正是 P1 被否、取 P2 的理由，
+* 见 SESSION §12.8②）。**这就是"两条时钟不共用排队执行链"的落点。**
+*
+* **为什么这里是模块级常量**（而不是 `registerAutopilot` 的局部量）：本钟的进程态是
+* **进程级可观测面**（`acc-diag` ①b / `containerClocks` / `autopilot-ops.runtimeBlock` 在读），
+* 且 `autopilotClockState()` / `__resetAutopilotClockStateForTest()` 是**公开导出**、
+* 可在未装配时被调用 ⇒ 实例必须**恒在**（旧实现的 `clockRuntime` 也正是模块级常量）。
+* 装配只做 `clock.start()`。
+*/
+const clockOpts = {
+	label: "Autopilot Trajectory 时钟",
+	ctx: void 0,
+	events: ["session/created", "serenity/settings-changed"],
+	gate: autopilotGloballyEnabled,
+	gateOffReason: "周期自唤醒闸关闭（autopilotWakeEnabled=false）",
+	bodyCountsTick: true,
+	begin: () => runAutopilotBegin(clockOpts.ctx),
+	body: () => runAutopilotTick(clockOpts.ctx),
+	startLog: () => `[serenity-hooks] ✓ Autopilot Trajectory 定时器启动（${collectAutopilotCccs(clockOpts.ctx).length} 个 CCC 启用）`,
+	onReset: () => runningByRoot.clear()
+};
+const clock = createClock(clockOpts);
+/**
+* autopilot **进程态**快照（只读；`enabled` = 全局闸**当前**值）。
+* ⚠️ 与 {@link wakeSchedulerState} 同规格，但**本钟无 `lastTickLog`**（见 {@link ClockOptions.logFrom}）。
+*/
+function autopilotClockState() {
+	return clock.snapshot();
+}
+/**
+* **重入守卫状态**（per-CCC：该 CCC 是否有一轮唤起正在进行）。
+*
+* 模块级而非常量闭包（⑥ C6a）：条件链要如实回答"此刻是否已有唤起在跑"——旧独立脚本
+* **完全没有这一判据**（8 项分歧之一）。若在 `registerAutopilot` 闭包里再造一份镜像 map，
+* 就是"两份判断"；故状态**提到模块级**，tick 与诊断读**同一张表**。
+* 与既有 `wakeHistory` 同规格（它本就是模块级进程态）。
+*/
+const runningByRoot = /* @__PURE__ */ new Map();
+/** 该 CCC 是否有唤起轮正在进行中（tick 的 per-CCC 防重入判据；诊断读同一份） */
+function autopilotWakeInFlight(root) {
+	return runningByRoot.get(root) === true;
+}
+/**
+* 装配（index.ts apply 调用）。时钟唤起（v1.26.14 修复 + v1.27.4 多 CCC 独立）：
+*
+* v1.26.14 根因：旧实现启动时一次性解析 root——web 进程启动时 live 会话往往为空 → 定时器不启动。
+* 修复：① 每次 tick 动态解析 root+settings ② 监听 session/created 启动定时器 ③ 优先实验 CCC。
+*
+* **v1.27.4 多 CCC 独立（用户"4个CCC能各自有autotrajectory吗"）**：
+* - 单定时器保留（TICK_MS 5min），每次 tick **遍历所有 live+enabled CCC**（collectAutopilotCccs）
+*   各自评估 shouldWake + 各自唤起——每 CCC 的 interval/session/bias/topPrompt/窗口独立
+* - `running` 守卫 **per-CCC**（不同 CCC 唤起互不阻塞）
+* - **全局串行化**（wakeChain：同 tick 多 CCC 到点 → 依次唤起，防模型并发挤兑）
+*
+* 零资源占用语义保留：无 enabled CCC → tick 内直接 return（定时器存在但每 5min 一次空检查，
+* unref 不阻塞进程退出）。
+*/
+function registerAutopilot(ctx) {
+	clockOpts.ctx = ctx;
+	clock.start();
+	registerDisposer(ctx, "autopilot 时钟", () => clock.dispose());
+}
+/**
+* tick 的**同步前置阶段**（`clock-runtime` 在 body 前同步调用）——判据**一行未改**：
+* 枚举 live+enabled CCC；为空 ⇒ 记跳过原因且**不计 tick**；非空 ⇒ 清空跳过原因并记一次 tick。
+*
+* ⚠️ 为什么与 {@link runAutopilotTick} 分开（不是风格，是**观测面正确性**）：
+* 本钟的 `ticks` / `lastSkipReason` 在旧实现里是在 tick 的**同步段**定下来的——诊断
+* （`autopilot-ops.runtimeBlock` / `autopilotClockState()`）在"启动即 tick"的那一瞬间就要读到
+* 本拍的值。若把它们挪进 async body，那一瞬间会读到上一拍的旧值（假报告）。
+* 两条回归钉守着这一点：『启动时无 live 会话 ⇒ ticks=0 + skipReason 留痕』
+* 与『配置关闭 ⇒ ticks=0』（`tests/autopilot-trajectory.test.ts`）。
+* @param ctx 插件上下文
+*/
+function runAutopilotBegin(ctx) {
+	if (collectAutopilotCccs(ctx).length === 0) {
+		clock.noteSkipReason("无 live+enabled CCC（等会话出现 / 配置生效）");
+		return;
+	}
+	clock.noteSkipReason(null);
+	clock.countTick();
+}
+/**
+* 一次 autopilot tick 的**业务体**（引擎外壳由 `clock-runtime` 提供）。
+*
+* 判据**一行未改**，仍全部本函数自持：枚举 live+enabled CCC → 逐 CCC 防重入 +
+* `shouldWake` 评估 → 命中者接到**本钟私有**串行链尾（`clock.enqueue`）。
+* 同步的"记账/跳过留痕"在 {@link runAutopilotBegin}。
+* @param ctx 插件上下文
+*/
+function runAutopilotTick(ctx) {
+	const roots = collectAutopilotCccs(ctx);
+	if (roots.length === 0) return;
+	for (const root of roots) {
+		if (runningByRoot.get(root)) continue;
+		const settings = readAutopilotSettings(root);
+		if (!settings?.enabled) continue;
+		const mdPath = resolveTargetMd(root, settings);
+		if (!shouldWake(settings, mdPath, Date.now(), false, wakeHistoryFor(root))) continue;
+		runningByRoot.set(root, true);
+		clock.enqueue(async () => {
+			try {
+				const res = await performAutopilotWake(ctx, root, settings, { force: false });
+				recordWake(root, {
+					time: Date.now(),
+					ok: res.ok,
+					detail: res.detail
+				});
+				if (res.ok) console.log(`[serenity-hooks] ✓ Autopilot Trajectory 唤起（${res.detail}）`);
+				else console.warn(`[serenity-hooks] ✗ Autopilot Trajectory 唤起跳过：${res.detail}`);
+			} catch (err) {
+				recordWake(root, {
+					time: Date.now(),
+					ok: false,
+					detail: `唤起异常: ${String(err?.message ?? err)}`
+				});
+				console.warn(`[serenity-hooks] ✗ Autopilot Trajectory 唤起失败: ${String(err?.message ?? err)}`);
+			} finally {
+				runningByRoot.set(root, false);
+			}
+		});
+	}
+}
+/**
+* 目标 agent：从 SESSION.md 反向定位 dsh 会话（cwd 归属校验 + **bound 精确匹配优先**，
+* 标题 F3 命名回退）；不可得 → null。
+*
+* v1.29.2（R2，用户"autopilot 会话绑定应当更稳固——唤起的时候能唤起最新的、
+* 绑定 autopilot SESSION 的会话"）：v1.29.1 `serenity/bound` 事件是权威绑定
+* （session use 激活时 append，dirName = 完整 AGENT_SESSIONS 目录名，编码无关 U4）。
+* 旧实现只按标题猜（=== sid / startsWith(sid-)）——若绑定该 SESSION 的 dsh 会话
+* 标题不是 S###- 前缀（LLM 改过/重建后 rename 异常），绑定明明在却唤起失败。
+* 加强：**bound.dirName 精确匹配优先**（权威证据），标题匹配降级为回退（存量
+* 无 bound 的 live 会话兼容）；多候选（罕见：同 SESSION 绑定多个 live 会话）取
+* **绑定最新**（bound.at 最大——最近 use 过 = 最可能当前在用）。
+*/
+function resolveTargetAgent(ctx, mdPath) {
+	const dirName = basename(dirname(mdPath));
+	const idMatch = dirName.match(/--S(\d{3,})--/);
+	const sid = idMatch ? `S${idMatch[1]}` : null;
+	const targetRoot = cccRootForCwd(mdPath);
+	const sessions = hostSessions(ctx);
+	const agents = hostAgents(ctx);
+	const candidates = [];
+	try {
+		for (const s of sessions?.list?.() ?? []) {
+			const sess = s;
+			const cwd = sess?.header?.cwd ?? "";
+			if (targetRoot) {
+				if (cccRootForCwd(cwd) !== targetRoot) continue;
+			} else if (cwd !== "" && !mdPath.startsWith(cwd.endsWith("/") ? cwd : cwd + "/")) continue;
+			const bound = readLastBound(sess);
+			const title = readSessionTitle(sess);
+			const boundMatched = bound !== null && bound.dirName === dirName;
+			const titleMatched = sid !== null && title !== null && (title === sid || title.startsWith(`${sid}-`));
+			if (boundMatched) candidates.push({
+				session: sess,
+				boundAt: bound?.at ?? null,
+				titleMatched
+			});
+			else if (titleMatched) candidates.push({
+				session: sess,
+				boundAt: null,
+				titleMatched
+			});
+		}
+	} catch {}
+	if (candidates.length === 0) return null;
+	candidates.sort((a, b) => {
+		const aBound = a.boundAt !== null;
+		if (aBound !== (b.boundAt !== null)) return aBound ? -1 : 1;
+		return (b.boundAt ?? 0) - (a.boundAt ?? 0);
+	});
+	for (const c of candidates) {
+		const agent = agents?.get?.(c.session.id ?? "");
+		if (agent) return agent;
+	}
+	return null;
+}
+/**
+* 从 dsh 会话 log 读取标题（latest-wins `session/title` 事件）——
+* **标题不在 sessions.list() 条目上**（wire/对象均无 title 字段；F3 命名经
+* sessionTitle.rename 写进 session log），必须从 events 提取（rebuild 同款读取模式）。
+*/
+function readSessionTitle(session) {
+	try {
+		const events = sessionEvents(session);
+		for (let i = events.length - 1; i >= 0; i--) {
+			const e = events[i];
+			if (e?.type === "session/title" && typeof e.data?.title === "string" && e.data.title.trim() !== "") return e.data.title.trim();
+		}
+	} catch {}
+	return null;
+}
+/**
+* 诊断：目标会话 agent 为何不可得（供 performAutopilotWake 失败信息——
+* 区分"无 live 会话" / "标题不匹配" / "bound 或标题命中但 agent 未加载"）。
+* v1.29.2（R2）：bound 命中但 agent 未加载也归入「已匹配未加载」（原只查标题）。
+* 返回诊断文本（无则 null）。
+*/
+function diagnoseTargetUnavailable(ctx, mdPath) {
+	const dirName = basename(dirname(mdPath));
+	const idMatch = dirName.match(/--S(\d{3,})--/);
+	const sid = idMatch ? `S${idMatch[1]}` : null;
+	const targetRoot = cccRootForCwd(mdPath);
+	const sameCccTitles = [];
+	const agentMissing = { matched: false };
+	try {
+		const sessions = hostSessions(ctx);
+		for (const s of sessions?.list?.() ?? []) {
+			const sess = s;
+			const cwd = sess?.header?.cwd ?? "";
+			if (targetRoot) {
+				if (cccRootForCwd(cwd) !== targetRoot) continue;
+			} else if (cwd !== "" && !mdPath.startsWith(cwd.endsWith("/") ? cwd : cwd + "/")) continue;
+			const bound = readLastBound(sess);
+			const title = readSessionTitle(sess);
+			if (title) sameCccTitles.push(title);
+			const boundMatched = bound !== null && bound.dirName === dirName;
+			const titleMatched = sid !== null && title !== null && (title === sid || title.startsWith(`${sid}-`));
+			if (boundMatched || titleMatched) {
+				if (!hostAgents(ctx)?.get?.(sess.id ?? "")) agentMissing.matched = true;
+			}
+		}
+	} catch {}
+	if (agentMissing.matched) return `会话已绑定/匹配 ${sid ?? dirName} 但 agent 未加载（会话可能刚创建/正在恢复——稍后重试）`;
+	if (sameCccTitles.length > 0) return `目标 CCC 内 live 会话标题: [${sameCccTitles.join(", ")}]——均不匹配 ${sid ?? dirName}（目标会话未在 WebUI 打开，或绑定/命名未生效）`;
+	return `目标 CCC 内无 live 会话（先在 WebUI 打开 ${sid ?? dirName} 会话后重试）`;
+}
+/** Autopilot 绑定的回退 CCC 根：进程 cwd 上溯 .serenity 优先，回退任一 live 会话 root */
+function resolveAutopilotRoot(ctx) {
+	const fromCwd = cccRootForCwd(process.cwd());
+	if (fromCwd) return fromCwd;
+	try {
+		const sessions = hostSessions(ctx);
+		for (const s of sessions?.list?.() ?? []) {
+			const r = cccRootForCwd(s?.header?.cwd ?? "");
+			if (r) return r;
+		}
+	} catch {}
+	return null;
+}
+function getAutopilotStatus(root) {
+	const cfg = readAutopilotSettings(root);
+	const now = Date.now();
+	const base = {
+		configured: cfg !== null,
+		enabled: cfg?.enabled ?? false,
+		intervalHours: Math.max(MIN_INTERVAL_HOURS, cfg?.intervalHours ?? 12),
+		biasProvider: cfg?.biasProvider?.trim() || "autopilot-bias.ts",
+		topPrompt: cfg?.topPrompt?.trim() || null,
+		session: cfg?.session ?? null,
+		avoidWakeHours: {
+			start: cfg?.avoidWakeHours?.start ?? DEFAULT_AVOID_HOURS.start,
+			end: cfg?.avoidWakeHours?.end ?? DEFAULT_AVOID_HOURS.end
+		},
+		beijingHour: beijingHour(now),
+		windowAllowed: inAllowedWakeWindow(now, cfg?.avoidWakeHours),
+		recentWakes: wakeHistoryFor(root).slice(-10).reverse()
+	};
+	if (!cfg) return {
+		...base,
+		target: null
+	};
+	const mdPath = resolveTargetMd(root, cfg);
+	if (!mdPath) return {
+		...base,
+		target: null
+	};
+	let idleHours = 0;
+	try {
+		idleHours = (now - statSync(mdPath).mtimeMs) / 36e5;
+	} catch {}
+	return {
+		...base,
+		target: {
+			dirName: basename(dirname(mdPath)),
+			autoFlag: isAutopilotSession(mdPath),
+			idleHours: Math.max(0, idleHours),
+			wakeable: shouldWake(cfg, mdPath, now, false, wakeHistoryFor(root))
+		}
+	};
+}
+/**
+* live 会话清单（诊断/面板解析用；标题从 events 读）——**只枚举 live 会话本身**。
+*
+* C2：CCC 枚举（"本机有哪些 CCC"）**不在这里**，归 `ccc-roots.listCccs`（并集）。
+* 本函数保留的是它**独有**的那部分：逐条 live 会话 + cwd 归属 + 标题 + id
+* （诊断页需要"哪个会话属于哪个 CCC"，那是会话维度、不是 CCC 维度）。
+* @param ctx 插件上下文
+* @returns 逐条 live 会话（`cccRoot` = 该会话 cwd 的 CCC 归属，无 → null）
+*/
+function listLiveSessions(ctx) {
+	const out = [];
+	try {
+		const sessions = hostSessions(ctx);
+		for (const s of sessions?.list?.() ?? []) {
+			const cwd = s?.header?.cwd ?? null;
+			out.push({
+				id: s?.id ?? "",
+				cwd,
+				cccRoot: cwd ? cccRootForCwd(cwd) : null,
+				title: readSessionTitle(s)
+			});
+		}
+	} catch {}
+	return out;
+}
+/**
+* 收集所有「配置了 Autopilot Trajectory 的 live CCC」——**v1.27.4 多 CCC 独立**：
+* 返回 enabled 的 CCC 列表（时钟 tick 遍历目标）；无 enabled → []。
+* （原 resolveAutoTrajectoryCcc 单目标语义被 collect 取代——面板/诊断用 enableOnly=false 取全量）
+*/
+function collectAutopilotCccs(ctx, opts = {}) {
+	const enabled = [];
+	const configured = [];
+	for (const s of listLiveSessions(ctx)) {
+		if (!s.cccRoot) continue;
+		const cfg = readAutopilotSettings(s.cccRoot);
+		if (!cfg) continue;
+		if (cfg.enabled) {
+			if (!enabled.includes(s.cccRoot)) enabled.push(s.cccRoot);
+		} else if (!configured.includes(s.cccRoot)) configured.push(s.cccRoot);
+	}
+	return opts.includeDisabled ? [...enabled, ...configured] : enabled;
+}
+function diagLive(ctx) {
+	const liveSessions = listLiveSessions(ctx);
+	const processCwd = process.cwd();
+	const processCcc = cccRootForCwd(processCwd);
+	const panelResolved = collectAutopilotCccs(ctx)[0] ?? resolveAutopilotRoot(ctx);
+	const autopilotCccs = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const s of liveSessions) {
+		if (!s.cccRoot || seen.has(s.cccRoot)) continue;
+		const cfg = readAutopilotSettings(s.cccRoot);
+		if (!cfg) continue;
+		seen.add(s.cccRoot);
+		const status = getAutopilotStatus(s.cccRoot);
+		const mdPath = resolveTargetMd(s.cccRoot, cfg);
+		const agentResolved = mdPath ? resolveTargetAgent(ctx, mdPath) !== null : false;
+		const agentDiagnosis = mdPath && !agentResolved ? diagnoseTargetUnavailable(ctx, mdPath) : null;
+		autopilotCccs.push({
+			root: s.cccRoot,
+			enabled: status.enabled,
+			session: status.session,
+			target: status.target,
+			agentResolved,
+			agentDiagnosis
+		});
+	}
+	return {
+		processCwd,
+		processCcc,
+		liveSessions,
+		autopilotCccs,
+		panelResolved
+	};
+}
+/**
+* **条件链的运行态事实**（⑥ C6a 的核心出口）——把只有插件进程能看到的判据交给
+* 条件链（{@link buildWakeChain} 的输入）：全局闸 / 重入守卫 / live 运行态。
+*
+* 为什么必须有（这是 C6 的动机本身）：旧独立脚本只能读文件 ⇒ 结构性地看不到这三样，
+* 于是逐条件报告**必然**与实际唤起行为分歧（8 项，见 `acc-component-relations-current-state.md` §4.4）。
+* 搬进进程内之后，`container_admin autopilot status` 与 `acc-diag` ④ 段读的就是**同一份事实**。
+*
+* `ctx` 可传 `null`（**不是**"三项全不可知"）：全局闸（`readSimpleSettings`）与重入守卫
+* （模块级 `runningByRoot`）**都不需要 ctx**，无 ctx 时也应读出真值——只有 live 运行态
+* （live 会话 / agent 可解析）依赖 ctx，那才是真正的"不可知"。
+* 这条区分由 `autopilot-ops.test.ts` 的全局闸可见性用例逼出来（首版把三者一起降级为不可知，
+* 使"闸关"在无 ctx 路径下隐形——正是本轮要消灭的那类假报告）。
+*
+* @param ctx 插件上下文（读 live 会话 + agent）；null = 无进程上下文（live 标不可知）
+* @param root 目标 CCC 根
+* @returns 条件链事实（`live` 为 null 表示"live 运行态不可知"）
+*/
+function autopilotRuntimeFacts(ctx, root) {
+	const settings = readAutopilotSettings(root);
+	const mdPath = settings ? resolveTargetMd(root, settings) : null;
+	let live = null;
+	if (ctx !== null) {
+		const sessionCount = listLiveSessions(ctx).filter((s) => s.cccRoot === root).length;
+		const agentResolved = mdPath ? resolveTargetAgent(ctx, mdPath) !== null : null;
+		live = {
+			sessionCount,
+			agentResolved,
+			diagnosis: mdPath && agentResolved === false ? diagnoseTargetUnavailable(ctx, mdPath) : null
+		};
+	}
+	return {
+		globalGate: autopilotGloballyEnabled(),
+		running: autopilotWakeInFlight(root),
+		live
+	};
+}
+//#endregion
+export { autopilot_trajectory_exports as a, registerAutopilot as c, autopilotWakeInFlight as i, registerDisposer as l, autopilotGloballyEnabled as n, diagLive as o, autopilotRuntimeFacts as r, getAutopilotStatus as s, autopilotClockState as t, createClock as u };