evolcore 0.0.32 → 0.0.34

package/dist/core/permission/tool-canonical.js

@@ -0,0 +1,226 @@
+/**
+ * tool-canonical.ts — runner-agnostic canonical tool name mapping
+ *
+ * Different runners surface the same capability under different names:
+ *
+ *   canonical   ← runner aliases
+ *   ─────────────────────────────────────────────────────────────────
+ *   Bash        ← Shell (Codex), exec_command (Codex legacy)
+ *   Write       ← FileChange (new-file intent, Codex)
+ *   Edit        ← FileChange (patch intent, Codex), apply_patch (Codex)
+ *   Read        ← read_file (Codex legacy)
+ *
+ * All policy enforcement (system-session modules, evaluateToolPreflight,
+ * checkReadonly) should call canonicalToolName() once at the entry point
+ * and operate on the result, rather than handling runner-specific aliases
+ * scattered throughout.
+ *
+ * D1-A: FileChange / apply_patch require the tool input to distinguish
+ * Write vs Edit intent; the mapping function accepts an optional `input`
+ * parameter for that purpose.
+ *
+ * canonicalToolCall() goes one step further and also normalises the input:
+ * every runner's write shape (Claude/ecagent file_path, Codex fileChanges,
+ * standalone or shell-wrapped apply_patch) yields the same list of write
+ * targets, so policy modules never read runner-specific input fields.
+ */
+import { parseApplyPatchDocument, parseShellApplyPatchInvocation, } from './ec-command-parser.js';
+/**
+ * Normalise a runner-specific tool name to its canonical form.
+ *
+ * This is a projection of canonicalToolCall(): both read the same
+ * `resolveToolIntent` result, so a name-only caller can never disagree with a
+ * caller that judges operands. Pass `input` when the runner tool name alone is
+ * ambiguous (FileChange, apply_patch, and shell-carried apply_patch).
+ */
+export function canonicalToolName(toolName, input) {
+    const intent = resolveToolIntent(toolName, input);
+    switch (intent.access) {
+        case 'write':
+        case 'read':
+            return intent.name;
+        case 'shell':
+            return 'Bash';
+        default:
+            return toolName;
+    }
+}
+/**
+ * Returns true iff the canonical name represents a shell execution tool.
+ * Consolidates the ad-hoc `isShellTool` checks spread across runners.
+ */
+export function isShellToolName(toolName) {
+    const canon = canonicalToolName(toolName);
+    return canon === 'Bash';
+}
+/**
+ * Returns true iff the canonical name represents a file-write tool.
+ * Used by system-session modules and readonly checks.
+ */
+export function isWriteToolName(toolName, input) {
+    return canonicalToolCall(toolName, input).access === 'write';
+}
+// ── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Codex FileChange intent: if fileChanges contains an apply-patch style entry
+ * (has an `oldContent` / `patch` key) it is Edit; otherwise Write.
+ */
+function resolveFileChangeName(input) {
+    if (!input)
+        return 'Write'; // conservative fallback
+    const changes = input.fileChanges;
+    if (!Array.isArray(changes) || changes.length === 0)
+        return 'Write';
+    const first = changes[0];
+    if (first && typeof first === 'object') {
+        const obj = first;
+        // A patch/edit operation carries 'patch', 'oldContent', or 'type': 'edit'
+        if ('patch' in obj || 'oldContent' in obj || obj.type === 'edit')
+            return 'Edit';
+    }
+    return 'Write';
+}
+/**
+ * apply_patch: if the patch string starts with '--- ' or 'diff ' it is an
+ * edit; otherwise (e.g. a full file replacement) treat as Write.
+ */
+function resolveApplyPatchName(input) {
+    if (!input)
+        return 'Edit'; // apply_patch is most commonly a diff edit
+    const patch = typeof input.patch === 'string' ? input.patch : '';
+    if (patch.startsWith('--- ') || patch.startsWith('diff '))
+        return 'Edit';
+    return 'Write';
+}
+const READ_TOOL_NAMES = new Set(['Read', 'Glob', 'Grep']);
+/** Keys a write tool may carry its target in (Claude / ecagent file tools). */
+const FILE_WRITE_PATH_KEYS = ['file_path', 'notebook_path', 'path'];
+/** Keys a standalone apply_patch call may carry its patch document in. */
+const APPLY_PATCH_DOCUMENT_KEYS = ['patch', 'input', 'command'];
+/** Runner tool names that mean "shell". */
+const SHELL_TOOL_NAMES = new Set(['Shell', 'exec_command']);
+/**
+ * The single place that decides what a tool call is. Every public helper here
+ * projects this result, so no two callers can classify the same call
+ * differently. `paths` is only populated for `write`; read scope stays with
+ * checkReadonly, which owns the Glob/Grep rules.
+ */
+function resolveToolIntent(toolName, input = {}) {
+    if (toolName === 'FileChange') {
+        const paths = [];
+        if (typeof input.grantRoot === 'string' && input.grantRoot)
+            paths.push(input.grantRoot);
+        collectFileChangePaths(input.fileChanges, paths);
+        return { access: 'write', name: resolveFileChangeName(input), via: 'tool', paths: unique(paths) };
+    }
+    if (toolName === 'apply_patch') {
+        return applyPatchCall(standaloneApplyPatchChanges(input), 'tool');
+    }
+    if (toolName === 'Bash' || SHELL_TOOL_NAMES.has(toolName)) {
+        const parsed = parseShellApplyPatchInvocation(input);
+        if (parsed.kind === 'file-change')
+            return applyPatchCall(parsed.fileChanges, 'shell');
+        // A recognised but malformed apply_patch is still a write attempt.
+        if (parsed.kind === 'invalid')
+            return { access: 'write', name: 'Edit', via: 'shell', paths: [] };
+        return { access: 'shell', name: 'Bash' };
+    }
+    // read_file is Codex's legacy read alias; Claude / ecagent use the name directly.
+    const name = toolName === 'read_file' ? 'Read' : toolName;
+    if (READ_TOOL_NAMES.has(name))
+        return { access: 'read', name: name };
+    if (name === 'Write' || name === 'Edit' || name === 'MultiEdit' || name === 'NotebookEdit') {
+        const paths = [];
+        for (const key of FILE_WRITE_PATH_KEYS) {
+            if (typeof input[key] === 'string' && input[key])
+                paths.push(input[key]);
+        }
+        return { access: 'write', name: name === 'Write' ? 'Write' : 'Edit', via: 'tool', paths: unique(paths) };
+    }
+    return { access: 'other', name: toolName };
+}
+export function canonicalToolCall(toolName, input = {}) {
+    return resolveToolIntent(toolName, input);
+}
+function applyPatchCall(changes, via) {
+    if (!changes || changes.length === 0)
+        return { access: 'write', name: 'Edit', via, paths: [] };
+    const name = changes.every(change => change.kind === 'add') ? 'Write' : 'Edit';
+    return { access: 'write', name, via, paths: unique(applyPatchChangePaths(changes)) };
+}
+/**
+ * A standalone apply_patch call is only accepted when every key that carries a
+ * patch document parses to the same change set; otherwise the paths approved
+ * here might not be the ones the runner applies.
+ */
+function standaloneApplyPatchChanges(input) {
+    let found;
+    let signature;
+    for (const key of APPLY_PATCH_DOCUMENT_KEYS) {
+        const value = input[key];
+        if (typeof value !== 'string' || !value.trim())
+            continue;
+        const changes = parseApplyPatchDocument(value);
+        if (!changes)
+            return undefined;
+        const next = JSON.stringify(changes);
+        if (signature !== undefined && signature !== next)
+            return undefined;
+        signature = next;
+        found = changes;
+    }
+    return found;
+}
+function unique(paths) {
+    return [...new Set(paths)];
+}
+// ── Write-target extraction shared with tool-policy ──────────────────────────
+function collectExplicitFileChangePaths(record, output) {
+    const explicitPathKeys = ['path', 'filePath', 'file_path', 'movePath', 'move_path', 'destinationPath', 'targetPath'];
+    const hasExplicitPath = explicitPathKeys.some(key => typeof record[key] === 'string');
+    for (const key of explicitPathKeys) {
+        if (typeof record[key] === 'string' && record[key])
+            output.push(record[key]);
+    }
+    if (record.kind && typeof record.kind === 'object') {
+        collectExplicitFileChangePaths(record.kind, output);
+    }
+    return hasExplicitPath;
+}
+/** Collect every target path from a Codex / Claude-style `fileChanges` payload. */
+export function collectFileChangePaths(value, output) {
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+                collectExplicitFileChangePaths(entry, output);
+            }
+        }
+        return;
+    }
+    if (!value || typeof value !== 'object')
+        return;
+    const record = value;
+    const hasExplicitPath = collectExplicitFileChangePaths(record, output);
+    // Claude-style inputs are maps keyed by path; Codex v2 uses an array of
+    // records with an explicit path field. Only treat keys as paths for the map
+    // shape so diff text and metadata never become path candidates.
+    if (!hasExplicitPath) {
+        for (const [filePath, change] of Object.entries(record)) {
+            if (filePath !== 'kind' && filePath !== 'type')
+                output.push(filePath);
+            if (change && typeof change === 'object' && !Array.isArray(change)) {
+                collectExplicitFileChangePaths(change, output);
+            }
+        }
+    }
+}
+/** Every path an apply_patch change set touches, including move destinations. */
+export function applyPatchChangePaths(changes) {
+    const paths = [];
+    for (const change of changes) {
+        paths.push(change.path);
+        if (change.movePath)
+            paths.push(change.movePath);
+    }
+    return paths;
+}

package/dist/core/permission/tool-policy.js

@@ -7,6 +7,7 @@ import { resolveRoot } from '../../paths.js';
 import { containsHClassReference, containsAgentScopeReference, containsLClassReference, checkProtectedPathAccess, getExistingHClassMaskTargets, hClassGrantIncludesProtectedPath, isHClassPath, isSameOrDescendant, isLClassPath, lClassGrantIncludesProtectedPath, resolveProtectedCandidate, resolveProtectedCandidateWithoutFinalSymlink, } from './protected-paths.js';
 import { classifyEvolcoreShellCommand, hasCodexCmdCarrierEcIntent, hasPowerShellCredentialAssignment, normalizeEvolcoreCommandArgv, parseCodexToolCommand, parseBoundedOutputShellCommand, parseShellApplyPatchInvocation, parseLiteralShellArgv, resolveCodexShellCarrierArgv, resolveCodexShellCarrierString, } from './ec-command-parser.js';
 import { analyzeReadonlyShellQuery, } from './readonly-shell-query.js';
+import { applyPatchChangePaths, collectFileChangePaths } from './tool-canonical.js';
 /** Resolve the session-owned temporary root supplied by the execution host. */
 export function resolveManagedTempDir(env = process.env) {
     const raw = typeof env.TMPDIR === 'string' ? env.TMPDIR.trim() : '';
@@ -1438,32 +1439,41 @@ function globReadScope(input, options) {
         ? resolveProtectedCandidate(prefix || path.parse(pattern).root)
         : resolveProtectedCandidate(prefix || '.', base);
 }
-function protectedReadToolStaysInWorkspace(toolName, input, projectPath) {
+function protectedReadToolStaysInWorkspace(toolName, input, projectPath, grantedRoots = [], excludeWorkspace = false) {
     const workspace = resolveProtectedCandidate(projectPath);
+    // A granted root is an explicitly authorized read boundary for this session
+    // (see session-path-grants.ts). Bash already honours its own managed temp
+    // root; read tools must honour the same table or a session cannot read
+    // files the policy layer granted it.
+    // excludeWorkspace：系统会话的 cwd 只用于解析相对路径，本身不是可读根。
+    const withinBoundary = (candidate) => (!excludeWorkspace && isSameOrDescendant(candidate, workspace))
+        || grantedRoots.some(root => isSameOrDescendant(candidate, root));
     if (toolName === 'Read') {
         if (typeof input.file_path !== 'string' || !input.file_path)
             return false;
-        return isSameOrDescendant(resolveProtectedCandidate(input.file_path, projectPath), workspace);
+        return withinBoundary(resolveProtectedCandidate(input.file_path, projectPath));
     }
     if (toolName === 'Grep') {
         const scope = typeof input.path === 'string' && input.path ? input.path : '.';
-        return isSameOrDescendant(resolveProtectedCandidate(scope, projectPath), workspace);
+        return withinBoundary(resolveProtectedCandidate(scope, projectPath));
     }
     if (toolName === 'Glob') {
         const baseValue = typeof input.path === 'string' && input.path ? input.path : '.';
         const base = resolveProtectedCandidate(baseValue, projectPath);
-        if (!isSameOrDescendant(base, workspace))
+        if (!withinBoundary(base))
             return false;
         const scope = globReadScope(input, { cwd: projectPath });
-        return isSameOrDescendant(scope, workspace);
+        return withinBoundary(scope);
     }
     return true;
 }
-function readonlyShellStaysInWorkspace(analysis, projectPath, managedTempDir) {
+function readonlyShellStaysInWorkspace(analysis, projectPath, readRoots = [], excludeWorkspace = false) {
     if (analysis.kind !== 'proven-readonly')
         return false;
     const workspace = resolveProtectedCandidate(projectPath);
-    const managedTemp = managedTempDir ? resolveProtectedCandidate(managedTempDir) : undefined;
+    const roots = readRoots
+        .filter(root => typeof root === 'string' && path.isAbsolute(root))
+        .map(root => resolveProtectedCandidate(root));
     return analysis.ir.pipelines.flatMap(pipeline => pipeline.flatMap(command => command.pathOperands.map(operand => ({
         operand,
         accessKind: command.accessKind ?? (operand.access === 'recursive' ? 'enumerate' : 'content'),
@@ -1471,8 +1481,8 @@ function readonlyShellStaysInWorkspace(analysis, projectPath, managedTempDir) {
         const candidate = accessKind === 'metadata' && operand.access === 'exact'
             ? resolveProtectedCandidateWithoutFinalSymlink(operand.value, projectPath)
             : resolveProtectedCandidate(operand.value, projectPath);
-        return isSameOrDescendant(candidate, workspace)
-            || (!!managedTemp && isSameOrDescendant(candidate, managedTemp));
+        return (!excludeWorkspace && isSameOrDescendant(candidate, workspace))
+            || roots.some(root => isSameOrDescendant(candidate, root));
     })());
 }
 const READONLY_SOURCE_ROOTS = new Set([
@@ -1571,10 +1581,15 @@ export function checkReadonly(toolName, input, projectPath, context) {
         'Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch',
         'TaskList', 'TaskGet', 'ToolSearch',
     ]);
+    // 会话私有临时根在授权表之外恒为可读：runner 自己的临时产物都落在这里。
+    const grantedRoots = [...new Set([
+            ...(context?.grantedReadRoots ?? []),
+            ...(context?.managedTempDir ? [context.managedTempDir] : []),
+        ])];
     if (readOnlyTools.has(toolName)) {
         const paths = protectedReadToolPaths(toolName, input);
         const pathOptions = { cwd: projectPath, root: context?.root, selfAid: context?.selfAid };
-        if (!protectedReadToolStaysInWorkspace(toolName, input, projectPath)) {
+        if (!protectedReadToolStaysInWorkspace(toolName, input, projectPath, grantedRoots, context?.excludeWorkspace === true)) {
             return { behavior: 'deny', message: '🔒 只读模式：文件读取范围不能越出当前项目目录', policyCode: 'readonly_workspace_escape' };
         }
         const directHPath = paths.find(filePath => containsHClassReference(filePath, pathOptions)
@@ -1626,7 +1641,7 @@ export function checkReadonly(toolName, input, projectPath, context) {
         if (protectedOperands.analysis.kind === 'proven-readonly'
             && !protectedOperands.hClass
             && !protectedOperands.lClass
-            && readonlyShellStaysInWorkspace(protectedOperands.analysis, projectPath, managedTempDir)) {
+            && readonlyShellStaysInWorkspace(protectedOperands.analysis, projectPath, grantedRoots, context?.excludeWorkspace === true)) {
             return { behavior: 'allow' };
         }
         if (protectedOperands.hClass) {
@@ -1816,53 +1831,6 @@ function collectFilesystemWriteGrantPaths(value, output, projectRootSubpaths) {
         }
     }
 }
-function collectExplicitFileChangePaths(record, output) {
-    const explicitPathKeys = ['path', 'filePath', 'file_path', 'movePath', 'move_path', 'destinationPath', 'targetPath'];
-    const hasExplicitPath = explicitPathKeys.some(key => typeof record[key] === 'string');
-    for (const key of explicitPathKeys) {
-        if (typeof record[key] === 'string' && record[key])
-            output.push(record[key]);
-    }
-    if (record.kind && typeof record.kind === 'object') {
-        collectExplicitFileChangePaths(record.kind, output);
-    }
-    return hasExplicitPath;
-}
-function collectFileChangePaths(value, output) {
-    if (Array.isArray(value)) {
-        for (const entry of value) {
-            if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
-                collectExplicitFileChangePaths(entry, output);
-            }
-        }
-        return;
-    }
-    if (!value || typeof value !== 'object')
-        return;
-    const record = value;
-    const hasExplicitPath = collectExplicitFileChangePaths(record, output);
-    // Claude-style inputs are maps keyed by path; Codex v2 uses an array of
-    // records with an explicit path field. Only treat keys as paths for the map
-    // shape so diff text and metadata never become path candidates.
-    if (!hasExplicitPath) {
-        for (const [filePath, change] of Object.entries(record)) {
-            if (filePath !== 'kind' && filePath !== 'type')
-                output.push(filePath);
-            if (change && typeof change === 'object' && !Array.isArray(change)) {
-                collectExplicitFileChangePaths(change, output);
-            }
-        }
-    }
-}
-function applyPatchChangePaths(changes) {
-    const paths = [];
-    for (const change of changes) {
-        paths.push(change.path);
-        if (change.movePath)
-            paths.push(change.movePath);
-    }
-    return paths;
-}
 function applyPatchWorkspaceEscape(changes, context) {
     const workspace = resolveProtectedCandidate(context.workspacePath ?? context.projectPath);
     const managedTempDir = context.managedTempDir
@@ -2066,7 +2034,7 @@ export function checkHClassWrite(toolName, input, context) {
             }
             else if (normalized.includes('/backups/config/') || normalized.includes('/.snapshots/')) {
                 suggestion = '\n\n💡 快照由系统自动管理，请使用：\n' +
-                    '  • 创建快照：ec config snapshot --desc "说明"\n' +
+                    `  • 创建快照：ec config snapshot --desc '<说明>'\n` +
                     '  • 查看历史：ec config history\n' +
                     '  • 恢复快照：ec config restore <version>';
             }
@@ -2602,7 +2570,7 @@ export function evaluateToolPreflight(toolName, input, context) {
                     ? '🔒 EC 命令包含无法安全解析的 PowerShell 展开；临时路径仅支持已登记的当前会话 $env:TMPDIR 或 ${env:TMPDIR}，也可使用完整路径。纯文字请使用单引号，或用 PowerShell 反引号转义 $ 和正文内的双引号。'
                     : shellDialect === 'cmd'
                         ? '🔒 EC 命令包含未转义的 cmd.exe 展开；请不要使用 %VAR%、!VAR! 或 ^ 转义。cmd.exe 传给 ec 时必须保持原文字面量'
-                        : '🔒 EC 双引号正文包含未转义的 Shell 展开；请将反引号写成 \\`，将 $()、${}、$变量中的 $ 写成 \\$。Shell 传给 ec 时会还原为原文字面量';
+                        : '🔒 EC 自由文本参数（正文、--desc、--name、--keywords 等）一律用单引号包住；双引号内的反引号与 $ 会被 shell 展开。正文里不要再出现半角撇号（ASCII 0x27），需要时用 `ʼ`（U+02BC）或 `＇`（U+FF07）';
                 return {
                     behavior: 'deny',
                     input,
@@ -2612,10 +2580,10 @@ export function evaluateToolPreflight(toolName, input, context) {
             }
             if (ecCommand.issue === 'invalid-quote') {
                 const message = shellDialect === 'powershell'
-                    ? '🔒 EC 命令引号未闭合或存在错误嵌套；PowerShell 也会解释中文弯引号。请按 PowerShell 规则转义，或把消息正文写入当前 $TMPDIR 后使用 --text-from-file'
+                    ? '🔒 EC 命令引号未闭合或存在错误嵌套。Note: PowerShell 把 U+2018/U+2019/U+201A/U+201B 也当引号定界符——正文里出现这四个字符同样会报此错。正文一律用半角单引号（ASCII 0x27）包住，正文内部的半角撇号用 `ʼ`（U+02BC）或 `＇`（U+FF07）代替，或把消息正文写入当前 $TMPDIR 后使用 --text-from-file'
                     : shellDialect === 'cmd'
                         ? '🔒 EC 命令引号未闭合或存在错误嵌套；cmd.exe carrier 的命令正文请保持一个完整参数，不要用未配对的双引号'
-                        : '🔒 EC 命令引号未闭合或存在错误嵌套；正文中的双引号请写成 \\"';
+                        : '🔒 EC 命令引号未闭合或存在错误嵌套。自由文本参数一律用单引号包住；正文里不要出现半角撇号（ASCII 0x27）本身，需要时用 `ʼ`（U+02BC）或 `＇`（U+FF07）';
                 return {
                     behavior: 'deny',
                     input,

package/dist/core/role/runtime-policy.js

@@ -147,13 +147,17 @@ export function validateRuntimeStringFieldOverride(input) {
  * Resolve the Agent-level host execution policy for one authenticated principal.
  * The Agent flag is independent of role permissionMode values.
  */
+export function isAgentFullAccessOwner(agentAid, principalId) {
+    if (!principalId)
+        return false;
+    const config = read(ConfigTarget.Agent, { self: agentAid }, { cache: false });
+    return config?.owners?.includes(principalId) === true
+        && loadDaemonConfig().owners?.includes(principalId) === true;
+}
 export function agentFullAccessStatus(agentAid, principalId) {
     const config = read(ConfigTarget.Agent, { self: agentAid }, { cache: false });
-    const daemon = loadDaemonConfig();
     const enabled = config?.fullaccess?.enabled === true;
-    const eligible = !!principalId
-        && !!config?.owners?.includes(principalId)
-        && !!daemon.owners?.includes(principalId);
+    const eligible = isAgentFullAccessOwner(agentAid, principalId);
     return { enabled, eligible, effective: enabled && eligible };
 }
 /** Create a trusted per-call claim for a direct private message. */
@@ -189,13 +193,20 @@ export function assertAgentPolicyAuthorization(authorization) {
         throw new Error('Agent fullaccess policy disabled or current owner is no longer eligible');
     }
 }
-/** Only the authenticated EC Web Agent settings may mutate this policy. */
-export function agentFullAccessWriteError(input) {
-    if (!input.ecwebManagement) {
-        return 'Agent fullaccess can only be configured from ECWeb';
+/** Only authenticated ECWeb management or a direct double-Owner Menu request may mutate this policy. */
+export function agentFullAccessWriteError(agentAid, subject) {
+    if (subject?.ecwebManagement === true) {
+        if (!subject.isDaemonOwner || subject.canApprovePersistentFullAccess === false || subject.chatType !== 'private') {
+            return 'Only authenticated ECWeb management may configure Agent fullaccess';
+        }
+        return undefined;
     }
-    if (!input.daemonOwner || input.delegated) {
-        return 'Only authenticated ECWeb management may configure Agent fullaccess';
+    if (subject?.agentFullAccessManagement !== true
+        || subject.chatType !== 'private'
+        || !subject.isDaemonOwner
+        || subject.processRole !== 'daemon-owner'
+        || !isAgentFullAccessOwner(agentAid, subject.principalId)) {
+        return 'Agent fullaccess requires a direct Menu request from both the target Agent Owner and daemon Owner';
     }
     return undefined;
 }

package/dist/core/session/session-fs-store.js

@@ -178,6 +178,111 @@ export function appendJsonlDurable(filePath, record) {
         fs.closeSync(fd);
     }
 }
+/**
+ * meta_*.jsonl（含 `_threads/`）是快照日志：每行一份完整 Session，只有最后一行是权威状态，
+ * 之前的行只供排障回看。超过 256KB 压到最近 50 行。
+ */
+export const SESSION_META_COMPACT_POLICY = {
+    maxBytes: 256 * 1024,
+    keepLines: 50,
+};
+/**
+ * 从 [0, endExclusive) 区间由后往前逐行产出（不含换行符，含空行）。
+ * 按 64KB 分块倒读，内存只与单行长度相关，与文件大小无关。
+ */
+function* iterateLinesBackward(fd, endExclusive, filePath) {
+    const chunkSize = 64 * 1024;
+    let cursor = endExclusive;
+    let carry = Buffer.alloc(0);
+    while (cursor > 0) {
+        const start = Math.max(0, cursor - chunkSize);
+        const chunk = readExactAt(fd, cursor - start, start, filePath);
+        const buf = carry.length ? Buffer.concat([chunk, carry]) : chunk;
+        let end = buf.length;
+        let newline = buf.lastIndexOf(0x0a, end - 1);
+        while (newline >= 0) {
+            yield buf.subarray(newline + 1, end);
+            end = newline;
+            newline = end > 0 ? buf.lastIndexOf(0x0a, end - 1) : -1;
+        }
+        carry = Buffer.from(buf.subarray(0, end));
+        cursor = start;
+    }
+    if (carry.length)
+        yield carry;
+}
+/**
+ * 快照日志的尾部压缩：文件超过 policy.maxBytes 时，只保留最近 keepLines 行
+ * （且不超过 maxBytes/2 字节，至少保留最后一行），写 tmp → fsync → rename 覆盖。
+ *
+ * - 保留行按字节原样拷贝，不解析，坏的末行仍交给读取方报错，不在这里被掩盖。
+ * - 末尾未以换行结束（崩溃残留或有人正在写）时不压缩，留给下次 append 的尾部修复。
+ * - rename 前复查文件大小，期间有其他进程追加则放弃本次压缩，避免吞掉新写入的行。
+ * - 直接 rename 覆盖，不先 unlink，不留目标文件缺失的窗口给并发读者。
+ *
+ * @returns 是否实际做了压缩。失败时抛错，原文件保持不变。
+ */
+export function compactJsonlTail(filePath, policy) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    let output;
+    let size;
+    try {
+        size = fs.fstatSync(fd).size;
+        if (size <= policy.maxBytes)
+            return false;
+        if (readExactAt(fd, 1, size - 1, filePath)[0] !== 0x0a)
+            return false;
+        const budget = Math.floor(policy.maxBytes / 2);
+        const kept = [];
+        let keptBytes = 0;
+        for (const line of iterateLinesBackward(fd, size - 1, filePath)) {
+            if (line.toString('utf8').trim() === '')
+                continue;
+            if (kept.length > 0 && (kept.length >= policy.keepLines || keptBytes + line.length + 1 > budget))
+                break;
+            kept.push(Buffer.from(line));
+            keptBytes += line.length + 1;
+        }
+        if (keptBytes >= size)
+            return false;
+        output = Buffer.concat(kept.reverse().flatMap(line => [line, Buffer.from('\n')]));
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    const tmpPath = filePath + '.compact.tmp';
+    const tmpFd = fs.openSync(tmpPath, 'w');
+    try {
+        writeAllSync(tmpFd, output);
+        fs.fsyncSync(tmpFd);
+    }
+    finally {
+        fs.closeSync(tmpFd);
+    }
+    try {
+        if (fs.statSync(filePath).size !== size) {
+            fs.unlinkSync(tmpPath);
+            return false;
+        }
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+    return true;
+}
 function writeAllSync(fd, content) {
     let offset = 0;
     while (offset < content.length) {
@@ -323,12 +428,24 @@ export function readJsonFile(filePath) {
         throw e;
     }
 }
+/**
+ * 宽松读取最后一条可解析记录：从尾部倒读，跳过空行和坏行（含未终止的尾行）。
+ * 开销只与末尾几行有关，不随文件大小增长。
+ */
 export function readLastJsonlLine(filePath) {
+    let fd;
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.trimEnd().split('\n');
-        for (let i = lines.length - 1; i >= 0; i--) {
-            const line = lines[i].trim();
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        for (const raw of iterateLinesBackward(fd, size, filePath)) {
+            const line = raw.toString('utf8').trim();
             if (!line)
                 continue;
             try {
@@ -340,10 +457,8 @@ export function readLastJsonlLine(filePath) {
         }
         return undefined;
     }
-    catch (e) {
-        if (e.code === 'ENOENT')
-            return undefined;
-        throw e;
+    finally {
+        fs.closeSync(fd);
     }
 }
 export function readAllJsonlLines(filePath) {