mslxdff 0.1.45 → 0.1.55

package/docs/adr/0001-reasoning-content-injection.md

@@ -1,14 +1,14 @@
-# ADR-0001: Inject a reasoning_content placeholder on outbound assistant messages
-
-The Zen upstream's thinking-mode models (deepseek-family at minimum) return
-`400 "The reasoning_content in the thinking mode must be passed back"` when a
-multi-turn request echoes an assistant message without its `reasoning_content`.
-Clients speaking plain OpenAI format never send that field, so the proxy writes
-a `" "` placeholder into assistant messages before forwarding. Scope is `all`
-for deepseek-family models and `tool_calls` for kimi-family models; messages
-that already carry non-empty `reasoning_content` are left untouched.
-
-The alternative — telling clients to manage `reasoning_content` themselves —
-would break standard OpenAI-compatible clients, so the proxy eats this
-compatibility cost instead. Matches `/root/9router` v0.5.45
+# ADR-0001: Inject a reasoning_content placeholder on outbound assistant messages
+
+The Zen upstream's thinking-mode models (deepseek-family at minimum) return
+`400 "The reasoning_content in the thinking mode must be passed back"` when a
+multi-turn request echoes an assistant message without its `reasoning_content`.
+Clients speaking plain OpenAI format never send that field, so the proxy writes
+a `" "` placeholder into assistant messages before forwarding. Scope is `all`
+for deepseek-family models and `tool_calls` for kimi-family models; messages
+that already carry non-empty `reasoning_content` are left untouched.
+
+The alternative — telling clients to manage `reasoning_content` themselves —
+would break standard OpenAI-compatible clients, so the proxy eats this
+compatibility cost instead. Matches `/root/9router` v0.5.45
 `open-sse/utils/reasoningContentInjector.js`.

package/docs/adr/0002-models-free-filter.md

@@ -1,12 +1,12 @@
-# ADR-0002: /v1/models exposes only free models, matched by suffix or whitelist
-
-The upstream `/zen/v1/models` list contains ~60 models; exposing them all would
-pollute clients with paid models this proxy can't serve for free. `/v1/models`
-therefore filters to: `id` ending in `-free`, OR the explicit whitelist entry
-`big-pickle`. The whitelist exists because `big-pickle` is a free model without
-the `-free` suffix, and a suffix-only filter would silently drop it.
-
-A plain `endsWith("-free")` filter was considered and rejected for exactly that
-reason. Matches `/root/9router` v0.5.45
-`src/app/api/providers/suggested-models/filters.js`
+# ADR-0002: /v1/models exposes only free models, matched by suffix or whitelist
+
+The upstream `/zen/v1/models` list contains ~60 models; exposing them all would
+pollute clients with paid models this proxy can't serve for free. `/v1/models`
+therefore filters to: `id` ending in `-free`, OR the explicit whitelist entry
+`big-pickle`. The whitelist exists because `big-pickle` is a free model without
+the `-free` suffix, and a suffix-only filter would silently drop it.
+
+A plain `endsWith("-free")` filter was considered and rejected for exactly that
+reason. Matches `/root/9router` v0.5.45
+`src/app/api/providers/suggested-models/filters.js`
 (`KNOWN_FREE_OPENCODE_MODELS = ["big-pickle"]`).

package/docs/adr/0003-zero-state-no-auth.md

@@ -1,10 +1,10 @@
-# ADR-0003: Zero-state, no-DB, no-account local proxy
-
-Status: partially superseded by [ADR-0004](./0004-bearer-token.md) — the
-no-auth clause below is replaced; the zero-DB / no-account / no-cloud principles
-stand.
-
-By design this proxy holds no database, no token store, no account rotation,
-and no cloud sync. A single static bearer token is the only credential, kept
-in a 0600 state file (see ADR-0004); everything else is stateless per-process
+# ADR-0003: Zero-state, no-DB, no-account local proxy
+
+Status: partially superseded by [ADR-0004](./0004-bearer-token.md) — the
+no-auth clause below is replaced; the zero-DB / no-account / no-cloud principles
+stand.
+
+By design this proxy holds no database, no token store, no account rotation,
+and no cloud sync. A single static bearer token is the only credential, kept
+in a 0600 state file (see ADR-0004); everything else is stateless per-process
 memory at most.

package/docs/adr/0004-bearer-token.md

@@ -1,18 +1,18 @@
-# ADR-0004: Single static bearer token, persisted in a 0600 state file
-
-The proxy requires a bearer token on `/v1/*` so an accidentally-exposed port
-isn't an open relay. There is no account system: the token is a random
-`crypto` 32-byte value (hex), generated once on first run, persisted to a
-state file (default `~/.config/mslxdff/state.json`, `0600`, path overridable
-via `MSLXDFF_STATE_FILE`), and printed to stdout on creation. Rotate with
-`mslxdff -refresh-token`, which regenerates, rewrites the file, prints the
-new token, and exits (does not start the server).
-
-Auth is enforced with a constant-time string compare on
-`Authorization: Bearer <token>`; mismatches get `401` with `WWW-Authenticate`.
-`/health` stays public (no token). Tokens never appear in logs.
-
-Alternatives rejected: a fixed default token (same key on every install),
-per-user accounts (needs a DB — that's the 9Router provisioning surface we
-rejected in ADR-0003), and unauthenticated local-only binding (fragile;
+# ADR-0004: Single static bearer token, persisted in a 0600 state file
+
+The proxy requires a bearer token on `/v1/*` so an accidentally-exposed port
+isn't an open relay. There is no account system: the token is a random
+`crypto` 32-byte value (hex), generated once on first run, persisted to a
+state file (default `~/.config/mslxdff/state.json`, `0600`, path overridable
+via `MSLXDFF_STATE_FILE`), and printed to stdout on creation. Rotate with
+`mslxdff -refresh-token`, which regenerates, rewrites the file, prints the
+new token, and exits (does not start the server).
+
+Auth is enforced with a constant-time string compare on
+`Authorization: Bearer <token>`; mismatches get `401` with `WWW-Authenticate`.
+`/health` stays public (no token). Tokens never appear in logs.
+
+Alternatives rejected: a fixed default token (same key on every install),
+per-user accounts (needs a DB — that's the 9Router provisioning surface we
+rejected in ADR-0003), and unauthenticated local-only binding (fragile;
 a proxy relay deserves an explicit secret even on localhost).

package/docs/agents/domain.md

@@ -1,51 +1,51 @@
-# Domain Docs
-
-How the engineering skills should consume this repo's domain documentation when exploring the codebase.
-
-## Before exploring, read these
-
-- **`CONTEXT.md`** at the repo root, or
-- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
-
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
-
-## File structure
-
-Single-context repo (most repos):
-
-```
-/
-├── CONTEXT.md
-├── docs/adr/
-│   ├── 0001-event-sourced-orders.md
-│   └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/adr/                          ← system-wide decisions
-└── src/
-    ├── ordering/
-    │   ├── CONTEXT.md
-    │   └── docs/adr/                  ← context-specific decisions
-    └── billing/
-        ├── CONTEXT.md
-        └── docs/adr/
-```
-
-## Use the glossary's vocabulary
-
-When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
-
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
-
-## Flag ADR conflicts
-
-If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
-
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
 > _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -1,30 +1,30 @@
-# Issue tracker: Local Markdown
-
-Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
-
-## Conventions
-
-- One feature per directory: `.scratch/<feature-slug>/`
-- The spec is `.scratch/<feature-slug>/spec.md`
-- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
-- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
-- Comments and conversation history append to the bottom of the file under a `## Comments` heading
-
-## When a skill says "publish to the issue tracker"
-
-Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
-
-## When a skill says "fetch the relevant ticket"
-
-Read the file at the referenced path. The user will normally pass the path or the issue number directly.
-
-## Wayfinding operations
-
-Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
-
-- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
-- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
-- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
-- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
-- **Claim**: set `Status: claimed` and save before any work.
+# Issue tracker: Local Markdown
+
+Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
 - **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

package/docs/agents/triage-labels.md

@@ -1,15 +1,15 @@
-# Triage Labels
-
-The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
-
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
-
-When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
-
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
 Edit the right-hand column to match whatever vocabulary you actually use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.45",
+  "version": "0.1.55",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/auto.js

@@ -1,5 +1,5 @@
 import { statSync } from "node:fs";
-import { loadModelErrors, saveModelErrors, loadModelLatencies, saveModelLatencies, loadPreferredModel, defaultStateFile } from "./state.js";
+import { loadModelErrors, saveModelErrors, loadModelLatencies, saveModelLatencies, loadPreferredModel, loadModelPicks, saveModelPicks, defaultStateFile } from "./state.js";
 
 // 出厂默认首选模型（state.json 的 preferredModel / env MSLXDFF_PREFERRED_MODEL 可覆盖）
 export const DEFAULT_PREFERRED_MODEL = "big-pickle";
@@ -129,6 +129,8 @@ export function createAutoSelector({
   latencies: seedLatencies,
   persist = (errors, f = file) => saveModelErrors(errors, f ? { file: f } : {}),
   persistLatencies = (latencies, f = file) => saveModelLatencies(latencies, f ? { file: f } : {}),
+  loadPicks = () => (file ? loadModelPicks({ file }) : []),
+  persistPicks = (picks) => (file ? saveModelPicks(picks, { file }) : picks),
 } = {}) {
   const lastErrorAt = { ...(seedErrors ?? loadModelErrors(file ? { file } : {})) };
   const latencies = { ...(seedLatencies ?? loadModelLatencies(file ? { file } : {})) };
@@ -144,13 +146,29 @@ export function createAutoSelector({
     return [...new Set(list)].filter(Boolean);
   }
 
+  // 勾选集 = auto 候选池白名单：只在勾选的模型里择优；空勾选或勾选中无可用模型时回退全量
+  async function pickedPool(list) {
+    const picks = loadPicks();
+    if (!picks.length) return list;
+    const pickedSet = new Set(picks);
+    const filtered = list.filter((id) => pickedSet.has(id));
+    return filtered.length ? filtered : list;
+  }
+
   async function candidates() {
-    return rankModels(await loadList(), lastErrorAt, { now: now(), cooldownMs, slowCooldownMs, latencies, preferred: getPreferredModel({ file: file ?? undefined }) });
+    const list = await loadList();
+    const pool = await pickedPool(list);
+    return rankModels(pool, lastErrorAt, { now: now(), cooldownMs, slowCooldownMs, latencies, preferred: getPreferredModel({ file: file ?? undefined }) });
   }
 
   async function candidatesFor(requested) {
     if (!requested) return candidates();
     const list = await loadList();
+    // 显式指定某模型 = 认可它，自动加入勾选集（仅当它是真实上游 free 模型时，避免垃圾 id 污染）
+    const picks = loadPicks();
+    if (list.includes(requested) && !picks.includes(requested) && persistPicks) {
+      await persistPicks([...picks, requested]);
+    }
     const all = list.includes(requested) ? list : [requested, ...list];
     const others = rankModels(all.filter((id) => id !== requested), lastErrorAt, {
       now: now(),

package/src/chooser.js

@@ -1,11 +1,14 @@
 // 交互式模型选择器的纯渲染逻辑（便于测试）；键盘循环在 bin/mslxdff.js
 
-// items: [{ id, status?, ms?, fail?, current? }]；cursor 当前高亮行
+// items: [{ id, status?, ms?, fail?, current?, picked? }]；cursor 当前高亮行
+// multi=true 时多选勾选（picked 显示 [x]/[ ]），否则单选默认模型（当前显示 ✓）
 // 返回行数组（无 ANSI 颜色，纯文本标记，Windows 终端友好）
-export function renderChooser(items, cursor = 0) {
+export function renderChooser(items, cursor = 0, { multi = false } = {}) {
   return items.map((it, i) => {
     const arrow = i === cursor ? "❯" : " ";
-    const check = it.current ? " ✓ (current)" : "";
+    const check = multi
+      ? (it.picked ? " [✓]" : " [ ]")
+      : (it.current ? " ✓ (current)" : "");
     let state = "";
     if (it.fail) state = `  [fail: ${it.fail}]`;
     else if (it.ms != null) state = `  [${it.ms}ms]`;
@@ -14,16 +17,19 @@ export function renderChooser(items, cursor = 0) {
   });
 }
 
-export function renderChooserHelp() {
-  return ["", "↑/↓ move · Enter select as default · q/Esc cancel"];
+export function renderChooserHelp(multi = false) {
+  return multi
+    ? ["", "↑/↓ move · Space toggle pick · Enter save picks · q/Esc cancel"]
+    : ["", "↑/↓ move · Enter select as default · q/Esc cancel"];
 }
 
-// 解析按键：返回 "up" | "down" | "enter" | "cancel" | null(忽略)
+// 解析按键：返回 "up" | "down" | "enter" | "cancel" | "space" | null(忽略)
 export function parseKey(str) {
   if (!str) return null;
   if (str === "\x1b[A" || str === "k") return "up";
   if (str === "\x1b[B" || str === "j") return "down";
   if (str === "\r" || str === "\n") return "enter";
+  if (str === " " || str === "\x1b[32") return "space"; // 空格（32=0x20 的 ASC 表示）或某些终端 terminator
   if (str === "\x1b" || str === "q" || str === "\x03") return "cancel";
   return null;
 }

package/src/daemon.js

@@ -1,84 +1,84 @@
-import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { join, dirname } from "node:path";
-import os from "node:os";
-import { fileURLToPath } from "node:url";
-
-export function daemonDir() {
-  return process.env.MSLXDFF_DAEMON_DIR || join(os.homedir(), ".config", "mslxdff");
-}
-
-export function pidFile() {
-  return join(daemonDir(), "daemon.pid");
-}
-
-export function logFile() {
-  return join(daemonDir(), "daemon.log");
-}
-
-export function startDaemon(args = []) {
-  const here = fileURLToPath(import.meta.url);
-  const entry = here.endsWith("bin/mslxdff.js")
-    ? here
-    : join(dirname(here), "..", "bin", "mslxdff.js");
-  const dir = daemonDir();
-  mkdirSync(dir, { recursive: true });
-  const logFd = openSync(logFile(), "a", 0o600);
-  const env = { ...process.env, MSLXDFF_DAEMON: "1" };
-  // a -debug foreground session wouldn't pass MSLXDFF_DEBUG to the
-  // background daemon it restores (that flag means "print events to stdout")
-  delete env.MSLXDFF_DEBUG;
-  const child = spawn(process.execPath, [entry, ...args, "--daemon"], {
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env,
-  });
-  child.unref();
-  return child.pid;
-}
-
-export function writePid(pid, version) {
-  const dir = daemonDir();
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(pidFile(), version ? `${pid}\n${version}` : String(pid), { mode: 0o600 });
-}
-
-export function readPid() {
-  if (!existsSync(pidFile())) return null;
-  const raw = readFileSync(pidFile(), "utf8").trim();
-  const n = Number(raw.split("\n")[0]);
-  return Number.isInteger(n) && n > 0 ? n : null;
-}
-
-export function readPidVersion() {
-  if (!existsSync(pidFile())) return null;
-  const raw = readFileSync(pidFile(), "utf8");
-  const lines = raw.split("\n");
-  return lines.length > 1 && lines[1].trim() ? lines[1].trim() : null;
-}
-
-// Best-effort liveness check (signal 0); ESRCH means the process is gone.
-export function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code !== "ESRCH";
-  }
-}
-
-export function stopDaemon() {
-  const pid = readPid();
-  if (!pid) return { stopped: false, reason: "no pid file" };
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch (err) {
-    if (err.code !== "ESRCH") throw err;
-  }
-  try {
-    unlinkSync(pidFile());
-  } catch {
-    // already gone
-  }
-  return { stopped: true, pid };
-}
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+export function daemonDir() {
+  return process.env.MSLXDFF_DAEMON_DIR || join(os.homedir(), ".config", "mslxdff");
+}
+
+export function pidFile() {
+  return join(daemonDir(), "daemon.pid");
+}
+
+export function logFile() {
+  return join(daemonDir(), "daemon.log");
+}
+
+export function startDaemon(args = []) {
+  const here = fileURLToPath(import.meta.url);
+  const entry = here.endsWith("bin/mslxdff.js")
+    ? here
+    : join(dirname(here), "..", "bin", "mslxdff.js");
+  const dir = daemonDir();
+  mkdirSync(dir, { recursive: true });
+  const logFd = openSync(logFile(), "a", 0o600);
+  const env = { ...process.env, MSLXDFF_DAEMON: "1" };
+  // a -debug foreground session wouldn't pass MSLXDFF_DEBUG to the
+  // background daemon it restores (that flag means "print events to stdout")
+  delete env.MSLXDFF_DEBUG;
+  const child = spawn(process.execPath, [entry, ...args, "--daemon"], {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env,
+  });
+  child.unref();
+  return child.pid;
+}
+
+export function writePid(pid, version) {
+  const dir = daemonDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(pidFile(), version ? `${pid}\n${version}` : String(pid), { mode: 0o600 });
+}
+
+export function readPid() {
+  if (!existsSync(pidFile())) return null;
+  const raw = readFileSync(pidFile(), "utf8").trim();
+  const n = Number(raw.split("\n")[0]);
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+export function readPidVersion() {
+  if (!existsSync(pidFile())) return null;
+  const raw = readFileSync(pidFile(), "utf8");
+  const lines = raw.split("\n");
+  return lines.length > 1 && lines[1].trim() ? lines[1].trim() : null;
+}
+
+// Best-effort liveness check (signal 0); ESRCH means the process is gone.
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== "ESRCH";
+  }
+}
+
+export function stopDaemon() {
+  const pid = readPid();
+  if (!pid) return { stopped: false, reason: "no pid file" };
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (err) {
+    if (err.code !== "ESRCH") throw err;
+  }
+  try {
+    unlinkSync(pidFile());
+  } catch {
+    // already gone
+  }
+  return { stopped: true, pid };
+}

package/src/logs.js

@@ -1,4 +1,5 @@
 import { appendFileSync, readFileSync, mkdirSync, existsSync, writeFileSync, statSync } from "node:fs";
+import { appendFile, stat, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import os from "node:os";
 import { defaultStateFile } from "./state.js";
@@ -40,10 +41,48 @@ function trimIfOversized(file, maxBytes = MAX_BYTES) {
   }
 }
 
+async function trimIfOversizedAsync(file, maxBytes = MAX_BYTES) {
+  try {
+    const st = await stat(file);
+    if (st.size <= maxBytes) return;
+    const text = await readFile(file, "utf8");
+    const lines = text.split("\n");
+    const keep = lines.slice(-100);
+    await writeFile(file, keep.join("\n"));
+  } catch {
+    // ignore
+  }
+}
+
+function shouldSync(file) {
+  if (process.env.MSLXDFF_LOGS_SYNC === "1") return true;
+  if (process.env.MSLXDFF_DAEMON_DIR) {
+    const dir = process.env.MSLXDFF_DAEMON_DIR;
+    if (file.startsWith(dir)) return true;
+  }
+  // 显式 tmp 文件（所有 test 的 mkdtemp 前缀）走同步，保证 read-after-write 可见
+  const low = file.toLowerCase();
+  if (low.includes("mslxdff-") || low.includes("tmp") || low.includes("temp")) return true;
+  // 非默认目录的文件一律同步（测试传入的临时路径）
+  try {
+    const def = logDir().toLowerCase();
+    if (!low.startsWith(def)) return true;
+  } catch {}
+  return false;
+}
+
 function appendLine(file, entry) {
   ensureDir(dirname(file));
-  appendFileSync(file, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
-  trimIfOversized(file);
+  const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+  if (shouldSync(file)) {
+    appendFileSync(file, line);
+    trimIfOversized(file);
+    return;
+  }
+  // 线上异步：不阻塞事件循环
+  appendFile(file, line)
+    .catch(() => {})
+    .then(() => trimIfOversizedAsync(file).catch(() => {}));
 }
 
 export function appendCall(entry, { file = callsFile() } = {}) {