@trim21/personal-pi-extensions 0.1.490 → 0.1.492

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.490",
+  "version": "0.1.492",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/approval-suggest.ts

@@ -18,7 +18,7 @@ import { type BashCommand, parseBashCommands } from "./approval-rules.js";
  */
 const ARITY = JSON.parse(readFileSync(new URL("arity.json", import.meta.url), "utf8")) as Record<
   string,
-  number
+  number | undefined
 >;
 
 /**

package/src/bwrap/core.ts

@@ -105,11 +105,11 @@ export function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
   const base = {
     mode: config.mode,
     bwrapPath: config.bwrapPath,
-    writablePaths: config.writablePaths ?? [".", "/tmp"],
+    writablePaths: config.writablePaths,
     extraWritablePaths: config.extraWritablePaths,
-    denyPaths: config.denyPaths ?? [],
-    extraArgs: config.extraArgs ?? [],
-    networkAllowlist: config.networkAllowlist ?? [],
+    denyPaths: config.denyPaths,
+    extraArgs: config.extraArgs,
+    networkAllowlist: config.networkAllowlist,
     mihomoPath: config.mihomoPath,
     slirp4netnsPath: config.slirp4netnsPath,
     approvalRules: config.approvalRules ?? [],
@@ -529,8 +529,8 @@ export function createBwrapBashOperations(
             }, timeout * 1000)
           : undefined;
         const onAbort = () => killChild(child);
-        child.stdout?.on("data", onData);
-        child.stderr?.on("data", onData);
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
         signal?.addEventListener("abort", onAbort, { once: true });
         child.once("error", reject);
         child.once("close", (exitCode) => {

package/src/bwrap/mihomo-config.ts

@@ -81,7 +81,9 @@ function parseAllowlistEntry(entry: string): AllowlistEntry {
     const match = /^\[(.+)\](?::(\d+))?$/.exec(entry);
     if (match?.[1] === undefined) throw new Error(`Invalid allowlist entry "${entry}"`);
     host = match[1];
-    port = match[2] === undefined ? undefined : parsePort(match[2]);
+    // 端口组 (?::(\d+))? 可选：无端口时 match[2] 在运行时是 undefined
+    const portPart = match[2] as string | undefined;
+    port = portPart === undefined ? undefined : parsePort(portPart);
   } else {
     const colon = entry.lastIndexOf(":");
     if (colon === -1) {

package/src/bwrap/network-stack.ts

@@ -332,8 +332,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
             killChild(child.pid);
           };
 
-          child.stdout?.on("data", execOptions.onData);
-          child.stderr?.on("data", execOptions.onData);
+          child.stdout.on("data", execOptions.onData);
+          child.stderr.on("data", execOptions.onData);
           execOptions.signal?.addEventListener("abort", onAbort, { once: true });
 
           child.once("error", (error) => {

package/src/claude-code/common.ts

@@ -18,10 +18,6 @@ import { Value } from "typebox/value";
 const fileSnapshotSchema = Type.Object({
   digest: Type.String(),
   textEditable: Type.Boolean(),
-  // 以下字段仅 Read 写入，供同范围重复读取 dedup；Edit/Write 不写，
-  // 覆盖记录后 offset 缺省 → 不再 dedup，强制重新 Read（对齐 CC readFileState）
-  offset: Type.Optional(Type.Number()),
-  limit: Type.Optional(Type.Number()),
 });
 
 export type FileSnapshot = Static<typeof fileSnapshotSchema>;

package/src/claude-code/edit-utils.ts

@@ -73,10 +73,10 @@ function applyCurlySingleQuotes(str: string): string {
   for (let i = 0; i < chars.length; i++) {
     if (chars[i] === "'") {
       // 缩写中的撇号（如 don't）用右花引号，不做开/闭判断
-      const prev = chars[i - 1];
-      const next = chars[i + 1];
-      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev);
-      const nextIsLetter = next !== undefined && /\p{L}/u.test(next);
+      const prev = i > 0 ? chars[i - 1] : "";
+      const next = i + 1 < chars.length ? chars[i + 1] : "";
+      const prevIsLetter = /\p{L}/u.test(prev);
+      const nextIsLetter = /\p{L}/u.test(next);
       if (prevIsLetter && nextIsLetter) {
         result.push(RIGHT_SINGLE_CURLY_QUOTE);
       } else {

package/src/claude-code/files.ts

@@ -16,7 +16,7 @@ import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
-import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
+import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
 import type { ToolPendant } from "../lib/pendant.ts";
@@ -34,10 +34,6 @@ import { convertLeadingTabsToSpaces, findActualString, preserveQuoteStyle } from
 
 const SAMPLE_BYTES = 4096;
 
-/** 同范围重复读取、文件未变时返回的 stub（对齐 Claude Code 的 file_unchanged）。 */
-export const FILE_UNCHANGED_STUB =
-  "File unchanged since last read. The content from the earlier Read tool_result in this conversation is still current — refer to that instead of re-reading.";
-
 /** Read 全读时的文件大小上限（对齐 Claude Code 的 256KB）。 */
 const MAX_READ_SIZE_BYTES = 0.25 * 1024 * 1024;
 /** Read 输出 token 粗估上限（对齐 Claude Code 的 25K tokens；无 tokenizer，按 4 字符/token 估算）。 */
@@ -229,7 +225,7 @@ function requireCurrentRead(
 export function registerFileTools(
   pi: ExtensionAPI,
   state: ClaudeCodeState,
-  service: LspService,
+  getService: () => LspService,
 ): void {
   pi.registerTool({
     name: "Read",
@@ -317,21 +313,6 @@ export function registerFileTools(
       const key = await readStateKey(filePath);
       const buffer = await readFile(filePath);
 
-      // 同范围 + checksum 未变 → 返回 stub 而非重发内容（对齐 CC readFileState；
-      // 复用 reads 里的 sha256，比 mtime 可靠，无时间片粒度问题）
-      const previous = state.reads.get(key);
-      if (
-        previous !== undefined &&
-        previous.offset !== undefined &&
-        previous.offset === offset &&
-        previous.limit === limit &&
-        snapshotsEqual(previous, snapshotOf(buffer))
-      ) {
-        return {
-          content: [{ type: "text", text: FILE_UNCHANGED_STUB }],
-          details: { pendant: { subtitle: formatSubtitlePath(ctx.cwd, filePath) } },
-        };
-      }
       if (isBinary(buffer.subarray(0, SAMPLE_BYTES)))
         throw new Error(`Cannot read binary file: ${filePath}`);
       // 全读（limit 未传）时受字节上限约束（对齐 Claude Code）
@@ -349,12 +330,14 @@ export function registerFileTools(
           `File content (${estimatedTokens} tokens) exceeds maximum allowed tokens (${MAX_READ_TOKENS}). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file.`,
         );
       }
-      const snapshot = { ...snapshotOf(buffer), offset, limit };
+      const snapshot = snapshotOf(buffer);
       state.reads.set(key, snapshot);
       // LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
-      void service.notifyFile(filePath, ctx.cwd).catch(() => {
-        // 后台通知失败不影响读取
-      });
+      void getService()
+        .notifyFile(filePath, ctx.cwd)
+        .catch(() => {
+          // 后台通知失败不影响读取
+        });
       return {
         content: [{ type: "text", text: formatted.text }],
         details: {
@@ -444,7 +427,7 @@ export function registerFileTools(
                 text: diagnosticText,
                 errorCount,
                 warningCount,
-              } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+              } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
                 notify: (message, level) => ctx.ui.notify(message, level),
                 signal,
               });
@@ -547,7 +530,7 @@ export function registerFileTools(
               text: diagnosticText,
               errorCount,
               warningCount,
-            } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
               notify: (message, level) => ctx.ui.notify(message, level),
             });
             return [
@@ -646,7 +629,7 @@ export function registerFileTools(
               text: diagnosticText,
               errorCount,
               warningCount,
-            } = await service.lspDiagnosticsForFile(filePath, ctx.cwd, {
+            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
               notify: (message, level) => ctx.ui.notify(message, level),
             });
             return [
@@ -675,23 +658,8 @@ export function registerFileTools(
     },
   });
 
-  // lsp-rename 工具壳与 opencode 共享（lib/lsp/rename-tool.ts）；本工具集
-  // 跟踪 read-before-write 状态，rename 落盘的文件要标记为已读并随 details
-  // 持久化（FILE_TOOL_NAMES 的 restoreFileReads 依赖 details.reads）。
-  registerLspRenameTool(pi, service, {
-    recordReads: async (applied) => {
-      const reads: Record<string, FileSnapshot> = {};
-      for (const fileEdit of applied) {
-        const key = await readStateKey(fileEdit.path);
-        const snapshot = snapshotOf(fileEdit.newText);
-        state.reads.set(key, snapshot);
-        reads[key] = snapshot;
-      }
-      return reads;
-    },
-  });
-  // 只读符号查询工具（find-definition / find-reference / inspect）与 opencode 共享。
-  registerLspInspectTools(pi, service);
+  // 只读符号查询工具（find-definition / find-reference / inspect）与 opencode 共享；
+  // 它们由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
 /** 会更新 reads state 并随 details 持久化快照的工具名。 */
@@ -723,10 +691,34 @@ function restoreFileReads(
  * state 归本文件所有：扩展实例内创建，并随 session 事件从历史分支恢复，
  * 与主进程 index.ts 聚合加载时的行为一致。
  */
-export default function claudeCodeFileTools(pi: ExtensionAPI): void {
-  const service = registerLsp(pi);
+export default function claudeCodeFileTools(pi: ExtensionAPI, options?: LspServiceOptions): void {
   const state = createClaudeCodeState();
 
+  // LSP 专属工具（lsp-rename / inspect 族）仅在 lsp.json 存在 enabled 服务器时
+  // 注册（session_start 校验后）；本工具集跟踪 read-before-write 状态，rename
+  // 落盘的文件要标记为已读并随 details 持久化（restoreFileReads 依赖 details.reads）。
+  const manager = createLspManager(
+    pi,
+    {
+      onEnabled: (pi, service) => {
+        registerLspRenameTool(pi, service, {
+          recordReads: async (applied) => {
+            const reads: Record<string, FileSnapshot> = {};
+            for (const fileEdit of applied) {
+              const key = await readStateKey(fileEdit.path);
+              const snapshot = snapshotOf(fileEdit.newText);
+              state.reads.set(key, snapshot);
+              reads[key] = snapshot;
+            }
+            return reads;
+          },
+        });
+        registerLspInspectTools(pi, service);
+      },
+    },
+    options,
+  );
+
   // 扩展实例在进程启动 / /reload / /new / /resume / /fork 时重建，内存里的
   // 已读记账随之丢失。这里从当前分支的历史工具结果里恢复：digest 是当时的值，
   // 若文件在此期间被外部修改，Edit/Write 时的指纹对比仍会要求重新 Read，
@@ -742,5 +734,6 @@ export default function claudeCodeFileTools(pi: ExtensionAPI): void {
     restoreFileReads(state, ctx.sessionManager);
   });
 
-  registerFileTools(pi, state, service);
+  // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
+  registerFileTools(pi, state, () => manager.mustLazyGetService());
 }

package/src/claude-code/glob.ts

@@ -34,7 +34,7 @@ function extractGlobBaseDirectory(pattern: string): {
 } {
   const globChars = /[*?[{]/;
   const match = globChars.exec(pattern);
-  if (!match || match.index === undefined) {
+  if (!match) {
     // 无 glob 特殊字符：字面路径，目录部分作为 baseDir
     return { baseDir: dirname(pattern), relativePattern: basename(pattern) };
   }

package/src/gh-readonly.ts

@@ -122,12 +122,12 @@ export function runGh(
       timeoutId = setTimeout(() => killProcess("timeout"), timeout);
     }
 
-    proc.stdout?.on("data", (data: Buffer) => {
+    proc.stdout.on("data", (data: Buffer) => {
       const text = data.toString();
       stdout += text;
       combined.push(text);
     });
-    proc.stderr?.on("data", (data: Buffer) => {
+    proc.stderr.on("data", (data: Buffer) => {
       const text = data.toString();
       stderr += text;
       combined.push(text);
@@ -793,7 +793,7 @@ export async function renderStepLog(
   const totalLines = clean.split("\n").length;
   let logToShow = clean;
   let appliedOffset = false;
-  if (offset !== undefined && offset !== null && offset > 1) {
+  if (offset !== undefined && offset > 1) {
     if (offset > totalLines) {
       return {
         content: [
@@ -867,7 +867,7 @@ export async function renderJobLogs(
 ): Promise<CiLogsResult> {
   const { job, offset, limit, full } = params;
 
-  if (!jobs || jobs.length === 0) {
+  if (jobs.length === 0) {
     return {
       content: [{ type: "text", text: `No jobs found for run ${params.runId}` }],
       details: {},
@@ -923,7 +923,7 @@ export async function renderJobLogs(
 
         // Apply offset on the cleaned text, then truncate.
         let logToShow = clean;
-        if (offset !== undefined && offset !== null && offset > 1) {
+        if (offset !== undefined && offset > 1) {
           if (offset > totalLines) {
             steps.push({ name: s.name });
             continue;
@@ -1037,9 +1037,12 @@ export async function writeLogFile(
 
   let content: string;
   let what: string;
-  if (step !== undefined && step !== null) {
+  if (step === undefined) {
+    content = stripAnsi(rawLog);
+    what = `job "${targetJob.name}" (id: ${targetJob.id})`;
+  } else {
     const found = targetJob.steps.find((s) => s.name.toLowerCase() === step.toLowerCase());
-    if (!found) {
+    if (found === undefined) {
       return {
         content: [
           {
@@ -1064,9 +1067,6 @@ export async function writeLogFile(
     }
     content = cleanStepOutput(stepLog);
     what = `step ${found.number} ("${found.name}") of job "${targetJob.name}"`;
-  } else {
-    content = stripAnsi(rawLog);
-    what = `job "${targetJob.name}" (id: ${targetJob.id})`;
   }
 
   const target = resolve(cwd ?? process.cwd(), outputFile);
@@ -1480,7 +1480,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         getJobLog(String(run_id), jobId, effectiveRepo, signal, ctx.cwd, params);
 
       // ── Write the complete log to a file ───────────────────────────────
-      if (output_file !== undefined && output_file !== null && output_file !== "") {
+      if (output_file !== undefined && output_file !== "") {
         const result = await writeLogFile(
           { runId: String(run_id), job, step, outputFile: output_file },
           jobs,
@@ -1492,7 +1492,7 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
       }
 
       // ── Fetch a specific step's logs (requires `job`) ─────────────────
-      if (step !== undefined && step !== null) {
+      if (step !== undefined) {
         onUpdate?.({
           content: [{ type: "text", text: `Fetching job list...` }],
           details: {},

package/src/lib/cli.ts

@@ -238,7 +238,7 @@ export function parseCommand<TFlags extends TObject>(
       } else if (info.kind === "boolean") {
         rawFlags[info.key] = true;
       } else {
-        const next = tokens[i + 1];
+        const next = tokens.at(i + 1);
         if (next !== undefined && !looksLikeFlag(next)) {
           rawFlags[info.key] = next;
           i++;
@@ -266,7 +266,7 @@ export function parseCommand<TFlags extends TObject>(
         } else if (j + 1 < rest.length) {
           rawFlags[info.key] = rest.slice(j + 1);
         } else {
-          const next = tokens[i + 1];
+          const next = tokens.at(i + 1);
           if (next !== undefined && !looksLikeFlag(next)) {
             rawFlags[info.key] = next;
             i++;
@@ -327,10 +327,7 @@ export function parseCommand<TFlags extends TObject>(
     parsed = Value.Convert(spec.flags, Value.Clone(parsed));
     if (!Value.Check(spec.flags, parsed)) {
       const [first] = [...Value.Errors(spec.flags, parsed)];
-      return errorResult(
-        spec,
-        `Invalid arguments: ${first?.message ?? "value does not match flags"}`,
-      );
+      return errorResult(spec, `Invalid arguments: ${first.message}`);
     }
   } catch {
     return errorResult(spec, "Invalid arguments");

package/src/lib/lsp/client.ts

@@ -25,6 +25,7 @@ import type {
   Hover,
   Location as LspLocation,
   LocationLink,
+  Range,
   WorkspaceEdit,
 } from "vscode-languageserver-types";
 
@@ -192,7 +193,9 @@ function toInspectLocations(result: DefinitionResult): InspectLocation[] {
   for (const item of items) {
     if ("targetUri" in item) {
       if (!item.targetUri.startsWith("file:")) continue;
-      const range = item.targetSelectionRange ?? item.targetRange;
+      const range =
+        (item as Omit<LocationLink, "targetSelectionRange"> & { targetSelectionRange?: Range })
+          .targetSelectionRange ?? item.targetRange;
       locations.push({
         path: normalize(fileURLToPath(item.targetUri)),
         line: range.start.line,
@@ -424,7 +427,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     new StreamMessageReader(input.server.process.stdout),
     new StreamMessageWriter(input.server.process.stdin),
   );
-  input.server.process.stderr?.resume();
+  input.server.process.stderr.resume();
   /** 连接或服务器进程已关闭；pull 重试循环以此终止，避免无界等待。 */
   let connectionClosed = false;
   input.server.process.once("exit", () => {
@@ -581,7 +584,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("workspace/didChangeConfiguration", { settings });
   }
 
-  const files: Record<string, { version: number; text: string }> = {};
+  const files: Record<string, { version: number; text: string } | undefined> = {};
 
   // ── 驻留 LRU ────────────────────────────────────────────────────────────────
 
@@ -823,16 +826,16 @@ export async function create(input: CreateInput): Promise<LspClient> {
     if (timeout <= 0) return Promise.resolve(false);
     return new Promise<boolean>((resolve) => {
       let finished = false;
+      const timer = setTimeout(() => finish(false), timeout);
       const finish = (result: boolean) => {
         if (finished) return;
         finished = true;
-        if (timer) clearTimeout(timer);
+        clearTimeout(timer);
         registrationListeners.delete(listener);
         resolve(result);
       };
       const listener = () => finish(true);
       registrationListeners.add(listener);
-      const timer = setTimeout(() => finish(false), timeout);
     });
   }
 
@@ -846,12 +849,14 @@ export async function create(input: CreateInput): Promise<LspClient> {
     return new Promise<boolean>((resolve) => {
       let finished = false;
       let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+      const timeoutTimer = setTimeout(() => finish(false), request.timeout);
+      const unsub = () => diagnosticListeners.delete(listener);
       const finish = (result: boolean) => {
         if (finished) return;
         finished = true;
         if (debounceTimer) clearTimeout(debounceTimer);
-        if (timeoutTimer) clearTimeout(timeoutTimer);
-        unsub?.();
+        clearTimeout(timeoutTimer);
+        unsub();
         resolve(result);
       };
       const schedule = () => {
@@ -866,13 +871,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
         );
       };
 
-      const timeoutTimer = setTimeout(() => finish(false), request.timeout);
       const listener = (event: { path: string; serverID: string }) => {
         if (event.path !== request.path || event.serverID !== input.serverID) return;
         schedule();
       };
       diagnosticListeners.add(listener);
-      const unsub = () => diagnosticListeners.delete(listener);
       schedule();
     });
   }

package/src/lib/lsp/inspect-tool.ts

@@ -216,7 +216,7 @@ async function probeSymbolCandidates(options: {
   }
   const groups = new Map<string, { output: InspectOutput; candidates: LspPosition[] }>();
   for (const [index, candidate] of candidates.entries()) {
-    const output = outputs[index];
+    const output = outputs.at(index);
     if (!output) continue;
     const group = groups.get(output.text);
     if (group) group.candidates.push(candidate);
@@ -234,7 +234,7 @@ async function probeSymbolCandidates(options: {
       `Ambiguous symbol on line ${options.line} of ${options.filePath}: several distinct symbols share the name "${options.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
     );
   }
-  const first = [...groups.values()][0];
+  const first = [...groups.values()].at(0);
   if (!first) throw new Error("LSP inspect returned no result");
   return first.output;
 }

package/src/lib/lsp/language.ts

@@ -2,7 +2,7 @@
  * 文件扩展名 → LSP languageId 映射，用于 didOpen 通知。
  * 移植自 opencode packages/opencode/src/lsp/language.ts。
  */
-export const LANGUAGE_EXTENSIONS: Record<string, string> = {
+export const LANGUAGE_EXTENSIONS: Record<string, string | undefined> = {
   ".abap": "abap",
   ".bat": "bat",
   ".bib": "bibtex",

package/src/lib/lsp/lsp.ts

@@ -18,7 +18,7 @@
 
 import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { extname, join, normalize, relative, sep } from "node:path";
 
 import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
@@ -90,12 +90,19 @@ export type LspConfig = Static<typeof lspConfigSchema>;
 
 /** "500" → 500、"5s" → 5000、"1m" → 60000；无效字符串返回 NaN（由 toMs 过滤）。 */
 function parseTimeoutString(value: string): number {
-  const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)?$/.exec(value.trim());
+  // 单位组永远参与匹配（缺省为空串），避免"可选捕获组在类型上不可空"的歧义
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|)\s*$/.exec(value.trim());
   if (!match) return NaN;
   const amount = Number(match[1]);
-  const unit = match[2] ?? "ms";
-  const factors: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 };
-  return amount * (factors[unit] ?? 1);
+  const factors: Record<string, number | undefined> = {
+    "": 1,
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+  };
+  const factor = factors[match[2]];
+  return amount * (factor ?? 1);
 }
 
 function toMs(value: number | string | undefined): number | undefined {
@@ -843,71 +850,154 @@ export interface LspServiceOptions {
   globalConfigPath?: string;
 }
 
-/** 创建 LSP service 并注册 pi 的进程级清理生命周期。 */
-export function registerLsp(pi: ExtensionAPI, options?: LspServiceOptions): LspService {
-  const service = createLspService(options?.adapters, options?.globalConfigPath);
-  pi.on?.("session_shutdown", () => service.shutdownAll());
-  // session 开始是最早能拿到本地配置 cwd 的时机：预加载并校验，配置错误立即通知
-  pi.on?.("session_start", (_event, ctx) => {
-    void loadLspConfig(ctx.cwd, options?.globalConfigPath)
-      .then((config) => validateConfig(config, options?.adapters))
-      .catch((error: unknown) => {
-        if (error instanceof Error) ctx.ui.notify?.(error.message, "error");
+export interface LspManagerHooks {
+  /**
+   * session_start 校验通过且存在 enabled 服务器时调用（每实例至多一次）；
+   * LSP 专属工具（rename / inspect 族）在此注册，未配置时保持不可见。
+   */
+  onEnabled: (pi: ExtensionAPI, service: LspService) => void;
+}
+
+export interface LspManager {
+  /**
+   * 文件工具的 service 访问器：永不抛错。disabled / session_start 未运行时
+   * 返回共享 no-op service（诊断与文件事件通知为空操作）。
+   */
+  mustLazyGetService(): LspService;
+  /** 当前会话是否已创建 service（/lsp-stop 后仍为 true，内部 disabled 语义不变）。 */
+  haveEnabledLsp(): boolean;
+}
+
+/**
+ * no-op service 单例：空 adapter 列表 → getClients 永远返回空，任何请求都是
+ * 空操作。globalConfigPath 指向必然不存在的文件——真实全局配置若声明了
+ * `enabled`，createLspService 的建时校验会因空 adapter 集合而抛错。
+ */
+const noopServiceHolder: { service?: LspService } = {};
+function getNoopService(): LspService {
+  noopServiceHolder.service ??= createLspService(
+    [],
+    join(tmpdir(), ".pi-lsp-noop-global-does-not-exist.json"),
+  );
+  return noopServiceHolder.service;
+}
+
+/** 会话配置里生效（未被 enabled 白名单排除、未被 disabled）的服务器数量。 */
+function enabledServerCount(config: LspConfig, adapters?: LspServerAdapter[]): number {
+  const ids = adapters ? adapters.map((adapter) => adapter.id) : Object.keys(config.servers ?? {});
+  return ids.filter((id) => {
+    if (config.enabled && !config.enabled.includes(id)) return false;
+    if (config.disabled?.includes(id)) return false;
+    return true;
+  }).length;
+}
+
+/**
+ * 创建 LSP manager 并注册 pi 会话生命周期：
+ * - session_start（被 pi await）：加载并校验配置；存在 enabled 服务器才创建
+ *   service（进程仍首次工具调用才 spawn）并调用 onEnabled 注册 LSP 工具；
+ *   配置缺失或错误则保持 disabled（错误 notify 后降级，不阻断会话启动）。
+ * - session_shutdown：关闭全部服务器进程。
+ * 文件工具经 mustLazyGetService 访问，在任何状态下都能安全工作。
+ */
+export function createLspManager(
+  pi: ExtensionAPI,
+  hooks: LspManagerHooks,
+  options?: LspServiceOptions,
+): LspManager {
+  let service: LspService | undefined;
+
+  pi.on("session_start", async (_event, ctx) => {
+    // /reload 等路径可能对同一 runner 重发 session_start：先清掉旧实例再建
+    if (service !== undefined) {
+      // 旧实例关闭失败不阻断新会话构建
+      await service.shutdownAll().catch(() => {
+        /* noop */
       });
-    // footer status 显示当前所有 LSP server 状态（无 UI 时不显示）
-    service.attachStatus(
-      ctx.ui?.setStatus
-        ? (text) => ctx.ui.setStatus("lsp", text ? ctx.ui.theme.fg("accent", text) : undefined)
-        : undefined,
-    );
+      service = undefined;
+    }
+    try {
+      const config = await loadLspConfig(ctx.cwd, options?.globalConfigPath);
+      validateConfig(config, options?.adapters);
+      if (enabledServerCount(config, options?.adapters) === 0) return;
+      const next = createLspService(options?.adapters, options?.globalConfigPath);
+      // footer status 显示当前所有 LSP server 状态（无 UI 时不显示）
+      next.attachStatus((text) =>
+        ctx.ui.setStatus("lsp", text ? ctx.ui.theme.fg("accent", text) : undefined),
+      );
+      service = next;
+      hooks.onEnabled(pi, next);
+    } catch (error) {
+      service = undefined;
+      if (error instanceof Error) ctx.ui.notify(error.message, "error");
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    void service?.shutdownAll();
   });
+
   // agent 生命周期边界显式刷新 status：agent 运行中 LSP server 才被惰性
   // spawn（首次工具调用），start/end 时保证 footer 反映当前实际状态。
-  pi.on?.("agent_start", () => service.refreshStatus());
-  pi.on?.("agent_end", () => service.refreshStatus());
+  pi.on("agent_start", () => service?.refreshStatus());
+  pi.on("agent_end", () => service?.refreshStatus());
 
-  pi.registerCommand?.("lsp-stop", {
+  pi.registerCommand("lsp-stop", {
     description: "Stop all LSP servers and disable LSP until /lsp-start or /lsp-reload",
     handler: async (_args, ctx) => {
+      if (service === undefined) {
+        ctx.ui.notify("LSP not configured: nothing to stop", "warning");
+        return;
+      }
       await service.stop();
-      ctx.ui.notify?.("LSP disabled: all servers stopped", "info");
+      ctx.ui.notify("LSP disabled: all servers stopped", "info");
     },
   });
 
-  pi.registerCommand?.("lsp-start", {
+  pi.registerCommand("lsp-start", {
     description: "Re-enable LSP; servers start on the next tool call",
     handler: (_args, ctx) => {
+      if (service === undefined) {
+        ctx.ui.notify("LSP not configured: nothing to enable", "warning");
+        return Promise.resolve();
+      }
       service.start();
-      ctx.ui.notify?.("LSP enabled: servers will start on the next tool call", "info");
+      ctx.ui.notify("LSP enabled: servers will start on the next tool call", "info");
       return Promise.resolve();
     },
   });
 
-  pi.registerCommand?.("lsp-reload", {
+  pi.registerCommand("lsp-reload", {
     description: "Restart a specific LSP server: /lsp-reload <server-id>",
     getArgumentCompletions: (prefix) =>
-      service
-        .serverIDs()
+      (service?.serverIDs() ?? [])
         .toSorted()
         .filter((id) => id.startsWith(prefix))
         .map((id) => ({ value: id, label: id })),
     handler: async (args, ctx) => {
+      if (service === undefined) {
+        ctx.ui.notify("LSP not configured: nothing to reload", "warning");
+        return;
+      }
       const serverID = args.trim();
       const known = service.serverIDs().toSorted();
       if (!serverID) {
-        ctx.ui.notify?.(
+        ctx.ui.notify(
           `usage: /lsp-reload <server-id>${known.length > 0 ? ` (known: ${known.join(", ")})` : ""}`,
           "warning",
         );
         return;
       }
       await service.reload(serverID);
-      ctx.ui.notify?.(
+      ctx.ui.notify(
         `LSP server "${serverID}" reloaded: will restart on the next tool call`,
         "info",
       );
     },
   });
 
-  return service;
+  return {
+    mustLazyGetService: () => service ?? getNoopService(),
+    haveEnabledLsp: () => service !== undefined,
+  };
 }

package/src/lib/lsp/rename-tool.ts

@@ -150,7 +150,7 @@ export function registerLspRenameTool(
         { result: (typeof successes)[number]["result"]; candidates: typeof candidates }
       >();
       for (const [index, candidate] of candidates.entries()) {
-        const entry = successes[index];
+        const entry = successes.at(index);
         if (!entry) continue;
         const key = canonicalizeEdit(entry.result.edit);
         const group = groups.get(key);
@@ -172,7 +172,7 @@ export function registerLspRenameTool(
           `Ambiguous rename target on line ${params.line} of ${filePath}: several distinct symbols share the name "${params.symbol}". Retry with 'character' (1-based) to pick one:\n${listing}`,
         );
       }
-      const firstGroup = [...groups.values()][0];
+      const firstGroup = [...groups.values()].at(0);
       if (!firstGroup) throw new Error("LSP rename returned no target");
       const { result } = firstGroup;
 

package/src/lib/ui.ts

@@ -76,7 +76,7 @@ export async function selectMultiple(
   opts: { signal?: AbortSignal; doneLabel: string },
 ): Promise<string[]> {
   const selected: string[] = [];
-  while (true) {
+  for (;;) {
     const selectedSet = new Set(selected);
     const displayToLabel = new Map<string, string>();
     const round: SelectAction[] = [];
@@ -143,7 +143,7 @@ export async function selectCheckboxActions<T extends string>(
   opts: { signal?: AbortSignal } = {},
 ): Promise<CheckboxActionResult<T> | undefined> {
   const selected: string[] = [];
-  while (true) {
+  for (;;) {
     const selectedSet = new Set(selected);
     const displayToLabel = new Map<string, string>();
     const round: SelectAction[] = [];

package/src/lib/write-guard.ts

@@ -143,7 +143,7 @@ export async function guardWriteAccess(
     throw new Error(`Path "${absolutePath}" is outside workspace. No UI available for approval.`);
   }
 
-  while (true) {
+  for (;;) {
     const diffPreview = opts.change ? await buildDiffPreview(absolutePath, opts.change) : undefined;
     const title =
       `Model requests write access outside workspace:\n\n` +

package/src/openai-cost/config.ts

@@ -66,7 +66,7 @@ function nonEmpty(value: string | undefined): string | undefined {
 function normalizeModel(model: Static<typeof modelSchema>): OpenaiCostModelConfig | undefined {
   const id = nonEmpty(model.id);
   if (!id) return undefined;
-  const input = model.input?.filter((value) => value === "text" || value === "image") ?? [];
+  const input = model.input ?? [];
   return {
     id,
     name: nonEmpty(model.name) ?? id,

package/src/openai-cost/cost.ts

@@ -90,7 +90,7 @@ export async function scanSseCost(body: ReadableStream<Uint8Array>): Promise<num
   let buffer = "";
   let last: number | undefined;
   try {
-    while (true) {
+    for (;;) {
       const { done, value } = await reader.read();
       if (done) break;
       buffer += decoder.decode(value, { stream: true });

package/src/opencode/edit-engine.ts

@@ -372,7 +372,7 @@ const EscapeNormalizedReplacer: Replacer = function* (content, find) {
 
 const MultiOccurrenceReplacer: Replacer = function* (content, find) {
   let startIndex = 0;
-  while (true) {
+  for (;;) {
     const index = content.indexOf(find, startIndex);
     if (index === -1) break;
     yield find;

package/src/opencode/files.ts

@@ -31,7 +31,7 @@ import { Type } from "typebox";
 
 import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
-import { type LspService, registerLsp } from "../lib/lsp/lsp.js";
+import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
 import { formatSubtitlePath } from "../lib/path.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
@@ -105,8 +105,8 @@ const IMAGE_SIGNATURES: {
       return (
         startsWithAscii(buf, 0, "BM") &&
         buf.length >= 30 &&
-        (buf[28] ?? 0) === 1 &&
-        [1, 4, 8, 16, 24, 32].includes(buf[28 + 1] ?? 0)
+        buf[28] === 1 &&
+        [1, 4, 8, 16, 24, 32].includes(buf[28 + 1])
       );
     },
     mimeType: "image/bmp",
@@ -295,7 +295,7 @@ async function formatDirectoryEntries(dirPath: string): Promise<string[]> {
   return results;
 }
 
-function registerReadTool(pi: ExtensionAPI, service: LspService): void {
+function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void {
   pi.registerTool({
     name: "read",
     label: "read",
@@ -434,9 +434,11 @@ function registerReadTool(pi: ExtensionAPI, service: LspService): void {
       content = [{ type: "text", text: outputText }];
 
       // opencode: LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
-      void service.notifyFile(absolutePath, ctx.cwd).catch(() => {
-        // 后台通知失败不影响读取
-      });
+      void getService()
+        .notifyFile(absolutePath, ctx.cwd)
+        .catch(() => {
+          // 后台通知失败不影响读取
+        });
 
       return {
         content,
@@ -462,7 +464,7 @@ const editSchema = Type.Object({
   ),
 });
 
-function registerEditTool(pi: ExtensionAPI, service: LspService): void {
+function registerEditTool(pi: ExtensionAPI, getService: () => LspService): void {
   pi.registerTool({
     name: "edit",
     label: "edit",
@@ -525,7 +527,7 @@ function registerEditTool(pi: ExtensionAPI, service: LspService): void {
               text: diagnosticText,
               errorCount,
               warningCount,
-            } = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+            } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
             return [
               "Edit applied successfully.",
               { diff: "", patch: "", firstChangedLine: 0 },
@@ -567,7 +569,7 @@ function registerEditTool(pi: ExtensionAPI, service: LspService): void {
             text: diagnosticText,
             errorCount,
             warningCount,
-          } = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+          } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
           return [
             "Edit applied successfully.",
             { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
@@ -615,7 +617,7 @@ export function resolveBom(
   return { bom: sourceBom || nextBom, text };
 }
 
-function registerWriteTool(pi: ExtensionAPI, service: LspService): void {
+function registerWriteTool(pi: ExtensionAPI, getService: () => LspService): void {
   pi.registerTool({
     name: "write",
     label: "write",
@@ -667,7 +669,7 @@ function registerWriteTool(pi: ExtensionAPI, service: LspService): void {
             text: diagnosticText,
             errorCount,
             warningCount,
-          } = await service.lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+          } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
 
           return [
             "Wrote file successfully.",
@@ -694,19 +696,25 @@ function registerWriteTool(pi: ExtensionAPI, service: LspService): void {
 
 // ── 入口 ─────────────────────────────────────────────────────────────────────
 
-export function registerFileTools(pi: ExtensionAPI, service: LspService): void {
-  registerReadTool(pi, service);
-  registerEditTool(pi, service);
-  registerWriteTool(pi, service);
-  // 工具壳与 claude-code 共享（lib/lsp/rename-tool.ts）；opencode 不跟踪
-  // read-before-write 状态，不传 recordReads hook。
-  registerLspRenameTool(pi, service);
-  // 只读符号查询工具（find-definition / find-reference / inspect）与 claude-code 共享。
-  registerLspInspectTools(pi, service);
+export function registerFileTools(pi: ExtensionAPI, getService: () => LspService): void {
+  registerReadTool(pi, getService);
+  registerEditTool(pi, getService);
+  registerWriteTool(pi, getService);
+  // lsp-rename / inspect 工具由 manager 的 onEnabled 回调注册，不在这里注册。
 }
 
-/** 独立入口：创建 LSP service（闭包共享给三个工具）并注册。 */
-export default function opencodeFileTools(pi: ExtensionAPI): void {
-  const service = registerLsp(pi);
-  registerFileTools(pi, service);
+/** 独立入口：创建 LSP manager（session_start 时按配置启用）并注册文件工具。 */
+export default function opencodeFileTools(pi: ExtensionAPI, options?: LspServiceOptions): void {
+  const manager = createLspManager(
+    pi,
+    {
+      onEnabled: (pi, service) => {
+        registerLspRenameTool(pi, service);
+        registerLspInspectTools(pi, service);
+      },
+    },
+    options,
+  );
+  // 文件工具无条件注册；service 惰性获取，disabled 时为 no-op。
+  registerFileTools(pi, () => manager.mustLazyGetService());
 }

package/src/talk/index.ts

@@ -171,7 +171,7 @@ export default function talk(pi: ExtensionAPI) {
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
   pi.on("session_start", (_event, ctx: ExtensionContext) => {
-    const cwd = ctx.sessionManager.getCwd() ?? ctx.cwd;
+    const cwd = ctx.sessionManager.getCwd();
     const now = Date.now();
     // A fork/branch/resume of a session that joined a group keeps that talk
     // identity (agentId); a fresh session gets the new session id.
@@ -463,13 +463,7 @@ export default function talk(pi: ExtensionAPI) {
 
   pi.registerMessageRenderer<DeliveryDetails>(DELIVERY_TYPE, (message, _options, theme) => {
     const d = message.details;
-    if (
-      !d ||
-      typeof d.id !== "string" ||
-      typeof d.ts !== "number" ||
-      typeof d.body !== "string" ||
-      !d.from
-    ) {
+    if (!d || typeof d.id !== "string" || typeof d.ts !== "number" || typeof d.body !== "string") {
       return; // pre-renderer entries: keep pi's default custom-message box
     }
     const idTail = d.id.slice(-8);

package/src/talk/registry.ts

@@ -164,7 +164,7 @@ function pidAlive(pid: number, pidStart?: number): boolean {
     process.kill(pid, 0);
   } catch (error) {
     // EPERM means the process exists but isn't ours — still alive
-    return (error as NodeJS.ErrnoException)?.code === "EPERM";
+    return (error as NodeJS.ErrnoException).code === "EPERM";
   }
   if (pidStart === undefined) return true;
   const start = readStartTime(pid);

package/src/vision-agent.ts

@@ -276,7 +276,7 @@ export async function callVision(
         messages: [{ role: "user", content, timestamp: Date.now() }],
       },
       {
-        maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+        maxTokens: model.maxTokens,
         signal: withTimeout(signal, REQUEST_TIMEOUT_MS),
       },
     );
@@ -290,7 +290,7 @@ export async function callVision(
     throw new Error("API 未返回内容");
   }
   const tokenStr =
-    typeof result.usage?.totalTokens === "number" ? String(result.usage.totalTokens) : "?";
+    typeof result.usage.totalTokens === "number" ? String(result.usage.totalTokens) : "?";
   const labels = loaded.map((l) => l.label).join(", ");
   return `[${labels}]\n${text}\n[模型: ${model.id}, tokens: ${tokenStr}]`;
 }