pi-patch-keeper 1.0.3 → 1.0.5

package/README.en.md

@@ -1,43 +1,45 @@
 # pi-patch-keeper — extension load-order guard (pi extension)
 
-Stops "force-type" extensions from silently dropping every later section.
+Prevents "force-typed" extensions from silently swallowing every section written after them.
 
-## Features
+## Why it exists
 
-- Checks `packages` order in `~/.pi/agent/settings.json` at startup.
-- Statically scans npm extension sources for unconditional `return { systemPrompt }` / `forceSystemPrompt`.
-- Moves known force-type packages to the end of `packages` (settings backed up first).
-- Speaks only when something is wrong; `/patch-keeper` reports, `/patch-keeper fix` repairs.
-- This release contains no machine-specific patch healing (source patches, PiDeck asar, etc.).
+`before_agent_start` runs extensions in order. An extension that returns `{ systemPrompt }` (or sets `forceSystemPrompt`) performs a **full replacement**, so every later extension's `sections` write is discarded — with no error. The symptom looks like "this extension is installed but has no effect".
 
-## Defaults
-
-| Item | Default | Note |
-| --- | --- | --- |
-| Force-type packages | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | override via `forceTail` |
-| Auto repair | on | backup `settings.json.bak-force-order-*` |
-| Startup notice | only on issue | silent when clean |
-| Scope | `npm:` packages | local path packages are skipped |
+## What it does
 
-## Install
+- On startup, checks the order of `packages` in `~/.pi/agent/settings.json`: known force-typed extensions must sit at the end.
+- Statically scans installed npm extension entry files and separates:
+  - **unconditional force** (`return { systemPrompt }` / `forceSystemPrompt`) → must be last;
+  - **sections-first with legacy fallback** → report only, no move suggested.
+- Records a fingerprint of key settings fields and warns when it changes (earlier conclusions may be stale).
+- `codemode` single-point check: disabling `builtin:codemode` requires a replacement, and vice versa.
+- Silent when everything is fine.
 
-```bash
-pi install npm:pi-patch-keeper@1.0.0
-pi install ./pi-patch-keeper
-```
+## Commands
 
-## Config
+| Command | Effect |
+| --- | --- |
+| `/patch-keeper` | Show order, suspected force packages, fallback packages, codemode status |
+| `/patch-keeper fix` | Move known force-typed packages to the end (backup written first) |
 
-```json
-{ "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
-```
+## Defaults
 
-## How it works
+| Key | Default |
+| --- | --- |
+| `forceTail` | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` |
+| Auto-fix | on (order only, backup first) |
+| Notify | only on problems |
+| Scope | `npm:` packages |
 
-- Reads each npm package's `pi.extensions` entry and compares where sections and force appear: sections first means a compatibility fallback, not an unconditional force.
-- Reports when any package still follows a force-type package.
+Optional config: `~/.pi/patch-keeper-state.json`
 
 ## Limits
 
-- Only npm packages can be inspected.
-- Reorders loading; never edits package code.
+- Detects static forms only; dynamic `systemPrompt` construction is not detected.
+- Local-path packages are skipped.
+- Unknown force-typed extensions must be added to `forceTail` manually.
+
+## License
+
+MIT.

package/README.md

@@ -4,44 +4,50 @@
 
 ## 来源与借鉴
 
-原创，无上游实现。设计灵感来自本机长期维护 PiDeck / pi 补丁的实践：补丁会被升级覆盖，故需要启动时自检与自愈。
+原创，无上游实现。动机来自一个反复出现的症状：某个扩展明明装了、section 也写了，却没出现在 system prompt 里——根因是它前面有扩展 `return { systemPrompt }`，覆盖式替换把后续写入全丢了，而且不报错。
 
 ## 功能
 
-- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序。
-- 静态扫描 npm 扩展源码，识别无条件 `return { systemPrompt }` / `forceSystemPrompt` 的包。
-- 已知 force 型包自动移到 `packages` 末尾（先备份 settings）。
-- 启动时只在发现问题时提示；`/patch-keeper` 随时查看状态，`/patch-keeper fix` 手动修复。
-- 发布版不含任何本机补丁自愈逻辑（源码补丁、PiDeck asar 等已剥离）。
+- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序：已知 force 型必须在末尾。
+- 静态扫描已装 npm 扩展的入口源码，区分两类：
+  - **无条件 force**（`return { systemPrompt }` 或 `forceSystemPrompt`）→ 必须排在末尾；
+  - **section 优先 + 旧宿主兜底**（先写 sections，旧宿主才 force）→ 只提示，不建议移动。
+- 记录 settings 关键字段指纹（packages / defaultTools / enabledModels / extensions / codemode），变化时提示「此前的结论可能过期」。
+- codemode 单点检查：禁用 `builtin:codemode` 时必须有替代实现，反之亦然（双实现或单点断裂都会报）。
+- 只在发现问题时提示；命令随时查看状态。
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/patch-keeper` | 查看顺序、疑似 force 包、兜底包、codemode 单点状态 |
+| `/patch-keeper fix` | 把已知 force 型移到 `packages` 末尾（写前备份 `settings.json.bak-force-order-*`） |
 
 ## 默认配置
 
 | 项 | 默认 | 说明 |
 | --- | --- | --- |
-| force 型包 | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | `~/.pi/patch-keeper.json` 的 `forceTail` 可覆盖 |
-| 自动修复顺序 | 开 | 写前备份 `settings.json.bak-force-order-*` |
-| 启动提示 | 仅异常时 | 无问题不打扰 |
+| `forceTail` | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | 已知无条件 force 型；触发概率升序 |
+| 自动修复 | 开 | 仅调整顺序，写前备份 |
+| 提示时机 | 仅异常 | 无问题零输出 |
 | 检测范围 | `npm:` 包 | 本地路径包跳过 |
 
-## 安装
-
-```bash
-pi install npm:pi-patch-keeper
-pi install ./pi-patch-keeper
-```
-
-## 配置示例
+配置文件（可选）：`~/.pi/patch-keeper-state.json`
 
 ```json
 { "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
 ```
 
-## 机制
+## 机制（为什么放在启动时）
+
+pi 的 `before_agent_start` 依次调用各扩展；返回 `{ systemPrompt }` 等于 `forceSystemPrompt`——**覆盖式替换**，此后所有扩展对 sections 的修改都被丢弃。因此「谁在末尾」是有行为后果的，不是风格问题。本扩展只在 `session_start` 检查与提示，自身**绝不** return systemPrompt。
+
+## 局限
 
-- 读取每个 npm 包的 `pi.extensions` 入口，检查 `before_agent_start` 中 section 写入与 force 出现的先后：先 sections 后 force 视为兼容兜底，不计入疑似。
-- 判定「force 型包之后仍有其他包」即报问题。
+- 只识别静态形态（`return { systemPrompt }` / `forceSystemPrompt`）；动态拼接无法识别。
+- 只处理 `npm:` 前缀包；本地路径包（`path:` / 相对路径）不扫描。
+- 只能保证「已知 force 型在末尾」；未知的 force 型需要人工确认后加入 `forceTail`。
 
-## 限制
+## 许可证
 
-- 只能读 `npm:` 包；读不到源码的包跳过。
-- 不修包内代码，只调整加载顺序。
+MIT。

package/index.ts

@@ -1,161 +1,252 @@
-/** 
- * pi-patch-keeper — extension load-order guard for the pi coding agent.
+/**
+ * patch-keeper —— 扩展加载顺序守护（pi 扩展）
  *
- * Force-type extensions (those returning { systemPrompt } / forceSystemPrompt)
- * replace the whole system prompt, silently dropping every section written by
- * handlers that run after them. This extension keeps known force-type packages
- * at the tail of settings.json "packages" and reports packages that still follow
- * one of them.
+ * 问题：pi 的 system prompt 由各扩展的 section 写入拼装。若某扩展在
+ * `before_agent_start` 里 `return { systemPrompt }`（或设置 forceSystemPrompt），
+ * 它会**静默丢弃其后所有扩展的 section 写入**——没有任何报错，表现为
+ * 「某个扩展配了却没效果」。
  *
- * Release edition: no machine-specific patch healing (source patches, PiDeck
- * asar, memory fixes) is included.
+ * 本扩展做三件事（全部只读，唯一的写是带备份修 settings）：
+ *  1. 检查 `settings.json` 的 packages 顺序：已知 force 型必须排在末尾。
+ *  2. 静态扫描已装 npm 扩展入口源码，区分「无条件 force」与「section 优先 + 旧宿主兜底」。
+ *  3. 记录 settings 关键字段指纹；变化时提示「环境已变，旧结论可能过期」。
+ *
+ * 纪律：绝不 return systemPrompt（否则自己就是问题）；任何失败只提示、不抛错。
  */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
 const HOME = os.homedir();
 const SETTINGS = path.join(HOME, ".pi", "agent", "settings.json");
-const CONFIG = path.join(HOME, ".pi", "patch-keeper.json");
-const NPM_DIR = path.join(HOME, ".pi", "agent", "npm", "node_modules");
-const DEFAULT_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+const STATE = path.join(HOME, ".pi", "patch-keeper-state.json");
+const NPM_ROOT = path.join(HOME, ".pi", "agent", "npm", "node_modules");
+
+/** 已知无条件 force 型包。触发概率升序：越靠后越应排在 packages 末尾。 */
+const DEFAULT_FORCE_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+
+/** 静态扫描：入口源码里出现这两个形态即判为 force。 */
+const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
+const SECTION_RE = /sections\s*(\[|\.)/;
+
+export type Result = { ok: boolean; detail: string };
 
 function safeRead(p: string): string | null {
-	try { return readFileSync(p, "utf8"); } catch { return null; }
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
 }
 
-function readJson(p: string): Record<string, unknown> | null {
-	const t = safeRead(p);
-	if (t === null) return null;
-	try { return JSON.parse(t) as Record<string, unknown>; } catch { return null; }
+function readSettings(): Record<string, unknown> | null {
+  const txt = safeRead(SETTINGS);
+  if (txt === null) return null;
+  try {
+    return JSON.parse(txt) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
 }
 
+/** 用户可在 ~/.pi/patch-keeper.json 用 forceTail 覆盖已知 force 型列表。 */
 function forceTail(): string[] {
-	const c = readJson(CONFIG);
-	const t = c?.forceTail;
-	const list = Array.isArray(t) ? t.filter((x): x is string => typeof x === "string") : DEFAULT_TAIL;
-	return list.length ? list : DEFAULT_TAIL;
+  const txt = safeRead(STATE);
+  if (!txt) return DEFAULT_FORCE_TAIL;
+  try {
+    const cfg = JSON.parse(txt) as { forceTail?: unknown };
+    return Array.isArray(cfg.forceTail) && cfg.forceTail.every((x) => typeof x === "string")
+      ? (cfg.forceTail as string[])
+      : DEFAULT_FORCE_TAIL;
+  } catch {
+    return DEFAULT_FORCE_TAIL;
+  }
 }
 
-function packagesOf(): string[] | null {
-	const s = readJson(SETTINGS);
-	const p = s?.packages;
-	return Array.isArray(p) ? p.filter((x): x is string => typeof x === "string") : null;
+/** force 型必须整体位于末尾，且相对顺序按 tail 数组。 */
+export function forceOrderIssues(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
+  const out: string[] = [];
+  const idx = (n: string) => packages.indexOf(n);
+  const present = tail.filter((n) => idx(n) >= 0);
+  if (!present.length) return out;
+  const minForce = Math.min(...present.map(idx));
+  const later = packages.slice(minForce + 1).filter((n) => !tail.includes(n));
+  if (later.length) {
+    out.push(
+      `force 型之后仍有 ${later.length} 个包（${later.slice(0, 2).join(" / ")}）—— 它们的 section 写入会被静默丢弃；把 ${tail.join(" / ")} 移到 packages 末尾`,
+    );
+  }
+  const ordered = present.every((n, i) => i === 0 || idx(present[i - 1]) < idx(n));
+  if (!ordered) out.push(`force 型相对顺序应与 ${tail.join(" → ")} 一致（最可能触发者最后）`);
+  return out;
 }
 
-/** Problems in the current load order (empty = OK). */
-export function forceOrderIssues(packages: string[]): string[] {
-	const out: string[] = [];
-	const tail = forceTail();
-	const present = tail.filter((n) => packages.includes(n));
-	if (!present.length) return out;
-	const minForce = Math.min(...present.map((n) => packages.indexOf(n)));
-	const later = packages.slice(minForce + 1).filter((n) => !tail.includes(n));
-	if (later.length) out.push(
-		"force-type package is followed by " + later.length + " package(s) (" + later.slice(0, 2).join(" / ") +
-		") — their sections are dropped; move " + tail.join(" / ") + " to the end");
-	if (tail.every((n) => packages.includes(n)) && packages.indexOf(tail[0]) > packages.indexOf(tail[1]))
-		out.push("force order should be " + tail.join(" -> ") + " (the most likely trigger goes last)");
-	return out;
+/** 把 force 型移到末尾（其余相对顺序不变）；已正确返回 null。 */
+export function normalizeForceOrder(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] | null {
+  const present = tail.filter((n) => packages.includes(n));
+  if (!present.length) return null;
+  const rest = packages.filter((n) => !tail.includes(n));
+  const next = [...rest, ...present];
+  return next.join("\n") === packages.join("\n") ? null : next;
 }
 
-/** Reordered packages, or null when already correct. */
-export function normalizeForceOrder(packages: string[]): string[] | null {
-	const tail = forceTail();
-	const present = tail.filter((n) => packages.includes(n));
-	if (!present.length) return null;
-	const next = [...packages.filter((n) => !tail.includes(n)), ...present];
-	return next.join("\n") === packages.join("\n") ? null : next;
+/** 读扩展入口源码并分类：无条件 force / section 优先（旧宿主兜底）/ 无。 */
+function classifyPackages(packages: string[], tail: string[]): { force: string[]; fallback: string[] } {
+  const force: string[] = [];
+  const fallback: string[] = [];
+  for (const name of packages) {
+    if (!name.startsWith("npm:") || tail.includes(name)) continue;
+    const dir = path.join(NPM_ROOT, name.slice(4));
+    if (!existsSync(dir)) continue;
+    let entries: string[] = [];
+    try {
+      const pj = JSON.parse(safeRead(path.join(dir, "package.json")) ?? "{}") as { pi?: { extensions?: unknown } };
+      const ex = pj.pi?.extensions;
+      entries = Array.isArray(ex) ? ex.filter((x): x is string => typeof x === "string") : [];
+    } catch {
+      continue;
+    }
+    for (const rel of entries.slice(0, 3)) {
+      const src = safeRead(path.join(dir, rel));
+      if (src === null) continue;
+      const i = src.indexOf("before_agent_start");
+      if (i < 0) continue;
+      const body = src.slice(i, i + 4000);
+      const fi = body.search(FORCE_RE);
+      if (fi < 0) continue;
+      const si = body.search(SECTION_RE);
+      if (si >= 0 && si < fi) fallback.push(name);
+      else force.push(name);
+      break;
+    }
+  }
+  return { force, fallback };
 }
 
-/** Repair settings.json order; backs up first. Returns a message or null. */
-function fixForceOrder(): string | null {
-	const s = readJson(SETTINGS);
-	if (!s) return null;
-	const packages = Array.isArray(s.packages) ? (s.packages as string[]) : [];
-	const next = normalizeForceOrder(packages);
-	if (!next) return null;
-	try {
-		copyFileSync(SETTINGS, SETTINGS + ".bak-force-order-" + Date.now());
-		s.packages = next;
-		writeFileSync(SETTINGS, JSON.stringify(s, null, 2), "utf8");
-	} catch (e) { return "force order repair failed: " + (e as Error).message; }
-	return "force order repaired: " + forceTail().filter((n) => next.includes(n)).join(" / ") + " moved to the end";
+/** 疑似无条件 force（会吞掉其后 section）。 */
+export function scanForcePackages(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
+  return classifyPackages(packages, tail).force;
 }
 
-const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
-const SECTION_RE = /sections\s*(\[|\.)/;
+/** 兼容兜底型（section 优先，仅旧宿主 force）。 */
+export function scanForceFallbacks(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
+  return classifyPackages(packages, tail).fallback;
+}
+
+/** codemode 单点检查：禁用 builtin:codemode 时必须有替代实现，反之亦然。 */
+export function consistencyCheck(extensions: string[], packages: string[]): string[] {
+  const disabled = extensions.includes("-builtin:codemode");
+  const guard = packages.includes("npm:pi-codemode-guard");
+  if (disabled && !guard) return ["codemode 单点断裂：已禁 builtin:codemode 但 packages 无替代实现 —— codemode 工具将不可用"];
+  if (!disabled && guard) return ["codemode 单点异常：替代实现已在，但 builtin:codemode 未禁用 —— 双实现风险"];
+  return [];
+}
+
+/** settings 关键字段指纹（顺序敏感）。 */
+function fingerprint(s: Record<string, unknown>): Record<string, string[]> {
+  return {
+    packages: (s.packages as string[]) ?? [],
+    defaultTools: (s.defaultTools as string[]) ?? [],
+    enabledModels: (s.enabledModels as string[]) ?? [],
+    extensions: (s.extensions as string[]) ?? [],
+    codemode: [(s.codemode as { mode?: string })?.mode ?? "?"],
+  };
+}
 
-/** Classify static force candidates: sections-first means a legacy-host fallback. */
-function classify(packages: string[]): { force: string[]; fallback: string[] } {
-	const force: string[] = [];
-	const fallback: string[] = [];
-	const tail = forceTail();
-	for (const name of packages) {
-		if (!name.startsWith("npm:") || tail.includes(name)) continue;
-		const dir = path.join(NPM_DIR, name.slice(4));
-		if (!existsSync(dir)) continue;
-		let entries: string[] = [];
-		const pj = readJson(path.join(dir, "package.json")) as { pi?: { extensions?: unknown } } | null;
-		const ex = pj?.pi?.extensions;
-		entries = Array.isArray(ex) ? ex.filter((x): x is string => typeof x === "string") : [];
-		for (const rel of entries.slice(0, 3)) {
-			const src = safeRead(path.join(dir, rel));
-			if (src === null) continue;
-			const i = src.indexOf("before_agent_start");
-			if (i < 0) continue;
-			const body = src.slice(i, i + 4000);
-			const fi = body.search(FORCE_RE);
-			if (fi < 0) continue;
-			const si = body.search(SECTION_RE);
-			if (si >= 0 && si < fi) fallback.push(name); else force.push(name);
-			break;
-		}
-	}
-	return { force, fallback };
+/** 与上次指纹对比并写回；返回变化摘要（无变化为空）。 */
+function fingerprintDrift(cur: Record<string, string[]>): string[] {
+  let prev: Record<string, string[]> | null = null;
+  const raw = safeRead(STATE);
+  if (raw) {
+    try {
+      const j = JSON.parse(raw) as { fingerprint?: Record<string, string[]> };
+      prev = j.fingerprint ?? null;
+    } catch {
+      prev = null;
+    }
+  }
+  try {
+    const cfg = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+    writeFileSync(STATE, JSON.stringify({ ...cfg, fingerprint: cur }, null, 1), "utf8");
+  } catch {
+    /* 静默 */
+  }
+  if (prev === null) return [];
+  const out: string[] = [];
+  for (const k of ["packages", "defaultTools", "enabledModels", "extensions", "codemode"] as const) {
+    const a = prev[k] ?? [];
+    const b = cur[k];
+    if (a.join("\n") !== b.join("\n")) out.push(k);
+  }
+  return out;
 }
 
+/** 修 settings 的 force 顺序（写前备份）；无变化返回 null。 */
+function fixForceOrder(): string | null {
+  const s = readSettings();
+  if (!s) return null;
+  const tail = forceTail();
+  const packages = (s.packages as string[] | undefined) ?? [];
+  const next = normalizeForceOrder(packages, tail);
+  if (!next) return null;
+  try {
+    copyFileSync(SETTINGS, `${SETTINGS}.bak-force-order-${Date.now()}`);
+    s.packages = next;
+    writeFileSync(SETTINGS, JSON.stringify(s, null, 2), "utf8");
+  } catch (e) {
+    return `force 顺序自动修复失败：${(e as Error).message}`;
+  }
+  return `force 顺序已自动修复：${tail.filter((n) => next.includes(n)).join(" / ")} 移到 packages 末尾`;
+}
+
+/** 状态报告（命令与启动提示共用）。 */
 function report(): string[] {
-	const lines: string[] = [];
-	const pk = packagesOf();
-	if (!pk) { lines.push("settings: cannot read " + SETTINGS); return lines; }
-	const issues = forceOrderIssues(pk);
-	lines.push("force order: " + (issues.length ? issues[0] : "OK"));
-	const tail = forceTail();
-	lines.push("force packages: " + tail.filter((n) => pk.includes(n)).join(" / ") + (tail.some((n) => !pk.includes(n)) ? " (partial)" : ""));
-	const { force, fallback } = classify(pk);
-	lines.push("static scan: " + (force.length ? "force-like " + force.join(" / ") : "none"));
-	lines.push("fallbacks: " + (fallback.length ? fallback.join(" / ") : "none"));
-	return lines;
+  const s = readSettings();
+  if (!s) return ["读不到 settings.json"];
+  const tail = forceTail();
+  const packages = (s.packages as string[]) ?? [];
+  const lines: string[] = [];
+  const fo = forceOrderIssues(packages, tail);
+  lines.push(`force顺序 : ${fo.length ? fo[0] : "OK"}`);
+  const fe = scanForcePackages(packages, tail);
+  lines.push(`疑似force: ${fe.length ? fe.join(" / ") : "无（静态扫描）"}`);
+  const fb = scanForceFallbacks(packages, tail);
+  lines.push(`兼容兜底 : ${fb.length ? fb.join(" / ") : "无"}`);
+  const cm = consistencyCheck((s.extensions as string[]) ?? [], packages);
+  lines.push(`codemode : ${cm.length ? cm[0] : "单点一致"}`);
+  return lines;
 }
 
-export default function (pi: ExtensionAPI) {
-	pi.registerCommand("patch-keeper", {
-		description: "Show / repair extension load order (force-type packages must load last)",
-		handler: async (args: string, ctx: ExtensionContext) => {
-			const arg = (args || "").trim().toLowerCase();
-			if (arg === "fix") {
-				const r = fixForceOrder();
-				ctx.ui.notify(r ?? "patch-keeper: load order already correct", "info");
-				return;
-			}
-			ctx.ui.notify("patch-keeper\n" + report().join("\n"), "info");
-		},
-	});
-
-	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
-		try {
-			const pk = packagesOf();
-			if (!pk) return;
-			const msgs: string[] = [];
-			for (const x of forceOrderIssues(pk)) msgs.push("patch-keeper: " + x);
-			const fixed = fixForceOrder();
-			if (fixed) msgs.push("patch-keeper: " + fixed);
-			const { force } = classify(pk);
-			const tail = forceTail();
-			const mid = force.filter((n) => pk.indexOf(n) < pk.length - 1 && !tail.includes(n));
-			if (mid.length) msgs.push("patch-keeper: force-like package not last: " + mid.join(" / ") + " — move it to the end of packages");
-			for (const m of msgs) ctx.ui.notify(m, "warning");
-		} catch { /* detection must never break the session */ }
-	});
+export default function patchKeeper(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    try {
+      const s = readSettings();
+      if (!s) return;
+      const msgs: string[] = [];
+      const fixed = fixForceOrder();
+      if (fixed) msgs.push(fixed);
+      else for (const x of forceOrderIssues((s.packages as string[]) ?? [], forceTail())) msgs.push(x);
+      const drift = fingerprintDrift(fingerprint(s));
+      if (drift.length) msgs.push(`环境指纹已变（${drift.join(" / ")}）—— 此前关于工具/模型的结论可能过期`);
+      const cm = consistencyCheck((s.extensions as string[]) ?? [], (s.packages as string[]) ?? []);
+      for (const x of cm) msgs.push(x);
+      for (const m of msgs) ctx.ui.notify("patch-keeper: " + m, "warning");
+    } catch {
+      /* 静默：检测不该影响会话 */
+    }
+  });
+
+  pi.registerCommand("patch-keeper", {
+    description: "查看 / 修复扩展加载顺序（force 型必须在 packages 末尾）",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const arg = (args || "").trim().toLowerCase();
+      if (arg === "fix") {
+        const r = fixForceOrder();
+        ctx.ui.notify(r ? `patch-keeper: ${r}` : "patch-keeper: force 顺序已正确，无需修复", r ? "info" : "info");
+        return;
+      }
+      ctx.ui.notify(`扩展加载顺序\n${report().join("\n")}`, "info");
+    },
+  });
 }

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.0.3",
-  "description": "Guards extension load order so later sections are not silently dropped.",
+  "version": "1.0.5",
+  "description": "Detect and fix pi extension load-order hazards: force-typed extensions silently swallow later system-prompt sections.",
   "type": "module",
   "license": "MIT",
   "keywords": [
+    "load-order",
     "pi",
+    "pi-coding-agent",
     "pi-extension",
-    "pi-coding-agent"
+    "pi-package",
+    "system-prompt"
   ],
   "pi": {
     "extensions": [
@@ -22,5 +25,6 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
-  }
+  },
+  "author": "15066212pp"
 }