@wuyaos/pi-sync 1.1.0 → 1.2.0

package/README.zh-CN.md

@@ -4,202 +4,211 @@
 
 [![pi package](https://img.shields.io/badge/pi-package-blue)](https://github.com/earendil-works/pi-coding-agent)
 [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![release](https://img.shields.io/github/v/release/wuyaos/pi-packages?display_name=tag&sort=semver)](https://github.com/wuyaos/pi-packages/releases)
 
-面向 [Pi](https://github.com/earendil-works/pi-coding-agent) 的 WebDAV 配置同步工具 —— 跨机器备份与恢复 **models**、**settings**、**skills**、**extensions** 以及选定的 **session 项目**。
+面向 [Pi](https://github.com/earendil-works/pi-coding-agent) 的 WebDAV 归档备份与恢复工具。
 
-在 Pi 里输入 `/sync`，从菜单选择操作。一台机器上传，另一台下载并恢复。
+`pi-sync` 为 Pi agent 数据、共享 Skills 和项目会话创建有版本的 `.tar.xz` 归档。它现在是**纯归档模式**：没有实时上传、每轮 hook、定时同步或多机合并冲突。
 
-<p align="center">
-  <img src="docs/sync-menu.png" alt="Pi WebDAV Synchronization 菜单" width="720" />
-</p>
+## 特性
 
-<p align="center"><sub><b>Pi WebDAV Synchronization</b> —— 输入 <code>/sync</code> 后的交互菜单</sub></p>
-
-## 为什么需要它
-
-如果你在多台 PC / WSL / 服务器上使用 Pi，手工重装 models、skills、extensions 很痛苦。`pi-sync` 会把 agent 主目录打包成带时间戳的 zip，上传到任意 WebDAV 目录，并在恢复时保留本地安全备份。
+- 直接打包 `~/.pi/agent`，不创建完整临时副本
+- 通过可配置黑名单排除可重装或临时目录
+- `~/.agents/skills` 独立、可选归档
+- 会话按项目独立归档
+- 退出 Pi 时自动归档当前项目
+- 一次操作备份或恢复所有已启用类别
+- `/sync` 菜单支持英文/简体中文即时切换
+- WebDAV 上传和下载使用流式传输，不把整个归档读入内存
+- 拒绝危险路径、符号链接、特殊节点和不安全恢复目标
 
 ## 安装
 
-需要 [Pi coding agent](https://github.com/earendil-works/pi-coding-agent)，以及可用的 WebDAV（TeraCLOUD、坚果云、Nextcloud、ownCloud、自建等）。
-
-`pi-sync` 是 [wuyaos/pi-packages](https://github.com/wuyaos/pi-packages) monorepo 的子包。直接安装整个仓库会加载所有子包：
+从 npm 安装：
 
 ```bash
-pi install git:github.com/wuyaos/pi-packages
+pi install npm:@wuyaos/pi-sync
 ```
 
-只想加载 **pi-sync** 时，在 `~/.pi/agent/settings.json` 用 object 形式筛选：
+或安装整个 monorepo：
 
-```json
-{
-  "packages": [
-    {
-      "source": "git:github.com/wuyaos/pi-packages",
-      "extensions": ["pi-sync/extensions/*.ts"],
-      "themes": []
-    }
-  ]
-}
+```bash
+pi install git:github.com/wuyaos/pi-packages
 ```
 
-然后重启 Pi，或执行 `/reload`。
+安装后重启 Pi 或执行 `/reload`。
 
 ## 用法
 
-在 Pi 中输入 **`/sync`**。没有命令行子命令 —— 全部通过交互菜单完成：
+运行 `/sync`，交互菜单提供：
 
-| 菜单项 | 作用 |
-|--------|------|
-| ☁️ **Upload Backup (Backup to cloud)** | 打包当前配置并上传到 WebDAV |
-| 📥 **Download Backup (Restore from cloud)** | 列出云端备份，下载并在确认后恢复 |
-| ⚙️ **Configure Sync Settings** | 配置 WebDAV 地址 / 用户 / 密码，以及同步范围 |
-| ❌ **Cancel** | 退出菜单 |
+- **全部备份** / **全部恢复（最新）**
+- 单独上传或恢复 **Pi 备份**
+- 单独上传或恢复 **Skills 备份**
+- 单独上传或恢复 **会话归档**
+- 配置备份设置
+- 中英文菜单切换
 
-TUI 提示：`↵` 选择 · `↑↓` 导航 · `Esc` 取消。
+首次运行若缺少 WebDAV 地址、用户名或密码，会自动打开配置向导。
 
-### 首次配置
+## 归档模型
 
-```bash
-# 1. 安装
-pi install git:github.com/wuyaos/pi-packages
+### Pi 备份
 
-# 2. 打开菜单（若尚未配置 WebDAV，会先进入设置向导）
-/sync
+Pi 归档直接打包 `~/.pi/agent`。默认黑名单：
 
-# 3. 如需修改：Configure Sync Settings
-#    填写 URL / 用户名 / 密码
-#    建议：密码填 $PI_WEBDAV_PASS，并在 shell 中 export 该环境变量
+```json
+["npm", "git", "sessions", "state", "tmp", "webui-rpc-supervisor", "vstack"]
+```
+
+这样会保留配置与扩展状态，同时排除可重装的包源码、临时扩展缓存、单独归档的会话、工作区历史、后台任务状态和 Web UI RPC 运行时 socket。除非显式加入黑名单，`config/sync.json` 也会进入归档。
+
+归档名称：
 
-# 4. 主力机 → Upload Backup (Backup to cloud)
-# 5. 新机器（安装并配置后）→ Download Backup (Restore from cloud)
+```text
+backup/pi/pi_agent_<platform>_<timestamp>.tar.xz
 ```
 
-### 会同步哪些内容
+### 共享 Skills 备份
 
-| 组件 | 默认 | 说明 |
-|------|------|------|
-| Config | 开 | `models.json`、`settings.json`、`auth.json` |
-| Skills | 开 | 整个 `~/.pi/agent/skills` |
-| Extensions | 开 | `~/.pi/agent/extensions`（zip 中会排除 sync 插件自身） |
-| Sessions | 关 | `~/.pi/agent/sessions/` 下按项目分目录的会话历史；在 **Configure Sync Settings → Session Projects** 中勾选要同步的项目 |
+`~/.agents/skills` 使用独立归档，默认关闭：
 
-可在 **Configure Sync Settings** 中分别开关。
+```text
+backup/skills/agent_skills_<timestamp>.tar.xz
+```
 
-### Sessions（可选）
+### 会话归档
 
-会话历史按项目 cwd 存放在 `~/.pi/agent/sessions/<projectDir>/`。**Session Projects** 子菜单会列出本机所有项目目录，勾选你想备份的那些。
+会话按项目归档，不再进行实时同步，也没有 `_latest.json` marker：
 
-- 在 **Configure Sync Settings** 中打开 **Backup Sessions**。
-- 打开 **Session Projects** 逐个勾选项目（可用 **Select All** / **Reset list** 快捷全选/清空）。
-- 列表模式（可切换）：
-  - **白名单模式**：只备份勾选的项目，空列表 = 全部不备份。
-  - **黑名单模式**：跳过勾选的项目，空列表 = 全部备份。
-- 恢复时会以 *合并* 方式写入本地 `~/.pi/agent/sessions/`——会话文件名为唯一的时间戳+uuid，不会覆盖或删除本地已有会话。
+```text
+backup/sessions/<projectDir>/sessions_<platform>_<timestamp>.tar.xz
+```
+
+项目选择支持：
 
-> 注意：项目目录名由项目路径编码而来，备份在 A 机器上制作，恢复到 B 机器时只会落到相同项目路径对应的项目目录中。
+- **白名单**：仅归档列表中的项目；空列表表示全部不归档。
+- **黑名单**：排除列表中的项目；空列表表示归档全部项目。
 
-### 备份文件名
+开启 `backupOnExit` 后，Pi 在 `session_shutdown` 时归档当前允许的项目；仍可通过 `/sync` 手动归档。
 
-归档文件形如：
+## WebDAV 目录结构
 
 ```text
-pi_sync_backup_2026-7-14_20260714120000_windows11.zip
+<webdavUrl>/
+└── backup/
+    ├── pi/
+    │   └── pi_agent_<platform>_<timestamp>.tar.xz
+    ├── skills/
+    │   └── agent_skills_<timestamp>.tar.xz
+    └── sessions/
+        └── <projectDir>/
+            └── sessions_<platform>_<timestamp>.tar.xz
+```
+
+`maxBackups` 在每个备份目录内独立生效；设为 `0` 表示全部保留。
+
+## 配置
+
+配置文件为 `~/.pi/agent/config/sync.json`：
+
+```json
+{
+  "webdavUrl": "https://example.com/dav/pi",
+  "webdavUser": "user",
+  "webdavPass": "$PI_WEBDAV_PASS",
+  "language": "zh",
+  "backupProviders": true,
+  "backupSessions": true,
+  "backupAgentSkills": false,
+  "piExcludePaths": ["npm", "git", "sessions", "state", "tmp", "webui-rpc-supervisor", "vstack"],
+  "backupOnExit": true,
+  "sessionProjectMode": "blacklist",
+  "sessionProjects": [],
+  "maxBackups": 10
+}
 ```
 
-末尾的平台标签（`windows11` / `windows10` / `macos` / `linux`）标明该备份由哪类主机生成。
+密码支持环境变量引用（如 `$PI_WEBDAV_PASS`）。未设置 `language` 时，会读取 `settings.json → piSwitch.language`，无法识别则默认英文。
 
-### 恢复时的安全机制
+## 恢复行为与安全
 
-- 覆盖前，已有配置文件会生成带时间戳的 `.bak` 副本
-- 已有 skills / extensions 目录会先改名为 `*-backup-<timestamp>`，再替换/合并
-- 恢复前会展示计划，并要求确认
-- 恢复成功后可选择 reload agent runtime，以应用 skills / extensions
+- 检查归档中的绝对路径和目录穿越。
+- 解压前拒绝符号链接和非普通文件节点。
+- 先解压到临时目录，再合并到目标目录。
+- 若目标路径包含符号链接或类型冲突则拒绝恢复。
+- Pi 恢复只改写归档中存在的文件，黑名单目录保持原样。
+- Skills 恢复前会把现有 `~/.agents/skills` 移到带时间戳的备份目录。
+- 会话恢复以合并方式写入 `~/.pi/agent/sessions`。
+- Pi 恢复前展示计划，完成后可选择 `/reload`。
 
-## 新机引导（Windows，尚未安装 Pi）
+归档可能包含 WebDAV 凭据、API Key、provider 配置及其他秘密，应把 WebDAV 存储视为敏感数据。
 
-若还没装 Pi，也可先用辅助脚本拉取最新 zip：
+## Windows 新机引导
+
+`pi-bootstrap.ps1` 会从 `backup/pi/` 下载最新归档，并合并到 `%USERPROFILE%\.pi\agent`：
+
+> **仅限可信归档：** 此 bootstrap 脚本不执行 pi-sync TypeScript 恢复流程的路径和符号链接校验。日常恢复请使用 `/sync`，仅在可信 WebDAV 端点和可信归档场景下使用该脚本。
 
 ```powershell
-# 优先用环境变量，避免密钥进入 shell 历史
-$env:PI_WEBDAV_URL  = "https://your-webdav.example/dav/Pi"
-$env:PI_WEBDAV_USER = "your-user"
-$env:PI_WEBDAV_PASS = "your-app-password"
+$env:PI_WEBDAV_URL  = "https://example.com/dav/pi"
+$env:PI_WEBDAV_USER = "user"
+$env:PI_WEBDAV_PASS = "app-password"
 .\pi-bootstrap.ps1
 ```
 
-或使用占位符一行命令（运行前请替换）：
+该脚本用于可信归档和新机恢复。恢复后需要安装/更新 packages，以重建被排除的 `npm/` 和 `git/` 目录。
 
-```powershell
-$url="https://your-webdav.example/dav/Pi"; $user="your-user"; $pass="your-app-password"
-$pair="$user`:$pass"; $auth=[Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes($pair))
-$resp=Invoke-RestMethod -Uri $url -Method PROPFIND -Headers @{Authorization="Basic $auth";Depth="1"} -ContentType "application/xml"
-$files=([regex]'<d:href>([^<]+)</d:href>').Matches($resp) | %{$_.Groups[1].Value} | ?{$_ -match "pi_sync_backup_.*\.zip$"} | Sort-Object -Descending
-$latest=$files[0]; $name=Split-Path $latest -Leaf
-Invoke-WebRequest -Uri "$url/$name" -Headers @{Authorization="Basic $auth"} -OutFile "$env:TEMP\$name"
-```
+## 故障排查
 
-之后安装 Pi，后续更新用 `/sync` → **Download Backup** 即可。
+| 现象 | 处理 |
+|---|---|
+| HTTP 401 / 403 | 检查 WebDAV 地址，并使用应用专用密码。 |
+| PROPFIND 失败 | 确认服务端支持 `Depth: 1` 的 WebDAV `PROPFIND`。 |
+| tar 报错 | 安装支持 xz 的 `tar`。 |
+| 退出时未备份 | 检查 `backupOnExit`、`backupSessions`、项目黑白名单和 WebDAV 凭据。 |
+| Pi 恢复后插件缺失 | 运行 `pi update --extensions`，或按 `settings.json` 重新安装 packages。 |
 
-## 安全建议
+## 开发验证
 
-- WebDAV 凭证保存在本机 `~/.pi/agent/sync_config.json`
-- 优先使用**应用专用密码**（不要用主账号密码）
-- 更推荐环境变量引用：界面里密码填 `$PI_WEBDAV_PASS`，再在 shell profile 中 export
-- 若开启相关选项，备份可能包含 `auth.json` / API key —— 请把 WebDAV 目录当敏感数据对待
-- 切勿把真实 WebDAV 地址与凭证提交进 git
+```bash
+cd /mnt/d/work/project/person/pi-packages
+node --import tsx --test pi-sync/extensions/sync/*.test.ts
+npm run typecheck
+```
 
-## 故障排查
+monorepo 类型检查可能报告其他包的既有错误；pi-sync 自身错误路径以 `pi-sync/` 开头。
 
-| 现象 | 处理 |
-|------|------|
-| HTTP 401 / 403 | 检查用户名密码；改用应用专用密码；确认 URL 含正确 DAV 路径 |
-| PROPFIND 失败 / 列表为空 | 服务端可能禁用 PROPFIND；换 WebDAV 提供商；确认允许 Depth:1 |
-| tar / zip 报错 | PATH 中需要可用的 `tar`（Windows 10+ 自带；Git Bash / WSL 亦可） |
-| 恢复覆盖了本地内容 | 在 agent 目录旁查找 `*.bak-*` 与 `skills-backup-*` / `extensions-backup-*` |
-| 恢复后插件不见了 | 重新执行 `pi install git:github.com/wuyaos/pi-packages` —— 归档会排除 sync 包自身 |
+### WebDAV 烟雾测试
 
-## 目录结构
+仓库内的 smoke harness 会创建唯一命名的临时 Pi 与会话归档，执行上传、列举、下载和校验，最后删除测试对象；它不会输出凭据，且默认拒绝写入：
 
-```text
-pi-sync/
-  package.json
-  LICENSE
-  README.md
-  README.zh-CN.md
-  pi-bootstrap.ps1
-  docs/
-    sync-menu.png       # /sync 菜单截图
-  extensions/
-    sync/
-      index.ts          # /sync 命令
-    _shared/
-      json-io.ts
-      enhanced-select.ts
-      spawn.ts
-      fetch-utils.ts
-      box-drawing.ts
+```bash
+cd /mnt/d/work/project/person/pi-packages
+PI_SYNC_SMOKE_WRITE=1 bash --noprofile --norc pi-sync/scripts/verify.sh
 ```
 
+`verify.sh` 还会执行单元测试、严格的 pi-sync 类型检查、扩展加载检查、发布白名单检查和 diff 检查。它读取 `~/.pi/agent/config/sync.json`；可通过 `PI_SYNC_SMOKE_PROJECT` 指定一个允许归档的本地会话目录名（如 `--home-user--`）。
+
 ## 更新日志
 
-### v1.0.1
+### v1.2.0
+
+- 从实时同步改为有版本的纯归档备份/恢复
+- 新增 Pi 主目录直接 tar 打包与黑名单排除
+- 分离 Pi、共享 Skills 和项目会话归档
+- 新增退出时会话归档、手动全部备份/全部恢复
+- 新增中英文菜单切换
+- 新增 WebDAV 流式传输、配置缓存和归档/恢复安全检查
+- 删除实时同步、定时同步、custom-path、memory 和 legacy 单体代码
+
+### v1.1.1
 
-- 备份 zip 文件名增加主机平台标签（`windows11` / `macos` / `linux` 等）
-- 从 bootstrap 脚本示例中移除真实凭证
-- 增加 MIT `LICENSE`，扩充 README（安全、恢复保护、故障排查、菜单截图）
+- 缓存 WebDAV 目录创建结果与已加载配置，减少重复 I/O
 
 ### v1.0.0
 
-- 首次公开发布：基于 WebDAV 的交互式 `/sync` 菜单
-  - Upload Backup · Download Backup · Configure Sync Settings
-- Windows 新机引导脚本
+- 初始 WebDAV 备份/恢复版本
 
 ## 许可证
 
 MIT — 见 [LICENSE](./LICENSE)。
-
-## 致谢
-
-本开源项目已链接并获 [LINUX DO](https://linux.do) 社区认可。

package/extensions/sync/archive.ts

@@ -4,12 +4,10 @@ import * as path from "node:path";
 import { runCommand } from "../_shared/spawn";
 import {
   AGENT_DIR,
-  AGENT_ROOT_MARKDOWN_FILES,
   AGENT_SKILLS_DIR,
-  MEMORY_MARKDOWN_FILES,
   SESSIONS_DIR,
   ensureDir,
-  isProjectAllowed,
+  normalizePiExcludePaths,
   type ManifestFile,
   type SyncConfig,
 } from "./config";
@@ -41,9 +39,17 @@ export async function runTar(args: string[], options: { capture?: boolean; timeo
   return options.capture ? result.stdout : "";
 }
 
+function lstatRegularOrDirectory(src: string): fs.Stats {
+  const stats = fs.lstatSync(src);
+  if (stats.isSymbolicLink() || (!stats.isFile() && !stats.isDirectory())) {
+    throw new Error(`Refusing unsafe filesystem entry: ${src}`);
+  }
+  return stats;
+}
+
 export function copyRecursiveSync(src: string, dest: string): void {
   if (!fs.existsSync(src)) return;
-  const stats = fs.statSync(src);
+  const stats = lstatRegularOrDirectory(src);
   if (stats.isDirectory()) {
     ensureDir(dest);
     for (const child of fs.readdirSync(src)) copyRecursiveSync(path.join(src, child), path.join(dest, child));
@@ -55,7 +61,7 @@ export function copyRecursiveSync(src: string, dest: string): void {
 
 export function copyRecursiveSyncFiltered(src: string, dest: string, include: (name: string, isDirectory: boolean) => boolean): void {
   if (!fs.existsSync(src)) return;
-  const stats = fs.statSync(src);
+  const stats = lstatRegularOrDirectory(src);
   if (!include(path.basename(src), stats.isDirectory())) return;
   if (stats.isDirectory()) {
     ensureDir(dest);
@@ -68,12 +74,18 @@ export function copyRecursiveSyncFiltered(src: string, dest: string, include: (n
 
 export function collectManifest(dir: string, archivePrefix: string, sourcePrefix: string, files: ManifestFile[]): void {
   if (!fs.existsSync(dir)) return;
+  const stats = lstatRegularOrDirectory(dir);
+  if (stats.isFile()) {
+    files.push({ archive: archivePrefix, source: sourcePrefix });
+    return;
+  }
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const archivePath = `${archivePrefix}/${entry.name}`;
     const sourcePath = sourcePrefix ? `${sourcePrefix}/${entry.name}` : entry.name;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) collectManifest(full, archivePath, sourcePath, files);
-    else files.push({ archive: archivePath, source: sourcePath });
+    else if (entry.isFile()) files.push({ archive: archivePath, source: sourcePath });
+    else throw new Error(`Refusing unsafe filesystem entry: ${full}`);
   }
 }
 
@@ -98,27 +110,36 @@ export async function listArchiveEntries(archivePath: string): Promise<string[]>
     .filter((entry) => entry && entry !== ".");
 }
 
+/**
+ * `tar -t` only prints names, so it cannot distinguish regular files from
+ * links or device nodes. Ask tar for the entry type before extraction.
+ * The POSIX tar permission field starts with `-` (file) or `d` (directory);
+ * every other type is rejected.
+ */
+export async function validateArchiveEntryTypes(archivePath: string): Promise<void> {
+  const lines = (await runTar(["-t", "-v", "-f", archivePath], { capture: true }))
+    .split(/\r?\n/)
+    .filter(Boolean);
+  if (lines.length === 0) throw new Error("Backup archive is empty or unreadable");
+  for (const line of lines) {
+    const entryType = line[0];
+    if (entryType !== "-" && entryType !== "d") {
+      throw new Error(`Unsafe archive entry type rejected: ${entryType ?? "unknown"}`);
+    }
+  }
+}
+
 export function validateArchiveEntries(entries: string[]): void {
-  const allowed = new Set(["config", "skills", "extensions", "sessions", "memory", "agent-skills", "manifest.json"]);
-  const legacyConfigFiles = new Set(["models.json", "settings.json", "auth.json"]);
-  const rootMarkdownFiles = new Set<string>(AGENT_ROOT_MARKDOWN_FILES);
   if (entries.length === 0) throw new Error("Backup archive is empty or unreadable");
   for (const entry of entries) {
     const parts = entry.split("/");
-    if (entry.startsWith("/") || /^[a-zA-Z]:\//.test(entry) || parts.includes("..") || !allowed.has(parts[0]!)) {
+    if (
+      entry.startsWith("/")
+      || /^[a-zA-Z]:\//.test(entry)
+      || parts.some((part) => !part || part === "." || part === "..")
+    ) {
       throw new Error(`Unsafe archive path rejected: ${entry}`);
     }
-    if (parts[0] !== "config" || !parts[1]) continue;
-    if (parts[1] === "root") {
-      if (!parts[2]) continue;
-      if (parts.length !== 3 || (!parts[2].endsWith(".json") && !rootMarkdownFiles.has(parts[2]))) {
-        throw new Error(`Unexpected root config file rejected: ${entry}`);
-      }
-    } else if (parts[1] === "sub") {
-      continue;
-    } else if (parts.length !== 2 || !legacyConfigFiles.has(parts[1])) {
-      throw new Error(`Unexpected config file rejected: ${entry}`);
-    }
   }
 }
 
@@ -127,67 +148,53 @@ export async function packTemporaryArchive(tempDir: string, archivePath: string)
   await runTar(["-J", "-c", "-f", archivePath, "-C", tempDir, "."]);
 }
 
-export async function createConfigZip(config: SyncConfig, archivePath: string): Promise<string[]> {
-  const tempDir = path.join(os.tmpdir(), `pi_config_temp_${Date.now()}`);
-  const rootDir = path.join(tempDir, "config", "root");
-  const subDir = path.join(tempDir, "config", "sub");
-  const manifest: ManifestFile[] = [];
-  const contents: string[] = [];
-  ensureDir(rootDir);
-  ensureDir(subDir);
-  try {
-    if (config.backupProviders) {
-      const rootNames = fs.readdirSync(AGENT_DIR).filter((name) => name.endsWith(".json"));
-      for (const name of AGENT_ROOT_MARKDOWN_FILES) if (!rootNames.includes(name)) rootNames.push(name);
-      for (const name of rootNames) {
-        const src = path.join(AGENT_DIR, name);
-        if (!fs.existsSync(src) || !fs.statSync(src).isFile()) continue;
-        fs.copyFileSync(src, path.join(rootDir, name));
-        manifest.push({ archive: `config/root/${name}`, source: name });
-        contents.push(`Config: ${name}`);
-      }
-      const configDir = path.join(AGENT_DIR, "config");
-      if (fs.existsSync(configDir)) {
-        copyRecursiveSync(configDir, subDir);
-        collectManifest(subDir, "config/sub", "config", manifest);
-        contents.push("Config directory");
-      }
-    }
-    if (config.backupExtensions) {
-      const source = path.join(AGENT_DIR, "extensions");
-      const dest = path.join(tempDir, "extensions");
-      if (fs.existsSync(source)) {
-        copyRecursiveSync(source, dest);
-        fs.rmSync(path.join(dest, "sync"), { recursive: true, force: true });
-        collectManifest(dest, "extensions", "extensions", manifest);
-        contents.push("Extensions directory");
-      }
-    }
-    if (manifest.length === 0) throw new Error("No config or extension files found to back up.");
-    writeManifest(tempDir, AGENT_DIR, manifest);
-    await packTemporaryArchive(tempDir, archivePath);
-    return contents;
-  } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
+function isExcluded(relativePath: string, exclusions: readonly string[]): boolean {
+  return exclusions.some((excluded) => relativePath === excluded || relativePath.startsWith(`${excluded}/`));
 }
 
-export async function createMemoryZip(archivePath: string): Promise<string[]> {
-  const sourceDir = path.join(AGENT_DIR, "pi-hermes-memory");
-  const tempDir = path.join(os.tmpdir(), `pi_memory_temp_${Date.now()}`);
-  const destDir = path.join(tempDir, "memory");
-  const manifest: ManifestFile[] = [];
-  ensureDir(destDir);
-  try {
-    for (const name of MEMORY_MARKDOWN_FILES) {
-      const src = path.join(sourceDir, name);
-      if (!fs.existsSync(src)) continue;
-      fs.copyFileSync(src, path.join(destDir, name));
-      manifest.push({ archive: `memory/${name}`, source: `pi-hermes-memory/${name}` });
+function validatePiAgentTree(sourceDir: string, exclusions: readonly string[]): number {
+  const root = lstatRegularOrDirectory(sourceDir);
+  if (!root.isDirectory()) throw new Error(`Pi agent path is not a directory: ${sourceDir}`);
+  let fileCount = 0;
+  const visit = (dir: string, relativeDir: string): void => {
+    for (const name of fs.readdirSync(dir)) {
+      const relativePath = relativeDir ? `${relativeDir}/${name}` : name;
+      if (isExcluded(relativePath, exclusions)) continue;
+      const fullPath = path.join(dir, name);
+      const stats = lstatRegularOrDirectory(fullPath);
+      if (stats.isDirectory()) visit(fullPath, relativePath);
+      else fileCount += 1;
     }
-    if (manifest.length === 0) throw new Error("No durable pi-hermes-memory markdown files found.");
-    writeManifest(tempDir, AGENT_DIR, manifest);
-    await packTemporaryArchive(tempDir, archivePath);
-    return manifest.map((item) => `Memory: ${path.basename(item.source)}`);
-  } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
+  };
+  visit(sourceDir, "");
+  return fileCount;
+}
+
+/**
+ * Pack ~/.pi/agent directly without first copying it to a staging directory.
+ * A lightweight filesystem scan rejects links/special nodes before tar runs;
+ * excluded install/state trees are skipped during both scan and compression.
+ */
+export async function createPiAgentZip(
+  config: Pick<SyncConfig, "piExcludePaths">,
+  archivePath: string,
+  sourceDir = AGENT_DIR,
+): Promise<string[]> {
+  const source = path.resolve(sourceDir);
+  const output = path.resolve(archivePath);
+  if (output === source || output.startsWith(`${source}${path.sep}`)) {
+    throw new Error("Pi backup archive must be written outside ~/.pi/agent.");
+  }
+  const exclusions = normalizePiExcludePaths(config.piExcludePaths);
+  const fileCount = validatePiAgentTree(source, exclusions);
+  if (fileCount === 0) throw new Error("No Pi agent files found to back up.");
+  const excludeArgs = exclusions.map((relativePath) => `--exclude=./${relativePath}`);
+  await yieldToUI();
+  await runTar(["-J", "-c", "-f", output, ...excludeArgs, "-C", source, "."]);
+  return [
+    `Pi agent: ${fileCount} file(s)`,
+    `Excluded: ${exclusions.length ? exclusions.join(", ") : "none"}`,
+  ];
 }
 
 export async function createAgentSkillsZip(archivePath: string): Promise<string[]> {
@@ -220,45 +227,3 @@ export async function createSessionsArchiveZip(projectDir: string, archivePath:
     return [`Sessions: ${projectDir} (${manifest.length} file(s))`];
   } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
 }
-
-export async function createLegacyZip(config: SyncConfig, archivePath: string): Promise<string[]> {
-  const tempDir = path.join(os.tmpdir(), `pi_sync_temp_${Date.now()}`);
-  const manifest: ManifestFile[] = [];
-  const contents: string[] = [];
-  ensureDir(tempDir);
-  try {
-    if (config.backupProviders) {
-      const configDir = path.join(tempDir, "config");
-      ensureDir(configDir);
-      for (const name of ["models.json", "settings.json", "auth.json"]) {
-        const src = path.join(AGENT_DIR, name);
-        if (!fs.existsSync(src)) continue;
-        fs.copyFileSync(src, path.join(configDir, name));
-        manifest.push({ archive: `config/${name}`, source: name });
-        contents.push(`Config: ${name}`);
-      }
-    }
-    if (config.backupSkills) {
-      const src = path.join(AGENT_DIR, "skills"), dest = path.join(tempDir, "skills");
-      if (fs.existsSync(src)) { copyRecursiveSync(src, dest); collectManifest(dest, "skills", "skills", manifest); contents.push("Skills Directory"); }
-    }
-    if (config.backupExtensions) {
-      const src = path.join(AGENT_DIR, "extensions"), dest = path.join(tempDir, "extensions");
-      if (fs.existsSync(src)) { copyRecursiveSync(src, dest); fs.rmSync(path.join(dest, "sync"), { recursive: true, force: true }); collectManifest(dest, "extensions", "extensions", manifest); contents.push("Extensions Directory"); }
-    }
-    if (config.backupSessions) {
-      for (const entry of fs.existsSync(SESSIONS_DIR) ? fs.readdirSync(SESSIONS_DIR, { withFileTypes: true }) : []) {
-        if (!entry.isDirectory()) continue;
-        if (!isProjectAllowed(entry.name, config)) continue;
-        const dest = path.join(tempDir, "sessions", entry.name);
-        copyRecursiveSync(path.join(SESSIONS_DIR, entry.name), dest);
-      }
-      const sessionsDest = path.join(tempDir, "sessions");
-      if (fs.existsSync(sessionsDest)) { collectManifest(sessionsDest, "sessions", "sessions", manifest); contents.push("Sessions"); }
-    }
-    if (manifest.length === 0) throw new Error("No components selected or found to backup.");
-    writeManifest(tempDir, AGENT_DIR, manifest);
-    await packTemporaryArchive(tempDir, archivePath);
-    return contents;
-  } finally { fs.rmSync(tempDir, { recursive: true, force: true }); }
-}