@singh-gur/pi-session-sync 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gurakhshish Singh
+
+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/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# pi-session-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.
+**Start on your laptop. Pick it up on your desktop. Keep coding.**
+
+Your [pi](https://pi.dev) sessions, on every machine. Push a conversation from one machine, pull it on another, and carry on exactly where you left off: same history, same `/tree`, with paths rewritten for the machine you're on. Everything travels through a private git repo you already own. No server, no account, no new service.
+
+[Install](#get-started) · [Configure](#configure) · [How it works](#how-it-works) · [npm](https://www.npmjs.com/package/@singh-gur/pi-session-sync)
+
+![The /session-sync-push picklist listing four sessions under /home/me/dev with the current one selected, followed by "session-sync: pushed 1, unchanged 0".](https://raw.githubusercontent.com/singh-gur/pi-session-sync/main/assets/hero.png)
+
+*Illustration of the extension's picklist with synthetic sessions. Colors and spacing depend on your terminal and pi theme.*
+
+> [!WARNING]
+> **Your sync repo must be private.** Sessions contain your prompts, code, tool output (file contents, command output) and possibly secrets such as API keys or tokens. They are not encrypted or redacted.
+
+## Why you'll like it
+
+- **Pick exactly what travels.** `/session-sync-push` and `/session-sync-pull` open a picklist with the current session pre-selected. Nothing moves without you choosing it.
+- **Paths that follow you.** `/Users/me/code/api` on your Mac becomes `/home/me/dev/api` on your Linux box. Named roots turn machine paths into portable placeholders, so `/resume` finds the session in the right project.
+- **Work on both machines, lose nothing.** Sessions are merged entry by entry. Continue the same conversation in two places and both branches show up in `/tree`, with the newest one active.
+- **Your files stay the source of truth.** Pull never deletes local sessions, and the active session only reloads when the agent is idle.
+- **Just git.** Any remote `git` can reach: GitHub, GitLab, Gitea, a bare repo over SSH. Authentication uses your existing git setup.
+- **Hands-free if you want it.** Optional auto mode pulls the current folder's sessions when pi starts and pushes when you quit, configurable per root or folder. Off by default; startup pulls run in the background, and network failures only show a warning.
+
+## Get started
+
+```sh
+pi install npm:@singh-gur/pi-session-sync
+```
+
+1. Create an **empty, private** git repo for your sessions.
+2. Add the [config file](#configure) on each machine.
+3. Start pi (or run `/reload`), then:
+
+```text
+/session-sync-push     # on the machine you worked on
+/session-sync-pull     # on the machine you're moving to
+```
+
+Requires **Node.js >= 24.16**, **pi 1.x** (tested with 1.5.2), and `git` on your `PATH` with access to your sync repo. Install the package on every machine you want to sync.
+
+<details>
+<summary>Try without installing, install from GitHub, pin, or update</summary>
+
+```sh
+# Try it for the current run only
+pi -e npm:@singh-gur/pi-session-sync
+
+# Install from GitHub
+pi install git:github.com/singh-gur/pi-session-sync
+
+# Install from a local checkout
+pi install /path/to/pi-session-sync
+
+# Update installed pi packages
+pi update --extensions
+```
+
+To pin a release, append `@<version>`, for example `npm:@singh-gur/pi-session-sync@0.1.0`. Pinned versions are skipped by package updates.
+
+</details>
+
+## Configure
+
+Create `~/.pi/agent/git-session-sync.json` on each machine. It is machine-local and never synced.
+
+```json
+{
+  "repoUrl": "git@github.com:me/pi-sessions.git",
+  "branch": "main",
+  "roots": { "dev": "/home/me/dev", "home": "/home/me" },
+  "auto": { "pullOnStart": false, "pushOnShutdown": false }
+}
+```
+
+| Key | Required | What it does |
+| --- | --- | --- |
+| `repoUrl` | yes | Any URL `git` can clone. Use an empty private repo. |
+| `branch` | no | Branch to sync. Defaults to `main`. |
+| `roots` | yes | Named root directories. Names use `a-z`, `0-9`, `_` and `-`; paths must be absolute. Only sessions under a root are synced. |
+| `auto.pullOnStart` | no | When pi starts, pull new or changed sessions for the folder pi was started in, in the background. Defaults to `false`. |
+| `auto.pushOnShutdown` | no | Push the current session when you quit pi. Defaults to `false`. |
+| `auto.overrides` | no | Per-root or per-folder auto settings; see below. |
+
+### Per-root and per-folder auto sync
+
+`auto.overrides` keys are a root name (`dev`) or a root name plus a path under it (`dev/api`). Each entry sets `pullOnStart` and/or `pushOnShutdown`; unset fields fall back to the closest matching parent key, then to the global `auto` value. The longest matching key wins. Keys must start with a configured root name.
+
+```json
+"auto": {
+  "pullOnStart": false,
+  "pushOnShutdown": true,
+  "overrides": {
+    "dev":         { "pullOnStart": true },
+    "dev/scratch": { "pushOnShutdown": false }
+  }
+}
+```
+
+Here `/home/me/dev/api` pulls on start and pushes on quit, `/home/me/dev/scratch` pulls but never auto-pushes, and folders under `home` only push. Folders outside every root never auto-sync.
+
+### Same project, different paths
+
+Give a root the **same name** on every machine and point it at that machine's folder:
+
+| Machine | Config | Session cwd |
+| --- | --- | --- |
+| MacBook | `"dev": "/Users/me/code"` | `/Users/me/code/api` |
+| In the repo | | `{{PISYNC:dev}}/api` |
+| Linux desktop | `"dev": "/home/me/dev"` | `/home/me/dev/api` |
+
+Every root path in a session (cwd, messages, tool calls and results) is replaced at path boundaries, with the longest matching root winning. Sessions that use a root name this machine doesn't define are skipped on pull, with a warning.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `/session-sync-push` | Pick sessions to push. Only the current session is pre-selected. |
+| `/session-sync-pull` | Fetch the repo and pick from sessions that are **[new]** or **[changed]** compared to your local copies. If the current session is updated, pi reloads it. |
+
+In the picklist: `↑`/`↓` move, `Space` checks or unchecks a session, `a` selects all/none, `Enter` syncs the checked sessions, `Esc` cancels. Each run ends with a summary: synced, unchanged, new entries, conflicts and anything skipped (with the reason).
+
+## How it works
+
+- **Merging.** Sessions are merged by entry id and ordered by timestamp, so the newest entry becomes the active leaf. If the same entry id has different content on each side, your local version is kept and the conflict is reported.
+- **Local first.** Your session files are the source of truth. The clone at `~/.pi/agent/git-session-sync/repo` is a disposable cache, reset to the remote before every operation. Concurrent pushes from other machines are merged and retried automatically.
+- **Safe writes.** Session files are written atomically, never outside pi's sessions directory, and never deleted.
+- **Repo layout.** `sessions/<root>/<project>/<session-file>.jsonl`, readable and diffable like any other repo.
+
+## Limitations
+
+- POSIX paths only (no Windows).
+- Only pi's default session directory is supported (no custom `sessionDir`).
+- Sessions with a different session format version are skipped.
+- The repo grows without bound (sessions can include base64 images).
+- Path rewriting also changes coincidental matches of a root path inside message text.
+- No encryption or redaction; see the warning above.
+
+## Development
+
+```sh
+just install  # pnpm install --frozen-lockfile
+just check    # typecheck + tests + pack dry run
+just try      # run pi with the extension loaded
+```
+
+Release:
+
+```sh
+just check
+just bump patch   # or minor / major: bumps version, tags, pushes
+just publish      # pnpm publish to npm
+```
+
+Found a problem? [Open an issue](https://github.com/singh-gur/pi-session-sync/issues). Never paste session contents that may include secrets.
+
+[MIT license](https://github.com/singh-gur/pi-session-sync/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@singh-gur/pi-session-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Pi extension: sync your pi sessions across machines through a private git repo, with per-machine path mapping and branch-preserving merges.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/singh-gur/pi-session-sync.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "session",
+    "sync",
+    "git",
+    "multi-machine",
+    "backup",
+    "sessions"
+  ],
+  "author": "singh-gur",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/singh-gur/pi-session-sync/issues"
+  },
+  "homepage": "https://github.com/singh-gur/pi-session-sync#readme",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/singh-gur/pi-session-sync/main/assets/hero.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.16.0"
+  },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "pnpm pack --dry-run"
+  }
 }

package/src/config.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { rootFor } from "./layout.ts";
+
+export type AutoFlags = { pullOnStart: boolean; pushOnShutdown: boolean };
+export type SyncConfig = {
+	repoUrl: string;
+	branch: string;
+	roots: Record<string, string>;
+	/** overrides: "<root>" or "<root>/<rel/path>" -> partial flags; longest matching key wins. */
+	auto: AutoFlags & { overrides: Record<string, Partial<AutoFlags>> };
+};
+
+const FLAGS = ["pullOnStart", "pushOnShutdown"] as const;
+
+const ROOT_NAME = /^[a-z0-9_-]+$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+export function parseConfig(raw: unknown): SyncConfig {
+	if (!isObject(raw)) throw new Error("config must be a JSON object");
+	if (typeof raw.repoUrl !== "string" || !raw.repoUrl.trim()) throw new Error("config.repoUrl is required");
+	if (raw.branch !== undefined && (typeof raw.branch !== "string" || !raw.branch.trim()))
+		throw new Error("config.branch must be a non-empty string");
+	if (!isObject(raw.roots) || Object.keys(raw.roots).length === 0)
+		throw new Error("config.roots must be a non-empty object of name -> absolute path");
+
+	const roots: Record<string, string> = {};
+	for (const [name, path] of Object.entries(raw.roots)) {
+		if (!ROOT_NAME.test(name)) throw new Error(`config.roots: invalid root name "${name}" (use a-z, 0-9, _ and -)`);
+		if (typeof path !== "string" || !path.startsWith("/"))
+			throw new Error(`config.roots.${name} must be an absolute path`);
+		const stripped = path.replace(/\/+$/, "");
+		if (!stripped) throw new Error(`config.roots.${name}: "/" is not allowed as a root`);
+		roots[name] = stripped;
+	}
+
+	const auto = isObject(raw.auto) ? raw.auto : {};
+	if (auto.overrides !== undefined && !isObject(auto.overrides))
+		throw new Error("config.auto.overrides must be an object of \"root[/path]\" -> { pullOnStart?, pushOnShutdown? }");
+	const overrides: Record<string, Partial<AutoFlags>> = {};
+	for (const [rawKey, val] of Object.entries(auto.overrides ?? {})) {
+		const key = rawKey.replace(/^\/+|\/+$/g, "");
+		const segs = key.split("/");
+		if (!(segs[0]! in roots)) throw new Error(`config.auto.overrides: "${rawKey}" must start with a configured root name`);
+		if (segs.some((s) => !s || s === "." || s === ".."))
+			throw new Error(`config.auto.overrides: "${rawKey}" has an empty, "." or ".." segment`);
+		if (!isObject(val)) throw new Error(`config.auto.overrides.${rawKey} must be an object`);
+		const o: Partial<AutoFlags> = {};
+		for (const [k, v] of Object.entries(val)) {
+			if (!(FLAGS as readonly string[]).includes(k) || typeof v !== "boolean")
+				throw new Error(`config.auto.overrides.${rawKey}.${k}: expected pullOnStart or pushOnShutdown with a boolean`);
+			o[k as keyof AutoFlags] = v;
+		}
+		overrides[key] = o;
+	}
+	return {
+		repoUrl: raw.repoUrl,
+		branch: (raw.branch as string | undefined) ?? "main",
+		roots,
+		auto: { pullOnStart: auto.pullOnStart === true, pushOnShutdown: auto.pushOnShutdown === true, overrides },
+	};
+}
+
+/** Effective auto flags for a local cwd: global defaults, then matching overrides from shortest to longest key. Off outside roots. */
+export function autoFor(cfg: SyncConfig, cwd: string): AutoFlags {
+	const r = rootFor(cwd, cfg.roots);
+	if (!r) return { pullOnStart: false, pushOnShutdown: false };
+	const path = r.rel ? `${r.name}/${r.rel}` : r.name;
+	const flags: AutoFlags = { pullOnStart: cfg.auto.pullOnStart, pushOnShutdown: cfg.auto.pushOnShutdown };
+	for (const key of Object.keys(cfg.auto.overrides).sort((a, b) => a.length - b.length))
+		if (path === key || path.startsWith(`${key}/`)) Object.assign(flags, cfg.auto.overrides[key]);
+	return flags;
+}
+
+export function loadConfig(file: string): SyncConfig | undefined {
+	if (!existsSync(file)) return undefined;
+	try {
+		return parseConfig(JSON.parse(readFileSync(file, "utf8")));
+	} catch (e) {
+		throw new Error(`${file}: ${(e as Error).message}`);
+	}
+}

package/src/git.ts

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { SyncConfig } from "./config.ts";
+
+export type Exec = (
+	cmd: string,
+	args: string[],
+	opts: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+const TIMEOUT = 60_000;
+
+async function git(exec: Exec, cwd: string, args: string[], allowFail = false) {
+	const r = await exec("git", args, { cwd, timeout: TIMEOUT });
+	if (r.code !== 0 && !allowFail) throw new Error(`git ${args.join(" ")} failed: ${r.stderr.trim() || r.stdout.trim()}`);
+	return r;
+}
+
+export async function ensureClone(exec: Exec, cfg: SyncConfig, cloneDir: string) {
+	if (existsSync(join(cloneDir, ".git"))) return;
+	const parent = dirname(cloneDir);
+	mkdirSync(parent, { recursive: true });
+	const r = await git(exec, parent, ["clone", "--branch", cfg.branch, cfg.repoUrl, cloneDir], true);
+	if (r.code === 0) return;
+	// Empty remote (or branch not created yet): plain clone, then create the branch locally.
+	await git(exec, parent, ["clone", cfg.repoUrl, cloneDir]);
+	await git(exec, cloneDir, ["checkout", "-B", cfg.branch]);
+}
+
+export async function syncToRemote(exec: Exec, cfg: SyncConfig, cloneDir: string) {
+	await git(exec, cloneDir, ["fetch", "origin"]);
+	const has = await git(exec, cloneDir, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${cfg.branch}`], true);
+	if (has.code !== 0) return;
+	await git(exec, cloneDir, ["checkout", "-B", cfg.branch, `origin/${cfg.branch}`]);
+	await git(exec, cloneDir, ["reset", "--hard", `origin/${cfg.branch}`]);
+	await git(exec, cloneDir, ["clean", "-fd"]);
+}
+
+/** rebuild() writes files into the clone and returns how many changed. Retries on push rejection. */
+export async function commitAndPush(
+	exec: Exec,
+	cfg: SyncConfig,
+	cloneDir: string,
+	message: string,
+	rebuild: () => Promise<number>,
+): Promise<{ pushed: number }> {
+	let lastErr = "";
+	for (let attempt = 0; attempt < 3; attempt++) {
+		await syncToRemote(exec, cfg, cloneDir);
+		const n = await rebuild();
+		if (n === 0) return { pushed: 0 };
+		await git(exec, cloneDir, ["add", "-A", "sessions"]);
+		await git(exec, cloneDir, ["commit", "-q", "-m", message]);
+		const p = await git(exec, cloneDir, ["push", "origin", `HEAD:${cfg.branch}`], true);
+		if (p.code === 0) return { pushed: n };
+		lastErr = p.stderr.trim();
+	}
+	throw new Error(`git push failed after 3 attempts: ${lastErr}`);
+}

package/src/index.ts

@@ -0,0 +1,273 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CURRENT_SESSION_VERSION, getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { autoFor, loadConfig, type SyncConfig } from "./config.ts";
+import { commitAndPush, ensureClone, type Exec, syncToRemote } from "./git.ts";
+import { localSessionDirFor, repoPathFor } from "./layout.ts";
+import { mergeSessions } from "./merge.ts";
+import { pickSessions } from "./picklist.ts";
+import { rewriteFileToLocal, rewriteFileToPortable } from "./rewrite.ts";
+
+const EXAMPLE = `{
+  "repoUrl": "git@github.com:me/pi-sessions.git",
+  "branch": "main",
+  "roots": { "dev": "/home/me/dev" },
+  "auto": { "pullOnStart": false, "pushOnShutdown": false }
+}`;
+
+const configFile = () => join(getAgentDir(), "git-session-sync.json");
+const cloneDir = () => join(getAgentDir(), "git-session-sync", "repo");
+const sessionsRoot = () => join(getAgentDir(), "sessions");
+
+type Summary = { synced: number; added: number; unchanged: number; conflicts: number; skipped: string[] };
+const newSummary = (): Summary => ({ synced: 0, added: 0, unchanged: 0, conflicts: 0, skipped: [] });
+
+function header(text: string): { version?: unknown; cwd?: unknown } | undefined {
+	try {
+		const h = JSON.parse(text.split("\n", 1)[0] ?? "");
+		return h?.type === "session" ? h : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+const readIf = (f: string) => (existsSync(f) ? readFileSync(f, "utf8") : undefined);
+
+function writeAtomic(file: string, text: string) {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-pss`;
+	writeFileSync(tmp, text);
+	renameSync(tmp, file);
+}
+
+/** Load config and check preconditions; notifies and returns undefined when sync cannot run. */
+function getConfig(ctx: ExtensionContext, quietIfMissing = false): SyncConfig | undefined {
+	let cfg: SyncConfig | undefined;
+	try {
+		cfg = loadConfig(configFile());
+	} catch (e) {
+		ctx.ui.notify(`session-sync: ${(e as Error).message}`, "error");
+		return undefined;
+	}
+	if (!cfg) {
+		if (!quietIfMissing) ctx.ui.notify(`session-sync: create ${configFile()} like:\n${EXAMPLE}`, "warning");
+		return undefined;
+	}
+	if (resolve(ctx.sessionManager.getSessionDir()) !== resolve(localSessionDirFor(resolve(ctx.cwd), getAgentDir()))) {
+		ctx.ui.notify("session-sync: custom sessionDir is unsupported", "error");
+		return undefined;
+	}
+	return cfg;
+}
+
+/** Push local session files (merged into the repo copy). */
+async function pushSessions(exec: Exec, cfg: SyncConfig, paths: string[]): Promise<Summary> {
+	const clone = cloneDir();
+	await ensureClone(exec, cfg, clone);
+	let s = newSummary();
+	await commitAndPush(exec, cfg, clone, `push ${paths.length} session(s) from ${hostname()}`, async () => {
+		s = newSummary();
+		for (const path of paths) {
+			const text = readIf(path);
+			const h = text && header(text);
+			if (!h) {
+				s.skipped.push(`${basename(path)}: unreadable`);
+				continue;
+			}
+			if (h.version !== CURRENT_SESSION_VERSION) {
+				s.skipped.push(`${basename(path)}: session version ${h.version}`);
+				continue;
+			}
+			const rel = typeof h.cwd === "string" ? repoPathFor(h.cwd, basename(path), cfg.roots) : undefined;
+			if (!rel) {
+				s.skipped.push(`${basename(path)}: cwd not under a configured root`);
+				continue;
+			}
+			const repoFile = join(clone, rel);
+			const repoText = readIf(repoFile);
+			const m = mergeSessions(rewriteFileToPortable(text, cfg.roots), repoText);
+			s.conflicts += m.conflicts;
+			if (m.text === repoText) s.unchanged++;
+			else {
+				writeAtomic(repoFile, m.text);
+				s.synced++;
+			}
+		}
+		return s.synced;
+	});
+	return s;
+}
+
+type PullCandidate = { repoFile: string; target: string; isNew: boolean; label: string };
+
+function walkJsonl(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, { withFileTypes: true, recursive: true })
+		.filter((d) => d.isFile() && d.name.endsWith(".jsonl"))
+		.map((d) => join(d.parentPath, d.name));
+}
+
+/** Localize a repo file; returns the target path and localized text, or a skip reason. */
+function localize(cfg: SyncConfig, repoFile: string): { target: string; text: string } | { skip: string } {
+	const name = basename(repoFile);
+	const { text, unknown } = rewriteFileToLocal(readFileSync(repoFile, "utf8"), cfg.roots);
+	if (unknown.length) return { skip: `${name}: unknown root(s) ${unknown.join(", ")}` };
+	const h = header(text);
+	if (!h || typeof h.cwd !== "string" || !h.cwd.startsWith("/")) return { skip: `${name}: invalid header` };
+	if (h.version !== CURRENT_SESSION_VERSION) return { skip: `${name}: session version ${h.version}` };
+	const target = resolve(localSessionDirFor(h.cwd, getAgentDir()), name);
+	// Trust boundary: repo content must never write outside the sessions dir.
+	if (!target.startsWith(resolve(sessionsRoot()) + sep)) return { skip: `${name}: target outside sessions dir` };
+	return { target, text };
+}
+
+/** `only`: repo-relative dir (e.g. "sessions/dev/api") to restrict the scan to; defaults to all sessions. */
+async function scanPull(exec: Exec, cfg: SyncConfig, s: Summary, only = "sessions"): Promise<PullCandidate[]> {
+	const clone = cloneDir();
+	await ensureClone(exec, cfg, clone);
+	await syncToRemote(exec, cfg, clone);
+	const out: PullCandidate[] = [];
+	for (const repoFile of walkJsonl(join(clone, only))) {
+		const l = localize(cfg, repoFile);
+		if ("skip" in l) {
+			s.skipped.push(l.skip);
+			continue;
+		}
+		const local = readIf(l.target);
+		if (local !== undefined && !mergeSessions(local, l.text).changed) continue;
+		const cwd = String(header(l.text)?.cwd);
+		out.push({ repoFile, target: l.target, isNew: local === undefined, label: `${local === undefined ? "[new]" : "[changed]"} ${cwd} · ${basename(repoFile)}` });
+	}
+	return out;
+}
+
+function applyPull(cfg: SyncConfig, c: PullCandidate, s: Summary) {
+	const l = localize(cfg, c.repoFile);
+	if ("skip" in l) return void s.skipped.push(l.skip);
+	const m = mergeSessions(readIf(c.target), l.text); // re-read: local may have changed since the scan
+	s.conflicts += m.conflicts;
+	if (!m.changed) return void s.unchanged++;
+	writeAtomic(c.target, m.text);
+	s.synced++;
+	s.added += m.added;
+}
+
+function report(ctx: ExtensionContext, verb: string, s: Summary) {
+	const parts = [`${verb} ${s.synced}`, `unchanged ${s.unchanged}`];
+	if (s.added) parts.push(`new entries ${s.added}`);
+	if (s.conflicts) parts.push(`id conflicts ${s.conflicts} (kept local)`);
+	if (s.skipped.length) parts.push(`skipped ${s.skipped.length}:\n  ${s.skipped.join("\n  ")}`);
+	ctx.ui.notify(`session-sync: ${parts.join(", ")}`, s.skipped.length ? "warning" : "info");
+}
+
+const errMsg = (e: unknown) => (e instanceof Error ? e.message : String(e));
+
+export default function (pi: ExtensionAPI) {
+	const exec: Exec = (cmd, args, opts) => pi.exec(cmd, args, opts);
+
+	pi.registerCommand("session-sync-push", {
+		description: "Push selected pi sessions to the sync git repo",
+		handler: async (_args, ctx: ExtensionCommandContext) => {
+			const cfg = getConfig(ctx);
+			if (!cfg) return;
+			const current = ctx.sessionManager.getSessionFile();
+			const infos = (await SessionManager.listAll())
+				.filter((i) => repoPathFor(i.cwd, basename(i.path), cfg.roots))
+				.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+			if (!infos.length) return ctx.ui.notify("session-sync: no sessions under configured roots", "info");
+			const picked = await pickSessions(
+				ctx,
+				"Push sessions",
+				"push",
+				infos.map((i) => ({
+					id: i.path,
+					label: `${(i.name || i.firstMessage || "(empty)").replace(/\s+/g, " ").slice(0, 60)} · ${i.cwd} · ${i.modified.toLocaleString()}`,
+					checked: i.path === current,
+				})),
+			);
+			if (!picked) return ctx.ui.notify("session-sync: cancelled", "info");
+			if (!picked.length) return ctx.ui.notify("session-sync: nothing selected", "info");
+			ctx.ui.setStatus("session-sync", "pushing sessions...");
+			try {
+				report(ctx, "pushed", await pushSessions(exec, cfg, picked));
+			} catch (e) {
+				ctx.ui.notify(`session-sync push failed: ${errMsg(e)}`, "error");
+			} finally {
+				ctx.ui.setStatus("session-sync", undefined);
+			}
+		},
+	});
+
+	pi.registerCommand("session-sync-pull", {
+		description: "Pull selected pi sessions from the sync git repo",
+		handler: async (_args, ctx: ExtensionCommandContext) => {
+			const cfg = getConfig(ctx);
+			if (!cfg) return;
+			const current = ctx.sessionManager.getSessionFile();
+			const s = newSummary();
+			let currentUpdated = false;
+			ctx.ui.setStatus("session-sync", "pulling sessions...");
+			try {
+				const candidates = await scanPull(exec, cfg, s);
+				ctx.ui.setStatus("session-sync", undefined);
+				if (!candidates.length) return report(ctx, "pulled", s);
+				const picked = await pickSessions(
+					ctx,
+					"Pull sessions",
+					"pull",
+					candidates.map((c) => ({ id: c.target, label: c.label, checked: c.target === current })),
+				);
+				if (!picked) return ctx.ui.notify("session-sync: cancelled", "info");
+				if (!picked.length) return ctx.ui.notify("session-sync: nothing selected", "info");
+				for (const c of candidates.filter((c) => picked.includes(c.target))) {
+					if (c.target === current && !ctx.isIdle()) {
+						s.skipped.push(`${basename(c.target)}: agent busy (current session)`);
+						continue;
+					}
+					const before = s.synced;
+					applyPull(cfg, c, s);
+					if (c.target === current && s.synced > before) currentUpdated = true;
+				}
+				report(ctx, "pulled", s);
+			} catch (e) {
+				return ctx.ui.notify(`session-sync pull failed: ${errMsg(e)}`, "error");
+			} finally {
+				ctx.ui.setStatus("session-sync", undefined);
+			}
+			// Reload the active session from disk; ctx is stale afterwards, so this is the last use.
+			if (currentUpdated && current) await ctx.switchSession(current);
+		},
+	});
+
+	pi.on("session_start", async (event, ctx) => {
+		if (event.reason !== "startup") return;
+		const cfg = getConfig(ctx, true);
+		const cwd = resolve(ctx.cwd);
+		// Only this folder's sessions; repoPathFor is undefined outside roots, so no network call there.
+		const rel = cfg && autoFor(cfg, cwd).pullOnStart ? repoPathFor(cwd, "x", cfg.roots) : undefined;
+		if (!cfg || !rel) return;
+		const current = ctx.sessionManager.getSessionFile();
+		// Fire and forget: never block startup on the network.
+		void (async () => {
+			const s = newSummary();
+			for (const c of await scanPull(exec, cfg, s, dirname(rel))) if (c.target !== current) applyPull(cfg, c, s);
+			if (s.synced || s.skipped.length) report(ctx, "auto-pulled", s);
+		})().catch((e) => ctx.ui.notify(`session-sync auto-pull failed: ${errMsg(e)}`, "warning"));
+	});
+
+	pi.on("session_shutdown", async (event, ctx) => {
+		if (event.reason !== "quit") return;
+		const cfg = getConfig(ctx, true);
+		const current = ctx.sessionManager.getSessionFile();
+		if (!cfg || !current || !existsSync(current)) return;
+		const h = header(readFileSync(current, "utf8"));
+		if (typeof h?.cwd !== "string" || !autoFor(cfg, h.cwd).pushOnShutdown) return;
+		try {
+			await pushSessions(exec, cfg, [current]);
+		} catch (e) {
+			ctx.ui.notify(`session-sync auto-push failed: ${errMsg(e)}`, "warning");
+		}
+	});
+}

package/src/layout.ts

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import type { Roots } from "./rewrite.ts";
+
+export const encodeRel = (rel: string) => (rel ? rel.replace(/[/\\:]/g, "-") : "_root_");
+
+/** Longest configured root containing cwd (equal or prefix + "/"). */
+export function rootFor(cwd: string, roots: Roots): { name: string; rel: string } | undefined {
+	let best: { name: string; rel: string; len: number } | undefined;
+	for (const [name, path] of Object.entries(roots)) {
+		if ((cwd === path || cwd.startsWith(`${path}/`)) && (!best || path.length > best.len))
+			best = { name, rel: cwd.slice(path.length + 1), len: path.length };
+	}
+	return best && { name: best.name, rel: best.rel };
+}
+
+export function repoPathFor(localCwd: string, fileName: string, roots: Roots): string | undefined {
+	const r = rootFor(localCwd, roots);
+	return r && `sessions/${r.name}/${encodeRel(r.rel)}/${fileName}`;
+}
+
+/** Mirror of pi's getDefaultSessionDirPath (session-manager.js:291-294), which is not exported. */
+export const localSessionDirFor = (cwd: string, agentDir: string) =>
+	join(agentDir, "sessions", `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`);

package/src/merge.ts

@@ -0,0 +1,65 @@
+type Line = Record<string, unknown>;
+
+function parse(text: string | undefined): { header: Line | undefined; entries: Line[] } {
+	const entries: Line[] = [];
+	let header: Line | undefined;
+	for (const raw of (text ?? "").split("\n")) {
+		if (!raw.trim()) continue;
+		const obj = JSON.parse(raw) as Line;
+		if (obj.type === "session" && !header) header = obj;
+		else entries.push(obj);
+	}
+	return { header, entries };
+}
+
+/**
+ * Merge two versions of one session JSONL file. Local wins on header and id conflicts.
+ * Entries are ordered by timestamp so the newest entry is the last line (pi's leaf, session-manager.js:733-742).
+ */
+export function mergeSessions(
+	localText: string | undefined,
+	remoteText: string | undefined,
+): { text: string; added: number; conflicts: number; changed: boolean } {
+	const local = parse(localText);
+	const remote = parse(remoteText);
+	if (local.header && remote.header && local.header.id !== remote.header.id)
+		throw new Error(`session header id mismatch: ${local.header.id} vs ${remote.header.id}`);
+
+	const header = local.header ?? remote.header;
+	const byId = new Map<unknown, string>();
+	const merged: Line[] = [];
+	const noId: Line[] = [];
+	let added = 0;
+	let conflicts = 0;
+
+	for (const e of local.entries) {
+		if (e.id === undefined) noId.push(e);
+		else if (!byId.has(e.id)) {
+			byId.set(e.id, JSON.stringify(e));
+			merged.push(e);
+		}
+	}
+	for (const e of remote.entries) {
+		if (e.id === undefined) {
+			if (!localText) noId.push(e);
+			continue;
+		}
+		const existing = byId.get(e.id);
+		if (existing === undefined) {
+			byId.set(e.id, JSON.stringify(e));
+			merged.push(e);
+			added++;
+		} else if (existing !== JSON.stringify(e)) conflicts++;
+	}
+
+	// Array.prototype.sort is stable: ties keep local-before-remote input order.
+	merged.sort((a, b) => {
+		const ta = String(a.timestamp ?? "");
+		const tb = String(b.timestamp ?? "");
+		return ta < tb ? -1 : ta > tb ? 1 : 0;
+	});
+
+	const lines = [...(header ? [header] : []), ...merged, ...noId].map((l) => JSON.stringify(l));
+	const text = lines.length ? `${lines.join("\n")}\n` : "";
+	return { text, added, conflicts, changed: text !== localText };
+}

package/src/picklist.ts

@@ -0,0 +1,83 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, getKeybindings, getSelectPageIndex, truncateToWidth } from "@earendil-works/pi-tui";
+
+export type PickItem = { id: string; label: string; checked: boolean };
+type Style = Pick<Theme, "fg" | "bold">;
+
+/** Checkbox list: ↑/↓ move, space toggles, `a` toggles all, enter confirms, esc cancels. */
+export class MultiSelect implements Component {
+	readonly capturesViewportInput = true;
+	cursor = 0;
+	readonly selected: Set<string>;
+
+	private title: string;
+	private verb: string;
+	private items: PickItem[];
+	private style: Style;
+	private done: (ids: string[] | undefined) => void;
+	private maxVisible = 12;
+
+	constructor(title: string, verb: string, items: PickItem[], style: Style, done: (ids: string[] | undefined) => void) {
+		this.title = title;
+		this.verb = verb;
+		this.items = items;
+		this.style = style;
+		this.done = done;
+		this.selected = new Set(items.filter((i) => i.checked).map((i) => i.id));
+	}
+
+	invalidate() {}
+
+	handleInput(data: string) {
+		const kb = getKeybindings();
+		const n = this.items.length;
+		const page = getSelectPageIndex(kb, data, this.cursor, n, this.maxVisible);
+		if (kb.matches(data, "tui.select.up")) this.cursor = (this.cursor - 1 + n) % n;
+		else if (kb.matches(data, "tui.select.down")) this.cursor = (this.cursor + 1) % n;
+		else if (page !== undefined) this.cursor = page;
+		else if (data === " ") {
+			const id = this.items[this.cursor]!.id;
+			if (!this.selected.delete(id)) this.selected.add(id);
+		} else if (data === "a" || data === "A") {
+			if (this.selected.size === n) this.selected.clear();
+			else for (const i of this.items) this.selected.add(i.id);
+		} else if (kb.matches(data, "tui.select.confirm")) this.done(this.items.filter((i) => this.selected.has(i.id)).map((i) => i.id));
+		else if (kb.matches(data, "tui.select.cancel")) this.done(undefined);
+	}
+
+	render(width: number): string[] {
+		const fg: Style["fg"] = (c, t) => this.style.fg(c, t);
+		const bold = (t: string) => this.style.bold(t);
+		const n = this.items.length;
+		const start = Math.max(0, Math.min(this.cursor - Math.floor(this.maxVisible / 2), n - this.maxVisible));
+		const end = Math.min(n, start + this.maxVisible);
+		const lines = [fg("accent", bold(this.title)) + fg("muted", `  ${this.selected.size}/${n} selected`), ""];
+		for (let i = start; i < end; i++) {
+			const item = this.items[i]!;
+			const on = this.selected.has(item.id);
+			const box = on ? fg("success", "[x]") : fg("dim", "[ ]");
+			const row = i === this.cursor ? `${fg("accent", "›")} ${box} ${fg("accent", item.label)}` : `  ${box} ${item.label}`;
+			lines.push(truncateToWidth(row, width));
+		}
+		if (start > 0 || end < n) lines.push(fg("dim", `  (${this.cursor + 1}/${n})`));
+		lines.push("", fg("dim", truncateToWidth(`↑↓ move · space select · a all/none · enter ${this.verb} · esc cancel`, width)));
+		return lines;
+	}
+}
+
+/** Returns selected ids (possibly empty), or undefined if cancelled. */
+export async function pickSessions(ctx: ExtensionContext, title: string, verb: string, items: PickItem[]): Promise<string[] | undefined> {
+	if (ctx.mode !== "tui") return items.filter((i) => i.checked).map((i) => i.id);
+	return ctx.ui.custom<string[] | undefined>((tui, theme, _kb, done) => {
+		const list = new MultiSelect(title, verb, items, theme, done);
+		return {
+			capturesViewportInput: true,
+			render: (w: number) => list.render(w),
+			invalidate: () => list.invalidate(),
+			handleInput(data: string) {
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	});
+}

package/src/rewrite.ts

@@ -0,0 +1,68 @@
+// shortcut: POSIX paths only, upgrade when Windows support is needed.
+
+export type Roots = Record<string, string>;
+
+export const TOKEN = (name: string) => `{{PISYNC:${name}}}`;
+const TOKEN_RE = /\{\{PISYNC:([a-z0-9_-]+)\}\}/g;
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Root path only matches at path boundaries: not glued to a preceding path/word char, and followed by "/" or a non-path char.
+function rootRegexes(roots: Roots): [RegExp, string][] {
+	return Object.entries(roots)
+		.sort((a, b) => b[1].length - a[1].length)
+		.map(([name, path]) => [new RegExp(`(?<![A-Za-z0-9._/-])${escapeRe(path)}(?![A-Za-z0-9._-])`, "g"), TOKEN(name)]);
+}
+
+export function toPortable(s: string, roots: Roots): string {
+	for (const [re, token] of rootRegexes(roots)) s = s.replace(re, token);
+	return s;
+}
+
+export function toLocal(s: string, roots: Roots): { value: string; unknown: string[] } {
+	const unknown = new Set<string>();
+	const value = s.replace(TOKEN_RE, (m, name: string) => {
+		const path = Object.hasOwn(roots, name) ? roots[name] : undefined;
+		if (path !== undefined) return path;
+		unknown.add(name);
+		return m;
+	});
+	return { value, unknown: [...unknown] };
+}
+
+function walk(v: unknown, fn: (s: string) => string): unknown {
+	if (typeof v === "string") return fn(v);
+	if (Array.isArray(v)) return v.map((x) => walk(x, fn));
+	if (v && typeof v === "object") {
+		const out: Record<string, unknown> = {};
+		for (const [k, x] of Object.entries(v)) out[k] = walk(x, fn);
+		return out;
+	}
+	return v;
+}
+
+export function rewriteLine(line: string, fn: (s: string) => string): string {
+	if (!line.trim()) return line;
+	return JSON.stringify(walk(JSON.parse(line), fn));
+}
+
+const mapLines = (text: string, fn: (s: string) => string) =>
+	text
+		.split("\n")
+		.map((l) => rewriteLine(l, fn))
+		.join("\n");
+
+export function rewriteFileToPortable(text: string, roots: Roots): string {
+	const rs = rootRegexes(roots);
+	return mapLines(text, (s) => rs.reduce((acc, [re, token]) => acc.replace(re, token), s));
+}
+
+export function rewriteFileToLocal(text: string, roots: Roots): { text: string; unknown: string[] } {
+	const unknown = new Set<string>();
+	const out = mapLines(text, (s) => {
+		const r = toLocal(s, roots);
+		for (const u of r.unknown) unknown.add(u);
+		return r.value;
+	});
+	return { text: out, unknown: [...unknown] };
+}