@askalf/claude-sync 0.0.2 → 0.1.0

package/README.md

@@ -1,5 +1,7 @@
 # @askalf/claude-sync
 
+> _claude-sync — own your sessions — move Claude Code sessions across machines. Part of **[Own Your Stack](https://github.com/askalf)** — own your AI infrastructure instead of renting it by the token._
+
 > Sync Claude Code sessions across machines. Pack a session into a portable `.ccsync` file, ship it via Dropbox / iCloud / Syncthing / a USB stick, unpack on the other side. Path-hash mismatches solved via git-remote-url as the canonical project key.
 
 ```bash
@@ -19,8 +21,8 @@ Claude Code stores sessions locally at `~/.claude/projects/<encoded-cwd>/<sessio
 
 `claude-sync` solves both:
 
-- **Canonical project key** = `git:<remote-url>`. Same logical repo → same key, regardless of where it's checked out. (Falls back to `name:<basename>` when no git remote.)
-- **Single-writer model.** You explicitly `push` from machine A, then `pull` on machine B. No background daemon racing files. The transport is a directory you nominate (Dropbox / iCloud / Syncthing / a USB stick); each machine writes its own file under its own machine name, so two machines pushing the same session don't collide.
+- **Canonical project key** = `git:<host>/<owner>/<repo>`, derived from the git remote. Same logical repo → same key, regardless of where it's checked out or which protocol you cloned with — SSH and HTTPS remotes normalize to the same key. (Falls back to `name:<basename>` when there's no git remote.)
+- **You choose the cadence.** `push` from machine A and `pull` on machine B by hand, or run `claude-sync watch` to push-on-change and pull-on-interval automatically. The transport is a directory you nominate (Dropbox / iCloud / Syncthing / a USB stick); each machine writes its own file under its own machine name, so two machines pushing the same session don't collide.
 
 ## Use it
 
@@ -57,12 +59,54 @@ claude --resume sess-abc123
 
 That's the whole loop.
 
+### Or let it run: watch mode
+
+Tired of remembering to `push` and `pull`? Run a daemon per project:
+
+```bash
+cd ~/code/myapp
+claude-sync watch
+# claude-sync watch — desktop
+#   project:  git:github.com/you/myapp
+#   cwd:      /Users/you/code/myapp
+#   syncDir:  /Users/you/Dropbox/claude-sync
+#   every 10s · push most-recent changed session · pull all projects
+#   Ctrl-C to stop.
+#
+#   ↑ pushed sess-abc123 (142 lines)
+#   Imported sess-def456 from laptop → …/sess-def456.jsonl
+```
+
+Every interval (default 10s, `--interval <seconds>`) it pushes the active
+session whenever it has grown and pulls anything newer from your other
+machines. It watches the **most-recent** session by default; pass a session-id
+to pin one, or `--all` to push every changed session in the project. `--once`
+runs a single cycle and exits — handy from `cron`. Ctrl-C stops cleanly.
+
+It's still poll-based, not real-time co-editing: don't run the *same* session
+live on two machines at once (see [Concurrency](#concurrency)). Watch is for
+"pick up where the other machine left off without thinking about it."
+
+### Starting on a fresh clone
+
+`pull` can only deliver a session to a directory it knows about. On a machine
+that has never had a session for this project yet, register the directory once:
+
+```bash
+cd ~/code/myapp
+claude-sync register   # binds this cwd to the project key — no session needed
+claude-sync pull       # now resolves
+```
+
+(`watch` registers automatically on start, and `import … --cwd <path>` registers
+the target, so you usually only need `register` for a manual `pull`-first flow.)
+
 ## How path resolution works
 
 When you `push` from a project with a git remote, claude-sync:
 
 1. Reads `git remote get-url origin` from your cwd.
-2. Builds a project key: `git:https://github.com/you/myapp.git`.
+2. Canonicalizes it into a project key: `git:github.com/you/myapp` (SSH and HTTPS remotes land on the same key).
 3. Registers the local cwd under that key in `~/.claude-sync/projects.json`.
 4. Writes the `.ccsync` into `<syncDir>/<encoded-key>/<session>-<machine>.ccsync`.
 
@@ -71,36 +115,36 @@ When you `pull`, the receiving machine:
 1. Scans `<syncDir>/` for project subdirs.
 2. For each, looks up the encoded key in its own `projects.json`.
 3. If a local cwd is registered for that key, installs the session there.
-4. If not — claude-sync hasn't seen this project on this machine yet — it skips with a warning. You either `push` once from the right cwd to register it, or run `claude-sync import <file> --cwd <path>` explicitly.
+4. If not — claude-sync hasn't seen this project on this machine yet — it skips with a warning. Run `claude-sync register` in the cwd once (binds the key, no session needed), or `claude-sync import <file> --cwd <path>` to install a specific file (which also registers the directory).
 
-In practice: clone the repo on the new machine, `cd` in, run `claude-sync push` once with no real session (it'll error if there's no session — that's fine), then run `claude-sync pull` to fetch. The first push registers the cwd.
-
-A cleaner way: just run any `claude` command in the cwd once, then `claude-sync export` (which registers without pushing).
+In practice: clone the repo on the new machine, `cd` in, `claude-sync register`, then `claude-sync pull`. Or just start `claude-sync watch`, which registers on launch.
 
 ## Concurrency
 
-There's no daemon and no automatic background sync. You decide when to push and when to pull. If you forget and edit the same session on both machines:
+`watch` automates *when* to push and pull, but it's still poll-based, not a locking protocol. If two machines edit the **same** session concurrently:
 
 - Two `.ccsync` files end up in `<syncDir>/<project>/`, named with each machine's name.
 - The receiving `pull` skips files older or shorter than the local copy.
 - Newer/longer files install with `--overwrite`. The losing machine's edits become a `<session-id>-copy.jsonl` (you can manually inspect + reconcile).
 
-Future versions may add a watch-mode + lock-file protocol for "real-time" sync; v0.0.1 is deliberate-action only.
+So: use `watch` to hand a project *back and forth* between machines hands-free; don't drive the same live session from two machines at once. A lock-file protocol for true real-time co-editing is a possible future addition.
 
 ## CLI reference
 
 ```text
 claude-sync init <syncDir> [--name <machine>]
 claude-sync list
+claude-sync register [cwd]
 claude-sync export [session-id] [-o <file>]
 claude-sync import <file> [--cwd <path>] [--overwrite]
 claude-sync push [session-id]
 claude-sync pull
+claude-sync watch [session-id] [--interval <seconds>] [--all] [--once]
 claude-sync doctor
 claude-sync --help / --version
 ```
 
-`doctor` prints config, machine name, registered projects, and warns if any registered cwd no longer exists on disk.
+`doctor` prints config, machine name, registered projects, and transport peers — and warns if any registered cwd no longer exists on disk, or if every file in the transport carries this machine's own name (which makes `pull` a silent no-op — give each machine a distinct `--name`).
 
 ## File format
 
@@ -110,7 +154,7 @@ claude-sync --help / --version
 {
   "_schemaVersion": 1,
   "sessionId": "...",
-  "projectKey": "git:https://github.com/you/myapp.git",
+  "projectKey": "git:github.com/you/myapp",
   "originalCwd": "C:\\Users\\you\\code\\myapp",
   "machineName": "desktop",
   "exportedAt": 1715380000000,
@@ -119,13 +163,12 @@ claude-sync --help / --version
 }
 ```
 
-Schema-versioned. Version 1 is the only thing v0.0.1 understands; importers refuse unknown versions explicitly rather than silently dropping fields.
+Schema-versioned. Version 1 is the only thing the current release understands; importers refuse unknown versions explicitly rather than silently dropping fields.
 
 ## What it isn't
 
-- **Not a daemon.** Push and pull are explicit user actions. Run a watcher yourself if you want background sync.
-- **Not a relay service.** v0.0.1 ships only the filesystem transport — point it at any synced folder. SSH / S3 / gist / WebSocket transports would be straightforward additions; not in v0.0.1.
-- **Not real-time.** If both machines are CC-active simultaneously, the second to `pull` overwrites their in-progress session unless they noticed and stopped first. Use one machine at a time.
+- **Not real-time co-editing.** `watch` polls on an interval; it isn't a locking protocol. If both machines drive the *same* session simultaneously, the second to sync overwrites the other's in-progress copy (the loser is kept as `<id>-copy.jsonl`). Use it to hand a project between machines, not to co-edit one session live.
+- **Not a relay service.** The current release ships only the filesystem transport — point it at any synced folder. SSH / S3 / gist / WebSocket transports would be straightforward additions; not shipped yet.
 - **Not a CC re-implementation.** It just shuffles JSONL. CC's session schema can change without breaking claude-sync — we never parse the events.
 
 ## Library API
@@ -134,13 +177,15 @@ For embedders (custom transports, watch daemons, etc.):
 
 ```ts
 import {
-  listSessions, readSession, writeSession,
+  listSessions, listSessionStats, countSessionLines, readSession, writeSession,
   buildCcsync, parseCcsync, readCcsyncFile, writeCcsyncFile,
-  projectKey, registerProject, lookupCwd,
-  pushToTransport, listTransport,
+  projectKey, normalizeGitRemote, registerProject, registerProjectKey, lookupCwd,
+  pushToTransport, listTransport, listTransportMachines,
 } from '@askalf/claude-sync';
 ```
 
+The `watch` command itself is built entirely on these exports — `listSessionStats` for cheap change detection, `pushToTransport` + `listTransport` for the sync, `registerProject` for first-contact — so a custom daemon or transport has everything it needs.
+
 See `src/index.ts` for the full surface. Zero runtime dependencies.
 
 ## Environment
@@ -153,18 +198,16 @@ See `src/index.ts` for the full surface. Zero runtime dependencies.
 
 MIT — see [LICENSE](LICENSE).
 
-## Also by askalf
-
-| Project | What it does |
-|---------|-------------|
-| [arnie](https://github.com/askalf/arnie) | Portable IT troubleshooting companion. Networking, AD, Windows Update, package managers, log triage, hardware checks. |
-| [brio](https://github.com/askalf/brio) | Capability layer for AI workloads — semantic cache, cost tiering, policy. Sits in front of any Anthropic-compat endpoint. |
-| [browser-bridge](https://github.com/askalf/browser-bridge) | Stealth headless Chromium in a container. CDP on 9222 — Playwright/Puppeteer/MCP-compatible. |
-| [claude-bridge](https://github.com/askalf/claude-bridge) | Bridge Claude Code sessions to Discord. |
-| [dario](https://github.com/askalf/dario) | Local LLM router. Use your Claude Max/Pro subscription as an API. |
-| [deepdive](https://github.com/askalf/deepdive) | Local research agent. Plan → search → fetch → extract → synthesize. Cited answers. |
-| [git-providers](https://github.com/askalf/git-providers) | Unified GitHub + GitLab + Bitbucket Cloud REST clients behind one GitProvider interface. Plus a 44-entry api-key-provider taxonomy. |
-| [hands](https://github.com/askalf/hands) | Cross-platform computer-use agent. Mouse, keyboard, screen. |
-| [install-kit](https://github.com/askalf/install-kit) | curl-pipe-bash template for self-hosted Docker apps. |
-| [pgflex](https://github.com/askalf/pgflex) | One Postgres API. Two modes (real PG ↔ PGlite WASM). |
-| [redisflex](https://github.com/askalf/redisflex) | One Redis API. Two modes (ioredis ↔ in-process). |
+## Own Your Stack
+
+Part of **[Own Your Stack](https://github.com/askalf)** — open tools for owning your AI infrastructure instead of renting it by the token. One subscription. Your box. Your terms.
+
+- **[dario](https://github.com/askalf/dario)** — own your routing
+- **[deepdive](https://github.com/askalf/deepdive)** — own your research
+- **[hands](https://github.com/askalf/hands)** — own your computer-use
+- **[agent](https://github.com/askalf/agent)** — own your fleet
+- **[browser-bridge](https://github.com/askalf/browser-bridge)** — own your browser
+- **claude-sync** — own your sessions _(you are here)_
+
+---
+Part of **[Own Your Stack](https://github.com/askalf)** — own your AI infrastructure instead of renting it. Built by Thomas Sprayberry.

package/dist/cli.d.ts

@@ -5,10 +5,12 @@
  * Subcommands:
  *   init <syncDir> [--name <machine>]    scaffold ~/.claude-sync/config.json
  *   list                                 list local CC sessions for the cwd
+ *   register [cwd]                       register a cwd's project key (no session needed)
  *   export [session-id] [-o <file>]      pack a session into a .ccsync file
  *   import <file> [--cwd <path>]         install a .ccsync file locally
  *   push [session-id]                    export + ship to configured syncDir
  *   pull                                 import any newer .ccsync files
+ *   watch [session-id] [--interval <s>]  daemon: auto-push changes + auto-pull peers
  *   doctor                               diagnose config + registry health
  *
  * Common flags: --help, --version. No external arg-parser dep — the

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;GAeG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/cli.js

@@ -5,10 +5,12 @@
  * Subcommands:
  *   init <syncDir> [--name <machine>]    scaffold ~/.claude-sync/config.json
  *   list                                 list local CC sessions for the cwd
+ *   register [cwd]                       register a cwd's project key (no session needed)
  *   export [session-id] [-o <file>]      pack a session into a .ccsync file
  *   import <file> [--cwd <path>]         install a .ccsync file locally
  *   push [session-id]                    export + ship to configured syncDir
  *   pull                                 import any newer .ccsync files
+ *   watch [session-id] [--interval <s>]  daemon: auto-push changes + auto-pull peers
  *   doctor                               diagnose config + registry health
  *
  * Common flags: --help, --version. No external arg-parser dep — the
@@ -16,13 +18,13 @@
  * dep budget at zero.
  */
 import { existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { resolve } from 'node:path';
 import { VERSION } from './index.js';
 import { loadConfig, saveConfig, configExists, buildDefaultConfig, } from './config.js';
-import { encodeProjectDir, registerProject, loadRegistry, lookupCwd, claudeProjectsRoot, } from './project.js';
-import { listSessions, readSession, writeSession, assignFreshId, } from './session.js';
+import { encodeProjectDir, registerProject, registerProjectKey, loadRegistry, lookupCwd, claudeProjectsRoot, } from './project.js';
+import { listSessions, listSessionStats, countSessionLines, readSession, writeSession, assignFreshId, } from './session.js';
 import { buildCcsync, readCcsyncFile, writeCcsyncFile, } from './format.js';
-import { pushToTransport, listTransport, listProjectKeys, } from './transport.js';
+import { pushToTransport, listTransport, listTransportMachines, listProjectKeys, } from './transport.js';
 const HELP = `claude-sync ${VERSION}
 
 Usage: claude-sync <command> [options]
@@ -37,6 +39,12 @@ Commands:
       List Claude Code sessions for the current working directory,
       sorted by recency.
 
+  register [cwd]
+      Register a directory's project key so \`pull\` can deliver peers'
+      sessions here — even before this machine has any session of its
+      own. Defaults to the current directory. Run this once on a fresh
+      clone, then \`pull\`.
+
   export [session-id] [-o <file>]
       Pack a session into a portable .ccsync file. Default session-id
       is the most recent one for the current cwd. Default output path
@@ -55,6 +63,14 @@ Commands:
       each into the matching local cwd. Skips sessions that already
       exist locally with the same line count (idempotent re-runs).
 
+  watch [session-id] [--interval <seconds>] [--all] [--once]
+      Run a sync daemon for the current directory: every <interval>
+      seconds (default 10), push the active session whenever it grows
+      and pull any newer sessions from peers. Watches the most-recent
+      session by default; pass a session-id to pin one, or --all to push
+      every changed session in this project. --once runs a single
+      push+pull cycle and exits. Ctrl-C to stop.
+
   doctor
       Print a health report: config, machine name, registered projects,
       Claude Code projects dir, and any obvious mismatches.
@@ -76,10 +92,12 @@ async function main(argv) {
     switch (cmd) {
         case 'init': return cmdInit(rest);
         case 'list': return cmdList(rest);
+        case 'register': return cmdRegister(rest);
         case 'export': return cmdExport(rest);
         case 'import': return cmdImport(rest);
         case 'push': return cmdPush(rest);
         case 'pull': return cmdPull(rest);
+        case 'watch': return cmdWatch(rest);
         case 'doctor': return cmdDoctor(rest);
         default:
             process.stderr.write(`Unknown command: ${cmd}\nRun \`claude-sync --help\` for usage.\n`);
@@ -126,6 +144,26 @@ function cmdList(_args) {
     }
     return 0;
 }
+// ── register ───────────────────────────────────────────────────────
+function cmdRegister(args) {
+    const arg = args[0];
+    const cwd = arg && !arg.startsWith('-') ? resolve(arg) : process.cwd();
+    if (!existsSync(cwd)) {
+        process.stderr.write(`Error: path does not exist: ${cwd}\n`);
+        return 1;
+    }
+    const { key } = registerProject(cwd);
+    const sessions = listSessions(cwd);
+    process.stdout.write(`Registered ${cwd}\n` +
+        `  project key:    ${key}\n` +
+        `  local sessions: ${sessions.length}\n`);
+    if (sessions.length === 0) {
+        process.stdout.write(`\n  No sessions here yet — that's fine. \`pull\` can now deliver peers'\n` +
+            `  work to this directory. \`push\`/\`export\` start working once you've\n` +
+            `  run a Claude Code session in this directory.\n`);
+    }
+    return 0;
+}
 // ── export ─────────────────────────────────────────────────────────
 function cmdExport(args) {
     const cwd = process.cwd();
@@ -164,7 +202,15 @@ function cmdImport(args) {
         return 1;
     }
     const cwdIdx = args.indexOf('--cwd');
-    const explicitCwd = cwdIdx >= 0 ? resolve(args[cwdIdx + 1] ?? '') : null;
+    let explicitCwd = null;
+    if (cwdIdx >= 0) {
+        const cwdArg = args[cwdIdx + 1];
+        if (!cwdArg || cwdArg.startsWith('--')) {
+            process.stderr.write('Error: --cwd requires a path argument.\n');
+            return 1;
+        }
+        explicitCwd = resolve(cwdArg);
+    }
     const overwrite = args.includes('--overwrite');
     const ccsync = readCcsyncFile(filePath);
     return installCcsync(ccsync, explicitCwd, overwrite);
@@ -179,17 +225,7 @@ function cmdPush(args) {
     const session = pickSession(cwd, sessionId);
     if (!session)
         return 1;
-    const { key } = registerProject(cwd);
-    const ccsync = buildCcsync({
-        sessionId: session.id,
-        projectKey: key,
-        originalCwd: cwd,
-        machineName: cfg.machineName,
-        exportedAt: Date.now(),
-        lineCount: session.lineCount,
-        jsonl: readSession(session.path),
-    });
-    const written = pushToTransport(cfg.syncDir, ccsync);
+    const written = exportToTransport(cfg, cwd, session);
     process.stdout.write(`Pushed ${session.id} → ${written}\n`);
     return 0;
 }
@@ -198,25 +234,40 @@ function cmdPull(_args) {
     const cfg = mustLoadConfig();
     if (!cfg)
         return 1;
-    const reg = loadRegistry();
-    const projectKeys = listProjectKeys(cfg.syncDir);
-    if (projectKeys.length === 0) {
+    if (listProjectKeys(cfg.syncDir).length === 0) {
         process.stdout.write(`Nothing to pull — ${cfg.syncDir} is empty.\n`);
         return 0;
     }
+    const { imported, skipped } = runPull(cfg, {
+        onSkip: (msg) => process.stdout.write(`  ${msg}\n`),
+    });
+    process.stdout.write(`\nDone — imported ${imported} session(s), skipped ${skipped}.\n`);
+    return 0;
+}
+/** Core of `pull`, shared with `watch`. Scans the transport across every
+ *  project and imports any session newer (more lines) than the local
+ *  copy. `onSkip` is called with a human message for each transport
+ *  project key that has no resolvable local cwd — `pull` prints them;
+ *  `watch` omits the callback to stay quiet. Genuine imports are always
+ *  announced by `installCcsync` itself. Idempotent: a session already at
+ *  or beyond the transport's line count is skipped, so repeated calls
+ *  (every watch tick) do nothing once converged. */
+function runPull(cfg, opts = {}) {
+    const reg = loadRegistry();
+    const projectKeys = listProjectKeys(cfg.syncDir);
     let imported = 0;
     let skipped = 0;
     for (const encodedKey of projectKeys) {
         // We have the encoded form; find the matching raw key in the registry.
         const rawKey = Object.keys(reg.projects).find((k) => encodeProjectDir(k) === encodedKey);
         if (!rawKey) {
-            process.stdout.write(`  skip ${encodedKey} (no local project registered for this key)\n`);
+            opts.onSkip?.(`skip ${encodedKey} (no local project registered for this key)`);
             skipped++;
             continue;
         }
         const cwd = lookupCwd(rawKey, reg);
         if (!cwd) {
-            process.stdout.write(`  skip ${encodedKey} (registered cwds no longer exist on disk)\n`);
+            opts.onSkip?.(`skip ${encodedKey} (registered cwds no longer exist on disk)`);
             skipped++;
             continue;
         }
@@ -236,9 +287,114 @@ function cmdPull(_args) {
                 imported++;
         }
     }
-    process.stdout.write(`\nDone — imported ${imported} session(s), skipped ${skipped}.\n`);
+    return { imported, skipped };
+}
+// ── watch ──────────────────────────────────────────────────────────
+async function cmdWatch(args) {
+    const cfg = mustLoadConfig();
+    if (!cfg)
+        return 1;
+    const once = args.includes('--once');
+    const pushAll = args.includes('--all');
+    let intervalSec = 10;
+    const intervalIdx = args.indexOf('--interval');
+    if (intervalIdx >= 0) {
+        const v = Number(args[intervalIdx + 1]);
+        if (!Number.isFinite(v) || v < 2) {
+            process.stderr.write('Error: --interval requires a number of seconds >= 2.\n');
+            return 1;
+        }
+        intervalSec = v;
+    }
+    const first = args[0];
+    const sessionId = first && !first.startsWith('-') ? first : undefined;
+    const cwd = process.cwd();
+    // Register up front so a fresh clone with zero sessions can still
+    // RECEIVE peers' work via the pull half of the loop while we watch.
+    const { key } = registerProject(cwd);
+    if (!once) {
+        const pushDesc = sessionId
+            ? `session ${sessionId}`
+            : pushAll ? 'every changed session' : 'most-recent changed session';
+        process.stdout.write(`claude-sync watch — ${cfg.machineName}\n` +
+            `  project:  ${key}\n` +
+            `  cwd:      ${cwd}\n` +
+            `  syncDir:  ${cfg.syncDir}\n` +
+            `  every ${intervalSec}s · push ${pushDesc} · pull all projects\n` +
+            `  Ctrl-C to stop.\n\n`);
+    }
+    // sessionId -> mtimeMs at last push. Seeds empty, so the first tick
+    // pushes the current state once, then only on subsequent growth.
+    const lastPushed = new Map();
+    let stopping = false;
+    const onSignal = () => { stopping = true; };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    try {
+        do {
+            try {
+                watchPushTick(cfg, cwd, { sessionId, pushAll, lastPushed });
+            }
+            catch (err) {
+                process.stderr.write(`  ! push error: ${err instanceof Error ? err.message : err}\n`);
+            }
+            try {
+                runPull(cfg);
+            }
+            catch (err) {
+                process.stderr.write(`  ! pull error: ${err instanceof Error ? err.message : err}\n`);
+            }
+            if (once || stopping)
+                break;
+            await delay(intervalSec * 1000, () => stopping);
+        } while (!stopping);
+    }
+    finally {
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+    }
+    if (!once)
+        process.stdout.write(`\nStopped.\n`);
     return 0;
 }
+/** One push half-cycle for watch: find sessions whose mtime grew since we
+ *  last pushed them and ship each. Uses the stat-only listing (no line
+ *  reads) for change detection, only counting lines for the few that
+ *  actually changed. */
+function watchPushTick(cfg, cwd, state) {
+    const stats = listSessionStats(cwd);
+    let candidates = stats;
+    if (state.sessionId) {
+        candidates = stats.filter((s) => s.id === state.sessionId);
+    }
+    else if (!state.pushAll) {
+        // Default: just the active (most-recent) session. `stats` is mtime-desc.
+        candidates = stats.slice(0, 1);
+    }
+    for (const s of candidates) {
+        const prev = state.lastPushed.get(s.id);
+        if (prev !== undefined && prev >= s.modifiedAt)
+            continue; // unchanged since last push
+        const lineCount = countSessionLines(s.path);
+        exportToTransport(cfg, cwd, { id: s.id, path: s.path, lineCount });
+        state.lastPushed.set(s.id, s.modifiedAt);
+        process.stdout.write(`  ↑ pushed ${s.id} (${lineCount} lines)\n`);
+    }
+}
+/** Resolve after `ms`, or early as soon as `shouldStop()` flips true, so
+ *  Ctrl-C interrupts the inter-tick sleep without waiting out the
+ *  interval. Polls a coarse 200ms so a `watch` process doesn't busy-spin. */
+function delay(ms, shouldStop) {
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const id = setInterval(() => {
+            if (shouldStop() || Date.now() - start >= ms) {
+                clearInterval(id);
+                resolve();
+            }
+        }, 200);
+    });
+}
 // ── doctor ─────────────────────────────────────────────────────────
 function cmdDoctor(_args) {
     const ok = (m) => { process.stdout.write(`  ✓ ${m}\n`); };
@@ -247,8 +403,29 @@ function cmdDoctor(_args) {
     if (configExists()) {
         const cfg = loadConfig();
         ok(`config: ${cfg.machineName} → ${cfg.syncDir}`);
-        if (!existsSync(cfg.syncDir))
+        if (!existsSync(cfg.syncDir)) {
             warn(`syncDir does not exist: ${cfg.syncDir}`);
+        }
+        else {
+            // Duplicate-machineName footgun: pull self-filters files whose
+            // machineName matches ours, so if every file in the transport
+            // carries this machine's name (two machines sharing a hostname),
+            // pull silently imports nothing.
+            const machines = listTransportMachines(cfg.syncDir);
+            const total = [...machines.values()].reduce((acc, n) => acc + n, 0);
+            if (total > 0) {
+                const peers = [...machines.keys()].filter((m) => m !== cfg.machineName);
+                if (peers.length === 0) {
+                    warn(`all ${total} file(s) in the transport use machineName "${cfg.machineName}" — ` +
+                        `the same as this machine. \`pull\` self-filters these, so it imports nothing. ` +
+                        `Give each machine a distinct name: re-run \`init --name <name>\` on a fresh ` +
+                        `machine, or edit machineName in ~/.claude-sync/config.json.`);
+                }
+                else {
+                    ok(`transport peers: ${peers.sort().join(', ')} (${total} file(s) total)`);
+                }
+            }
+        }
     }
     else {
         warn(`no config (run \`claude-sync init <syncDir>\`)`);
@@ -278,6 +455,23 @@ function mustLoadConfig() {
     }
     return loadConfig();
 }
+/** Build a `.ccsync` for `session` (in `cwd`) and write it to the
+ *  configured transport, returning the written path. Registers the cwd's
+ *  project key as a side effect, so pushing from a never-before-seen
+ *  directory self-registers. Shared by `push` and `watch`. */
+function exportToTransport(cfg, cwd, session) {
+    const { key } = registerProject(cwd);
+    const ccsync = buildCcsync({
+        sessionId: session.id,
+        projectKey: key,
+        originalCwd: cwd,
+        machineName: cfg.machineName,
+        exportedAt: Date.now(),
+        lineCount: session.lineCount,
+        jsonl: readSession(session.path),
+    });
+    return pushToTransport(cfg.syncDir, ccsync);
+}
 function pickSession(cwd, requestedId) {
     const sessions = listSessions(cwd);
     if (sessions.length === 0) {
@@ -313,6 +507,11 @@ function installCcsync(ccsync, explicitCwd, overwrite) {
     }
     try {
         const writtenTo = writeSession(targetCwd, sessionId, ccsync.jsonl, { overwrite });
+        // Bind the peer's project key to this local cwd so a later `pull`
+        // resolves it without a manual --cwd. This closes the first-contact
+        // gap: `import <file> --cwd <path>` now leaves the project registered.
+        // Idempotent — `pull` re-imports already register via this path too.
+        registerProjectKey(ccsync.projectKey, targetCwd);
         process.stdout.write(`Imported ${sessionId} from ${ccsync.machineName} → ${writtenTo}\n` +
             `  (${ccsync.lineCount} lines, project: ${ccsync.projectKey})\n`);
         return 0;
@@ -329,8 +528,6 @@ function formatBytes(n) {
         return `${(n / 1024).toFixed(1)} KB`;
     return `${(n / 1024 / 1024).toFixed(1)} MB`;
 }
-// We accept basename in some args; suppress unused-import warnings.
-void basename;
 main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
     process.stderr.write(`claude-sync: ${err.message}\n`);
     process.exit(1);