agent-carry 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## Unreleased
+
+- `agent-carry` works as a second command name for `carry`.
+- README trimmed; plugin author set.
+
+## 0.1.0
+
+First release. Claude Code adapter.
+
+- Export and import a session as a path-portable, redacted, merge-safe bundle (`carry export`, `carry import`, `carry inspect`, `carry list`).
+- Folder sync (`carry push`, `carry pull`) with optional AES-256-GCM encryption.
+- Plugin commands `/carry:share` and `/carry:pickup`, and optional session hooks.
+- Redaction covers: private keys, Anthropic/OpenAI/GitHub/AWS/Google/Slack/Stripe keys, JWTs, Bearer tokens,
+  passwords in URLs, `NAME=value` and `"name": "value"` secrets (including after ANSI colour codes, in lower case,
+  and inside escaped JSON), and base64 blobs that decode to any of those.
+- Credential-like text inside signed thinking blocks cannot be redacted, so export refuses unless you pass
+  `--strip-thinking` (drop thinking blocks) or `--allow-thinking-secrets`. `carry push` skips such sessions.
+- `carry --version`. Bundles larger than 1 GB are refused, and decompression is size-capped.
+- A session id that exists in several project folders is resolved by the current folder or `--project`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-carry contributors
+
+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,76 @@
-# Temporary Holding Version
+# agent-carry
 
-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.
+Move a coding-agent session to another machine or folder and keep working. Supports Claude Code today.
+
+Claude Code stores sessions per absolute project path, and the transcripts are full of absolute paths, so a
+copied session can't be resumed elsewhere. `carry` fixes that:
+
+- **Path-portable:** project, home and store paths become tokens on export and are rewritten on import.
+- **Merge-safe:** import is a union by record `uuid`. Importing twice changes nothing; a session continued on two machines becomes a two-branch history.
+- **Redacted:** credential-shaped strings (cloud keys, tokens, JWTs, private keys, `*_SECRET=...`, URL passwords) are removed on export, with a report.
+- **Complete:** subagent transcripts and tool results travel with the session.
+- **Inspectable:** a bundle is newline-delimited JSON (gzipped).
+
+## Usage
+
+```
+npm i -g agent-carry          # installs `carry` (also available as `agent-carry`)
+
+# machine A, in the project folder
+carry list
+carry export --latest -o session.carry.gz
+
+# machine B, in the same project (any path)
+carry import session.carry.gz
+claude --resume <id>          # printed by import
+```
+
+Encrypt a bundle with `CARRY_PASSPHRASE` or `--passphrase-file FILE` (AES-256-GCM, scrypt key). Never pass the
+passphrase as an argument.
+
+### Sync through a shared folder
+
+Point both machines at a folder your sync tool already replicates (Dropbox, iCloud, Syncthing, a git tree).
+
+```
+carry push ~/Sync/carry       # this project's sessions -> folder
+carry pull ~/Sync/carry       # other devices' sessions -> this machine
+```
+
+Projects are matched by git remote, not path. Each file has one writer, so there are no sync conflicts.
+
+### Claude Code plugin
+
+`plugin/` adds `/carry:share` and `/carry:pickup`. With `CARRY_SYNC_DIR` set, bundled hooks pull on session
+start and push on session end (hooks not yet exercised in a live Claude Code).
+
+## Commands
+
+| command | |
+|---|---|
+| `carry list [--all]` | sessions for this folder, or all |
+| `carry export <id\|--latest> [-o FILE]` | `--no-redact`, `--redact-emails`, `--strip-thinking`, `--allow-thinking-secrets`, `--project-root DIR` |
+| `carry inspect FILE` | header, parts, redaction counts |
+| `carry import FILE [--project-root DIR] [--dry-run]` | write into the target folder's session store |
+| `carry push DIR` / `carry pull DIR` | folder sync (`--name`, `--dry-run`, `--quiet`) |
+
+## Limits
+
+- **Resume** is verified on one real session (Claude Code 2.1.299); the transcript format is internal and can change. Run `scripts/verify-resume.sh <id>` to check yours.
+- **Thinking blocks are signed**, so they travel verbatim. If one contains a credential-like string, export refuses unless you pass `--strip-thinking` (resume with stripped thinking is untested) or `--allow-thinking-secrets`. `push` skips such sessions.
+- **Redaction is best effort.** It misses passwords that read like sentences and letters-only lowercase `password=word`. Read `carry inspect` before sharing, and encrypt anything you send to someone else.
+- Not handled: Windows paths, Cowork/desktop sessions, file-history (rewind) backups.
+- `push` re-uploads pulled sessions, so a sync folder grows with devices × sessions.
+
+## Development
+
+```
+npm test                  # 36 tests, synthetic two-machine setups
+npm run check:real        # read-only round trip of your own ~/.claude sessions
+```
+
+To add an agent, supply its session-folder mapping (`src/paths.js`), session reader (`src/store.js`), transcript
+record identity (`src/transcript.js`) and the `AGENT` constant (`src/bundle.js`). Path rewriting, redaction,
+merging, encryption and sync are agent-independent. Codex is not implemented yet.
+
+MIT

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "agent-carry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Move coding-agent sessions between machines and folders: path-portable, redacted, encrypted, merge-safe bundles. Claude Code today; adapter-ready for Codex and others.",
+  "type": "module",
+  "bin": {
+    "carry": "src/cli.js",
+    "agent-carry": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "plugin",
+    "README.md",
+    "LICENSE",
+    "scripts/verify-resume.sh",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "check:real": "node scripts/check-real.js"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "coding-agent",
+    "sessions",
+    "transcripts",
+    "portable",
+    "resume",
+    "sync"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harshhh28/agent-carry.git"
+  },
+  "homepage": "https://github.com/harshhh28/agent-carry#readme",
+  "bugs": {
+    "url": "https://github.com/harshhh28/agent-carry/issues"
+  },
+  "author": "Harsh Gajjar <harshgajjar2812@gmail.com>"
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "carry",
+  "version": "0.1.0",
+  "description": "Move coding-agent sessions between machines and folders: /carry:share exports a redacted, path-portable bundle, /carry:pickup imports one.",
+  "author": { "name": "Harsh Gajjar", "email": "harshgajjar2812@gmail.com" },
+  "license": "MIT"
+}

package/plugin/commands/pickup.md

@@ -0,0 +1,13 @@
+---
+description: Import a carry bundle into this folder so it can be resumed
+argument-hint: <bundle-file> [--dry-run]
+allowed-tools: Bash(carry import:*)
+---
+
+Import result:
+
+!`carry import $ARGUMENTS 2>&1 || echo "carry is not installed: run npm i -g agent-carry"`
+
+Tell the user the session was imported into this folder and that a running session cannot swap its own
+history: they should exit and run the `claude --resume <id>` line printed above. If `--dry-run` was used,
+say nothing was written.

package/plugin/commands/share.md

@@ -0,0 +1,13 @@
+---
+description: Export this project's latest session as a portable, redacted carry bundle
+argument-hint: [-o FILE] [--strip-thinking] [--redact-emails]
+allowed-tools: Bash(carry export:*)
+---
+
+Export result (this runs the `carry` CLI from `npm i -g agent-carry`):
+
+!`carry export --latest $ARGUMENTS 2>&1 || echo "carry is not installed: run npm i -g agent-carry"`
+
+Report in at most three lines: the file that was written, how many secrets were redacted, and any warning above.
+If there is a warning about credential-like strings in thinking blocks, tell the user to re-run `/carry:share --strip-thinking`.
+Do not open or print the bundle's contents.

package/plugin/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "[ -n \"$CARRY_SYNC_DIR\" ] && carry pull \"$CARRY_SYNC_DIR\" --quiet || true" } ] }
+    ],
+    "SessionEnd": [
+      { "hooks": [ { "type": "command", "command": "[ -n \"$CARRY_SYNC_DIR\" ] && carry push \"$CARRY_SYNC_DIR\" --quiet || true" } ] }
+    ]
+  }
+}

package/scripts/verify-resume.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Does `claude --resume` accept a session imported by carry into a folder it never ran in?
+#
+#   sh scripts/verify-resume.sh <session-id-prefix>     (ids: node src/cli.js list --all)
+#
+# Exports the session, imports it into a throwaway folder, resumes it with one
+# short prompt, then deletes the throwaway folder and its copy of the session.
+# The original session is only read. Costs one small API call.
+set -eu
+
+ID=${1:?usage: verify-resume.sh <session-id-prefix>}
+HERE=$(cd "$(dirname "$0")/.." && pwd -P)
+CARRY="node $HERE/src/cli.js"
+CLAUDE_DIR=${CLAUDE_CONFIG_DIR:-$HOME/.claude}
+
+TRY=$(mktemp -d "${TMPDIR:-/tmp}/carry-try.XXXXXX")
+TRY=$(cd "$TRY" && pwd -P)
+FOLDER="$CLAUDE_DIR/projects/$(printf '%s' "$TRY" | sed 's/[^A-Za-z0-9]/-/g')"
+cleanup() { rm -rf "$TRY" "$FOLDER"; echo "cleaned up $TRY and its session copy"; }
+trap cleanup EXIT
+
+echo "1/3 export"
+$CARRY export "$ID" -o "$TRY/s.carry.gz"
+FULL=$($CARRY inspect "$TRY/s.carry.gz" | sed -n 's/.*"sessionId": "\(.*\)".*/\1/p')
+
+echo "2/3 import into $TRY"
+cd "$TRY"
+$CARRY import "$TRY/s.carry.gz" >/dev/null
+
+echo "3/3 resume $FULL from a folder it never ran in"
+claude -p --resume "$FULL" "In one sentence: what was the very first thing the user asked in this conversation? Also say which directory we are in now." </dev/null
+echo
+echo "PASS if the answer above matches the session's first request and names $TRY."

package/src/bundle.js

@@ -0,0 +1,221 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { parseJsonl, summarize, sha256 } from './transcript.js';
+import { toPortable, fromPortable, mapStrings, residualHomePaths, TOKENS } from './portable.js';
+import { makeRedactor } from './redact.js';
+import { mergeEntries } from './merge.js';
+import { mangle, realpathOr, projectsDir } from './paths.js';
+import { encrypt, decrypt, isEncrypted } from './crypto.js';
+import { readSession } from './store.js';
+
+export const FORMAT = 1;
+const MAX_BUNDLE_BYTES = 1024 * 1024 * 1024; // refuse decompression bombs
+
+export const TOOL = 'agent-carry/0.1.0';
+
+/** Agents this build can read and write. Bundles name their agent so other adapters can be added without a format change. */
+export const AGENT = 'claude-code';
+const SUPPORTED_AGENTS = new Set([AGENT]);
+
+/**
+ * Bundle = newline-delimited JSON, readable with `less` and `jq`:
+ *   line 1   header (what is inside, counts, redaction report, body hash)
+ *   line 2+  {"p": part, "l": record} | {"p": part, "x": unparsable line}
+ *            | {"p": part, "t": text file} | {"p": part, "b": base64 file}
+ * A `.gz` suffix gzips the whole thing.
+ */
+
+export function buildBundle({ folder, id, where, redact = true, emails = false, stripThinking = false, allowThinkingSecrets = false }) {
+  const { parts, skipped } = readSession(folder, id);
+  const mapper = toPortable(where);
+  const redactor = redact ? makeRedactor({ emails }) : null;
+  const transform = (v) => {
+    let out = mapStrings(v, mapper.fn);
+    if (redactor) out = redactor.apply(out);
+    return out;
+  };
+
+  const body = [];
+  const thinking = { blocks: 0, possibleSecrets: 0 };
+  const partsMeta = [];
+  const residualSource = [];
+  let meta = null;
+
+  for (const part of parts) {
+    let count = 0;
+    if (part.kind === 'jsonl') {
+      const entries = parseJsonl(part.text);
+      if (part.rel === 'main.jsonl') meta = summarize(entries);
+      for (const { raw, rec } of entries) {
+        if (rec === null) {
+          const t = transform(raw);
+          body.push(JSON.stringify({ p: part.rel, x: t }));
+          residualSource.push(t);
+        } else {
+          let r = stripThinking ? dropThinking(rec) : rec;
+          if (!stripThinking) scanThinking(r, thinking);
+          r = transform(r);
+          body.push(JSON.stringify({ p: part.rel, l: r }));
+          residualSource.push(JSON.stringify(r));
+        }
+        count++;
+      }
+    } else if (part.kind === 'text') {
+      const t = transform(part.text);
+      body.push(JSON.stringify({ p: part.rel, t }));
+      residualSource.push(t);
+      count = 1;
+    } else {
+      body.push(JSON.stringify({ p: part.rel, b: part.base64 }));
+      count = 1;
+    }
+    partsMeta.push({ rel: part.rel, kind: part.kind, count });
+  }
+
+  if (redact && !stripThinking && !allowThinkingSecrets && thinking.possibleSecrets > 0) {
+    const e = new Error(
+      `${thinking.possibleSecrets} credential-like string(s) in ${thinking.blocks} signed thinking block(s) cannot be redacted (editing a thinking block invalidates it). ` +
+        'Re-run with --strip-thinking to drop thinking blocks, or --allow-thinking-secrets to export them as they are.',
+    );
+    e.code = 'THINKING_SECRETS';
+    throw e;
+  }
+  const bodyText = body.join('\n') + '\n';
+  const header = {
+    carry: FORMAT,
+    agent: AGENT,
+    tool: TOOL,
+    createdAt: new Date().toISOString(),
+    sessionId: id,
+    title: meta?.title ?? null,
+    claudeVersions: meta?.versions ?? [],
+    entrypoints: meta?.entrypoints ?? [],
+    turns: meta?.turns ?? 0,
+    tokens: TOKENS,
+    parts: partsMeta,
+    skippedLarge: skipped,
+    redaction: redactor ? { enabled: true, emails, counts: redactor.counts } : { enabled: false },
+    thinkingStripped: stripThinking,
+    thinking,
+    pathsRewritten: mapper.stats.replaced,
+    residualHomePaths: residualHomePaths(residualSource).size,
+    bodySha256: sha256(bodyText),
+  };
+  return { text: JSON.stringify(header) + '\n' + bodyText, header };
+}
+
+/**
+ * Thinking blocks are signed, so they travel unmodified: neither path-rewritten
+ * nor redacted. Count credential-shaped strings inside them so the exporter can
+ * warn instead of silently shipping them.
+ */
+function scanThinking(rec, acc) {
+  const c = rec?.message?.content;
+  if (!Array.isArray(c)) return;
+  for (const b of c) {
+    if (!b || b.type !== 'thinking' || typeof b.thinking !== 'string') continue;
+    acc.blocks++;
+    const probe = makeRedactor();
+    probe.fn(b.thinking);
+    acc.possibleSecrets += Object.values(probe.counts).reduce((a, n) => a + n, 0);
+  }
+}
+
+function dropThinking(rec) {
+  const c = rec?.message?.content;
+  if (!Array.isArray(c)) return rec;
+  const kept = c.filter((b) => !(b && (b.type === 'thinking' || b.type === 'redacted_thinking')));
+  return kept.length === c.length ? rec : { ...rec, message: { ...rec.message, content: kept } };
+}
+
+/** Atomic (temp + rename) so a file-sync tool never uploads a half-written bundle. */
+export function writeBundle(file, text, { passphrase } = {}) {
+  let data = Buffer.from(text);
+  if (file.endsWith('.gz') || file.endsWith('.enc') || passphrase) data = zlib.gzipSync(data);
+  if (passphrase) data = encrypt(data, passphrase);
+  fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+  const tmp = `${file}.carry-tmp`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+
+export function readBundle(file, { passphrase } = {}) {
+  if (fs.statSync(file).size > MAX_BUNDLE_BYTES) throw new Error('bundle is larger than 1 GB; refusing to read it');
+  let buf = fs.readFileSync(file);
+  if (isEncrypted(buf)) buf = decrypt(buf, passphrase);
+  if (buf[0] === 0x1f && buf[1] === 0x8b) buf = zlib.gunzipSync(buf, { maxOutputLength: MAX_BUNDLE_BYTES });
+  const text = buf.toString('utf8');
+  const nl = text.indexOf('\n');
+  if (nl < 0) throw new Error('not a carry bundle (no header)');
+  let header;
+  try {
+    header = JSON.parse(text.slice(0, nl));
+  } catch {
+    throw new Error('not a carry bundle (bad header)');
+  }
+  if (header.carry !== FORMAT) throw new Error(`unsupported bundle format ${header.carry} (this tool reads ${FORMAT})`);
+  // Bundles written before the field existed were all Claude Code.
+  const agent = header.agent ?? AGENT;
+  if (!SUPPORTED_AGENTS.has(agent)) {
+    throw new Error(`bundle is for agent "${agent}"; this version of agent-carry supports: ${[...SUPPORTED_AGENTS].join(', ')}`);
+  }
+  const bodyText = text.slice(nl + 1);
+  if (sha256(bodyText) !== header.bodySha256) throw new Error('bundle is corrupt or was modified: body hash mismatch');
+  const rows = bodyText.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  return { header, rows };
+}
+
+/**
+ * Write a bundle into a Claude home for a target project root. Returns a plan;
+ * with dryRun it writes nothing.
+ */
+export function importBundle({ bundle, claudeHome, root, home, dryRun = false }) {
+  const realRoot = realpathOr(root);
+  const folder = path.join(projectsDir(claudeHome), mangle(realRoot));
+  const where = { store: folder, root: realRoot, home };
+  const back = fromPortable(where);
+  const id = bundle.header.sessionId;
+  const plan = { id, folder, root: realRoot, files: [], warnings: [] };
+  if (mangle(realRoot).length > 200) {
+    plan.warnings.push('project path is very long; Claude Code may shorten the folder name differently than carry does');
+  }
+
+  const byPart = new Map();
+  for (const row of bundle.rows) {
+    if (!byPart.has(row.p)) byPart.set(row.p, []);
+    byPart.get(row.p).push(row);
+  }
+
+  for (const [rel, rows] of byPart) {
+    const dest = rel === 'main.jsonl' ? path.join(folder, `${id}.jsonl`) : path.join(folder, id, rel.replace(/^side\//, ''));
+    if (!path.resolve(dest).startsWith(path.resolve(folder) + path.sep)) throw new Error(`refusing path outside project folder: ${rel}`);
+    const kind = rows[0].l !== undefined || rows[0].x !== undefined ? 'jsonl' : rows[0].t !== undefined ? 'text' : 'binary';
+    let content;
+    let stat;
+    if (kind === 'jsonl') {
+      const incoming = rows.map((r) => {
+        const raw = r.l !== undefined ? JSON.stringify(mapStrings(r.l, back.fn)) : back.fn(r.x);
+        return { raw, rec: r.l !== undefined ? JSON.parse(raw) : null };
+      });
+      const local = fs.existsSync(dest) ? parseJsonl(fs.readFileSync(dest, 'utf8')) : [];
+      const m = mergeEntries(local, incoming);
+      content = m.lines.join('\n') + '\n';
+      stat = { existed: local.length > 0, added: m.added, skipped: m.skipped };
+    } else if (fs.existsSync(dest)) {
+      stat = { existed: true, added: 0, skipped: 1 };
+      content = null; // sidecar files are content-addressed by name; keep the local one
+    } else {
+      content = kind === 'text' ? back.fn(rows[0].t) : Buffer.from(rows[0].b, 'base64');
+      stat = { existed: false, added: 1, skipped: 0 };
+    }
+    plan.files.push({ rel, dest, kind, ...stat });
+    if (!dryRun && content !== null && (kind !== 'jsonl' || stat.added > 0 || !stat.existed)) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const tmp = `${dest}.carry-tmp`;
+      fs.writeFileSync(tmp, content);
+      fs.renameSync(tmp, dest);
+    }
+  }
+  return plan;
+}

package/src/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import os from 'node:os';
+import path from 'node:path';
+import { claudeHome, mangle, projectsDir, realpathOr } from './paths.js';
+import { projectFolders, listSessions, findSession } from './store.js';
+import { buildBundle, writeBundle, readBundle, importBundle } from './bundle.js';
+import { parseJsonl, summarize } from './transcript.js';
+import fs from 'node:fs';
+import { pushProject, pullProject } from './sync.js';
+
+const HELP = `carry (agent-carry): move coding-agent sessions between machines and folders. Supported agent: claude-code
+
+  carry list    [--all] [--project DIR]
+  carry export  <id|prefix|--latest> [-o FILE] [--project-root DIR]
+                [--no-redact] [--redact-emails] [--strip-thinking | --allow-thinking-secrets]
+  carry inspect <bundle>
+  carry import  <bundle> [--project-root DIR] [--dry-run]
+  carry push    <dir> [--name PROJECT] [--quiet]     sync every session of this project to a shared folder
+  carry pull    <dir> [--name PROJECT] [--dry-run] [--quiet]
+
+Encryption (export, import, push, pull): set CARRY_PASSPHRASE or pass --passphrase-file FILE.
+
+Global: --claude-home DIR (default $CLAUDE_CONFIG_DIR or ~/.claude), --home DIR
+`;
+
+function parseArgs(argv) {
+  const flags = {};
+  const pos = [];
+  const valued = new Set(['-o', '--out', '--project', '--project-root', '--claude-home', '--home', '--name', '--passphrase-file']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('-') && a !== '-') {
+      if (valued.has(a)) flags[a.replace(/^-+/, '')] = argv[++i];
+      else flags[a.replace(/^-+/, '')] = true;
+    } else pos.push(a);
+  }
+  return { flags, pos };
+}
+
+function fail(msg) {
+  process.stderr.write(`carry: ${msg}\n`);
+  process.exit(1);
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return process.stdout.write(`${pkg.version}\n`);
+  }
+  const { flags, pos } = parseArgs(rest);
+  const home = flags['claude-home'] ? path.resolve(flags['claude-home']) : claudeHome();
+  const userHome = flags.home ? path.resolve(flags.home) : os.homedir();
+  const cwd = flags['project-root'] || flags.project || process.cwd();
+  const passphrase = flags['passphrase-file'] ? fs.readFileSync(flags['passphrase-file'], 'utf8').replace(/\r?\n$/, '') : process.env.CARRY_PASSPHRASE || undefined;
+  const say = (m) => flags.quiet || process.stdout.write(`${m}\n`);
+
+  try {
+    if (!cmd || cmd === 'help' || flags.help) return process.stdout.write(HELP);
+
+    if (cmd === 'list') {
+      const folders = flags.all ? projectFolders(home) : [path.join(projectsDir(home), mangle(realpathOr(cwd)))];
+      let n = 0;
+      for (const f of folders) {
+        for (const s of listSessions(f)) {
+          n++;
+          const when = new Date(s.mtimeMs).toISOString().slice(0, 16).replace('T', ' ');
+          const where = flags.all ? `  ${s.dominantCwd ?? path.basename(f)}` : '';
+          process.stdout.write(`${s.id.slice(0, 8)}  ${when}  ${String(s.turns).padStart(3)} turns  ${s.title ?? '(untitled)'}${where}\n`);
+        }
+      }
+      if (!n) process.stdout.write(`no sessions found for ${flags.all ? 'any project' : realpathOr(cwd)}\n`);
+      return;
+    }
+
+    if (cmd === 'export') {
+      const folders = flags.all || !flags.latest ? projectFolders(home) : [path.join(projectsDir(home), mangle(realpathOr(cwd)))];
+      let target;
+      if (flags.latest) {
+        const here = path.join(projectsDir(home), mangle(realpathOr(cwd)));
+        const s = listSessions(here)[0];
+        if (!s) fail(`no sessions for ${realpathOr(cwd)}`);
+        target = { folder: here, id: s.id };
+      } else {
+        if (!pos[0]) fail('export needs a session id (see `carry list`) or --latest');
+        // Same id can exist in several project folders (a session that was carried). Prefer the folder
+        // named by --project, else the current one, and only then search everything.
+        const scoped = path.join(projectsDir(home), mangle(realpathOr(flags.project || process.cwd())));
+        try {
+          target = findSession([scoped], pos[0]);
+        } catch (e) {
+          if (flags.project) throw e;
+          target = findSession(folders, pos[0]);
+        }
+      }
+      const entries = parseJsonl(fs.readFileSync(path.join(target.folder, `${target.id}.jsonl`), 'utf8'));
+      const sum = summarize(entries);
+      const root = flags['project-root'] ? realpathOr(flags['project-root']) : sum.dominantCwd;
+      if (!root) fail('could not determine the project root from the transcript; pass --project-root');
+      const { text, header } = buildBundle({
+        folder: target.folder,
+        id: target.id,
+        where: { store: target.folder, root, home: userHome },
+        redact: !flags['no-redact'],
+        emails: !!flags['redact-emails'],
+        stripThinking: !!flags['strip-thinking'],
+        allowThinkingSecrets: !!flags['allow-thinking-secrets'],
+      });
+      const out = flags.o || flags.out || `${target.id.slice(0, 8)}${passphrase ? '.carry.enc' : '.carry.gz'}`;
+      writeBundle(out, text, { passphrase });
+      const red = Object.entries(header.redaction.counts || {}).map(([k, v]) => `${k}:${v}`).join(' ') || 'none found';
+      process.stdout.write(
+        `exported ${header.sessionId.slice(0, 8)} "${header.title ?? 'untitled'}" -> ${out}\n` +
+          `  parts: ${header.parts.length}   paths rewritten: ${header.pathsRewritten}\n` +
+          `  redacted: ${header.redaction.enabled ? red : 'OFF'}   encrypted: ${passphrase ? 'yes' : 'no'}\n`,
+      );
+      if (header.residualHomePaths > 0) {
+        process.stderr.write(`  warning: ${header.residualHomePaths} other absolute home path(s) remain in the bundle (other users or tools). Review with \`carry inspect\`.\n`);
+      }
+      if (header.thinking.possibleSecrets > 0) {
+        process.stderr.write(`  warning: ${header.thinking.possibleSecrets} credential-like string(s) in ${header.thinking.blocks} signed thinking block(s). These cannot be redacted without invalidating them; re-export with --strip-thinking.\n`);
+      }
+      if (header.skippedLarge.length) process.stderr.write(`  warning: ${header.skippedLarge.length} file(s) over 20MB were not included\n`);
+      return;
+    }
+
+    if (cmd === 'inspect') {
+      if (!pos[0]) fail('inspect needs a bundle file');
+      const { header } = readBundle(pos[0], { passphrase });
+      process.stdout.write(JSON.stringify(header, null, 2) + '\n');
+      return;
+    }
+
+    if (cmd === 'import') {
+      if (!pos[0]) fail('import needs a bundle file');
+      const bundle = readBundle(pos[0], { passphrase });
+      const plan = importBundle({ bundle, claudeHome: home, root: cwd, home: userHome, dryRun: !!flags['dry-run'] });
+      process.stdout.write(`${flags['dry-run'] ? 'would import' : 'imported'} ${plan.id.slice(0, 8)} into ${plan.folder}\n`);
+      for (const f of plan.files.filter((f) => f.kind === 'jsonl')) {
+        process.stdout.write(`  ${f.rel}: +${f.added} new, ${f.skipped} already present\n`);
+      }
+      const side = plan.files.filter((f) => f.kind !== 'jsonl');
+      if (side.length) process.stdout.write(`  sidecar files: ${side.filter((f) => f.added).length} new, ${side.filter((f) => !f.added).length} kept\n`);
+      for (const w of plan.warnings) process.stderr.write(`  warning: ${w}\n`);
+      if (!flags['dry-run']) process.stdout.write(`\nresume with:\n  cd ${plan.root} && claude --resume ${plan.id}\n`);
+      return;
+    }
+
+    if (cmd === 'push' || cmd === 'pull') {
+      if (!pos[0]) fail(`${cmd} needs a shared folder, e.g. carry ${cmd} ~/Sync/carry`);
+      const dir = path.resolve(pos[0]);
+      const common = { dir, claudeHome: home, root: cwd, userHome, passphrase, name: flags.name, log: say };
+      if (cmd === 'push') {
+        const r = pushProject(common);
+        if (r.skipped.length) process.stderr.write(`  ${r.skipped.length} session(s) skipped: credential-like text in thinking blocks\n`);
+        say(`push ${r.key}: ${r.pushed} written, ${r.unchanged} unchanged (device ${r.device}${passphrase ? ', encrypted' : ''})`);
+      } else {
+        const r = pullProject({ ...common, dryRun: !!flags['dry-run'] });
+        say(`pull ${r.key}: ${r.imported} session(s) updated, ${r.upToDate} up to date`);
+        for (const e of r.errors) process.stderr.write(`  error: ${e}\n`);
+        if (r.errors.length) process.exitCode = 1;
+      }
+      return;
+    }
+
+    fail(`unknown command "${cmd}"\n\n${HELP}`);
+  } catch (e) {
+    fail(e.message);
+  }
+}
+
+main();

package/src/crypto.js

@@ -0,0 +1,43 @@
+import crypto from 'node:crypto';
+
+/**
+ * Passphrase encryption for bundles: scrypt -> AES-256-GCM, node:crypto only.
+ * Layout: "CARRYENC" | version(1) | salt(16) | iv(12) | ciphertext | tag(16).
+ * The fixed header is bound into the auth tag, so any edit is detected.
+ */
+const MAGIC = Buffer.from('CARRYENC');
+const VERSION = 1;
+const HEADER = MAGIC.length + 1 + 16 + 12;
+const SCRYPT = { N: 2 ** 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+
+export const isEncrypted = (buf) => buf.length > HEADER + 16 && buf.subarray(0, MAGIC.length).equals(MAGIC);
+
+export function encrypt(plain, passphrase) {
+  if (!passphrase) throw new Error('empty passphrase');
+  const salt = crypto.randomBytes(16);
+  const iv = crypto.randomBytes(12);
+  const key = crypto.scryptSync(passphrase, salt, 32, SCRYPT);
+  const head = Buffer.concat([MAGIC, Buffer.from([VERSION]), salt, iv]);
+  const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+  c.setAAD(head);
+  const ct = Buffer.concat([c.update(plain), c.final()]);
+  return Buffer.concat([head, ct, c.getAuthTag()]);
+}
+
+export function decrypt(buf, passphrase) {
+  if (!passphrase) throw new Error('this bundle is encrypted: set CARRY_PASSPHRASE or pass --passphrase-file');
+  if (buf[MAGIC.length] !== VERSION) throw new Error(`unsupported encryption version ${buf[MAGIC.length]}`);
+  const head = buf.subarray(0, HEADER);
+  const salt = head.subarray(MAGIC.length + 1, MAGIC.length + 17);
+  const iv = head.subarray(MAGIC.length + 17);
+  const tag = buf.subarray(buf.length - 16);
+  const key = crypto.scryptSync(passphrase, salt, 32, SCRYPT);
+  const d = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  d.setAAD(head);
+  d.setAuthTag(tag);
+  try {
+    return Buffer.concat([d.update(buf.subarray(HEADER, buf.length - 16)), d.final()]);
+  } catch {
+    throw new Error('wrong passphrase, or the file was modified');
+  }
+}

package/src/merge.js

@@ -0,0 +1,29 @@
+import { recordKey } from './transcript.js';
+
+/**
+ * Union of two transcripts keyed by record identity. The local file is the
+ * source of truth: its lines are kept byte for byte and in order, and records
+ * that only exist in the incoming copy are appended. A session that continued
+ * on two machines therefore becomes a DAG with two branches, which is exactly
+ * what it is, and merging the same bundle twice changes nothing.
+ */
+export function mergeEntries(local, incoming) {
+  const localKeys = new Set(local.map(recordKey));
+  const lines = local.map((e) => e.raw);
+  const seenUuid = new Set();
+  let added = 0;
+  for (const e of incoming) {
+    const k = recordKey(e);
+    if (localKeys.has(k)) continue;
+    // Conversation records are unique by uuid. Bookkeeping records (mode,
+    // last-prompt, ...) have no identity and their *order* carries meaning
+    // (the last one wins), so repeats inside the incoming copy are kept.
+    if (k.startsWith('u:')) {
+      if (seenUuid.has(k)) continue;
+      seenUuid.add(k);
+    }
+    lines.push(e.raw);
+    added++;
+  }
+  return { lines, added, kept: local.length, skipped: incoming.length - added };
+}

package/src/paths.js

@@ -0,0 +1,26 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * Claude Code stores a project's sessions in a folder named after the project's
+ * working directory with every non-alphanumeric character replaced by '-'.
+ * The mapping is lossy (`/a/b-c` and `/a/b/c` collide), so it can only be
+ * computed forward, never inverted. That is why a session cannot simply be
+ * copied to another machine: the folder key depends on the absolute path.
+ */
+export const mangle = (absPath) => absPath.replace(/[^A-Za-z0-9]/g, '-');
+
+export function claudeHome(env = process.env) {
+  return env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+export const projectsDir = (home) => path.join(home, 'projects');
+
+export function realpathOr(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}

package/src/portable.js

@@ -0,0 +1,111 @@
+/**
+ * Path portability. Absolute paths are swapped for tokens on export and for the
+ * target machine's paths on import. Order matters: the project's session store
+ * lives under HOME and contains the project root in mangled form, so the
+ * longest, most specific prefix is replaced first.
+ */
+export const TOKENS = {
+  store: '${CARRY_STORE}',
+  root: '${CARRY_ROOT}',
+  home: '${CARRY_HOME}',
+};
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// A path only matches as a whole segment run: `/work/app` must not touch
+// `/work/app-two` or `/work/app.bak`, and must not match inside `/x/work/app`.
+const prefixRe = (abs) =>
+  new RegExp(`(?:(?<![A-Za-z0-9])|(?<=\\\\[nrt])|(?<=(?:\\x1b|u001b)\\[[0-9;]*m))${escapeRe(abs)}(?![A-Za-z0-9_-]|\\.[A-Za-z0-9])`, 'g');
+
+const THINKING = new Set(['thinking', 'redacted_thinking']);
+
+/**
+ * Apply `fn` to every string value in a parsed record. Thinking blocks are
+ * skipped on purpose: they carry a cryptographic signature and the API rejects
+ * a resumed history in which one was edited.
+ */
+export function mapStrings(value, fn) {
+  if (typeof value === 'string') return fn(value);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const out = value.map((v) => {
+      const m = mapStrings(v, fn);
+      if (m !== v) changed = true;
+      return m;
+    });
+    return changed ? out : value;
+  }
+  if (value && typeof value === 'object') {
+    if (THINKING.has(value.type)) return value;
+    let changed = false;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      // Keys too: file-history snapshots are maps keyed by absolute path.
+      const nk = fn(k);
+      const m = mapStrings(v, fn);
+      if (m !== v || nk !== k) changed = true;
+      out[nk] = m;
+    }
+    return changed ? out : value;
+  }
+  return value;
+}
+
+/** Build a string rewriter from a list of [from, to] prefix pairs, applied in order of `from` length. */
+function rewriter(pairs) {
+  const ordered = pairs
+    .filter(([from]) => from && from !== '/')
+    .sort((a, b) => b[0].length - a[0].length)
+    .map(([from, to]) => ({ from, to, re: prefixRe(from) }));
+  const stats = { replaced: 0 };
+  const fn = (s) => {
+    let out = s;
+    for (const { from, to, re } of ordered) {
+      if (!out.includes(from)) continue;
+      out = out.replace(re, () => {
+        stats.replaced++;
+        return to;
+      });
+    }
+    return out;
+  };
+  return { fn, stats };
+}
+
+/** `where` = {store, root, home}: absolute paths on the machine we are on. */
+export function toPortable(where) {
+  return rewriter([
+    [where.store, TOKENS.store],
+    [where.root, TOKENS.root],
+    [where.home, TOKENS.home],
+  ]);
+}
+
+export function fromPortable(where) {
+  // Tokens are unambiguous, so a plain global replace is enough.
+  const pairs = [
+    [TOKENS.store, where.store],
+    [TOKENS.root, where.root],
+    [TOKENS.home, where.home],
+  ];
+  const stats = { replaced: 0 };
+  const fn = (s) => {
+    if (!s.includes('${CARRY_')) return s;
+    let out = s;
+    for (const [tok, abs] of pairs) {
+      if (!out.includes(tok)) continue;
+      out = out.split(tok).join(abs);
+      stats.replaced++;
+    }
+    return out;
+  };
+  return { fn, stats };
+}
+
+/** Distinct absolute home-style paths that survived tokenisation (a leak signal, reported to the user). */
+export function residualHomePaths(strings) {
+  const found = new Set();
+  const re = /(?:\/Users|\/home)\/[^/\s"'`\\]+/g;
+  for (const s of strings) for (const m of s.matchAll(re)) found.add(m[0]);
+  return found;
+}

package/src/redact.js

@@ -0,0 +1,79 @@
+import { mapStrings } from './portable.js';
+
+/**
+ * Secret scrubbing for text that is about to leave the machine. Deliberately
+ * pattern-based and conservative: it removes well-known credential shapes, it
+ * does not promise to find every secret. The export report says how many were
+ * removed so the user can judge, and `carry inspect` shows what a bundle holds.
+ */
+const RULES = [
+  ['private-key', /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, () => '[REDACTED:private-key]'],
+  ['anthropic-key', /sk-ant-[A-Za-z0-9_-]{20,}/g, () => '[REDACTED:anthropic-key]'],
+  ['openai-key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g, () => '[REDACTED:openai-key]'],
+  ['github-token', /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{50,})/g, () => '[REDACTED:github-token]'],
+  ['aws-key', /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, () => '[REDACTED:aws-key]'],
+  ['google-key', /\bAIza[0-9A-Za-z_-]{35}\b/g, () => '[REDACTED:google-key]'],
+  ['slack-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, () => '[REDACTED:slack-token]'],
+  ['stripe-key', /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}/g, () => '[REDACTED:stripe-key]'],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, () => '[REDACTED:jwt]'],
+  ['bearer', /(\bBearer\s+)[A-Za-z0-9._~+/-]{20,}=*/g, (_m, p) => `${p}[REDACTED:bearer]`],
+  ['url-credentials', /(\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)[^\s@/]{3,}(@)/gi, (_m, a, b) => `${a}[REDACTED:password]${b}`],
+  [
+    'env-secret',
+    // Name may follow an ANSI colour code directly ("\x1b[31mDB_PASSWORD=..."), where \b would not fire.
+    /(?:(?<![A-Za-z0-9_])|(?<=(?:\x1b|u001b)\[[0-9;]*m))([A-Za-z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|PRIVATE_KEY|ACCESS_KEY)[A-Za-z0-9_]*)(\s*[=:]\s*)(['"]?)(?!\[REDACTED)[^\s'"\\\x1b]{8,}\3/gi,
+    (m, name, sep, q, offset, whole) => {
+      // ALL_CAPS is env-var style: always redact. Mixed or lower case is often code (`max_tokens`,
+      // `token = parseToken(x)`), so there the value must look like a credential, not an identifier.
+      if (name !== name.toUpperCase()) {
+        const value = m.slice(name.length + sep.length + q.length, m.length - q.length);
+        if (/tokens|count|hash|limit|budget|usage|type|len/i.test(name)) return m;
+        if (!/[0-9]/.test(value) || /[()<>{}]/.test(value)) return m;
+      }
+      return `${name}${sep}${q}[REDACTED:env-secret]${q}`;
+    },
+  ],
+  [
+    'json-secret',
+    // Tolerates any number of escaping backslashes: a JSON document stored inside a JSON string, and so on.
+    /(\\*"[A-Za-z_]*(?:secret|token|password|passwd|api_?key|private_?key)[A-Za-z_]*\\*"\s*:\s*\\*")(?!\[REDACTED)[^"\\]{8,}(\\*")/gi,
+    (_m, a, b) => `${a}[REDACTED:json-secret]${b}`,
+  ],
+];
+
+/** Base64 blobs are only redacted when they decode to text that the rules above would redact. */
+const looksPrintable = (t) => t.length > 0 && [...t].filter((c) => c >= ' ' && c <= '~' || c === '\n' || c === '\t').length / t.length > 0.95;
+const BASE64 = [
+  'base64-secret',
+  /(?<![A-Za-z0-9+/])[A-Za-z0-9+/]{24,}={0,2}(?![A-Za-z0-9+/=])/g,
+  (m) => {
+    let decoded;
+    try {
+      decoded = Buffer.from(m, 'base64').toString('utf8');
+    } catch {
+      return m;
+    }
+    if (!looksPrintable(decoded)) return m;
+    const changed = RULES.some(([, re, rep]) => decoded.replace(re, rep) !== decoded);
+    return changed ? '[REDACTED:base64-secret]' : m;
+  },
+];
+
+const EMAIL = ['email', /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, () => '[REDACTED:email]'];
+
+export function makeRedactor({ emails = false } = {}) {
+  const rules = emails ? [...RULES, BASE64, EMAIL] : [...RULES, BASE64];
+  const counts = {};
+  const fn = (s) => {
+    let out = s;
+    for (const [kind, re, rep] of rules) {
+      out = out.replace(re, (...a) => {
+        const r = rep(...a);
+        if (r !== a[0]) counts[kind] = (counts[kind] || 0) + 1;
+        return r;
+      });
+    }
+    return out;
+  };
+  return { fn, counts, apply: (value) => mapStrings(value, fn) };
+}

package/src/store.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectsDir } from './paths.js';
+import { parseJsonl, summarize } from './transcript.js';
+
+const MAX_SIDECAR_BYTES = 20 * 1024 * 1024;
+
+/** Every project folder under <home>/projects. */
+export function projectFolders(home) {
+  const dir = projectsDir(home);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => path.join(dir, d.name));
+}
+
+/** Sessions in one project folder, newest first. */
+export function listSessions(folder) {
+  if (!fs.existsSync(folder)) return [];
+  return fs
+    .readdirSync(folder)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => {
+      const file = path.join(folder, f);
+      const st = fs.statSync(file);
+      const s = summarize(parseJsonl(fs.readFileSync(file, 'utf8')));
+      return { id: f.slice(0, -'.jsonl'.length), file, folder, size: st.size, mtimeMs: st.mtimeMs, ...s };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+
+/** Resolve a full id or unique prefix, searching `folders` in order. */
+export function findSession(folders, idOrPrefix) {
+  const hits = [];
+  for (const folder of folders) {
+    if (!fs.existsSync(folder)) continue;
+    for (const f of fs.readdirSync(folder)) {
+      if (f.endsWith('.jsonl') && f.startsWith(idOrPrefix)) hits.push({ folder, id: f.slice(0, -6) });
+    }
+  }
+  if (hits.length === 0) throw new Error(`no session matches "${idOrPrefix}"`);
+  if (hits.length > 1) {
+    const where = hits.map((h) => `${h.id.slice(0, 8)} in ${path.basename(h.folder)}`).join('; ');
+    throw new Error(`"${idOrPrefix}" matches more than one session (${where}). Narrow it with --project DIR or a longer id.`);
+  }
+  return hits[0];
+}
+
+/**
+ * Everything that belongs to a session: its transcript plus the sidecar
+ * directory (`<id>/subagents/*.jsonl`, `<id>/tool-results/*`). Transcripts
+ * reference tool-results by absolute path, so they must travel together.
+ */
+export function readSession(folder, id) {
+  const parts = [{ rel: 'main.jsonl', kind: 'jsonl', text: fs.readFileSync(path.join(folder, `${id}.jsonl`), 'utf8') }];
+  const skipped = [];
+  const sideDir = path.join(folder, id);
+  const walk = (dir, relBase) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, e.name);
+      const rel = path.posix.join(relBase, e.name);
+      if (e.isDirectory()) walk(abs, rel);
+      else if (e.isFile()) {
+        if (fs.statSync(abs).size > MAX_SIDECAR_BYTES) {
+          skipped.push(rel);
+          continue;
+        }
+        const buf = fs.readFileSync(abs);
+        if (rel.endsWith('.jsonl')) parts.push({ rel: `side/${rel}`, kind: 'jsonl', text: buf.toString('utf8') });
+        else if (isText(buf)) parts.push({ rel: `side/${rel}`, kind: 'text', text: buf.toString('utf8') });
+        else parts.push({ rel: `side/${rel}`, kind: 'binary', base64: buf.toString('base64') });
+      }
+    }
+  };
+  if (fs.existsSync(sideDir)) walk(sideDir, '');
+  return { parts, skipped };
+}
+
+function isText(buf) {
+  const n = Math.min(buf.length, 4096);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return false;
+  return true;
+}

package/src/sync.js

@@ -0,0 +1,147 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { mangle, projectsDir, realpathOr } from './paths.js';
+import { listSessions } from './store.js';
+import { buildBundle, writeBundle, readBundle, importBundle } from './bundle.js';
+
+/**
+ * Folder sync. `push` and `pull` turn any shared folder (Syncthing, Dropbox,
+ * iCloud, a git working tree, a network share) into a session sync backend:
+ *
+ *   <dir>/<project>/<session-id>/<device-id>.carry.gz[.enc]
+ *
+ * Every file has exactly one writer (its device), so the sync tool never sees
+ * a write conflict. `pull` unions every other device's file into the local
+ * session, which is safe to repeat because merging is idempotent.
+ */
+
+export function configDir(env = process.env) {
+  if (env.CARRY_HOME) return env.CARRY_HOME;
+  if (process.platform === 'win32') return path.join(env.APPDATA || os.homedir(), 'agent-carry');
+  return path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'agent-carry');
+}
+
+const readJson = (f, d) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, 'utf8'));
+  } catch {
+    return d;
+  }
+};
+
+function writeJson(f, v) {
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = `${f}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(v, null, 2));
+  fs.renameSync(tmp, f);
+}
+
+export function deviceInfo(cfg) {
+  const f = path.join(cfg, 'device.json');
+  let d = readJson(f, null);
+  if (!d?.id) {
+    const host = os.hostname().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 24) || 'device';
+    d = { id: `${host}-${crypto.randomBytes(3).toString('hex')}` };
+    writeJson(f, d);
+  }
+  return d;
+}
+
+/**
+ * The same project lives at different paths on different machines, so its
+ * identity can't be its path. Prefer the git remote; fall back to the folder name.
+ */
+export function projectKey(root, override) {
+  const clean = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (override) return clean(override);
+  const base = clean(path.basename(root)) || 'project';
+  try {
+    const url = execFileSync('git', ['-C', root, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (url) {
+      const norm = url.replace(/^[a-z+]+:\/\//i, '').replace(/^[^@/]+@/, '').replace(/:/g, '/').replace(/\.git$/, '').replace(/\/+$/, '').toLowerCase();
+      return `${base}-${crypto.createHash('sha256').update(norm).digest('hex').slice(0, 8)}`;
+    }
+  } catch {
+    /* not a git repo */
+  }
+  return base;
+}
+
+const ext = (passphrase) => (passphrase ? '.carry.enc' : '.carry.gz');
+
+export function pushProject({ dir, claudeHome, root, userHome, passphrase, name, cfg = configDir(), log = () => {} }) {
+  const realRoot = realpathOr(root);
+  const folder = path.join(projectsDir(claudeHome), mangle(realRoot));
+  const key = projectKey(realRoot, name);
+  const dev = deviceInfo(cfg);
+  const out = { key, device: dev.id, pushed: 0, unchanged: 0, skipped: [] };
+  for (const s of listSessions(folder)) {
+    const target = path.join(dir, key, s.id, `${dev.id}${ext(passphrase)}`);
+    let built;
+    try {
+      built = buildBundle({ folder, id: s.id, where: { store: folder, root: realRoot, home: userHome } });
+    } catch (e) {
+      if (e.code !== 'THINKING_SECRETS') throw e;
+      out.skipped.push(s.id);
+      log(`skipped ${s.id.slice(0, 8)}: credential-like text in thinking blocks (export it by hand with --strip-thinking)`);
+      continue;
+    }
+    const { text, header } = built;
+    if (fs.existsSync(target)) {
+      try {
+        if (readBundle(target, { passphrase }).header.bodySha256 === header.bodySha256) {
+          out.unchanged++;
+          continue;
+        }
+      } catch {
+        /* unreadable old file: overwrite it */
+      }
+    }
+    writeBundle(target, text, { passphrase });
+    out.pushed++;
+    log(`pushed ${s.id.slice(0, 8)} ${s.title ?? ''}`);
+  }
+  return out;
+}
+
+export function pullProject({ dir, claudeHome, root, userHome, passphrase, name, dryRun = false, cfg = configDir(), log = () => {} }) {
+  const realRoot = realpathOr(root);
+  const key = projectKey(realRoot, name);
+  const dev = deviceInfo(cfg);
+  const stateFile = path.join(cfg, 'pulled.json');
+  const state = readJson(stateFile, {});
+  const out = { key, imported: 0, upToDate: 0, sessions: 0, errors: [] };
+  const projDir = path.join(dir, key);
+  if (!fs.existsSync(projDir)) return out;
+  for (const id of fs.readdirSync(projDir)) {
+    const sdir = path.join(projDir, id);
+    if (!fs.statSync(sdir).isDirectory()) continue;
+    for (const f of fs.readdirSync(sdir)) {
+      if (!/\.carry\.(gz|enc)$/.test(f) || f.startsWith(`${dev.id}.`)) continue;
+      const file = path.join(sdir, f);
+      const st = fs.statSync(file);
+      const sig = `${st.size}:${Math.round(st.mtimeMs)}`;
+      if (state[file] === sig) {
+        out.upToDate++;
+        continue;
+      }
+      try {
+        const bundle = readBundle(file, { passphrase });
+        const plan = importBundle({ bundle, claudeHome, root: realRoot, home: userHome, dryRun });
+        const added = plan.files.filter((x) => x.kind === 'jsonl').reduce((n, x) => n + x.added, 0);
+        if (!dryRun) state[file] = sig;
+        out.imported += added > 0 ? 1 : 0;
+        out.upToDate += added > 0 ? 0 : 1;
+        out.sessions++;
+        if (added > 0) log(`pulled ${id.slice(0, 8)} from ${f.split('.')[0]} (+${added} records)`);
+      } catch (e) {
+        out.errors.push(`${id.slice(0, 8)}/${f}: ${e.message}`);
+      }
+    }
+  }
+  if (!dryRun) writeJson(stateFile, state);
+  return out;
+}

package/src/transcript.js

@@ -0,0 +1,66 @@
+import crypto from 'node:crypto';
+
+/**
+ * Transcripts are internal and undocumented, so parsing is tolerant: a line
+ * that is not JSON is kept verbatim and travels with the session untouched.
+ */
+export function parseJsonl(text) {
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (raw === '') continue;
+    try {
+      out.push({ raw, rec: JSON.parse(raw) });
+    } catch {
+      out.push({ raw, rec: null });
+    }
+  }
+  return out;
+}
+
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+export const sha256 = sha;
+
+/**
+ * Identity of a record for merging. Conversation records carry a `uuid`, which
+ * is stable across machines. Bookkeeping records (titles, modes, snapshots)
+ * have none, so they are identified by content.
+ */
+export function recordKey({ raw, rec }) {
+  if (rec && typeof rec.uuid === 'string') return `u:${rec.uuid}`;
+  return `h:${sha(rec ? JSON.stringify(rec) : raw)}`;
+}
+
+export function summarize(entries) {
+  const cwds = new Map();
+  const versions = new Set();
+  const entrypoints = new Set();
+  let title = null;
+  let customTitle = null;
+  let first = null;
+  let last = null;
+  let turns = 0;
+  for (const { rec } of entries) {
+    if (!rec) continue;
+    if (rec.cwd) cwds.set(rec.cwd, (cwds.get(rec.cwd) || 0) + 1);
+    if (rec.version) versions.add(rec.version);
+    if (rec.entrypoint) entrypoints.add(rec.entrypoint);
+    if (rec.type === 'ai-title' && rec.aiTitle) title = rec.aiTitle;
+    if (rec.type === 'custom-title' && rec.customTitle) customTitle = rec.customTitle;
+    if (rec.timestamp) {
+      first ??= rec.timestamp;
+      last = rec.timestamp;
+    }
+    if (rec.type === 'user' && !rec.isMeta && !rec.isSidechain) turns++;
+  }
+  const dominantCwd = [...cwds.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  return {
+    title: customTitle || title,
+    dominantCwd,
+    cwds: [...cwds.keys()],
+    versions: [...versions],
+    entrypoints: [...entrypoints],
+    first,
+    last,
+    turns,
+  };
+}