@ai-agent-forge/agent-forge 0.88.0 → 0.88.2

package/dist/core/session-cleanup.d.ts

@@ -0,0 +1,49 @@
+export interface CleanupCandidate {
+    /** 会话文件绝对路径。 */
+    path: string;
+    sizeBytes: number;
+    mtimeMs: number;
+}
+export interface CleanupScanResult {
+    candidates: CleanupCandidate[];
+    totalBytes: number;
+}
+export interface CleanupApplyResult {
+    deleted: number;
+    freedBytes: number;
+}
+/** 解析 `/clean-sessions [days]` 参数：正整数天数，缺省 7；非法返回 null。 */
+export declare function parseCleanSessionsDays(arg: string | undefined): number | null;
+/**
+ * 扫描清理候选：遍历 sessionsRoot 下全部一级目录（含 `_agents`），对每个
+ * `*.jsonl`（排除 `*.trace.jsonl`）真实 stat，mtime 早于 cutoff 的收进候选。
+ * 不读索引；单个 readdir/stat 失败只损失该目录/文件，不中断扫描。
+ */
+export declare function scanSessionsForCleanup(input: {
+    sessionsRoot: string;
+    cutoffMs: number;
+    signal?: AbortSignal;
+}): Promise<CleanupScanResult>;
+/**
+ * 执行删除：逐个 unlink 会话文件 + 配对 `*.trace.jsonl` 与 `*.jsonl.guard`
+ * （存在才删，单个失败不中断其余）；每个会话删除成功后同步移除索引条目；
+ * 最后尝试删除被清空的项目目录（非空目录由 rmdir 自行失败并忽略）。
+ * 失败契约同 trace-retention：除中止外不抛错，按文件计数。
+ */
+export declare function applySessionCleanup(paths: string[], signal?: AbortSignal): Promise<CleanupApplyResult>;
+/** runCleanSessions 的宿主面：交互模式用 showError/showStatus/showDialogConfirm 适配。 */
+export interface CleanSessionsRunHost {
+    /** 展示信息行（预览 / 结果 / 取消提示）。 */
+    showMessage(text: string): void;
+    /** 展示错误（用法等）。 */
+    showError(text: string): void;
+    /** 宿主确认对话框；resolve true = 确认执行。 */
+    confirm(title: string, message: string): Promise<boolean>;
+}
+/**
+ * /clean-sessions 的完整两阶段流程（设计 §7）：解析参数 → 扫描 → 零命中直接
+ * 提示 → 预览（命中数、总占用、截止时间）→ 宿主确认 → 执行 → 报告。宿主无关，
+ * 确定性可测；interactive-mode 只做输出/确认适配。
+ */
+export declare function runCleanSessions(host: CleanSessionsRunHost, arg: string | undefined, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=session-cleanup.d.ts.map

package/dist/core/session-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cleanup.d.ts","sourceRoot":"","sources":["../../src/core/session-cleanup.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,gBAAgB;IAChC,kCAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,iGAA2D;AAC3D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM7E;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgC7B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsC5G;AAED,uGAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACpC,6DAA6B;IAC7B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qCAAiB;IACjB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6DAAmC;IACnC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAMD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,oBAAoB,EAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAuCf","sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { readdir, rmdir, stat, unlink } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { getSessionsDir } from \"../config.ts\";\nimport { t } from \"./i18n/index.ts\";\nimport { removeSessionFromIndex } from \"./session-index.ts\";\nimport { getTraceFilePathForSession } from \"./session-manager.ts\";\n\n/**\n * 会话清理命令 /clean-sessions 的内核机制（设计 docs/design/会话索引.md §7）。\n *\n * 清理是磁盘回收语义：真实 stat 每个会话文件取文件系统 mtime 判定，不信任索引\n * 缓存（索引可能是过期投影）。范围是 sessions 根下全部一级项目目录含 `_agents/`；\n * 自定义 --session-dir 不在范围内。删除不可逆，两阶段执行：预览 → 宿主确认 →\n * 执行。单一触发入口：交互模式文本命令，无键绑定（设计 §8）。\n */\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst DEFAULT_CLEAN_SESSIONS_DAYS = 7;\n/** 会话写守卫配对文件后缀（`<sessionFile>.guard`，同 session-storage.ts）。 */\nconst GUARD_FILE_SUFFIX = \".guard\";\n\nexport interface CleanupCandidate {\n\t/** 会话文件绝对路径。 */\n\tpath: string;\n\tsizeBytes: number;\n\tmtimeMs: number;\n}\n\nexport interface CleanupScanResult {\n\tcandidates: CleanupCandidate[];\n\ttotalBytes: number;\n}\n\nexport interface CleanupApplyResult {\n\tdeleted: number;\n\tfreedBytes: number;\n}\n\n/** 解析 `/clean-sessions [days]` 参数：正整数天数，缺省 7；非法返回 null。 */\nexport function parseCleanSessionsDays(arg: string | undefined): number | null {\n\tif (arg === undefined || arg.trim() === \"\") return DEFAULT_CLEAN_SESSIONS_DAYS;\n\tconst trimmed = arg.trim();\n\tif (!/^\\d+$/.test(trimmed)) return null;\n\tconst days = Number.parseInt(trimmed, 10);\n\treturn days > 0 ? days : null;\n}\n\n/**\n * 扫描清理候选：遍历 sessionsRoot 下全部一级目录（含 `_agents`），对每个\n * `*.jsonl`（排除 `*.trace.jsonl`）真实 stat，mtime 早于 cutoff 的收进候选。\n * 不读索引；单个 readdir/stat 失败只损失该目录/文件，不中断扫描。\n */\nexport async function scanSessionsForCleanup(input: {\n\tsessionsRoot: string;\n\tcutoffMs: number;\n\tsignal?: AbortSignal;\n}): Promise<CleanupScanResult> {\n\tconst { sessionsRoot, cutoffMs, signal } = input;\n\tconst candidates: CleanupCandidate[] = [];\n\tlet rootEntries: Dirent[];\n\ttry {\n\t\trootEntries = await readdir(sessionsRoot, { withFileTypes: true });\n\t} catch {\n\t\treturn { candidates, totalBytes: 0 };\n\t}\n\tfor (const entry of rootEntries) {\n\t\tif (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\t\tlet fileNames: string[];\n\t\ttry {\n\t\t\tfileNames = await readdir(join(sessionsRoot, entry.name));\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const file of fileNames) {\n\t\t\tif (!file.endsWith(\".jsonl\") || file.endsWith(\".trace.jsonl\")) continue;\n\t\t\tsignal?.throwIfAborted();\n\t\t\tconst path = join(sessionsRoot, entry.name, file);\n\t\t\ttry {\n\t\t\t\tconst stats = await stat(path);\n\t\t\t\tif (stats.mtimeMs < cutoffMs) {\n\t\t\t\t\tcandidates.push({ path, sizeBytes: stats.size, mtimeMs: stats.mtimeMs });\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// stat 失败的文件不进候选（下轮收敛）。\n\t\t\t}\n\t\t}\n\t}\n\treturn { candidates, totalBytes: candidates.reduce((sum, candidate) => sum + candidate.sizeBytes, 0) };\n}\n\n/**\n * 执行删除：逐个 unlink 会话文件 + 配对 `*.trace.jsonl` 与 `*.jsonl.guard`\n * （存在才删，单个失败不中断其余）；每个会话删除成功后同步移除索引条目；\n * 最后尝试删除被清空的项目目录（非空目录由 rmdir 自行失败并忽略）。\n * 失败契约同 trace-retention：除中止外不抛错，按文件计数。\n */\nexport async function applySessionCleanup(paths: string[], signal?: AbortSignal): Promise<CleanupApplyResult> {\n\tlet deleted = 0;\n\tlet freedBytes = 0;\n\tconst affectedDirs = new Set<string>();\n\tfor (const path of paths) {\n\t\tsignal?.throwIfAborted();\n\t\tlet sizeBytes = 0;\n\t\ttry {\n\t\t\tsizeBytes = (await stat(path)).size;\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tawait unlink(path);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tdeleted++;\n\t\tfreedBytes += sizeBytes;\n\t\tremoveSessionFromIndex(path);\n\t\taffectedDirs.add(dirname(path));\n\t\tfor (const sidecar of [getTraceFilePathForSession(path), `${path}${GUARD_FILE_SUFFIX}`]) {\n\t\t\ttry {\n\t\t\t\tawait unlink(sidecar);\n\t\t\t} catch {\n\t\t\t\t// 配对文件存在才删。\n\t\t\t}\n\t\t}\n\t}\n\tfor (const dir of affectedDirs) {\n\t\tsignal?.throwIfAborted();\n\t\ttry {\n\t\t\tawait rmdir(dir);\n\t\t} catch {\n\t\t\t// 目录非空（还有别的文件）则保留。\n\t\t}\n\t}\n\treturn { deleted, freedBytes };\n}\n\n/** runCleanSessions 的宿主面：交互模式用 showError/showStatus/showDialogConfirm 适配。 */\nexport interface CleanSessionsRunHost {\n\t/** 展示信息行（预览 / 结果 / 取消提示）。 */\n\tshowMessage(text: string): void;\n\t/** 展示错误（用法等）。 */\n\tshowError(text: string): void;\n\t/** 宿主确认对话框；resolve true = 确认执行。 */\n\tconfirm(title: string, message: string): Promise<boolean>;\n}\n\nfunction formatMegabytes(bytes: number): string {\n\treturn `${(bytes / (1024 * 1024)).toFixed(1)} MB`;\n}\n\n/**\n * /clean-sessions 的完整两阶段流程（设计 §7）：解析参数 → 扫描 → 零命中直接\n * 提示 → 预览（命中数、总占用、截止时间）→ 宿主确认 → 执行 → 报告。宿主无关，\n * 确定性可测；interactive-mode 只做输出/确认适配。\n */\nexport async function runCleanSessions(\n\thost: CleanSessionsRunHost,\n\targ: string | undefined,\n\tsignal?: AbortSignal,\n): Promise<void> {\n\tconst days = parseCleanSessionsDays(arg);\n\tif (days === null) {\n\t\thost.showError(t(\"Usage: /clean-sessions [days] - days must be a positive integer (default 7)\"));\n\t\treturn;\n\t}\n\tconst cutoffMs = Date.now() - days * DAY_MS;\n\tconst scan = await scanSessionsForCleanup({ sessionsRoot: getSessionsDir(), cutoffMs, signal });\n\tif (scan.candidates.length === 0) {\n\t\thost.showMessage(t(\"No sessions untouched for {days} days - nothing to clean\", { days }));\n\t\treturn;\n\t}\n\t// 预览（两阶段第一步）：命中数量、总占用、截止时间点。\n\thost.showMessage(\n\t\tt(\"{count} sessions ({size}) untouched since {cutoff} - confirm to delete\", {\n\t\t\tcount: scan.candidates.length,\n\t\t\tsize: formatMegabytes(scan.totalBytes),\n\t\t\tcutoff: new Date(cutoffMs).toLocaleString(),\n\t\t}),\n\t);\n\tconst confirmed = await host.confirm(\n\t\tt(\"Clean old sessions\"),\n\t\tt(\"Permanently delete {count} sessions ({size}) untouched for {days} days? This cannot be undone.\", {\n\t\t\tcount: scan.candidates.length,\n\t\t\tsize: formatMegabytes(scan.totalBytes),\n\t\t\tdays,\n\t\t}),\n\t);\n\tif (!confirmed) {\n\t\thost.showMessage(t(\"Clean-sessions cancelled\"));\n\t\treturn;\n\t}\n\tconst result = await applySessionCleanup(\n\t\tscan.candidates.map((candidate) => candidate.path),\n\t\tsignal,\n\t);\n\thost.showMessage(\n\t\tt(\"Deleted {count} sessions, freed {size}\", { count: result.deleted, size: formatMegabytes(result.freedBytes) }),\n\t);\n}\n"]}

package/dist/core/session-cleanup.js

@@ -0,0 +1,159 @@
+import { readdir, rmdir, stat, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getSessionsDir } from "../config.js";
+import { t } from "./i18n/index.js";
+import { removeSessionFromIndex } from "./session-index.js";
+import { getTraceFilePathForSession } from "./session-manager.js";
+/**
+ * 会话清理命令 /clean-sessions 的内核机制（设计 docs/design/会话索引.md §7）。
+ *
+ * 清理是磁盘回收语义：真实 stat 每个会话文件取文件系统 mtime 判定，不信任索引
+ * 缓存（索引可能是过期投影）。范围是 sessions 根下全部一级项目目录含 `_agents/`；
+ * 自定义 --session-dir 不在范围内。删除不可逆，两阶段执行：预览 → 宿主确认 →
+ * 执行。单一触发入口：交互模式文本命令，无键绑定（设计 §8）。
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_CLEAN_SESSIONS_DAYS = 7;
+/** 会话写守卫配对文件后缀（`<sessionFile>.guard`，同 session-storage.ts）。 */
+const GUARD_FILE_SUFFIX = ".guard";
+/** 解析 `/clean-sessions [days]` 参数：正整数天数，缺省 7；非法返回 null。 */
+export function parseCleanSessionsDays(arg) {
+    if (arg === undefined || arg.trim() === "")
+        return DEFAULT_CLEAN_SESSIONS_DAYS;
+    const trimmed = arg.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const days = Number.parseInt(trimmed, 10);
+    return days > 0 ? days : null;
+}
+/**
+ * 扫描清理候选：遍历 sessionsRoot 下全部一级目录（含 `_agents`），对每个
+ * `*.jsonl`（排除 `*.trace.jsonl`）真实 stat，mtime 早于 cutoff 的收进候选。
+ * 不读索引；单个 readdir/stat 失败只损失该目录/文件，不中断扫描。
+ */
+export async function scanSessionsForCleanup(input) {
+    const { sessionsRoot, cutoffMs, signal } = input;
+    const candidates = [];
+    let rootEntries;
+    try {
+        rootEntries = await readdir(sessionsRoot, { withFileTypes: true });
+    }
+    catch {
+        return { candidates, totalBytes: 0 };
+    }
+    for (const entry of rootEntries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        let fileNames;
+        try {
+            fileNames = await readdir(join(sessionsRoot, entry.name));
+        }
+        catch {
+            continue;
+        }
+        for (const file of fileNames) {
+            if (!file.endsWith(".jsonl") || file.endsWith(".trace.jsonl"))
+                continue;
+            signal?.throwIfAborted();
+            const path = join(sessionsRoot, entry.name, file);
+            try {
+                const stats = await stat(path);
+                if (stats.mtimeMs < cutoffMs) {
+                    candidates.push({ path, sizeBytes: stats.size, mtimeMs: stats.mtimeMs });
+                }
+            }
+            catch {
+                // stat 失败的文件不进候选（下轮收敛）。
+            }
+        }
+    }
+    return { candidates, totalBytes: candidates.reduce((sum, candidate) => sum + candidate.sizeBytes, 0) };
+}
+/**
+ * 执行删除：逐个 unlink 会话文件 + 配对 `*.trace.jsonl` 与 `*.jsonl.guard`
+ * （存在才删，单个失败不中断其余）；每个会话删除成功后同步移除索引条目；
+ * 最后尝试删除被清空的项目目录（非空目录由 rmdir 自行失败并忽略）。
+ * 失败契约同 trace-retention：除中止外不抛错，按文件计数。
+ */
+export async function applySessionCleanup(paths, signal) {
+    let deleted = 0;
+    let freedBytes = 0;
+    const affectedDirs = new Set();
+    for (const path of paths) {
+        signal?.throwIfAborted();
+        let sizeBytes = 0;
+        try {
+            sizeBytes = (await stat(path)).size;
+        }
+        catch {
+            continue;
+        }
+        try {
+            await unlink(path);
+        }
+        catch {
+            continue;
+        }
+        deleted++;
+        freedBytes += sizeBytes;
+        removeSessionFromIndex(path);
+        affectedDirs.add(dirname(path));
+        for (const sidecar of [getTraceFilePathForSession(path), `${path}${GUARD_FILE_SUFFIX}`]) {
+            try {
+                await unlink(sidecar);
+            }
+            catch {
+                // 配对文件存在才删。
+            }
+        }
+    }
+    for (const dir of affectedDirs) {
+        signal?.throwIfAborted();
+        try {
+            await rmdir(dir);
+        }
+        catch {
+            // 目录非空（还有别的文件）则保留。
+        }
+    }
+    return { deleted, freedBytes };
+}
+function formatMegabytes(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * /clean-sessions 的完整两阶段流程（设计 §7）：解析参数 → 扫描 → 零命中直接
+ * 提示 → 预览（命中数、总占用、截止时间）→ 宿主确认 → 执行 → 报告。宿主无关，
+ * 确定性可测；interactive-mode 只做输出/确认适配。
+ */
+export async function runCleanSessions(host, arg, signal) {
+    const days = parseCleanSessionsDays(arg);
+    if (days === null) {
+        host.showError(t("Usage: /clean-sessions [days] - days must be a positive integer (default 7)"));
+        return;
+    }
+    const cutoffMs = Date.now() - days * DAY_MS;
+    const scan = await scanSessionsForCleanup({ sessionsRoot: getSessionsDir(), cutoffMs, signal });
+    if (scan.candidates.length === 0) {
+        host.showMessage(t("No sessions untouched for {days} days - nothing to clean", { days }));
+        return;
+    }
+    // 预览（两阶段第一步）：命中数量、总占用、截止时间点。
+    host.showMessage(t("{count} sessions ({size}) untouched since {cutoff} - confirm to delete", {
+        count: scan.candidates.length,
+        size: formatMegabytes(scan.totalBytes),
+        cutoff: new Date(cutoffMs).toLocaleString(),
+    }));
+    const confirmed = await host.confirm(t("Clean old sessions"), t("Permanently delete {count} sessions ({size}) untouched for {days} days? This cannot be undone.", {
+        count: scan.candidates.length,
+        size: formatMegabytes(scan.totalBytes),
+        days,
+    }));
+    if (!confirmed) {
+        host.showMessage(t("Clean-sessions cancelled"));
+        return;
+    }
+    const result = await applySessionCleanup(scan.candidates.map((candidate) => candidate.path), signal);
+    host.showMessage(t("Deleted {count} sessions, freed {size}", { count: result.deleted, size: formatMegabytes(result.freedBytes) }));
+}
+//# sourceMappingURL=session-cleanup.js.map

package/dist/core/session-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-cleanup.js","sourceRoot":"","sources":["../../src/core/session-cleanup.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { readdir, rmdir, stat, unlink } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { getSessionsDir } from \"../config.ts\";\nimport { t } from \"./i18n/index.ts\";\nimport { removeSessionFromIndex } from \"./session-index.ts\";\nimport { getTraceFilePathForSession } from \"./session-manager.ts\";\n\n/**\n * 会话清理命令 /clean-sessions 的内核机制（设计 docs/design/会话索引.md §7）。\n *\n * 清理是磁盘回收语义：真实 stat 每个会话文件取文件系统 mtime 判定，不信任索引\n * 缓存（索引可能是过期投影）。范围是 sessions 根下全部一级项目目录含 `_agents/`；\n * 自定义 --session-dir 不在范围内。删除不可逆，两阶段执行：预览 → 宿主确认 →\n * 执行。单一触发入口：交互模式文本命令，无键绑定（设计 §8）。\n */\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst DEFAULT_CLEAN_SESSIONS_DAYS = 7;\n/** 会话写守卫配对文件后缀（`<sessionFile>.guard`，同 session-storage.ts）。 */\nconst GUARD_FILE_SUFFIX = \".guard\";\n\nexport interface CleanupCandidate {\n\t/** 会话文件绝对路径。 */\n\tpath: string;\n\tsizeBytes: number;\n\tmtimeMs: number;\n}\n\nexport interface CleanupScanResult {\n\tcandidates: CleanupCandidate[];\n\ttotalBytes: number;\n}\n\nexport interface CleanupApplyResult {\n\tdeleted: number;\n\tfreedBytes: number;\n}\n\n/** 解析 `/clean-sessions [days]` 参数：正整数天数，缺省 7；非法返回 null。 */\nexport function parseCleanSessionsDays(arg: string | undefined): number | null {\n\tif (arg === undefined || arg.trim() === \"\") return DEFAULT_CLEAN_SESSIONS_DAYS;\n\tconst trimmed = arg.trim();\n\tif (!/^\\d+$/.test(trimmed)) return null;\n\tconst days = Number.parseInt(trimmed, 10);\n\treturn days > 0 ? days : null;\n}\n\n/**\n * 扫描清理候选：遍历 sessionsRoot 下全部一级目录（含 `_agents`），对每个\n * `*.jsonl`（排除 `*.trace.jsonl`）真实 stat，mtime 早于 cutoff 的收进候选。\n * 不读索引；单个 readdir/stat 失败只损失该目录/文件，不中断扫描。\n */\nexport async function scanSessionsForCleanup(input: {\n\tsessionsRoot: string;\n\tcutoffMs: number;\n\tsignal?: AbortSignal;\n}): Promise<CleanupScanResult> {\n\tconst { sessionsRoot, cutoffMs, signal } = input;\n\tconst candidates: CleanupCandidate[] = [];\n\tlet rootEntries: Dirent[];\n\ttry {\n\t\trootEntries = await readdir(sessionsRoot, { withFileTypes: true });\n\t} catch {\n\t\treturn { candidates, totalBytes: 0 };\n\t}\n\tfor (const entry of rootEntries) {\n\t\tif (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\t\tlet fileNames: string[];\n\t\ttry {\n\t\t\tfileNames = await readdir(join(sessionsRoot, entry.name));\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const file of fileNames) {\n\t\t\tif (!file.endsWith(\".jsonl\") || file.endsWith(\".trace.jsonl\")) continue;\n\t\t\tsignal?.throwIfAborted();\n\t\t\tconst path = join(sessionsRoot, entry.name, file);\n\t\t\ttry {\n\t\t\t\tconst stats = await stat(path);\n\t\t\t\tif (stats.mtimeMs < cutoffMs) {\n\t\t\t\t\tcandidates.push({ path, sizeBytes: stats.size, mtimeMs: stats.mtimeMs });\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// stat 失败的文件不进候选（下轮收敛）。\n\t\t\t}\n\t\t}\n\t}\n\treturn { candidates, totalBytes: candidates.reduce((sum, candidate) => sum + candidate.sizeBytes, 0) };\n}\n\n/**\n * 执行删除：逐个 unlink 会话文件 + 配对 `*.trace.jsonl` 与 `*.jsonl.guard`\n * （存在才删，单个失败不中断其余）；每个会话删除成功后同步移除索引条目；\n * 最后尝试删除被清空的项目目录（非空目录由 rmdir 自行失败并忽略）。\n * 失败契约同 trace-retention：除中止外不抛错，按文件计数。\n */\nexport async function applySessionCleanup(paths: string[], signal?: AbortSignal): Promise<CleanupApplyResult> {\n\tlet deleted = 0;\n\tlet freedBytes = 0;\n\tconst affectedDirs = new Set<string>();\n\tfor (const path of paths) {\n\t\tsignal?.throwIfAborted();\n\t\tlet sizeBytes = 0;\n\t\ttry {\n\t\t\tsizeBytes = (await stat(path)).size;\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tawait unlink(path);\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tdeleted++;\n\t\tfreedBytes += sizeBytes;\n\t\tremoveSessionFromIndex(path);\n\t\taffectedDirs.add(dirname(path));\n\t\tfor (const sidecar of [getTraceFilePathForSession(path), `${path}${GUARD_FILE_SUFFIX}`]) {\n\t\t\ttry {\n\t\t\t\tawait unlink(sidecar);\n\t\t\t} catch {\n\t\t\t\t// 配对文件存在才删。\n\t\t\t}\n\t\t}\n\t}\n\tfor (const dir of affectedDirs) {\n\t\tsignal?.throwIfAborted();\n\t\ttry {\n\t\t\tawait rmdir(dir);\n\t\t} catch {\n\t\t\t// 目录非空（还有别的文件）则保留。\n\t\t}\n\t}\n\treturn { deleted, freedBytes };\n}\n\n/** runCleanSessions 的宿主面：交互模式用 showError/showStatus/showDialogConfirm 适配。 */\nexport interface CleanSessionsRunHost {\n\t/** 展示信息行（预览 / 结果 / 取消提示）。 */\n\tshowMessage(text: string): void;\n\t/** 展示错误（用法等）。 */\n\tshowError(text: string): void;\n\t/** 宿主确认对话框；resolve true = 确认执行。 */\n\tconfirm(title: string, message: string): Promise<boolean>;\n}\n\nfunction formatMegabytes(bytes: number): string {\n\treturn `${(bytes / (1024 * 1024)).toFixed(1)} MB`;\n}\n\n/**\n * /clean-sessions 的完整两阶段流程（设计 §7）：解析参数 → 扫描 → 零命中直接\n * 提示 → 预览（命中数、总占用、截止时间）→ 宿主确认 → 执行 → 报告。宿主无关，\n * 确定性可测；interactive-mode 只做输出/确认适配。\n */\nexport async function runCleanSessions(\n\thost: CleanSessionsRunHost,\n\targ: string | undefined,\n\tsignal?: AbortSignal,\n): Promise<void> {\n\tconst days = parseCleanSessionsDays(arg);\n\tif (days === null) {\n\t\thost.showError(t(\"Usage: /clean-sessions [days] - days must be a positive integer (default 7)\"));\n\t\treturn;\n\t}\n\tconst cutoffMs = Date.now() - days * DAY_MS;\n\tconst scan = await scanSessionsForCleanup({ sessionsRoot: getSessionsDir(), cutoffMs, signal });\n\tif (scan.candidates.length === 0) {\n\t\thost.showMessage(t(\"No sessions untouched for {days} days - nothing to clean\", { days }));\n\t\treturn;\n\t}\n\t// 预览（两阶段第一步）：命中数量、总占用、截止时间点。\n\thost.showMessage(\n\t\tt(\"{count} sessions ({size}) untouched since {cutoff} - confirm to delete\", {\n\t\t\tcount: scan.candidates.length,\n\t\t\tsize: formatMegabytes(scan.totalBytes),\n\t\t\tcutoff: new Date(cutoffMs).toLocaleString(),\n\t\t}),\n\t);\n\tconst confirmed = await host.confirm(\n\t\tt(\"Clean old sessions\"),\n\t\tt(\"Permanently delete {count} sessions ({size}) untouched for {days} days? This cannot be undone.\", {\n\t\t\tcount: scan.candidates.length,\n\t\t\tsize: formatMegabytes(scan.totalBytes),\n\t\t\tdays,\n\t\t}),\n\t);\n\tif (!confirmed) {\n\t\thost.showMessage(t(\"Clean-sessions cancelled\"));\n\t\treturn;\n\t}\n\tconst result = await applySessionCleanup(\n\t\tscan.candidates.map((candidate) => candidate.path),\n\t\tsignal,\n\t);\n\thost.showMessage(\n\t\tt(\"Deleted {count} sessions, freed {size}\", { count: result.deleted, size: formatMegabytes(result.freedBytes) }),\n\t);\n}\n"]}

package/dist/core/session-index.d.ts

@@ -0,0 +1,75 @@
+import type { SessionInfo } from "./session-manager.ts";
+export interface SessionIndexProjectEntry {
+    /** 项目目录名（getDefaultSessionDirPath(cwd) 的编码目录名，不从 cwd 重推导）。 */
+    dir: string;
+    cwd: string;
+}
+export interface SessionIndexSessionEntry {
+    /** 会话文件 basename；键 = (dir, file)。 */
+    file: string;
+    dir: string;
+    id: string;
+    cwd: string;
+    /**
+     * 缓存有效期令牌：条目写入时该会话文件的 stat mtime。缺失或与磁盘不一致 =
+     * 缓存过期，对账时重读刷新（设计 §3/§5）。
+     */
+    file_mtime_ms?: number;
+    name?: string;
+    parent_session_path?: string;
+    /** 创建时锁定的 profile（可选字段，向后可读；与 SessionHeader 对应）。 */
+    profile_id?: string;
+    profile_version?: string;
+    created_ms: number;
+    modified_ms: number;
+    message_count: number;
+    first_message: string;
+}
+export interface SessionIndexUpdateInput {
+    /** 绝对会话文件路径（默认布局下位于 sessions 根之内）。 */
+    sessionPath: string;
+    sessionId: string;
+    cwd: string;
+    name?: string;
+    parentSessionPath?: string;
+    profileId?: string;
+    profileVersion?: string;
+    createdMs: number;
+    modifiedMs: number;
+    messageCount: number;
+    firstMessage: string;
+    /** true = 同步原子落盘；false = 标脏，节流窗口内落盘。 */
+    immediate: boolean;
+}
+export interface ListSessionsViaIndexInput {
+    /** sessions 根目录（…/sessions）绝对路径。 */
+    sessionsRoot: string;
+    /** 完整 SessionInfo 构建器（session-manager 的 buildSessionInfo）；返回 null = 非会话文件。 */
+    buildInfo: (path: string) => Promise<SessionInfo | null>;
+    /** 旧全量扫描委托：索引缺失/损坏/版本不符时用于重建索引（与旧 listAll 同价）。 */
+    scanAll: () => Promise<SessionInfo[]>;
+    /** 索引命中时的单次完整已排序快照回调（重建路径的进度由 scanAll 按旧语义发布）。 */
+    onHit?: (sessions: SessionInfo[]) => void;
+    signal?: AbortSignal;
+}
+/** 索引文件路径（与 plugin-state.json 同级；getAgentDir() 尊重 AGENT_FORGE_DIR）。 */
+export declare function getSessionIndexPath(): string;
+/** 立即落盘脏状态（测试与 exit 钩子共用）；无脏状态时为 no-op。 */
+export declare function flushSessionIndexNow(): void;
+/**
+ * upsert 单会话条目并按 immediate 决定落盘时机。预热优化（设计 §4）：条目缺失
+ * 或过期由读路径的 mtime 令牌对账刷新，不承担正确性。内部错误一律吞掉
+ * （fail-open）：索引是投影，写入失败由下次读取对账自愈，绝不影响会话持久化。
+ */
+export declare function recordSessionUpdate(input: SessionIndexUpdateInput): void;
+/**
+ * 按路径移除条目并立即原子落盘；索引不存在/损坏/路径不在 sessions 根时静默 no-op
+ * （不抛错、不重建，设计 §6）。
+ */
+export declare function removeSessionFromIndex(sessionPath: string): void;
+/**
+ * listAll 默认布局分支的索引读路径。返回 undefined 表示索引层意外失败（IO 等），
+ * 调用方应回退到旧全量扫描（fail-open，设计 §5）；中止按惯例抛 AbortError。
+ */
+export declare function listSessionsViaIndex(input: ListSessionsViaIndexInput): Promise<SessionInfo[] | undefined>;
+//# sourceMappingURL=session-index.d.ts.map

package/dist/core/session-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-index.d.ts","sourceRoot":"","sources":["../../src/core/session-index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAiBxD,MAAM,WAAW,wBAAwB;IACxC,sGAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,wBAAwB;IACxC,mDAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gGAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACtB;AASD,MAAM,WAAW,uBAAuB;IACvC,gFAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,4EAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACzC,0DAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,gHAA8E;IAC9E,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACzD,kHAAkD;IAClD,OAAO,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACtC,sHAAkD;IAClD,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;IAC1C,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,qGAAuE;AACvE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AA4CD,2FAA2C;AAC3C,wBAAgB,oBAAoB,IAAI,IAAI,CAS3C;AAoKD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAyCxE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAchE;AA+HD;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC,CA+B/G","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { type Dirent, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from \"node:fs\";\nimport { readdir, stat } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, join, relative } from \"node:path\";\nimport { getAgentDir, getSessionsDir } from \"../config.ts\";\nimport { AGENT_SESSIONS_DIR_NAME } from \"./agent-session-paths.ts\";\nimport type { SessionInfo } from \"./session-manager.ts\";\n\n/**\n * 会话元数据索引（session-index.json），设计契约见 docs/design/会话索引.md。\n *\n * 索引是文件系统的投影、永远不是事实源；条目内部分两层：关系（file/dir/id/cwd）\n * 由 readdir 对账保证，内容缓存由 file_mtime_ms 令牌保证（mtime 未变才可信，\n * 变了就重读刷新）。写钩子是预热优化、不承担正确性（设计 §4）；读路径\n * （listSessionsViaIndex）负责对账自愈与全量重建。不加跨进程锁——丢失的更新\n * 会被令牌机制限定为无害，下次读取对账时按文件系统纠正（设计 §6）。\n */\n\nconst SESSION_INDEX_VERSION = 1;\nconst SESSION_INDEX_FILE_NAME = \"session-index.json\";\n/** 节流落盘窗口（设计 §4：每轮消息追加标脏，10s 落盘一次）。 */\nconst FLUSH_THROTTLE_MS = 10_000;\n\nexport interface SessionIndexProjectEntry {\n\t/** 项目目录名（getDefaultSessionDirPath(cwd) 的编码目录名，不从 cwd 重推导）。 */\n\tdir: string;\n\tcwd: string;\n}\n\nexport interface SessionIndexSessionEntry {\n\t/** 会话文件 basename；键 = (dir, file)。 */\n\tfile: string;\n\tdir: string;\n\tid: string;\n\tcwd: string;\n\t/**\n\t * 缓存有效期令牌：条目写入时该会话文件的 stat mtime。缺失或与磁盘不一致 =\n\t * 缓存过期，对账时重读刷新（设计 §3/§5）。\n\t */\n\tfile_mtime_ms?: number;\n\tname?: string;\n\tparent_session_path?: string;\n\t/** 创建时锁定的 profile（可选字段，向后可读；与 SessionHeader 对应）。 */\n\tprofile_id?: string;\n\tprofile_version?: string;\n\tcreated_ms: number;\n\tmodified_ms: number;\n\tmessage_count: number;\n\tfirst_message: string;\n}\n\ninterface SessionIndexFile {\n\tversion: number;\n\tupdated_at_ms: number;\n\tprojects: SessionIndexProjectEntry[];\n\tsessions: SessionIndexSessionEntry[];\n}\n\nexport interface SessionIndexUpdateInput {\n\t/** 绝对会话文件路径（默认布局下位于 sessions 根之内）。 */\n\tsessionPath: string;\n\tsessionId: string;\n\tcwd: string;\n\tname?: string;\n\tparentSessionPath?: string;\n\tprofileId?: string;\n\tprofileVersion?: string;\n\tcreatedMs: number;\n\tmodifiedMs: number;\n\tmessageCount: number;\n\tfirstMessage: string;\n\t/** true = 同步原子落盘；false = 标脏，节流窗口内落盘。 */\n\timmediate: boolean;\n}\n\nexport interface ListSessionsViaIndexInput {\n\t/** sessions 根目录（…/sessions）绝对路径。 */\n\tsessionsRoot: string;\n\t/** 完整 SessionInfo 构建器（session-manager 的 buildSessionInfo）；返回 null = 非会话文件。 */\n\tbuildInfo: (path: string) => Promise<SessionInfo | null>;\n\t/** 旧全量扫描委托：索引缺失/损坏/版本不符时用于重建索引（与旧 listAll 同价）。 */\n\tscanAll: () => Promise<SessionInfo[]>;\n\t/** 索引命中时的单次完整已排序快照回调（重建路径的进度由 scanAll 按旧语义发布）。 */\n\tonHit?: (sessions: SessionInfo[]) => void;\n\tsignal?: AbortSignal;\n}\n\n/** 索引文件路径（与 plugin-state.json 同级；getAgentDir() 尊重 AGENT_FORGE_DIR）。 */\nexport function getSessionIndexPath(): string {\n\treturn join(getAgentDir(), SESSION_INDEX_FILE_NAME);\n}\n\n// ---------------------------------------------------------------------------\n// 模块级脏状态：pendingFlush 捕获写入目标与快照，进程 exit 时同步落盘。\n// 按路径比较，测试间 ENV_AGENT_DIR 切换不会串写。\n// ---------------------------------------------------------------------------\n\ninterface PendingFlush {\n\tindexPath: string;\n\tstate: SessionIndexFile;\n}\n\nlet pendingFlush: PendingFlush | undefined;\nlet flushTimer: ReturnType<typeof setTimeout> | undefined;\nlet exitHookRegistered = false;\n\nfunction clearPending(): void {\n\tpendingFlush = undefined;\n\tif (flushTimer !== undefined) {\n\t\tclearTimeout(flushTimer);\n\t\tflushTimer = undefined;\n\t}\n}\n\nfunction ensureExitFlushHook(): void {\n\tif (exitHookRegistered) return;\n\texitHookRegistered = true;\n\tprocess.once(\"exit\", () => {\n\t\tflushSessionIndexNow();\n\t});\n}\n\nfunction armDirty(indexPath: string, state: SessionIndexFile): void {\n\tpendingFlush = { indexPath, state };\n\tensureExitFlushHook();\n\tif (flushTimer === undefined) {\n\t\tflushTimer = setTimeout(() => {\n\t\t\tflushTimer = undefined;\n\t\t\tflushSessionIndexNow();\n\t\t}, FLUSH_THROTTLE_MS);\n\t\tflushTimer.unref();\n\t}\n}\n\n/** 立即落盘脏状态（测试与 exit 钩子共用）；无脏状态时为 no-op。 */\nexport function flushSessionIndexNow(): void {\n\tconst pending = pendingFlush;\n\tif (!pending) return;\n\tclearPending();\n\ttry {\n\t\twriteStateSync(pending.indexPath, pending.state);\n\t} catch {\n\t\t// 失败留给对账自愈（设计 §6），不向会话写入路径传播。\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// 读写原语\n// ---------------------------------------------------------------------------\n\nfunction emptyState(): SessionIndexFile {\n\treturn { version: SESSION_INDEX_VERSION, updated_at_ms: 0, projects: [], sessions: [] };\n}\n\nfunction safeMs(value: number): number {\n\treturn Number.isFinite(value) ? value : 0;\n}\n\nfunction isSessionFileName(file: string): boolean {\n\treturn file.endsWith(\".jsonl\") && !file.endsWith(\".trace.jsonl\");\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n\treturn typeof value === \"number\" && Number.isFinite(value);\n}\n\n/**\n * 条目级最小形状校验：必填字段类型/finite 不符的条目直接丢弃（视同缺失，交给\n * 对账/重建自愈，覆盖设计 §2 目标 3 的字段级损坏）；可选字段仅在为 string 时\n * 保留，否则按键缺席处理。\n */\nfunction coerceSessionEntry(value: unknown): SessionIndexSessionEntry | null {\n\tif (typeof value !== \"object\" || value === null) return null;\n\tconst raw = value as Record<string, unknown>;\n\tif (typeof raw.file !== \"string\" || typeof raw.dir !== \"string\" || typeof raw.id !== \"string\") return null;\n\tif (typeof raw.cwd !== \"string\") return null;\n\tif (!isFiniteNumber(raw.created_ms) || !isFiniteNumber(raw.modified_ms) || !isFiniteNumber(raw.message_count)) {\n\t\treturn null;\n\t}\n\tif (typeof raw.first_message !== \"string\") return null;\n\treturn {\n\t\tfile: raw.file,\n\t\tdir: raw.dir,\n\t\tid: raw.id,\n\t\tcwd: raw.cwd,\n\t\t...(isFiniteNumber(raw.file_mtime_ms) ? { file_mtime_ms: raw.file_mtime_ms } : {}),\n\t\t...(typeof raw.name === \"string\" ? { name: raw.name } : {}),\n\t\t...(typeof raw.parent_session_path === \"string\" ? { parent_session_path: raw.parent_session_path } : {}),\n\t\t...(typeof raw.profile_id === \"string\" ? { profile_id: raw.profile_id } : {}),\n\t\t...(typeof raw.profile_version === \"string\" ? { profile_version: raw.profile_version } : {}),\n\t\tcreated_ms: raw.created_ms,\n\t\tmodified_ms: raw.modified_ms,\n\t\tmessage_count: raw.message_count,\n\t\tfirst_message: raw.first_message,\n\t};\n}\n\nfunction coerceProjectEntry(value: unknown): SessionIndexProjectEntry | null {\n\tif (typeof value !== \"object\" || value === null) return null;\n\tconst raw = value as Record<string, unknown>;\n\t// 项目条目只有 dir/cwd 关系；last_active 由成员条目 modified_ms 服务时派生\n\t// （设计 §3），入库时的任何附加键一律忽略。\n\tif (typeof raw.dir !== \"string\" || typeof raw.cwd !== \"string\") return null;\n\treturn { dir: raw.dir, cwd: raw.cwd };\n}\n\n/** 读取并校验索引文件；不存在/JSON 损坏/版本不符返回 null（由调用方重建或忽略）。 */\nfunction readIndexFile(indexPath: string): SessionIndexFile | null {\n\tlet content: string;\n\ttry {\n\t\tcontent = readFileSync(indexPath, \"utf8\");\n\t} catch {\n\t\treturn null;\n\t}\n\ttry {\n\t\tconst parsed = JSON.parse(content) as { version?: unknown; projects?: unknown; sessions?: unknown };\n\t\tif (parsed.version !== SESSION_INDEX_VERSION) return null;\n\t\tif (!Array.isArray(parsed.projects) || !Array.isArray(parsed.sessions)) return null;\n\t\tconst projects = parsed.projects.map(coerceProjectEntry).filter((entry): entry is SessionIndexProjectEntry => {\n\t\t\treturn entry !== null;\n\t\t});\n\t\tconst sessions = parsed.sessions.map(coerceSessionEntry).filter((entry): entry is SessionIndexSessionEntry => {\n\t\t\treturn entry !== null;\n\t\t});\n\t\treturn { version: SESSION_INDEX_VERSION, updated_at_ms: 0, projects, sessions };\n\t} catch {\n\t\treturn null;\n\t}\n}\n\n/** 原子写（temp + rename，同 ecosystem/state.ts 模式）；同步 API 供 exit 钩子共用。 */\nfunction writeStateSync(indexPath: string, state: SessionIndexFile): void {\n\tconst parent = dirname(indexPath);\n\tmkdirSync(parent, { recursive: true });\n\tconst temporaryPath = join(parent, `.${basename(indexPath)}.${randomUUID()}.tmp`);\n\ttry {\n\t\tstate.updated_at_ms = Date.now();\n\t\twriteFileSync(temporaryPath, `${JSON.stringify(state)}\\n`, \"utf8\");\n\t\trenameSync(temporaryPath, indexPath);\n\t} finally {\n\t\ttry {\n\t\t\tunlinkSync(temporaryPath);\n\t\t} catch {\n\t\t\t// rename 成功后 tmp 已不存在；清理失败不掩盖写入结果。\n\t\t}\n\t}\n}\n\n/** 可变状态：优先续用未落盘的脏快照，避免节流窗口内的读-改-写互相覆盖。 */\nfunction loadMutableState(indexPath: string): SessionIndexFile {\n\tif (pendingFlush?.indexPath === indexPath) return pendingFlush.state;\n\treturn readIndexFile(indexPath) ?? emptyState();\n}\n\n/**\n * 解析会话路径在索引中的位置：dir = 相对 sessions 根的父目录名（不从 cwd 重推导，\n * 规避 Windows 盘符大小写陷阱，设计 §3），file = basename。\n * sessions 根之外、根一级散落文件、非 `*.jsonl` 与 `*.trace.jsonl` 一律返回 null。\n */\nfunction locationInRoot(sessionsRoot: string, sessionPath: string): { dir: string; file: string } | null {\n\tconst rel = relative(sessionsRoot, sessionPath);\n\tif (rel === \"\" || rel.startsWith(\"..\") || isAbsolute(rel)) return null;\n\tconst dir = dirname(rel);\n\tif (dir === \".\" || dir === \"..\") return null;\n\tconst file = basename(rel);\n\tif (!isSessionFileName(file)) return null;\n\treturn { dir, file };\n}\n\nfunction findSessionEntry(state: SessionIndexFile, dir: string, file: string): SessionIndexSessionEntry | undefined {\n\treturn state.sessions.find((entry) => entry.dir === dir && entry.file === file);\n}\n\nfunction touchProject(state: SessionIndexFile, dir: string, cwd: string): void {\n\tif (state.projects.some((project) => project.dir === dir)) return;\n\tstate.projects.push({ dir, cwd });\n}\n\nfunction addSessionFromInfo(\n\tstate: SessionIndexFile,\n\tdir: string,\n\tfile: string,\n\tinfo: SessionInfo,\n\tmtimeMs?: number,\n): void {\n\tstate.sessions = state.sessions.filter((entry) => !(entry.dir === dir && entry.file === file));\n\tstate.sessions.push({\n\t\tfile,\n\t\tdir,\n\t\tid: info.id,\n\t\tcwd: info.cwd,\n\t\t...(info.name === undefined ? {} : { name: info.name }),\n\t\t...(info.parentSessionPath === undefined ? {} : { parent_session_path: info.parentSessionPath }),\n\t\t...(info.profileId === undefined ? {} : { profile_id: info.profileId }),\n\t\t...(info.profileVersion === undefined ? {} : { profile_version: info.profileVersion }),\n\t\t...(mtimeMs === undefined ? {} : { file_mtime_ms: mtimeMs }),\n\t\tcreated_ms: safeMs(info.created.getTime()),\n\t\tmodified_ms: safeMs(info.modified.getTime()),\n\t\tmessage_count: info.messageCount,\n\t\tfirst_message: info.firstMessage,\n\t});\n\ttouchProject(state, dir, info.cwd);\n}\n\n// ---------------------------------------------------------------------------\n// 写路径（设计 §4）\n// ---------------------------------------------------------------------------\n\n/**\n * upsert 单会话条目并按 immediate 决定落盘时机。预热优化（设计 §4）：条目缺失\n * 或过期由读路径的 mtime 令牌对账刷新，不承担正确性。内部错误一律吞掉\n * （fail-open）：索引是投影，写入失败由下次读取对账自愈，绝不影响会话持久化。\n */\nexport function recordSessionUpdate(input: SessionIndexUpdateInput): void {\n\ttry {\n\t\tconst sessionsRoot = getSessionsDir();\n\t\tconst location = locationInRoot(sessionsRoot, input.sessionPath);\n\t\tif (!location) return;\n\t\t// 缓存有效期令牌 = 当前文件 mtime；stat 失败则条目不带令牌（视为过期，无害）。\n\t\tlet mtimeMs: number | undefined;\n\t\ttry {\n\t\t\tmtimeMs = statSync(input.sessionPath).mtimeMs;\n\t\t} catch {\n\t\t\tmtimeMs = undefined;\n\t\t}\n\t\tconst indexPath = getSessionIndexPath();\n\t\tconst state = loadMutableState(indexPath);\n\t\tstate.sessions = state.sessions.filter((entry) => !(entry.dir === location.dir && entry.file === location.file));\n\t\tconst modifiedMs = safeMs(input.modifiedMs);\n\t\tstate.sessions.push({\n\t\t\tfile: location.file,\n\t\t\tdir: location.dir,\n\t\t\tid: input.sessionId,\n\t\t\tcwd: input.cwd,\n\t\t\t...(input.name === undefined ? {} : { name: input.name }),\n\t\t\t...(input.parentSessionPath === undefined ? {} : { parent_session_path: input.parentSessionPath }),\n\t\t\t...(input.profileId === undefined ? {} : { profile_id: input.profileId }),\n\t\t\t...(input.profileVersion === undefined ? {} : { profile_version: input.profileVersion }),\n\t\t\t...(mtimeMs === undefined ? {} : { file_mtime_ms: mtimeMs }),\n\t\t\tcreated_ms: safeMs(input.createdMs),\n\t\t\tmodified_ms: modifiedMs,\n\t\t\tmessage_count: input.messageCount,\n\t\t\tfirst_message: input.firstMessage,\n\t\t});\n\t\ttouchProject(state, location.dir, input.cwd);\n\t\tif (input.immediate) {\n\t\t\tclearPending();\n\t\t\twriteStateSync(indexPath, state);\n\t\t} else {\n\t\t\tarmDirty(indexPath, state);\n\t\t}\n\t} catch {\n\t\t// 索引维护绝不影响会话写入（设计 §4/§6）。\n\t}\n}\n\n/**\n * 按路径移除条目并立即原子落盘；索引不存在/损坏/路径不在 sessions 根时静默 no-op\n * （不抛错、不重建，设计 §6）。\n */\nexport function removeSessionFromIndex(sessionPath: string): void {\n\ttry {\n\t\tconst location = locationInRoot(getSessionsDir(), sessionPath);\n\t\tif (!location) return;\n\t\tconst indexPath = getSessionIndexPath();\n\t\tconst state = loadMutableState(indexPath);\n\t\tconst before = state.sessions.length;\n\t\tstate.sessions = state.sessions.filter((entry) => !(entry.dir === location.dir && entry.file === location.file));\n\t\tif (state.sessions.length === before) return;\n\t\tclearPending();\n\t\twriteStateSync(indexPath, state);\n\t} catch {\n\t\t// 对账会在下次读取自愈（设计 §6）。\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// 读路径与对账（设计 §5）\n// ---------------------------------------------------------------------------\n\nfunction sessionInfoFromEntry(sessionsRoot: string, entry: SessionIndexSessionEntry): SessionInfo {\n\treturn {\n\t\tpath: join(sessionsRoot, entry.dir, entry.file),\n\t\tid: entry.id,\n\t\tcwd: entry.cwd,\n\t\t...(entry.name === undefined ? {} : { name: entry.name }),\n\t\t...(entry.parent_session_path === undefined ? {} : { parentSessionPath: entry.parent_session_path }),\n\t\t...(entry.profile_id === undefined ? {} : { profileId: entry.profile_id }),\n\t\t...(entry.profile_version === undefined ? {} : { profileVersion: entry.profile_version }),\n\t\tcreated: new Date(entry.created_ms),\n\t\tmodified: new Date(entry.modified_ms),\n\t\tmessageCount: entry.message_count,\n\t\tfirstMessage: entry.first_message,\n\t\tallMessagesText: \"\",\n\t};\n}\n\nfunction sortedSessions(sessionsRoot: string, state: SessionIndexFile): SessionInfo[] {\n\tconst ordered = [...state.sessions].sort((a, b) => b.modified_ms - a.modified_ms || b.file.localeCompare(a.file));\n\treturn ordered.map((entry) => sessionInfoFromEntry(sessionsRoot, entry));\n}\n\n/** 重建路径：由全量扫描结果构建索引状态，逐文件 stat 写入 mtime 令牌。 */\nasync function stateFromSessions(sessionsRoot: string, sessions: SessionInfo[]): Promise<SessionIndexFile> {\n\tconst state = emptyState();\n\tfor (const info of sessions) {\n\t\tconst location = locationInRoot(sessionsRoot, info.path);\n\t\tif (!location) continue;\n\t\tlet mtimeMs: number | undefined;\n\t\ttry {\n\t\t\tmtimeMs = (await stat(info.path)).mtimeMs;\n\t\t} catch {\n\t\t\tmtimeMs = undefined;\n\t\t}\n\t\taddSessionFromInfo(state, location.dir, location.file, info, mtimeMs);\n\t}\n\treturn state;\n}\n\n/**\n * 对账：目录名集合 diff + 目录内文件名集合 diff，逐文件 stat 与条目的\n * file_mtime_ms 令牌比对（设计 §5）——条目缺失 → buildInfo 补；mtime 与令牌\n * 一致 → 缓存可信直接沿用；不一致或令牌缺失 → buildInfo 重读刷新缓存与新令牌\n * （重读失败 = 文件已不再是会话 → 剔除陈旧条目）；索引有、磁盘无 → 剔除；\n * 消失目录连同其 project 行剔除。返回是否有变更。\n */\nasync function reconcileIndex(\n\tsessionsRoot: string,\n\tstate: SessionIndexFile,\n\tbuildInfo: (path: string) => Promise<SessionInfo | null>,\n\tsignal?: AbortSignal,\n): Promise<boolean> {\n\t// 磁盘清单：目录名 → (文件名 → stat mtime)。stat 失败（readdir 与 stat 之间\n\t// 被删/不可读）视同本轮缺席，下轮对账收敛。\n\tconst diskDirs = new Map<string, Map<string, number>>();\n\tlet rootEntries: Dirent[];\n\ttry {\n\t\trootEntries = await readdir(sessionsRoot, { withFileTypes: true });\n\t} catch {\n\t\t// sessions 根不可读视同空盘：剔除全部条目（索引是投影，根恢复后重建）。\n\t\trootEntries = [];\n\t}\n\tfor (const entry of rootEntries) {\n\t\tif (entry.name === AGENT_SESSIONS_DIR_NAME) continue;\n\t\tif (!entry.isDirectory() && !entry.isSymbolicLink()) continue;\n\t\tlet fileNames: string[];\n\t\ttry {\n\t\t\tfileNames = await readdir(join(sessionsRoot, entry.name));\n\t\t} catch {\n\t\t\t// 目录不可读视同已清空，其索引条目被剔除（悬挂容忍，设计 §6）。\n\t\t\tfileNames = [];\n\t\t}\n\t\tconst files = new Map<string, number>();\n\t\tfor (const file of fileNames) {\n\t\t\tif (!isSessionFileName(file)) continue;\n\t\t\tsignal?.throwIfAborted();\n\t\t\ttry {\n\t\t\t\tfiles.set(file, (await stat(join(sessionsRoot, entry.name, file))).mtimeMs);\n\t\t\t} catch {\n\t\t\t\t// 本轮视同缺席。\n\t\t\t}\n\t\t}\n\t\tdiskDirs.set(entry.name, files);\n\t}\n\n\tlet changed = false;\n\n\tfor (const [dir, files] of diskDirs) {\n\t\tfor (const [file, mtimeMs] of files) {\n\t\t\tconst existing = findSessionEntry(state, dir, file);\n\t\t\tif (existing && existing.file_mtime_ms !== undefined && existing.file_mtime_ms === mtimeMs) continue;\n\t\t\tsignal?.throwIfAborted();\n\t\t\tconst info = await buildInfo(join(sessionsRoot, dir, file));\n\t\t\tif (!info) {\n\t\t\t\tif (existing) {\n\t\t\t\t\t// 文件已不再解析为会话（损坏/改写）：剔除陈旧条目。\n\t\t\t\t\tstate.sessions = state.sessions.filter((candidate) => candidate !== existing);\n\t\t\t\t\tchanged = true;\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\taddSessionFromInfo(state, dir, file, info, mtimeMs);\n\t\t\tchanged = true;\n\t\t}\n\t}\n\n\tconst keptSessions = state.sessions.filter((entry) => diskDirs.get(entry.dir)?.has(entry.file));\n\tif (keptSessions.length !== state.sessions.length) {\n\t\tstate.sessions = keptSessions;\n\t\tchanged = true;\n\t}\n\n\tconst keptProjects = state.projects.filter((project) => diskDirs.has(project.dir));\n\tif (keptProjects.length !== state.projects.length) {\n\t\tstate.projects = keptProjects;\n\t\tchanged = true;\n\t}\n\n\treturn changed;\n}\n\n/**\n * listAll 默认布局分支的索引读路径。返回 undefined 表示索引层意外失败（IO 等），\n * 调用方应回退到旧全量扫描（fail-open，设计 §5）；中止按惯例抛 AbortError。\n */\nexport async function listSessionsViaIndex(input: ListSessionsViaIndexInput): Promise<SessionInfo[] | undefined> {\n\tconst { sessionsRoot, buildInfo, scanAll, onHit, signal } = input;\n\ttry {\n\t\tsignal?.throwIfAborted();\n\t\tconst indexPath = getSessionIndexPath();\n\t\tlet state: SessionIndexFile;\n\t\tif (pendingFlush?.indexPath === indexPath) {\n\t\t\t// 节流窗口内已积累的更新是对账基准：对账落盘不得把窗口内更新回退覆盖。\n\t\t\tstate = pendingFlush.state;\n\t\t} else {\n\t\t\tconst fromDisk = readIndexFile(indexPath);\n\t\t\tif (fromDisk === null) {\n\t\t\t\t// 缺失/损坏/版本不符 → 旧扫描全量重建并落盘（与旧行为同价，设计 §5.1）。\n\t\t\t\tconst sessions = await scanAll();\n\t\t\t\twriteStateSync(indexPath, await stateFromSessions(sessionsRoot, sessions));\n\t\t\t\treturn sessions;\n\t\t\t}\n\t\t\tstate = fromDisk;\n\t\t}\n\t\tconst changed = await reconcileIndex(sessionsRoot, state, buildInfo, signal);\n\t\tif (changed) {\n\t\t\tif (pendingFlush?.indexPath === indexPath) clearPending();\n\t\t\twriteStateSync(indexPath, state);\n\t\t}\n\t\tconst sessions = sortedSessions(sessionsRoot, state);\n\t\tonHit?.(sessions);\n\t\treturn sessions;\n\t} catch {\n\t\tsignal?.throwIfAborted();\n\t\treturn undefined;\n\t}\n}\n"]}