pi-proactive 0.2.0-beta.5 → 0.2.0-beta.7

package/app/app.mjs

@@ -0,0 +1,1378 @@
+#!/usr/bin/env node
+/**
+ * pi-proactive App —— **pi-agent 的 shim / wrapper**（最小可用外壳 · M1a）。
+ *
+ * 定位（docs/product/app-shell/APP-SPEC.md §0）：App **不实现**任何 agent / 调度 / 主动性逻辑；
+ * 它只做三件事 —— 启动（shim）· 注入（wrapper）· 呈现（通知 / 只读面板）。
+ * 底下跑的就是**真 pi-agent 本体**（`pi --mode rpc --no-session -e <pi-proactive 包>`）。
+ *
+ * 六个域（与 APP-SPEC §1 一一对应）：
+ *   D1 注入  启动参数 = `pi --mode rpc --no-session -e <包路径>`；**可证明** = 进程内扩展清单含 pi-proactive。
+ *   D2 承载  专属短路径 agent 根 `/tmp/pp-app-<pid>`（unix socket 路径上限 100B → 端点必须建得出来）。
+ *   D3 驱动  JSONL 命令/响应**按 id 关联**（不是按顺序）。
+ *   D4 呈现  系统通知（macOS osascript，通道可插拔、不可用时**明确降级**）+ 只读监督面板（复用 supervisor-web）。
+ *   D5 生命周期 单实例锁 · 二次启动回执「已在运行」· 退出**零残留**（进程/socket/临时根/锁/日志）。
+ *   D6 引导  ≤3 步、一次只问一件事、任何一步可「算了」且零残留 + **三问话术**（它是谁/在干什么/怎么让它做事）。
+ *
+ * 硬纪律：
+ *   - 零第三方依赖（只用 Node 内置）；纯 .mjs（npm 包内不得有 .ts）。
+ *   - **状态等待代替固定等待**：等扩展真的注册了才叫就绪；超时 ⇒ 报【未就绪】+ 诊断（禁止 sleep 后假装成功）。
+ *   - **单次注入**：只用 `-e`，不写用户 settings.json（不污染用户环境）。
+ *   - **不写凭据**：沿用宿主 pi 的认证（共享模式）或环境里的 API key；App 自己不存任何凭据。
+ *   - **不碰用户既有项目**：只读监督面；写操作留 pi-agent。
+ *
+ * 用法：`node app/app.mjs <start|stop|status|describe|guide|ask> [选项]`
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** 包根：`<pkg>/app` → `<pkg>`（npm 安装后 = 已安装的 pi-proactive 包）。 */
+export const DEFAULT_PKG_ROOT = path.resolve(here, "..");
+
+/** unix socket 路径上限（字节）—— 与 pi-proactive/src/socket.ts 的 MAX_SOCKET_PATH_BYTES 同口径。 */
+export const MAX_SOCKET_PATH_BYTES = 100;
+
+/** App 实例的默认 agentId（短 → 端点路径短且可预测）。 */
+export const APP_AGENT_ID = "app";
+
+/** 端点落在 `<agentRoot>/proactive/run/`（与 src/socket.ts 的布局一致）。 */
+const RUN_SUBDIR = path.join("proactive", "run");
+
+/** 通知记录（证据）落在 `<agentRoot>/proactive/app/`。 */
+const APP_SUBDIR = path.join("proactive", "app");
+
+const MISSING_PI_MESSAGE =
+	"未找到 pi 可执行文件（--pi-bin 未给、PI_BIN 未设、PATH 里也没有 pi）。\n" +
+	"安装指引：npm i -g @earendil-works/pi-coding-agent\n" +
+	"或用 --pi-bin /绝对路径/pi（或环境变量 PI_BIN=/绝对路径/pi）指定已安装的 pi。";
+
+// ------------------------------------------------------------------ 小工具
+
+function errText(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * 进程是否存活。
+ * EPERM = 活着但不属于当前用户；僵尸（Z）= 已退出、只是等父进程收尸 → 不算活着。
+ */
+function isAlive(pid) {
+	if (!pid || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+	} catch (err) {
+		return Boolean(err && err.code === "EPERM");
+	}
+	try {
+		const out = spawnSync("ps", ["-o", "state=", "-p", String(pid)], { encoding: "utf8" });
+		if ((out.stdout || "").trim().startsWith("Z")) return false;
+	} catch {
+		/* ignore */
+	}
+	return true;
+}
+
+/** 可执行文件判定（存在 + 是文件 + 有执行位）。 */
+function isExecutableFile(p) {
+	try {
+		const st = fs.statSync(p);
+		if (!st.isFile()) return false;
+		fs.accessSync(p, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** 短路径临时根：优先 /tmp（macOS 的 os.tmpdir() 很长，会吃掉 socket 路径预算）。 */
+function defaultTmpDir() {
+	try {
+		if (fs.statSync("/tmp").isDirectory()) return "/tmp";
+	} catch {
+		/* ignore */
+	}
+	return os.tmpdir();
+}
+
+function uid() {
+	return typeof process.getuid === "function" ? process.getuid() : 0;
+}
+
+/** agentId → 文件名安全化（与扩展 sanitizeSocketFileName 同口径：`/` `\` `#` 空白 → `-`）。 */
+function sanitizeName(name) {
+	return String(name).replace(/[/\\#\s]/g, "-") || "unknown";
+}
+
+/**
+ * 端点路径（与 src/socket.ts 的 socketPathFor **同规则**）：
+ * 常规名 `<sanitized(agentId)>.sock`；完整路径超 100B → 降级为 `h-<sha256 前 16 位>.sock`。
+ * 判定只依赖 (agentId, agentDir) → 与扩展服务端推出同一个路径。
+ */
+function socketPathFor(agentId, agentRoot) {
+	const runDir = path.join(agentRoot, RUN_SUBDIR);
+	const natural = path.join(runDir, `${sanitizeName(agentId)}.sock`);
+	if (Buffer.byteLength(natural, "utf8") <= MAX_SOCKET_PATH_BYTES) return natural;
+	const hashed = `h-${createHash("sha256").update(String(agentId), "utf8").digest("hex").slice(0, 16)}.sock`;
+	return path.join(runDir, hashed);
+}
+
+// ------------------------------------------------------------------ D2 承载
+
+/**
+ * 算出本次实例的「承载面」：agent 根 / 端点 / 日志 / 锁。
+ * - dedicated（默认）：`/tmp/pp-app-<pid>`（**专属短路径**）→ 我们拥有它 → 退出可整体删除；
+ * - shared：沿用宿主 pi 的 agent 根（PI_CODING_AGENT_DIR 或 ~/.pi/agent）→ **我们不拥有** → 只删自己的产物；
+ * - 显式 agentDir：覆盖根目录，同样**不拥有**。
+ */
+export function resolveInstance(opts = {}) {
+	const env = opts.env || process.env;
+	const pid = opts.pid || process.pid;
+	const agentRootKind = opts.agentRootKind === "shared" ? "shared" : "dedicated";
+	const explicit = opts.agentDir ? String(opts.agentDir) : "";
+	const tmpDir = opts.tmpDir || defaultTmpDir();
+	const dedicatedRoot = path.join(tmpDir, `pp-app-${pid}`);
+	const sharedRoot = env.PI_CODING_AGENT_DIR ? env.PI_CODING_AGENT_DIR : path.join(os.homedir(), ".pi", "agent");
+	const agentRoot = explicit || (agentRootKind === "shared" ? sharedRoot : dedicatedRoot);
+	return composeInstance({
+		agentRootKind,
+		agentRoot,
+		ownsAgentRoot: agentRootKind !== "shared" && explicit === "",
+		agentId: env.PI_PROACTIVE_AGENT_ID ? env.PI_PROACTIVE_AGENT_ID : APP_AGENT_ID,
+		logPath: path.join(tmpDir, `pp-app-${pid}.log`),
+		// 锁与实例无关（跨实例才能检出「已在运行」）→ 按 uid 隔离，避免跨用户互相挡。
+		lockPath: path.join(tmpDir, `pp-app-${uid()}.lock`),
+		pkgRoot: opts.pkgRoot || env.PI_PROACTIVE_PKG_ROOT || DEFAULT_PKG_ROOT,
+	});
+}
+
+/** 由原始字段算出完整实例描述（端点路径与长度预算统一在这里算）。 */
+function composeInstance(raw) {
+	const socketPath = socketPathFor(raw.agentId, raw.agentRoot);
+	const socketPathBytes = Buffer.byteLength(socketPath, "utf8");
+	return {
+		agentRootKind: raw.agentRootKind,
+		dedicated: raw.agentRootKind === "dedicated",
+		ownsAgentRoot: Boolean(raw.ownsAgentRoot),
+		agentRoot: raw.agentRoot,
+		agentId: raw.agentId,
+		socketPath,
+		socketPathBytes,
+		// 如实标记：超长 = 端点建不出来 → 后续检查必须判「未触发」，不得判「不残留」。
+		socketOverBudget: socketPathBytes > MAX_SOCKET_PATH_BYTES,
+		logPath: raw.logPath,
+		lockPath: raw.lockPath,
+		pkgRoot: raw.pkgRoot,
+	};
+}
+
+/**
+ * 锁文件是「现在跑着的是哪个实例」的**唯一真源**：
+ * stop / status 必须按锁里记的路径清理与汇报 —— 否则会拿自己的 pid 去清别人的实例（清不到 = 残留）。
+ */
+function instanceFromLock(lock, fallback) {
+	if (!lock) return fallback;
+	return composeInstance({
+		agentRootKind: lock.agentRootKind || fallback.agentRootKind,
+		agentRoot: lock.agentRoot || fallback.agentRoot,
+		ownsAgentRoot: lock.ownsAgentRoot === undefined ? fallback.ownsAgentRoot : Boolean(lock.ownsAgentRoot),
+		agentId: lock.agentId || fallback.agentId,
+		logPath: lock.logPath || fallback.logPath,
+		lockPath: fallback.lockPath,
+		pkgRoot: lock.pkgRoot || fallback.pkgRoot,
+	});
+}
+
+/** 找真实存在的端点（run/*.sock）；没有则返回 null（= **未触发**，不是「不残留」）。 */
+export function findEndpoint(agentRoot) {
+	const dir = path.join(agentRoot, RUN_SUBDIR);
+	let names;
+	try {
+		names = fs.readdirSync(dir);
+	} catch {
+		return null;
+	}
+	const sock = names.filter((n) => n.endsWith(".sock")).sort()[0];
+	if (!sock) return null;
+	const p = path.join(dir, sock);
+	return { path: p, bytes: Buffer.byteLength(p, "utf8") };
+}
+
+/** 本机是否有我们留下的 launchd 单元（本 App 不装单元 —— 检查即证明）。 */
+function listLaunchdUnits() {
+	const dir = path.join(os.homedir(), "Library", "LaunchAgents");
+	try {
+		return fs
+			.readdirSync(dir)
+			.filter((n) => n.startsWith("pp-app") && n.endsWith(".plist"))
+			.sort();
+	} catch {
+		return [];
+	}
+}
+
+/** 残留终检（进程 / 端点 / 目录 / 锁 / 日志 / launchd）。 */
+/** 残留终检（进程 / 端点 / 目录 / 锁 / 日志 / launchd）。 */
+export function residueReport(instance, lock) {
+	const endpoint = findEndpoint(instance.agentRoot);
+	return {
+		// 「残留」= 停完之后**还在外面跑着**的进程；本进程自己不算残留。
+		appProcessAlive: isAlive(lock && lock.pid) && (!lock || lock.pid !== process.pid),
+		piProcessAlive: isAlive(lock && lock.piPid),
+		socketExists: fs.existsSync(instance.socketPath),
+		endpointExists: endpoint !== null,
+		agentRootExists: fs.existsSync(instance.agentRoot),
+		lockExists: fs.existsSync(instance.lockPath),
+		logExists: fs.existsSync(instance.logPath),
+		launchdUnits: listLaunchdUnits(),
+	};
+}
+
+// ------------------------------------------------------------------ D1 注入
+
+/**
+ * 定位 pi 可执行文件：--pi-bin > PI_BIN > PATH。
+ * 找不到 → 抛错并给安装指引（**不静默降级、不假装在跑**）。
+ */
+export function resolvePiBin(opts = {}) {
+	const env = opts.env || process.env;
+	const explicit = opts.piBin ? String(opts.piBin) : "";
+	const fromEnv = env.PI_BIN ? String(env.PI_BIN) : "";
+	for (const cand of [
+		{ bin: explicit, source: "arg" },
+		{ bin: fromEnv, source: "env" },
+	]) {
+		if (!cand.bin) continue;
+		if (!isExecutableFile(cand.bin)) {
+			throw new Error(
+				`指定的 pi 可执行文件不可用：${cand.bin}（来源：${cand.source === "arg" ? "--pi-bin" : "PI_BIN"}）—— ` +
+					"请给出真实存在且可执行的绝对路径",
+			);
+		}
+		return { bin: cand.bin, source: cand.source };
+	}
+	for (const dir of (env.PATH || "").split(path.delimiter)) {
+		if (!dir) continue;
+		const cand = path.join(dir, "pi");
+		if (isExecutableFile(cand)) return { bin: cand, source: "path" };
+	}
+	throw new Error(MISSING_PI_MESSAGE);
+}
+
+/**
+ * 启动参数：`pi --mode rpc --no-session -e <pi-proactive 包路径>`。
+ * - `--mode rpc`：JSONL 命令/响应/事件；
+ * - `--no-session`：不落会话文件；
+ * - `-e/--extension`：pi 官方的「单次调用试一个包」→ 天然幂等、**不写用户 settings.json**。
+ */
+export function buildLaunchArgs(opts = {}) {
+	const pkgRoot = opts.pkgRoot || DEFAULT_PKG_ROOT;
+	return ["--mode", "rpc", "--no-session", "-e", pkgRoot];
+}
+
+/** 子进程环境：把 agent 根与身份显式交给扩展（**不写任何凭据文件**）。 */
+function buildChildEnv(opts = {}) {
+	const env = opts.env || process.env;
+	const instance = opts.instance;
+	return {
+		...env,
+		PI_CODING_AGENT_DIR: instance.agentRoot,
+		PI_PROACTIVE_AGENT_ID: instance.agentId,
+		// App 下的会话以【协调者】角色运行（DESIGN §9 G-4）。
+		PI_PROACTIVE_ROLE: "coordinator",
+	};
+}
+
+/**
+ * 凭据可用性（**如实**判定，不静默）：
+ * 共享模式沿用宿主 pi 的 auth.json；专属模式下只能靠环境里的 API key。
+ * 都没有 → 明说「能看不能做」。
+ */
+/**
+ * 平台支持判定（**macOS 优先**；Windows 分支留给后续，但**不得**写成「应该能行」）。
+ * 未实现的平台 ⇒ 明确报错，不假装能跑。
+ */
+export function platformSupport(platform = process.platform) {
+	if (platform === "win32") {
+		return {
+			supported: false,
+			reason:
+				"本 App 目前只实现了 macOS / Linux（unix domain socket + 系统通知通道）；" +
+				"Windows 分支**尚未实现**（端点与通道的落位方式都不同）→ 明确报错，不假装能跑。",
+		};
+	}
+	return { supported: true, reason: "" };
+}
+
+/**
+ * 凭据可用性（**如实**判定，不静默）：
+ * 共享模式沿用宿主 pi 的 auth.json；专属模式下只能靠环境里的 API key。
+ * 都没有 → 明说「能看不能做」。
+ */
+export function detectCredential(agentRoot, env = process.env) {
+	const authFile = path.join(agentRoot, "auth.json");
+	try {
+		const raw = JSON.parse(fs.readFileSync(authFile, "utf8"));
+		const providers = Object.entries(raw || {}).filter(
+			([, v]) => v && typeof v === "object" && Object.keys(v).length > 0,
+		);
+		if (providers.length > 0) {
+			return {
+				ok: true,
+				source: "auth.json",
+				detail: `已找到模型凭据（${authFile}：${providers.map(([k]) => k).join("、")}）`,
+			};
+		}
+		// pi 会在**新建**的 agent 根写一个空的 `{}` → 那不是凭据（不得据此说「能做事」）。
+	} catch {
+		/* 没有或读不了 → 继续看环境变量 */
+	}
+	for (const [key, value] of Object.entries(env || {})) {
+		if (key.endsWith("_API_KEY") && typeof value === "string" && value.trim() !== "") {
+			return { ok: true, source: "env", detail: `已找到模型凭据（环境变量 ${key}）` };
+		}
+	}
+	return {
+		ok: false,
+		source: "none",
+		detail: "这个环境里没有模型凭据（既没有登录文件，也没有 API key 环境变量）→ 我现在只能看、不能做事",
+	};
+}
+
+// ------------------------------------------------------------------ D3 驱动（JSONL）
+
+/**
+ * pi 子进程的 JSONL 会话：命令按 **id** 关联响应（不是按顺序）。
+ * 事件（extension_ui_request 等）走监听器。
+ */
+export function createRpcSession(child) {
+	const pending = new Map();
+	const listeners = [];
+	let buf = "";
+	let seq = 0;
+
+	const onData = (chunk) => {
+		buf += String(chunk);
+		let idx;
+		while ((idx = buf.indexOf("\n")) >= 0) {
+			const line = buf.slice(0, idx).replace(/\r$/, "");
+			buf = buf.slice(idx + 1);
+			if (!line.trim()) continue;
+			let rec;
+			try {
+				rec = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (rec && rec.type === "response" && rec.id !== undefined && pending.has(rec.id)) {
+				const resolve = pending.get(rec.id);
+				pending.delete(rec.id);
+				resolve(rec);
+				continue;
+			}
+			for (const cb of listeners) {
+				try {
+					cb(rec);
+				} catch {
+					/* 监听器出错不得影响协议 */
+				}
+			}
+		}
+	};
+	child.stdout.on("data", onData);
+
+	return {
+		/** 发一条命令并等它的响应（超时 ⇒ reject，绝不无限等）。 */
+		request(command, timeoutMs = 10_000) {
+			const id = command.id || `pp-${Date.now()}-${++seq}`;
+			const full = { ...command, id };
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					pending.delete(id);
+					reject(new Error(`RPC ${command.type} 超时（${timeoutMs}ms）`));
+				}, timeoutMs);
+				pending.set(id, (rec) => {
+					clearTimeout(timer);
+					resolve(rec);
+				});
+				child.stdin.write(`${JSON.stringify(full)}\n`, (err) => {
+					if (err) {
+						clearTimeout(timer);
+						pending.delete(id);
+						reject(err);
+					}
+				});
+			});
+		},
+		/** 订阅非响应记录（事件 / extension_ui_request）。 */
+		onRecord(cb) {
+			listeners.push(cb);
+			return () => {
+				const i = listeners.indexOf(cb);
+				if (i >= 0) listeners.splice(i, 1);
+			};
+		},
+		/** 发送一条命令（不等响应）。 */
+		send(command) {
+			const full = { ...command, id: command.id || `pp-${Date.now()}-${++seq}` };
+			child.stdin.write(`${JSON.stringify(full)}\n`);
+			return full.id;
+		},
+	};
+}
+
+// ------------------------------------------------------------------ 单实例锁
+
+function readLock(lockPath) {
+	try {
+		const obj = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+		return obj && typeof obj === "object" ? obj : null;
+	} catch {
+		return null;
+	}
+}
+
+/** 独占创建锁文件（EEXIST = 已经有实例占位）。 */
+function createLock(lockPath, payload) {
+	fs.writeFileSync(lockPath, JSON.stringify(payload, null, 2), { flag: "wx", mode: 0o600 });
+}
+
+/** 覆盖锁内容（我们已持有它）→ 临时文件 + rename（原子替换）。 */
+function updateLock(lockPath, payload) {
+	const tmp = `${lockPath}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), { mode: 0o600 });
+	fs.renameSync(tmp, lockPath);
+}
+
+function removeLock(lockPath) {
+	try {
+		fs.unlinkSync(lockPath);
+	} catch {
+		/* ignore */
+	}
+}
+
+// ------------------------------------------------------------------ 清理 / 残留
+
+/** 删掉本次实例自己的产物（共享模式下**不**删用户的 agent 根）。 */
+function cleanupArtifacts(instance, lock) {
+	const agentId = (lock && lock.agentId) || instance.agentId;
+	try {
+		fs.unlinkSync(path.join(instance.agentRoot, RUN_SUBDIR, `${sanitizeName(agentId)}.sock`));
+	} catch {
+		/* ignore */
+	}
+	try {
+		fs.unlinkSync(path.join(instance.agentRoot, "proactive", "agents", `${sanitizeName(agentId)}.json`));
+	} catch {
+		/* ignore */
+	}
+	if (instance.ownsAgentRoot) {
+		try {
+			fs.rmSync(instance.agentRoot, { recursive: true, force: true });
+		} catch {
+			/* ignore */
+		}
+	}
+	try {
+		fs.unlinkSync(instance.logPath);
+	} catch {
+		/* ignore */
+	}
+}
+
+// ------------------------------------------------------------------ D4 呈现（复用既有资产）
+
+/**
+ * 加载包内模块（**产物态 build/src/*.js 优先，源码态 src/*.ts 兜底**）。
+ * 与 tools/cli.mjs 的 loadSupervisorModule 同一套路：动态 import 的 specifier 是绝对 file:// URL
+ * （.mjs 不能写 .ts 后缀的相对导入 —— 门禁 G3 也是这个口径）。
+ */
+export async function loadPiModule(base, pkgRoot = DEFAULT_PKG_ROOT) {
+	const candidates = [path.join(pkgRoot, "build", "src", `${base}.js`), path.join(pkgRoot, "src", `${base}.ts`)];
+	for (const file of candidates) {
+		if (!fs.existsSync(file)) continue;
+		return await import(pathToFileURL(file).href);
+	}
+	throw new Error(`包内缺少模块 ${base}（期望 build/src/${base}.js 或 src/${base}.ts）—— 请重新安装 pi-proactive`);
+}
+
+/**
+ * 设备级通知通道（**可插拔**）：复用 src/notify.ts 的 macOS osascript 通道与四段载荷。
+ * 不可用时**明确降级**（不静默）：返回 available=false + 原因。
+ */
+export async function createNotifier(opts = {}) {
+	const notify = await loadPiModule("notify", opts.pkgRoot);
+	const channel = notify.createMacChannel({
+		...(opts.exec ? { exec: opts.exec } : {}),
+		...(opts.available ? { available: opts.available } : {}),
+	});
+	return {
+		channel: channel.id,
+		available: (() => {
+			try {
+				return channel.isAvailable();
+			} catch {
+				return false;
+			}
+		})(),
+		/** 发一条通知（绝不抛错：通知失败不得让 App 崩）。 */
+		async send(text, meta = {}) {
+			const payload = notify.buildContactPayload({
+				why: meta.why ?? "pi 助理有事要告诉你",
+				ask: String(text),
+				consequence: meta.consequence ?? "先不用你做什么也可以",
+				howToDisable: meta.howToDisable ?? "在 Pi 会话里说「别烦我」",
+				...(meta.title ? { title: meta.title } : {}),
+			});
+			try {
+				const res = await channel.send(payload);
+				return { ok: Boolean(res.ok), detail: res.detail, payload };
+			} catch (err) {
+				return { ok: false, detail: errText(err), payload };
+			}
+		},
+	};
+}
+
+/** 只读监督面板（复用 src/supervisor-web.ts：只监听 127.0.0.1、只读、单一数据源）。 */
+export async function startPanel(opts = {}) {
+	const web = await loadPiModule("supervisor-web", opts.pkgRoot);
+	const handle = await web.startSupervisorWeb({
+		agentDir: opts.agentDir,
+		port: opts.port ?? 0,
+		...(opts.agentId ? { agentId: opts.agentId } : {}),
+	});
+	return { url: handle.url, port: handle.port, close: () => handle.close() };
+}
+
+// ------------------------------------------------------------------ D6 引导与可发现性
+
+/**
+ * 三问话术（**D2 判据**：App 启动后能一句话回答「它是谁 / 在干什么 / 怎么让它做事」）。
+ * 约束：零必读概念（不出现 agent-dir / 预算 / 宿主 / 端口 …），人话，一句一答。
+ * 文本**逐字写在产物里** → 第三方可直接读到（不依赖运行时的隐藏上下文）。
+ */
+export function describeApp() {
+	return {
+		who: "我是 pi 助理：一个住在你这台机器上的帮手。你不用一直守着它——有事它会主动来找你。",
+		what: "它在做三件事：记住你交给它的任务、盯着该发生的变化、到点或者达成时告诉你。",
+		how: "直接对它说人话就行，比如「盯着 CI 变绿」「有人找我时告诉我」「别烦我」。要它真的替你做事，这个环境里得有模型凭据；没有的话它会明确告诉你。",
+	};
+}
+
+/**
+ * 首启引导（≤3 步 · 一次只问一件事 · 每步都能「算了」· 零必读概念）。
+ * 「算了」= 收工退出，且不留任何残留。
+ */
+export function guideSteps() {
+	return [
+		{ id: "stay", question: "要我以后常驻吗？", options: ["要", "算了"], cancel: "算了" },
+		{ id: "watch", question: "要我盯着什么吗？说一句话就行。", options: ["说一句话", "算了"], cancel: "算了" },
+		{ id: "ping", question: "有事我这样找你行吗？（系统通知）", options: ["行", "算了"], cancel: "算了" },
+	];
+}
+
+// ------------------------------------------------------------------ 回执
+
+function baseReceipt(instance) {
+	return {
+		status: "not-running",
+		agentRootKind: instance.agentRootKind,
+		agentRoot: instance.agentRoot,
+		agentId: instance.agentId,
+		socketPath: instance.socketPath,
+		socketPathBytes: instance.socketPathBytes,
+		socketOverBudget: instance.socketOverBudget,
+		lockPath: instance.lockPath,
+		logPath: instance.logPath,
+		pkgRoot: instance.pkgRoot,
+	};
+}
+
+// ------------------------------------------------------------------ 运行中的会话（进程内）
+
+/** 本进程内已启动的会话（按锁路径索引）→ `ask` 等命令可以复用同一份 JSONL 连接。 */
+const sessions = new Map();
+
+/** 通知去重集合（按事件 id）→ 同一事件不弹两次。 */
+const notifiedIds = new Set();
+
+// ------------------------------------------------------------------ 启动 / 停止 / 状态
+
+/**
+ * 启动 App：拉起 pi → **等就绪信号**（不是 sleep）→ 拉起只读面板 → 注册通知通道 → 回执。
+ *
+ * 就绪判定（两道，都要真证据）：
+ *   ① AC1：RPC `get_commands` 的**进程内**扩展清单里有来自本包的扩展入口；
+ *   ② AC2：`<agentRoot>/proactive/run/*.sock` 真实出现。
+ * 任一不满足 → **明确失败**（报【未就绪】+ 诊断），不静默降级、不假装在跑。
+ */
+export async function startApp(opts = {}) {
+	const instance = resolveInstance(opts);
+	const base = baseReceipt(instance);
+	const timeoutMs = opts.timeoutMs || 30_000;
+
+	// --- 平台：macOS / Linux 优先（unix socket + osascript/notify-send）；Windows 分支**未实现**
+	//     → 明确报错，不写「应该能行」。
+	const platform = platformSupport();
+	if (!platform.supported) {
+		return { ...base, status: "error", error: platform.reason };
+	}
+	// --- 单实例锁：已有活实例 → 幂等回执「已在运行」（不产生第二份实例/第二份通知注册）
+	const existing = readLock(instance.lockPath);
+	if (existing) {
+		if (isAlive(existing.pid)) {
+			const running = instanceFromLock(existing, instance);
+			return {
+				...baseReceipt(running),
+				status: "already-running",
+				pid: existing.pid,
+				piPid: existing.piPid,
+				piBin: existing.piBin,
+				piBinSource: existing.piBinSource,
+				launchArgs: existing.launchArgs,
+				panelUrl: existing.panelUrl,
+				evidence: existing.evidence,
+				residue: residueReport(running, existing),
+			};
+		}
+		// 陈旧锁（进程已死）→ 清掉它和它的残留，再来一次
+		cleanupArtifacts(instanceFromLock(existing, instance), existing);
+		removeLock(instance.lockPath);
+	}
+
+	// --- 定位 pi（找不到 → 明确报错 + 安装指引）
+	let pi;
+	try {
+		pi = resolvePiBin({ piBin: opts.piBin, env: opts.env });
+	} catch (err) {
+		return { ...base, status: "error", error: errText(err) };
+	}
+
+	// --- 占锁（独占）：抢不到 = 别的实例刚起来 → 幂等回执
+	try {
+		createLock(instance.lockPath, {
+			pid: process.pid,
+			piPid: 0,
+			agentRootKind: instance.agentRootKind,
+			agentRoot: instance.agentRoot,
+			ownsAgentRoot: instance.ownsAgentRoot,
+			agentId: instance.agentId,
+			logPath: instance.logPath,
+			pkgRoot: instance.pkgRoot,
+			piBin: pi.bin,
+			piBinSource: pi.source,
+			launchArgs: buildLaunchArgs({ pkgRoot: instance.pkgRoot }),
+			startedAt: Date.now(),
+		});
+	} catch (err) {
+		if (err && err.code === "EEXIST") {
+			const lock = readLock(instance.lockPath);
+			if (lock && isAlive(lock.pid)) {
+				const running = instanceFromLock(lock, instance);
+				return {
+					...baseReceipt(running),
+					status: "already-running",
+					pid: lock.pid,
+					piPid: lock.piPid,
+					panelUrl: lock.panelUrl,
+					evidence: lock.evidence,
+					residue: residueReport(running, lock),
+				};
+			}
+			return { ...base, status: "error", error: `锁文件存在但无法判定归属：${instance.lockPath}` };
+		}
+		return { ...base, status: "error", error: `写锁失败：${errText(err)}` };
+	}
+
+	// --- 拉起 pi
+	let child = null;
+	let stderrTail = "";
+	try {
+		fs.mkdirSync(instance.agentRoot, { recursive: true, mode: 0o700 });
+		const logFd = fs.openSync(instance.logPath, "a", 0o600);
+		try {
+			child = spawn(pi.bin, buildLaunchArgs({ pkgRoot: instance.pkgRoot }), {
+				env: buildChildEnv({ instance, env: opts.env }),
+				stdio: ["pipe", "pipe", "pipe"],
+			});
+		} finally {
+			fs.closeSync(logFd);
+		}
+	} catch (err) {
+		removeLock(instance.lockPath);
+		return { ...base, status: "error", error: `启动 pi 失败：${errText(err)}` };
+	}
+	child.stderr.on("data", (c) => {
+		stderrTail = (stderrTail + String(c)).slice(-2000);
+		try {
+			fs.appendFileSync(instance.logPath, String(c));
+		} catch {
+			/* ignore */
+		}
+	});
+
+	const session = createRpcSession(child);
+	const exited = new Promise((resolve) => child.on("exit", (code) => resolve(code)));
+	let exitInfo = null;
+	void exited.then((code) => {
+		exitInfo = { code };
+	});
+
+	const lockPayload = {
+		...(readLock(instance.lockPath) || {}),
+		piPid: child.pid,
+		piBin: pi.bin,
+		piBinSource: pi.source,
+		launchArgs: buildLaunchArgs({ pkgRoot: instance.pkgRoot }),
+	};
+	try {
+		updateLock(instance.lockPath, lockPayload);
+	} catch {
+		/* ignore */
+	}
+
+	// --- 就绪判定（状态等待，超时 ⇒ 报【未就绪】+ 诊断）
+	const ready = await waitReady(session, instance, timeoutMs, () => exitInfo, () => stderrTail);
+	if (!ready.ok) {
+		killChild(child);
+		cleanupArtifacts(instance, { agentId: instance.agentId });
+		removeLock(instance.lockPath);
+		return { ...base, status: "error", error: `未就绪：${ready.reason}`, evidence: ready.evidence };
+	}
+
+	// --- 通知通道（可插拔；不可用 ⇒ 明确降级提示，面板仍在）
+	let notifier = null;
+	let notifyDegraded = "";
+	try {
+		notifier = await createNotifier({
+			pkgRoot: instance.pkgRoot,
+			...(opts.notifyExec ? { exec: opts.notifyExec } : {}),
+			...(opts.notifyAvailable ? { available: opts.notifyAvailable } : {}),
+		});
+		if (!notifier.available) {
+			notifyDegraded = `系统通知不可用（通道 ${notifier.channel} 在这台机器上不可用）→ 面板仍在，通知改在会话里给你`;
+		}
+	} catch (err) {
+		notifyDegraded = `系统通知通道初始化失败：${errText(err)} → 面板仍在`;
+	}
+
+	// --- 通知记录（证据）+ 去重
+	const notificationRecordPath = path.join(instance.agentRoot, APP_SUBDIR, "notifications.jsonl");
+	const notificationState = { count: 0, last: null };
+	const unsubscribe = session.onRecord((rec) => {
+		if (!rec || rec.type !== "extension_ui_request" || rec.method !== "notify") return;
+		const eventId = String(rec.id || rec.message || "");
+		if (eventId && notifiedIds.has(eventId)) return; // 同一事件不弹两次
+		if (eventId) notifiedIds.add(eventId);
+		const message = String(rec.message ?? "");
+		const done = notifier
+			? notifier.send(message, { title: rec.notifyType === "error" ? "助理出错了" : "助理找你有事" })
+			: Promise.resolve({ ok: false, detail: "无通知通道" });
+		void done.then((res) => {
+			notificationState.count += 1;
+			notificationState.last = { eventId, message, ok: Boolean(res.ok), detail: res.detail };
+			try {
+				fs.mkdirSync(path.dirname(notificationRecordPath), { recursive: true });
+				fs.appendFileSync(
+					notificationRecordPath,
+					`${JSON.stringify({ ts: Date.now(), eventId, message, ok: Boolean(res.ok), detail: res.detail })}\n`,
+				);
+			} catch {
+				/* 记录失败不得影响主流程 */
+			}
+			if (opts.onNotify) opts.onNotify(notificationState.last);
+		});
+	});
+
+	// --- 只读监督面板（可失败降级，不阻塞主流程）
+	let panel = null;
+	let panelDegraded = "";
+	try {
+		panel = await startPanel({
+			pkgRoot: instance.pkgRoot,
+			agentDir: instance.agentRoot,
+			port: opts.panelPort ?? 0,
+			agentId: instance.agentId,
+		});
+	} catch (err) {
+		panelDegraded = `监督面板起不来：${errText(err)} → 其余功能不受影响`;
+	}
+
+	// --- 凭据如实判定（不静默）
+	const credential = detectCredential(instance.agentRoot, opts.env || process.env);
+
+	// --- 写锁（供退出清理与幂等判定）
+	try {
+		updateLock(instance.lockPath, {
+			...lockPayload,
+			evidence: ready.evidence,
+			panelUrl: panel ? panel.url : undefined,
+			notifications: notificationState.count,
+		});
+	} catch {
+		/* ignore */
+	}
+
+	sessions.set(instance.lockPath, { child, session, panel, unsubscribe, instance });
+
+	return {
+		...base,
+		status: "started",
+		pid: process.pid,
+		piPid: child.pid,
+		piBin: pi.bin,
+		piBinSource: pi.source,
+		launchArgs: lockPayload.launchArgs,
+		panelUrl: panel ? panel.url : undefined,
+		panelPort: panel ? panel.port : undefined,
+		notify: {
+			channel: notifier ? notifier.channel : "none",
+			available: Boolean(notifier && notifier.available),
+			...(notifyDegraded ? { degraded: notifyDegraded } : {}),
+		},
+		...(panelDegraded ? { panelDegraded } : {}),
+		credential,
+		evidence: ready.evidence,
+		supervisor: await collectSupervisorSnapshot(instance),
+		notificationRecordPath,
+		notifications: notificationState,
+		guidance: { steps: guideSteps(), nextStep: guideSteps()[0] },
+		residue: residueReport(instance, { pid: process.pid, piPid: child.pid }),
+		session: { child, session, panel, unsubscribe, instance },
+	};
+}
+
+/** 等就绪信号（AC1 扩展注册 + AC2 端点出现）。返回 {ok, reason, evidence}。 */
+async function waitReady(session, instance, timeoutMs, exitInfo, stderrTail) {
+	const evidence = {
+		extensionListSource: "rpc:get_commands",
+		endpointExists: false,
+		registryFile: path.join(instance.agentRoot, "proactive", "agents", `${sanitizeName(instance.agentId)}.json`),
+	};
+	const diagnose = (reason) => {
+		const pkgExt = path.join(instance.pkgRoot, "build", "extensions", "proactive.js");
+		const built = fs.existsSync(pkgExt);
+		return (
+			`${reason}\n` +
+			`诊断：包路径=${instance.pkgRoot}｜扩展入口${built ? "存在" : "**不存在**（请先构建：bash pi-proactive/tools/build-release.sh）"}｜` +
+			`端点目录=${path.join(instance.agentRoot, RUN_SUBDIR)}｜端点预算=${instance.socketPathBytes}B/${MAX_SOCKET_PATH_BYTES}B` +
+			(instance.socketOverBudget ? "（**超预算** → 端点建不出来）" : "") +
+			`\n子进程退出=${exitInfo() ? JSON.stringify(exitInfo()) : "仍在运行"}｜stderr 末尾=${(stderrTail() || "").slice(-400) || "（空）"}`
+		);
+	};
+
+	// ① 进程内扩展清单必须含 pi-proactive（AC1 的**取证**）
+	let commands = [];
+	try {
+		const res = await session.request({ type: "get_commands" }, Math.min(timeoutMs, 15_000));
+		commands = (res && res.data && res.data.commands) || [];
+	} catch (err) {
+		return {
+			ok: false,
+			reason: diagnose(`读不到 pi 进程内的扩展清单（${errText(err)}）`),
+			evidence,
+		};
+	}
+	const hit = commands.find(
+		(c) =>
+			c &&
+			c.source === "extension" &&
+			typeof (c.sourceInfo && c.sourceInfo.path) === "string" &&
+			c.sourceInfo.path.startsWith(instance.pkgRoot),
+	);
+	evidence.extensionPath = hit ? hit.sourceInfo.path : undefined;
+	evidence.extensionCommand = hit ? hit.name : undefined;
+	evidence.extensionCount = commands.length;
+	if (!hit) {
+		return {
+			ok: false,
+			reason: diagnose(
+				`注入未生效：pi 进程内的扩展清单里没有来自 ${instance.pkgRoot} 的扩展（source=extension）`,
+			),
+			evidence,
+		};
+	}
+
+	// ② 端点必须**真的出现**（AC2）
+	const endpoint = await waitForEndpoint(instance, timeoutMs);
+	evidence.endpointExists = endpoint !== null;
+	evidence.endpointPath = endpoint ? endpoint.path : undefined;
+	evidence.endpointBytes = endpoint ? endpoint.bytes : undefined;
+	if (!endpoint) {
+		return {
+			ok: false,
+			reason: diagnose(
+				`端点未出现（**未触发**，不是「不残留」）：${path.join(instance.agentRoot, RUN_SUBDIR)} 下没有 *.sock`,
+			),
+			evidence,
+		};
+	}
+	return { ok: true, evidence };
+}
+
+/** 等端点出现（返回端点信息；超时 = null = 未触发）。 */
+async function waitForEndpoint(instance, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const ep = findEndpoint(instance.agentRoot);
+		if (ep) return ep;
+		if (Date.now() >= deadline) return null;
+		await new Promise((r) => setTimeout(r, 100));
+	}
+}
+
+/** 只读监督快照（命令面口径 —— 与面板同一份聚合，数字必然逐字一致）。 */
+async function collectSupervisorSnapshot(instance) {
+	try {
+		const state = await loadPiModule("supervisor-state", instance.pkgRoot);
+		return state.collectSupervisorState({ agentDir: instance.agentRoot, agentId: instance.agentId });
+	} catch {
+		return undefined;
+	}
+}
+
+/** 终止 pi 子进程（先 TERM 后 KILL）。 */
+function killChild(child) {
+	if (!child || child.exitCode !== null) return;
+	try {
+		child.kill("SIGTERM");
+	} catch {
+		/* ignore */
+	}
+	const timer = setTimeout(() => {
+		try {
+			child.kill("SIGKILL");
+		} catch {
+			/* ignore */
+		}
+	}, 3_000);
+	timer.unref?.();
+}
+
+/** 等一个 pid 消失（最多 ms）。 */
+async function waitGone(pid, ms) {
+	const deadline = Date.now() + ms;
+	while (Date.now() < deadline) {
+		if (!isAlive(pid)) return true;
+		await new Promise((r) => setTimeout(r, 100));
+	}
+	return !isAlive(pid);
+}
+
+/**
+ * 停止 App：停 App 进程（它会带走 pi）→ 兜底杀 pi → 清残留 → 回执残留终检。
+ * 没在跑 → 幂等回执「未在运行」。
+ */
+export async function stopApp(opts = {}) {
+	const instance = resolveInstance(opts);
+	const lock = readLock(instance.lockPath);
+	if (!lock) {
+		return { ...baseReceipt(instance), status: "not-running", residue: residueReport(instance, null) };
+	}
+	// 清理目标 = 锁里记的那个实例（不是本进程 pid 派生的路径 —— 否则清的是自己，不是它）。
+	const target = instanceFromLock(lock, instance);
+	const live = sessions.get(instance.lockPath);
+	if (live) {
+		if (live.unsubscribe) live.unsubscribe();
+		if (live.panel) await live.panel.close().catch(() => {});
+		killChild(live.child);
+		sessions.delete(instance.lockPath);
+	}
+	// App 进程（不是自己就杀）
+	if (lock.pid && lock.pid !== process.pid && isAlive(lock.pid)) {
+		try {
+			process.kill(lock.pid, "SIGTERM");
+		} catch {
+			/* ignore */
+		}
+		if (!(await waitGone(lock.pid, 5_000))) {
+			try {
+				process.kill(lock.pid, "SIGKILL");
+			} catch {
+				/* ignore */
+			}
+			await waitGone(lock.pid, 2_000);
+		}
+	}
+	// pi 子进程
+	if (lock.piPid && isAlive(lock.piPid)) {
+		try {
+			process.kill(lock.piPid, "SIGTERM");
+		} catch {
+			/* ignore */
+		}
+		if (!(await waitGone(lock.piPid, 5_000))) {
+			try {
+				process.kill(lock.piPid, "SIGKILL");
+			} catch {
+				/* ignore */
+			}
+			await waitGone(lock.piPid, 2_000);
+		}
+	}
+	cleanupArtifacts(target, lock);
+	removeLock(instance.lockPath);
+	return {
+		...baseReceipt(target),
+		status: "stopped",
+		pid: lock.pid,
+		piPid: lock.piPid,
+		residue: residueReport(target, lock),
+	};
+}
+
+/** 状态查询：如实反映在跑 / 没在跑（附与面板同源的只读快照）。 */
+export async function statusApp(opts = {}) {
+	const instance = resolveInstance(opts);
+	const lock = readLock(instance.lockPath);
+	if (!lock) {
+		return {
+			...baseReceipt(instance),
+			status: "not-running",
+			residue: residueReport(instance, null),
+			supervisor: await collectSupervisorSnapshot(instance),
+		};
+	}
+	const target = instanceFromLock(lock, instance);
+	const running = isAlive(lock.pid);
+	return {
+		...baseReceipt(target),
+		status: running ? "running" : "not-running",
+		pid: lock.pid,
+		piPid: lock.piPid,
+		piBin: lock.piBin,
+		piBinSource: lock.piBinSource,
+		launchArgs: lock.launchArgs,
+		panelUrl: lock.panelUrl,
+		evidence: lock.evidence,
+		residue: residueReport(target, lock),
+		supervisor: await collectSupervisorSnapshot(target),
+	};
+}
+
+/**
+ * 下发一条 prompt 并等 **id 关联**的响应（AC3 / D3 驱动）。
+ * 进程内已有实例 → 复用同一份 JSONL 连接；否则起一个一次性实例（起 → 问 → 停）。
+ */
+export async function askApp(opts = {}) {
+	const instance = resolveInstance(opts);
+	const live = sessions.get(instance.lockPath);
+	if (live) {
+		const request = { type: "prompt", message: String(opts.message ?? "") };
+		try {
+			const response = await live.session.request(request, opts.timeoutMs || 30_000);
+			return { ok: true, request: { ...request, id: response.id }, response, reused: true };
+		} catch (err) {
+			return { ok: false, error: errText(err), request };
+		}
+	}
+	const started = await startApp(opts);
+	if (started.status !== "started") {
+		return { ok: false, error: String(started.error ?? `启动失败（${started.status}）`) };
+	}
+	const liveSession = started.session;
+	const request = { type: "prompt", message: String(opts.message ?? "") };
+	try {
+		const response = await liveSession.session.request(request, opts.timeoutMs || 30_000);
+		await stopApp(opts);
+		return { ok: true, request: { ...request, id: response.id }, response, reused: false };
+	} catch (err) {
+		await stopApp(opts);
+		return { ok: false, error: errText(err), request };
+	}
+}
+
+// ------------------------------------------------------------------ CLI
+
+const USAGE = `pi-proactive App —— pi-agent 的 shim / wrapper（最小可用外壳）
+
+用法：
+  app.mjs start [--shared] [--agent-dir DIR] [--pi-bin PATH] [--pkg-root DIR] [--tmp-dir DIR] [--json]
+  app.mjs stop   [--json]
+  app.mjs status [--json]
+  app.mjs describe [--json]     三问：它是谁 / 在干什么 / 怎么让它做事
+  app.mjs guide   [--json]      首启引导（≤3 步）
+  app.mjs ask "<要它做的事>" [--json]
+
+说明：
+  start    拉起 pi（--mode rpc --no-session -e <pi-proactive 包>）并常驻；等**扩展真的注册**才算就绪；
+           二次启动回执「已在运行」（不产生第二份实例）。
+  stop     停止并做残留终检（进程 / socket / 临时根 / 锁 / 日志 / launchd）。
+  status   如实汇报当前状态（含只读监督快照）。
+  describe 三问话术（零必读概念）。
+  guide    首启引导的步骤。
+  ask      经 JSONL 下发一条 prompt 并回带 id 关联的响应。
+
+选项：
+  --shared           用宿主 pi 的 agent 根（默认：专属短路径 /tmp/pp-app-<pid>）
+  --agent-dir DIR    显式指定 agent 根（不会被 App 删除）
+  --pi-bin PATH      指定 pi 可执行文件（默认：PI_BIN > PATH）
+  --pkg-root DIR     指定 pi-proactive 包路径（默认：本包自身）
+  --tmp-dir DIR      临时根的基目录（默认 /tmp）
+  --json             机器可读回执（每行一个 JSON）`;
+
+/** 控制词：「算了」= 收工退出（零残留）；「退出」= 直接退出。 */
+const CANCEL_WORDS = ["算了", "cancel"];
+const QUIT_WORDS = ["退出", "quit", "exit"];
+
+function parseArgs(argv) {
+	const flags = { json: false };
+	const rest = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--json") flags.json = true;
+		else if (a === "--shared") flags.shared = true;
+		else if (a === "--agent-dir") flags.agentDir = argv[++i];
+		else if (a === "--pi-bin") flags.piBin = argv[++i];
+		else if (a === "--pkg-root") flags.pkgRoot = argv[++i];
+		else if (a === "--tmp-dir") flags.tmpDir = argv[++i];
+		else if (a === "--help" || a === "-h") flags.help = true;
+		else if (a.startsWith("--")) throw new Error(`未知参数：${a}`);
+		else rest.push(a);
+	}
+	return { flags, rest };
+}
+
+function printReceipt(receipt, json) {
+	if (json) {
+		const { session, ...rest } = receipt;
+		process.stdout.write(`${JSON.stringify(rest)}\n`);
+		return;
+	}
+	const lines = [
+		`状态：${receipt.status}`,
+		`agent 根：${receipt.agentRoot}（${receipt.agentRootKind}）`,
+		`端点：${receipt.socketPath}（${receipt.socketPathBytes}B / 上限 ${MAX_SOCKET_PATH_BYTES}B${receipt.socketOverBudget ? " · 超长！" : ""}）`,
+	];
+	if (receipt.piPid) lines.push(`pi 进程：${receipt.piPid}（${receipt.piBin || "?"}）`);
+	if (receipt.panelUrl) lines.push(`监督面板（只读）：${receipt.panelUrl}`);
+	if (receipt.notify) {
+		lines.push(
+			`系统通知：${receipt.notify.available ? `可用（${receipt.notify.channel}）` : `**不可用** · ${receipt.notify.degraded || "已降级"}`}`,
+		);
+	}
+	if (receipt.credential) lines.push(`凭据：${receipt.credential.detail}`);
+	if (receipt.evidence) {
+		lines.push(`注入证据：${receipt.evidence.extensionListSource} → ${receipt.evidence.extensionPath || "（无）"}`);
+		lines.push(`端点已出现：${receipt.evidence.endpointExists ? "是" : "否"}`);
+	}
+	if (receipt.residue) {
+		const r = receipt.residue;
+		lines.push(
+			`残留终检：进程 ${r.appProcessAlive || r.piProcessAlive ? "有" : "无"} · 端点 ${r.endpointExists ? "有" : "无"} · ` +
+				`agent 根 ${r.agentRootExists ? "有" : "无"} · 锁 ${r.lockExists ? "有" : "无"} · launchd ${r.launchdUnits.length}`,
+		);
+	}
+	if (receipt.error) lines.push(`错误：${receipt.error}`);
+	process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+/** 引导问句（一行一步，零必读概念）。 */
+function printGuidance(step) {
+	process.stdout.write(`下一步：${step.question}（${step.options.join(" / ")}）\n`);
+}
+
+async function main(argv) {
+	const cmd = argv[0];
+	let parsed;
+	try {
+		parsed = parseArgs(argv.slice(1));
+	} catch (err) {
+		process.stderr.write(`${errText(err)}\n${USAGE}\n`);
+		return 2;
+	}
+	const { flags, rest } = parsed;
+	if (!cmd || flags.help || cmd === "help") {
+		process.stdout.write(`${USAGE}\n`);
+		return cmd ? 0 : 2;
+	}
+	const opts = {
+		agentRootKind: flags.shared ? "shared" : "dedicated",
+		agentDir: flags.agentDir,
+		piBin: flags.piBin,
+		pkgRoot: flags.pkgRoot,
+		tmpDir: flags.tmpDir,
+	};
+
+	if (cmd === "describe") {
+		const d = describeApp();
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(d)}\n`);
+			return 0;
+		}
+		process.stdout.write(`它是谁：${d.who}\n在干什么：${d.what}\n怎么让它做事：${d.how}\n`);
+		return 0;
+	}
+	if (cmd === "guide") {
+		const steps = guideSteps();
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify({ steps })}\n`);
+			return 0;
+		}
+		process.stdout.write(`${steps.map((s, i) => `${i + 1}. ${s.question}（${s.options.join(" / ")}）`).join("\n")}\n`);
+		return 0;
+	}
+	if (cmd === "status") {
+		const receipt = await statusApp(opts);
+		printReceipt(receipt, flags.json);
+		return 0;
+	}
+	if (cmd === "stop") {
+		const receipt = await stopApp(opts);
+		printReceipt(receipt, flags.json);
+		return 0;
+	}
+	if (cmd === "ask") {
+		const message = rest.join(" ").trim();
+		if (!message) {
+			process.stderr.write(`ask 需要一句话：app.mjs ask "<要它做的事>"\n`);
+			return 2;
+		}
+		const result = await askApp({ ...opts, message });
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result)}\n`);
+		} else if (result.ok) {
+			process.stdout.write(`${JSON.stringify(result.response)}\n`);
+		} else {
+			process.stderr.write(`ask 失败：${String(result.error)}\n`);
+		}
+		return result.ok ? 0 : 1;
+	}
+	if (cmd !== "start") {
+		process.stderr.write(`未知子命令：${cmd}\n${USAGE}\n`);
+		return 2;
+	}
+
+	// --- start：拉起并常驻（App 就是 pi 的守护者：它持有 pi 的 stdin/stdout）
+	const receipt = await startApp(opts);
+	printReceipt(receipt, flags.json);
+	if (receipt.status === "error") return 2;
+	if (receipt.status !== "started") {
+		// already-running → 幂等回执（不常驻第二份实例）
+		process.stdout.write("已在运行（没有起第二份）\n");
+		return 0;
+	}
+	const live = receipt.session;
+	const steps = guideSteps();
+	let stepIndex = 0;
+	printGuidance(steps[0]);
+
+	let stopping = false;
+	const shutdown = async (reason) => {
+		if (stopping) return;
+		stopping = true;
+		if (live) {
+			if (live.unsubscribe) live.unsubscribe();
+			if (live.panel) await live.panel.close().catch(() => {});
+			try {
+				live.child.stdin.end();
+			} catch {
+				/* ignore */
+			}
+			const deadline = Date.now() + 3_000;
+			while (live.child.exitCode === null && Date.now() < deadline) {
+				await new Promise((r) => setTimeout(r, 50));
+			}
+			killChild(live.child);
+		}
+		const instance = resolveInstance(opts);
+		cleanupArtifacts(instance, { agentId: instance.agentId });
+		removeLock(instance.lockPath);
+		sessions.delete(instance.lockPath);
+		process.stdout.write(`${reason}\n`);
+		process.exit(0);
+	};
+
+	process.on("SIGINT", () => void shutdown("收到中断，收工（不留残留）"));
+	process.on("SIGTERM", () => void shutdown("收到结束信号，收工（不留残留）"));
+	if (live) {
+		live.child.on("exit", () => {
+			if (!stopping) void shutdown("助理进程退出了，收工（不留残留）");
+		});
+	}
+
+	// 会话驱动：stdin 的一行 = 一条 prompt（按 id 关联响应）
+	const promptOf = async (text) => {
+		try {
+			const res = await live.session.request({ type: "prompt", message: text }, 120_000);
+			process.stdout.write(`${JSON.stringify(res)}\n`);
+		} catch (err) {
+			process.stdout.write(`下发失败：${errText(err)}\n`);
+		}
+	};
+
+	if (process.stdin.isTTY) {
+		// 交互式：一问一答推进引导；任何一步都能「算了」→ 零残留
+		process.stdin.setEncoding("utf8");
+		let buffer = "";
+		process.stdin.on("data", (chunk) => {
+			buffer += String(chunk);
+			let i;
+			while ((i = buffer.indexOf("\n")) >= 0) {
+				const line = buffer.slice(0, i).trim();
+				buffer = buffer.slice(i + 1);
+				if (!line) continue;
+				if (CANCEL_WORDS.includes(line)) {
+					void shutdown("好，收工（不留残留）");
+					return;
+				}
+				if (QUIT_WORDS.includes(line)) {
+					void shutdown("退出（不留残留）");
+					return;
+				}
+				if (stepIndex < steps.length && (line === steps[stepIndex].options[0] || line === "要" || line === "是")) {
+					stepIndex += 1;
+					if (stepIndex < steps.length) {
+						printGuidance(steps[stepIndex]);
+					} else {
+						process.stdout.write("好，都记下了。接下来直接跟我说要做什么就行。\n");
+					}
+					continue;
+				}
+				// 其余一律当作「要它做的事」
+				stepIndex = steps.length;
+				void promptOf(line);
+			}
+		});
+	} else {
+		process.stdin.setEncoding("utf8");
+		let buffer = "";
+		process.stdin.on("data", (chunk) => {
+			buffer += String(chunk);
+			let i;
+			while ((i = buffer.indexOf("\n")) >= 0) {
+				const line = buffer.slice(0, i).trim();
+				buffer = buffer.slice(i + 1);
+				if (!line) continue;
+				if (CANCEL_WORDS.includes(line) || QUIT_WORDS.includes(line)) {
+					void shutdown("好，收工（不留残留）");
+					return;
+				}
+				void promptOf(line);
+			}
+		});
+	}
+
+	// 常驻：等信号
+	await new Promise(() => {});
+	return 0;
+}
+
+const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+if (isMain) {
+	main(process.argv.slice(2))
+		.then((code) => {
+			process.exitCode = code;
+		})
+		.catch((err) => {
+			process.stderr.write(`[pi-proactive app] 未预期错误：${errText(err)}\n`);
+			process.exitCode = 1;
+		});
+}