dsh-p2p-sync 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# dsh-p2p-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.
+Direct, serverless peer-to-peer TCP synchronization plugin for [DeepSeek Harness (DSH)](https://deepseek-ai.github.io/dsh/).
+
+Keeps two DSH installs (such as an Android phone and a laptop) in sync directly over TCP without cloud storage, coordinators, or relays.
+
+---
+
+## Installation
+
+### From NPM
+
+```bash
+pnpm add dsh-p2p-sync
+# or
+npm install dsh-p2p-sync
+```
+
+### Local Development / npm link
+
+To link and develop locally:
+
+```bash
+cd dsh-p2p-sync
+npm link
+# in your DSH profile directory:
+npm link dsh-p2p-sync
+```
+
+---
+
+## DSH Bundle Configuration
+
+Add the plugin to your profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: p2p-sync
+      name: 'dsh-p2p-sync'
+      config:
+        port: 7421
+        sharedSecret: 'your-shared-secret'
+        peers:
+          - '100.64.0.2:7421' # e.g. Tailscale or LAN IP
+        intervalMs: 300000     # auto-sync every 5 mins (0 to disable)
+```
+
+---
+
+## Tools
+
+Once loaded, the plugin registers four tools on your DSH agent:
+
+| Tool | Parameters | Description |
+|---|---|---|
+| `sync_status` | *(none)* | View local device ID, peers, sync status, and pending conflict backups. |
+| `sync_now` | `{ peer?: string, dryRun?: boolean }` | Trigger an immediate sync round (use `dryRun: true` to preview changes). |
+| `sync_peers` | `{ action: "list"\|"add"\|"remove", peer?: string }` | List, add, or remove peer addresses at runtime. |
+| `sync_pending` | `{ peer?: string }` | Inspect sessions and configs that differ right now without applying changes. |
+
+---
+
+## How It Works
+
+- **Sessions (`session.v4.jsonl.zstd`)**: Append-only replication tracking high-water sequence marks. Strict contiguity checking prevents gaps. If both devices edit the same session offline, the higher device ID automatically renames its copy to `<id>-fork-<device8>` so zero data is lost.
+- **Config & Preferences**: Reconciled using a Hybrid Logical Clock (HLC) with Last-Write-Wins (LWW). Overwritten local configs are backed up under `sync-state/conflicts/`.
+- **Wire Security**: Peer connections authenticate via an HMAC-SHA256 handshake over exchanged random nonces.
+- **Exclusions**: Secrets (`.credentials.yaml`), machine binaries (`node_modules/`), and runtime state logs are never transmitted.
+
+---
+
+## Testing
+
+```bash
+node --test test/*.mjs
+```

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: p2p-sync
+      name: 'dsh-p2p-sync'
+      config: {}

package/lib/hlc.js

@@ -0,0 +1,74 @@
+export class HLC {
+  constructor(deviceId) {
+    if (!deviceId) {
+      throw new Error('HLC requires a non-empty deviceId');
+    }
+    this.deviceId = deviceId;
+    this.millis = 0;
+    this.counter = 0;
+  }
+
+  static pack(millis, counter, device) {
+    const mStr = String(millis).padStart(16, '0');
+    const cStr = Number(counter).toString(16).padStart(8, '0');
+    return `${mStr}${cStr}:${device}`;
+  }
+
+  static unpack(versionStr) {
+    if (typeof versionStr !== 'string') {
+      throw new Error('Version must be a string');
+    }
+    const colonIdx = versionStr.indexOf(':');
+    if (colonIdx === -1) {
+      throw new Error(`Invalid HLC version string: ${versionStr}`);
+    }
+    const timePart = versionStr.slice(0, colonIdx);
+    const device = versionStr.slice(colonIdx + 1);
+
+    if (timePart.length < 24) {
+      throw new Error(`Invalid HLC timestamp length: ${timePart}`);
+    }
+    const millis = parseInt(timePart.slice(0, 16), 10);
+    const counter = parseInt(timePart.slice(16, 24), 16);
+
+    return { millis, counter, device };
+  }
+
+  static compare(v1, v2) {
+    if (v1 === v2) return 0;
+    return v1 < v2 ? -1 : 1;
+  }
+
+  pack() {
+    return HLC.pack(this.millis, this.counter, this.deviceId);
+  }
+
+  now() {
+    const physical = Date.now();
+    if (physical > this.millis) {
+      this.millis = physical;
+      this.counter = 0;
+    } else {
+      this.counter++;
+    }
+    return this.pack();
+  }
+
+  observe(remoteVersionStr) {
+    const remote = HLC.unpack(remoteVersionStr);
+    const physical = Date.now();
+    const maxMillis = Math.max(physical, this.millis, remote.millis);
+
+    if (maxMillis === this.millis && maxMillis === remote.millis) {
+      this.counter = Math.max(this.counter, remote.counter) + 1;
+    } else if (maxMillis === this.millis) {
+      this.counter++;
+    } else if (maxMillis === remote.millis) {
+      this.counter = remote.counter + 1;
+    } else {
+      this.counter = 0;
+    }
+    this.millis = maxMillis;
+    return this.pack();
+  }
+}

package/lib/index.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { LocalReplica } from './local.js';
+import { PeerManager } from './peer.js';
+
+export const name = 'dsh-p2p-sync';
+export const inject = ['web'];
+
+export const Config = z.object({
+  port: z.number().default(7421).description('TCP listening port for P2P sync (default 7421)'),
+  peers: z.array(z.string()).default([]).description('Configured peer addresses (host:port or host)'),
+  sharedSecret: z.string().default('').description('Shared secret for HMAC-SHA256 peer authentication'),
+  intervalMs: z.number().default(0).description('Background loop interval in ms (0 = disabled)'),
+  dshHome: z.string().default('').description('Path to DSH home directory (defaults to DSH_HOME env var)'),
+  syncProjectDir: z.boolean().default(false).description('Sync working project directory (default false)'),
+});
+
+export async function apply(ctx, config = {}) {
+  const dshHome = config.dshHome || process.env.DSH_HOME || process.cwd();
+  const localReplica = new LocalReplica(dshHome);
+  await localReplica.init();
+
+  const peerManager = new PeerManager(localReplica, {
+    port: config.port ?? 7421,
+    peers: config.peers ?? [],
+    sharedSecret: config.sharedSecret ?? '',
+    intervalMs: config.intervalMs ?? 0,
+  });
+
+  await peerManager.start();
+
+  if (typeof ctx?.on === 'function') {
+    ctx.on('dispose', async () => {
+      await peerManager.stop();
+    });
+  }
+
+  const toolDefs = [
+    {
+      name: 'sync_status',
+      description: 'Report peers, last round result, per-session high-water marks, and pending conflicts.',
+      parameters: { type: 'object', properties: {} },
+      async execute() {
+        const manifest = await localReplica.getManifest();
+        const mgrStatus = peerManager.getStatus();
+
+        const conflictDir = path.join(dshHome, 'sync-state', 'conflicts');
+        const conflicts = fs.existsSync(conflictDir)
+          ? fs.readdirSync(conflictDir)
+          : [];
+
+        return {
+          deviceId: localReplica.deviceId,
+          port: mgrStatus.port,
+          peers: mgrStatus.peers,
+          peerStatus: mgrStatus.peerStatus,
+          activeSyncs: mgrStatus.activeSyncs,
+          sessions: manifest.sessions,
+          configs: manifest.configs,
+          conflicts,
+        };
+      },
+    },
+    {
+      name: 'sync_now',
+      description: 'Force a sync round with a peer (or all peers); supports dryRun returning what would move.',
+      parameters: {
+        type: 'object',
+        properties: {
+          peer: { type: 'string', description: 'Peer address (host:port or host). If omitted, syncs with all peers.' },
+          dryRun: { type: 'boolean', description: 'If true, simulates the sync and reports what would move.' },
+        },
+      },
+      async execute(args = {}) {
+        const targets = args.peer ? [args.peer] : peerManager.peers;
+        if (targets.length === 0) {
+          return { message: 'No peers configured to sync with' };
+        }
+
+        const results = {};
+        for (const target of targets) {
+          try {
+            results[target] = await peerManager.syncPeer(target, { dryRun: !!args.dryRun });
+          } catch (err) {
+            results[target] = { error: err.message };
+          }
+        }
+        return results;
+      },
+    },
+    {
+      name: 'sync_peers',
+      description: 'List, add, or remove configured sync peers.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'add', 'remove'] },
+          peer: { type: 'string', description: 'Peer address to add or remove' },
+        },
+      },
+      async execute(args = {}) {
+        const action = args.action || 'list';
+        if (action === 'add' && args.peer) {
+          const norm = args.peer.trim();
+          if (!peerManager.peers.includes(norm)) {
+            peerManager.peers.push(norm);
+          }
+        } else if (action === 'remove' && args.peer) {
+          const norm = args.peer.trim();
+          peerManager.peers = peerManager.peers.filter((p) => p !== norm);
+        }
+        return { peers: peerManager.peers };
+      },
+    },
+    {
+      name: 'sync_pending',
+      description: 'Inspect sessions and configs that differ right now by performing a dryRun comparison with peer.',
+      parameters: {
+        type: 'object',
+        properties: {
+          peer: { type: 'string', description: 'Peer address to check against' },
+        },
+      },
+      async execute(args = {}) {
+        const target = args.peer || peerManager.peers[0];
+        if (!target) {
+          return { error: 'No peer specified or configured' };
+        }
+        try {
+          return await peerManager.syncPeer(target, { dryRun: true });
+        } catch (err) {
+          return { error: err.message };
+        }
+      },
+    },
+  ];
+
+  for (const t of toolDefs) {
+    if (ctx?.tools?.register) {
+      ctx.tools.register(t);
+    }
+    // Also bind directly to ctx for direct access
+    if (ctx) {
+      ctx[t.name] = t.execute;
+    }
+  }
+
+  return {
+    name,
+    localReplica,
+    peerManager,
+    tools: toolDefs,
+    async stop() {
+      await peerManager.stop();
+    },
+  };
+}
+
+Object.defineProperty(apply, 'name', { value: name, configurable: true });
+export default Object.assign(apply, { Config, inject });

package/lib/local.js

@@ -0,0 +1,271 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { HLC } from './hlc.js';
+import {
+  decodeSessionLog,
+  encodeSessionLog,
+  appendEventsToBuffer,
+} from './sessionlog.js';
+import {
+  isExcludedPath,
+  atomicWriteFile,
+  stashConflictFile,
+  hashBuffer,
+} from './replica.js';
+
+export class LocalReplica {
+  constructor(homeDir, deviceId) {
+    this.homeDir = path.resolve(homeDir);
+    this.customDeviceId = deviceId;
+    this.deviceId = null;
+    this.hlc = null;
+    this.versions = {};
+  }
+
+  async init() {
+    const syncStateDir = path.join(this.homeDir, 'sync-state');
+    fs.mkdirSync(syncStateDir, { recursive: true });
+
+    const deviceIdFile = path.join(syncStateDir, 'device-id');
+    if (this.customDeviceId) {
+      this.deviceId = this.customDeviceId;
+      fs.writeFileSync(deviceIdFile, this.deviceId, 'utf8');
+    } else if (fs.existsSync(deviceIdFile)) {
+      this.deviceId = fs.readFileSync(deviceIdFile, 'utf8').trim();
+    } else {
+      this.deviceId = crypto.randomBytes(16).toString('hex');
+      fs.writeFileSync(deviceIdFile, this.deviceId, 'utf8');
+    }
+
+    this.hlc = new HLC(this.deviceId);
+
+    const versionsFile = path.join(syncStateDir, 'versions.json');
+    if (fs.existsSync(versionsFile)) {
+      try {
+        this.versions = JSON.parse(fs.readFileSync(versionsFile, 'utf8'));
+      } catch {
+        this.versions = {};
+      }
+    }
+  }
+
+  _saveVersions() {
+    const versionsFile = path.join(this.homeDir, 'sync-state', 'versions.json');
+    atomicWriteFile(versionsFile, Buffer.from(JSON.stringify(this.versions, null, 2), 'utf8'));
+  }
+
+  async getManifest() {
+    const sessions = {};
+    const configs = {};
+
+    // 1. Scan sessions: sessions/<projectKey>/<sessionId>/session.v4.jsonl.zstd
+    const sessionsDir = path.join(this.homeDir, 'sessions');
+    if (fs.existsSync(sessionsDir)) {
+      const projectDirs = fs.readdirSync(sessionsDir, { withFileTypes: true });
+      for (const pDir of projectDirs) {
+        if (!pDir.isDirectory()) continue;
+        const projectKey = pDir.name;
+        const fullProjPath = path.join(sessionsDir, projectKey);
+        const sessionDirs = fs.readdirSync(fullProjPath, { withFileTypes: true });
+
+        for (const sDir of sessionDirs) {
+          if (!sDir.isDirectory()) continue;
+          const sessionId = sDir.name;
+          const fullSessionDir = path.join(fullProjPath, sessionId);
+          const logFile = path.join(fullSessionDir, 'session.v4.jsonl.zstd');
+          const lockFile = path.join(fullSessionDir, 'session.lock');
+
+          if (!fs.existsSync(logFile)) continue;
+
+          const isLocked = fs.existsSync(lockFile);
+          const key = `${projectKey}/${sessionId}`;
+
+          try {
+            const buf = fs.readFileSync(logFile);
+            const decoded = decodeSessionLog(buf);
+            sessions[key] = {
+              seq: decoded.maxSeq,
+              sha: decoded.sha256,
+              size: buf.length,
+              locked: isLocked,
+            };
+          } catch (err) {
+            // If corrupt or unable to read, record with locked or skip
+            sessions[key] = {
+              seq: -1,
+              sha: '',
+              size: 0,
+              locked: true,
+              error: err.message,
+            };
+          }
+        }
+      }
+    }
+
+    // 2. Scan configs
+    const candidateFiles = [];
+
+    // profiles/*/package.json and cordis.patch.yml
+    const profilesDir = path.join(this.homeDir, 'profiles');
+    if (fs.existsSync(profilesDir)) {
+      const profEntries = fs.readdirSync(profilesDir, { withFileTypes: true });
+      for (const p of profEntries) {
+        if (!p.isDirectory() || p.name === 'node_modules') continue;
+        const pkgJson = path.join('profiles', p.name, 'package.json');
+        const cordisYml = path.join('profiles', p.name, 'cordis.patch.yml');
+        candidateFiles.push(pkgJson, cordisYml);
+      }
+    }
+
+    candidateFiles.push(
+      path.join('android', 'extensions-state.json'),
+      path.join('datastore', 'settings.preferences_pb')
+    );
+
+    let versionsChanged = false;
+
+    for (const rel of candidateFiles) {
+      if (isExcludedPath(rel)) continue;
+      const fullPath = path.join(this.homeDir, rel);
+      if (!fs.existsSync(fullPath)) continue;
+
+      const stat = fs.statSync(fullPath);
+      if (!stat.isFile()) continue;
+
+      const buf = fs.readFileSync(fullPath);
+      const sha = hashBuffer(buf);
+
+      let version = this.versions[rel]?.version;
+      if (!version || this.versions[rel]?.sha !== sha) {
+        version = this.hlc.now();
+        this.versions[rel] = { version, sha };
+        versionsChanged = true;
+      }
+
+      configs[rel.replace(/\\/g, '/')] = {
+        version,
+        sha,
+        size: buf.length,
+      };
+    }
+
+    if (versionsChanged) {
+      this._saveVersions();
+    }
+
+    return { sessions, configs };
+  }
+
+  async serveSession(key, fromSeq = 0) {
+    const logFile = path.join(this.homeDir, 'sessions', key, 'session.v4.jsonl.zstd');
+    const lockFile = path.join(this.homeDir, 'sessions', key, 'session.lock');
+
+    if (fs.existsSync(lockFile)) {
+      return { key, locked: true };
+    }
+
+    if (!fs.existsSync(logFile)) {
+      throw new Error(`Session log not found: ${key}`);
+    }
+
+    const buf = fs.readFileSync(logFile);
+    const decoded = decodeSessionLog(buf);
+
+    if (fromSeq === 0) {
+      return {
+        key,
+        header: decoded.header,
+        events: decoded.events,
+        sha: decoded.sha256,
+      };
+    }
+
+    return {
+      key,
+      events: decoded.events.filter((e) => e.seq >= fromSeq),
+      sha: decoded.sha256,
+    };
+  }
+
+  async serveConfig(relPath) {
+    if (isExcludedPath(relPath)) {
+      throw new Error(`Attempt to serve excluded config: ${relPath}`);
+    }
+    const fullPath = path.join(this.homeDir, relPath);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Config file not found: ${relPath}`);
+    }
+
+    const buf = fs.readFileSync(fullPath);
+    const sha = hashBuffer(buf);
+    const version = this.versions[relPath]?.version || this.hlc.now();
+
+    return {
+      relPath: relPath.replace(/\\/g, '/'),
+      version,
+      contentBase64: buf.toString('base64'),
+      sha,
+    };
+  }
+
+  async applyFork(key, forkedKey) {
+    const oldLog = path.join(this.homeDir, 'sessions', key, 'session.v4.jsonl.zstd');
+    const newDir = path.join(this.homeDir, 'sessions', forkedKey);
+    const newLog = path.join(newDir, 'session.v4.jsonl.zstd');
+
+    if (fs.existsSync(oldLog)) {
+      fs.mkdirSync(newDir, { recursive: true });
+      fs.renameSync(oldLog, newLog);
+    }
+  }
+
+  async applySession(item) {
+    const sessionDir = path.join(this.homeDir, 'sessions', item.key);
+    const lockFile = path.join(sessionDir, 'session.lock');
+    if (fs.existsSync(lockFile)) {
+      return; // Skip locked session
+    }
+
+    const logFile = path.join(sessionDir, 'session.v4.jsonl.zstd');
+
+    if (item.header) {
+      // Full log
+      const buf = encodeSessionLog(item.header, item.events || []);
+      atomicWriteFile(logFile, buf);
+    } else if (item.events && item.events.length > 0) {
+      // Incremental append
+      if (!fs.existsSync(logFile)) {
+        throw new Error(`Cannot append to non-existent session ${item.key}`);
+      }
+      const existingBuf = fs.readFileSync(logFile);
+      const res = appendEventsToBuffer(existingBuf, item.events);
+      atomicWriteFile(logFile, res.buffer);
+    }
+  }
+
+  async applyConfig(item) {
+    if (isExcludedPath(item.relPath)) {
+      throw new Error(`Attempt to apply excluded path: ${item.relPath}`);
+    }
+
+    const fullPath = path.join(this.homeDir, item.relPath);
+    const buf = Buffer.from(item.contentBase64, 'base64');
+    const computedSha = hashBuffer(buf);
+
+    if (computedSha !== item.sha) {
+      throw new Error(`Corrupt payload: sha mismatch for ${item.relPath}`);
+    }
+
+    if (item.stash && fs.existsSync(fullPath)) {
+      const device = HLC.unpack(item.version).device;
+      stashConflictFile(this.homeDir, item.relPath, device, Date.now());
+    }
+
+    atomicWriteFile(fullPath, buf);
+    this.versions[item.relPath] = { version: item.version, sha: item.sha };
+    this.hlc.observe(item.version);
+    this._saveVersions();
+  }
+}

package/lib/merge.js

@@ -0,0 +1,126 @@
+import { HLC } from './hlc.js';
+
+export function planSessions(localSessions = {}, remoteSessions = {}, localDeviceId, remoteDeviceId) {
+  const wants = [];
+  const forks = [];
+  const allKeys = new Set([...Object.keys(localSessions), ...Object.keys(remoteSessions)]);
+
+  for (const key of allKeys) {
+    const local = localSessions[key];
+    const remote = remoteSessions[key];
+
+    // Concurrency safety: check session.lock before touching a session
+    if (local?.locked || remote?.locked) {
+      continue;
+    }
+
+    if (!local && remote) {
+      // Absent locally -> pull full log from 0
+      wants.push({ key, from: 0 });
+      continue;
+    }
+
+    if (local && !remote) {
+      // Present locally, absent remotely -> peer will pull
+      continue;
+    }
+
+    // Both present
+    if (local.seq === remote.seq) {
+      if (local.sha === remote.sha) {
+        // In sync
+        continue;
+      }
+
+      // Equal seq, different sha -> true divergence -> fork
+      if (localDeviceId > remoteDeviceId) {
+        const device8 = localDeviceId.slice(0, 8);
+        const slashIdx = key.indexOf('/');
+        const projectKey = slashIdx !== -1 ? key.slice(0, slashIdx) : '.';
+        const sessionId = slashIdx !== -1 ? key.slice(slashIdx + 1) : key;
+        const forkedKey = `${projectKey}/${sessionId}-fork-${device8}`;
+
+        forks.push({ key, forkedKey });
+        // Do not pull peer's original in the same round you rename
+      }
+      // If remote has greater device ID, remote renames its copy, we keep canonical, no pull this round
+      continue;
+    }
+
+    if (local.seq < remote.seq) {
+      // Pull seq > local
+      wants.push({ key, from: local.seq + 1 });
+      continue;
+    }
+
+    if (local.seq > remote.seq) {
+      // Peer will pull
+      continue;
+    }
+  }
+
+  return { wants, forks };
+}
+
+export function planConfigs(localConfigs = {}, remoteConfigs = {}) {
+  const wants = [];
+  const stashes = [];
+  const metadataUpdates = [];
+  const allKeys = new Set([...Object.keys(localConfigs), ...Object.keys(remoteConfigs)]);
+
+  for (const relPath of allKeys) {
+    const local = localConfigs[relPath];
+    const remote = remoteConfigs[relPath];
+
+    if (!local && remote) {
+      wants.push(relPath);
+      continue;
+    }
+
+    if (local && !remote) {
+      // Peer will pull
+      continue;
+    }
+
+    // Both present
+    const comp = HLC.compare(remote.version, local.version);
+
+    if (comp > 0) {
+      // Remote version is higher (LWW)
+      if (remote.sha !== local.sha) {
+        wants.push(relPath);
+        stashes.push({
+          relPath,
+          remoteVersion: remote.version,
+          remoteSha: remote.sha,
+        });
+      } else {
+        metadataUpdates.push({ relPath, version: remote.version });
+      }
+      continue;
+    }
+
+    if (comp < 0) {
+      // Local version is higher -> peer will pull
+      continue;
+    }
+
+    // comp === 0: equal versions
+    if (remote.sha === local.sha) {
+      // Identical
+      continue;
+    }
+
+    // Equal versions with different content: break tie on sha
+    if (remote.sha > local.sha) {
+      wants.push(relPath);
+      stashes.push({
+        relPath,
+        remoteVersion: remote.version,
+        remoteSha: remote.sha,
+      });
+    }
+  }
+
+  return { wants, stashes, metadataUpdates };
+}

package/lib/peer.js

@@ -0,0 +1,182 @@
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { Channel } from './wire.js';
+import { executeSyncRound } from './sync.js';
+
+export async function authenticateHandshake(channel, sharedSecret) {
+  if (!sharedSecret) {
+    return true;
+  }
+
+  const localNonce = crypto.randomBytes(32).toString('hex');
+  await channel.send({ type: 'auth-challenge', nonce: localNonce });
+
+  const remoteChallenge = await channel.receive('auth-challenge');
+  const remoteNonce = remoteChallenge.nonce;
+
+  const proof = crypto
+    .createHmac('sha256', sharedSecret)
+    .update(localNonce + remoteNonce)
+    .digest('hex');
+
+  const expectedRemoteProof = crypto
+    .createHmac('sha256', sharedSecret)
+    .update(remoteNonce + localNonce)
+    .digest('hex');
+
+  await channel.send({ type: 'auth-response', proof });
+
+  const remoteResponse = await channel.receive('auth-response');
+  if (remoteResponse.proof !== expectedRemoteProof) {
+    throw new Error('Authentication failed: proof mismatch');
+  }
+
+  return true;
+}
+
+export function parsePeerAddress(peerStr, defaultPort = 7421) {
+  const str = peerStr.trim();
+  const colonIdx = str.lastIndexOf(':');
+  if (colonIdx === -1) {
+    return { host: str, port: defaultPort };
+  }
+  const host = str.slice(0, colonIdx);
+  const port = parseInt(str.slice(colonIdx + 1), 10);
+  return { host, port: Number.isNaN(port) ? defaultPort : port };
+}
+
+export class PeerManager {
+  constructor(localReplica, config = {}) {
+    this.localReplica = localReplica;
+    this.port = config.port || 7421;
+    this.peers = Array.isArray(config.peers) ? [...config.peers] : [];
+    this.sharedSecret = config.sharedSecret || '';
+    this.intervalMs = config.intervalMs || 0;
+    this.server = null;
+    this.timer = null;
+    this.activeSyncs = new Set();
+    this.peerStatus = new Map();
+  }
+
+  async start() {
+    await this.startListener();
+    if (this.intervalMs > 0) {
+      this.timer = setInterval(() => {
+        this.runScheduledRound().catch(() => {});
+      }, this.intervalMs);
+    }
+  }
+
+  async stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.server) {
+      await new Promise((resolve) => this.server.close(resolve));
+      this.server = null;
+    }
+  }
+
+  async startListener() {
+    return new Promise((resolve, reject) => {
+      const srv = net.createServer(async (socket) => {
+        const remoteAddr = `${socket.remoteAddress}:${socket.remotePort}`;
+        const channel = new Channel(socket);
+        try {
+          await authenticateHandshake(channel, this.sharedSecret);
+          await executeSyncRound(channel, this.localReplica);
+        } catch {
+          // Socket error or sync fail
+        } finally {
+          channel.close();
+        }
+      });
+
+      srv.on('error', (err) => {
+        reject(err);
+      });
+
+      srv.listen(this.port, () => {
+        this.server = srv;
+        resolve();
+      });
+    });
+  }
+
+  async syncPeer(peerStr, opts = {}) {
+    const norm = peerStr.trim();
+    if (this.activeSyncs.has(norm)) {
+      return { skipped: 'concurrent_sync_in_progress' };
+    }
+
+    this.activeSyncs.add(norm);
+    const { host, port } = parsePeerAddress(norm, this.port);
+
+    try {
+      const socket = await new Promise((resolve, reject) => {
+        const s = net.connect({ host, port }, () => resolve(s));
+        s.once('error', reject);
+      });
+
+      const channel = new Channel(socket);
+      try {
+        await authenticateHandshake(channel, this.sharedSecret);
+        const result = await executeSyncRound(channel, this.localReplica, opts);
+
+        const status = this.peerStatus.get(norm) || {};
+        this.peerStatus.set(norm, {
+          ...status,
+          lastSuccess: Date.now(),
+          lastError: null,
+          backoffMs: 1000,
+        });
+
+        return result;
+      } finally {
+        channel.close();
+      }
+    } catch (err) {
+      const status = this.peerStatus.get(norm) || {};
+      const nextBackoff = Math.min((status.backoffMs || 1000) * 2, 60000);
+      this.peerStatus.set(norm, {
+        ...status,
+        lastError: err.message,
+        lastFailure: Date.now(),
+        backoffMs: nextBackoff,
+      });
+      throw err;
+    } finally {
+      this.activeSyncs.delete(norm);
+    }
+  }
+
+  async runScheduledRound() {
+    const now = Date.now();
+    for (const peer of this.peers) {
+      const status = this.peerStatus.get(peer);
+      if (status?.lastFailure && status?.backoffMs) {
+        if (now - status.lastFailure < status.backoffMs) {
+          continue; // In backoff period
+        }
+      }
+      this.syncPeer(peer).catch(() => {});
+    }
+  }
+
+  getStatus() {
+    const peerStatuses = {};
+    for (const peer of this.peers) {
+      peerStatuses[peer] = this.peerStatus.get(peer) || {
+        lastSuccess: null,
+        lastError: null,
+      };
+    }
+    return {
+      port: this.port,
+      peers: this.peers,
+      activeSyncs: Array.from(this.activeSyncs),
+      peerStatus: peerStatuses,
+    };
+  }
+}

package/lib/replica.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export function isExcludedPath(relPath) {
+  const norm = relPath.replace(/\\/g, '/');
+
+  if (norm === '.credentials.yaml' || norm.endsWith('/.credentials.yaml')) return true;
+  if (norm.includes('node_modules')) return true;
+  if (norm === 'android/app-layer.patch.yml') return true;
+  if (norm === 'android/budget.json') return true;
+  if (norm === 'android/boot-journal.json') return true;
+  if (norm === 'android/pnpm-report.jsonl') return true;
+  if (norm.startsWith('logs/') || norm.includes('/logs/')) return true;
+  if (norm.startsWith('storages/session_projcache/') || norm.includes('/storages/session_projcache/')) return true;
+  if (norm.endsWith('session.lock')) return true;
+
+  return false;
+}
+
+export function atomicWriteFile(targetPath, buffer) {
+  const dir = path.dirname(targetPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tmpPath = `${targetPath}.${process.pid}.${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`;
+  fs.writeFileSync(tmpPath, buffer);
+  fs.renameSync(tmpPath, targetPath);
+}
+
+export function stashConflictFile(homeDir, relPath, device = 'remote', stamp = Date.now()) {
+  const sourcePath = path.join(homeDir, relPath);
+  if (!fs.existsSync(sourcePath)) {
+    return null;
+  }
+
+  const safeName = relPath.replace(/[/\\]/g, '_');
+  const conflictDir = path.join(homeDir, 'sync-state', 'conflicts');
+  fs.mkdirSync(conflictDir, { recursive: true });
+
+  const destPath = path.join(conflictDir, `${safeName}.${device}.${stamp}.bak`);
+  fs.copyFileSync(sourcePath, destPath);
+  return destPath;
+}
+
+export function hashBuffer(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}

package/lib/sessionlog.js

@@ -0,0 +1,87 @@
+import { zstdCompressSync, zstdDecompressSync } from 'node:zlib';
+import { createHash } from 'node:crypto';
+
+export class SessionLogContiguityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SessionLogContiguityError';
+  }
+}
+
+export function hashBuffer(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export function validateEventContiguity(events, expectedStartSeq = 0) {
+  for (let i = 0; i < events.length; i++) {
+    const expected = expectedStartSeq + i;
+    if (events[i].seq !== expected) {
+      throw new SessionLogContiguityError(
+        `Non-contiguous event seq: expected ${expected}, got ${events[i].seq}`
+      );
+    }
+  }
+}
+
+export function encodeSessionLog(header, events = []) {
+  validateEventContiguity(events, 0);
+  const lines = [JSON.stringify(header)];
+  for (const ev of events) {
+    lines.push(JSON.stringify(ev));
+  }
+  const payload = Buffer.from(lines.join('\n') + '\n', 'utf8');
+  return zstdCompressSync(payload);
+}
+
+export function decodeSessionLog(compressedBuffer) {
+  const decompressed = zstdDecompressSync(compressedBuffer);
+  const text = decompressed.toString('utf8');
+  const rawLines = text.split('\n').filter((line) => line.trim().length > 0);
+  if (rawLines.length === 0) {
+    throw new Error('Empty session log');
+  }
+
+  const header = JSON.parse(rawLines[0]);
+  const events = [];
+  for (let i = 1; i < rawLines.length; i++) {
+    events.push(JSON.parse(rawLines[i]));
+  }
+
+  validateEventContiguity(events, 0);
+
+  const maxSeq = events.length > 0 ? events[events.length - 1].seq : -1;
+  const sha256 = hashBuffer(compressedBuffer);
+
+  return {
+    header,
+    events,
+    maxSeq,
+    sha256,
+    uncompressedBytes: decompressed.length,
+  };
+}
+
+export function appendEventsToBuffer(existingCompressedBuffer, newEvents) {
+  if (!newEvents || newEvents.length === 0) {
+    return {
+      buffer: existingCompressedBuffer,
+      maxSeq: decodeSessionLog(existingCompressedBuffer).maxSeq,
+      sha256: hashBuffer(existingCompressedBuffer),
+    };
+  }
+
+  const decoded = decodeSessionLog(existingCompressedBuffer);
+  const expectedStart = decoded.maxSeq + 1;
+  validateEventContiguity(newEvents, expectedStart);
+
+  const combinedEvents = [...decoded.events, ...newEvents];
+  const buffer = encodeSessionLog(decoded.header, combinedEvents);
+  const maxSeq = combinedEvents[combinedEvents.length - 1].seq;
+  const sha256 = hashBuffer(buffer);
+
+  return {
+    buffer,
+    maxSeq,
+    sha256,
+  };
+}

package/lib/sync.js

@@ -0,0 +1,119 @@
+import { planSessions, planConfigs } from './merge.js';
+
+export async function executeSyncRound(channel, localReplica, opts = {}) {
+  // 1. Hello
+  await channel.send({
+    type: 'hello',
+    protocol: 'dsh-p2p-v1',
+    deviceId: localReplica.deviceId,
+    label: opts.label || '',
+  });
+
+  const remoteHello = await channel.receive('hello');
+  if (remoteHello.protocol !== 'dsh-p2p-v1') {
+    throw new Error(`Protocol mismatch: expected dsh-p2p-v1, got ${remoteHello.protocol}`);
+  }
+  if (remoteHello.deviceId === localReplica.deviceId) {
+    throw new Error('Cannot sync with self: identical deviceId');
+  }
+
+  // 2. Manifest
+  const localManifest = await localReplica.getManifest();
+  await channel.send({
+    type: 'manifest',
+    sessions: localManifest.sessions,
+    configs: localManifest.configs,
+  });
+
+  const remoteManifest = await channel.receive('manifest');
+
+  // 3. Wants
+  const sessionPlan = planSessions(
+    localManifest.sessions,
+    remoteManifest.sessions,
+    localReplica.deviceId,
+    remoteHello.deviceId
+  );
+  const configPlan = planConfigs(localManifest.configs, remoteManifest.configs);
+
+  // Apply any planned forks before data transfer
+  for (const fork of sessionPlan.forks) {
+    await localReplica.applyFork(fork.key, fork.forkedKey);
+  }
+
+  if (opts.dryRun) {
+    await channel.send({ type: 'bye' });
+    await channel.receive('bye');
+    return {
+      dryRun: true,
+      remoteDeviceId: remoteHello.deviceId,
+      sessionWants: sessionPlan.wants,
+      configWants: configPlan.wants,
+      forks: sessionPlan.forks,
+    };
+  }
+
+  await channel.send({
+    type: 'wants',
+    sessions: sessionPlan.wants,
+    configs: configPlan.wants,
+  });
+
+  const remoteWants = await channel.receive('wants');
+
+  // 4. Serve & Receive
+  const numSessionsToReceive = sessionPlan.wants.length;
+  const numConfigsToReceive = configPlan.wants.length;
+
+  const serveTask = async () => {
+    for (const sWant of remoteWants.sessions || []) {
+      const item = await localReplica.serveSession(sWant.key, sWant.from);
+      await channel.send({ type: 'serve-session', item });
+    }
+    for (const cWant of remoteWants.configs || []) {
+      const item = await localReplica.serveConfig(cWant);
+      await channel.send({ type: 'serve-config', item });
+    }
+    await channel.send({ type: 'serve-end' });
+  };
+
+  const receiveTask = async () => {
+    const receivedSessions = [];
+    for (let i = 0; i < numSessionsToReceive; i++) {
+      const msg = await channel.receive('serve-session');
+      receivedSessions.push(msg.item);
+    }
+    const receivedConfigs = [];
+    for (let i = 0; i < numConfigsToReceive; i++) {
+      const msg = await channel.receive('serve-config');
+      receivedConfigs.push(msg.item);
+    }
+    await channel.receive('serve-end');
+    return { receivedSessions, receivedConfigs };
+  };
+
+  const [, { receivedSessions, receivedConfigs }] = await Promise.all([
+    serveTask(),
+    receiveTask(),
+  ]);
+
+  // 5. Apply, save state, bye
+  for (const item of receivedSessions) {
+    await localReplica.applySession(item);
+  }
+
+  for (const item of receivedConfigs) {
+    const shouldStash = configPlan.stashes.some((s) => s.relPath === item.relPath);
+    await localReplica.applyConfig({ ...item, stash: shouldStash });
+  }
+
+  await channel.send({ type: 'bye' });
+  await channel.receive('bye');
+
+  return {
+    remoteDeviceId: remoteHello.deviceId,
+    sessionsReceived: receivedSessions.length,
+    configsReceived: receivedConfigs.length,
+    forks: sessionPlan.forks.length,
+  };
+}

package/lib/wire.js

@@ -0,0 +1,185 @@
+export const MAX_FRAME_SIZE = 64 * 1024 * 1024; // 64 MiB
+
+export class WireError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WireError';
+  }
+}
+
+export function encodeFrame(message) {
+  const jsonStr = JSON.stringify(message);
+  const payload = Buffer.from(jsonStr, 'utf8');
+  if (payload.length > MAX_FRAME_SIZE) {
+    throw new WireError(`Frame size ${payload.length} exceeds maximum cap of ${MAX_FRAME_SIZE} bytes`);
+  }
+  const frame = Buffer.allocUnsafe(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+export class Channel {
+  constructor(stream, opts = {}) {
+    this.stream = stream;
+    this.defaultTimeoutMs = opts.timeoutMs ?? 120000;
+    this.incomingBuffer = Buffer.alloc(0);
+    this.frameQueue = [];
+    this.receivers = [];
+    this.closed = false;
+    this.fatalError = null;
+
+    this._onData = (chunk) => this._handleData(chunk);
+    this._onError = (err) => this._fatal(err);
+    this._onEnd = () => this._handleClose();
+    this._onClose = () => this._handleClose();
+
+    this.stream.on('data', this._onData);
+    this.stream.on('error', this._onError);
+    this.stream.on('end', this._onEnd);
+    this.stream.on('close', this._onClose);
+  }
+
+  _handleData(chunk) {
+    this.incomingBuffer = Buffer.concat([this.incomingBuffer, chunk]);
+
+    while (this.incomingBuffer.length >= 4) {
+      const frameLen = this.incomingBuffer.readUInt32BE(0);
+      if (frameLen > MAX_FRAME_SIZE) {
+        this._fatal(new WireError(`Frame size ${frameLen} exceeds maximum cap of ${MAX_FRAME_SIZE} bytes`));
+        return;
+      }
+
+      if (this.incomingBuffer.length < 4 + frameLen) {
+        // Need more bytes
+        break;
+      }
+
+      const payload = this.incomingBuffer.subarray(4, 4 + frameLen);
+      this.incomingBuffer = this.incomingBuffer.subarray(4 + frameLen);
+
+      let message;
+      try {
+        message = JSON.parse(payload.toString('utf8'));
+      } catch (err) {
+        this._fatal(new WireError(`Failed to parse JSON frame: ${err.message}`));
+        return;
+      }
+
+      this._dispatchMessage(message);
+    }
+  }
+
+  _dispatchMessage(message) {
+    if (this.receivers.length > 0) {
+      const receiver = this.receivers.shift();
+      clearTimeout(receiver.timer);
+      if (receiver.expectedType && message.type !== receiver.expectedType) {
+        receiver.reject(new WireError(
+          `Unexpected frame type: got ${message.type}, expected ${receiver.expectedType}`
+        ));
+      } else {
+        receiver.resolve(message);
+      }
+    } else {
+      this.frameQueue.push(message);
+    }
+  }
+
+  _fatal(err) {
+    this.fatalError = err instanceof WireError ? err : new WireError(err.message);
+    this.close();
+  }
+
+  _handleClose() {
+    this.closed = true;
+    const err = this.fatalError || new WireError('Channel closed');
+    while (this.receivers.length > 0) {
+      const receiver = this.receivers.shift();
+      clearTimeout(receiver.timer);
+      receiver.reject(err);
+    }
+  }
+
+  async send(message) {
+    if (this.closed) {
+      throw this.fatalError || new WireError('Cannot send on closed channel');
+    }
+    const frame = encodeFrame(message);
+    if (!this.stream.write(frame)) {
+      await new Promise((resolve, reject) => {
+        const onDrain = () => {
+          cleanup();
+          resolve();
+        };
+        const onError = (err) => {
+          cleanup();
+          reject(err);
+        };
+        const cleanup = () => {
+          this.stream.removeListener('drain', onDrain);
+          this.stream.removeListener('error', onError);
+        };
+        this.stream.once('drain', onDrain);
+        this.stream.once('error', onError);
+      });
+    }
+  }
+
+  receive(expectedType, timeoutMs) {
+    if (this.fatalError) {
+      return Promise.reject(this.fatalError);
+    }
+
+    // Check if frame already queued
+    if (this.frameQueue.length > 0) {
+      const message = this.frameQueue.shift();
+      if (expectedType && message.type !== expectedType) {
+        return Promise.reject(new WireError(
+          `Unexpected frame type: got ${message.type}, expected ${expectedType}`
+        ));
+      }
+      return Promise.resolve(message);
+    }
+
+    if (this.closed) {
+      return Promise.reject(new WireError('Channel closed'));
+    }
+
+    const effectiveTimeout = timeoutMs ?? this.defaultTimeoutMs;
+
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      if (effectiveTimeout > 0) {
+        timer = setTimeout(() => {
+          const idx = this.receivers.findIndex((r) => r.resolve === resolve);
+          if (idx !== -1) {
+            this.receivers.splice(idx, 1);
+          }
+          reject(new WireError(`Timed out waiting for frame (${expectedType ?? 'any'}) after ${effectiveTimeout}ms`));
+        }, effectiveTimeout);
+      }
+
+      this.receivers.push({
+        resolve,
+        reject,
+        expectedType,
+        timer,
+      });
+    });
+  }
+
+  close() {
+    if (!this.closed) {
+      this.closed = true;
+      this.stream.removeListener('data', this._onData);
+      this.stream.removeListener('error', this._onError);
+      this.stream.removeListener('end', this._onEnd);
+      this.stream.removeListener('close', this._onClose);
+      if (typeof this.stream.destroy === 'function') {
+        this.stream.destroy();
+      }
+      this._handleClose();
+    }
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "dsh-p2p-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Direct peer-to-peer sync for DeepSeek Harness (no cloud, no coordinator).",
+  "main": "lib/index.js",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oiupoyt/dsh-p2p-sync.git"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.19.0"
+  }
+}