@gfgghgftgffg/amox-pi-sync 0.1.5 → 0.1.7

package/MAINTENANCE.md

@@ -5,15 +5,15 @@
 - Upstream: [MuratAitov/pi-sync](https://github.com/MuratAitov/pi-sync), npm `pi-sync-suite@0.1.1`.
 - Source ref: `npm:pi-sync-suite@0.1.1` (published source baseline, not the repository's moving HEAD).
 - Upstream MIT notice is preserved verbatim in `LICENSE`: Copyright (c) 2026 Murat.
-- Local package: `@gfgghgftgffg/amox-pi-sync@0.1.5`, standalone TypeScript entrypoint `index.ts` and `core.ts`; no runtime dependency on the original suite.
+- Local package: `@gfgghgftgffg/amox-pi-sync@0.1.7`, standalone TypeScript entrypoint `index.ts` and `core.ts`; no runtime dependency on the original suite.
 
 ## Scope
 
-Keep raw agent-data push/pull, safe relative include/exclude paths (sessions + missions by default), manual/background automatic sync, backups/restoration and diagnostics. No configuration sync/settings merging, Markdown/JSON exports, Environment Tools or Local Packages. Cleanup is retained only for manually deleting local backup directories (Preview, Run, Delete Selected Backup, Retention); never sessions/missions, with no automatic deletion or archive restoration. Default cleanup candidates are complete backups older than 180 days or beyond the newest 20; counting individual files is not the retention unit. No three-line widget: optional Starline capsule/details, with `/sync-status` fallback.
+Keep raw agent-data push/pull, safe relative include/exclude paths (sessions + missions by default), manual/background automatic sync, deletion propagation from a per-device `syncedPaths` baseline, orphan subagent pruning, backups/restoration and diagnostics. No configuration sync/settings merging, Markdown/JSON exports, Environment Tools or Local Packages. Cleanup is retained only for manually deleting local backup directories (Preview, Run, Delete Selected Backup, Retention); never sessions/missions, with no automatic deletion or archive restoration. Default cleanup candidates are complete backups older than 180 days or beyond the newest 20; counting individual files is not the retention unit. No three-line widget: optional Starline capsule/details, with `/sync-status` fallback.
 
 Settings are stored in `amox-pi-sync.json`; legacy `pi-sync-suite.json` is read only as a migration fallback until new settings are saved. Backups use `amox-pi-sync-backups` and require manual retention management via Cleanup. Manual/off startup must not access the network; auto startup fingerprints locally then starts timers and a non-awaited background pull. Setup only saves configuration and stops timers, requiring reload to activate auto mode. The automatic loop must not block the UI. Migration uses an independent `amox-pi-sync-repo`, not the old snapshot directory. The `pi-sync` status key preserves existing Starline placement; the pill bridge takes priority over legacy command mapping. `off` disables automation, not explicit commands. Presentation separates labels and values with a colon; the path count is explicitly marked configured. Starline action rows have a leading bullet, while native Pi selectors retain their own indicators. Presentation uses semantic Pi theme colours for labels, values and errors, and bold targets without fixed foreground/background colours so Starline owns selection contrast. Keep Manual/Auto/Off and Push/Pull terminology consistent across capsule, details, menus and command feedback; never append idle to the mode. Anchor bubbles to the clicked Starline cell, including submenus and confirmations; commands reuse the last clicked anchor or center before one is known. Forward pill colours by default and offer semantic theme colour overrides through bubbleColor; do not override selected-row text contrast. Colour changes must not start timers or network work. Without Starline use native Pi UI and hide the Starline colour option. Recompute theme styles when rendering, keep RPC/native status text plain, and do not store styled strings in settings. On Windows prefer native OpenSSH when present for non-ASCII home paths; retain batch mode, timeout and host-key verification. Keep large diagnostic results in the action notification rather than copying JSON dumps into status details.
 
-Safety requirements: private SSH remote, no working-directory mutation, no semantic JSONL merging, preserve local-only files, back up replacements and never overwrite active sessions. Network transfers use a 10-minute timeout and local Git commands 60 seconds; a terminated or timed-out process must never be recorded as success, even when an executor reports code 0. Pull fast-forwards or performs a clean file-level three-way merge; conflicts abort and apply nothing. A rejected non-fast-forward push fetches, integrates without rebase or force, and retries once; files integrated during push are applied on the next pull. Git commands force `core.autocrlf=false` and `core.eol=lf`, with a repository-local `* -text` attribute; do not rewrite raw bytes or existing mixed-EOL history automatically. Safe-path validation must exclude configuration and implementation data even when users select arbitrary relative data paths. Do not claim encryption, conflict-free multi-device merging or automatic secret removal.
+Safety requirements: private SSH remote, no working-directory mutation, no semantic JSONL merging, preserve files that were never synced, back up replacements/deletions and never overwrite or delete active sessions. Deletion propagation must use `syncedPaths`: Push removes only previously synced paths missing locally, Pull removes only baseline paths absent from the new snapshot, and Pull preserves locally missing baseline paths as pending push deletions. A missing baseline is seeded at session start from files present both locally and in an existing snapshot; local-only and unpulled remote-only paths stay outside it. Pre-upgrade deletions are not inferred automatically. Prune orphan sessions scans `sessions/**/*.jsonl`, compares parent basenames case-insensitively, accepts `type#8hex` names, iterates parent candidates to a fixed point, skips files modified within 10 minutes and the active session, refuses dirty repositories, commits snapshot removals before deleting local files, and never deletes symlinks or non-files. Before-push pruning runs outside `run("Push")`, is Off by default, and never blocks a push on failure. Network transfers use a 10-minute timeout and local Git commands 60 seconds; a terminated or timed-out process must never be recorded as success, even when an executor reports code 0. Pull fast-forwards or performs a clean file-level three-way merge; conflicts abort and apply nothing. A rejected non-fast-forward push fetches, integrates without rebase or force, and retries once; files integrated during push are applied on the next pull. Git commands force `core.autocrlf=false` and `core.eol=lf`, with a repository-local `* -text` attribute; do not rewrite raw bytes or existing mixed-EOL history automatically. Safe-path validation must exclude configuration and implementation data even when users select arbitrary relative data paths. Do not claim encryption, conflict-free multi-device merging or automatic secret removal.
 
 ## 功能取舍与维护边界
 
@@ -28,6 +28,7 @@ Safety requirements: private SSH remote, no working-directory mutation, no seman
 | sessions、missions | 保留 | sessions 保存对话与工具记录；missions 保存工作流任务及关联索引。两者共同保留工作记录，但不保证恢复运行中的任务或临时目录中的外部产物。 |
 | 通用路径选择 | 保留 | 允许用户按需要包含、排除安全的 agent 数据路径，不将范围写死为两个目录；敏感文件与实现目录仍受限制。 |
 | 手动、自动同步 | 保留 | 支持用户主动换机时推拉，也保留可选后台同步；默认手动，不因精简功能改变用户的同步时机。 |
+| 删除传播、孤儿会话清理 | 新增 | 手动删除的会话需要从远端和快照中移除，否则下次 Pull 会恢复；用 `syncedPaths` 基线只传播本机曾同步过的删除。Prune 依据父子会话关系清理孤儿子代理，并同步删除快照副本。 |
 | 备份恢复 | 保留 | 同路径文件可能被远端内容替换，覆盖前的本地副本是恢复入口。 |
 | Cleanup | 保留并修正 | 即使没有聊天归档，备份仍会积累，需要界面内的手动管理。按完整恢复点预览和确认删除，修正上游保留数量逻辑；不清理 sessions、missions，也不自动删除。 |
 | 诊断 | 保留 | 用户需要查看待传输差异、Git 状态和错误，不能将失败或“未检查”显示为已同步。 |

package/README.md

@@ -28,12 +28,13 @@ pi update --extensions
 | `/sync-setup git@host:owner/private-repo.git [interval]` | Configure an SSH repository and optional pull interval in minutes (no transfer) |
 | `/sync-push` | Push selected raw agent data |
 | `/sync-pull` | Pull selected raw agent data |
+| `/sync-prune [--yes]` | Preview and delete orphan subagent sessions plus their snapshot copies |
 | `/sync-settings` | Open settings and maintenance actions |
 | `/sync-status` | View status and actions; also works without Starline |
 
-The settings menu contains **View Status**, **Sync Mode** (`auto`, `manual`, `off`), **Sync Paths** (include/exclude safe relative agent-data paths), **Backups** (create/list/restore), **Diagnostics** (doctor/diff/log), and **Cleanup** (Preview, Run, Delete Selected Backup, Retention). `sessions` and `missions` are the default paths. Manual push and pull commands remain available in both `manual` and `off` modes.
+The settings menu contains **View Status**, **Sync Mode** (`auto`, `manual`, `off`), **Sync Paths** (include/exclude safe relative agent-data paths), **Prune before push** (default Off), **Backups** (create/list/restore), **Diagnostics** (doctor/diff/log), and **Cleanup** (Preview, Run, Delete Selected Backup, Retention). `sessions` and `missions` are the default paths. Manual push and pull commands remain available in both `manual` and `off` modes.
 
-Manual/off startup performs no network access. Auto startup computes a local fingerprint, starts timers and launches a background pull without awaiting network completion. `/sync-setup` only saves configuration and stops timers; reload to activate auto mode if enabled. With Starline installed, use its clickable status capsule to open details and actions: check status, push, pull and settings. The status key remains `pi-sync` for existing Starline placement; the pill bridge takes precedence over legacy `extensionStatuses.commands`, with no Starline configuration changes required. There is no three-line widget. Pill clicks anchor bubbles to the corresponding Starline cell, like Model; settings, submenus and confirmations retain that anchor. `/sync-status` uses the last clicked anchor, or a centered fallback before the first click. Text entry still uses Pi input dialogs. **Bubble colour** in settings defaults to **Follow pill**; alternatively choose the current theme’s accent, success, warning or error colour for borders and selection. Before a pill click, Follow pill uses theme accent. The optional `bubbleColor` setting stores `pill`, `accent`, `success`, `warning` or `error`; changing it performs no transfer. Without Starline this option is hidden and Pi renders its native dialogs. Labels and values are separated by a colon (for example, `Paths: 2 configured`); Starline action rows start with `•`. Labels and values use Pi theme colours, while bold action rows keep Starline’s selection contrast. State shows Manual, Auto or Off directly; active operations use Push/Pull, with the configured mode shown separately. Without Starline, the native UI remains available and status output stays plain text.
+Manual/off startup performs no network access. Auto startup computes a local fingerprint, starts timers and launches a background pull without awaiting network completion. `/sync-setup` only saves configuration and stops timers; reload to activate auto mode if enabled. With Starline installed, use its clickable status capsule to open details and actions: check status, push, pull, prune orphan sessions and settings. The status key remains `pi-sync` for existing Starline placement; the pill bridge takes precedence over legacy `extensionStatuses.commands`, with no Starline configuration changes required. There is no three-line widget. Pill clicks anchor bubbles to the corresponding Starline cell, like Model; settings, submenus and confirmations retain that anchor. `/sync-status` uses the last clicked anchor, or a centered fallback before the first click. Text entry still uses Pi input dialogs. **Bubble colour** in settings defaults to **Follow pill**; alternatively choose the current theme’s accent, success, warning or error colour for borders and selection. Before a pill click, Follow pill uses theme accent. The optional `bubbleColor` setting stores `pill`, `accent`, `success`, `warning` or `error`; changing it performs no transfer. Without Starline this option is hidden and Pi renders its native dialogs. Labels and values are separated by a colon (for example, `Paths: 2 configured`); Starline action rows start with `•`. Labels and values use Pi theme colours, while bold action rows keep Starline’s selection contrast. State shows Manual, Auto or Off directly; active operations use Push/Pull, with the configured mode shown separately. Without Starline, the native UI remains available and status output stays plain text.
 
 ## Data and safety
 
@@ -42,7 +43,8 @@ Manual/off startup performs no network access. Auto startup computes a local fin
 
 - Paths are relative to Pi's agent-data directory, not the current project. Arbitrary safe data paths can be included or excluded; the extension does not change the working directory.
 - Raw files are transferred without Markdown/JSON export or semantic JSONL merging. Concurrent edits are not a semantic merge; an automatic three-way merge is file-level and aborts if both sides changed the same file. Coordinate devices and inspect diagnostics.
-- Local-only files are retained; deletions are not propagated. Incoming content replaces differing same-path files after backup; active sessions must not be overwritten. Restore applies only the currently managed paths.
+- Deletions of previously synced files propagate: Push removes them from the snapshot, and Pull deletes local copies removed remotely, after backup. Files that were never synced are retained. A per-device `syncedPaths` baseline prevents unpulled remote files from being mistaken for local deletions. On first session start a missing baseline is seeded from files present both locally and in an existing snapshot; local-only and unpulled remote-only files stay outside it. Pre-upgrade deletions are not inferred automatically. Incoming content replaces differing same-path files after backup; active sessions must not be deleted or overwritten. Restore applies only the currently managed paths.
+- **Prune orphan sessions** (action or `/sync-prune`) scans `sessions/**/*.jsonl` for subagent sessions whose parent is missing or itself pruned. It compares parent basenames case-insensitively, accepts names matching `type#8hex`, skips files modified in the last 10 minutes and the active session, shows count/size/first names, commits snapshot removals first, then deletes local files. Staged or uncommitted repository changes abort without deleting local files. `--yes` skips confirmation. **Prune before push** runs it before manual, command and automatic pushes; a prune failure warns but does not block the push.
 - Network Git operations (`clone`, `fetch`, `pull`, `push`) use a 10-minute timeout; local Git operations use 60 seconds. A process terminated by timeout or cancellation is a failure and is never recorded as completed, even if Pi reports exit code 0. Pull fast-forwards when possible; otherwise it performs a clean three-way merge in the snapshot repository. Conflicts abort the merge and apply no files. A rejected non-fast-forward push fetches, integrates remote history without rebase or force, and retries once; files integrated during push are applied on the next pull.
 - Git commands force `core.autocrlf=false` and `core.eol=lf`, and the snapshot repository uses a local `* -text` attribute so Git does not convert raw bytes. Existing history with mixed CRLF/LF is not rewritten automatically; normalizing it requires an explicit manual migration and repack. On Windows, SSH prefers native OpenSSH (`System32/OpenSSH/ssh.exe`) when available to support non-ASCII user directories; otherwise it uses `ssh`. Batch mode, connection timeout and host-key verification remain enabled, overriding a custom `core.sshCommand`.
 - Backups use `amox-pi-sync-backups` under the agent-data directory. Cleanup only deletes local backups after manual preview/confirmation, using complete backup directories rather than individual files. The default limits are 20 complete backups and a maximum age of 180 days; backups older than this or beyond the newest 20 become cleanup candidates. There is no automatic deletion; sessions and missions are never cleanup targets.

package/README.zh-CN.md

@@ -28,12 +28,13 @@ pi update --extensions
 | `/sync-setup git@host:owner/private-repo.git [interval]` | 配置 SSH 仓库及可选拉取间隔（分钟），不传输数据 |
 | `/sync-push` | Push 选中的原始 agent 数据 |
 | `/sync-pull` | Pull 选中的原始 agent 数据 |
+| `/sync-prune [--yes]` | 预览并删除孤儿子代理会话及其快照副本 |
 | `/sync-settings` | 打开设置与维护操作 |
 | `/sync-status` | 查看状态和操作；未安装 Starline 时也可使用 |
 
-设置菜单保留 **View Status**、**Sync Mode**（`auto`、`manual`、`off`）、**Sync Paths**（包含/排除任意安全的 agent 数据相对路径）、**Backups**（创建/列表/恢复）、**Diagnostics**（doctor/diff/log）和 **Cleanup**（Preview、Run、Delete Selected Backup、Retention）。默认路径为 `sessions` 和 `missions`。`manual` 和 `off` 模式仍可手动上传、拉取。
+设置菜单保留 **View Status**、**Sync Mode**（`auto`、`manual`、`off`）、**Sync Paths**（包含/排除任意安全的 agent 数据相对路径）、**Prune before push**（默认 Off）、**Backups**（创建/列表/恢复）、**Diagnostics**（doctor/diff/log）和 **Cleanup**（Preview、Run、Delete Selected Backup、Retention）。默认路径为 `sessions` 和 `missions`。`manual` 和 `off` 模式仍可手动上传、拉取。
 
-manual/off 启动不访问网络。auto 启动先计算本地 fingerprint，再启动定时器并发起后台拉取，不等待网络完成。`/sync-setup` 只保存配置并停止定时器；已启用 auto 时需 reload 激活。安装 Starline 时，优先点击状态胶囊打开详情，执行 Check status、Push、Pull 或 Settings。状态 key 保留为 `pi-sync`，兼容原 Starline placement；pill bridge 优先于旧 `extensionStatuses.commands`，无需修改 Starline 配置。没有三行 widget。点击胶囊时，气泡像 Model 一样锚定对应的 Starline cell；设置、子菜单及确认框沿用该锚点。`/sync-status` 使用最近点击的锚点，首次点击前回退居中。文本输入仍使用 Pi 输入框。设置中的 **Bubble colour** 默认 **Follow pill**（跟随胶囊），也可选择当前主题的 accent、success、warning 或 error 作为边框和选中项颜色；首次点击前使用主题 accent。可选配置 `bubbleColor` 保存为 `pill`、`accent`、`success`、`warning` 或 `error`，修改配色不触发传输。未安装 Starline 时隐藏此选项，由 Pi 渲染原生弹框。标签与值统一用冒号分隔（如 `Paths: 2 configured`，表示配置了 2 个同步路径），Starline 中的可选操作统一以 `•` 开头。标签、数值和异常使用 Pi 主题色区分，可选操作使用粗体并保留 Starline 自带的选中对比度。State 直接显示 Manual、Auto 或 Off；执行中显示 Push／Pull，另列当前模式，不追加 idle。未安装 Starline 时回退原生界面，状态输出保留纯文本。
+manual/off 启动不访问网络。auto 启动先计算本地 fingerprint，再启动定时器并发起后台拉取，不等待网络完成。`/sync-setup` 只保存配置并停止定时器；已启用 auto 时需 reload 激活。安装 Starline 时，优先点击状态胶囊打开详情，执行 Check status、Push、Pull、Prune orphan sessions 或 Settings。状态 key 保留为 `pi-sync`，兼容原 Starline placement；pill bridge 优先于旧 `extensionStatuses.commands`，无需修改 Starline 配置。没有三行 widget。点击胶囊时，气泡像 Model 一样锚定对应的 Starline cell；设置、子菜单及确认框沿用该锚点。`/sync-status` 使用最近点击的锚点，首次点击前回退居中。文本输入仍使用 Pi 输入框。设置中的 **Bubble colour** 默认 **Follow pill**（跟随胶囊），也可选择当前主题的 accent、success、warning 或 error 作为边框和选中项颜色；首次点击前使用主题 accent。可选配置 `bubbleColor` 保存为 `pill`、`accent`、`success`、`warning` 或 `error`，修改配色不触发传输。未安装 Starline 时隐藏此选项，由 Pi 渲染原生弹框。标签与值统一用冒号分隔（如 `Paths: 2 configured`，表示配置了 2 个同步路径），Starline 中的可选操作统一以 `•` 开头。标签、数值和异常使用 Pi 主题色区分，可选操作使用粗体并保留 Starline 自带的选中对比度。State 直接显示 Manual、Auto 或 Off；执行中显示 Push／Pull，另列当前模式，不追加 idle。未安装 Starline 时回退原生界面，状态输出保留纯文本。
 
 ## 数据与安全
 
@@ -42,7 +43,8 @@ manual/off 启动不访问网络。auto 启动先计算本地 fingerprint，再
 
 - 路径相对于 Pi agent 数据目录，不是当前项目。可包含/排除任意安全的数据相对路径；扩展不改写工作目录。
 - 传输原始文件，不生成 Markdown/JSON 归档，不做语义化 JSONL 合并。并发编辑不是语义合并；自动三方合并按文件进行，双方修改同一文件时会中止。请协调多设备操作并查看诊断。
-- 保留本地独有文件，不传播删除；同路径的不同内容以拉取数据为准，覆盖前备份；不得覆盖活跃会话。恢复备份只处理当前纳管范围。
+- 曾经同步过的文件被手动删除后，删除会传播：Push 从快照移除，Pull 会删除远端已移除的本地副本（删除前备份）。从未同步过的本地文件保留。每台设备用 `syncedPaths` 基线记录已同步路径，避免把“远端有、本机尚未 Pull”的文件误判为本地删除。首次启动时若没有基线，会从“本地和现有快照同时存在”的文件中初始化；本地独有和尚未 Pull 的远端文件不会进入基线。升级前已经发生的删除不会自动推断。同路径的不同内容以拉取数据为准，覆盖前备份；不得删除或覆盖活跃会话。恢复备份只处理当前纳管范围。
+- **Prune orphan sessions**（操作项或 `/sync-prune`）扫描 `sessions/**/*.jsonl`，找出父会话不存在或父会话本身也被清理的子代理会话。父文件按 basename 不区分大小写比对，名字匹配 `type#8hex`；最近 10 分钟内修改过的文件和当前活跃会话会跳过；预览显示条数、体积和前几条名称；先提交快照删除，再删本地文件。仓库有暂存或未提交修改时拒绝执行，不删本地文件。`--yes` 跳过确认。**Prune before push** 会在手动、命令和自动 Push 前执行；清理失败只警告，不阻断 Push。
 - 网络 Git 操作（`clone`、`fetch`、`pull`、`push`）超时为 10 分钟，本地 Git 操作为 60 秒。被超时或取消终止的进程一律视为失败，即使 Pi 返回 exit code 0，也不会写入完成时间。能快进时 Pull 直接快进，否则在快照仓库中执行干净的三方合并；冲突会中止合并且不应用任何文件。Push 被非快进拒绝时会 fetch、在不 rebase、不 force 的前提下整合远端历史，并重试一次；Push 整合的文件在下一次 Pull 时应用。
 - Git 操作强制 `core.autocrlf=false`、`core.eol=lf`，快照仓库使用本地 `* -text` 属性，避免 Git 转换原始字节。已有 CRLF/LF 混合历史不会被自动改写；统一换行需要显式的手动迁移和 repack。Windows 优先使用原生 OpenSSH（`System32/OpenSSH/ssh.exe`），支持中文用户目录；不存在时及其他平台使用 `ssh`。保留非交互模式、连接超时及主机密钥验证，不复用自定义 `core.sshCommand`。
 - 备份位于 agent 数据目录下的 `amox-pi-sync-backups`。Cleanup 仅在手动预览/确认后删除本地备份，按完整备份目录计数，不按单个文件计数。默认数量上限 20 份、最长 180 天；超龄或超出最新 20 份的备份纳入清理候选，不自动删除，不清理 sessions 或 missions。

package/core.ts

@@ -22,11 +22,15 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, realpathSync } from "node:fs";
+import { createReadStream, existsSync, realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
 
 export type BubbleColor = "pill" | "accent" | "success" | "warning" | "error";
 export type Config = {
   bubbleColor?: BubbleColor;
+  pruneOrphanSessionsBeforePush?: boolean;
+  /** Managed paths present in the last successful push/pull; used to propagate deletions safely. */
+  syncedPaths?: string[];
   version: 1; repoUrl: string; repoDir: string; mode: "manual" | "auto" | "off";
   paths: string[]; pullIntervalMinutes: number; watchIntervalMs: number; pushDebounceMs: number;
   lastPushAt?: string; lastPullAt?: string; lastResult?: string;
@@ -38,6 +42,10 @@ export type Status = { busy?: string; error?: string; localChanges?: string; rem
 export type Backup = { id: string; createdAt: string; reason: string; includedPaths: string[] };
 export type BackupSummary = Backup;
 export type SyncResult = { changed: boolean; message: string; files: string[]; backupId?: string };
+export type SessionEntry = { path: string; parentSession?: string; name?: string; bytes?: number; mtimeMs?: number };
+export type PruneCandidate = { path: string; name: string; bytes: number };
+export type PrunePlan = { candidates: PruneCandidate[]; skipped: number };
+export type PruneResult = { removed: string[]; repoRemoved: number; skipped: number };
 
 // Canonicalize the trusted agent root (including existing parents). macOS /var
 // and /tmp are OS aliases; links inside managed data are still rejected below.
@@ -72,6 +80,66 @@ function inside(parent: string, child: string): boolean {
   return rel === "" || (!rel.startsWith(`..${path.sep}`) && rel !== ".." && !path.isAbsolute(rel));
 }
 function overlaps(a: string, b: string): boolean { return inside(a, b) || inside(b, a); }
+const ORPHAN_NAME = /^.+#[0-9a-f]{8}$/;
+const SESSION_RECENT_MS = 10 * 60_000;
+function baseName(value: string): string {
+  const parts = value.replaceAll("\\", "/").split("/");
+  return (parts.at(-1) ?? "").toLowerCase();
+}
+/** Pure candidate selection: parent basename + subagent name, iterated to a fixed point. */
+export function selectOrphanSessions(entries: SessionEntry[], options: { activePath?: string; now?: number; recentMs?: number } = {}): PrunePlan {
+  const now = options.now ?? Date.now();
+  const recentMs = options.recentMs ?? SESSION_RECENT_MS;
+  const active = options.activePath?.toLowerCase();
+  const byBase = new Map<string, SessionEntry[]>();
+  for (const entry of entries) {
+    const base = baseName(entry.path);
+    const list = byBase.get(base) ?? [];
+    list.push(entry);
+    byBase.set(base, list);
+  }
+  const isRecent = (entry: SessionEntry) => now - (entry.mtimeMs ?? 0) < recentMs;
+  const isActive = (entry: SessionEntry) => active !== undefined && entry.path.toLowerCase() === active;
+  const parentOf = (entry: SessionEntry) => {
+    if (typeof entry.parentSession !== "string" || !entry.parentSession) return { state: "missing" as const };
+    const list = byBase.get(baseName(entry.parentSession));
+    if (!list?.length) return { state: "missing" as const };
+    // Duplicate basenames are ambiguous; never treat either copy as an orphan.
+    if (list.length !== 1) return { state: "ambiguous" as const };
+    return { state: "found" as const, parent: list[0]! };
+  };
+  const compute = (protectRecent: boolean): Set<SessionEntry> => {
+    const candidates = new Set<SessionEntry>();
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const entry of entries) {
+        if (candidates.has(entry) || isActive(entry)) continue;
+        if (protectRecent && isRecent(entry)) continue;
+        if (typeof entry.name !== "string" || !ORPHAN_NAME.test(entry.name)) continue;
+        const parent = parentOf(entry);
+        if (parent.state === "ambiguous") continue;
+        if (parent.state === "missing" || candidates.has(parent.parent)) {
+          candidates.add(entry);
+          changed = true;
+        }
+      }
+    }
+    return candidates;
+  };
+  const structural = compute(false);
+  const selected = compute(true);
+  return {
+    candidates: [...selected]
+      .map(entry => ({ path: entry.path, name: entry.name!, bytes: Math.max(0, entry.bytes ?? 0) }))
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    skipped: [...structural].filter(entry => !selected.has(entry)).length,
+  };
+}
+/** A path is managed when it equals or is below one of the configured relative paths. */
+function managedPath(relative: string, managed: string[]): boolean {
+  return managed.some(item => relative === item || relative.startsWith(`${item}/`));
+}
 function remote(url: string): void {
   if (typeof url !== "string" || /[\s\x00-\x1f]/.test(url)) throw new Error("Use an SSH git URL: git@host:path or ssh://user@host/path");
   if (/^[a-zA-Z0-9._-]+@[a-zA-Z0-9][a-zA-Z0-9.-]*:[a-zA-Z0-9_~][a-zA-Z0-9._~/-]*$/.test(url) && !url.split(":")[1]!.split("/").includes("..")) return;
@@ -94,12 +162,18 @@ function validate(config: Config, paths: Paths): void {
   }
   if (overlaps(config.repoDir, paths.backupDir) || inside(config.repoDir, paths.agentDir) || inside(config.repoDir, paths.configFile) || inside(paths.backupDir, paths.agentDir)) throw new Error("Unsafe repository/backup directory nesting");
   if (config.bubbleColor !== undefined && !["pill", "accent", "success", "warning", "error"].includes(config.bubbleColor)) throw new Error("Unsupported bubble colour");
+  if (config.pruneOrphanSessionsBeforePush !== undefined && typeof config.pruneOrphanSessionsBeforePush !== "boolean") throw new Error("pruneOrphanSessionsBeforePush must be boolean");
+  if (config.syncedPaths !== undefined) {
+    if (!Array.isArray(config.syncedPaths) || config.syncedPaths.some(item => typeof item !== "string")) throw new Error("syncedPaths must be a string array");
+    const paths = config.syncedPaths.map(validatePath);
+    if (new Set(paths).size !== paths.length) throw new Error("syncedPaths must not contain duplicates");
+  }
   const retention = config.retention ?? { keepBackups: 20, maxAgeDays: 180 };
   if (!Number.isInteger(retention.keepBackups) || retention.keepBackups < 0 || !Number.isFinite(retention.maxAgeDays) || retention.maxAgeDays <= 0) throw new Error("Invalid backup retention: keepBackups must be a nonnegative integer and maxAgeDays positive");
   for (const key of ["pullIntervalMinutes", "watchIntervalMs", "pushDebounceMs"] as const) if (!Number.isFinite(config[key]) || config[key] <= 0) throw new Error(`${key} must be positive`);
 }
 export function createConfig(repoUrl: string, paths = defaultPaths()): Config {
-  const config: Config = { version: 1, repoUrl, repoDir: path.join(paths.agentDir, "amox-pi-sync-repo"), mode: "manual", paths: ["sessions", "missions"], retention: { keepBackups: 20, maxAgeDays: 180 }, pullIntervalMinutes: 1440, watchIntervalMs: 10000, pushDebounceMs: 2500 };
+  const config: Config = { version: 1, repoUrl, repoDir: path.join(paths.agentDir, "amox-pi-sync-repo"), mode: "manual", paths: ["sessions", "missions"], pruneOrphanSessionsBeforePush: false, retention: { keepBackups: 20, maxAgeDays: 180 }, pullIntervalMinutes: 1440, watchIntervalMs: 10000, pushDebounceMs: 2500 };
   validate(config, paths); return config;
 }
 async function stat(file: string) { try { return await fs.lstat(file); } catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return null; throw e; } }
@@ -210,6 +284,125 @@ export class SyncService {
     await this.ensureAttributes();
     for (const file of (await this.git(["ls-files", "-z"])).split("\0").filter(Boolean)) validatePath(file);
   }
+  private managedPaths(): string[] { return this.config.paths.map(validatePath); }
+  private activeSessionRelative(): string | undefined {
+    if (!this.activeSessionFile) return undefined;
+    const absolute = path.resolve(this.paths.agentDir, this.activeSessionFile);
+    let resolved = absolute;
+    try { resolved = realpathSync.native(absolute); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    const relative = path.relative(this.paths.agentDir, resolved);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return undefined;
+    return validatePath(relative.split(path.sep).join("/"));
+  }
+  private async localFileExists(relative: string): Promise<boolean> {
+    const target = path.join(this.paths.agentDir, validatePath(relative));
+    await noLinks(target);
+    return Boolean(await stat(target));
+  }
+  private async readSessionHeader(file: string): Promise<{ parentSession?: string } | undefined> {
+    let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
+    try {
+      handle = await fs.open(file, "r");
+      const buffer = Buffer.alloc(64 * 1024);
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+      const first = buffer.subarray(0, bytesRead).toString("utf8").split("\n", 1)[0] ?? "";
+      const header = JSON.parse(first);
+      return { parentSession: typeof header?.parentSession === "string" && header.parentSession ? header.parentSession : undefined };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT" || error instanceof SyntaxError) return undefined;
+      throw error;
+    } finally { await handle?.close(); }
+  }
+  private async readLastSessionName(file: string): Promise<string | undefined> {
+    let name: string | undefined;
+    let stream: ReturnType<typeof createReadStream> | undefined;
+    try {
+      stream = createReadStream(file, { encoding: "utf8" });
+      const lines = createInterface({ input: stream, crlfDelay: Infinity });
+      try {
+        for await (const line of lines) {
+          if (!line.includes("session_info")) continue;
+          try {
+            const entry = JSON.parse(line);
+            if (entry?.type === "session_info" && typeof entry.name === "string") name = entry.name;
+          } catch { /* ignore malformed lines while a transcript is being written */ }
+        }
+      } finally { lines.close(); }
+      return name;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    } finally { stream?.destroy(); }
+  }
+  private async scanSessionEntries(): Promise<SessionEntry[]> {
+    if (!this.managedPaths().includes("sessions")) throw new Error("Prune requires \"sessions\" in managed paths");
+    const root = path.join(this.paths.agentDir, "sessions");
+    await noLinks(root);
+    const rootInfo = await stat(root);
+    if (!rootInfo) return [];
+    if (!rootInfo.isDirectory()) throw new Error("sessions is not a directory");
+    const entries: SessionEntry[] = [];
+    const visit = async (absolute: string, relative: string): Promise<void> => {
+      await noLinks(absolute);
+      const info = await stat(absolute);
+      if (!info) return;
+      if (info.isDirectory()) {
+        for (const child of (await fs.readdir(absolute)).sort()) await visit(path.join(absolute, child), `${relative}/${child}`);
+        return;
+      }
+      if (!info.isFile() || !relative.toLowerCase().endsWith(".jsonl")) return;
+      const header = await this.readSessionHeader(absolute);
+      if (!header) return;
+      const name = header.parentSession ? await this.readLastSessionName(absolute) : undefined;
+      entries.push({ path: validatePath(`sessions/${relative}`), parentSession: header.parentSession, name, bytes: info.size, mtimeMs: info.mtimeMs });
+    };
+    for (const child of (await fs.readdir(root)).sort()) await visit(path.join(root, child), child);
+    return entries;
+  }
+  private async stageDeletions(files: string[]): Promise<void> {
+    let batch: string[] = []; let budget = 0;
+    const flush = async () => {
+      if (!batch.length) return;
+      await this.git(["--literal-pathspecs", "add", "-A", "--", ...batch]);
+      batch = []; budget = 0;
+    };
+    for (const file of files) {
+      const cost = file.length * 2 + 3;
+      if (budget + cost > 6000 && batch.length) await flush();
+      batch.push(file); budget += cost;
+    }
+    await flush();
+  }
+  /** Paths currently present under the managed roots, without reading file bodies. */
+  private async listPaths(root: string): Promise<Set<string>> {
+    const result = new Set<string>();
+    const visit = async (relative: string): Promise<void> => {
+      validatePath(relative);
+      const absolute = path.join(root, relative); await noLinks(absolute);
+      const info = await stat(absolute); if (!info) return;
+      if (info.isDirectory()) { for (const child of (await fs.readdir(absolute)).sort()) await visit(`${relative}/${child}`); }
+      else if (info.isFile()) result.add(relative);
+      else throw new Error(`Not a regular file: ${relative}`);
+    };
+    for (const item of this.config.paths) await visit(validatePath(item));
+    return result;
+  }
+  /**
+   * Seed a missing baseline from files present both locally and in an existing
+   * snapshot. Local-only and unpulled remote-only files stay outside the
+   * baseline, so later deletions propagate without deleting unseen remote data.
+   */
+  async initializeBaseline(): Promise<boolean> {
+    if (this.config.syncedPaths !== undefined) return false;
+    const gitDir = path.join(this.config.repoDir, ".git"); await noLinks(gitDir);
+    if (!(await stat(gitDir))) return false;
+    const local = await this.listPaths(this.paths.agentDir);
+    const snapshot = await this.listPaths(this.config.repoDir);
+    this.config.syncedPaths = [...local].filter(item => snapshot.has(item)).sort();
+    await saveConfig(this.config, this.paths);
+    return true;
+  }
   private async collect(root: string, scan = false): Promise<Files> {
     const files: Files = new Map();
     const visit = async (relative: string): Promise<void> => {
@@ -263,31 +456,106 @@ export class SyncService {
     }
     return result.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
   }
-  private async apply(files: Files, reason: string): Promise<SyncResult> {
-    const changes: Files = new Map(); const replaced: string[] = [];
+  private async apply(files: Files, reason: string, deletions: string[] = [], preserve: Set<string> = new Set()): Promise<SyncResult> {
+    const changes: Files = new Map(); const replaced: string[] = []; const removed: string[] = [];
+    let active = this.activeSessionFile ? path.resolve(this.paths.agentDir, this.activeSessionFile) : undefined;
+    if (active) {
+      try { active = await fs.realpath(active); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    }
+    const sameActive = (target: string) => active && (process.platform === "win32"
+      ? path.resolve(target).toLowerCase() === active.toLowerCase() : path.resolve(target) === active);
     for (const [relative, data] of files) {
+      if (preserve.has(relative)) continue;
       const target = path.join(this.paths.agentDir, relative); await noLinks(target);
       const info = await stat(target);
       if (info && !info.isFile()) throw new Error(`File/directory conflict at ${relative}; move the local entry aside and retry`);
       const local = info ? await fs.readFile(target) : undefined;
       if (local?.equals(data)) continue;
-      const activePath = this.activeSessionFile && path.resolve(this.paths.agentDir, this.activeSessionFile);
-      let active = activePath;
-      if (activePath) {
-        try { active = await fs.realpath(activePath); }
-        catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
-      }
-      const samePath = active && (process.platform === "win32" ? path.resolve(target).toLowerCase() === active.toLowerCase() : path.resolve(target) === active);
-      if (samePath) throw new Error(`Active session differs: ${relative}. Switch to a new session or close it before pull/restore; no files were applied.`);
+      if (sameActive(target)) throw new Error(`Active session differs: ${relative}. Switch to a new session or close it before pull/restore; no files were applied.`);
       changes.set(relative, data); if (local) replaced.push(relative);
     }
-    if (!changes.size) return { changed: false, message: "Already up to date; no files applied or backup created", files: [] };
+    for (const relative of deletions) {
+      validatePath(relative);
+      const target = path.join(this.paths.agentDir, relative); await noLinks(target);
+      const info = await stat(target);
+      if (!info) continue;
+      if (!info.isFile()) throw new Error(`File/directory conflict at ${relative}; move the local entry aside and retry`);
+      if (sameActive(target)) throw new Error(`Active session cannot be deleted: ${relative}. Switch to a new session before pull/restore; no files were applied.`);
+      removed.push(relative);
+    }
+    const preserved = preserve.size ? `; preserved ${preserve.size} local deletion(s) pending push` : "";
+    if (!changes.size && !removed.length) return { changed: false, message: `Already up to date; no files applied or backup created${preserved}`, files: [] };
     const backup = await this.makeBackup(reason);
     await this.write(this.paths.agentDir, changes);
-    const message = `Applied ${changes.size} file(s); replaced ${replaced.length} differing local file(s) from remote/backup, preserved local-only files. Recovery backup: ${backup.id}${replaced.length ? `; replaced: ${replaced.join(", ")}` : ""}`;
+    for (const relative of removed) await fs.rm(path.join(this.paths.agentDir, relative), { force: true });
+    const deleted = removed.length ? `; deleted ${removed.length} remote-deleted file(s)` : "";
+    const message = `Applied ${changes.size} file(s)${deleted}; replaced ${replaced.length} differing local file(s) from remote/backup, preserved local-only files${preserved}. Recovery backup: ${backup.id}${replaced.length ? `; replaced: ${replaced.join(", ")}` : ""}`;
     this.config.lastResult = message;
-    return { changed: changes.size > 0, message, files: [...changes.keys()], backupId: backup.id };
+    return { changed: changes.size > 0 || removed.length > 0, message, files: [...changes.keys()], backupId: backup.id };
   }
+  async planPruneSessions(): Promise<PrunePlan> {
+    return selectOrphanSessions(await this.scanSessionEntries(), { activePath: this.activeSessionRelative() });
+  }
+  async pruneOrphanSessions(expectedPaths?: string[]): Promise<PruneResult> { return this.run("prune", async () => {
+    const plan = await this.planPruneSessions();
+    const expected = expectedPaths === undefined ? undefined : new Set(expectedPaths.map(validatePath));
+    const candidates = expected ? plan.candidates.filter(candidate => expected.has(candidate.path)) : plan.candidates;
+    if (!candidates.length) return { removed: [], repoRemoved: 0, skipped: plan.skipped };
+    const active = this.activeSessionRelative()?.toLowerCase();
+    let skipped = plan.skipped;
+    const selected: typeof candidates = [];
+    for (const candidate of candidates) {
+      const relative = validatePath(candidate.path);
+      if (active && relative.toLowerCase() === active) { skipped++; continue; }
+      const file = path.join(this.paths.agentDir, relative);
+      await noLinks(file);
+      const info = await stat(file);
+      if (info && !info.isFile()) throw new Error(`Not a regular file: ${relative}`);
+      // Recheck recency before touching the snapshot; a live subagent may have
+      // written the file while the preview was open.
+      if (info && Date.now() - info.mtimeMs < SESSION_RECENT_MS) { skipped++; continue; }
+      selected.push(candidate);
+    }
+    if (!selected.length) return { removed: [], repoRemoved: 0, skipped };
+    await this.ensureRepo();
+    if ((await this.git(["diff", "--cached", "--name-only"])).trim()) throw new Error("Repository has staged changes; run Push or resolve them before pruning");
+    if ((await this.git(["status", "--porcelain"])).trim()) throw new Error("Repository has uncommitted changes; run Push or resolve them before pruning");
+    const repoRemoved: string[] = [];
+    for (const candidate of selected) {
+      const relative = validatePath(candidate.path);
+      const file = path.join(this.config.repoDir, relative);
+      await noLinks(file);
+      const info = await stat(file);
+      if (!info) continue;
+      if (!info.isFile()) throw new Error(`Not a regular file in snapshot: ${relative}`);
+      await fs.rm(file);
+      repoRemoved.push(relative);
+    }
+    if (repoRemoved.length) {
+      await this.stageDeletions(repoRemoved);
+      await this.git(["commit", "-m", `amox-pi-sync: prune ${repoRemoved.length} orphan subagent session(s)`]);
+    }
+    const removed: string[] = [];
+    for (const candidate of selected) {
+      const relative = validatePath(candidate.path);
+      if (active && relative.toLowerCase() === active) { skipped++; continue; }
+      const file = path.join(this.paths.agentDir, relative);
+      await noLinks(file);
+      const info = await stat(file);
+      if (!info) continue;
+      if (!info.isFile()) throw new Error(`Not a regular file: ${relative}`);
+      if (Date.now() - info.mtimeMs < SESSION_RECENT_MS) { skipped++; continue; }
+      await fs.rm(file);
+      removed.push(relative);
+    }
+    if (removed.length) {
+      const deleted = new Set(removed);
+      this.config.syncedPaths = this.config.syncedPaths?.filter(item => !deleted.has(item));
+      await saveConfig(this.config, this.paths);
+    }
+    return { removed, repoRemoved: repoRemoved.length, skipped };
+  }); }
   async check(): Promise<Status> { return this.run("check", async () => {
     this.status.checkedAt = undefined; this.status.remoteChanges = undefined;
     await this.ensureRepo(); await this.git(["fetch", "origin"], this.config.repoDir, NETWORK_TIMEOUT_MS);
@@ -336,7 +604,22 @@ export class SyncService {
     const files = await this.collect(this.paths.agentDir, true);
     // Validate the existing snapshot too; never follow nested symlinks or stage secrets.
     await this.collect(this.config.repoDir, true);
+    const managed = this.managedPaths();
+    // Only delete paths this device previously synced. Files that exist only in
+    // the remote snapshot (not yet pulled) are never inferred as local deletions.
+    const deletions = this.config.syncedPaths === undefined ? [] : this.config.syncedPaths
+      .filter(item => managedPath(item, managed) && !files.has(item));
     await this.write(this.config.repoDir, files);
+    const repoDeleted: string[] = [];
+    for (const relative of deletions) {
+      const file = path.join(this.config.repoDir, validatePath(relative));
+      await noLinks(file);
+      const info = await stat(file);
+      if (!info) continue;
+      if (!info.isFile()) throw new Error(`Not a regular file in snapshot: ${relative}`);
+      await fs.rm(file);
+      repoDeleted.push(relative);
+    }
     let batch: string[] = []; let budget = 0;
     for (const file of files.keys()) {
       // Include quoting/argument overhead within Windows' command-line limit.
@@ -347,6 +630,7 @@ export class SyncService {
       batch.push(file); budget += cost;
     }
     if (batch.length) await this.git(["--literal-pathspecs", "add", "--", ...batch]);
+    if (repoDeleted.length) await this.stageDeletions(repoDeleted);
     const staged = (await this.git(["diff", "--cached", "--name-only"])).trim();
     if (staged) await this.git(["commit", "-m", `amox-pi-sync: ${new Date().toISOString()}`]);
     // A rejected non-fast-forward push is recoverable without force. Any other
@@ -363,9 +647,11 @@ export class SyncService {
       await this.git(["push", "-u", "origin", "HEAD"], this.config.repoDir, NETWORK_TIMEOUT_MS);
     }
     this.config.lastPushAt = new Date().toISOString();
+    this.config.syncedPaths = [...files.keys()].sort();
+    const removed = repoDeleted.length ? `; removed ${repoDeleted.length} locally deleted file(s) from the snapshot` : "";
     this.config.lastResult = integrated
-      ? "Integrated remote history and pushed managed snapshot; run Pull to apply remote files (no force push)"
-      : "Pushed managed snapshot (no force push; remote-only files preserved)";
+      ? `Integrated remote history and pushed managed snapshot${removed}; run Pull to apply remote files (no force push)`
+      : `Pushed managed snapshot${removed} (no force push; unpulled remote files preserved)`;
     await saveConfig(this.config, this.paths);
     return this.config.lastResult;
   }); }
@@ -373,8 +659,21 @@ export class SyncService {
     await this.ensureRepo();
     if ((await this.git(["status", "--porcelain"])).trim()) throw new Error("Repository has uncommitted changes; resolve them before pulling");
     const result = await this.integrateRemote();
-    const applied = await this.apply(await this.collect(this.config.repoDir, true), "before applying remote snapshot");
+    const snapshot = await this.collect(this.config.repoDir, true);
+    const snapshotPaths = new Set(snapshot.keys());
+    const managed = this.managedPaths();
+    const preserve = new Set<string>();
+    const deletions: string[] = [];
+    if (this.config.syncedPaths !== undefined) {
+      for (const relative of this.config.syncedPaths) {
+        if (!managedPath(relative, managed)) continue;
+        if (!snapshotPaths.has(relative)) deletions.push(relative);
+        else if (!(await this.localFileExists(relative))) preserve.add(relative);
+      }
+    }
+    const applied = await this.apply(snapshot, "before applying remote snapshot", deletions, preserve);
     this.config.lastPullAt = new Date().toISOString();
+    this.config.syncedPaths = [...snapshotPaths].sort();
     this.config.lastResult = `${result.merged ? "Merged diverged snapshots cleanly. " : ""}${applied.message}`;
     await saveConfig(this.config, this.paths); return this.config.lastResult;
   }); }

package/index.ts

@@ -2,7 +2,7 @@
 // Upstream: https://github.com/MuratAitov/pi-sync
 import { stripVTControlCharacters } from "node:util";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { SyncService, createConfig, defaultPaths, loadConfig, saveConfig, validatePath, type Config } from "./core.ts";
+import { SyncService, createConfig, defaultPaths, loadConfig, saveConfig, validatePath, type Config, type PruneResult } from "./core.ts";
 
 type BubbleLine = string | { text: string; onSelect: () => void; current?: boolean };
 type Tone = "text" | "muted" | "dim" | "accent" | "success" | "warning" | "error";
@@ -25,6 +25,9 @@ const message = (error: unknown) => terminalText(error instanceof Error ? error.
 const displayTime = (value?: string) => value ? new Date(value).toLocaleString() : "Never";
 const modeLabel = (mode: Config["mode"]) => ({ manual: "Manual", auto: "Auto", off: "Off" })[mode];
 const terminalText = (value: string) => stripVTControlCharacters(value).replace(/\r\n?/g, "\n").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+const formatBytes = (bytes: number) => bytes < 1024 ? `${bytes} B` : bytes < 1024 ** 2 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+const formatPruneResult = (result: PruneResult) =>
+  `Pruned ${result.removed.length} local and ${result.repoRemoved} snapshot session(s)${result.skipped ? `; skipped ${result.skipped} recent/active` : ""}. Snapshot removal is committed locally; Push to publish.`;
 const menuHint = "↑↓ Enter Esc";
 
 export default function amoxPiSync(pi: ExtensionAPI): void {
@@ -84,12 +87,13 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
     fingerprint = undefined;
   }
 
-  function makeService(): void {
+  function makeService(): SyncService | undefined {
     service = config ? new SyncService(config, paths, async (args, cwd, timeoutMs) => {
       const result = await pi.exec("git", args, { cwd, timeout: timeoutMs });
       return { stdout: result.stdout, stderr: result.stderr, code: result.code, killed: result.killed };
     }) : undefined;
     if (service) service.activeSessionFile = ctx?.sessionManager.getSessionFile();
+    return service;
   }
 
   async function run(label: string, action: (sync: SyncService) => Promise<unknown>, quiet = false): Promise<boolean> {
@@ -132,6 +136,37 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
     }
   }
 
+  async function pruneSessions(context: ExtensionContext, assumeYes = false): Promise<void> {
+    if (busy) { context.ui.notify(`Sync is busy: ${busy}.`, "warning"); return; }
+    if (!service || !config) { context.ui.notify("Run /sync-setup first.", "warning"); return; }
+    let plan;
+    try { plan = await service.planPruneSessions(); }
+    catch (failure) { report(failure); return; }
+    const count = plan.candidates.length;
+    const bytes = plan.candidates.reduce((total, candidate) => total + candidate.bytes, 0);
+    const skipped = plan.skipped ? `\nSkipped: ${plan.skipped} recent/active session(s).` : "";
+    if (!count) { context.ui.notify(`No orphan subagent sessions to prune.${skipped}`, "info"); return; }
+    const preview = plan.candidates.slice(0, 5).map(candidate => `• ${candidate.name} (${formatBytes(candidate.bytes)})`).join("\n");
+    const more = count > 5 ? `\n… and ${count - 5} more` : "";
+    const description = `${count} orphan subagent session(s), ${formatBytes(bytes)} total.\n${preview}${more}${skipped}\n\nSnapshot copies are committed locally first, then local files are deleted. Push afterwards to publish the deletion. Parent lookup is local; Pull first if another device may have the parent.`;
+    if (assumeYes) context.ui.notify(`Pruning ${count} orphan session(s), ${formatBytes(bytes)}.${skipped}`, "info");
+    else if (!await confirm(context, "Prune orphan sessions?", description)) return;
+    await run("Prune", async sync => formatPruneResult(await sync.pruneOrphanSessions(plan.candidates.map(candidate => candidate.path))));
+  }
+
+  async function pushWithPrune(quiet = false): Promise<boolean> {
+    if (busy) return await run("Push", sync => sync.push(), quiet);
+    if (config?.pruneOrphanSessionsBeforePush && service && ctx) {
+      try {
+        const result = await service.pruneOrphanSessions();
+        if (!quiet && (result.removed.length || result.repoRemoved)) ctx.ui.notify(formatPruneResult(result), "info");
+      } catch (failure) {
+        ctx.ui.notify(`amox-pi-sync prune: ${message(failure)}`, "warning");
+      }
+    }
+    return await run("Push", sync => sync.push(), quiet);
+  }
+
   async function startTimers(): Promise<void> {
     stopTimers();
     const token = generation;
@@ -156,7 +191,7 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
         if (token !== generation || next === fingerprint || busy) return;
         if (debounce) clearTimeout(debounce);
         debounce = setTimeout(() => {
-          if (token === generation && !busy) void run("Push", sync => sync.push(), true);
+          if (token === generation && !busy) void pushWithPrune(true);
         }, config!.pushDebounceMs);
       }).catch(failure => {
         const text = message(failure);
@@ -221,8 +256,9 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
     if (config && !busy) {
       body.push("", context.ui.theme.fg("muted", "Actions"),
         { text: actionText(context, "Check status"), onSelect: () => { void run("Check", sync => sync.check()); } },
-        { text: actionText(context, "Push"), onSelect: () => { void run("Push", sync => sync.push()); } },
+        { text: actionText(context, "Push"), onSelect: () => { void pushWithPrune(); } },
         { text: actionText(context, "Pull"), onSelect: () => { void run("Pull", sync => sync.pull()); } },
+        { text: actionText(context, "Prune orphan sessions"), onSelect: () => { void pruneSessions(context); } },
       );
     } else if (!busy) body.push("");
     if (!busy) body.push({ text: actionText(context, "Settings"), onSelect: () => settings(context).catch(report) });
@@ -299,13 +335,17 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
         { value: "status", label: "Status" },
         { value: "mode", label: `Mode: ${config ? modeLabel(config.mode) : "Not configured"}` },
         { value: "paths", label: `Paths: ${config?.paths.length ?? 0} configured` },
+        { value: "prune", label: `Prune before push: ${config?.pruneOrphanSessionsBeforePush ? "On" : "Off"}` },
         ...(bubbleAPI(context)?.version === 1 ? [{ value: "color", label: `Bubble colour: ${colorChoices.find(choice => choice.value === (config?.bubbleColor ?? "pill"))!.label}` }] : []),
         "Backups", "Cleanup", "Diagnostics", "Back",
       ], { rows: overviewRows });
       if (!choice || choice === "Back") return;
       if (choice === "status") { showStatus(context); return; }
       if (!config || !service) { context.ui.notify("Run /sync-setup first.", "warning"); continue; }
-      if (choice === "color") {
+      if (choice === "prune") {
+        const next = { ...config, pruneOrphanSessionsBeforePush: !config.pruneOrphanSessionsBeforePush };
+        await persist(next);
+      } else if (choice === "color") {
         const selected = await select(context, "Sync bubble colour", [...colorChoices, "Back"], { current: config.bubbleColor ?? "pill" });
         if (!selected || selected === "Back") continue;
         const next = { ...config, bubbleColor: selected as NonNullable<Config["bubbleColor"]> };
@@ -406,7 +446,8 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
     error = undefined;
     try {
       config = await loadConfig(paths);
-      makeService();
+      const active = makeService();
+      if (active) await active.initializeBaseline();
     } catch (failure) { error = message(failure); context.ui.notify(`amox-pi-sync config: ${error}`, "error"); }
     // Clear the old upstream widget without creating a replacement widget.
     context.ui.setWidget(STATUS_KEY, undefined);
@@ -442,7 +483,15 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
   });
   pi.registerCommand("sync-push", {
     description: "Push the managed raw data snapshot",
-    handler: async () => { await run("Push", sync => sync.push()); },
+    handler: async () => { await pushWithPrune(); },
+  });
+  pi.registerCommand("sync-prune", {
+    description: "Preview and delete orphan subagent sessions and their snapshot copies",
+    handler: async (args, context) => {
+      const flag = args.trim();
+      if (flag && flag !== "--yes") { context.ui.notify("Usage: /sync-prune [--yes]", "warning"); return; }
+      await pruneSessions(context, flag === "--yes");
+    },
   });
   pi.registerCommand("sync-pull", {
     description: "Pull raw data, backing up files before replacement",
@@ -465,6 +514,7 @@ export default function amoxPiSync(pi: ExtensionAPI): void {
           next.paths = [...config.paths];
           next.mode = config.mode;
           next.bubbleColor = config.bubbleColor;
+          next.pruneOrphanSessionsBeforePush = config.pruneOrphanSessionsBeforePush;
         }
         if (busy) throw new Error(`Sync is busy: ${busy}; retry setup after it finishes.`);
         stopTimers();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gfgghgftgffg/amox-pi-sync",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "Independent Pi agent-data sync fork with SSH Git transport, backups and optional Starline status.",
   "license": "MIT",