@davideasden/pi-undo 0.2.31 → 0.2.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,7 +19,7 @@ Each completed agent run creates a checkpoint that captures both the Pi session
19
19
 
20
20
  ## Requirements
21
21
 
22
- - Pi `0.86.1` 或更高版本(已在 0.86.1 上验证)。`0.84.4` 及更早版本不再受支持,也不在 CI 中测试:早期版本的会话树与扩展生命周期行为不同,不保证撤回语义正确。
22
+ - Pi `1.2.0` 或更高版本(已在 1.2.0 上验证,见 [Pi 1.2.0 兼容验证记录](docs/pi-1.2.0-validation.md))。`1.1.x` 及更早版本不再受支持,也不在 CI 中测试:早期版本的扩展生命周期行为不同(例如 `before_agent_start` 的触发范围与会话 busy 语义),不保证撤回语义正确。历史验证记录见 [Pi 0.86.1 撤回修复与验证记录](docs/pi-0.86.1-validation.md)。
23
23
  - Node.js `22.19.0` or later.
24
24
  - Git available on `PATH` (used internally for content-addressed snapshots).
25
25
 
@@ -167,7 +167,7 @@ recovery_required
167
167
 
168
168
  本机 macOS arm64 的三次 undo 中位数:3,000 包/1 文件从 1,976 ms 降至 924 ms,10,000 包/1 文件从 5,857 ms 降至 2,755 ms;100 文件的子目录撤销从 517 ms 降至 180 ms,混合撤销从 711 ms 降至 186 ms。测量方法和限制见 [原生性能验证记录](docs/native-performance.md)。
169
169
 
170
- 可通过真实 Pi 0.86.1 SDK 和离线 faux provider 运行大型工作区基准;它覆盖 3,000/10,000 个依赖包、修改 1/100 个文件,每组撤回三次并验证重做:
170
+ 可通过真实 Pi 1.2.0 SDK 和离线 faux provider 运行大型工作区基准;它覆盖 3,000/10,000 个依赖包、修改 1/100 个文件,每组撤回三次并验证重做:
171
171
 
172
172
  ```bash
173
173
  PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davideasden/pi-undo",
3
- "version": "0.2.31",
3
+ "version": "0.2.33",
4
4
  "description": "Persistent workspace undo and redo for Pi",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,16 +47,16 @@
47
47
  "pack:dry-run": "npm pack --dry-run"
48
48
  },
49
49
  "peerDependencies": {
50
- "@earendil-works/pi-coding-agent": ">=0.86.1",
51
- "@earendil-works/pi-tui": ">=0.86.1"
50
+ "@earendil-works/pi-coding-agent": ">=1.2.0",
51
+ "@earendil-works/pi-tui": ">=1.2.0"
52
52
  },
53
53
  "dependencies": {
54
54
  "proper-lockfile": "4.1.2"
55
55
  },
56
56
  "devDependencies": {
57
- "@earendil-works/pi-ai": "0.86.1",
58
- "@earendil-works/pi-coding-agent": "0.86.1",
59
- "@earendil-works/pi-tui": "0.86.1",
57
+ "@earendil-works/pi-ai": "1.2.0",
58
+ "@earendil-works/pi-coding-agent": "1.2.0",
59
+ "@earendil-works/pi-tui": "1.2.0",
60
60
  "@types/node": "24.12.4",
61
61
  "@types/proper-lockfile": "4.1.4",
62
62
  "typescript": "5.9.3",
@@ -100,6 +100,8 @@ interface VisibleLeaf {
100
100
  readonly kind: "file" | "symlink";
101
101
  readonly mode: number;
102
102
  readonly fingerprint: string;
103
+ /** 不含 ctime,用于把 macOS 元数据写入与内容或路径变化区分开。 */
104
+ readonly stableFingerprint?: string;
103
105
  readonly changedAtNs: bigint;
104
106
  readonly cacheable: boolean;
105
107
  }
@@ -136,6 +138,7 @@ interface PersistedLeafCacheEntry {
136
138
  readonly kind: "file" | "symlink";
137
139
  readonly mode: number;
138
140
  readonly fingerprint: string;
141
+ readonly stableFingerprint?: string;
139
142
  readonly cacheable: boolean;
140
143
  readonly objectId: string;
141
144
  readonly changedAtNs: string;
@@ -515,6 +518,7 @@ export class SnapshotStore {
515
518
  const cache = this.visibleLeafCache.get(gitDirectory);
516
519
  if (cache === undefined) return false;
517
520
  const entriesByPath = new Map(entries.map((entry) => [entry.relativePath, entry]));
521
+ const expectedObjectIds = new Map(entries.map((entry) => [entry.relativePath, entry.objectId]));
518
522
  for (const leaf of leaves) {
519
523
  const entry = entriesByPath.get(leaf.relativePath);
520
524
  const cached = cache.get(leaf.relativePath);
@@ -548,7 +552,13 @@ export class SnapshotStore {
548
552
  ignoredPresentPaths,
549
553
  })) return false;
550
554
  // metadata 初检与最终复核之间若有变化,放弃 baseline,回退完整 capture。
551
- await this.assertVisibleLeavesUnchanged(absoluteRoot, leaves, transactionDirectory);
555
+ await this.assertVisibleLeavesUnchanged(
556
+ absoluteRoot,
557
+ leaves,
558
+ transactionDirectory,
559
+ expectedObjectIds,
560
+ environment,
561
+ );
552
562
  }
553
563
  return true;
554
564
  } catch (error) {
@@ -1219,7 +1229,8 @@ export class SnapshotStore {
1219
1229
  ...batch.map((leaf) => leaf.relativePath),
1220
1230
  ], { cwd, env: environment });
1221
1231
  const hashes = parseObjectIdLines(output, batch.length);
1222
- await this.assertVisibleLeavesUnchanged(cwd, batch);
1232
+ const batchObjectIds = new Map(batch.map((leaf, index) => [leaf.relativePath, hashes[index]!]));
1233
+ await this.assertVisibleLeavesUnchanged(cwd, batch, undefined, batchObjectIds, environment);
1223
1234
  return batch.map((leaf, index) => [leaf.relativePath, hashes[index]!] as const);
1224
1235
  });
1225
1236
  for (const batch of hashedBatches) {
@@ -1240,7 +1251,7 @@ export class SnapshotStore {
1240
1251
  throw new SnapshotStoreError("capture_failed", `文件对象 materialize 失败:${leaf.relativePath}`);
1241
1252
  }
1242
1253
  await assertNoSymlinkEscape(cwd, leaf.relativePath);
1243
- await this.assertVisibleLeafUnchanged(cwd, leaf);
1254
+ await this.assertVisibleLeafUnchanged(cwd, leaf, objectId, environment);
1244
1255
  objectIds.set(leaf.relativePath, objectId);
1245
1256
  }
1246
1257
  for (const indexInput of indexInfoBatches(leaves, objectIds)) {
@@ -1250,7 +1261,7 @@ export class SnapshotStore {
1250
1261
  stdin: indexInput,
1251
1262
  });
1252
1263
  }
1253
- await this.assertVisibleLeavesUnchanged(cwd, leaves, requestDirectory);
1264
+ await this.assertVisibleLeavesUnchanged(cwd, leaves, requestDirectory, objectIds, environment);
1254
1265
  return { leaves, objectIds, verifiedAtNs: BigInt(Date.now()) * 1_000_000n };
1255
1266
  }
1256
1267
 
@@ -1303,6 +1314,7 @@ export class SnapshotStore {
1303
1314
  kind: entry.kind,
1304
1315
  mode: entry.mode,
1305
1316
  fingerprint: entry.fingerprint,
1317
+ stableFingerprint: entry.stableFingerprint,
1306
1318
  cacheable: entry.cacheable,
1307
1319
  changedAtNs: BigInt(entry.changedAtNs),
1308
1320
  objectId: entry.objectId,
@@ -1326,6 +1338,7 @@ export class SnapshotStore {
1326
1338
  kind: leaf.kind,
1327
1339
  mode: leaf.mode,
1328
1340
  fingerprint: leaf.fingerprint,
1341
+ stableFingerprint: leaf.stableFingerprint,
1329
1342
  cacheable: leaf.cacheable,
1330
1343
  objectId: leaf.objectId,
1331
1344
  changedAtNs: leaf.changedAtNs.toString(),
@@ -1351,6 +1364,8 @@ export class SnapshotStore {
1351
1364
  cwd: string,
1352
1365
  leaves: readonly VisibleLeaf[],
1353
1366
  requestDirectory?: string,
1367
+ expectedObjectIds?: ReadonlyMap<string, string>,
1368
+ environment?: Readonly<Record<string, string | undefined>>,
1354
1369
  ): Promise<void> {
1355
1370
  if (leaves.length === 0) return;
1356
1371
  const paths = leaves.map((leaf) => leaf.relativePath);
@@ -1359,32 +1374,105 @@ export class SnapshotStore {
1359
1374
  await assertNoSymlinkParents(cwd, paths);
1360
1375
  const inspected = await this.inspectNativeMetadataBatches(cwd, paths, requestDirectory);
1361
1376
  if (inspected !== undefined) {
1377
+ const contentChecks: VisibleLeaf[] = [];
1362
1378
  for (let index = 0; index < leaves.length; index += 1) {
1363
1379
  const leaf = leaves[index]!;
1364
1380
  const metadata = nativeVisibleLeafMetadata(inspected[index]!);
1365
- if (metadata === null || visibleLeafFingerprint(metadata) !== leaf.fingerprint) {
1381
+ if (metadata === null || visibleLeafStableFingerprint(metadata) !== leaf.stableFingerprint) {
1366
1382
  throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1367
1383
  }
1384
+ if (visibleLeafFingerprint(metadata) !== leaf.fingerprint) contentChecks.push(leaf);
1368
1385
  }
1386
+ await mapConcurrentOrdered(contentChecks, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
1387
+ this.assertVisibleLeafContentUnchanged(
1388
+ cwd,
1389
+ leaf,
1390
+ expectedObjectIds?.get(leaf.relativePath),
1391
+ environment,
1392
+ ));
1369
1393
  await assertNoSymlinkParents(cwd, paths);
1370
1394
  return;
1371
1395
  }
1372
1396
  await mapConcurrentOrdered(leaves, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
1373
- this.assertVisibleLeafUnchanged(cwd, leaf));
1397
+ this.assertVisibleLeafUnchanged(
1398
+ cwd,
1399
+ leaf,
1400
+ expectedObjectIds?.get(leaf.relativePath),
1401
+ environment,
1402
+ ));
1374
1403
  await assertNoSymlinkParents(cwd, paths);
1375
1404
  return;
1376
1405
  }
1377
1406
  await assertNoSymlinkParents(cwd, paths);
1378
1407
  await mapConcurrentOrdered(leaves, FILE_SYSTEM_INSPECTION_CONCURRENCY, (leaf) =>
1379
- this.assertVisibleLeafUnchanged(cwd, leaf));
1408
+ this.assertVisibleLeafUnchanged(
1409
+ cwd,
1410
+ leaf,
1411
+ expectedObjectIds?.get(leaf.relativePath),
1412
+ environment,
1413
+ ));
1380
1414
  }
1381
1415
 
1382
- private async assertVisibleLeafUnchanged(cwd: string, leaf: VisibleLeaf): Promise<void> {
1416
+ private async assertVisibleLeafUnchanged(
1417
+ cwd: string,
1418
+ leaf: VisibleLeaf,
1419
+ expectedObjectId?: string,
1420
+ environment?: Readonly<Record<string, string | undefined>>,
1421
+ ): Promise<void> {
1383
1422
  const metadata = await lstat(join(cwd, ...leaf.relativePath.split("/")), { bigint: true }).catch((error) => {
1384
1423
  if (hasErrorCode(error, "ENOENT")) return null;
1385
1424
  throw error;
1386
1425
  });
1387
- if (metadata === null || visibleLeafFingerprint(visibleLeafMetadataFromStats(metadata)) !== leaf.fingerprint) {
1426
+ if (metadata === null) {
1427
+ throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1428
+ }
1429
+ const visibleMetadata = visibleLeafMetadataFromStats(metadata);
1430
+ if (visibleLeafFingerprint(visibleMetadata) === leaf.fingerprint) return;
1431
+ if (visibleLeafStableFingerprint(visibleMetadata) !== leaf.stableFingerprint) {
1432
+ throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1433
+ }
1434
+ // 首次 hash 前还没有可信对象 ID;稳定元数据不变时先继续,hash 后再做内容证明。
1435
+ if (expectedObjectId === undefined || environment === undefined) return;
1436
+ await this.assertVisibleLeafContentUnchanged(cwd, leaf, expectedObjectId, environment);
1437
+ }
1438
+
1439
+ /** ctime 单独变化时重新核验内容,并确认内容核验期间稳定元数据没有漂移。 */
1440
+ private async assertVisibleLeafContentUnchanged(
1441
+ cwd: string,
1442
+ leaf: VisibleLeaf,
1443
+ expectedObjectId: string | undefined,
1444
+ environment: Readonly<Record<string, string | undefined>> | undefined,
1445
+ ): Promise<void> {
1446
+ if (expectedObjectId === undefined || environment === undefined) {
1447
+ throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1448
+ }
1449
+ let objectId: string;
1450
+ if (leaf.kind === "symlink") {
1451
+ await assertNoSymlinkEscape(cwd, leaf.relativePath);
1452
+ const linkText = await readlink(join(cwd, ...leaf.relativePath.split("/")), { encoding: "buffer" });
1453
+ decodeUtf8(linkText, "symlink target 不是可无损表示的 UTF-8");
1454
+ objectId = (await this.runGit(["hash-object", "--stdin"], {
1455
+ cwd,
1456
+ env: environment,
1457
+ stdin: linkText,
1458
+ })).trim();
1459
+ } else {
1460
+ objectId = (await this.runGit(["hash-object", "--no-filters", "--", leaf.relativePath], {
1461
+ cwd,
1462
+ env: environment,
1463
+ })).trim();
1464
+ }
1465
+ if (!isObjectId(objectId) || objectId !== expectedObjectId) {
1466
+ throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1467
+ }
1468
+ const finalMetadata = await lstat(join(cwd, ...leaf.relativePath.split("/")), { bigint: true }).catch((error) => {
1469
+ if (hasErrorCode(error, "ENOENT")) return null;
1470
+ throw error;
1471
+ });
1472
+ if (
1473
+ finalMetadata === null ||
1474
+ visibleLeafStableFingerprint(visibleLeafMetadataFromStats(finalMetadata)) !== leaf.stableFingerprint
1475
+ ) {
1388
1476
  throw new SnapshotStoreError("capture_failed", `捕获期间工作区叶子已变化:${leaf.relativePath}`);
1389
1477
  }
1390
1478
  }
@@ -1473,6 +1561,7 @@ export class SnapshotStore {
1473
1561
  ? 0o120000
1474
1562
  : (metadata.mode & 0o111n) === 0n ? 0o100644 : 0o100755,
1475
1563
  fingerprint: visibleLeafFingerprint(metadata),
1564
+ stableFingerprint: visibleLeafStableFingerprint(metadata),
1476
1565
  changedAtNs: metadata.mtimeNs > metadata.ctimeNs ? metadata.mtimeNs : metadata.ctimeNs,
1477
1566
  cacheable,
1478
1567
  });
@@ -2126,6 +2215,7 @@ function samePersistedLeafCache(
2126
2215
  existing.kind !== entry.kind ||
2127
2216
  existing.mode !== entry.mode ||
2128
2217
  existing.fingerprint !== entry.fingerprint ||
2218
+ existing.stableFingerprint !== entry.stableFingerprint ||
2129
2219
  existing.cacheable !== entry.cacheable ||
2130
2220
  existing.objectId !== entry.objectId ||
2131
2221
  existing.changedAtNs !== entry.changedAtNs ||
@@ -2257,6 +2347,7 @@ function isPersistedLeafCacheFile(value: unknown): value is PersistedLeafCacheFi
2257
2347
  typeof candidate.mode !== "number" ||
2258
2348
  typeof candidate.fingerprint !== "string" ||
2259
2349
  typeof candidate.cacheable !== "boolean" ||
2350
+ (typeof candidate.stableFingerprint !== "undefined" && typeof candidate.stableFingerprint !== "string") ||
2260
2351
  typeof candidate.objectId !== "string" ||
2261
2352
  typeof candidate.changedAtNs !== "string" ||
2262
2353
  typeof candidate.verifiedAtNs !== "string" ||
@@ -2270,6 +2361,17 @@ function isPersistedLeafCacheFile(value: unknown): value is PersistedLeafCacheFi
2270
2361
  return true;
2271
2362
  }
2272
2363
 
2364
+ function visibleLeafStableFingerprint(metadata: VisibleLeafMetadata): string {
2365
+ return checksum(canonicalJson({
2366
+ kind: metadata.kind,
2367
+ dev: metadata.dev.toString(),
2368
+ ino: metadata.ino.toString(),
2369
+ mode: metadata.mode.toString(),
2370
+ size: metadata.size.toString(),
2371
+ mtimeNs: metadata.mtimeNs.toString(),
2372
+ }));
2373
+ }
2374
+
2273
2375
  function visibleLeafFingerprint(metadata: VisibleLeafMetadata): string {
2274
2376
  return checksum(canonicalJson({
2275
2377
  kind: metadata.kind,