@gfgghgftgffg/amox-pi-sync 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MAINTENANCE.md

@@ -0,0 +1,59 @@
+# MAINTENANCE — amox-pi-sync
+
+## Source and attribution
+
+- 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.1`, 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.
+
+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.
+
+Safety requirements: private SSH remote, no working-directory mutation, no JSONL merging, preserve local-only files, back up replacements and never overwrite active sessions. 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.
+
+## 功能取舍与维护边界
+
+本 fork 负责原始 agent 数据的跨设备传输和本地恢复。部署、配置模板与机器路径适配由 `amox-agent-bootstrap` 等部署流程负责；阅读版会话导出使用 Pi 原生 `/export`。使用本扩展不要求安装 bootstrap。
+
+| 上游功能 | 处理 | 原因 |
+| --- | --- | --- |
+| 配置同步、settings 合并 | 删除 | 避免本机同步快照与部署模板成为两个配置来源，也不将机器专属设置直接应用到另一台电脑。通用路径选择仍可传输用户明确选中的安全数据文件，但不提供配置合并或路径适配。 |
+| Markdown/JSON 聊天归档 | 删除 | 本扩展的目标是保留可继续工作的原始会话；上游导出会省略、截断内容，不能代替原始数据。阅读和分享交给 Pi 原生导出，不在同步器内维护另一套渲染器。 |
+| Environment Tools | 删除 | 工具安装和依赖适配归部署流程管理，数据拉取不应同时承担环境安装职责。 |
+| Local Packages | 删除 | 它控制 settings 中本地扩展路径的同步；配置同步移除后不再需要，而且传输路径字符串不会安装路径所指向的代码。 |
+| sessions、missions | 保留 | sessions 保存对话与工具记录；missions 保存工作流任务及关联索引。两者共同保留工作记录，但不保证恢复运行中的任务或临时目录中的外部产物。 |
+| 通用路径选择 | 保留 | 允许用户按需要包含、排除安全的 agent 数据路径，不将范围写死为两个目录；敏感文件与实现目录仍受限制。 |
+| 手动、自动同步 | 保留 | 支持用户主动换机时推拉，也保留可选后台同步；默认手动，不因精简功能改变用户的同步时机。 |
+| 备份恢复 | 保留 | 同路径文件可能被远端内容替换，覆盖前的本地副本是恢复入口。 |
+| Cleanup | 保留并修正 | 即使没有聊天归档，备份仍会积累，需要界面内的手动管理。按完整恢复点预览和确认删除，修正上游保留数量逻辑；不清理 sessions、missions，也不自动删除。 |
+| 诊断 | 保留 | 用户需要查看待传输差异、Git 状态和错误，不能将失败或“未检查”显示为已同步。 |
+| 常驻三行 widget | 替换 | 将状态、操作与设置统一到 Starline 气泡，避免常驻重复信息；未安装 Starline 时保留原生命令界面。 |
+
+精简目标是职责清晰和减少维护范围，未进行启动性能对比。每日监控上游正式发布，保持上述边界定向移植；新增功能应有明确需求，不随上游更新自动恢复已移除模块。
+
+## Repository integration
+
+`maintenance/manifest.json` marks this package `maintenanceMode: selective-fork`. Daily maintenance monitors the latest stable npm publication, not unpublished moving repository HEAD. It compares the exact published baseline and target archives, verifies their SHA-512 integrity, and reads source as untrusted text without installing or executing the original suite. A separate read-only SDK review must cover every changed published file and apply the feature decisions above:
+
+- **Port** worthwhile fixes and improvements within retained behavior, especially data/path safety, backups, diagnostics, background responsiveness and compatibility with the existing Starline UI. Preserve local guarantees; add focused regressions.
+- **Skip** changes only to removed features or irrelevant material. Already-implemented behavior may be skipped only with a concrete source-based explanation. Record the decision; do not bump the package or move the integrated upstream baseline.
+- **Ask** the owner about new features, conflicting goals, unclear value, behavior/safety tradeoffs, compatibility uncertainty or incomplete source/review evidence. Any unresolved item pauses the whole sync port, not other packages. ntfy includes the upstream version delta, reasons and files. Do not call an uncertain change irrelevant to bypass review.
+
+Only a complete review with ports and no unresolved items enables adaptation of `index.ts`/`core.ts` and its scoped tests/docs. The owner’s feature-decisions section is immutable during automatic adaptation. An actual implementation change and focused regression are required; version-only or docs-only ports cannot be published. If implementation reveals new uncertainty, `ask_owner` records the reason, sends ntfy and pauses the existing candidate without further push or merge; it must not bypass a failed check by rebuilding. The fixed host independently stages its package version and publication baseline; local checks, exact-head three-platform CI and Release acceptance still apply. No upstream runtime dependency is added. **Never replace this fork with the full suite or reintroduce removed features.** Tool-context measurements still skip this command-only package.
+
+Skip/ask reports are saved privately under the host maintenance state directory as `fork-review-amox-pi-sync.json`, including the baseline/target, integrity and per-change evidence. The same version and unchanged local implementation/policy reuse the report without another model call; pending owner decisions remain visible in daily ntfy summaries. Source acquisition failures are rechecked. A new target or changed local policy/implementation triggers review again, always against the last integrated baseline so skipped changes cannot hide later relevant fixes. Port decisions are not cached as successful integration. To resolve a pending decision, record the owner's rule in this file and merge it, then rerun maintenance; do not edit a report to fake an approved release.
+
+All workspace packages retain their own versions; the root version identifies a release batch and its explicit package selection. This package also records `releaseVersioning: independent`. Release assets use each manifest/package version in the tarball name; the GitHub release tag remains tied to the root version. Installation and production checks still include this package. `toolContract: false` excludes this command-only fork from upstream-versus-lean tool-size comparisons; `registeredTools: []` is checked during isolated production loading.
+
+来源记录不代表当前 CI/发布结果或现行审批要求。更新前应对比 manifest 中当前固定版本/revision 与目标源码。
+
+## Verification before an update
+
+1. Read the exact published upstream source and its MIT notice, compare only relevant sync behavior, and record the reviewed ref. Do not use repository HEAD as the publication baseline.
+2. Update local implementation and focused regressions without weakening active-session, path, backup or migration guarantees. Keep UI tests isolated from user Pi settings; use temporary data directories and local Git fixtures rather than real remotes.
+3. Run `npm run check --workspace @gfgghgftgffg/amox-pi-sync`, repository integration tests, `npm run contracts:check` and `npm run verify:production`.
+4. Keep package version, manifest version, lockfile and bilingual documentation consistent. Do not publish, change real Pi settings or commit as part of verification.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# amox-pi-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[简体中文](README.zh-CN.md)
+
+Standalone Pi agent-data sync over a private SSH Git repository. Package: `@gfgghgftgffg/amox-pi-sync`. Based on [MuratAitov/pi-sync](https://github.com/MuratAitov/pi-sync), `pi-sync-suite@0.1.1` (MIT; Copyright © 2026 Murat). The exact source reference is `npm:pi-sync-suite@0.1.1`; see [MAINTENANCE.md](MAINTENANCE.md).
+
+## Install
+
+Requires Pi `>=1.1.0`, Node `>=22.19.0`, npm, Git and working SSH authentication.
+
+From this repository checkout:
+
+```sh
+node scripts/install-extension.mjs amox-pi-sync
+```
+
+Only this extension is installed. Do not load it alongside the original `pi-sync-suite`; inspect existing sources with `pi list` and remove the old source yourself. If the first npm publication is pending, use the checkout installer above. Once available, npm installation and updates use:
+
+```sh
+pi install npm:@gfgghgftgffg/amox-pi-sync
+pi update --extensions
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/sync-setup git@host:owner/private-repo.git [interval]` | Configure an SSH repository and optional pull interval in minutes (no transfer) |
+| `/sync-push` | Upload selected raw agent data |
+| `/sync-pull` | Pull selected raw agent data |
+| `/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.
+
+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, upload, 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. `/sync-status`, pill clicks, settings, submenus and confirmations share centered Starline bubbles above the footer; text entry still uses Pi input dialogs. Without Starline, the native UI remains available.
+
+## Data and safety
+
+> [!WARNING]
+> Sessions, missions and other selected files may contain secrets. Use a **private SSH repository**, review included paths, and secure both the remote and local backups. Private Git is not encryption or a secret scrubber.
+
+- 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 JSONL merging. Concurrent edits are not a semantic merge; 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.
+- Git commands disable automatic line-ending conversion so Windows `core.autocrlf` does not rewrite raw sessions. SSH uses system `ssh` with batch mode and a connection timeout, 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.
+- Settings use `amox-pi-sync.json`. If absent, legacy `pi-sync-suite.json` can be read for migration. The old file is not changed before new settings are saved; saving writes the new file. Migration uses a separate `amox-pi-sync-repo` directory rather than reusing the old snapshot.
+
+Configuration sync/settings merging, Markdown/JSON archives, Environment Tools and Local Packages from the original suite are not included. Deployment tools such as `amox-agent-bootstrap` own environment setup and machine-specific configuration; Pi's native `/export` handles readable exports. Raw data selection, backups and manual backup cleanup remain part of sync. See [feature decisions](MAINTENANCE.md#功能取舍与维护边界) for the reasons and maintenance boundaries. This is a selectively maintained fork, not a runtime wrapper or a full replacement of the upstream suite. Daily reviews track published upstream changes, port worthwhile retained behavior, skip removed features and ask the owner through ntfy when uncertain; removed modules are not restored automatically.

package/README.zh-CN.md

@@ -0,0 +1,50 @@
+# amox-pi-sync
+
+[English](README.md)
+
+通过私有 SSH Git 仓库同步 Pi agent 数据的独立扩展。包名：`@gfgghgftgffg/amox-pi-sync`。基于 [MuratAitov/pi-sync](https://github.com/MuratAitov/pi-sync) 的 `pi-sync-suite@0.1.1`（MIT；Copyright © 2026 Murat）。来源 ref 为 `npm:pi-sync-suite@0.1.1`，详见[MAINTENANCE.md](MAINTENANCE.md)。
+
+## 安装
+
+需要 Pi `>=1.1.0`、Node `>=22.19.0`、npm、Git 和可用的 SSH 认证。
+
+在本仓库目录执行：
+
+```sh
+node scripts/install-extension.mjs amox-pi-sync
+```
+
+只安装本扩展。不要同时加载原版 `pi-sync-suite`；通过 `pi list` 检查已有来源，自行移除旧来源。若首次 npm 发布尚未完成，使用上述本地安装方式。npm 包可用后可使用：
+
+```sh
+pi install npm:@gfgghgftgffg/amox-pi-sync
+pi update --extensions
+```
+
+## 命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `/sync-setup git@host:owner/private-repo.git [interval]` | 配置 SSH 仓库及可选拉取间隔（分钟），不传输数据 |
+| `/sync-push` | 上传选中的原始 agent 数据 |
+| `/sync-pull` | 拉取选中的原始 agent 数据 |
+| `/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` 模式仍可手动上传、拉取。
+
+manual/off 启动不访问网络。auto 启动先计算本地 fingerprint，再启动定时器并发起后台拉取，不等待网络完成。`/sync-setup` 只保存配置并停止定时器；已启用 auto 时需 reload 激活。安装 Starline 时，优先点击状态胶囊打开详情，执行状态检查、上传、拉取或设置。状态 key 保留为 `pi-sync`，兼容原 Starline placement；pill bridge 优先于旧 `extensionStatuses.commands`，无需修改 Starline 配置。没有三行 widget。`/sync-status`、点击胶囊、设置和子菜单统一使用底栏上方居中的 Starline 气泡，确认操作也使用相同样式；文本输入仍使用 Pi 输入框。未安装 Starline 时回退原生界面。
+
+## 数据与安全
+
+> [!WARNING]
+> 会话、missions 及其他选中文件可能包含秘密。请使用**私有 SSH 仓库**，检查同步路径，并保护远端和本地备份。私有 Git 不提供加密或秘密清除。
+
+- 路径相对于 Pi agent 数据目录，不是当前项目。可包含/排除任意安全的数据相对路径；扩展不改写工作目录。
+- 传输原始文件，不生成 Markdown/JSON 归档，不合并 JSONL。并发编辑不是语义合并；请协调多设备操作并查看诊断。
+- 保留本地独有文件，不传播删除；同路径的不同内容以拉取数据为准，覆盖前备份；不得覆盖活跃会话。恢复备份只处理当前纳管范围。
+- Git 操作关闭自动换行转换，避免 Windows 的 `core.autocrlf` 改写原始会话。SSH 使用系统 `ssh` 的非交互模式及连接超时，不复用自定义 `core.sshCommand`。
+- 备份位于 agent 数据目录下的 `amox-pi-sync-backups`。Cleanup 仅在手动预览/确认后删除本地备份，按完整备份目录计数，不按单个文件计数。默认数量上限 20 份、最长 180 天；超龄或超出最新 20 份的备份纳入清理候选，不自动删除，不清理 sessions 或 missions。
+- 新设置文件为 `amox-pi-sync.json`；不存在时可读取旧 `pi-sync-suite.json` 迁移。保存新设置前不改旧文件，保存时写入新文件。迁移使用独立的 `amox-pi-sync-repo` 目录，不复用旧快照。
+
+不包含原版的配置同步/settings 合并、Markdown/JSON 归档、Environment Tools 和 Local Packages。环境部署和机器专属配置交给 `amox-agent-bootstrap` 等部署流程，阅读版导出使用 Pi 原生 `/export`；同步器保留原始数据选择、备份恢复和手动备份清理。各项原因与后续维护边界见[功能取舍](MAINTENANCE.md#功能取舍与维护边界)。这是选择性跟进上游的独立 fork，不是调用原版运行时的包装，也不是原版全功能替代品。每日审查上游正式发布，仅移植保留范围内有价值的改动；舍弃功能跳过，不能判断时由 ntfy 请维护者决定，不自动恢复原版模块。

package/core.ts

@@ -0,0 +1,374 @@
+/*
+ * Reduced derivative of pi-sync-suite (config, snapshot, backup, git and engine).
+ * MIT License — Copyright (c) 2026 Murat
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+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 { realpathSync } from "node:fs";
+
+export type Config = {
+  version: 1; repoUrl: string; repoDir: string; mode: "manual" | "auto" | "off";
+  paths: string[]; pullIntervalMinutes: number; watchIntervalMs: number; pushDebounceMs: number;
+  lastPushAt?: string; lastPullAt?: string; lastResult?: string;
+  retention?: { keepBackups: number; maxAgeDays: number };
+};
+export type Paths = { agentDir: string; configFile: string; backupDir: string };
+export type GitExecutor = (args: string[], cwd: string) => Promise<{ stdout: string; stderr: string; code: number }>;
+export type Status = { busy?: string; error?: string; localChanges?: string; remoteChanges?: number; checkedAt?: string };
+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 };
+
+// Canonicalize the trusted agent root (including existing parents). macOS /var
+// and /tmp are OS aliases; links inside managed data are still rejected below.
+function canonicalRoot(input: string): string {
+  let parent = path.resolve(input);
+  const missing: string[] = [];
+  for (;;) {
+    try { return path.join(realpathSync.native(parent), ...missing.reverse()); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      const next = path.dirname(parent);
+      if (next === parent) throw error;
+      missing.push(path.basename(parent));
+      parent = next;
+    }
+  }
+}
+export function defaultPaths(agentDir = process.env.PI_CODING_AGENT_DIR ?? path.join(homedir(), ".pi", "agent")): Paths {
+  agentDir = canonicalRoot(agentDir);
+  return { agentDir, configFile: path.join(agentDir, "amox-pi-sync.json"), backupDir: path.join(agentDir, "amox-pi-sync-backups") };
+}
+const forbidden = /^(?:auth(?:\..*)?|settings(?:\..*)?|credentials?(?:\..*)?|\.env(?:\..*)?|\.git(?:\..*)?|git|\.ssh|npm|bin|node_modules|packages|local-packages|pi-sync-suite\.json|pi-sync-environment(?:-ignore)?\.json|sync-suite-repo|sync-suite-backups|sync-suite-chat-exports|amox-pi-sync(?:\..*|-.*)?)$/i;
+/** Agent-relative portable paths only; all components are checked, including nested files. */
+export function validatePath(input: string): string {
+  if (typeof input !== "string" || !input || /[\x00-\x1f<>:"|?*]/.test(input) || /^[\\/]/.test(input)) throw new Error(`Unsafe relative path: ${input}`);
+  const clean = input.replaceAll("\\", "/");
+  if (clean.split("/").some(p => !p || p === "." || p === ".." || /[. ]$/.test(p) || forbidden.test(p) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(p))) throw new Error(`Forbidden sync path: ${input}`);
+  return clean;
+}
+function inside(parent: string, child: string): boolean {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === "" || (!rel.startsWith(`..${path.sep}`) && rel !== ".." && !path.isAbsolute(rel));
+}
+function overlaps(a: string, b: string): boolean { return inside(a, b) || inside(b, a); }
+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;
+  try {
+    const u = new URL(url);
+    if (u.protocol === "ssh:" && u.hostname && !u.password && !u.search && !u.hash && /^\/[a-zA-Z0-9_~][a-zA-Z0-9._~/-]*$/.test(u.pathname) && !/%|\.\./.test(url) && /^[a-zA-Z0-9._-]*$/.test(u.username)) return;
+  } catch { /* reject below */ }
+  throw new Error("Use an SSH git URL: git@host:path or ssh://user@host/path");
+}
+function validate(config: Config, paths: Paths): void {
+  remote(config.repoUrl);
+  if (config.version !== 1 || !["manual", "auto", "off"].includes(config.mode)) throw new Error("Unsupported sync version or mode");
+  if (!path.isAbsolute(config.repoDir)) throw new Error("repoDir must be absolute");
+  if (!Array.isArray(config.paths)) throw new Error("paths must be an array");
+  const selected = config.paths.map(validatePath).map(p => path.resolve(paths.agentDir, p));
+  for (let i = 0; i < selected.length; i++) {
+    const p = selected[i]!;
+    if (selected.slice(i + 1).some(other => overlaps(p, other))) throw new Error("Managed paths must not overlap");
+    if ([config.repoDir, paths.backupDir, paths.configFile, `${paths.configFile}.lock`, path.join(paths.agentDir, "pi-sync-suite.json")].some(other => overlaps(p, other))) throw new Error("Managed paths overlap sync config, repository or backup directory");
+  }
+  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");
+  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 };
+  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; } }
+async function noLinks(file: string): Promise<void> {
+  const full = path.resolve(file); const parent = path.dirname(full);
+  if (parent !== full) await noLinks(parent);
+  if ((await stat(full))?.isSymbolicLink()) throw new Error(`Refusing symlink: ${full}`);
+}
+export async function loadConfig(paths = defaultPaths()): Promise<Config | null> {
+  await noLinks(paths.configFile);
+  if (await stat(paths.configFile)) {
+    const config = JSON.parse(await fs.readFile(paths.configFile, "utf8")) as Config;
+    validate(config, paths); return config;
+  }
+  const oldFile = path.join(paths.agentDir, "pi-sync-suite.json");
+  await noLinks(oldFile);
+  if (!(await stat(oldFile))) return null;
+  const old = JSON.parse(await fs.readFile(oldFile, "utf8"));
+  if (old.version !== 1) throw new Error("Unsupported legacy config version");
+  const config = createConfig(old.repoUrl, paths);
+  config.mode = old.autoMode === "off" ? "off" : ["full-auto", "config-only-auto"].includes(old.autoMode) ? "auto" : "manual";
+  const allowed = Array.isArray(old.policy?.includedPaths) ? old.policy.includedPaths.filter((p: unknown) => p === "sessions" || p === "missions") : [];
+  if (allowed.length) config.paths = [...new Set<string>(allowed)];
+  for (const key of ["pullIntervalMinutes", "watchIntervalMs", "pushDebounceMs"] as const) if (old[key] !== undefined) config[key] = old[key];
+  validate(config, paths); return config;
+}
+export async function saveConfig(config: Config, paths = defaultPaths()): Promise<void> {
+  validate(config, paths); await noLinks(paths.configFile);
+  await fs.mkdir(path.dirname(paths.configFile), { recursive: true });
+  const temp = `${paths.configFile}.${randomUUID()}.tmp`;
+  try { await fs.writeFile(temp, JSON.stringify(config, null, 2) + "\n", { mode: 0o600, flag: "wx" }); await fs.rename(temp, paths.configFile); }
+  finally { await fs.rm(temp, { force: true }); }
+}
+
+// Raw sessions are opaque bytes and intentionally bypass content scanning. Use a
+// trusted PRIVATE repository: sessions may contain credentials or private text.
+const secret = /-----BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----|\bghp_[A-Za-z0-9_]{30,}\b|\bsk-[A-Za-z0-9_-]{20,}\b|\b(?:api[_-]?key|token|password|secret)\b\s*[:=]\s*["']?[^"'\s]{12,}/i;
+const gitOptions = ["-c", "core.hooksPath=", "-c", "core.autocrlf=false", "-c", "credential.interactive=false", "-c", "core.sshCommand=ssh -oBatchMode=yes -oConnectTimeout=10"];
+type Files = Map<string, Buffer>;
+export class SyncService {
+  public status: Status = {};
+  public activeSessionFile?: string;
+  constructor(public config: Config, public paths: Paths, private exec: GitExecutor) { validate(config, paths); }
+  private async run<T>(name: string, work: () => Promise<T>): Promise<T> {
+    if (this.status.busy) throw new Error(`Sync busy: ${this.status.busy}; retry when it finishes`);
+    this.status.busy = name; this.status.error = undefined;
+    let lock: Awaited<ReturnType<typeof fs.open>> | undefined;
+    const lockFile = `${this.paths.configFile}.lock`;
+    try {
+      validate(this.config, this.paths);
+      await noLinks(lockFile); await fs.mkdir(path.dirname(lockFile), { recursive: true });
+      try { lock = await fs.open(lockFile, "wx", 0o600); }
+      catch (e) { if ((e as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Sync locked by another process: ${lockFile}. If its process exited, verify no sync is running before removing this lock.`); throw e; }
+      await lock.writeFile(JSON.stringify({ pid: process.pid, operation: name, createdAt: new Date().toISOString() }));
+      return await work();
+    } catch (e) { this.status.error = e instanceof Error ? e.message : String(e); throw e; }
+    finally { try { if (lock) { await lock.close(); await fs.unlink(lockFile); } } finally { this.status.busy = undefined; } }
+  }
+  private async git(args: string[], cwd = this.config.repoDir): Promise<string> {
+    const result = await this.exec([...gitOptions, ...args], cwd);
+    if (result.code !== 0) throw new Error(`git ${args[0]} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}. Resolve repository conflicts manually; no force push or JSONL merge is performed.`);
+    return result.stdout;
+  }
+  private async ensureRepo(): Promise<void> {
+    await noLinks(this.config.repoDir);
+    const gitDir = path.join(this.config.repoDir, ".git"); await noLinks(gitDir);
+    if (!(await stat(gitDir))) {
+      if (await stat(this.config.repoDir) && (await fs.readdir(this.config.repoDir)).length) throw new Error("Repository directory is nonempty but has no .git; choose an empty directory");
+      await fs.mkdir(path.dirname(this.config.repoDir), { recursive: true });
+      await this.git(["clone", "--", this.config.repoUrl, this.config.repoDir], path.dirname(this.config.repoDir));
+    }
+    const origin = (await this.git(["remote", "get-url", "origin"])).trim();
+    if (origin !== this.config.repoUrl) throw new Error("Repository origin differs from configured SSH URL; inspect it before syncing");
+    const pushUrls = (await this.git(["remote", "get-url", "--push", "--all", "origin"])).trim().split(/\r?\n/);
+    if (pushUrls.some(url => url !== this.config.repoUrl)) throw new Error("Repository push URL differs from configured SSH URL");
+    for (const file of (await this.git(["ls-files", "-z"])).split("\0").filter(Boolean)) validatePath(file);
+  }
+  private async collect(root: string, scan = false): Promise<Files> {
+    const files: Files = new Map();
+    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()) {
+        const data = await fs.readFile(absolute);
+        if (scan && relative.split("/")[0] !== "sessions" && secret.test(data.toString("utf8"))) throw new Error(`Secret-like content in ${relative}; remove credentials before syncing`);
+        files.set(relative, data);
+      } else throw new Error(`Not a regular file: ${relative}`);
+    };
+    for (const item of this.config.paths) await visit(validatePath(item));
+    return files;
+  }
+  private async write(root: string, files: Files): Promise<void> {
+    for (const [relative, data] of files) {
+      const file = path.join(root, validatePath(relative)); await noLinks(file);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      const tmp = `${file}.${randomUUID()}.tmp`;
+      try { await fs.writeFile(tmp, data, { flag: "wx", mode: 0o600 }); await fs.rename(tmp, file); }
+      finally { await fs.rm(tmp, { force: true }); }
+    }
+  }
+  private async makeBackup(reason: string): Promise<Backup> {
+    const files = await this.collect(this.paths.agentDir);
+    const id = `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${randomUUID()}`;
+    const root = path.join(this.paths.backupDir, id); await noLinks(root);
+    await fs.mkdir(path.join(root, "files"), { recursive: true });
+    await this.write(path.join(root, "files"), files);
+    const manifest: Backup = { id, createdAt: new Date().toISOString(), reason, includedPaths: [...this.config.paths] };
+    await fs.writeFile(path.join(root, "manifest.json"), JSON.stringify(manifest, null, 2), { flag: "wx", mode: 0o600 });
+    return manifest;
+  }
+  private async backups(): Promise<Backup[]> {
+    await noLinks(this.paths.backupDir);
+    if (!(await stat(this.paths.backupDir))) return [];
+    const result: Backup[] = [];
+    for (const entry of await fs.readdir(this.paths.backupDir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error(`Refusing backup symlink: ${entry.name}`);
+      if (!entry.isDirectory()) continue;
+      const file = path.join(this.paths.backupDir, entry.name, "manifest.json"); await noLinks(file);
+      if (!(await stat(file))) continue; // interrupted backup, not restorable
+      const manifest = JSON.parse(await fs.readFile(file, "utf8")) as Backup;
+      if (manifest.id !== entry.name || !Array.isArray(manifest.includedPaths) || !Number.isFinite(Date.parse(manifest.createdAt)) || typeof manifest.reason !== "string") throw new Error(`Invalid backup manifest: ${entry.name}`);
+      manifest.includedPaths.forEach(validatePath);
+      const filesDir = path.join(this.paths.backupDir, entry.name, "files"); await noLinks(filesDir);
+      if (!(await stat(filesDir))?.isDirectory()) throw new Error(`Incomplete backup: ${entry.name}`);
+      result.push(manifest);
+    }
+    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[] = [];
+    for (const [relative, data] of files) {
+      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.`);
+      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: [] };
+    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(", ")}` : ""}`;
+    this.config.lastResult = message;
+    return { changed: changes.size > 0, message, files: [...changes.keys()], backupId: backup.id };
+  }
+  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"]);
+    const local = await this.collect(this.paths.agentDir, true);
+    const snapshot = await this.collect(this.config.repoDir, true);
+    let added = 0; let changed = 0; let remoteOnly = 0;
+    for (const [file, data] of local) {
+      const other = snapshot.get(file);
+      if (!other) added++;
+      else if (!data.equals(other)) changed++;
+    }
+    for (const file of snapshot.keys()) if (!local.has(file)) remoteOnly++;
+    const localChanges = added || changed || remoteOnly ? `added/local-only: ${added}; changed: ${changed}; remote-only: ${remoteOnly}` : "";
+    const upstream = await this.exec([...gitOptions, "rev-parse", "--verify", "@{u}"], this.config.repoDir);
+    const remoteChanges = upstream.code === 0 ? Number((await this.git(["rev-list", "--count", "HEAD..@{u}"])).trim()) : undefined;
+    this.status.localChanges = localChanges; this.status.remoteChanges = remoteChanges;
+    this.status.checkedAt = new Date().toISOString(); return { ...this.status, busy: undefined };
+  }); }
+  async push(): Promise<string> { return this.run("push", async () => {
+    await this.ensureRepo();
+    if ((await this.git(["diff", "--cached", "--name-only"])).trim()) throw new Error("Repository has staged changes; inspect/commit them manually before sync");
+    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);
+    await this.write(this.config.repoDir, files);
+    let batch: string[] = []; let budget = 0;
+    for (const file of files.keys()) {
+      // Include quoting/argument overhead within Windows' command-line limit.
+      const cost = file.length * 2 + 3;
+      if (budget + cost > 6000 && batch.length) {
+        await this.git(["--literal-pathspecs", "add", "--", ...batch]); batch = []; budget = 0;
+      }
+      batch.push(file); budget += cost;
+    }
+    if (batch.length) await this.git(["--literal-pathspecs", "add", "--", ...batch]);
+    const staged = (await this.git(["diff", "--cached", "--name-only"])).trim();
+    if (staged) await this.git(["commit", "-m", `amox-pi-sync: ${new Date().toISOString()}`]);
+    // Always retry push, even when the previous attempt committed but failed offline.
+    await this.git(["push", "-u", "origin", "HEAD"]);
+    this.config.lastPushAt = new Date().toISOString();
+    this.config.lastResult = "Pushed managed snapshot (no force push; remote-only files preserved)";
+    await saveConfig(this.config, this.paths);
+    return this.config.lastResult;
+  }); }
+  async pull(): Promise<string> { return this.run("pull", async () => {
+    await this.ensureRepo();
+    if ((await this.git(["status", "--porcelain"])).trim()) throw new Error("Repository has uncommitted changes; resolve them before ff-only pull");
+    await this.git(["pull", "--ff-only", "origin"]);
+    const result = await this.apply(await this.collect(this.config.repoDir, true), "before applying remote snapshot");
+    this.config.lastPullAt = new Date().toISOString(); await saveConfig(this.config, this.paths); return result.message;
+  }); }
+  async backup(): Promise<Backup> { return this.run("backup", () => this.makeBackup("manual")); }
+  async listBackups(): Promise<Backup[]> { return this.run("listBackups", () => this.backups()); }
+  async restore(id = "latest"): Promise<string> { return this.run("restore", async () => {
+    const list = await this.backups(); const found = id === "latest" ? list[0] : list.find(b => b.id === id);
+    if (!found) throw new Error(`Backup not found: ${id}`);
+    // Never trust absolute source paths or a path list supplied by a manifest.
+    const result = await this.apply(await this.collect(path.join(this.paths.backupDir, found.id, "files")), `before restoring ${found.id}`);
+    await saveConfig(this.config, this.paths); return result.message;
+  }); }
+  /** Preview only. Nothing is removed automatically, including in auto mode. */
+  async planCleanup(): Promise<BackupSummary[]> { return this.run("planCleanup", async () => {
+    const retention = this.config.retention ?? { keepBackups: 20, maxAgeDays: 180 };
+    const cutoff = Date.now() - retention.maxAgeDays * 86400000;
+    return (await this.backups()).flatMap((backup, index) => {
+      const expired = Date.parse(backup.createdAt) < cutoff;
+      const excess = index >= retention.keepBackups;
+      return expired || excess ? [{ ...backup, reason: expired ? `older than ${retention.maxAgeDays} days` : `exceeds newest ${retention.keepBackups} backups` }] : [];
+    });
+  }); }
+  /** UI must preview and confirm first; IDs may explicitly select retained backups. */
+  async applyCleanup(ids: string[]): Promise<number> { return this.run("applyCleanup", async () => {
+    if (!Array.isArray(ids) || ids.some(id => typeof id !== "string" || !id || id === "." || id === ".." || /[\\/\\\\:\x00-\x1f]/.test(id))) throw new Error("Invalid backup ID for cleanup");
+    const known = new Set((await this.backups()).map(backup => backup.id));
+    const unique = [...new Set(ids)];
+    // Validate the complete selection before deleting anything.
+    for (const id of unique) {
+      if (!known.has(id)) throw new Error(`Unknown or incomplete backup: ${id}`);
+      const target = path.resolve(this.paths.backupDir, id);
+      if (path.dirname(target) !== path.resolve(this.paths.backupDir) || [this.paths.agentDir, this.config.repoDir, this.paths.configFile, ...this.config.paths.map(p => path.join(this.paths.agentDir, p))].some(p => inside(target, p))) throw new Error(`Unsafe backup deletion: ${id}`);
+      await noLinks(target);
+    }
+    for (const id of unique) await fs.rm(path.join(this.paths.backupDir, id), { recursive: true });
+    return unique.length;
+  }); }
+  /** Read-only polling: no operation lock or status changes, one file buffer at a time. */
+  async fingerprint(): Promise<string> {
+    validate(this.config, this.paths);
+    const hash = createHash("sha256");
+    const visit = async (relative: string): Promise<void> => {
+      validatePath(relative);
+      const absolute = path.join(this.paths.agentDir, 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()) {
+        const data = await fs.readFile(absolute);
+        hash.update(JSON.stringify([relative, data.length])).update(data);
+      } else throw new Error(`Not a regular file: ${relative}`);
+    };
+    for (const item of this.config.paths) await visit(validatePath(item));
+    return hash.digest("hex");
+  }
+  async log(): Promise<string> { return this.run("log", async () => { await this.ensureRepo(); return (await this.git(["log", "--oneline", "-8"])).trim(); }); }
+  async doctor(): Promise<{ name: string; ok: boolean; message: string }[]> { return this.run("doctor", async () => {
+    const checks: { name: string; ok: boolean; message: string }[] = [];
+    const check = async (name: string, work: () => Promise<string>) => { try { checks.push({ name, ok: true, message: await work() }); } catch (e) { checks.push({ name, ok: false, message: String(e) }); } };
+    await check("git", () => this.git(["--version"], this.paths.agentDir));
+    await check("paths", async () => { await this.collect(this.paths.agentDir); return this.config.paths.join(", "); });
+    await check("repository", async () => {
+      await noLinks(this.config.repoDir);
+      if (!(await stat(path.join(this.config.repoDir, ".git")))) throw new Error("Not cloned; check/push/pull will initialize it");
+      const url = (await this.git(["remote", "get-url", "origin"])).trim();
+      if (url !== this.config.repoUrl) throw new Error("origin differs from configured URL");
+      return await this.git(["status", "--short", "--branch"]);
+    });
+    await check("identity", async () => `${(await this.git(["var", "GIT_AUTHOR_IDENT"], await stat(this.config.repoDir) ? this.config.repoDir : this.paths.agentDir)).trim()}`);
+    return checks;
+  }); }
+}

package/index.ts

@@ -0,0 +1,391 @@
+// Derived from pi-sync-suite 0.1.1, Copyright (c) 2026 Murat (MIT).
+// Upstream: https://github.com/MuratAitov/pi-sync
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SyncService, createConfig, defaultPaths, loadConfig, saveConfig, validatePath, type Config } from "./core.ts";
+
+type BubbleLine = string | { text: string; onSelect: () => void };
+type BubbleContent = { title: string; body: BubbleLine[]; hint: string };
+type BubbleHandle = { refresh(): void; close(): void; onClose?(callback: () => void): void };
+type PillAPI = {
+  version: number;
+  register(key: string, action: (input: { ctx: ExtensionContext; pill?: unknown }) => void): () => void;
+  showBubble(ctx: ExtensionContext, source: () => BubbleContent, pill?: unknown): BubbleHandle | undefined;
+};
+const STATUS_KEY = "pi-sync";
+const pillAPI = () => (globalThis as Record<symbol, unknown>)[Symbol.for("pi-starline.pill-api.v1")] as PillAPI | undefined;
+const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+const displayTime = (value?: string) => value ? new Date(value).toLocaleString() : "never";
+
+export default function amoxPiSync(pi: ExtensionAPI): void {
+  let ctx: ExtensionContext | undefined;
+  let config: Config | null = null;
+  let service: SyncService | undefined;
+  let paths = defaultPaths(process.env.PI_CODING_AGENT_DIR);
+  let busy: string | undefined;
+  let inFlight: Promise<void> | undefined;
+  let error: string | undefined;
+  let notice: string | undefined;
+  let bubble: BubbleHandle | undefined;
+  let unregister: (() => void) | undefined;
+  let pullTimer: ReturnType<typeof setInterval> | undefined;
+  let watchTimer: ReturnType<typeof setInterval> | undefined;
+  let debounce: ReturnType<typeof setTimeout> | undefined;
+  let fingerprint: string | undefined;
+  let watching = false;
+  let generation = 0;
+
+  const publish = () => {
+    ctx?.ui.setStatus(STATUS_KEY, `Sync: ${busy ?? (error ? "error" : config?.mode ?? "setup")}`);
+    bubble?.refresh();
+  };
+
+  function stopTimers(): void {
+    generation++;
+    if (pullTimer) clearInterval(pullTimer);
+    if (watchTimer) clearInterval(watchTimer);
+    if (debounce) clearTimeout(debounce);
+    pullTimer = watchTimer = debounce = undefined;
+    fingerprint = undefined;
+  }
+
+  function makeService(): void {
+    service = config ? new SyncService(config, paths, async (args, cwd) => {
+      const result = await pi.exec("git", args, { cwd, timeout: 60_000 });
+      return { stdout: result.stdout, stderr: result.stderr, code: result.code };
+    }) : undefined;
+    if (service) service.activeSessionFile = ctx?.sessionManager.getSessionFile();
+  }
+
+  async function run(label: string, action: (sync: SyncService) => Promise<unknown>, quiet = false): Promise<boolean> {
+    if (!service || !config || !ctx) {
+      if (!quiet) ctx?.ui.notify("Run /sync-setup <private-ssh-repository> first.", "warning");
+      return false;
+    }
+    if (busy) {
+      if (!quiet) ctx.ui.notify(`Sync is already ${busy}.`, "warning");
+      return false;
+    }
+    const active = service;
+    const context = ctx;
+    active.activeSessionFile = context.sessionManager.getSessionFile();
+    busy = label;
+    let finish!: () => void;
+    const settled = new Promise<void>(resolve => { finish = resolve; });
+    inFlight = settled;
+    error = undefined;
+    publish();
+    try {
+      const uploadedFingerprint = label === "uploading" ? await active.fingerprint() : undefined;
+      const result = await action(active);
+      notice = typeof result === "string" ? result : `${label} completed`;
+      // Mark only the pre-upload snapshot as observed. Changes made while Git
+      // runs must remain detectable by the next watcher pass.
+      if (uploadedFingerprint !== undefined) fingerprint = uploadedFingerprint;
+      if (!quiet) context.ui.notify(notice, "info");
+      return true;
+    } catch (failure) {
+      error = message(failure);
+      context.ui.notify(`amox-pi-sync ${label}: ${error}`, "error");
+      return false;
+    } finally {
+      busy = undefined;
+      publish();
+      finish();
+      if (inFlight === settled) inFlight = undefined;
+    }
+  }
+
+  async function startTimers(): Promise<void> {
+    stopTimers();
+    const token = generation;
+    if (!config || !service || config.mode !== "auto") return;
+    const active = service;
+    try {
+      fingerprint = await active.fingerprint();
+    } catch (failure) {
+      error = message(failure);
+      ctx?.ui.notify(`amox-pi-sync watcher: ${error}`, "error");
+      publish();
+      return;
+    }
+    if (token !== generation) return;
+    pullTimer = setInterval(() => {
+      if (!busy) void run("downloading", sync => sync.pull(), true);
+    }, config.pullIntervalMinutes * 60_000);
+    watchTimer = setInterval(() => {
+      if (busy || watching) return;
+      watching = true;
+      void active.fingerprint().then(next => {
+        if (token !== generation || next === fingerprint || busy) return;
+        if (debounce) clearTimeout(debounce);
+        debounce = setTimeout(() => {
+          if (token === generation && !busy) void run("uploading", sync => sync.push(), true);
+        }, config!.pushDebounceMs);
+      }).catch(failure => {
+        const text = message(failure);
+        if (text !== error) ctx?.ui.notify(`amox-pi-sync watcher: ${text}`, "error");
+        error = text;
+        publish();
+      }).finally(() => { watching = false; });
+    }, config.watchIntervalMs);
+    // Do not await network during session startup.
+    void run("downloading", sync => sync.pull(), true);
+  }
+
+  function detailLines(): string[] {
+    if (!config || !service) return ["Not configured", "Use /sync-setup <private-ssh-repository>", ...(error ? [`Error: ${error}`] : [])];
+    const status = service.status;
+    return [
+      `State: ${busy ?? (error ? "error" : `idle (${config.mode})`)}`,
+      `Objects: ${config.paths.join(", ") || "none"}`,
+      `Remote: ${config.repoUrl}`,
+      `Last upload: ${displayTime(config.lastPushAt)}`,
+      `Last pull: ${displayTime(config.lastPullAt)}`,
+      `Local: ${status.localChanges?.trim() || (status.checkedAt ? "no pending changes at last check" : "not checked")}`,
+      `Remote updates: ${status.remoteChanges === undefined ? "not checked" : status.remoteChanges}`,
+      `Checked: ${displayTime(status.checkedAt)}`,
+      ...(config.lastResult ? [`Last sync result: ${config.lastResult}`] : []),
+      ...(notice ? [`Last action: ${notice}`] : []),
+      ...(error ? [`Error: ${error}`] : []),
+    ];
+  }
+
+  function content(context: ExtensionContext): BubbleContent {
+    const body: BubbleLine[] = detailLines();
+    if (config && !busy) {
+      body.push(
+        { text: "Check status", onSelect: () => { void run("checking", sync => sync.check()); } },
+        { text: "Upload", onSelect: () => { void run("uploading", sync => sync.push()); } },
+        { text: "Pull", onSelect: () => { void run("downloading", sync => sync.pull()); } },
+      );
+    }
+    if (!busy) body.push({ text: "Settings", onSelect: () => settings(context).catch(report) });
+    return { title: "Amox Pi Sync", body, hint: "Last-check values are not a live guarantee · Esc to close" };
+  }
+
+  function showStatus(context: ExtensionContext): void {
+    const api = pillAPI();
+    if (api?.version === 1 && context.hasUI) {
+      // All command, pill and menu views share Starline's unanchored placement.
+      bubble = api.showBubble(context, () => content(context));
+    } else {
+      context.ui.notify(detailLines().join("\n"), error ? "warning" : "info");
+    }
+  }
+
+  async function select(context: ExtensionContext, title: string, options: string[], description?: string): Promise<string | undefined> {
+    const api = pillAPI();
+    if (api?.version !== 1 || !context.hasUI) return context.ui.select(title, options);
+    return new Promise(resolve => {
+      let selected = false;
+      const handle = api.showBubble(context, () => ({
+        title,
+        body: [
+          ...(description ? [description] : []),
+          ...options.map(text => ({ text, onSelect: () => { selected = true; resolve(text); } })),
+        ],
+        hint: "↑/↓ · Enter to select · Esc to close",
+      }));
+      bubble = handle;
+      if (handle?.onClose) {
+        // Starline closes the bubble before calling a target's onSelect.
+        // Defer cancellation until that synchronous callback has run.
+        handle.onClose(() => queueMicrotask(() => { if (!selected) resolve(undefined); }));
+      } else {
+        handle?.close();
+        void context.ui.select(title, options).then(resolve);
+      }
+    });
+  }
+
+  async function confirm(context: ExtensionContext, title: string, description: string): Promise<boolean> {
+    if (pillAPI()?.version !== 1 || !context.hasUI) return context.ui.confirm(title, description);
+    return await select(context, title, ["Cancel", "Confirm"], description) === "Confirm";
+  }
+
+  const report = (failure: unknown) => {
+    error = message(failure);
+    ctx?.ui.notify(`amox-pi-sync: ${error}`, "error");
+    publish();
+  };
+
+  async function persist(next: Config): Promise<void> {
+    if (busy) throw new Error(`Sync is already ${busy}; retry the settings change after it finishes.`);
+    await saveConfig(next, paths);
+    config = next;
+    makeService();
+    publish();
+    await startTimers();
+  }
+
+  async function settings(context: ExtensionContext): Promise<void> {
+    if (busy) { context.ui.notify(`Sync is already ${busy}.`, "warning"); return; }
+    for (;;) {
+      const choice = await select(context, "Amox Pi Sync", [
+        "View Status", `Sync Mode [${config?.mode ?? "not configured"}]`,
+        `Sync Paths [${config?.paths.length ?? 0}]`, "Backups", "Cleanup", "Diagnostics", "Back",
+      ]);
+      if (!choice || choice === "Back") return;
+      if (choice === "View Status") { showStatus(context); return; }
+      if (!config || !service) { context.ui.notify("Run /sync-setup first.", "warning"); continue; }
+      if (choice.startsWith("Sync Mode")) {
+        const selected = await select(context, "Sync mode", ["Manual", "Auto", "Off", "Back"]);
+        if (!selected || selected === "Back") continue;
+        const next = structuredClone(config);
+        if (selected === "Auto") {
+          const minutes = await context.ui.input("Pull interval in minutes", String(config.pullIntervalMinutes));
+          if (minutes === undefined) continue;
+          if (!/^\d+$/.test(minutes) || Number(minutes) < 1 || Number(minutes) > 35_790) {
+            context.ui.notify("Use a whole number from 1 to 35790 minutes.", "error"); continue;
+          }
+          next.pullIntervalMinutes = Number(minutes);
+        }
+        next.mode = selected.toLowerCase() as Config["mode"];
+        await persist(next);
+      } else if (choice.startsWith("Sync Paths")) {
+        const selected = await select(context, "Sync paths", [
+          ...config.paths.map(item => `Exclude ${item}`), "Include path", "Back",
+        ]);
+        if (!selected || selected === "Back") continue;
+        const next = structuredClone(config);
+        if (selected === "Include path") {
+          const entered = await context.ui.input("Relative path inside Pi agent directory", "missions");
+          if (!entered) continue;
+          const item = validatePath(entered);
+          if (!next.paths.includes(item)) next.paths.push(item);
+        } else next.paths = next.paths.filter(item => `Exclude ${item}` !== selected);
+        await persist(next);
+      } else if (choice === "Backups") {
+        const selected = await select(context, "Backups (local; no automatic cleanup)", ["Create", "List", "Restore", "Back"]);
+        if (selected === "Create") await run("backing up", async sync => {
+          const backup = await sync.backup(); return JSON.stringify(backup, null, 2);
+        });
+        if (selected === "List") await run("listing backups", async sync => JSON.stringify(await sync.listBackups(), null, 2));
+        if (selected === "Restore") {
+          const backups = await service.listBackups();
+          if (!backups.length) { context.ui.notify("No backups.", "info"); continue; }
+          const id = await context.ui.input("Backup ID", "latest");
+          if (!id) continue;
+          if (!await confirm(context, "Restore backup?", "Matching managed files can be overwritten. A pre-restore backup will be created. The active session cannot be replaced.")) continue;
+          await run("restoring", sync => sync.restore(id));
+        }
+      } else if (choice === "Cleanup") {
+        const selected = await select(context, "Cleanup (complete local backups only)", ["Preview", "Run", "Delete Selected Backup", "Retention", "Back"]);
+        if (selected === "Preview" || selected === "Run") {
+          let candidates: Awaited<ReturnType<SyncService["planCleanup"]>> = [];
+          const planned = await run("planning cleanup", async sync => {
+            candidates = await sync.planCleanup();
+            return candidates.length ? JSON.stringify(candidates, null, 2) : "No backup cleanup candidates.";
+          });
+          if (!planned || selected !== "Run" || !candidates.length) continue;
+          if (await confirm(context, "Delete complete backups?", `Delete ${candidates.length} previewed backup(s)? Sessions, missions and the sync repository will not be deleted.`)) {
+            await run("cleaning backups", async sync => `Deleted ${await sync.applyCleanup(candidates.map(item => item.id))} backup(s).`);
+          }
+        } else if (selected === "Delete Selected Backup") {
+          const backups = await service.listBackups();
+          if (!backups.length) { context.ui.notify("No backups.", "info"); continue; }
+          const id = await select(context, "Select complete backup to delete", [...backups.map(item => item.id), "Back"]);
+          if (!id || id === "Back") continue;
+          if (await confirm(context, "Delete backup?", `Permanently delete local backup ${id}?`)) {
+            await run("cleaning backups", async sync => `Deleted ${await sync.applyCleanup([id])} backup.`);
+          }
+        } else if (selected === "Retention") {
+          const keep = await context.ui.input("Keep newest complete backups (0 or more)", String(config.retention?.keepBackups ?? 20));
+          if (keep === undefined) continue;
+          const days = await context.ui.input("Maximum backup age in days (1 or more)", String(config.retention?.maxAgeDays ?? 180));
+          if (days === undefined) continue;
+          if (!/^\d+$/.test(keep) || !/^\d+$/.test(days) || !Number.isSafeInteger(Number(keep)) || !Number.isSafeInteger(Number(days)) || Number(days) < 1) {
+            context.ui.notify("Retention requires a nonnegative whole backup count and positive whole day count.", "error"); continue;
+          }
+          const next = structuredClone(config);
+          next.retention = { keepBackups: Number(keep), maxAgeDays: Number(days) };
+          await persist(next);
+          context.ui.notify("Retention saved. Cleanup remains manual; no files deleted.", "info");
+        }
+      } else if (choice === "Diagnostics") {
+        const selected = await select(context, "Diagnostics", ["Doctor", "Diff / Check", "Log", "Back"]);
+        if (selected === "Doctor") await run("diagnosing", async sync => JSON.stringify(await sync.doctor(), null, 2));
+        if (selected === "Diff / Check") await run("checking", async sync => { await sync.check(); return detailLines().join("\n"); });
+        if (selected === "Log") await run("reading log", sync => sync.log());
+      }
+    }
+  }
+
+  pi.on("session_start", async (_event, context) => {
+    stopTimers();
+    ctx = context;
+    paths = defaultPaths(process.env.PI_CODING_AGENT_DIR);
+    config = null;
+    service = undefined;
+    error = undefined;
+    try {
+      config = await loadConfig(paths);
+      makeService();
+    } 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);
+    publish();
+    unregister?.();
+    const api = pillAPI();
+    unregister = api?.version === 1 ? api.register(STATUS_KEY, ({ ctx: current }) => showStatus(current)) : undefined;
+    await startTimers();
+  });
+
+  pi.on("session_shutdown", async () => {
+    stopTimers();
+    unregister?.();
+    unregister = undefined;
+    bubble?.close();
+    bubble = undefined;
+    await inFlight;
+    ctx?.ui.setStatus(STATUS_KEY, undefined);
+    ctx = undefined;
+  });
+
+  pi.registerCommand("sync-status", {
+    description: "Show sync state, managed paths, last results and actions",
+    handler: async (_args, context) => { showStatus(context); },
+  });
+  pi.registerCommand("sync-settings", {
+    description: "Manage sync mode, paths, backups and diagnostics",
+    handler: async (_args, context) => { await settings(context).catch(report); },
+  });
+  pi.registerCommand("sync-push", {
+    description: "Upload the managed raw data snapshot",
+    handler: async () => { await run("uploading", sync => sync.push()); },
+  });
+  pi.registerCommand("sync-pull", {
+    description: "Pull raw data, backing up files before replacement",
+    handler: async () => { await run("downloading", sync => sync.pull()); },
+  });
+  pi.registerCommand("sync-setup", {
+    description: "Configure a private SSH repository: /sync-setup <ssh-url> [pull-minutes]",
+    handler: async (args, context) => {
+      if (busy) { context.ui.notify(`Sync is already ${busy}.`, "warning"); return; }
+      try {
+        const [url, interval, ...extra] = args.trim().split(/\s+/);
+        if (!url || extra.length) throw new Error("Usage: /sync-setup <private-ssh-url> [pull-minutes]");
+        const next = createConfig(url, paths);
+        if (interval !== undefined) {
+          if (!/^\d+$/.test(interval) || Number(interval) < 1 || Number(interval) > 35_790) throw new Error("Pull interval must be 1–35790 whole minutes.");
+          next.pullIntervalMinutes = Number(interval);
+        }
+        if (config) {
+          if (!await confirm(context, "Replace sync repository configuration?", "Existing managed paths and mode will be retained; no data is transferred by setup.")) return;
+          next.paths = [...config.paths];
+          next.mode = config.mode;
+        }
+        if (busy) throw new Error(`Sync is already ${busy}; retry setup after it finishes.`);
+        stopTimers();
+        await saveConfig(next, paths);
+        config = next;
+        makeService();
+        error = undefined;
+        publish();
+        // Setup changes configuration only; automatic work starts on next reload/mode change.
+        stopTimers();
+        context.ui.notify("Configured. No transfer performed. Use /sync-status; reload to activate automatic mode if enabled.", "info");
+      } catch (failure) { report(failure); }
+    },
+  });
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@gfgghgftgffg/amox-pi-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Independent Pi agent-data sync fork with SSH Git transport, backups and optional Starline status.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "gfgghgftgffg",
+  "contributors": [
+    {
+      "name": "MuratAitov",
+      "url": "https://github.com/MuratAitov/pi-sync"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gfgghgftgffg/amox_pi_extensions_lean.git",
+    "directory": "packages/amox-pi-sync"
+  },
+  "homepage": "https://github.com/gfgghgftgffg/amox_pi_extensions_lean/tree/main/packages/amox-pi-sync#readme",
+  "bugs": {
+    "url": "https://github.com/gfgghgftgffg/amox_pi_extensions_lean/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "sync",
+    "git"
+  ],
+  "files": [
+    "index.ts",
+    "core.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "MAINTENANCE.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "check": "npm run typecheck && npm test"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "jiti": "2.7.0",
+    "typebox": "1.3.36",
+    "typescript": "7.0.2"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}