@rexvane/piweb 0.3.18 → 0.3.20

package/src/lib/session-reader.ts

@@ -31,6 +31,18 @@ function toSummary(info: {
 	};
 }
 
+/** firstMessage 只当侧栏标题与搜索用：整段贴进来的长提问不该随每 3 秒一次的列表轮询反复下发 */
+export const FIRST_MESSAGE_MAX_CHARS = 300;
+
+function clipFirstMessage(text: string): string {
+	if (text.length <= FIRST_MESSAGE_MAX_CHARS) return text;
+	let end = FIRST_MESSAGE_MAX_CHARS;
+	const last = text.charCodeAt(end - 1);
+	// 别把代理对（emoji 等）切成半个
+	if (last >= 0xd800 && last <= 0xdbff) end -= 1;
+	return `${text.slice(0, end)}…`;
+}
+
 /**
  * 单个 JSONL → 摘要，与 SDK `SessionManager.listAll()` 的口径一致：
  * 首行必须是 session 头；名字取最后一条 session_info；messageCount 计全部 message 条目；
@@ -82,7 +94,7 @@ async function summarize(filePath: string, stat: { mtime: Date }): Promise<Sessi
 			created: new Date(String(header.timestamp)),
 			modified,
 			messageCount,
-			firstMessage: firstMessage || "(no messages)",
+			firstMessage: clipFirstMessage(firstMessage) || "(no messages)",
 		});
 	} catch {
 		return null;
@@ -90,10 +102,92 @@ async function summarize(filePath: string, stat: { mtime: Date }): Promise<Sessi
 }
 
 /** 按文件缓存的摘要：mtime 与大小都没变就不重读（侧栏每 3 秒轮询一次，全盘重读几 MB JSONL 太浪费） */
-const summaryCache = new Map<string, { mtimeMs: number; size: number; summary: SessionSummary | null }>();
+const summaryCache = new Map<string, CachedSummary>();
 /** 并发列表请求共用一次扫描 */
 let scanning: Promise<SessionSummary[]> | null = null;
 
+interface CachedSummary {
+	mtimeMs: number;
+	size: number;
+	summary: SessionSummary | null;
+}
+
+/**
+ * 摘要缓存落盘：进程内的 summaryCache 一重启就没了，而冷启动要把 ~/.pi/agent/sessions 下
+ * 的 JSONL 全量解析一遍（本机 36 个会话 / 17.5MB ≈ 136ms，会话越多越贵）。落盘后重启只需
+ * 按 mtime + 大小校验，命中就沿用摘要——侧栏首次渲染从"全量解析"变成"读一个小 JSON"。
+ * 索引只是加速：读不到、版本不符、写不进去都退化成全量扫描，绝不影响正确性。
+ */
+/** 2：firstMessage 开始截断，旧索引里的整段原文要重新摘要 */
+const INDEX_VERSION = 2;
+const INDEX_FILENAME = "piweb-session-index.json";
+const INDEX_MAX_ENTRIES = 5000;
+const INDEX_SAVE_DELAY_MS = 1500;
+let indexLoadedFrom: string | null = null;
+let indexDirty = false;
+let indexTimer: ReturnType<typeof setTimeout> | null = null;
+
+function indexPath(): string {
+	return path.join(getAgentDir(), INDEX_FILENAME);
+}
+
+type IndexEntry = [mtimeMs: number, size: number, summary: SessionSummary | null];
+
+async function loadIndex(): Promise<void> {
+	const target = indexPath();
+	if (indexLoadedFrom === target) return;
+	indexLoadedFrom = target;
+	// 会话库换了目录（PI_CODING_AGENT_DIR）就不能再沿用上一个目录的摘要
+	summaryCache.clear();
+	try {
+		const raw = JSON.parse(await fs.readFile(target, "utf8")) as { version?: unknown; entries?: Record<string, unknown> };
+		if (raw?.version !== INDEX_VERSION || !raw.entries || typeof raw.entries !== "object" || Array.isArray(raw.entries)) return;
+		for (const [file, entry] of Object.entries(raw.entries)) {
+			if (!Array.isArray(entry) || entry.length !== 3) continue;
+			const [mtimeMs, size, summary] = entry as IndexEntry;
+			if (typeof mtimeMs !== "number" || typeof size !== "number") continue;
+			summaryCache.set(file, { mtimeMs, size, summary: summary && typeof summary === "object" ? summary : null });
+		}
+	} catch {
+		/* 首次运行没有索引，或索引损坏：全量扫描即可 */
+	}
+}
+
+function scheduleIndexSave(): void {
+	indexDirty = true;
+	if (indexTimer) return;
+	indexTimer = setTimeout(() => {
+		indexTimer = null;
+		void saveIndex();
+	}, INDEX_SAVE_DELAY_MS);
+	indexTimer.unref?.();
+}
+
+async function saveIndex(): Promise<void> {
+	if (!indexDirty) return;
+	indexDirty = false;
+	// 写回缓存所属的那个目录：索引路径不能在落盘时重新解析（会话库换目录时会把 A 的摘要写进 B）
+	const target = indexLoadedFrom;
+	if (!target) return;
+	const entries: Record<string, IndexEntry> = {};
+	// 只留最近改动的若干条，避免索引本身无限长
+	for (const [file, cached] of [...summaryCache.entries()].sort((a, b) => b[1].mtimeMs - a[1].mtimeMs).slice(0, INDEX_MAX_ENTRIES)) {
+		entries[file] = [cached.mtimeMs, cached.size, cached.summary];
+	}
+	try {
+		await fs.mkdir(path.dirname(target), { recursive: true });
+		const temporary = `${target}.${process.pid}.tmp`;
+		try {
+			await fs.writeFile(temporary, JSON.stringify({ version: INDEX_VERSION, entries }), "utf8");
+			await fs.rename(temporary, target);
+		} finally {
+			await fs.rm(temporary, { force: true }).catch(() => undefined);
+		}
+	} catch {
+		/* 索引写不进去只影响速度，下一次列表请求照常扫描 */
+	}
+}
+
 async function scanSessions(): Promise<SessionSummary[]> {
 	const root = path.join(getAgentDir(), "sessions");
 	const files: string[] = [];
@@ -113,6 +207,7 @@ async function scanSessions(): Promise<SessionSummary[]> {
 	const seen = new Set<string>();
 	const out: SessionSummary[] = [];
 	const BATCH = 16;
+	let changed = false;
 	for (let i = 0; i < files.length; i += BATCH) {
 		await Promise.all(files.slice(i, i + BATCH).map(async (file) => {
 			seen.add(file);
@@ -125,10 +220,17 @@ async function scanSessions(): Promise<SessionSummary[]> {
 			}
 			const summary = await summarize(file, stat);
 			summaryCache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, summary });
+			changed = true;
 			if (summary) out.push(summary);
 		}));
 	}
-	for (const key of summaryCache.keys()) if (!seen.has(key)) summaryCache.delete(key);
+	for (const key of summaryCache.keys()) {
+		if (!seen.has(key)) {
+			summaryCache.delete(key);
+			changed = true;
+		}
+	}
+	if (changed) scheduleIndexSave();
 	return out;
 }
 
@@ -140,6 +242,7 @@ export async function listSessions(query?: string): Promise<SessionSummary[]> {
 	if (listCache && Date.now() - listCache.at < 1200) {
 		list = listCache.list;
 	} else {
+		await loadIndex();
 		scanning ??= scanSessions().finally(() => { scanning = null; });
 		list = await scanning;
 		listCache = { at: Date.now(), list };

package/src/lib/skills-service.ts

@@ -133,25 +133,47 @@ export async function readSkillFile(filePath: string, cwd?: string): Promise<str
 	return fs.readFile(authorized, "utf8");
 }
 
-/** 删除技能（SKILL.md 所在目录）。包技能（node_modules 内）随包安装，删除会被还原 → 拒绝并用禁用管理。 */
+/** 技能根与用户目录本身：哪怕 SKILL.md 直接放在里面，也只能删文件，绝不能删目录 */
+function protectedDirs(context: ScopeContext): Set<string> {
+	const dirs = [
+		context.agentDir,
+		`${context.agentDir}/skills`,
+		`${context.agentDir}/web-skills`,
+		context.home,
+		`${context.home}/.pi`,
+		`${context.home}/.agents`,
+		`${context.home}/.agents/skills`,
+	];
+	if (context.cwd) dirs.push(context.cwd, `${context.cwd}/.pi`, `${context.cwd}/.pi/skills`, `${context.cwd}/.agents`, `${context.cwd}/.agents/skills`);
+	return new Set(dirs);
+}
+
+/**
+ * 删除技能。包技能（node_modules 内）随包安装，删除会被还原 → 拒绝并用禁用管理。
+ *
+ * 只有「<名字>/SKILL.md」这种技能才连目录一起删。SDK 也认技能根下直接放的平铺 `foo.md`，
+ * 它的 dirname 就是技能根本身（~/.pi/agent/skills、项目 .pi/skills…），按目录删会把整个技能根
+ * 连同其它技能一起删掉 —— 所以平铺技能、以及目录不归它独占的情况，一律只删这一个文件。
+ */
 export async function deleteSkill(filePath: string, cwd?: string): Promise<{ removed: string }> {
 	const skills = await listSkills(cwd);
 	const authorized = await resolveDiscoveredPath(filePath, skills.map((skill) => skill.filePath));
 	const context = await scopeContext(cwd);
-	if ((await classifyScope(authorized, context)) === "package") {
+	const scope = await classifyScope(authorized, context);
+	if (scope === "package") {
 		throw new Error("package-managed skill: disable it instead (it is reinstalled with the package)");
 	}
 	const skillDir = path.dirname(authorized);
-	// 只删技能目录本身，不能误删父目录（全局技能目录 ~/.pi/agent/skills、项目 .agents/skills 等）
-	const normalizedSkillDir = await toComparablePath(skillDir);
-	const knownRoots = [`${context.agentDir}/skills`, `${context.agentDir}/web-skills`];
-	if (!knownRoots.includes(normalizedSkillDir)) {
-		// 非已知根：项目内技能目录，至少确认 SKILL.md 直接位于其下且目录名非空
-		if (path.basename(skillDir) === "") throw new Error("refusing to delete workspace root");
-	}
-	await fs.rm(skillDir, { recursive: true, force: true });
+	const comparableDir = await toComparablePath(skillDir);
+	const comparableFile = await toComparablePath(authorized);
+	const others = await Promise.all(skills.map((skill) => toComparablePath(skill.filePath)));
+	const ownsDir = path.basename(authorized) === "SKILL.md"
+		&& path.dirname(skillDir) !== skillDir
+		&& !protectedDirs(context).has(comparableDir)
+		&& !others.some((other) => other !== comparableFile && within(other, comparableDir));
+	const removed = ownsDir ? skillDir : authorized;
+	await fs.rm(removed, { recursive: ownsDir, force: true });
 	await reloadAllLoaders();
-	const scope = await classifyScope(authorized, context);
 	await reloadSessionsForCwd(scope === "project" ? cwd : undefined);
-	return { removed: skillDir };
+	return { removed };
 }

package/src/lib/text-sanitize.ts

@@ -1,3 +1,15 @@
+/**
+ * 按字节截断但不切开 UTF-8 多字节字符：边界落在字符中间时，把这个不完整的字符整个丢掉，
+ * 否则 toString("utf8") 会在末尾吐出 U+FFFD（中文预览截断处出现乱码方块）。
+ */
+export function utf8Prefix(bytes: Buffer, maxBytes: number): Buffer {
+	if (bytes.length <= maxBytes) return bytes;
+	let end = maxBytes;
+	// bytes[end] 是第一个被丢掉的字节；它是续字节（10xxxxxx）说明字符从前面开始，最多回退 3 步
+	while (end > 0 && end > maxBytes - 4 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+	return bytes.subarray(0, end);
+}
+
 export interface SanitizedToolOutput {
 	text: string;
 	encodingLoss: boolean;

package/src/lib/theme.ts

@@ -4,6 +4,8 @@
  * 两者独立持久化：配色 piweb.pebrelTheme，亮暗 piweb.theme。
  */
 
+import { applyAllFonts } from './font';
+
 export type PebrelTheme =
 	| 'silver-steel'
 	| 'limestone-coal'
@@ -123,6 +125,7 @@ export function applyPebrelTheme(theme: PebrelTheme, mode?: ThemeMode): void {
 	}
 	applyLightDark(effectiveMode);
 	applyFontSize();
+	applyAllFonts();
 	try {
 		localStorage.setItem(THEME_KEY, theme);
 		localStorage.setItem(MODE_KEY, effectiveMode);

package/src/lib/types.ts

@@ -84,7 +84,8 @@ export type WebEvent =
 			type: "tool";
 			id: string;
 			name: string;
-			args: unknown;
+			/** 进度更新（running 且带 partialResult）不重发 args，接收方沿用 start 时的值 */
+			args?: unknown;
 			state: "running" | "done";
 			partialResult?: string;
 			result?: string;
@@ -146,7 +147,9 @@ export type WebEvent =
 	| { type: "retry"; attempt: number; maxAttempts: number; message: string; ts: number }
 	/** 项目生长：提交了一个 commit（pi 的一轮 / 用户两轮之间的修改 / 工作区基线） */
 	| { type: "growth"; round: GrowthRound; ts: number }
-	| { type: "growth_error"; message: string | null; ts: number };
+	| { type: "growth_error"; message: string | null; ts: number }
+	/** 项目生长要先在工作区建 git 仓库，等用户同意；request 为 null = 已回答（关掉弹窗） */
+	| { type: "growth_consent"; request: GrowthConsentRequest | null; ts: number };
 
 export interface WebStats {
 	userMessages: number;
@@ -169,6 +172,13 @@ export interface WebStats {
 export type GrowthRoundKind = "round" | "user" | "baseline";
 export type GrowthRoundStatus = "done" | "aborted" | "error";
 
+/** 工作区还不是 git 仓库根目录：not-git = 不在任何仓库里；nested = 是 parent 仓库的子目录（会嵌套建一个） */
+export interface GrowthConsentRequest {
+	cwd: string;
+	reason: "not-git" | "nested";
+	parent?: string;
+}
+
 export interface GrowthChange {
 	status: "A" | "M" | "D" | "R";
 	/** 相对工作区的路径（"/" 分隔） */
@@ -266,6 +276,8 @@ export interface WebSnapshot {
 	/** 全部持久用户消息的轮次（含上下文压缩后不再渲染的消息）。 */
 	userTurns: { id: string; ts: number }[];
 	growthError: string | null;
+	/** 等用户回答的建仓库请求；缺省按没有处理（兼容旧服务端） */
+	growthConsent?: GrowthConsentRequest | null;
 	model?: { provider: string; id: string; name: string };
 	thinkingLevel?: string;
 	thinkingLevels: string[];
@@ -274,6 +286,8 @@ export interface WebSnapshot {
 	customActiveTools?: string[] | null;
 	/** 当前待应答的扩展请求；快照是权威集合，不重放已答请求。 */
 	extensionUiRequests?: Extract<WebEvent, { type: "extension_ui" }>[];
+	/** 扩展通过 setStatus 设的页脚状态（key → 文本）；缺省按空处理（兼容旧服务端） */
+	extensionStatuses?: Record<string, string>;
 	tools: { active: string[]; all: { name: string; description?: string }[] };
 	stats: WebStats | null;
 	contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } | null;

package/src/lib/update-service.ts

@@ -91,7 +91,6 @@ async function readPackageVersion(filePath: string): Promise<string> {
 export function createUpdateService({ root = APP_ROOT, run = runCommand, versions = getRuntimeVersions, env = process.env, platform = process.platform }: UpdateServiceOptions = {}) {
 	let updateRunning = false;
 	const commandEnv = { ...env };
-	delete commandEnv.PI_WEB_PASSWORD;
 
 	async function checkedRoot(): Promise<string> {
 		return assertInstallation(root);

package/src/lib/web-auth-shared.ts

@@ -3,7 +3,11 @@
  * 登录页与 proxy / API 路由都用这些常量与纯函数。
  */
 
-export const SESSION_COOKIE = "piweb_session";
+/**
+ * Cookie 名前缀。完整名字是 前缀 + base64url(sha256(权威))，
+ * 所以换域名或换端口后旧 Cookie 自然不再匹配，不需要额外清理。
+ */
+export const COOKIE_PREFIX = "piweb_session_";
 export const SESSION_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
 
 /** 登录后跳转目标白名单：仅同源相对路径，防开放重定向 */

package/src/lib/web-auth.ts

@@ -1,36 +1,153 @@
 /**
- * 会话认证（服务端）：登录页用密码换一个无状态令牌（HMAC 派生），存 httpOnly Cookie。
- * Basic 认证保留为 API / 脚本兜底（bin/piweb.js 探活与 curl 依赖它）。
+ * 会话认证（服务端）：启动令牌换一个无状态令牌（HMAC 派生），存 httpOnly Cookie。
+ * 这是唯一的认证路径 —— 密码登录已移除，Basic 也不再被接受。
+ *
+ * 设计要点（借鉴 deepseek-harness 的 browser-auth）：
+ *   1. 签名密钥是独立随机值（web-secret.ts），与启动令牌无关 —— Cookie 泄露也无法离线爆破凭据；
+ *   2. Cookie 载荷带上权威（host:port），Cookie 名也由权威派生 —— 令牌不能跨域名/端口复用；
+ *   3. 载荷自带 issuedAt / expiresAt，服务端只验签名与时间窗，不存会话表；
+ *      登出要撤回的那一张、以及「让所有设备重新登录」的时间线，由调用方传入吊销清单（web-secret.ts）。
+ *
  * 纯常量与浏览器安全函数在 web-auth-shared（登录页引用，不能带上 node:crypto）。
  */
-import { createHmac } from "node:crypto";
-import { equalText } from "./auth";
-import { SESSION_COOKIE, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath } from "./web-auth-shared";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { COOKIE_PREFIX, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath } from "./web-auth-shared";
 
-export { SESSION_COOKIE, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath };
+export { COOKIE_PREFIX, SESSION_MAX_AGE_SECONDS, readCookieHeader, safeNextPath };
 
-/** 校验登录密码（恒定时间比较） */
-export function validPassword(candidate: string, password: string): boolean {
-	return equalText(candidate, password);
+const COOKIE_PAYLOAD_VERSION = 1;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
+
+export interface SessionCookiePayload {
+	version: typeof COOKIE_PAYLOAD_VERSION;
+	/** 签发时的 host:port；Cookie 名与签名都绑定它 */
+	authority: string;
+	issuedAt: number;
+	expiresAt: number;
+}
+
+function encodeBase64Url(value: Buffer): string {
+	return value.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** 严格解码：字符集、长度、往返一致性都要过，避免 Buffer 宽松解码吃掉非法字符 */
+function decodeBase64Url(value: string): Buffer | undefined {
+	if (!BASE64URL_PATTERN.test(value) || value.length % 4 === 1) return undefined;
+	const decoded = Buffer.from(value.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+	return encodeBase64Url(decoded) === value ? decoded : undefined;
+}
+
+/**
+ * 认证是否启用：只看 PI_WEB_AUTH（1 / true / on / yes）。不再有第二个开关。
+ * 反代后面 PiWeb 仍绑回环，绑定位址判断不出「是否暴露」，所以这种情况必须显式打开。
+ */
+export function authEnabled(env: Record<string, string | undefined> = process.env): boolean {
+	const flag = (env.PI_WEB_AUTH ?? "").trim().toLowerCase();
+	return flag === "1" || flag === "true" || flag === "on" || flag === "yes";
+}
+
+/** 请求的权威（host:port，小写）。带用户信息或解析失败一律无效。 */
+export function requestAuthority(request: Request): string | undefined {
+	const host = request.headers.get("host") || new URL(request.url).host;
+	if (!host) return undefined;
+	try {
+		const parsed = new URL(`http://${host}`);
+		if (parsed.username || parsed.password) return undefined;
+		return parsed.host.toLowerCase();
+	} catch {
+		return undefined;
+	}
+}
+
+export function cookieNameForAuthority(authority: string): string {
+	return COOKIE_PREFIX + createHash("sha256").update(authority).digest("base64url");
+}
+
+function signature(secret: Buffer, body: string): Buffer {
+	return createHmac("sha256", secret).update(body).digest();
+}
+
+export function encodeSessionCookie(payload: SessionCookiePayload, secret: Buffer): string {
+	const body = encodeBase64Url(Buffer.from(JSON.stringify(payload), "utf8"));
+	return `v1.${body}.${encodeBase64Url(signature(secret, body))}`;
+}
+
+export function decodeSessionCookie(value: string, secret: Buffer): SessionCookiePayload | undefined {
+	const parts = value.split(".");
+	if (parts.length !== 3 || parts[0] !== "v1") return undefined;
+	const body = parts[1];
+	const encoded = parts[2];
+	if (!body || !encoded) return undefined;
+	const actual = decodeBase64Url(encoded);
+	if (!actual) return undefined;
+	const expected = signature(secret, body);
+	if (actual.byteLength !== expected.byteLength || !timingSafeEqual(actual, expected)) return undefined;
+	const bodyBytes = decodeBase64Url(body);
+	if (!bodyBytes) return undefined;
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(bodyBytes.toString("utf8"));
+	} catch {
+		return undefined;
+	}
+	if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) return undefined;
+	const payload = decoded as Partial<SessionCookiePayload>;
+	if (payload.version !== COOKIE_PAYLOAD_VERSION) return undefined;
+	if (typeof payload.authority !== "string") return undefined;
+	if (!Number.isSafeInteger(payload.issuedAt) || !Number.isSafeInteger(payload.expiresAt)) return undefined;
+	return payload as SessionCookiePayload;
+}
+
+/** 为一个权威签一张新 Cookie（名字、值、有效期一起给） */
+export function createSessionCookie(authority: string, secret: Buffer, now = Date.now()) {
+	const expiresAt = now + SESSION_MAX_AGE_SECONDS * 1000;
+	const payload: SessionCookiePayload = { version: COOKIE_PAYLOAD_VERSION, authority, issuedAt: now, expiresAt };
+	return {
+		name: cookieNameForAuthority(authority),
+		value: encodeSessionCookie(payload, secret),
+		expiresAt,
+		maxAgeSeconds: SESSION_MAX_AGE_SECONDS,
+	};
+}
+
+/** 吊销清单（由 web-secret 从磁盘读出）：notBefore 之前签发的全部作废；revoked 里是单张 Cookie 的指纹 */
+export interface SessionRevocationList {
+	notBefore: number;
+	revoked: ReadonlyMap<string, number>;
+}
+
+/** 单张 Cookie 的指纹：吊销清单里只存它，不存 Cookie 本身 */
+export function sessionCookieId(raw: string): string {
+	return createHash("sha256").update(raw).digest("base64url");
 }
 
-/** 令牌 = 过期时间戳 + 以密码为密钥的 HMAC。密码变更即全部令牌失效。 */
-export function createSessionToken(password: string, now = Date.now()): string {
-	const expires = now + SESSION_MAX_AGE_SECONDS * 1000;
-	return `${expires}.${sign(password, String(expires))}`;
+/** 请求自带的、签名与权威都对的会话 Cookie（不看时间窗与吊销）；登出时用它算出要撤的那一张 */
+export function sessionCookieFromRequest(request: Request, secret: Buffer): { id: string; payload: SessionCookiePayload } | undefined {
+	const authority = requestAuthority(request);
+	if (!authority) return undefined;
+	const raw = readCookieHeader(request.headers.get("cookie"), cookieNameForAuthority(authority));
+	if (!raw) return undefined;
+	const payload = decodeSessionCookie(raw, secret);
+	if (!payload || payload.authority !== authority) return undefined;
+	return { id: sessionCookieId(raw), payload };
 }
 
-export function validSessionToken(token: string | undefined | null, password: string, now = Date.now()): boolean {
-	if (!token) return false;
-	const separator = token.indexOf(".");
-	if (separator <= 0) return false;
-	const expires = Number(token.slice(0, separator));
-	if (!Number.isSafeInteger(expires) || expires <= now) return false;
-	return equalText(token.slice(separator + 1), sign(password, String(expires)));
+/** 校验请求自带的会话 Cookie：签名、权威、时间窗都要对，且没被吊销 */
+export function validSessionCookie(request: Request, secret: Buffer, now = Date.now(), revocations?: SessionRevocationList): boolean {
+	const cookie = sessionCookieFromRequest(request, secret);
+	if (!cookie) return false;
+	const { payload } = cookie;
+	if (revocations && (payload.issuedAt < revocations.notBefore || revocations.revoked.has(cookie.id))) return false;
+	return payload.issuedAt <= now
+		&& payload.expiresAt > now
+		&& payload.expiresAt > payload.issuedAt
+		&& payload.expiresAt - payload.issuedAt <= SESSION_MAX_AGE_SECONDS * 1000;
 }
 
-function sign(password: string, payload: string): string {
-	return createHmac("sha256", `piweb-session:${password}`).update(payload).digest("base64url");
+/** 清 Cookie 时要用同一个名字，否则删不掉 */
+export function clearSessionCookie(request: Request) {
+	const authority = requestAuthority(request);
+	return { name: authority ? cookieNameForAuthority(authority) : COOKIE_PREFIX, value: "" };
 }
 
 export function isSecureRequest(request: Request): boolean {

package/src/lib/web-launch-token.ts

@@ -0,0 +1,55 @@
+/**
+ * 启动令牌（借鉴 deepseek-harness 的 launch token）。
+ *
+ * 每个进程启动时生成一次 32 字节随机值，由启动器打印成 `?token=…` 链接。
+ * 浏览器用它换一张签名 Cookie，之后不再需要令牌。
+ * 令牌不接受出现在 API 路径上，也不接受走 Authorization 头 —— 只有根路径的
+ * GET 能消费它，这样令牌不会因为某个 API 客户端的日志而泄漏。
+ */
+import { timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { agentDir } from "./web-secret";
+
+export const TOKEN_QUERY = "token";
+export const TOKEN_BYTES = 32;
+
+/** 恒定时间比较；两边任一为空（没配令牌）时一律无效 */
+export function validLaunchToken(candidate: string | undefined, expected: string | undefined): boolean {
+	if (!candidate || !expected) return false;
+	const actual = Buffer.from(candidate, "utf8");
+	const wanted = Buffer.from(expected, "utf8");
+	return actual.byteLength === wanted.byteLength && timingSafeEqual(actual, wanted);
+}
+
+/**
+ * 正在运行的实例把自己的启动令牌留在 `<agentDir>/web-launch/<端口>.token`。
+ *
+ * 用途只有一个：再次运行启动器、发现这个端口上已有 PiWeb 时，能直接打开带令牌的登录链接，
+ * 而不是把用户扔到一个他手里没有凭据的登录页。文件和 web-secret 放在同一个目录、同样 0600：
+ * 读得到它的人本来就读得到签名密钥，不额外扩大暴露面。路径规则与 scripts/launcher.mjs 一致。
+ */
+export function launchTokenFile(port: number | string): string {
+	return path.join(agentDir(), "web-launch", `${port}.token`);
+}
+
+/** 服务启动时调用：写下本进程的令牌，退出时摘掉（只摘自己写的那份） */
+export function publishLaunchToken(env: Record<string, string | undefined> = process.env): void {
+	const token = env.PI_WEB_LAUNCH_TOKEN;
+	const port = env.PIWEB_PORT;
+	if (!token || !port) return;
+	const file = launchTokenFile(port);
+	try {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, `${token}\n`, { mode: 0o600 });
+	} catch {
+		return; // 只是便利功能：写不进去就退回旧行为（打开裸地址）
+	}
+	process.once("exit", () => {
+		try {
+			if (fs.readFileSync(file, "utf8").trim() === token) fs.unlinkSync(file);
+		} catch {
+			/* 已经不在了 */
+		}
+	});
+}