sage-mem 2.1.18 → 2.1.20

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.18`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.20`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.18`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.20`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/client.js

@@ -978,6 +978,22 @@ const StarmapRuntime = (function (require, _react) {
 			return makeCanvas2DRenderer(canvasEl, layout, visBox, hoverBox);
 		}
 
+		/**
+		 * 星图动画的统一时钟（Q15）。
+		 *
+		 * rAF 回调的时间戳与 `performance.now()` 是**同一个原点**（单调、从页面加载起算），
+		 * 而 `Date.now()` 是 epoch 毫秒 —— 两套混用会让相位变成大负数。旧版入场动画就是这个
+		 * bug：`t0 = Date.now()` 去减 rAF 的 `ts`，`ts - t0` 恒为大负数 → 永远「入场没结束」，
+		 * 但每帧画完又不接着排帧，于是入场只画了一帧、相位还是负的。
+		 *
+		 * 星图里所有「过了多少毫秒」都走这里（freshness 那种墙钟判断除外，那本来就该用 Date.now）。
+		 */
+		function starmapNow() {
+			return (typeof performance !== "undefined" && performance && typeof performance.now === "function")
+				? performance.now()
+				: Date.now();
+		}
+
 		// ── 星图主体（canvas + 图例 + 详情面板）──
 		function StarMap(props) {
 			const ctx = props.ctx || appCtx;
@@ -1108,16 +1124,18 @@ const StarmapRuntime = (function (require, _react) {
 				if (!data || !layout || !canvasEl) return undefined;
 				const renderer = createRenderer(canvasEl, layout, visBox, hoverBox);
 				drawBox.renderer = renderer;
-				drawBox.t0 = Date.now();
+				// t0 与 rAF 的 ts 必须同一时钟（见 starmapNow）。旧版用 Date.now 当 t0，
+				// 于是相位是 epoch 级的大负数，入场窗口永远关不上。
+				drawBox.t0 = starmapNow();
 				renderer.render(0);
 
 				// ── 按需重绘（重做过一版）──
 				// 旧版是一个常驻 rAF 循环：只要星图页开着就永远满帧重画，后台标签页也一样，
 				// 而画面其实早就静止了。新的规矩只有三种情况会画：
 				//   1. 入场展示动画期间（约 1.3s，星点按诞生时间依次点亮）
-				//   2. 有人调 markDirty()（hover / 数据或筛选变化 / 尺寸变化）
+				//   2. 有人调 markDirty()（hover / 数据或筛选变化 / 尺寸变化 / 回放）
 				//   3. 诞生回放进行中
-				// 其余时间一帧都不画。另外帧率封顶 30fps，页面不可见时直接跳过。
+				// 其余时间一帧都不画。另外帧率封顶 30fps，页面不可见时暂停（回来再补一帧）。
 				const FRAME_MS = 1000 / 30;
 				const ENTRANCE_MS = 1300;
 				let raf = 0;
@@ -1126,26 +1144,51 @@ const StarmapRuntime = (function (require, _react) {
 				function schedule() {
 					if (!raf) raf = window.requestAnimationFrame(tick);
 				}
+				/** 还需要连续帧的两种状态：入场动画没走完 / 诞生回放激活。 */
+				function animating(ts) {
+					return (ts - drawBox.t0 < ENTRANCE_MS) || replayBox.active === true;
+				}
 				function tick(ts) {
 					raf = 0;
 					if (!drawBox.renderer) return;
-					if (ts - drawBox.t0 < ENTRANCE_MS || replayBox.active) dirty = true;
+					if (animating(ts)) dirty = true;
+					// 页面不可见：这一帧不画，也**不**再排下一帧（旧版直接 return，结果从后台
+					// 切回来就再也不画了）。visibilitychange 回到可见时会补一帧。
+					if (typeof document !== "undefined" && document && document.hidden) {
+						dirty = true;
+						return;
+					}
 					if (!dirty) return;
-					if (typeof document !== "undefined" && document.hidden) return;
 					if (ts - lastDraw < FRAME_MS) { schedule(); return; }
 					dirty = false;
 					lastDraw = ts;
 					drawBox.renderer.render((ts - drawBox.t0) / 1000);
+					// 入场 / 回放没结束就接着排下一帧；静止之后一帧都不排（不允许常驻空转）。
+					if (animating(ts)) schedule();
 				}
 				drawBox.markDirty = function () { dirty = true; schedule(); };
+				// 从后台标签页回来：补一帧（隐藏期间不排帧，靠这个事件唤醒）。
+				const onVisibility = function () {
+					if (typeof document === "undefined" || !document) return;
+					if (document.hidden) { dirty = true; return; }
+					dirty = true;
+					schedule();
+				};
+				if (typeof document !== "undefined" && document && typeof document.addEventListener === "function") {
+					document.addEventListener("visibilitychange", onVisibility);
+				}
 				schedule();
 
 				return () => {
 					window.cancelAnimationFrame(raf);
+					if (typeof document !== "undefined" && document && typeof document.removeEventListener === "function") {
+						document.removeEventListener("visibilitychange", onVisibility);
+					}
 					drawBox.renderer = null;
 					drawBox.markDirty = null;
 					replayBox.active = false;
 					window.cancelAnimationFrame(replayBox.raf);
+					replayBox.raf = 0;
 					if (renderer.destroy) renderer.destroy();
 				};
 			}, [data, layout, canvasEl, themeKey]);
@@ -1163,7 +1206,7 @@ const StarmapRuntime = (function (require, _react) {
 					if (drawBox.renderer.setGeometry) drawBox.renderer.setGeometry();
 					// 交给按需重绘那一套：下一帧画（<33ms），不再这里直接 render
 					if (drawBox.markDirty) drawBox.markDirty();
-					else drawBox.renderer.render((Date.now() - drawBox.t0) / 1000);
+					else drawBox.renderer.render((starmapNow() - drawBox.t0) / 1000);
 				}
 			}, [data, layout, kindsOn, query, showArchive]);
 
@@ -1298,7 +1341,9 @@ const StarmapRuntime = (function (require, _react) {
 			function stopReplay() {
 				replayBox.active = false;
 				window.cancelAnimationFrame(replayBox.raf);
+				replayBox.raf = 0;
 				if (drawBox.renderer && drawBox.renderer.setReveal) drawBox.renderer.setReveal(null);
+				// 停回放要回到「全亮」：markDirty 让绘制循环补这一帧。
 				if (drawBox.markDirty) drawBox.markDirty();
 				setReplaying(false);
 				setReplayDate(null);
@@ -1316,17 +1361,22 @@ const StarmapRuntime = (function (require, _react) {
 				window.cancelAnimationFrame(replayBox.raf);
 				const span = Math.max(mx - mn, 60000) + 2400;
 				const dur = 18000;
-				const t0 = Date.now();
+				let t0 = null;
 				replayBox.active = true;
 				setReplaying(true);
+				// 关键：回放期间由「按需绘制」那套逐帧重画。setReveal 只改渲染器的变量，
+				// 不标脏 / 不唤醒绘制循环的话屏幕上什么都不动（旧版就是这样，回放是空的）。
+				if (drawBox.markDirty) drawBox.markDirty();
 				let lastLabel = 0;
-				const tick = () => {
+				const tick = (ts) => {
 					if (!replayBox.active) return;
-					const p = Math.min(1, (Date.now() - t0) / dur);
+					// 进度也用 rAF 的单调时间戳，和绘制循环同一个时钟（旧版用 Date.now 又混了一次）。
+					if (t0 === null) t0 = ts;
+					const p = Math.min(1, (ts - t0) / dur);
 					const cur = mn - 1200 + span * p;
 					if (drawBox.renderer && drawBox.renderer.setReveal) drawBox.renderer.setReveal(cur);
-					if (Date.now() - lastLabel > 250) {
-						lastLabel = Date.now();
+					if (ts - lastLabel > 250) {
+						lastLabel = ts;
 						setReplayDate(Math.min(mx, cur));
 					}
 					if (p >= 1) { stopReplay(); return; }

package/lib/memory/util.js

@@ -4,7 +4,7 @@
 
 import { constants } from 'node:fs'
 import { randomUUID } from 'node:crypto'
-import { copyFile, link, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { chmod, copyFile, link, lstat, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
 
 /**
  * 统一告警出口。所有非 ENOENT 的失败都必须落到日志，绝不静默
@@ -46,6 +46,31 @@ async function renameWithRetry(from, to, attempts = 8) {
   }
 }
 
+/**
+ * 新建文件（写进本原语的那些记忆与状态）的默认 mode：**只对本人可读写**。
+ *
+ * 为什么是明确的 0600 而不是「umask 默认」（2026-10-31 外部审查 Q18）：记忆正文是隐私
+ * 内容，权限不该由开发机 / 服务器的 umask 环境决定（umask=022 时默认新建是 0644，
+ * 同机其它账号可读）。写进 `writeFileAtomic` 的既有文件一律继承原 mode，
+ * 所以这一条只影响**新建**。
+ */
+const NEW_FILE_MODE = 0o600
+
+/**
+ * 这次替换该用的 mode：**已有普通文件**继承它现在的权限位；新建文件用保守默认。
+ *
+ * ⚠️ 用 `lstat` 而不是 `stat`（2026-10-31 外部审查 Q18）：目标是符号链接时不该跟随 ——
+ * `stat` 会拿到链接指向的**外部**文件的权限，等于把记忆文件的权限交给别处的文件决定；
+ * 而 rename 之后被替换的是链接本身（不是穿透），本来也不该继承外部的 mode。
+ *
+ * @returns {Promise<number>} mode 位（含 setuid/setgid/sticky：`& 0o7777`）
+ */
+async function modeForTarget(target) {
+  const info = await lstat(target).catch(() => null)
+  if (!info || !info.isFile() || typeof info.mode !== 'number') return NEW_FILE_MODE
+  return info.mode & 0o7777
+}
+
 /**
  * 原子写：先写同目录临时文件，再 rename 覆盖目标。
  *
@@ -53,13 +78,28 @@ async function renameWithRetry(from, to, attempts = 8) {
  * 缺半边，这条记忆从此解析不出来、检索不到，而文件看上去还在。
  * 同卷 rename 是原子的：读方要么看到旧全文、要么看到新全文，不存在中间态。
  * 任何一步失败都不碰目标文件，**自己那份**临时文件收尾清掉。
+ *
+ * ⚠️ **权限继承**（2026-10-31 外部审查 Q18）：rename 替换的是**目录项**，新 inode
+ * 不会继承原文件的 mode。旧写法新建临时文件走默认 mode，于是一个被用户设成 0600 的
+ * 记忆，面板保存一次就变成 0644（umask=022），隐私被悄悄放宽，而且没有任何提示。
+ * 现在在 rename **之前**把 mode 贴到临时文件上：
+ *   - 已有普通文件 → 继承它现在的权限（用 lstat，不跟随符号链接）；
+ *   - 新建文件 → 明确的保守模式 `NEW_FILE_MODE`（0600，不随 umask 漂）。
+ * 先 `writeFile(tmp, …, { mode })` 让临时文件**一开始就不会比目标宽**，再 `chmod` 成精确值
+ * （writeFile 的 mode 会被 umask 掩掉一部分，比如 0660 & ~022 = 0640）。
+ * 任何一步失败都发生在 rename 之前 → 目标文件一个字节、一个权限位都不会动。
+ * Windows 上 chmod 是 no-op，这里不依赖它能生效（行为断言在 POSIX 上跑）。
  */
 export async function writeFileAtomic(target, content) {
   tmpSeq += 1
   const uniq = `${process.pid}-${Date.now().toString(36)}-${tmpSeq.toString(36)}-${Math.random().toString(36).slice(2, 8)}`
   const tmp = `${target}.${uniq}.tmp`
+  const mode = await modeForTarget(target)
   try {
-    await writeFile(tmp, content, 'utf8')
+    await writeFile(tmp, content, { encoding: 'utf8', mode })
+    // 精确落位：writeFile 传的 mode 受 umask 掩码，chmod 不受 —— 两者都做才既「不会更宽」
+    // 又「不会被收紧」。放在 rename 之前，失败时目标仍是原样。
+    await chmod(tmp, mode)
     await renameWithRetry(tmp, target)
   } finally {
     // rename 成功后 tmp 已不存在（ENOENT），失败时把它清掉不留垃圾。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.18",
+  "version": "2.1.20",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",