@rexvane/piweb 0.3.17 → 0.3.19

package/src/lib/auth-throttle.ts

@@ -0,0 +1,102 @@
+/**
+ * 登录失败的全局指数退避。
+ *
+ * 目前无调用方：密码登录已移除，留作将来需要人机凭据时的现成实现。
+ *
+ * PiWeb 只服务一个操作者，且默认绑 127.0.0.1：路由处理器拿不到可靠的客户端地址
+ * （x-forwarded-for 可伪造，直连时根本没有）。与其信任一个按 IP 的键，不如让所有失败
+ * 共用一个计数器，短暂挡住全部密码尝试。被误伤的「另一个用户」只有操作者本人，
+ * 有界等待可以接受，而爆破被压到大约每分钟一次。
+ *
+ * 状态挂在 globalThis 上，这样 Next 的热重载不会把计数器重置掉。
+ */
+
+export const AUTH_THROTTLE_BASE_DELAY_MS = 1_000;
+export const AUTH_THROTTLE_MAX_DELAY_MS = 60_000;
+
+/**
+ * 最后一次失败之后多久忘掉计数器。必须大于最大退避，否则「等过一次封禁」就
+ * 等于把退避重置回基础值，反而给攻击者一轮新的尝试额度。
+ */
+export const AUTH_THROTTLE_RESET_AFTER_MS = 5 * 60_000;
+
+export interface AuthThrottleState {
+	failures: number;
+	lastFailureAt: number;
+	blockedUntil: number;
+}
+
+const STATE_KEY = "piweb:auth-throttle";
+
+function freshState(): AuthThrottleState {
+	return { failures: 0, lastFailureAt: 0, blockedUntil: 0 };
+}
+
+export function createAuthThrottleState(): AuthThrottleState {
+	return freshState();
+}
+
+function isState(value: unknown): value is AuthThrottleState {
+	return typeof value === "object"
+		&& value !== null
+		&& typeof (value as AuthThrottleState).failures === "number"
+		&& typeof (value as AuthThrottleState).lastFailureAt === "number"
+		&& typeof (value as AuthThrottleState).blockedUntil === "number";
+}
+
+function getGlobalState(): AuthThrottleState {
+	const store = globalThis as Record<PropertyKey, unknown>;
+	const key = Symbol.for(STATE_KEY);
+	const existing = store[key];
+	if (isState(existing)) return existing;
+	const created = freshState();
+	store[key] = created;
+	return created;
+}
+
+function expireIfStale(state: AuthThrottleState, now: number): void {
+	if (state.failures > 0 && now - state.lastFailureAt >= AUTH_THROTTLE_RESET_AFTER_MS) {
+		Object.assign(state, freshState());
+	}
+}
+
+export function backoffDelayMs(failures: number): number {
+	if (failures <= 0) return 0;
+	const exponent = Math.min(failures - 1, 31);
+	return Math.min(AUTH_THROTTLE_BASE_DELAY_MS * 2 ** exponent, AUTH_THROTTLE_MAX_DELAY_MS);
+}
+
+/** 还要等多少毫秒才允许下一次尝试；0 表示可以试 */
+export function getAuthRetryAfterMs(now = Date.now(), state: AuthThrottleState = getGlobalState()): number {
+	expireIfStale(state, now);
+	return Math.max(0, state.blockedUntil - now);
+}
+
+/** 记一次失败，返回下一次尝试被强制的等待时间 */
+export function recordAuthFailure(now = Date.now(), state: AuthThrottleState = getGlobalState()): number {
+	expireIfStale(state, now);
+	state.failures += 1;
+	state.lastFailureAt = now;
+	const delay = backoffDelayMs(state.failures);
+	state.blockedUntil = now + delay;
+	return delay;
+}
+
+/**
+ * 登录成功即清零（与上游 pi-web 的 recordAuthSuccess 一致）。
+ * 攻击者不知道密码就不可能触发这条路径，所以清零不会削弱防护，
+ * 而操作者输对一次之后不必继续背着之前的退避。
+ */
+export function recordAuthSuccess(state: AuthThrottleState = getGlobalState()): void {
+	Object.assign(state, freshState());
+}
+
+/** 仅供测试：清掉挂在 globalThis 上的计数器 */
+export function resetAuthThrottle(): void {
+	Object.assign(getGlobalState(), freshState());
+}
+
+/** Retry-After 头的整秒值；被封禁时至少 1 */
+export function retryAfterSeconds(retryAfterMs: number): number {
+	return Math.max(1, Math.ceil(retryAfterMs / 1000));
+}

package/src/lib/auth.ts

@@ -1,28 +1,11 @@
-const BASIC_PREFIX = "Basic ";
-
-/** 恒定时间字符串比较（长度不同也走完全程，不早退） */
-export function equalText(left: string, right: string): boolean {
-	const max = Math.max(left.length, right.length);
-	let mismatch = left.length ^ right.length;
-	for (let i = 0; i < max; i += 1) {
-		mismatch |= (left.charCodeAt(i) || 0) ^ (right.charCodeAt(i) || 0);
-	}
-	return mismatch === 0;
-}
-
-export function validBasicAuthorization(header: string | null, password: string): boolean {
-	if (!header?.startsWith(BASIC_PREFIX)) return false;
-	try {
-		const decoded = Buffer.from(header.slice(BASIC_PREFIX.length), "base64").toString("utf8");
-		const separator = decoded.indexOf(":");
-		if (separator < 0) return false;
-		return equalText(decoded.slice(0, separator), "pi") && equalText(decoded.slice(separator + 1), password);
-	} catch {
-		return false;
-	}
-}
+import { isIP } from "node:net";
 
+/**
+ * 同源校验。跨站一律拒绝（Sec-Fetch-Site 由浏览器给出，脚本改不了），
+ * 没有 Origin 的请求（curl、服务端调用）放行。
+ */
 export function isSafeOrigin(request: Request): boolean {
+	if (request.headers.get("sec-fetch-site") === "cross-site") return false;
 	const origin = request.headers.get("origin");
 	if (!origin) return true;
 	try {
@@ -34,12 +17,36 @@ export function isSafeOrigin(request: Request): boolean {
 	}
 }
 
-export function isSafeHost(request: Request, passwordConfigured: boolean): boolean {
-	if (passwordConfigured) return true;
+export function trustedHostnames(raw: string | undefined): string[] {
+	return (raw ?? "").split(",").map((value) => value.trim().toLowerCase()).filter(Boolean);
+}
+
+/**
+ * 白名单环境变量。PI_WEB_TRUSTED_HOSTS 是本项目的名字，PI_WEB_ALLOWED_HOSTS 是上游
+ * agegr/pi-web 的名字，两个都收，免得用户按上游文档配置却不生效。
+ */
+export function configuredTrustedHosts(env: Record<string, string | undefined> = process.env): string[] {
+	return [...trustedHostnames(env.PI_WEB_TRUSTED_HOSTS), ...trustedHostnames(env.PI_WEB_ALLOWED_HOSTS)];
+}
+
+/**
+ * Host 校验：无论有没有开认证都要做。
+ *
+ * 只信任本机名（含 *.localhost）、IP 字面量、以及操作者显式列出的主机名。
+ * IP 字面量保留局域网直连能力，且不可能被 DNS rebinding 利用 —— 浏览器会把字面
+ * 地址原样写进 Host，攻击者域名对不上。反代转发的域名必须进白名单：
+ * DNS rebinding 靠的是攻击者域名解析到回环后仍带自己的 Host，它不可能等于白名单里的名字。
+ */
+export function isSafeHost(request: Request, trustedHosts: readonly string[] = []): boolean {
 	try {
 		const host = request.headers.get("host") || new URL(request.url).host;
 		const parsed = new URL(`http://${host}`);
-		return !parsed.username && !parsed.password && parsed.host.toLowerCase() === host.toLowerCase() && isLoopbackHostname(parsed.hostname);
+		if (parsed.username || parsed.password || parsed.host.toLowerCase() !== host.toLowerCase()) return false;
+		const hostname = parsed.hostname.toLowerCase();
+		if (isLoopbackHostname(hostname)) return true;
+		// URL 给 IPv6 字面量带着方括号（[fe80::1]），isIP 只认去掉括号的写法
+		if (isIP(hostname.replace(/^\[(.*)\]$/, "$1")) !== 0) return true;
+		return trustedHosts.includes(hostname);
 	} catch {
 		return false;
 	}
@@ -47,5 +54,6 @@ export function isSafeHost(request: Request, passwordConfigured: boolean): boole
 
 export function isLoopbackHostname(hostname: string): boolean {
 	const host = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
-	return host === "localhost" || host === "::1" || host === "0:0:0:0:0:0:0:1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	return host === "::1" || host === "0:0:0:0:0:0:0:1" || /^127(?:\.\d{1,3}){3}$/.test(host);
 }

package/src/lib/files-service.ts

@@ -7,6 +7,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { BoundaryError, isPathInside, resolveWorkspacePath } from "./path-security";
 import { getAgentDir } from "./pi";
+import { utf8Prefix } from "./text-sanitize";
 
 export interface FileEntry {
 	name: string;
@@ -122,7 +123,7 @@ export async function readWorkspaceFile(cwdValue: unknown, relPath: unknown): Pr
 	} finally {
 		await handle.close();
 	}
-	const preview = buffer.subarray(0, Math.min(bytesRead, MAX_READ_BYTES));
+	const preview = utf8Prefix(buffer.subarray(0, bytesRead), MAX_READ_BYTES);
 	// 只检查预览范围，绝不为识别二进制而加载整个大文件
 	if (preview.includes(0)) {
 		return { path: toRel(root, real), binary: true, truncated: false, content: "" };
@@ -185,9 +186,67 @@ export async function saveUpload(name: unknown, dataBase64: unknown): Promise<{
 		throw error;
 	}
 	await handle.close();
+	scheduleUploadSweep();
 	return { path: target, name: safeName, size: buffer.length };
 }
 
+/** 上传超过这么多天、且没有任何会话记录提到它，才会被清理 */
+export const UPLOAD_RETENTION_DAYS = 30;
+const UPLOAD_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+let lastUploadSweep = 0;
+
+/** 上传成功后顺带在后台清理，每个进程每天最多一次 */
+function scheduleUploadSweep(): void {
+	const now = Date.now();
+	if (now - lastUploadSweep < UPLOAD_SWEEP_INTERVAL_MS) return;
+	lastUploadSweep = now;
+	void sweepUploads(now).catch(() => undefined);
+}
+
+/**
+ * 清理 web-uploads：消息里引用的是上传文件的绝对路径，所以只要还有会话 JSONL 提到文件名就保留
+ * （会话被删、或归档过期删除后，它的附件才变成孤儿）；没发出去的草稿留 30 天的余量。
+ * 会话目录读不全就整次放弃，宁可不删也不误删。返回删掉的文件名。
+ */
+export async function sweepUploads(now = Date.now(), retentionDays = UPLOAD_RETENTION_DAYS): Promise<string[]> {
+	const agentDir = getAgentDir();
+	const dir = path.join(agentDir, "web-uploads");
+	const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+	const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+	// 文件名 → 在 JSONL 里可能出现的写法（原样 / JSON 转义后）
+	const candidates = new Map<string, string[]>();
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const stat = await fs.stat(path.join(dir, entry.name)).catch(() => null);
+		if (!stat || stat.mtimeMs > cutoff) continue;
+		candidates.set(entry.name, [entry.name, JSON.stringify(entry.name).slice(1, -1)]);
+	}
+	if (!candidates.size) return [];
+	const sessionsRoot = path.join(agentDir, "sessions");
+	let sessionFiles: string[];
+	try {
+		sessionFiles = (await fs.readdir(sessionsRoot, { recursive: true })).filter((name) => name.endsWith(".jsonl"));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") return [];
+		sessionFiles = [];
+	}
+	for (const name of sessionFiles) {
+		let text: string;
+		try {
+			text = await fs.readFile(path.join(sessionsRoot, name), "utf8");
+		} catch {
+			return [];
+		}
+		for (const [file, needles] of candidates) if (needles.some((needle) => text.includes(needle))) candidates.delete(file);
+		if (!candidates.size) return [];
+	}
+	const removed: string[] = [];
+	for (const file of candidates.keys()) {
+		await fs.unlink(path.join(dir, file)).then(() => removed.push(file), () => undefined);
+	}
+	return removed;
+}
+
 export function parseUploadLength(value: string | null): number {
 	if (value === null || !/^\d+$/.test(value)) throw new BoundaryError("missing or invalid upload size");
 	const size = Number(value);
@@ -220,6 +279,7 @@ export async function saveUploadStream(name: unknown, stream: ReadableStream<Uin
 		if (size === 0) throw new BoundaryError("empty upload");
 		if (expectedSize !== undefined && size !== expectedSize) throw new BoundaryError("incomplete upload: size does not match the declared length");
 		complete = true;
+		scheduleUploadSweep();
 		return { path: target, name: safeName, size };
 	} finally {
 		await reader.cancel().catch(() => undefined);

package/src/lib/font.ts

@@ -0,0 +1,84 @@
+/**
+ * 字体族偏好：界面字体与代码字体各自独立选择。
+ * 与字号（piweb.fontSize / piweb.chatFontSize，见 theme.ts applyFontSize）分开，
+ * 存 localStorage：piweb.fontUi / piweb.fontMono，
+ * 通过覆盖 CSS 变量 --font-ui / --font-mono 生效（变量默认值见 globals.css）。
+ *
+ * 值有两种写法：
+ *   - 预设 id（如 "maple" / "system" / "jetbrains"）
+ *   - 自定义字体栈，前缀 "custom:"（如 "custom:Fira Code, monospace"）
+ */
+
+export type FontScope = "ui" | "mono";
+
+export const DEFAULT_FONT_STACK: Record<FontScope, string> = {
+	ui: '"Maple Mono CN", ui-monospace, SFMono-Regular, Menlo, Consolas, "PingFang SC", "Microsoft YaHei", monospace',
+	mono: '"Maple Mono CN", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+};
+
+export interface FontPreset {
+	id: string;
+	stack: string;
+	label: { zh: string; en: string };
+}
+
+export const FONT_PRESETS: Record<FontScope, FontPreset[]> = {
+	ui: [
+		{ id: "maple", stack: DEFAULT_FONT_STACK.ui, label: { zh: "Maple Mono CN（默认）", en: "Maple Mono CN (default)" } },
+		{ id: "system", stack: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif', label: { zh: "系统默认", en: "System default" } },
+		{ id: "noto", stack: '"Noto Sans SC", ui-sans-serif, system-ui, "PingFang SC", "Microsoft YaHei", sans-serif', label: { zh: "思源黑体", en: "Noto Sans SC" } },
+	],
+	mono: [
+		{ id: "maple", stack: DEFAULT_FONT_STACK.mono, label: { zh: "Maple Mono CN（默认）", en: "Maple Mono CN (default)" } },
+		{ id: "system", stack: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace", label: { zh: "系统等宽", en: "System monospace" } },
+		{ id: "jetbrains", stack: '"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace', label: { zh: "JetBrains Mono", en: "JetBrains Mono" } },
+		{ id: "fira", stack: '"Fira Code", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace', label: { zh: "Fira Code", en: "Fira Code" } },
+	],
+};
+
+export const CUSTOM_PREFIX = "custom:";
+const KEY: Record<FontScope, string> = { ui: "piweb.fontUi", mono: "piweb.fontMono" };
+const CSS_VAR: Record<FontScope, string> = { ui: "--font-ui", mono: "--font-mono" };
+
+/** localStorage 里的原始偏好（预设 id 或 custom: 前缀的字体栈） */
+export function loadFontChoice(scope: FontScope): string | null {
+	if (typeof window === "undefined") return null;
+	try {
+		return localStorage.getItem(KEY[scope]);
+	} catch {
+		return null;
+	}
+}
+
+/** 把偏好解析成可直接写进 CSS 变量的字体栈；无法识别时回落默认 */
+export function resolveFontStack(scope: FontScope, stored: string | null): string {
+	if (!stored) return DEFAULT_FONT_STACK[scope];
+	if (stored.startsWith(CUSTOM_PREFIX)) {
+		const custom = stored.slice(CUSTOM_PREFIX.length).trim();
+		return custom || DEFAULT_FONT_STACK[scope];
+	}
+	return FONT_PRESETS[scope].find((p) => p.id === stored)?.stack ?? DEFAULT_FONT_STACK[scope];
+}
+
+/** 应用并持久化；value 传 null 表示恢复默认（移除内联覆盖 + 清 localStorage） */
+export function applyFontChoice(scope: FontScope, value: string | null): void {
+	if (typeof window === "undefined") return;
+	const root = document.documentElement;
+	try {
+		if (!value) {
+			root.style.removeProperty(CSS_VAR[scope]);
+			localStorage.removeItem(KEY[scope]);
+			return;
+		}
+		root.style.setProperty(CSS_VAR[scope], resolveFontStack(scope, value));
+		localStorage.setItem(KEY[scope], value);
+	} catch {
+		/* ignore */
+	}
+}
+
+/** 启动 / 系统主题变化 / 跨标签同步时重放两处字体偏好 */
+export function applyAllFonts(): void {
+	applyFontChoice("ui", loadFontChoice("ui"));
+	applyFontChoice("mono", loadFontChoice("mono"));
+}

package/src/lib/git-service.ts

@@ -7,6 +7,7 @@ import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
+import { resolveGitBin } from "./growth-service";
 import { BoundaryError, isPathInside, resolveWorkspacePath } from "./path-security";
 
 const exec = promisify(execFile);
@@ -61,8 +62,9 @@ const EMPTY: GitInfo = {
 /** 单次差异输出上限：超过则截断并标记（详情栏不是完整的 diff 工具） */
 const MAX_DIFF_BYTES = 400 * 1024;
 
-function runGit(cwd: string, args: string[], maxBuffer = 4 * 1024 * 1024): Promise<string> {
-	return exec("git", args, { cwd, timeout: 15_000, maxBuffer, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }).then((r) => r.stdout);
+/** 与生长记录共用解析出的 git（macOS 从 GUI / launchd 启动时 PATH 里常常没有 Homebrew 的 git） */
+async function runGit(cwd: string, args: string[], maxBuffer = 4 * 1024 * 1024): Promise<string> {
+	return exec(await resolveGitBin(), args, { cwd, timeout: 15_000, maxBuffer, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }).then((r) => r.stdout);
 }
 
 function kindOf(x: string, y: string): GitFileEntry["kind"] {
@@ -164,7 +166,7 @@ export async function gitInfo(cwdValue: unknown): Promise<GitInfo> {
 			.split("\n")
 			.filter(Boolean)
 			.map((line) => {
-				const [hash, subject, author, relative] = line.split("");
+				const [hash, subject, author, relative] = line.split("\x1f");
 				return { hash, subject: subject ?? "", author: author ?? "", relative: relative ?? "" };
 			});
 	} catch {

package/src/lib/growth-service.ts

@@ -1,8 +1,9 @@
 /**
  * growth-service：项目生长 = 每轮一个 git commit（工作区自带 git，无影子仓库、无旁路账本）。
  *
- * commit 直接落在工作区自己的 git 仓库里：非 git 目录在首次提交前自动 `git init`；
- * 工作区若只是别的仓库的子目录，则在自身根目录嵌套 init，保证记录范围恰好等于工作区。
+ * commit 直接落在工作区自己的 git 仓库里：工作区已是仓库根目录就直接用；
+ * 非 git 目录、或只是别的仓库的子目录，要用户同意后（allowInit）才在工作区根 `git init`
+ * （子目录则嵌套 init），保证记录范围恰好等于工作区；没同意就抛 needs-consent。
  * 每轮结束 = 往 PiWeb 独立暂存区 <gitdir>/piweb/index（GIT_INDEX_FILE 传入）add 全部改动，
  * write-tree + commit-tree，挂到专用引用 refs/piweb/rounds/<key>：不碰 HEAD、不碰用户暂存区、不占分支。
  * 排除规则 <gitdir>/piweb/exclude 只叠加、绝不改写用户的 info/exclude。
@@ -19,6 +20,7 @@ import { existsSync, realpathSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { GROWTH_EXCLUDE_DIRS } from "./growth-tree";
+import { utf8Prefix } from "./text-sanitize";
 import type { GrowthChange, GrowthRound, GrowthRoundKind, GrowthRoundStatus } from "./types";
 
 /** 单文件快照上限：超过的不进快照（树里也就看不到它） */
@@ -42,10 +44,17 @@ export const EXCLUDE_DIRS = GROWTH_EXCLUDE_DIRS;
 const EXCLUDE_FILES = [".DS_Store", "Thumbs.db", "*.log", ".env", ".env.*", "!.env.example", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_ed25519*"];
 const EXCLUDE_CONTENT = `# PiWeb growth snapshot exclusions (generated, do not edit)\n${[...EXCLUDE_DIRS.map((d) => `${d}/`), ...EXCLUDE_FILES].join("\n")}\n`;
 
+/** 工作区还不是仓库根目录：not-git = 不在任何仓库里；nested = 是 parent 仓库的子目录 */
+export interface GrowthInitTarget {
+	reason: "not-git" | "nested";
+	parent?: string;
+}
+
 export class GrowthError extends Error {
 	constructor(
 		message: string,
-		public code: "unavailable" | "too-large" | "not-found" | "failed" = "failed",
+		public code: "unavailable" | "too-large" | "not-found" | "failed" | "needs-consent" = "failed",
+		public target?: GrowthInitTarget,
 	) {
 		super(message);
 		this.name = "GrowthError";
@@ -120,9 +129,9 @@ type Env = Record<string, string | undefined>;
 /**
  * 解析 git 可执行文件：macOS GUI/launchd 启动的进程 PATH 常不含 Homebrew，
  * spawn("git") 会 ENOENT → 生长快照整体误判不可用。PATH 找不到时退回常见安装位置。
- * 只在非 Windows 生效；结果缓存到 registry（成功后不再变）。
+ * 只在非 Windows 生效；结果缓存到 registry（成功后不再变）。git-service 也用它。
  */
-async function resolveGitBin(): Promise<string> {
+export async function resolveGitBin(): Promise<string> {
 	if (registry.gitBin) return registry.gitBin;
 	let bin = "git";
 	if (process.platform !== "win32") {
@@ -207,10 +216,14 @@ async function gitOk(): Promise<boolean> {
 	if (registry.gitFailedAt && Date.now() - registry.gitFailedAt < GIT_FAIL_RETRY_MS) return false;
 	const check = runGit(["--version"]).then((r) => r.code === 0, () => false);
 	registry.gitOk = check;
+	// 成功结果一直留着（项目栏每次打开都会问一次，不必每次起一个 git 进程）；失败只短缓存
 	void check.then((ok) => {
+		if (ok) {
+			registry.gitFailedAt = undefined;
+			return;
+		}
 		registry.gitOk = undefined;
-		if (ok) registry.gitFailedAt = undefined;
-		else registry.gitFailedAt = Date.now();
+		registry.gitFailedAt = Date.now();
 	});
 	return check;
 }
@@ -285,26 +298,28 @@ async function refExistsFast(gitDir: string, ref: string): Promise<boolean> {
 
 /**
  * 解析工作区可用的 git-dir：工作区已是某仓库的工作树根就直接复用；
- * 否则（非 git 目录、或只是别的仓库的子目录）在工作区根 `git init`。
+ * 否则（非 git 目录、或只是别的仓库的子目录）只有 allowInit（用户同意过）才在工作区根 `git init`，
+ * 不然抛 needs-consent 并带上原因，由界面去问。
  * init 失败（目录不可写等）按终态处理，本会话停用生长跟踪。
  */
-async function ensureGitDir(cwd: string): Promise<string> {
-	const usable = async (): Promise<string | null> => {
+async function ensureGitDir(cwd: string, allowInit: boolean): Promise<string> {
+	const probe = async (): Promise<{ gitDir: string } | GrowthInitTarget> => {
 		const r = await runGit(["rev-parse", "--absolute-git-dir", "--show-toplevel", "--is-bare-repository"], { cwd });
-		if (r.code !== 0) return null;
+		if (r.code !== 0) return { reason: "not-git" };
 		const [gitDir = "", top = "", bare = ""] = r.stdout.toString("utf8").split("\n").map((s) => s.trim());
-		if (!gitDir || bare === "true" || !top) return null;
+		if (!gitDir || bare === "true" || !top) return { reason: "not-git" };
 		// 快照范围必须恰好等于工作区：落在别的仓库的子目录里时，宁可嵌套 init 自己的仓库
-		if (comparablePath(realpathSafe(top)) !== comparablePath(realpathSafe(cwd))) return null;
-		return gitDir;
+		if (comparablePath(realpathSafe(top)) !== comparablePath(realpathSafe(cwd))) return { reason: "nested", parent: path.resolve(top) };
+		return { gitDir };
 	};
-	const existing = await usable();
-	if (existing) return existing;
+	const existing = await probe();
+	if ("gitDir" in existing) return existing.gitDir;
+	if (!allowInit) throw new GrowthError("growth tracking needs consent to create a git repository here", "needs-consent", existing);
 	const r = await runGit(["init", "-q"], { cwd });
 	if (r.code !== 0) throw new GrowthError(`git init failed: ${r.stderr.trim().split("\n")[0] || `exit ${r.code}`}`, "unavailable");
-	const created = await usable();
-	if (!created) throw new GrowthError("workspace cannot be used as a git repository", "unavailable");
-	return created;
+	const created = await probe();
+	if (!("gitDir" in created)) throw new GrowthError("workspace cannot be used as a git repository", "unavailable");
+	return created.gitDir;
 }
 
 /** 链头的 commit 与 tree；引用不存在返回 null（for-each-ref 对不存在的引用输出空、退出码 0） */
@@ -314,10 +329,10 @@ async function readHead(ws: WorkspaceState): Promise<{ commit: string; tree: str
 	return HASH_RE.test(commit) && HASH_RE.test(tree) ? { commit, tree } : null;
 }
 
-async function createWorkspace(cwd: string): Promise<WorkspaceState> {
+async function createWorkspace(cwd: string, allowInit: boolean): Promise<WorkspaceState> {
 	if (!(await gitOk())) throw new GrowthError("git is not installed", "unavailable");
 	const key = workspaceKey(cwd);
-	const gitDir = await ensureGitDir(cwd);
+	const gitDir = await ensureGitDir(cwd, allowInit);
 	const piwebDir = path.join(gitDir, "piweb");
 	await fs.mkdir(piwebDir, { recursive: true });
 	const ws: WorkspaceState = {
@@ -340,7 +355,8 @@ async function createWorkspace(cwd: string): Promise<WorkspaceState> {
 	return ws;
 }
 
-async function getWorkspace(cwdValue: string): Promise<WorkspaceState> {
+/** allowInit：工作区还不是仓库根目录时是否允许 `git init`（只有提交路径、且用户同意过才传 true；读取一律不建仓库） */
+async function getWorkspace(cwdValue: string, allowInit = false): Promise<WorkspaceState> {
 	const cwd = await fs.realpath(path.resolve(cwdValue)).catch(() => path.resolve(cwdValue));
 	const key = workspaceKey(cwd);
 	let pending = registry.workspaces.get(key);
@@ -355,7 +371,7 @@ async function getWorkspace(cwdValue: string): Promise<WorkspaceState> {
 		}
 	}
 	if (!pending) {
-		pending = createWorkspace(cwd);
+		pending = createWorkspace(cwd, allowInit);
 		registry.workspaces.set(key, pending);
 		pending.catch(() => registry.workspaces.delete(key));
 	}
@@ -663,14 +679,39 @@ export interface RoundMeta {
 	status?: GrowthRoundStatus;
 }
 
+export interface CommitOptions {
+	/** 工作区还不是仓库根目录时允许 `git init`（用户同意过） */
+	allowInit?: boolean;
+	/** 拍完快照、提交之前再问一次：返回 true 就放弃这次提交（返回 null） */
+	abortIf?: () => boolean;
+}
+
+/** 每个工作区每提交这么多次跑一次 `git gc --auto`（与 git commit 自己的做法一样，没到阈值时什么也不做） */
+const GC_EVERY_COMMITS = 50;
+const commitsSinceGc = new Map<string, number>();
+
+/** 不等、不设超时（大仓库打包可能要很久，中途杀掉白干）；也不占工作区锁，并发由 git 自己的锁处理 */
+async function gcInBackground(ws: WorkspaceState): Promise<void> {
+	const gitBin = await resolveGitBin();
+	const child = spawn(gitBin, ["--git-dir", ws.gitDir, "gc", "--auto", "--quiet"], {
+		cwd: ws.cwd,
+		env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+		stdio: "ignore",
+		windowsHide: true,
+	});
+	child.on("error", () => undefined);
+	child.unref();
+}
+
 /**
  * 提交一个 commit 到 refs/piweb/rounds/<key>（做法等同 git add -A + git commit，但只用 PiWeb 独立暂存区）。
  * pi 的一轮无论有没有改动都提交（空 commit 也算一轮，轮号与对话一一对应）；
  * 用户修改 / 基线只在工作区相对上一个 commit 有变化时提交，否则返回 null。
  */
-export async function commitRound(cwdValue: string, meta: RoundMeta): Promise<GrowthRound | null> {
-	const ws = await getWorkspace(cwdValue);
+export async function commitRound(cwdValue: string, meta: RoundMeta, options: CommitOptions = {}): Promise<GrowthRound | null> {
+	const ws = await getWorkspace(cwdValue, options.allowInit === true);
 	return withLock(ws, async () => {
+		if (options.abortIf?.()) return null;
 		if (ws.excludeRules !== EXCLUDE_CONTENT) {
 			await fs.writeFile(ws.excludeFile, EXCLUDE_CONTENT, "utf8");
 			ws.excludeRules = EXCLUDE_CONTENT;
@@ -678,6 +719,8 @@ export async function commitRound(cwdValue: string, meta: RoundMeta): Promise<Gr
 		await refreshIndex(ws);
 		const tree = (await shadow(ws, ["write-tree"])).stdout.toString("utf8").trim();
 		assertHash(tree, "tree");
+		// 快照拍到一半时 pi 已经开始改文件：分不清谁改的，宁可不记（改动并入 pi 这一轮）
+		if (options.abortIf?.()) return null;
 		const env = {
 			GIT_AUTHOR_NAME: "PiWeb", GIT_AUTHOR_EMAIL: "piweb@localhost",
 			GIT_COMMITTER_NAME: "PiWeb", GIT_COMMITTER_EMAIL: "piweb@localhost",
@@ -721,15 +764,20 @@ export async function commitRound(cwdValue: string, meta: RoundMeta): Promise<Gr
 			}
 			ws.lastCommit = commit;
 			ws.lastTree = tree;
-			// 不在用户仓库里主动 gc：对象由专用引用保活，仓库维护交还用户
+			// commit-tree 是底层命令，不会像 git commit 那样顺手 gc --auto：快照对象一直是松散文件、只增不减。
+			// 隔一段补一次，没到阈值 git 什么都不做。不带 PiWeb 暂存区：用户自己 index 里的对象照常算可达；
+			// PiWeb 暂存区此刻刚整体提交，里面的对象都已挂在专用引用上
+			const count = (commitsSinceGc.get(ws.key) ?? 0) + 1;
+			commitsSinceGc.set(ws.key, count % GC_EVERY_COMMITS);
+			if (count >= GC_EVERY_COMMITS) void gcInBackground(ws);
 			return round;
 		}
 	});
 }
 
 /** 发 prompt 前调用：把两轮之间用户自己的修改单独记一笔（工作区还没有任何提交时记成基线），没改动不提交 */
-export function recordWorkspaceChanges(cwdValue: string, session: string): Promise<GrowthRound | null> {
-	return commitRound(cwdValue, { kind: "user", session });
+export function recordWorkspaceChanges(cwdValue: string, session: string, options: CommitOptions = {}): Promise<GrowthRound | null> {
+	return commitRound(cwdValue, { kind: "user", session }, options);
 }
 
 // ---------- 读取 ----------
@@ -835,7 +883,7 @@ export async function filePatch(cwdValue: string, from: unknown, to: unknown, re
 	const r = await shadow(ws, ["diff", "-M", "--no-color", "--no-ext-diff", "-U1000000", assertHash(from, "from"), assertHash(to, "to"), "--", ...paths]);
 	if (/^Binary files .* differ$/m.test(r.stdout.toString("utf8", 0, Math.min(r.stdout.length, 64 * 1024)))) return { patch: "", binary: true, truncated: false };
 	if (r.stdout.length <= MAX_PATCH_BYTES) return { patch: r.stdout.toString("utf8"), binary: false, truncated: false };
-	return { patch: r.stdout.subarray(0, MAX_PATCH_BYTES).toString("utf8"), binary: false, truncated: true };
+	return { patch: utf8Prefix(r.stdout, MAX_PATCH_BYTES).toString("utf8"), binary: false, truncated: true };
 }
 
 export interface GrowthContent {
@@ -855,5 +903,5 @@ export async function fileContent(cwdValue: string, tree: unknown, relPath: unkn
 	const head = buf.subarray(0, Math.min(buf.length, 8000));
 	if (head.includes(0)) return { content: "", binary: true, truncated: false, size: buf.length };
 	if (buf.length <= MAX_CONTENT_BYTES) return { content: buf.toString("utf8"), binary: false, truncated: false, size: buf.length };
-	return { content: buf.subarray(0, MAX_CONTENT_BYTES).toString("utf8"), binary: false, truncated: true, size: buf.length };
+	return { content: utf8Prefix(buf, MAX_CONTENT_BYTES).toString("utf8"), binary: false, truncated: true, size: buf.length };
 }