openfused 0.3.3 → 0.3.5

package/README.md

@@ -14,8 +14,8 @@ No vendor lock-in. No proprietary protocol. Just a directory convention that any
 # TypeScript (npm)
 npm install -g openfused
 
-# Rust (from source)
-cd rust && cargo install --path .
+# Rust (crates.io)
+cargo install openfuse
 
 # Docker (daemon)
 docker compose up
@@ -124,7 +124,7 @@ The `age` format is interoperable — Rust CLI and TypeScript SDK use the same k
 
 ## Registry — DNS for Agents
 
-Public registry at `openfuse-registry.wzmcghee.workers.dev`. Any agent can register, discover others, and send messages.
+Public registry at `registry.openfused.dev`. Any agent can register, discover others, and send messages.
 
 ```bash
 # Register your agent
@@ -146,7 +146,7 @@ openfuse send wearethecompute "hello from the mesh"
 
 ## Sync
 
-Pull peer context and push outbox messages. Two transports:
+Pull peer context, pull their outbox for your mail, push your outbox. Two transports:
 
 ```bash
 # LAN — rsync over SSH (uses your ~/.ssh/config for host aliases)
@@ -155,12 +155,34 @@ openfuse peer add ssh://alice.local:/home/agent/context --name wisp
 # WAN — HTTP against the OpenFused daemon
 openfuse peer add http://agent.example.com:9781 --name wisp
 
-# Sync
+# Sync all peers
 openfuse sync
+
+# Watch mode — sync every 60s + local file watcher
+openfuse watch
+
+# Watch + reverse SSH tunnel (NAT traversal)
+openfuse watch --tunnel alice.local
+```
+
+Sync does three things:
+1. **Pulls** peer's CONTEXT.md, PROFILE.md, shared/, knowledge/ into `.peers/<name>/`
+2. **Pulls** peer's outbox for messages addressed to you (`*_to-{your-name}.json`)
+3. **Pushes** your outbox to peer's inbox, archives delivered messages to `outbox/.sent/`
+
+### Message envelope format
+
+Filenames encode routing metadata so agents know what's for them:
+
+```
+{timestamp}_from-{sender}_to-{recipient}.json
 ```
 
-Sync pulls: `CONTEXT.md`, `shared/`, `knowledge/` into `.peers/<name>/`.
-Sync pushes: outbox messages to the peer's inbox. Delivered messages move to `outbox/.sent/`.
+Examples:
+- `2026-03-21T07-59-44Z_from-claude-code_to-wisp.json` — DM, encrypted for wisp
+- `2026-03-21T08-00-00Z_from-wisp_to-all.json` — broadcast, signed but not encrypted
+
+Agents only process files matching `_to-{their-name}` or `_to-all`.
 
 SSH transport uses hostnames from `~/.ssh/config` — not raw IPs.
 
@@ -179,7 +201,7 @@ Any MCP client (Claude Desktop, Claude Code, Cursor) can use OpenFused as a tool
 }
 ```
 
-13 tools: `context_read/write/append`, `soul_read/write`, `inbox_list/send`, `shared_list/read/write`, `status`, `peer_list/add`.
+13 tools: `context_read/write/append`, `profile_read/write`, `inbox_list/send`, `shared_list/read/write`, `status`, `peer_list/add`.
 
 ## Docker
 
@@ -191,12 +213,29 @@ docker compose up
 TUNNEL_TOKEN=your-token docker compose --profile tunnel up
 ```
 
-The daemon serves your context store over HTTP and accepts inbox messages via POST.
+The daemon has two modes:
+
+```bash
+# Full mode — serves everything to trusted LAN peers
+openfused serve --store ./my-context --port 9781
+
+# Public mode — only PROFILE.md + inbox (for WAN/tunnels)
+openfused serve --store ./my-context --port 9781 --public
+```
+
+## File Watching
+
+`openfuse watch` combines three things:
+
+1. **Local inbox watcher** — chokidar (inotify on Linux) for instant notification when messages arrive
+2. **CONTEXT.md watcher** — detects local changes
+3. **Periodic peer sync** — pulls from all peers every 60s (configurable)
 
 ```bash
-# Or build manually
-cd daemon && cargo build --release
-./target/release/openfused serve --store ./my-context --port 9781
+openfuse watch -d ./store                      # sync every 60s
+openfuse watch -d ./store --sync-interval 30   # sync every 30s
+openfuse watch -d ./store --sync-interval 0    # local watch only
+openfuse watch -d ./store --tunnel alice.local  # + reverse SSH tunnel
 ```
 
 ## Reachability

package/dist/cli.js

@@ -3,12 +3,12 @@ import { Command } from "commander";
 import { nanoid } from "nanoid";
 import { ContextStore } from "./store.js";
 import { watchInbox, watchContext, watchSync } from "./watch.js";
-import { syncAll, syncOne } from "./sync.js";
+import { syncAll, syncOne, deliverOne } from "./sync.js";
 import * as registry from "./registry.js";
 import { fingerprint } from "./crypto.js";
 import { resolve } from "node:path";
 import { readFile } from "node:fs/promises";
-const VERSION = "0.3.3";
+const VERSION = "0.3.5";
 const program = new Command();
 program
     .name("openfuse")
@@ -123,8 +123,15 @@ inbox
     .option("-d, --dir <path>", "Context store directory", ".")
     .action(async (peerId, message, opts) => {
     const store = new ContextStore(resolve(opts.dir));
-    await store.sendInbox(peerId, message);
-    console.log(`Message sent to ${peerId}'s outbox.`);
+    const filename = await store.sendInbox(peerId, message);
+    // Try immediate delivery — if peer is reachable, deliver now
+    const delivered = await deliverOne(store, peerId, filename);
+    if (delivered) {
+        console.log(`Delivered to ${peerId}.`);
+    }
+    else {
+        console.log(`Queued for ${peerId}. Will deliver on next sync.`);
+    }
 });
 // --- watch ---
 program
@@ -132,8 +139,9 @@ program
     .description("Watch for inbox messages, context changes, and sync with peers")
     .option("-d, --dir <path>", "Context store directory", ".")
     .option("--sync-interval <seconds>", "Peer sync interval in seconds (0 to disable)", "60")
-    .option("--tunnel <host>", "Open reverse SSH tunnel to host (makes your store reachable from behind NAT)")
-    .option("--tunnel-port <port>", "Remote port for reverse tunnel", "2222")
+    .option("--tunnel <host>", "Reverse SSH tunnel to host for NAT traversal (uses autossh if available)")
+    .option("--tunnel-port <port>", "Remote port for reverse SSH tunnel", "2222")
+    .option("--cloudflared", "Start a cloudflared quick tunnel (no config needed, gives you a public URL)")
     .action(async (opts) => {
     const store = new ContextStore(resolve(opts.dir));
     if (!(await store.exists())) {
@@ -175,6 +183,24 @@ program
         console.log(`Tunnel: ${cmd} -R ${tunnelPort}:localhost:9781 ${tunnelHost}`);
         console.log(`Your store is reachable at ssh://${tunnelHost}:${tunnelPort} (via daemon on :9781)`);
     }
+    // Cloudflared quick tunnel (optional) — gives you a public *.trycloudflare.com URL
+    if (opts.cloudflared) {
+        const { spawn } = await import("node:child_process");
+        const cf = spawn("cloudflared", ["tunnel", "--url", "http://localhost:9781"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        cf.on("error", (e) => console.error(`[cloudflared] failed: ${e.message}. Install: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/`));
+        cf.stderr.on("data", (data) => {
+            const line = data.toString();
+            const match = line.match(/https:\/\/[^\s]+\.trycloudflare\.com/);
+            if (match) {
+                console.log(`[cloudflared] Your public URL: ${match[0]}`);
+                console.log(`  Register it: openfuse register --endpoint ${match[0]}`);
+            }
+        });
+        process.on("exit", () => cf.kill());
+        console.log("Starting cloudflared tunnel...");
+    }
     console.log(`Press Ctrl+C to stop.\n`);
     watchInbox(store.root, (from, message) => {
         console.log(`\n[inbox] New message from ${from}:`);

package/dist/crypto.js

@@ -1,3 +1,8 @@
+// --- Why Ed25519 + age? ---
+// Ed25519: fast, deterministic, no padding oracle attacks, widely supported (SSH, FIDO2, libsodium).
+// age over PGP: simpler API, no config footguns, no Web of Trust baggage — just X25519+ChaCha20-Poly1305.
+// Two separate keypairs because signing (Ed25519) and encryption (X25519) are distinct operations;
+// combining them would violate key-separation best practice.
 import { generateKeyPairSync, sign, verify, createPrivateKey, createPublicKey, createHash } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
@@ -27,6 +32,8 @@ export async function hasKeys(storeRoot) {
     return existsSync(join(storeRoot, KEY_DIR, "private.key"));
 }
 // --- Fingerprint ---
+// SHA-256 truncated to 16 bytes, displayed as colon-separated hex pairs (GPG-style).
+// Human-readable so agents can verify identities out-of-band — same UX as SSH fingerprints.
 export function fingerprint(publicKey) {
     const hash = createHash("sha256").update(publicKey).digest();
     const pairs = [];
@@ -64,6 +71,12 @@ export async function signMessage(storeRoot, from, message) {
     const signature = sign(null, payload, privateKey).toString("base64");
     return { from, timestamp, message, signature, publicKey, encrypted: false };
 }
+// --- Encrypt-then-sign ---
+// Encrypt first, then sign the ciphertext. This order matters:
+// 1. Proves WHO sent the ciphertext (non-repudiation on the encrypted blob)
+// 2. Prevents Surreptitious Forwarding — signature covers the encrypted form,
+//    so a relay can't strip the signature and re-sign for a different recipient.
+// 3. Signature is verifiable by anyone without needing the decryption key.
 export async function signAndEncrypt(storeRoot, from, plaintext, recipientAgeKey) {
     const ciphertext = await ageEncrypt(plaintext, recipientAgeKey);
     const encoded = Buffer.from(ciphertext).toString("base64");
@@ -104,6 +117,8 @@ async function ageDecrypt(ciphertext, storeRoot) {
     return await d.decrypt(ciphertext, "text");
 }
 // --- Helpers ---
+// XML envelope wrapping — gives LLMs a structured, parseable format with clear
+// trust signals (verified/UNVERIFIED). HTML-escaped to prevent injection into prompts.
 export function wrapExternalMessage(signed, verified) {
     const status = verified ? "verified" : "UNVERIFIED";
     const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");

package/dist/mcp.js

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
+// --- MCP server: 13 tools ---
+// Why exactly 13? They map 1:1 to the store's capabilities — no more, no less.
+// CRUD for context (read/write/append), profile (read/write), inbox (list/send),
+// shared files (list/read/write), status, and peer management (list/add).
+// Every tool an LLM needs to be a full participant in the mesh, nothing it doesn't.
+// stdio transport because MCP clients (Claude Desktop, Cursor) expect it.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ContextStore } from "./store.js";
 import { resolve } from "node:path";
-/** Reject path traversal in filenames — extract basename, block dangerous patterns */
+// LLMs will pass whatever filenames users ask for — including "../../etc/shadow".
+// This is the trust boundary between the AI and the filesystem.
 function sanitizeFilename(name) {
-    // Extract basename (strip any directory components)
     const base = name.split("/").pop().split("\\").pop();
     if (!base || base === "." || base === ".." || base.includes("..")) {
         throw new Error(`Invalid filename: ${name}`);
@@ -17,7 +23,7 @@ const storeDir = process.env.OPENFUSE_DIR || process.argv[3] || ".";
 const store = new ContextStore(resolve(storeDir));
 const server = new McpServer({
     name: "openfuse",
-    version: "0.3.3",
+    version: "0.3.5",
 });
 // --- Context ---
 server.tool("context_read", "Read the agent's CONTEXT.md (working memory)", async () => {

package/dist/registry.d.ts

@@ -1,5 +1,5 @@
 import { ContextStore } from "./store.js";
-export declare const DEFAULT_REGISTRY = "https://openfuse-registry.wzmcghee.workers.dev";
+export declare const DEFAULT_REGISTRY = "https://registry.openfused.dev";
 export interface Manifest {
     name: string;
     endpoint: string;

package/dist/registry.js

@@ -1,5 +1,13 @@
+// --- Registry: DNS + keyserver hybrid ---
+// The registry solves agent discovery without requiring a DHT or blockchain.
+// It's a signed directory: agents register name→endpoint+publicKey mappings,
+// similar to DNS (name resolution) + PGP keyservers (key distribution).
+// Crucially, imported keys are UNTRUSTED by default — the local agent must
+// explicitly `openfuse key trust` after out-of-band verification (fingerprint check).
+// This is TOFU (Trust On First Use) done right: the registry distributes keys,
+// but never asserts trust. Trust is a local decision.
 import { signMessage, fingerprint } from "./crypto.js";
-export const DEFAULT_REGISTRY = "https://openfuse-registry.wzmcghee.workers.dev";
+export const DEFAULT_REGISTRY = "https://registry.openfused.dev";
 export function resolveRegistry(flag) {
     return flag || process.env.OPENFUSE_REGISTRY || DEFAULT_REGISTRY;
 }
@@ -16,6 +24,8 @@ export async function register(store, endpoint, registry) {
         created: new Date().toISOString(),
         capabilities: ["inbox", "shared", "knowledge"],
     };
+    // Canonical string prevents field-reordering attacks — pipe-delimited, deterministic order.
+    // Signature proves the registrant owns the private key (anti-squatting).
     const canonical = `${manifest.name}|${manifest.endpoint}|${manifest.publicKey}|${manifest.encryptionKey || ""}`;
     const signed = await signMessage(store.root, manifest.name, canonical);
     manifest.signature = signed.signature;
@@ -31,7 +41,22 @@ export async function register(store, endpoint, registry) {
     }
     return manifest;
 }
+// Discovery: try DNS TXT first (decentralized, no registry needed), fall back to Worker API.
+// DNS format: v=of1 e={endpoint} pk={pubkey} ek={agekey} fp={fingerprint}
+// Self-hosted: _openfuse.{name}.{their-domain} — user manages their own TXT records.
+// Our zone: _openfuse.{name}.openfused.dev — managed by the registry Worker on registration.
 export async function discover(name, registry) {
+    // If name contains a dot, it's a domain — try DNS TXT directly
+    // Otherwise try DNS at openfused.dev, then fall back to registry API
+    const dnsNames = name.includes(".")
+        ? [`_openfuse.${name}`]
+        : [`_openfuse.${name}.openfused.dev`];
+    for (const dnsName of dnsNames) {
+        const manifest = await discoverViaDns(dnsName, name);
+        if (manifest)
+            return manifest;
+    }
+    // Fall back to registry API
     const resp = await fetch(`${registry.replace(/\/$/, "")}/discover/${name}`);
     if (!resp.ok) {
         const body = await resp.json().catch(() => ({ error: `HTTP ${resp.status}` }));
@@ -39,6 +64,45 @@ export async function discover(name, registry) {
     }
     return (await resp.json());
 }
+async function discoverViaDns(dnsName, agentName) {
+    try {
+        // Use DNS-over-HTTPS (Cloudflare 1.1.1.1) to resolve TXT records
+        const resp = await fetch(`https://1.1.1.1/dns-query?name=${encodeURIComponent(dnsName)}&type=TXT`, {
+            headers: { "Accept": "application/dns-json" },
+        });
+        if (!resp.ok)
+            return null;
+        const data = await resp.json();
+        if (!data.Answer || data.Answer.length === 0)
+            return null;
+        // Parse v=of1 format from TXT record
+        const txt = data.Answer[0].data.replace(/"/g, "");
+        if (!txt.startsWith("v=of1"))
+            return null;
+        const fields = {};
+        for (const part of txt.split(" ")) {
+            const [k, v] = part.split("=", 2);
+            if (k && v)
+                fields[k] = v;
+        }
+        if (!fields.e || !fields.pk)
+            return null;
+        return {
+            name: agentName,
+            endpoint: fields.e,
+            publicKey: fields.pk,
+            encryptionKey: fields.ek || undefined,
+            fingerprint: fields.fp || "",
+            created: "",
+            capabilities: ["inbox", "shared", "knowledge"],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// Revocation is permanent and self-authenticated: the agent signs its own revocation
+// with the key being revoked. No admin needed — if you have the private key, you can kill it.
 export async function revoke(store, registry) {
     const config = await store.readConfig();
     if (!config.publicKey)
@@ -59,6 +123,7 @@ export async function revoke(store, registry) {
         throw new Error(body.error || `Revocation failed`);
     }
 }
+// Non-blocking version check with 2s timeout — never delays the CLI for a slow network.
 export async function checkUpdate(currentVersion) {
     try {
         const controller = new AbortController();

package/dist/store.d.ts

@@ -28,7 +28,7 @@ export declare class ContextStore {
     writeContext(content: string): Promise<void>;
     readProfile(): Promise<string>;
     writeProfile(content: string): Promise<void>;
-    sendInbox(peerId: string, message: string): Promise<void>;
+    sendInbox(peerId: string, message: string): Promise<string>;
     readInbox(): Promise<Array<{
         file: string;
         content: string;

package/dist/store.js

@@ -1,3 +1,16 @@
+// --- Store convention ---
+// The context store IS the protocol. Every agent is a directory on disk with a known layout:
+//   CONTEXT.md  — working memory (mutable, private)
+//   PROFILE.md  — public address card (replaces SOUL.md: "soul" implied private identity,
+//                 but this file is shared with peers — "profile" is honest about its visibility)
+//   inbox/      — append-only message queue from other agents
+//   outbox/     — signed envelopes waiting to be delivered
+//   shared/     — files explicitly published to peers
+//   history/    — conversation logs
+//   knowledge/  — reference docs
+//   .keys/      — Ed25519 + age keypairs (gitignored)
+//   .mesh.json  — config, peer list, keyring
+// No database, no daemon required. `ls` is your status command.
 import { readFile, writeFile, mkdir, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { existsSync } from "node:fs";
@@ -44,7 +57,8 @@ export class ContextStore {
     async readConfig() {
         const raw = await readFile(this.configPath, "utf-8");
         const config = JSON.parse(raw);
-        // Migrate legacy trustedKeys → keyring
+        // Migrate legacy trustedKeys → keyring (v0.1 stored bare public keys in a flat array;
+        // v0.2+ uses a GPG-style keyring with trust levels, fingerprints, and encryption keys)
         if (config.trustedKeys && config.trustedKeys.length > 0) {
             if (!config.keyring)
                 config.keyring = [];
@@ -95,9 +109,12 @@ export class ContextStore {
         else {
             signed = await signMessage(this.root, config.id, message);
         }
+        // Envelope filename encodes routing metadata so sync can match outbox files to peers
+        // without parsing JSON. Colons/dots replaced to stay filesystem-safe across OS.
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const filename = `${timestamp}_${peerId}.json`;
+        const filename = `${timestamp}_from-${config.name}_to-${peerId}.json`;
         await writeFile(join(this.root, "outbox", filename), serializeSignedMessage(signed));
+        return filename;
     }
     async readInbox() {
         const inboxDir = join(this.root, "inbox");
@@ -159,7 +176,8 @@ export class ContextStore {
         return readdir(sharedDir);
     }
     async share(filename, content) {
-        // Sanitize: extract basename, reject traversal
+        // Path traversal defense: basename extraction + ".." rejection.
+        // Critical because MCP tools pass user-supplied filenames directly.
         const base = filename.split("/").pop().split("\\").pop();
         if (!base || base === "." || base === ".." || base.includes("..")) {
             throw new Error(`Invalid filename: ${filename}`);

package/dist/sync.d.ts

@@ -5,5 +5,7 @@ export interface SyncResult {
     pushed: string[];
     errors: string[];
 }
+/** Try to deliver a single outbox message immediately. Returns true if delivered. */
+export declare function deliverOne(store: ContextStore, peerName: string, filename: string): Promise<boolean>;
 export declare function syncAll(store: ContextStore): Promise<SyncResult[]>;
 export declare function syncOne(store: ContextStore, peerName: string): Promise<SyncResult>;

package/dist/sync.js

@@ -1,10 +1,16 @@
+// --- Transport design ---
+// Two transports, one protocol. HTTP for WAN (daemon serves context over the internet),
+// SSH/rsync for LAN (zero config if you already have SSH keys — uses ~/.ssh/config aliases
+// so agents reference hostnames, never raw IPs that change). Both transports do the same
+// thing: pull CONTEXT.md + PROFILE.md + shared/ + knowledge/, push outbox → peer inbox.
 import { readFile, writeFile, mkdir, readdir, rename } from "node:fs/promises";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 const execFile = promisify(execFileCb);
-/** Move delivered message from outbox/ to outbox/.sent/ to prevent re-delivery. */
+// Archive instead of delete: preserves audit trail and lets agents review what was sent.
+// Without this, sync would re-deliver the same message every cycle.
 async function archiveSent(outboxDir, fname) {
     const sentDir = join(outboxDir, ".sent");
     await mkdir(sentDir, { recursive: true });
@@ -21,7 +27,8 @@ function parseUrl(url) {
             throw new Error("SSH URL must be ssh://host:/path");
         const host = rest.slice(0, colonIdx);
         const path = rest.slice(colonIdx + 1);
-        // Validate: prevent argument injection via rsync
+        // Prevent argument injection: rsync treats leading "-" as flags, and shell
+        // metacharacters could escape the execFile boundary on some platforms.
         if (host.startsWith("-") || path.startsWith("-")) {
             throw new Error("Invalid SSH URL: host/path cannot start with '-'");
         }
@@ -32,6 +39,42 @@ function parseUrl(url) {
     }
     throw new Error(`Unknown URL scheme: ${url}. Use http:// or ssh://`);
 }
+/** Try to deliver a single outbox message immediately. Returns true if delivered. */
+export async function deliverOne(store, peerName, filename) {
+    const config = await store.readConfig();
+    const peer = config.peers.find((p) => p.name === peerName || p.id === peerName);
+    if (!peer)
+        return false;
+    const outboxDir = join(store.root, "outbox");
+    const filePath = join(outboxDir, filename);
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const transport = parseUrl(peer.url);
+        if (transport.type === "http") {
+            const body = await readFile(filePath, "utf-8");
+            const r = await fetch(`${transport.baseUrl}/inbox`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body,
+            });
+            if (!r.ok)
+                return false;
+        }
+        else {
+            await execFile("rsync", [
+                "-az", filePath,
+                `${transport.host}:${transport.path}/inbox/${filename}`,
+            ]);
+        }
+        // Delivered — archive to .sent/
+        await archiveSent(outboxDir, filename);
+        return true;
+    }
+    catch {
+        return false; // stays in outbox for next sync
+    }
+}
 export async function syncAll(store) {
     const config = await store.readConfig();
     const results = [];
@@ -91,7 +134,8 @@ async function syncHttp(store, peer, baseUrl, peerDir) {
             for (const f of files) {
                 if (f.is_dir)
                     continue;
-                // Sanitize remote filename — extract basename, reject traversal
+                // Remote peer controls this filename — must sanitize before writing to local disk.
+                // Basename extraction blocks "../../../etc/passwd" style traversal from a malicious peer.
                 const safeName = f.name.split("/").pop().split("\\").pop();
                 if (!safeName || safeName.includes(".."))
                     continue;
@@ -112,7 +156,7 @@ async function syncHttp(store, peer, baseUrl, peerDir) {
         for (const fname of await readdir(outboxDir)) {
             if (!fname.endsWith(".json"))
                 continue;
-            if (!fname.includes(peer.name) && !fname.includes(peer.id))
+            if (!fname.includes(`_to-${peer.name}.json`) && !fname.includes(peer.id))
                 continue;
             try {
                 const body = await readFile(join(outboxDir, fname), "utf-8");
@@ -161,13 +205,36 @@ async function syncSsh(store, peer, host, remotePath, peerDir) {
             errors.push(`${dir}/: ${e.stderr || e.message}`);
         }
     }
-    // Push outbox
+    // Pull peer's outbox for messages addressed to us — peer may be behind NAT
+    // and can't push to us, so we grab messages they left in their outbox for us.
+    const config = await store.readConfig();
+    const myName = config.name;
+    const inboxDir = join(store.root, "inbox");
+    await mkdir(inboxDir, { recursive: true });
+    try {
+        await execFile("rsync", [
+            "-az", "--ignore-existing",
+            "--include", `*_to-${myName}.json`,
+            "--include", `*_to-all.json`,
+            "--include", `*_${myName}.json`, // legacy format (pre-envelope)
+            "--exclude", "*",
+            `${host}:${remotePath}/outbox/`,
+            `${inboxDir}/`,
+        ]);
+        pulled.push("outbox→inbox");
+    }
+    catch (e) {
+        if (!String(e.stderr || e.message).includes("No such file")) {
+            errors.push(`pull outbox: ${e.stderr || e.message}`);
+        }
+    }
+    // Push our outbox → peer inbox
     const outboxDir = join(store.root, "outbox");
     if (existsSync(outboxDir)) {
         for (const fname of await readdir(outboxDir)) {
             if (!fname.endsWith(".json"))
                 continue;
-            if (!fname.includes(peer.name) && !fname.includes(peer.id))
+            if (!fname.includes(`_to-${peer.name}.json`) && !fname.includes(peer.id))
                 continue;
             try {
                 await execFile("rsync", ["-az", join(outboxDir, fname), `${host}:${remotePath}/inbox/${fname}`]);

package/dist/watch.js

@@ -1,3 +1,7 @@
+// --- Watch strategy ---
+// chokidar for local filesystem events (inbox, CONTEXT.md) — instant, inotify-backed on Linux.
+// Polling interval for remote sync (watchSync) — because remote peers are over HTTP/SSH,
+// there's no filesystem event to listen for. Polling is the only option without WebSockets.
 import { watch } from "chokidar";
 import { readFile } from "node:fs/promises";
 import { join, basename } from "node:path";
@@ -25,6 +29,8 @@ export function watchInbox(storeRoot, callback) {
         }
         catch { }
     };
+    // awaitWriteFinish: messages are written by sync (multi-step: create + write + close).
+    // Without stability threshold, we'd fire on half-written files.
     const watcher = watch(inboxDir, {
         ignoreInitial: true,
         awaitWriteFinish: { stabilityThreshold: 500 },
@@ -55,8 +61,11 @@ export function watchContext(storeRoot, callback) {
 export function watchSync(store, intervalMs, onSync, onError) {
     let running = false;
     const doSync = async () => {
+        // Guard against overlapping syncs: if a peer is slow or unreachable, the previous
+        // cycle may still be running when the next interval fires. Overlapping syncs could
+        // double-deliver outbox messages or corrupt in-flight file writes.
         if (running)
-            return; // skip if previous sync still in progress
+            return;
         running = true;
         try {
             const results = await syncAll(store);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfused",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Decentralized context mesh for AI agents. Encrypted sync, signed messaging, MCP server. The protocol is files.",
   "license": "MIT",
   "type": "module",