dsh-auto-compaction 0.1.1 → 0.1.3

package/lib/index.js

@@ -22,11 +22,24 @@ import { join } from "node:path";
 import { BlockAssembler, LlmError, contentHasImage } from "@deepseek-ai/dsh-llm";
 import BasicCompactionEngine from "@deepseek-ai/dsh-compaction-basic";
 import { decideTrigger, shouldAttempt } from "./plan.js";
+import { writeStatus } from "./status.js";
+import {
+  continuationInstruction,
+  expectedSections,
+  looksTruncated,
+  mergeSummary,
+  rewriteInstruction,
+  stripTruncationMarkers,
+  validateSummary,
+} from "./summary.js";
 
 const LOG = "[handoff]";
+const MAX_SUMMARY_ATTEMPTS = 3;
 
 const SETTINGS_DIR = join(homedir(), ".dsh-handoff-compaction");
-const SETTINGS_FILE = join(SETTINGS_DIR, "settings.json");
+// Test harnesses point this at a missing file so the live sidecar cannot leak
+// into a case that expects the configured ratio.
+const SETTINGS_FILE = process.env.DSH_HANDOFF_SETTINGS_FILE ?? join(SETTINGS_DIR, "settings.json");
 const DEFAULT_TEMPLATE_FILE = join(SETTINGS_DIR, "template.md");
 
 /**
@@ -124,6 +137,22 @@ function finishError(finish) {
   }
 }
 
+function mergeUsage(left, right) {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  const merged = { ...left };
+  for (const key of Object.keys(right)) {
+    const value = right[key];
+    if (typeof value === "number" && typeof merged[key] === "number") merged[key] += value;
+    else if (merged[key] === undefined) merged[key] = value;
+  }
+  return merged;
+}
+
+function errorCodeOf(error) {
+  return error !== null && typeof error === "object" && typeof error.code === "string" ? error.code : "";
+}
+
 export default class HandoffCompaction extends BasicCompactionEngine {
   static inject = ["llm", "tokenMeter", "sessions"];
 
@@ -169,9 +198,10 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       autoCreateTemplate,
       ...base
     } = config;
-    // auto:false keeps the stock between-step pressure trigger out of the way;
-    // this backend decides on idle instead.
-    super(ctx, { ...base, auto: false });
+    // The stock trigger is registered so the plugin switch can hand compaction
+    // back to the native engine live; compactIfNeeded() suppresses it while the
+    // handoff path is enabled.
+    super(ctx, { ...base, auto: true });
     this.handoff = {
       instruction: typeof handoffInstruction === "string" && handoffInstruction.trim().length > 0 ? handoffInstruction : undefined,
       contextWindowOverride: contextWindowOverride ?? 0,
@@ -211,6 +241,26 @@ export default class HandoffCompaction extends BasicCompactionEngine {
     return `${Math.round((this.config.thresholdRatio ?? 0.9) * 100)}%`;
   }
 
+  /**
+   * Settings switch. Missing settings or a missing field keeps the plugin on;
+   * only an explicit `enabled: false` hands compaction back to the stock engine.
+   */
+  handoffEnabled() {
+    const live = readSettings();
+    return !(live !== undefined && live.enabled === false);
+  }
+
+  /**
+   * The base registers its between-step pressure / overflow triggers whenever
+   * `auto` is on. While the handoff path is enabled they must stay inert, so
+   * the plugin still only compacts from its idle gate. Disabled: delegate, and
+   * DSH's native compaction behaves exactly as without the plugin.
+   */
+  async compactIfNeeded(agent, trigger, signal) {
+    if (this.handoffEnabled()) return null;
+    return super.compactIfNeeded(agent, trigger, signal);
+  }
+
   log(message, level = "info") {
     const line = `${new Date().toISOString()} ${LOG} ${message}`;
     if (this.handoff?.traceConsole === true) {
@@ -246,6 +296,7 @@ export default class HandoffCompaction extends BasicCompactionEngine {
 
   async checkAndHandoff(agent, why = "idle") {
     if (this.running.has(agent)) return;
+    if (!this.handoffEnabled()) return;
     try {
       const session = agent.session;
       if (!session) return;
@@ -301,24 +352,123 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       }
 
       this.running.add(agent);
+      writeStatus(session.id, {
+        phase: "running",
+        step: "prepare",
+        startedAt: Date.now(),
+        totalTokens: measurement.totalTokens,
+        thresholdTokens: decision.thresholdTokens,
+        contextWindow,
+        timeoutMs: this.handoff.timeoutMs,
+        provider: target.provider,
+        model: target.model,
+      });
       try {
         const result = await this.compactNow(agent, AbortSignal.timeout(this.handoff.timeoutMs));
         if (result === null || result === undefined) {
+          writeStatus(session.id, {
+            phase: "done",
+            step: "done",
+            completedAt: Date.now(),
+            shadowedNodes: 0,
+            shadowedTokens: 0,
+            note: "no compactable range",
+          });
           this.log("idle: no compactable range; nothing replaced", "warn");
           return;
         }
+        writeStatus(session.id, {
+          phase: "done",
+          step: "done",
+          completedAt: Date.now(),
+          shadowedNodes: result.shadowedSeqs.length,
+          shadowedTokens: result.shadowedTokenCount,
+          missingSections: [],
+          retrying: false,
+        });
         this.log(`committed: replaced ${result.shadowedSeqs.length} node(s) (~${result.shadowedTokenCount} tokens) with the handoff checkpoint`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeStatus(agent.session?.id, {
+          phase: "failed",
+          step: "failed",
+          failedAt: Date.now(),
+          error: message,
+          errorCode: errorCodeOf(error),
+        });
+        throw error;
       } finally {
         this.running.delete(agent);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      writeStatus(agent.session?.id, {
+        phase: "failed",
+        step: "failed",
+        failedAt: Date.now(),
+        error: message,
+        errorCode: errorCodeOf(error),
+      });
       this.log(`failed: ${message}`, "warn");
     }
   }
 
+  /**
+   * Wrap the stock transaction so manual /compact and automatic idle
+   * compaction share the same status sidecar. The base method still owns the
+   * surface lock, summarization and commit.
+   */
+  async compactNow(agent, signal, sourceCommandId) {
+    // Manual /compact while the plugin is off stays a stock native compaction:
+    // no handoff template, no plugin status sidecar.
+    if (!this.handoffEnabled()) return super.compactNow(agent, signal, sourceCommandId);
+    const sessionId = agent?.session?.id;
+    let totalTokens;
+    try { totalTokens = this.ctx.tokenMeter.measure(agent.session).totalTokens; } catch { totalTokens = undefined; }
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "prepare",
+      startedAt: Date.now(),
+      timeoutMs: this.handoff.timeoutMs,
+      ...(typeof totalTokens === "number" ? { totalTokens } : {}),
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      error: "",
+      errorCode: "",
+    });
+    try {
+      const result = await super.compactNow(agent, signal, sourceCommandId);
+      writeStatus(sessionId, {
+        phase: "done",
+        step: "done",
+        completedAt: Date.now(),
+        shadowedNodes: Array.isArray(result?.shadowedSeqs) ? result.shadowedSeqs.length : 0,
+        shadowedTokens: typeof result?.shadowedTokenCount === "number" ? result.shadowedTokenCount : 0,
+        missingSections: [],
+        retrying: false,
+        writing: false,
+        ...(result === null || result === undefined ? { note: "no compactable range" } : {}),
+      });
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeStatus(sessionId, {
+        phase: "failed",
+        step: "failed",
+        failedAt: Date.now(),
+        error: message,
+        errorCode: errorCodeOf(error),
+      });
+      throw error;
+    }
+  }
+
   /** Handoff template instead of the stock compaction instruction. */
   async summarize(input, agent, signal) {
+    // Native pressure/overflow compaction runs through this same hook, so the
+    // stock prompt must come back the moment the plugin is switched off.
+    if (!this.handoffEnabled()) return super.summarize(input, agent, signal);
     const latest = agent.session.requestHeader?.()?.config;
     const configured = this.config.summarizationProvider && this.config.summarizationModel
       ? { provider: this.config.summarizationProvider, model: this.config.summarizationModel }
@@ -328,6 +478,13 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       : undefined;
     const target = configured ?? latest ?? agentTarget;
     if (target === undefined) throw new Error("no provider/model available for the handoff summary");
+    // Replaying the prefix only reuses the provider cache when the auxiliary
+    // request carries the same routing knobs as the routed one. Strata writes
+    // the reasoning directive into the prefix, so a missing effort breaks the
+    // cache a few thousand tokens in. Only inherit it when the summary target
+    // is the same model that produced the latest request.
+    const sameTarget = latest !== undefined && target.provider === latest.provider && target.model === latest.model;
+    const reasoningEffort = sameTarget ? latest.reasoningEffort : undefined;
 
     const resolved = this.handoff.instruction === undefined
       ? readTemplate(this.handoff.templateFile, this.handoff.autoCreateTemplate)
@@ -337,40 +494,157 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       : BUILTIN_INSTRUCTION;
     this.log(`template: ${resolved.source}${resolved.text === undefined ? " (fallback)" : ""}`);
 
-    const assembler = new BlockAssembler();
-    const messages = [
+    const expected = expectedSections(instruction);
+    const baseMessages = [
       ...input.messages,
       Object.freeze({ role: "user", content: [{ type: "text", text: instruction }] }),
     ];
-    const options = {
+    const baseOptions = {
       provider: target.provider,
       model: target.model,
-      messages,
       toolHistory: agent.session.toolHistory(),
       ...(input.tools === undefined ? {} : { tools: [...input.tools] }),
       maxTokens: this.config.maxTokens,
+      ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
       sessionId: agent.session.id,
       purpose: "compaction",
       ...(signal === undefined ? {} : { signal }),
     };
+    const sessionId = agent.session?.id;
 
-    for await (const chunk of this.ctx.llm.stream(options)) assembler.push(chunk);
-    const error = finishError(assembler.finish);
-    if (error !== undefined) throw error;
+    let combined = "";
+    let rawOutput = [];
+    let usage;
+    let validation = {
+      ok: expected.length === 0,
+      missing: [...expected],
+      truncated: false,
+      endsWithHeading: false,
+      reason: "not attempted",
+    };
+    const attempts = [];
 
-    const rawOutput = assembler.blocks();
-    if (contentHasImage(rawOutput)) throw new LlmError("handoff summary cannot contain image output", "UNSUPPORTED_CONTENT");
-    const summary = rawOutput.filter((block) => block.type === "text");
-    if (!summary.some((block) => block.text.trim().length > 0)) throw new Error("handoff summary produced no text content");
+    let liveTotalTokens;
+    try { liveTotalTokens = this.ctx.tokenMeter.measure(agent.session).totalTokens; } catch { liveTotalTokens = undefined; }
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "summary",
+      summaryAttempt: 1,
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      ...(typeof liveTotalTokens === "number" ? { totalTokens: liveTotalTokens } : {}),
+    });
+
+    for (let attempt = 1; attempt <= MAX_SUMMARY_ATTEMPTS; attempt += 1) {
+      signal?.throwIfAborted?.();
+      const messages = attempt === 1
+        ? baseMessages
+        : attempt === 2
+          ? [
+            ...baseMessages,
+            Object.freeze({ role: "assistant", content: [{ type: "text", text: combined }] }),
+            Object.freeze({ role: "user", content: [{ type: "text", text: continuationInstruction(validation) }] }),
+          ]
+          : [
+            ...baseMessages,
+            Object.freeze({
+              role: "user",
+              content: [{ type: "text", text: rewriteInstruction(validation, this.config.maxTokens) }],
+            }),
+          ];
+
+      const result = await this.runSummaryRequest(baseOptions, messages);
+      const truncatedNow = looksTruncated(result.text);
+      const clean = stripTruncationMarkers(result.text);
+      combined = attempt === 1
+        ? clean
+        : attempt === 2
+          ? mergeSummary(combined, clean)
+          : clean;
+      rawOutput = result.rawOutput;
+      usage = mergeUsage(usage, result.usage);
+      validation = validateSummary(combined, expected);
+      if (truncatedNow) {
+        validation = {
+          ...validation,
+          ok: false,
+          truncated: true,
+          reason: validation.reason.length > 0 ? `${validation.reason}; truncation marker` : "truncation marker",
+        };
+      }
+      attempts.push({
+        attempt,
+        finish: result.finishKind,
+        chars: result.text.length,
+        ok: validation.ok,
+      });
+      if (validation.ok) break;
+      if (attempt < MAX_SUMMARY_ATTEMPTS) {
+        const next = attempt + 1;
+        this.log(`summary incomplete after attempt ${attempt}: ${validation.reason}; ${attempt === 1 ? "continuing" : "rewriting"}`);
+        writeStatus(sessionId, {
+          phase: "running",
+          step: "summary",
+          summaryAttempt: next,
+          retrying: true,
+          writing: next === MAX_SUMMARY_ATTEMPTS,
+          missingSections: validation.missing,
+          summaryChars: combined.length,
+          summaryAttempts: attempts,
+        });
+      }
+    }
+
+    if (!validation.ok) {
+      const error = new Error(`handoff summary incomplete after ${attempts.length} attempt(s): ${validation.reason}`);
+      error.code = "INCOMPLETE_SUMMARY";
+      error.attempts = attempts;
+      throw error;
+    }
+
+    const finalText = combined.trim();
+    if (finalText.length === 0) throw new Error("handoff summary produced no text content");
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "commit",
+      summaryAttempt: attempts.length,
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      summaryChars: finalText.length,
+      summaryAttempts: attempts,
+    });
 
     return {
-      summary,
+      summary: [{ type: "text", text: finalText }],
       rawOutput,
       llmStreamCall: true,
       provider: target.provider,
       model: target.model,
       maxTokens: this.config.maxTokens,
-      ...(assembler.usage === undefined ? {} : { usage: assembler.usage }),
+      ...(usage === undefined ? {} : { usage }),
+    };
+  }
+
+  /** One summary LLM call; max-tokens is returned as a partial, not thrown. */
+  async runSummaryRequest(baseOptions, messages) {
+    const assembler = new BlockAssembler();
+    for await (const chunk of this.ctx.llm.stream({ ...baseOptions, messages })) assembler.push(chunk);
+    const finish = assembler.finish ?? { kind: "stop" };
+    if (finish.kind === "error" || finish.kind === "aborted") {
+      const error = finishError(finish);
+      if (error !== undefined) throw error;
+    }
+    const rawOutput = assembler.blocks();
+    if (contentHasImage(rawOutput)) throw new LlmError("handoff summary cannot contain image output", "UNSUPPORTED_CONTENT");
+    const text = rawOutput.filter((block) => block.type === "text").map((block) => block.text).join("");
+    if (text.trim().length === 0) throw new Error("handoff summary produced no text content");
+    return {
+      rawOutput,
+      text,
+      finishKind: finish.kind,
+      usage: assembler.usage,
     };
   }
 }

package/lib/status.js

@@ -0,0 +1,52 @@
+/**
+ * Per-session compaction status sidecar.
+ *
+ * The engine writes one small JSON file while it prepares, summarizes and
+ * commits a handoff; the UI dock polls it through the companion package's RPC
+ * channel. Kept free of DSH imports so the UI's node half can reuse it.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const STATUS_DIR = process.env.DSH_HANDOFF_STATUS_DIR || join(homedir(), ".dsh-handoff-compaction", "status");
+const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Absolute status file for a session id, or undefined when the id is unsafe. */
+export function statusFileFor(sessionId) {
+  if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId)) return undefined;
+  return join(STATUS_DIR, `${sessionId}.json`);
+}
+
+/** Latest status for a session, or undefined when absent/unreadable. */
+export function readStatus(sessionId) {
+  const file = statusFileFor(sessionId);
+  if (file === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Merge one patch into the session status and replace the file atomically.
+ * Returns false when the session id is unsafe or the write failed; status
+ * writes must never break a compaction.
+ */
+export function writeStatus(sessionId, patch) {
+  const file = statusFileFor(sessionId);
+  if (file === undefined || patch === undefined || patch === null) return false;
+  try {
+    mkdirSync(STATUS_DIR, { recursive: true });
+    const previous = readStatus(sessionId) ?? {};
+    const next = { ...previous, ...patch, sessionId, updatedAt: Date.now() };
+    const temp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    writeFileSync(temp, JSON.stringify(next), "utf8");
+    renameSync(temp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/summary.js

@@ -0,0 +1,147 @@
+/**
+ * Pure completeness checks for the generated handoff document.
+ *
+ * The local models used with DSH sometimes stop early and append a literal
+ * "（截断）" marker (or stop right after a heading) instead of failing the
+ * request. These helpers let the engine treat such output as incomplete,
+ * continue it, or rewrite it before the checkpoint is committed.
+ */
+
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^\s*(#{2,3})\s+(.+?)\s*$/;
+
+function normalizeHeading(text) {
+  return String(text ?? "")
+    .replace(/^#{2,3}\s*/, "")
+    .replace(/^\s*\d+[.、)]\s*/, "")
+    .replace(/[*_`]/g, "")
+    .replace(/[\s：:]+$/g, "")
+    .trim();
+}
+
+function headingsIn(text) {
+  const out = [];
+  let fenced = false;
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    if (FENCE.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    const match = HEADING.exec(line);
+    if (match === null) continue;
+    const heading = normalizeHeading(match[2]);
+    if (heading.length > 0 && !out.includes(heading)) out.push(heading);
+  }
+  return out;
+}
+
+/** Section headings the template asks the model to produce. */
+export function expectedSections(templateText) {
+  return headingsIn(templateText);
+}
+
+/** Section headings actually present in a generated summary. */
+export function summarySections(summaryText) {
+  return headingsIn(summaryText);
+}
+
+/** Whether the text ends with a model-generated truncation marker. */
+export function looksTruncated(text) {
+  const tail = String(text ?? "").trimEnd();
+  if (tail.length === 0) return false;
+  if (/[（(]\s*截断\s*[)）]\s*$/.test(tail)) return true;
+  if (/[\[【]\s*截断\s*[\]】]\s*$/.test(tail)) return true;
+  const last = tail.slice(-48);
+  return /(?:输出|回答|摘要|文档|内容|响应)\s*(?:已|被)?\s*截断\s*$/.test(last);
+}
+
+/** Remove literal truncation markers the model wrote about its own output. */
+export function stripTruncationMarkers(text) {
+  return String(text ?? "")
+    .replace(/[…\.]{0,3}\s*[（(]\s*截断\s*[)）]/g, "")
+    .replace(/[…\.]{0,3}\s*[\[【]\s*截断\s*[\]】]/g, "")
+    .trimEnd();
+}
+
+/**
+ * Validate one generated handoff document against the template sections.
+ * `ok` is false when a section is missing, the text ends on a bare heading,
+ * or the model marked its own output as truncated.
+ */
+export function validateSummary(text, expected = []) {
+  const headings = headingsIn(text);
+  const missing = expected.filter(
+    (section) => !headings.some((heading) => heading.includes(section) || section.includes(heading)),
+  );
+  const truncated = looksTruncated(text);
+  const endsWithHeading = /(?:^|\n)\s*#{2,3}\s+[^\n]*\s*$/.test(String(text ?? "").trimEnd());
+  const reasons = [];
+  if (missing.length > 0) reasons.push(`missing sections: ${missing.join(", ")}`);
+  if (truncated) reasons.push("truncation marker");
+  if (endsWithHeading) reasons.push("ends on a heading");
+  return {
+    ok: missing.length === 0 && !truncated && !endsWithHeading,
+    missing,
+    truncated,
+    endsWithHeading,
+    reason: reasons.join("; "),
+  };
+}
+
+function lastHeading(text) {
+  const headings = headingsIn(text);
+  return headings.length === 0 ? undefined : headings[headings.length - 1];
+}
+
+function startsWithHeading(text) {
+  const first = String(text ?? "").trimStart().split(/\r?\n/, 1)[0] ?? "";
+  const match = HEADING.exec(first);
+  return match === null ? undefined : normalizeHeading(match[2]);
+}
+
+/** Join a partial summary and a continuation without duplicating its heading. */
+export function mergeSummary(partial, tail) {
+  const head = String(partial ?? "").trimEnd();
+  const rest = String(tail ?? "").trim();
+  if (head.length === 0) return rest;
+  if (rest.length === 0) return head;
+  const repeated = lastHeading(head);
+  const first = startsWithHeading(rest);
+  if (repeated !== undefined && first !== undefined && repeated === first) {
+    const newline = rest.indexOf("\n");
+    const body = newline === -1 ? "" : rest.slice(newline + 1).trim();
+    return body.length === 0 ? head : `${head}\n${body}`;
+  }
+  if (first !== undefined) return `${head}\n\n${rest}`;
+  const safeBreak = /[。！？.!?；;：:)\]）】]$/.test(head);
+  return safeBreak ? `${head}\n\n${rest}` : `${head}${rest}`;
+}
+
+/** User turn appended after the partial assistant document. */
+export function continuationInstruction(validation) {
+  const missing = validation?.missing ?? [];
+  const lines = [
+    "你刚才写到一半中断了。请从断点继续这份交接文档：",
+    "- 先补完断点处的句子，不要重复已经写过的内容或标题；",
+  ];
+  if (missing.length > 0) {
+    lines.push(`- 然后按模板顺序补完这些缺失小节：${missing.join("、")}；`);
+  } else {
+    lines.push("- 并完成文档剩余部分；");
+  }
+  lines.push("- 只输出 Markdown 正文，不要解释，不要写「（截断）」。");
+  return lines.join("\n");
+}
+
+/** User turn appended when a continuation still does not pass validation. */
+export function rewriteInstruction(validation, maxTokens) {
+  const missing = validation?.missing ?? [];
+  const why = missing.length > 0 ? `缺少这些小节：${missing.join("、")}` : "输出在末尾被截断";
+  return [
+    `上一次的交接文档不完整（${why}）。`,
+    "请重新完整输出整份交接文档，必须包含模板要求的全部小节；",
+    `不要因为长度自行截断，不要写「（截断）」；本任务允许输出到 ${String(maxTokens)} tokens。`,
+    "只输出 Markdown 正文。",
+  ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-auto-compaction",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -40,5 +40,8 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

package/scripts/preset-scope.mjs

@@ -2,42 +2,141 @@
  * preset-scope.mjs — switch an editable DSH preset between the handoff plugin and
  * DSH's native compaction, reversibly.
  *
- * A preset context can only have ONE provider of `ctx.compaction`, so "native off"
- * means "which row is active". The script replaces a marker-delimited slot in the
- * preset's cordis.patch.yml with either row file, validates the resulting YAML, and
- * keeps a .bak-scope copy. Disabling restores the stock row (`auto: true`), so a
- * preset goes back to DSH native compaction the moment the plugin is switched off.
+ * Two layers must agree for "native off" to be real:
+ *   1. the preset's marker-delimited compaction slot (the row that supplies
+ *      `ctx.compaction` inside the preset group), and
+ *   2. the profile-level root `compaction-basic` node (DSH's default engine,
+ *      which also listens on `agent/pre-step` and can compact before the
+ *      preset's isolated plugin is consulted).
+ *
+ * Layer 1 is replaced wholesale between row-plugin.yml and row-native.yml.
+ * Layer 2 is guarded by a marker comment that sets `auto: false` while the
+ * plugin is enabled and is removed on disable, restoring the stock default.
+ *
+ * Without --preset/--all-local, `enable` reads the plugin settings sidecar:
+ * `scope: "preset"` switches exactly the listed preset ids to the plugin and
+ * resets every other editable preset to native; `scope: "global"` switches all.
+ * `disable` restores native everywhere. The root guard is on only while at
+ * least one preset uses the plugin.
  *
  * Usage:
- *   node scripts/preset-scope.mjs status  [--preset <cordis.patch.yml>] [--all-local]
- *   node scripts/preset-scope.mjs enable  [--preset <cordis.patch.yml>] [--all-local]
- *   node scripts/preset-scope.mjs disable [--preset <cordis.patch.yml>] [--all-local]
+ *   node scripts/preset-scope.mjs status  [--preset <cordis.patch.yml>] [--profile-patch <cordis.patch.yml>] [--all-local] [--skip-profile]
+ *   node scripts/preset-scope.mjs enable  [--preset <cordis.patch.yml>] [--profile-patch <cordis.patch.yml>] [--all-local] [--skip-profile]
+ *   node scripts/preset-scope.mjs disable [--preset <cordis.patch.yml>] [--profile-patch <cordis.patch.yml>] [--all-local] [--skip-profile]
  * Restart DSH afterwards.
  */
 import fs from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_PRESET = "C:/Users/Me/.dsh-local-pkgs/dsh-preset-lightweight-local/cordis.patch.yml";
-const LOCAL_PKGS = "C:/Users/Me/.dsh-local-pkgs";
+const APP_DATA = process.env.APPDATA ?? path.join(homedir(), "AppData", "Roaming");
+const DEFAULT_PROFILE_PATCH = process.env.DSH_PROFILE_PATCH
+  ?? path.join(APP_DATA, "dsh-desktop", "harness", "profiles", "web", "cordis.patch.yml");
+const DEFAULT_SETTINGS = path.join(homedir(), ".dsh-handoff-compaction", "settings.json");
+const LOCAL_PKGS = process.env.DSH_LOCAL_PKGS ?? path.join(homedir(), ".dsh-local-pkgs");
+const SETTINGS_FILE = process.env.DSH_HANDOFF_SETTINGS_FILE ?? DEFAULT_SETTINGS;
 const SLOT_BEGIN = "# >>> handoff:slot:begin";
 const SLOT_END = "# <<< handoff:slot:end";
+const GUARD_BEGIN = "# >>> handoff:native-guard:begin";
+const GUARD_END = "# <<< handoff:native-guard:end";
 const ROW_INDENT = 14;
 
 const argv = process.argv.slice(2);
 const mode = (argv.find((a) => !a.startsWith("--")) ?? "status").toLowerCase();
 const presetArg = argv.indexOf("--preset");
+const profileArg = argv.indexOf("--profile-patch");
 const allLocal = argv.includes("--all-local");
+const skipProfile = argv.includes("--skip-profile");
+const profilePatch = profileArg >= 0
+  ? argv[profileArg + 1]
+  : (process.env.DSH_PROFILE_PATCH ?? DEFAULT_PROFILE_PATCH);
+
+function readSettings() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function presetIdOf(text) {
+  const yaml = loadYaml();
+  if (yaml === undefined) return undefined;
+  try {
+    const doc = yaml.load(text, { schema: yamlSchema(yaml) });
+    return doc?.[0]?.insert?.[0]?.config?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every editable local preset that carries the handoff slot markers. */
+function discoverPresetFiles() {
+  if (!fs.existsSync(LOCAL_PKGS)) return [];
+  return fs.readdirSync(LOCAL_PKGS)
+    .map((name) => path.join(LOCAL_PKGS, name, "cordis.patch.yml"))
+    .filter((file) => fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(SLOT_BEGIN));
+}
 
-function targets() {
-  if (allLocal) {
-    return fs.readdirSync(LOCAL_PKGS)
-      .map((name) => path.join(LOCAL_PKGS, name, "cordis.patch.yml"))
-      .filter((file) => fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(SLOT_BEGIN));
+function defaultPresetFile() {
+  return discoverPresetFiles()[0]
+    ?? path.join(LOCAL_PKGS, "dsh-preset-lightweight-local", "cordis.patch.yml");
+}
+
+/**
+ * Rows to apply. `enable: true` means the plugin takes this preset; `false`
+ * restores its own native row. Non-selected presets are reset to native so a
+ * previous switch cannot leak into a preset the user did not select.
+ */
+function selection(action) {
+  if (presetArg >= 0) {
+    return [{ file: argv[presetArg + 1], enable: action === "enable" }];
+  }
+  const files = discoverPresetFiles();
+  if (action === "disable") return files.map((file) => ({ file, enable: false }));
+  if (allLocal) return files.map((file) => ({ file, enable: true }));
+  const settings = readSettings();
+  if (settings?.scope === "global") return files.map((file) => ({ file, enable: true }));
+  if (settings?.scope === "preset") {
+    const selected = new Set(Array.isArray(settings.presets) ? settings.presets : []);
+    const planned = files.map((file) => {
+      const id = presetIdOf(fs.readFileSync(file, "utf8"));
+      return { file, id, enable: id !== undefined && selected.has(id) };
+    });
+    for (const id of selected) {
+      if (!planned.some((entry) => entry.id === id)) {
+        console.error(`warn: selected preset "${id}" has no editable handoff slot; left native`);
+      }
+    }
+    return planned;
   }
-  return [presetArg >= 0 ? argv[presetArg + 1] : DEFAULT_PRESET];
+  return [{ file: defaultPresetFile(), enable: action === "enable" }];
+}
+
+function statusPlan() {
+  if (presetArg >= 0) return [{ file: argv[presetArg + 1] }];
+  const settings = readSettings();
+  const files = discoverPresetFiles();
+  if (settings?.scope === "global") return files.map((file) => ({ file, selected: true }));
+  if (settings?.scope === "preset") {
+    const selected = new Set(Array.isArray(settings.presets) ? settings.presets : []);
+    return files.map((file) => ({ file, selected: selected.has(presetIdOf(fs.readFileSync(file, "utf8"))) }));
+  }
+  return [{ file: defaultPresetFile() }];
+}
+
+function pluginRow(presetId) {
+  const text = fs.readFileSync(path.join(HERE, "row-plugin.yml"), "utf8");
+  const trace = path.join(homedir(), ".dsh-handoff-compaction", "trace.log").replace(/\\/g, "/");
+  const withId = (presetId === undefined
+    ? text
+    : text.replace(/^(\s*presetId:\s*).*$/m, `$1${presetId}`))
+    .replace(/^(\s*traceFile:\s*).*$/m, `$1"${trace}"`);
+  return indentRow(withId);
 }
 
 function indentRow(text) {
@@ -47,23 +146,43 @@ function indentRow(text) {
 
 function loadYaml() {
   try {
-    return createRequire("C:/Users/Me/AppData/Roaming/dsh-desktop/harness/profiles/web/")("js-yaml");
+    return createRequire(import.meta.url)("js-yaml");
+  } catch {
+    // The engine's own dependency is preferred; a profile-installed copy is the fallback.
+  }
+  try {
+    const profileRoot = path.join(APP_DATA, "dsh-desktop", "harness", "profiles", "web");
+    return createRequire(path.join(profileRoot, "package.json"))("js-yaml");
   } catch {
     return undefined;
   }
 }
 
-function validate(text) {
+function yamlSchema(yaml) {
+  const jsTag = new yaml.Type("tag:yaml.org,2002:js", { kind: "scalar", construct: (d) => d });
+  return yaml.DEFAULT_SCHEMA.extend([jsTag]);
+}
+
+function validatePreset(text) {
   const yaml = loadYaml();
   if (yaml === undefined) return "skipped (js-yaml unavailable)";
-  const jsTag = new yaml.Type("tag:yaml.org,2002:js", { kind: "scalar", construct: (d) => d });
-  const doc = yaml.load(text, { schema: yaml.DEFAULT_SCHEMA.extend([jsTag]) });
+  const doc = yaml.load(text, { schema: yamlSchema(yaml) });
   const group = doc[0].insert[0].config.plugins.find((entry) => entry.id === "compaction");
   const rows = group.config.filter((entry) => entry.id === "compaction-basic");
   if (rows.length !== 1) throw new Error(`expected exactly one compaction-basic row, found ${rows.length}`);
   return `ok -> ${rows[0].name}`;
 }
 
+function validateProfile(text) {
+  const yaml = loadYaml();
+  if (yaml === undefined) return "skipped (js-yaml unavailable)";
+  const doc = yaml.load(text, { schema: yamlSchema(yaml) });
+  if (!Array.isArray(doc)) throw new Error("profile patch: expected a top-level array");
+  const row = doc.find((entry) => entry?.id === "compaction-basic" && entry?.name === "@deepseek-ai/dsh-compaction-basic");
+  if (row === undefined) throw new Error("profile patch: native compaction-basic entry not found");
+  return `ok -> ${row.name}, auto=${row.config?.auto === undefined ? "default" : String(row.config.auto)}`;
+}
+
 function slotBounds(lines) {
   const begin = lines.findIndex((line) => line.includes(SLOT_BEGIN));
   const end = lines.findIndex((line) => line.includes(SLOT_END));
@@ -81,7 +200,148 @@ function activeName(lines) {
   return "unknown";
 }
 
-for (const file of targets()) {
+/** Locate the top-level native compaction-basic entry that carries a name + config. */
+function nativeBounds(lines) {
+  const starts = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^-\s+id:\s*compaction-basic\s*$/.test(lines[i])) starts.push(i);
+  }
+  for (let index = 0; index < starts.length; index += 1) {
+    const start = starts[index];
+    const end = index + 1 < starts.length ? starts[index + 1] : lines.length;
+    const block = lines.slice(start, end).join("\n");
+    if (/name:\s*["']?@deepseek-ai\/dsh-compaction-basic["']?/.test(block) && /^\s{2}config:\s*$/m.test(block)) {
+      return { start, end };
+    }
+  }
+  return undefined;
+}
+
+function configLine(lines, bounds) {
+  for (let i = bounds.start + 1; i < bounds.end; i += 1) {
+    if (/^\s{2}config:\s*$/.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+function guardBounds(lines, bounds) {
+  let begin = -1;
+  let end = -1;
+  for (let i = bounds.start; i < bounds.end; i += 1) {
+    if (lines[i].includes(GUARD_BEGIN)) begin = i;
+    if (lines[i].includes(GUARD_END)) end = i;
+  }
+  return begin >= 0 && end > begin ? { begin, end } : undefined;
+}
+
+function autoLine(lines, configIdx, bounds) {
+  for (let i = configIdx + 1; i < bounds.end; i += 1) {
+    if (/^- /.test(lines[i])) break;
+    if (/^\s{2}[A-Za-z]/.test(lines[i])) break;
+    if (/^\s{4}auto:\s*/.test(lines[i])) return i;
+  }
+  return -1;
+}
+
+function guardState(lines, bounds) {
+  const cfg = configLine(lines, bounds);
+  if (cfg < 0) return "no config";
+  const guard = guardBounds(lines, bounds);
+  if (guard !== undefined) {
+    const hasFalse = lines.slice(guard.begin + 1, guard.end).some((line) => /^\s*auto:\s*false\s*$/.test(line));
+    return hasFalse ? "auto:false (plugin guard)" : "guarded (auto missing!)";
+  }
+  const auto = autoLine(lines, cfg, bounds);
+  return auto < 0 ? "absent (default true)" : `auto:${lines[auto].split(":")[1].trim()}`;
+}
+
+function editProfilePatch(file, action) {
+  if (!fs.existsSync(file)) {
+    console.error(`skip (missing profile patch): ${file}`);
+    return;
+  }
+  const original = fs.readFileSync(file, "utf8");
+  const lines = original.split(/\r?\n/);
+  const bounds = nativeBounds(lines);
+  if (bounds === undefined) {
+    console.error(`skip (no native compaction-basic entry): ${file}`);
+    return;
+  }
+  const cfg = configLine(lines, bounds);
+  if (cfg < 0) {
+    console.error(`skip (native entry has no config block): ${file}`);
+    return;
+  }
+  const guard = guardBounds(lines, bounds);
+  let nextLines = [...lines];
+
+  if (action === "enable") {
+    if (guard !== undefined) {
+      const hasAuto = nextLines.slice(guard.begin + 1, guard.end).some((line) => /^\s*auto:\s*/.test(line));
+      nextLines = nextLines.map((line, index) => (index > guard.begin && index < guard.end && /^\s*auto:\s*/.test(line)
+        ? line.replace(/^(\s*)auto:\s*.*$/, "$1auto: false")
+        : line));
+      if (!hasAuto) nextLines.splice(guard.begin + 1, 0, "    auto: false");
+    } else {
+      const auto = autoLine(nextLines, cfg, bounds);
+      if (auto >= 0) {
+        nextLines[auto] = nextLines[auto].replace(/^(\s*)auto:\s*.*$/, "$1auto: false");
+      } else {
+        nextLines.splice(cfg + 1, 0,
+          "    " + GUARD_BEGIN,
+          "    auto: false",
+          "    " + GUARD_END);
+      }
+    }
+  } else {
+    if (guard !== undefined) {
+      nextLines.splice(guard.begin, guard.end - guard.begin + 1);
+    } else {
+      const auto = autoLine(nextLines, cfg, bounds);
+      if (auto >= 0) nextLines[auto] = nextLines[auto].replace(/^(\s*)auto:\s*.*$/, "$1auto: true");
+    }
+  }
+
+  const next = nextLines.join("\n");
+  if (next === original) {
+    console.log(`${file}\n  -> native ${action === "enable" ? "auto:false" : "auto:true"}  [no change]`);
+    return;
+  }
+  const verdict = validateProfile(next);
+  if (!verdict.startsWith("ok")) {
+    console.error(`aborted (validation): ${verdict}`);
+    process.exitCode = 1;
+    return;
+  }
+  fs.copyFileSync(file, `${file}.bak-scope`);
+  fs.writeFileSync(file, next);
+  console.log(`${file}\n  -> native ${action === "enable" ? "auto:false" : "auto:true"}  [${verdict}]`);
+}
+
+function profileStatus() {
+  if (skipProfile) return;
+  if (!fs.existsSync(profilePatch)) {
+    console.log(`${profilePatch}\n  missing`);
+    return;
+  }
+  const original = fs.readFileSync(profilePatch, "utf8");
+  const lines = original.split(/\r?\n/);
+  const bounds = nativeBounds(lines);
+  if (bounds === undefined) {
+    console.log(`${profilePatch}\n  native compaction-basic entry not found`);
+    return;
+  }
+  console.log(`${profilePatch}\n  原生守卫: ${guardState(lines, bounds)}\n  YAML: ${validateProfile(original)}`);
+}
+
+if (mode !== "status" && mode !== "enable" && mode !== "disable") {
+  console.error("usage: preset-scope.mjs <status|enable|disable> [--preset <file>] [--profile-patch <file>] [--all-local] [--skip-profile]");
+  process.exit(2);
+}
+
+const plan = mode === "status" ? statusPlan() : selection(mode);
+for (const entry of plan) {
+  const file = entry.file;
   if (!fs.existsSync(file)) {
     console.error(`skip (missing): ${file}`);
     continue;
@@ -96,27 +356,37 @@ for (const file of targets()) {
 
   if (mode === "status") {
     const current = activeName(lines);
-    const kind = current === "dsh-handoff-compaction" ? "插件接管（原生关闭）"
+    const kind = current === "dsh-handoff-compaction" || current === "dsh-auto-compaction" ? "插件接管（原生关闭）"
       : current === "@deepseek-ai/dsh-compaction-basic" ? "DSH 原生压缩"
       : "未知";
-    console.log(`${file}\n  当前: ${current}\n  含义: ${kind}\n  YAML: ${validate(original)}`);
+    const selected = entry.selected === undefined ? "" : `\n  勾选: ${entry.selected ? "是（插件）" : "否（原生）"}`;
+    const switchLine = readSettings()?.enabled === false
+      ? "\n  开关: 已停用（设置页关闭，运行时压缩交回原生行为）"
+      : "\n  开关: 启用";
+    console.log(`${file}\n  当前: ${current}\n  含义: ${kind}${selected}${switchLine}\n  YAML: ${validatePreset(original)}`);
     continue;
   }
 
-  if (mode !== "enable" && mode !== "disable") {
-    console.error("usage: preset-scope.mjs <status|enable|disable> [--preset <file>] [--all-local]");
-    process.exit(2);
+  const id = presetIdOf(original);
+  if (entry.enable && id === undefined) {
+    console.error(`skip (cannot read preset id): ${file}`);
+    continue;
   }
-
-  const rowFile = path.join(HERE, mode === "enable" ? "row-plugin.yml" : "row-native.yml");
-  const row = indentRow(fs.readFileSync(rowFile, "utf8"));
+  const row = entry.enable
+    ? pluginRow(id)
+    : indentRow(fs.readFileSync(path.join(HERE, "row-native.yml"), "utf8"));
   const next = [
     ...lines.slice(0, bounds.begin + 1),
     ...row,
     ...lines.slice(bounds.end),
   ].join("\n");
 
-  const verdict = validate(next);
+  if (next === original) {
+    console.log(`${file}\n  -> ${activeName(lines)}  [no change]`);
+    continue;
+  }
+
+  const verdict = validatePreset(next);
   if (!verdict.startsWith("ok")) {
     console.error(`aborted (validation): ${verdict}`);
     process.exit(1);
@@ -126,4 +396,14 @@ for (const file of targets()) {
   console.log(`${file}\n  -> ${activeName(next.split(/\r?\n/))}  [${verdict}]`);
 }
 
-if (mode === "enable" || mode === "disable") console.log("重启 DSH 后生效。");
+if (mode === "status") {
+  profileStatus();
+} else {
+  // The root guard only disables DSH's profile-level duplicate engine. Each
+  // preset's own compaction row stays native unless the plan selected it, so
+  // this is not "native off for every preset".
+  const anyPlugin = plan.some((entry) => entry.enable);
+  if (!skipProfile) editProfilePatch(profilePatch, mode === "enable" && anyPlugin ? "enable" : "disable");
+  if (mode === "enable" && !anyPlugin) console.error("warn: no selected preset uses the plugin; root native fallback left on");
+  console.log("重启 DSH 后生效。");
+}

package/scripts/row-plugin.yml

@@ -3,8 +3,8 @@
   config:
     thresholdRatio: 0.9
     headroomTokens: 10000
-    maxTokens: 8192
+    maxTokens: 12288
     idleDelayMs: 1500
     dryRun: false
     presetId: lightweight-local
-    traceFile: "C:/Users/Me/.dsh-handoff-work/trace.log"
+    traceFile: ""