pairai 0.2.5 → 0.3.2

package/pairai.ts

@@ -3,25 +3,27 @@
  * pairai CLI — connect AI agents via the pairai hub
  *
  * Commands:
- *   npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini] [--global] [--force]
- *   npx pairai serve [--provider claude|gemini]
+ *   npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq] [--global] [--force]
+ *   npx pairai serve [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq]
  *   npx pairai upgrade     — update to latest version (preserves keys and config)
  *   npx pairai version     — show current version
  *
- * Env: PAIRAI_HUB_URL, PAIRAI_AGENT_CRED, PAIRAI_KEY_FILE, PAIRAI_POLL_MS
+ * Env: PAIRAI_HUB_URL      — hub URL (default: https://pairai.pro)
+ *      PAIRAI_AGENT_CRED   — agent API key (from setup)
+ *      PAIRAI_KEY_FILE     — path to RSA private key .pem
+ *      PAIRAI_POLL_MS      — poll interval in ms (default: 5000)
+ *      PAIRAI_LOCK_DIR     — lock file directory (default: ~/.pairai/locks)
+ *      PAIRAI_DEBUG        — verbose log: "1" for ~/.pairai/debug.log, or a file path
  * Legacy: PAIRAI_URL, PAIRAI_API_KEY, PAIRAI_PRIVATE_KEY_PATH
  */
 import { execSync } from "node:child_process";
-import {
-  generateKeyPairSync,
-  publicEncrypt, privateDecrypt, sign, verify,
-  randomBytes, createCipheriv, createDecipheriv, constants,
-} from "node:crypto";
-import { writeFileSync, mkdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { generateKeyPairSync } from "node:crypto";
+import { writeFileSync, mkdirSync, readFileSync, existsSync, appendFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { validateProvider, detectProvider, updateVersionInConfig, checkExistingConfig, formatKeyBackupBox } from "./lib.js";
+import { validateProvider, detectProvider, checkExistingConfig, formatKeyBackupBox, acquireLock, releaseLock, getProviderConfig, localEncrypt as _localEncrypt, localDecrypt as _localDecrypt } from "./lib.js";
+import type { Provider } from "./lib.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf-8"));
@@ -30,6 +32,19 @@ const VERSION: string = PKG.version;
 const args = process.argv.slice(2);
 const command = args[0];
 
+// ── Debug logging ────────────────────────────────────────────────────────────
+// Enable with PAIRAI_DEBUG=1 or PAIRAI_DEBUG=/path/to/file.log
+// When enabled, writes verbose poll/notification logs to the specified file
+// (or ~/.pairai/debug.log if set to "1").
+const DEBUG_LOG = process.env.PAIRAI_DEBUG;
+const debugLogPath = DEBUG_LOG === "1" ? join(homedir(), ".pairai", "debug.log")
+  : DEBUG_LOG || null;
+function debugLog(msg: string) {
+  if (!debugLogPath) return;
+  const line = `${new Date().toISOString()} ${msg}\n`;
+  try { appendFileSync(debugLogPath, line); } catch {}
+}
+
 // ── Version ─────────────────────────────────────────────────────────────────
 
 if (command === "version" || args.includes("--version") || args.includes("-v")) {
@@ -49,27 +64,11 @@ if (command === "upgrade") {
     } else {
       console.log(`  New version available: v${latest}`);
       console.log(`  Upgrading...\n`);
+      // Clear npx cache so next `npx pairai serve` picks up the new version
+      try { execSync("npx clear-npx-cache 2>/dev/null || rm -rf " + join(homedir(), ".npm/_npx"), { stdio: "pipe" }); } catch {}
       execSync("npm install -g pairai@latest", { stdio: "inherit" });
       console.log(`\n  Upgraded to v${latest}.`);
       console.log(`  Keys and config are unchanged.\n`);
-
-      // Update pinned version in config files
-      const configPaths = [
-        join(process.cwd(), ".mcp.json"),
-        join(process.cwd(), ".gemini", "settings.json"),
-        join(homedir(), ".gemini", "settings.json"),
-      ];
-      for (const p of configPaths) {
-        try {
-          if (!existsSync(p)) continue;
-          const content = readFileSync(p, "utf-8");
-          const updated = updateVersionInConfig(content, latest);
-          if (updated !== content) {
-            writeFileSync(p, updated);
-            console.log(`  Updated version in ${p}`);
-          }
-        } catch {}
-      }
     }
   } catch (err) {
     console.error(`  Upgrade failed: ${(err as Error).message}`);
@@ -78,7 +77,7 @@ if (command === "upgrade") {
   process.exit(0);
 }
 
-// detectProvider, validateProvider, updateVersionInConfig, checkExistingConfig,
+// detectProvider, validateProvider, checkExistingConfig,
 // formatKeyBackupBox are imported from ./lib.js
 
 // ── Setup: register + configure ──────────────────────────────────────────────
@@ -87,6 +86,20 @@ if (command === "setup") {
   const rest = args.slice(1);
   const hubIdx = rest.indexOf("--hub");
   const hubUrl = hubIdx !== -1 ? rest.splice(hubIdx, 2)[1] : "https://pairai.pro";
+  try {
+    const parsed = new URL(hubUrl);
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+      console.error("  Error: Hub URL must use http: or https: protocol.");
+      process.exit(1);
+    }
+    const isLocal = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "::1";
+    if (parsed.protocol === "http:" && !isLocal) {
+      console.error("  Warning: Hub URL uses HTTP (insecure). Use HTTPS for production deployments.");
+    }
+  } catch {
+    console.error("  Error: Invalid hub URL.");
+    process.exit(1);
+  }
   const providerIdx = rest.indexOf("--provider");
   const providerArg = providerIdx !== -1 ? rest.splice(providerIdx, 2)[1] : undefined;
   if (providerArg) {
@@ -95,7 +108,7 @@ if (command === "setup") {
       process.exit(1);
     }
   }
-  const provider = (providerArg as "claude" | "gemini") ?? detectProvider();
+  const provider = (providerArg as Provider) ?? detectProvider();
   const globalIdx = rest.indexOf("--global");
   const useGlobal = globalIdx !== -1 ? (rest.splice(globalIdx, 1), true) : false;
   const agentName = rest.find((a) => !a.startsWith("--"));
@@ -103,7 +116,7 @@ if (command === "setup") {
   const forceIdx = rest.indexOf("--force");
   const useForce = forceIdx !== -1 ? (rest.splice(forceIdx, 1), true) : false;
   if (!agentName) {
-    console.error('Usage: npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini] [--global] [--force]');
+    console.error('Usage: npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq] [--global] [--force]');
     process.exit(1);
   }
 
@@ -144,7 +157,7 @@ if (command === "setup") {
   console.log(`  API Key:   ${apiKey}`);
 
   const keyDir = join(homedir(), ".pairai", "keys");
-  mkdirSync(keyDir, { recursive: true });
+  mkdirSync(keyDir, { recursive: true, mode: 0o700 });
   const keyPath = join(keyDir, `${id}.pem`);
   writeFileSync(keyPath, privateKey, { mode: 0o600 });
   console.log(`  Private key: ${keyPath}`);
@@ -152,61 +165,54 @@ if (command === "setup") {
   for (const line of formatKeyBackupBox(keyPath)) console.log(line);
   console.log();
 
-  if (provider === "gemini") {
-    // Write .gemini/settings.json (project or global)
-    const geminiDir = useGlobal
-      ? join(homedir(), ".gemini")
-      : join(process.cwd(), ".gemini");
-    mkdirSync(geminiDir, { recursive: true });
-    const settingsPath = join(geminiDir, "settings.json");
-
-    // Merge with existing settings
+  const cfg = getProviderConfig(provider, process.cwd(), homedir(), useGlobal);
+  const serverEntry = {
+    command: "npx",
+    args: ["pairai", "serve"],
+    env: {
+      PAIRAI_HUB_URL: hubUrl,
+      PAIRAI_AGENT_CRED: apiKey,
+      PAIRAI_KEY_FILE: keyPath,
+    },
+  };
+
+  // Ensure config directory exists
+  mkdirSync(dirname(cfg.configPath), { recursive: true, mode: 0o700 });
+
+  if (cfg.format === "toml") {
+    // Codex CLI uses TOML
+    let existing = "";
+    try { if (existsSync(cfg.configPath)) existing = readFileSync(cfg.configPath, "utf-8"); } catch {}
+    const tomlBlock = [
+      `\n[mcp_servers.${cfg.mcpKey}]`,
+      `command = "npx"`,
+      `args = ["pairai", "serve"]`,
+      ``,
+      `[mcp_servers.${cfg.mcpKey}.env]`,
+      `PAIRAI_HUB_URL = "${hubUrl}"`,
+      `PAIRAI_AGENT_CRED = "${apiKey}"`,
+      `PAIRAI_KEY_FILE = "${keyPath}"`,
+    ].join("\n");
+    writeFileSync(cfg.configPath, existing + tomlBlock + "\n", { mode: 0o600 });
+  } else {
+    // JSON — merge with existing config
     let existing: any = {};
-    try {
-      if (existsSync(settingsPath)) {
-        existing = JSON.parse(readFileSync(settingsPath, "utf-8"));
-      }
-    } catch {}
-
+    try { if (existsSync(cfg.configPath)) existing = JSON.parse(readFileSync(cfg.configPath, "utf-8")); } catch {}
     if (!existing.mcpServers) existing.mcpServers = {};
-    existing.mcpServers.pairai = {
-      command: "npx",
-      args: [`pairai@${VERSION}`, "serve"],
-      env: {
-        PAIRAI_HUB_URL: hubUrl,
-        PAIRAI_AGENT_CRED: apiKey,
-        PAIRAI_KEY_FILE: keyPath,
-      },
-    };
-
-    writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + "\n");
-    console.log(`  Config: ${settingsPath}`);
-    console.log();
-    console.log(`  Next steps:`);
-    console.log(`    1. Restart Gemini CLI to activate the pairai MCP server`);
-    console.log(`    2. Ask Gemini: "Generate a pairing code"`);
-    console.log(`    3. Share the code with another agent to connect`);
-  } else {
-    // Write .mcp.json for Claude Code
-    const mcpConfig = {
-      mcpServers: {
-        "pairai-channel": {
-          command: "npx",
-          args: [`pairai@${VERSION}`, "serve"],
-          env: { PAIRAI_AGENT_CRED: apiKey, PAIRAI_HUB_URL: hubUrl, PAIRAI_KEY_FILE: keyPath },
-        },
-      },
-    };
+    existing.mcpServers[cfg.mcpKey] = serverEntry;
+    writeFileSync(cfg.configPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+  }
 
-    const cwd = process.cwd();
-    const mcpJsonPath = join(cwd, ".mcp.json");
-    writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n");
-    console.log(`  Config: ${mcpJsonPath}`);
+  console.log(`  Config: ${cfg.configPath}`);
+  console.log();
+  console.log(`  Next steps:`);
+  console.log(`    1. ${cfg.instruction}`);
+  console.log(`    2. Ask your AI: "Generate a pairing code"`);
+  console.log(`    3. Share the code with another agent to connect`);
+  if (provider === "claude") {
     console.log();
-    console.log(`  Next steps:`);
-    console.log(`    1. Start Claude Code in this directory`);
-    console.log(`    2. Ask Claude: "Generate a pairing code"`);
-    console.log(`    3. Share the code with another agent to connect`);
+    console.log(`  Optional: Enable real-time notifications (research preview):`);
+    console.log(`    claude --dangerously-load-development-channels`);
   }
 
   console.log();
@@ -218,10 +224,19 @@ if (command === "setup") {
 if (command !== "serve") {
   console.error(`pairai v${VERSION}\n`);
   console.error("Usage:");
-  console.error('  npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini] [--global] [--force]');
-  console.error("  npx pairai serve [--provider claude|gemini]");
+  console.error('  npx pairai setup "Agent Name" [--hub URL] [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq] [--global] [--force]');
+  console.error("  npx pairai serve [--provider claude|gemini|cursor|copilot|windsurf|codex|amazonq]");
   console.error("  npx pairai upgrade        — update to latest version");
   console.error("  npx pairai version        — show current version");
+  console.error("");
+  console.error("Environment variables:");
+  console.error("  PAIRAI_HUB_URL      Hub URL (default: https://pairai.pro)");
+  console.error("  PAIRAI_AGENT_CRED   Agent API key (from setup)");
+  console.error("  PAIRAI_KEY_FILE     Path to RSA private key .pem file");
+  console.error("  PAIRAI_POLL_MS      Poll interval in ms (default: 5000)");
+  console.error("  PAIRAI_LOCK_DIR     Lock file directory (default: ~/.pairai/locks)");
+  console.error("  PAIRAI_DEBUG=1      Verbose log to ~/.pairai/debug.log");
+  console.error("  PAIRAI_DEBUG=<path> Verbose log to custom file");
   process.exit(1);
 }
 
@@ -238,9 +253,19 @@ if (serveProviderArg) {
     process.exit(1);
   }
 }
-const serveProvider = (serveProviderArg as "claude" | "gemini") ?? "claude";
+const serveProvider = (serveProviderArg as Provider) ?? "claude";
 
 const HUB_URL = process.env.PAIRAI_HUB_URL ?? process.env.PAIRAI_URL ?? "https://pairai.pro";
+try {
+  const parsedHub = new URL(HUB_URL);
+  if (!["http:", "https:"].includes(parsedHub.protocol)) {
+    console.error("[pairai] Error: Hub URL must use http: or https: protocol.");
+    process.exit(1);
+  }
+} catch {
+  console.error("[pairai] Error: Invalid hub URL.");
+  process.exit(1);
+}
 const API_KEY = process.env.PAIRAI_AGENT_CRED ?? process.env.PAIRAI_API_KEY;
 const POLL_MS = Number(process.env.PAIRAI_POLL_MS ?? "5000");
 const PRIVATE_KEY_PATH = process.env.PAIRAI_KEY_FILE ?? process.env.PAIRAI_PRIVATE_KEY_PATH;
@@ -258,29 +283,51 @@ const headers = {
 
 // ── Hub API ──────────────────────────────────────────────────────────────────
 
+const HUB_TIMEOUT_MS = 30_000;
+
+const API_PREFIX = "/api/v1";
+
 async function hubGet(path: string) {
-  const res = await fetch(`${HUB_URL}${path}`, { headers });
+  const res = await fetch(`${HUB_URL}${API_PREFIX}${path}`, { headers, signal: AbortSignal.timeout(HUB_TIMEOUT_MS) });
   if (!res.ok) throw new Error(`GET ${path}: ${res.status}`);
   return res.json();
 }
 
 async function hubPost(path: string, body?: unknown) {
-  const res = await fetch(`${HUB_URL}${path}`, {
+  const res = await fetch(`${HUB_URL}${API_PREFIX}${path}`, {
     method: "POST",
     headers: body ? headers : { Authorization: headers.Authorization },
     body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
   });
   if (!res.ok) throw new Error(`POST ${path}: ${res.status}`);
   return res.json();
 }
 
 async function hubPatch(path: string, body: unknown) {
-  const res = await fetch(`${HUB_URL}${path}`, {
+  const res = await fetch(`${HUB_URL}${API_PREFIX}${path}`, {
     method: "PATCH",
     headers,
     body: JSON.stringify(body),
+    signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(body.error ?? `PATCH ${path}: ${res.status}`);
+  }
+  return res.json();
+}
+
+async function hubDelete(path: string) {
+  const res = await fetch(`${HUB_URL}${API_PREFIX}${path}`, {
+    method: "DELETE",
+    headers: { Authorization: headers.Authorization },
+    signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
   });
-  if (!res.ok) throw new Error(`PATCH ${path}: ${res.status}`);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as { error?: string };
+    throw new Error(body.error ?? `DELETE ${path}: ${res.status}`);
+  }
   return res.json();
 }
 
@@ -309,27 +356,7 @@ async function loadPublicKeys() {
 
 function localEncrypt(plaintext: string, taskId: string, recipientPubKeys: Record<string, string>) {
   if (!PRIVATE_KEY) throw new Error("No private key configured");
-  const key = randomBytes(32);
-  const iv = randomBytes(12);
-  const cipher = createCipheriv("aes-256-gcm", key, iv);
-  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  const ciphertext = Buffer.concat([iv, encrypted, tag]).toString("base64");
-
-  const signature = sign(null, Buffer.from(taskId + ciphertext), {
-    key: PRIVATE_KEY,
-    padding: constants.RSA_PKCS1_PSS_PADDING,
-    saltLength: 32,
-  }).toString("base64");
-
-  const encryptedKeys: Record<string, string> = {};
-  for (const [id, pub] of Object.entries(recipientPubKeys)) {
-    encryptedKeys[id] = publicEncrypt(
-      { key: pub, oaepHash: "sha256", padding: constants.RSA_PKCS1_OAEP_PADDING },
-      key,
-    ).toString("base64");
-  }
-  return { ciphertext, signature, encryptedKeys };
+  return _localEncrypt(plaintext, taskId, PRIVATE_KEY, recipientPubKeys);
 }
 
 function localDecrypt(
@@ -340,21 +367,7 @@ function localDecrypt(
   myEncKey: string,
 ): string {
   if (!PRIVATE_KEY) throw new Error("No private key configured");
-  const valid = verify(null, Buffer.from(taskId + ciphertext), {
-    key: senderPub,
-    padding: constants.RSA_PKCS1_PSS_PADDING,
-    saltLength: 32,
-  }, Buffer.from(sig, "base64"));
-  if (!valid) throw new Error("Signature verification failed");
-
-  const aesKey = privateDecrypt(
-    { key: PRIVATE_KEY, oaepHash: "sha256", padding: constants.RSA_PKCS1_OAEP_PADDING },
-    Buffer.from(myEncKey, "base64"),
-  );
-  const data = Buffer.from(ciphertext, "base64");
-  const decipher = createDecipheriv("aes-256-gcm", aesKey, data.subarray(0, 12));
-  decipher.setAuthTag(data.subarray(-16));
-  return Buffer.concat([decipher.update(data.subarray(12, -16)), decipher.final()]).toString("utf8");
+  return _localDecrypt(ciphertext, sig, taskId, senderPub, myEncKey, PRIVATE_KEY);
 }
 
 // ── MCP Server ───────────────────────────────────────────────────────────────
@@ -362,6 +375,7 @@ function localDecrypt(
 const instructions = [
   "You are connected to the pairai agent hub. Messages from other AI agents arrive as notifications.",
   "The channel server polls for updates automatically — you don't need to poll manually.",
+  "When the user asks about updates, new messages, or pending work, use pairai_check_updates (not pairai_list_tasks).",
   "",
   "Notification attributes:",
   "  task_id     — the task this message belongs to",
@@ -381,7 +395,7 @@ const capabilities = serveProvider === "claude"
   : { tools: {} };
 
 const mcp = new Server(
-  { name: "pairai", version: "1.0.0" },
+  { name: "pairai", version: VERSION },
   { capabilities, instructions }
 );
 
@@ -389,6 +403,16 @@ const mcp = new Server(
 
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    {
+      name: "pairai_check_updates",
+      description: "Check for NEW incoming tasks and UNREAD messages from other agents. This is the primary way to discover what needs your attention — returns only unseen items, not all tasks. Call this first when asked about updates, new messages, or pending work.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          acknowledge: { type: "boolean", description: "If true, marks all current updates as seen after returning them" },
+        },
+      },
+    },
     {
       name: "pairai_reply",
       description: "Send a message to the other agent in a task.",
@@ -463,6 +487,8 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
           description: { type: "string", description: "What this agent does (max 500 chars)" },
           capabilities: { type: "array", items: { type: "string" }, description: "List of capabilities, e.g. ['scheduling', 'code-review']" },
           metadata: { type: "object", description: "Arbitrary JSON metadata (max 4KB)" },
+          discoverable: { type: "boolean", description: "Whether to appear in the public agent directory" },
+          defaultApprovalRule: { type: "string", enum: ["auto", "require"], description: "Default approval rule for new connections" },
         },
       },
     },
@@ -478,9 +504,84 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["connection_id"],
       },
     },
+    {
+      name: "pairai_update_webhook",
+      description: "Configure a webhook URL to receive events. Set url to null to disable.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          url: { type: ["string", "null"], description: "HTTPS webhook endpoint, or null to disable" },
+          secret: { type: "string", description: "Shared secret for HMAC-SHA256 signature (min 16 chars)" },
+          events: { type: "array", items: { type: "string" }, description: "Event types to receive (empty = all)" },
+        },
+      },
+    },
+    {
+      name: "pairai_discover_agents",
+      description: "Search the public directory of discoverable agents by capability or name.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          capability: { type: "string", description: "Filter by capability tag" },
+          query: { type: "string", description: "Search name and description" },
+          limit: { type: "number", description: "Max results (default 20)" },
+        },
+      },
+    },
+    {
+      name: "pairai_set_approval_rule",
+      description: "Set whether incoming tasks from a connection require human approval. 'auto' accepts automatically, 'require' holds tasks pending.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          connection_id: { type: "string", description: "Connection ID" },
+          rule: { type: "string", enum: ["auto", "require"], description: "Approval rule" },
+        },
+        required: ["connection_id", "rule"],
+      },
+    },
+    {
+      name: "pairai_disconnect",
+      description: "Disconnect from an agent. Cascades: cancels active tasks, notifies the other agent.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          connection_id: { type: "string", description: "Connection ID to delete" },
+        },
+        required: ["connection_id"],
+      },
+    },
+    {
+      name: "pairai_list_pending_approvals",
+      description: "List tasks waiting for your approval.",
+      inputSchema: { type: "object" as const, properties: {} },
+    },
+    {
+      name: "pairai_approve_task",
+      description: "Approve a task that is pending your approval.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string", description: "Task ID" },
+        },
+        required: ["task_id"],
+      },
+    },
+    {
+      name: "pairai_reject_task",
+      description: "Reject a task pending your approval. Optionally provide a reason.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string", description: "Task ID" },
+          reason: { type: "string", description: "Reason for rejection" },
+        },
+        required: ["task_id"],
+      },
+    },
     {
       name: "pairai_list_tasks",
-      description: "List all tasks you are involved in (as initiator or target).",
+      description: "List ALL tasks (not just new ones). Use this to browse your full task history or filter by status. For checking what's new, use pairai_check_updates instead.",
       inputSchema: {
         type: "object" as const,
         properties: {
@@ -513,6 +614,18 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["task_id", "filename", "mime_type", "base64_content"],
       },
     },
+    {
+      name: "pairai_download_file",
+      description: "Download a file from a task. For encrypted tasks, the file is automatically decrypted.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string", description: "Task ID the file belongs to" },
+          file_id: { type: "string", description: "File ID to download" },
+        },
+        required: ["task_id", "file_id"],
+      },
+    },
     {
       name: "pairai_create_encrypted_task",
       description: "Create an encrypted task. Title and description are encrypted — the hub cannot read them.",
@@ -531,7 +644,58 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
 
 mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: a } = req.params;
-  const args = a as Record<string, string>;
+  const args = a as Record<string, unknown>;
+
+  if (name === "pairai_check_updates") {
+    await loadPublicKeys();
+    const updates = (await hubGet("/updates")) as {
+      hasUpdates: boolean;
+      pendingTasks: Array<{ id: string; title: string; fromAgent: string }>;
+      unreadMessages: Array<{ taskId: string; taskTitle: string; count: number }>;
+      cursor: number;
+    };
+
+    if (!updates.hasUpdates) {
+      return { content: [{ type: "text" as const, text: "No updates. You're all caught up." }] };
+    }
+
+    const parts: string[] = [];
+
+    if (updates.pendingTasks.length > 0) {
+      const enriched: string[] = [];
+      for (const task of updates.pendingTasks) {
+        const full = (await hubGet(`/tasks/${task.id}`)) as any;
+        const desc = full.encrypted ? decryptTaskDescription(full, task.id) : (full.description ?? "");
+        const title = desc.split("\n")[0] || task.title;
+        enriched.push(`- "${title}" from ${task.fromAgent} (task ID: ${task.id})`);
+      }
+      parts.push(`**${updates.pendingTasks.length} pending task(s):**\n${enriched.join("\n")}`);
+    }
+
+    if (updates.unreadMessages.length > 0) {
+      const enriched: string[] = [];
+      for (const unread of updates.unreadMessages) {
+        const full = (await hubGet(`/tasks/${unread.taskId}`)) as any;
+        const msgs = (full.messages ?? []) as Array<any>;
+        const recent = msgs.slice(-unread.count);
+        const previews: string[] = [];
+        for (const m of recent) {
+          const d = full.encrypted ? decryptMessage(m, unread.taskId) : { content: m.content, contentType: m.contentType };
+          previews.push(d.content.slice(0, 100));
+        }
+        enriched.push(`- ${unread.count} new in "${unread.taskTitle}" (task ID: ${unread.taskId})\n  Preview: ${previews.join(" | ")}`);
+      }
+      parts.push(`**Unread messages:**\n${enriched.join("\n")}`);
+    }
+
+    // Always ack — this is the authoritative "user has seen these" signal.
+    // The poll loop does NOT ack; only this tool does.
+    if (updates.cursor > 0) {
+      await hubPost("/updates/ack", { cursor: updates.cursor });
+    }
+
+    return { content: [{ type: "text" as const, text: parts.join("\n\n") }] };
+  }
 
   if (name === "pairai_reply") {
     const { task_id, text, content_type } = args as { task_id: string; text: string; content_type?: string };
@@ -548,17 +712,22 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
         return { content: [{ type: "text" as const, text: "Error: Cannot reply to encrypted task — missing cryptographic keys. Re-run setup or reconnect." }] };
       }
       const envelope = JSON.stringify({ contentType: content_type ?? "text", body: text });
-      const { ciphertext, signature, encryptedKeys } = localEncrypt(envelope, task_id, {
-        [myAgentId]: myPublicKey,
-        [otherId]: otherPub,
-      });
-      await hubPost(`/tasks/${task_id}/messages`, {
-        content: ciphertext,
-        contentType: "encrypted",
-        encryptedKeys,
-        senderSignature: signature,
-      });
-      return { content: [{ type: "text" as const, text: "Sent (encrypted)." }] };
+      try {
+        const { ciphertext, signature, encryptedKeys } = localEncrypt(envelope, task_id, {
+          [myAgentId]: myPublicKey,
+          [otherId]: otherPub,
+        });
+        await hubPost(`/tasks/${task_id}/messages`, {
+          content: ciphertext,
+          contentType: "encrypted",
+          encryptedKeys,
+          senderSignature: signature,
+        });
+        return { content: [{ type: "text" as const, text: "Sent (encrypted)." }] };
+      } catch (err) {
+        console.error(`[pairai] encryption failed for task ${task_id}: ${(err as Error).message}`);
+        return { content: [{ type: "text" as const, text: `Error: Failed to encrypt reply — ${(err as Error).message}. The other agent may have an invalid public key.` }], isError: true };
+      }
     }
     // Non-encrypted task: send plaintext
     await hubPost(`/tasks/${task_id}/messages`, {
@@ -569,8 +738,16 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   }
 
   if (name === "pairai_update_status") {
-    await hubPatch(`/tasks/${args.task_id}`, { status: args.status });
-    return { content: [{ type: "text" as const, text: `Status → ${args.status}` }] };
+    try {
+      await hubPatch(`/tasks/${args.task_id}`, { status: args.status });
+      return { content: [{ type: "text" as const, text: `Status → ${args.status}` }] };
+    } catch (err) {
+      const msg = (err as Error).message;
+      if (msg.includes("409") || msg.includes("400")) {
+        return { content: [{ type: "text" as const, text: `Cannot update status — ${msg}` }] };
+      }
+      throw err;
+    }
   }
 
   if (name === "pairai_get_profile") {
@@ -638,6 +815,8 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     if (args.description !== undefined) body.description = args.description;
     if (args.capabilities !== undefined) body.capabilities = args.capabilities;
     if (args.metadata !== undefined) body.metadata = args.metadata;
+    if (args.discoverable !== undefined) body.discoverable = args.discoverable === "true" || args.discoverable === true;
+    if (args.defaultApprovalRule !== undefined) body.defaultApprovalRule = args.defaultApprovalRule;
     const data = await hubPatch("/agents/me", body);
     return { content: [{ type: "text" as const, text: "Profile updated.\n" + JSON.stringify(data, null, 2) }] };
   }
@@ -648,6 +827,57 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
   }
 
+  if (name === "pairai_update_webhook") {
+    const body: Record<string, unknown> = {};
+    if (args.url !== undefined) body.webhookUrl = args.url;
+    if (args.secret !== undefined) body.webhookSecret = args.secret;
+    if (args.events !== undefined) body.webhookEvents = args.events;
+    const data = await hubPatch("/agents/me", body);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
+  if (name === "pairai_discover_agents") {
+    const params = new URLSearchParams();
+    if (args.capability) params.set("capability", args.capability);
+    if (args.query) params.set("q", args.query);
+    if (args.limit) params.set("limit", args.limit);
+    const qs = params.toString();
+    const data = await hubGet(`/agents/discover${qs ? `?${qs}` : ""}`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
+  if (name === "pairai_set_approval_rule") {
+    const { connection_id, rule } = args as { connection_id: string; rule: string };
+    const data = await hubPatch(`/connections/${connection_id}`, { approval: rule });
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
+  if (name === "pairai_disconnect") {
+    const { connection_id } = args as { connection_id: string };
+    try {
+      const result = (await hubDelete(`/connections/${connection_id}`)) as { cancelledTasks?: number };
+      return { content: [{ type: "text" as const, text: `Disconnected. ${result.cancelledTasks ?? 0} task(s) cancelled.` }] };
+    } catch (err) {
+      return { content: [{ type: "text" as const, text: `Error: ${(err as Error).message}` }], isError: true };
+    }
+  }
+
+  if (name === "pairai_list_pending_approvals") {
+    const data = await hubGet("/approvals");
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
+  if (name === "pairai_approve_task") {
+    const data = await hubPost(`/approvals/${args.task_id}/approve`);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
+  if (name === "pairai_reject_task") {
+    const { task_id, reason } = args as { task_id: string; reason?: string };
+    const data = await hubPost(`/approvals/${task_id}/reject`, reason ? { reason } : undefined);
+    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+  }
+
   if (name === "pairai_list_tasks") {
     await loadPublicKeys();
     const data = (await hubGet("/tasks")) as Array<{
@@ -677,13 +907,20 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
       encryptedKeys?: any; senderSignature?: string;
     }>;
     if (data.encrypted) {
-      const desc = decryptTaskDescription(data, data.id);
-      data.description = desc;
+      try {
+        data.description = decryptTaskDescription(data, data.id);
+      } catch {
+        data.description = "[decryption failed]";
+      }
     }
     const decryptedMsgs = msgs.map((m) => {
       if (data.encrypted) {
-        const d = decryptMessage(m, data.id);
-        return { ...m, content: d.content, contentType: d.contentType };
+        try {
+          const d = decryptMessage(m, data.id);
+          return { ...m, content: d.content, contentType: d.contentType };
+        } catch {
+          return { ...m, content: "[decryption failed]", contentType: "text" };
+        }
       }
       return m;
     });
@@ -694,12 +931,151 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { task_id, filename, mime_type, base64_content } = args as {
       task_id: string; filename: string; mime_type: string; base64_content: string;
     };
+
+    // Check if task is encrypted
+    const taskData = (await hubGet(`/tasks/${task_id}`)) as any;
+    if (taskData.encrypted) {
+      // Size guardrail: encryption overhead (~37%) could exceed hub's 50MB limit
+      const rawSize = Buffer.from(base64_content, "base64").byteLength;
+      if (rawSize > 28 * 1024 * 1024) {
+        return { content: [{ type: "text" as const, text: "Error: File too large for encrypted upload (max ~28 MB before encryption overhead)." }] };
+      }
+
+      await loadPublicKeys();
+      const otherId =
+        taskData.initiatorAgentId === myAgentId ? taskData.targetAgentId : taskData.initiatorAgentId;
+      const otherPub = pubKeyCache.get(otherId);
+      if (!otherPub || !myPublicKey || !PRIVATE_KEY) {
+        return { content: [{ type: "text" as const, text: "Error: Cannot upload to encrypted task — missing cryptographic keys. Re-run setup or reconnect." }] };
+      }
+
+      const envelope = JSON.stringify({ filename, mimeType: mime_type, data: base64_content });
+      const { ciphertext, signature, encryptedKeys } = localEncrypt(envelope, task_id, {
+        [myAgentId]: myPublicKey,
+        [otherId]: otherPub,
+      });
+
+      const data = await hubPost(`/tasks/${task_id}/files/json`, {
+        filename: "encrypted_file",
+        mimeType: "application/octet-stream",
+        base64Content: ciphertext,
+        encryptedKeys,
+        senderSignature: signature,
+      });
+      return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+    }
+
+    // Non-encrypted task: pass through
     const data = await hubPost(`/tasks/${task_id}/files/json`, {
       filename, mimeType: mime_type, base64Content: base64_content,
     });
     return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
   }
 
+  if (name === "pairai_download_file") {
+    const { task_id, file_id } = args as { task_id: string; file_id: string };
+
+    // Fetch the task to check encryption status
+    const taskData = (await hubGet(`/tasks/${task_id}`)) as any;
+
+    // Download raw file bytes
+    const response = await fetch(`${HUB_URL}/files/${file_id}`, {
+      headers: { Authorization: `Bearer ${API_KEY}` },
+      signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      return { content: [{ type: "text" as const, text: `Error: Failed to download file (${response.status}).` }] };
+    }
+    const fileBuffer = Buffer.from(await response.arrayBuffer());
+
+    if (!taskData.encrypted) {
+      // Non-encrypted: return raw file info
+      const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+      const disposition = response.headers.get("content-disposition") ?? "";
+      const filenameMatch = disposition.match(/filename="([^"]+)"/);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            filename: filenameMatch?.[1] ?? "file",
+            mimeType: contentType,
+            data: fileBuffer.toString("base64"),
+            sizeBytes: fileBuffer.byteLength,
+          }, null, 2),
+        }],
+      };
+    }
+
+    // Encrypted task: find the message that holds the encryption keys for this file
+    const taskMessages = (await hubGet(`/tasks/${task_id}/messages`)) as Array<{
+      id: string; content: string; contentType: string; senderAgentId: string;
+      encryptedKeys?: any; senderSignature?: string;
+    }>;
+    const fileMsg = taskMessages.find((m) => m.content === file_id);
+    if (!fileMsg) {
+      return { content: [{ type: "text" as const, text: "Error: Could not find message for this file." }] };
+    }
+
+    // Legacy plaintext file in encrypted task (no keys stored)
+    if (!fileMsg.encryptedKeys || !fileMsg.senderSignature) {
+      const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            filename: "file",
+            mimeType: contentType,
+            data: fileBuffer.toString("base64"),
+            sizeBytes: fileBuffer.byteLength,
+            warning: "File was uploaded without encryption (legacy).",
+          }, null, 2),
+        }],
+      };
+    }
+
+    // Decrypt the file
+    if (!PRIVATE_KEY) {
+      return { content: [{ type: "text" as const, text: "Error: No private key configured. Re-run setup." }] };
+    }
+
+    await loadPublicKeys();
+    const senderPub = fileMsg.senderAgentId === myAgentId
+      ? myPublicKey
+      : pubKeyCache.get(fileMsg.senderAgentId);
+    const keys = typeof fileMsg.encryptedKeys === "string"
+      ? JSON.parse(fileMsg.encryptedKeys)
+      : fileMsg.encryptedKeys;
+    const myKey = keys[myAgentId];
+
+    if (!senderPub || !myKey) {
+      return { content: [{ type: "text" as const, text: "Error: Decryption keys not found for this agent." }] };
+    }
+
+    try {
+      // The hub stores binary (decoded from base64 ciphertext); re-encode for localDecrypt
+      const ciphertextB64 = fileBuffer.toString("base64");
+      const plain = localDecrypt(ciphertextB64, fileMsg.senderSignature, task_id, senderPub, myKey);
+      const envelope = JSON.parse(plain);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            filename: envelope.filename,
+            mimeType: envelope.mimeType,
+            data: envelope.data,
+            sizeBytes: Buffer.from(envelope.data, "base64").byteLength,
+          }, null, 2),
+        }],
+      };
+    } catch (err) {
+      const msg = (err as Error).message;
+      if (msg.includes("Signature")) {
+        return { content: [{ type: "text" as const, text: "Error: File signature verification failed — possible tampering." }] };
+      }
+      return { content: [{ type: "text" as const, text: `Error: Failed to decrypt file — ${msg}` }] };
+    }
+  }
+
   if (name === "pairai_create_encrypted_task") {
     if (!PRIVATE_KEY)
       return { content: [{ type: "text" as const, text: "No private key configured. Re-run setup." }] };
@@ -742,6 +1118,7 @@ mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
 // ── Polling ──────────────────────────────────────────────────────────────────
 
 const seenMessages = new Set<string>();
+const SEEN_MESSAGES_MAX = 10_000;
 
 function decryptMessage(
   msg: { content: string; contentType: string; senderAgentId: string; encryptedKeys?: any; senderSignature?: string },
@@ -798,13 +1175,16 @@ async function poll() {
       hasUpdates: boolean;
       pendingTasks: Array<{ id: string; title: string; fromAgent: string }>;
       unreadMessages: Array<{ taskId: string; taskTitle: string; count: number }>;
+      cursor: number;
     };
 
+    debugLog(`poll: hasUpdates=${updates.hasUpdates} tasks=${updates.pendingTasks.length} messages=${updates.unreadMessages.length} cursor=${updates.cursor}`);
     if (!updates.hasUpdates) return;
+    console.error(`[pairai] poll: ${updates.pendingTasks.length} tasks, ${updates.unreadMessages.length} messages`);
 
     for (const task of updates.pendingTasks) {
       const key = `task:${task.id}`;
-      if (seenMessages.has(key)) continue;
+      if (seenMessages.has(key)) { debugLog(`skip seen task ${task.id}`); continue; }
       seenMessages.add(key);
 
       const full = (await hubGet(`/tasks/${task.id}`)) as {
@@ -813,78 +1193,152 @@ async function poll() {
         descriptionKeys?: any;
         senderSignature?: string;
         initiatorAgentId?: string;
-        messages: Array<{
-          content: string;
-          contentType: string;
-          senderAgentId: string;
-          encryptedKeys?: any;
-          senderSignature?: string;
-        }>;
+        approvalStatus?: string | null;
       };
+      const taskMsgs = (await hubGet(`/tasks/${task.id}/messages`)) as Array<{
+        content: string;
+        contentType: string;
+        senderAgentId: string;
+        encryptedKeys?: any;
+        senderSignature?: string;
+      }>;
 
       const desc = decryptTaskDescription(full, task.id);
-      const decryptedMessages = (full.messages ?? []).map((m) => {
-        const d = decryptMessage(m, task.id);
-        return d.content;
+      const decryptedMessages = (taskMsgs ?? []).map((m) => {
+        // Encrypted file messages: content is a file ID (short nanoid), not ciphertext
+        if (m.contentType === "encrypted" && m.encryptedKeys && m.content.length < 30) {
+          return "[File attachment — use pairai_download_file to retrieve]";
+        }
+        try {
+          const d = decryptMessage(m, task.id);
+          return d.content;
+        } catch {
+          return "[decryption failed]";
+        }
       });
 
-      const body = [desc || task.title, ...decryptedMessages.map((c) => `> ${c}`)].join("\n\n");
+      const isPendingApproval = full.approvalStatus === "pending";
+      const approvalPrefix = isPendingApproval ? "[APPROVAL REQUIRED] " : "";
+      const approvalSuffix = isPendingApproval
+        ? `\n\nThis task requires your approval before the agent will act on it.\nUse pairai_approve_task or pairai_reject_task with task ID: ${task.id}`
+        : "";
 
-      await mcp.notification({
-        method: "notifications/claude/channel",
-        params: {
-          content: body,
-          meta: { task_id: task.id, task_title: task.title, from_agent: task.fromAgent, event_type: "new_task" },
-        },
-      });
+      const body = approvalPrefix + [desc || task.title, ...decryptedMessages.map((c) => `> ${c}`)].join("\n\n") + approvalSuffix;
+
+      try {
+        await mcp.notification({
+          method: "notifications/claude/channel",
+          params: {
+            content: body,
+            meta: { task_id: task.id, task_title: task.title, from_agent: task.fromAgent, event_type: "new_task" },
+          },
+        });
+        console.error(`[pairai] channel notification sent: new_task ${task.id} from ${task.fromAgent}${isPendingApproval ? " [APPROVAL REQUIRED]" : ""}`);
+      } catch (err) {
+        console.error(`[pairai] channel notification FAILED: ${(err as Error).message}`);
+      }
     }
 
     for (const unread of updates.unreadMessages) {
-      const full = (await hubGet(`/tasks/${unread.taskId}`)) as {
-        messages: Array<{
-          id: string;
-          content: string;
-          contentType: string;
-          senderAgentId: string;
-          encryptedKeys?: any;
-          senderSignature?: string;
-        }>;
-      };
+      const msgs = (await hubGet(`/tasks/${unread.taskId}/messages`)) as Array<{
+        id: string;
+        content: string;
+        contentType: string;
+        senderAgentId: string;
+        encryptedKeys?: any;
+        senderSignature?: string;
+      }>;
 
-      if (!full?.messages) continue;
-      for (const msg of full.messages.slice(-unread.count)) {
+      debugLog(`unread: taskId=${unread.taskId} count=${unread.count} fetched=${msgs?.length ?? 0}`);
+      if (!msgs || msgs.length === 0) continue;
+      for (const msg of msgs.slice(-unread.count)) {
         const key = `msg:${msg.id}`;
-        if (seenMessages.has(key)) continue;
+        if (seenMessages.has(key)) { debugLog(`skip seen msg ${msg.id}`); continue; }
         seenMessages.add(key);
 
-        const decrypted = decryptMessage(msg, unread.taskId);
+        // Encrypted file messages: content is a file ID (short nanoid), not ciphertext
+        const isEncryptedFile = msg.contentType === "encrypted" && msg.encryptedKeys && msg.content.length < 30;
+        let decrypted: { content: string; contentType: string };
+        if (isEncryptedFile) {
+          decrypted = { content: "[File attachment — use pairai_download_file to retrieve]", contentType: "text" };
+        } else {
+          try {
+            decrypted = decryptMessage(msg, unread.taskId);
+          } catch {
+            decrypted = { content: "[decryption failed]", contentType: "text" };
+          }
+        }
 
-        await mcp.notification({
-          method: "notifications/claude/channel",
-          params: {
-            content: decrypted.content,
-            meta: {
-              task_id: unread.taskId,
-              task_title: unread.taskTitle,
-              from_agent: msg.senderAgentId,
-              event_type: "new_message",
-              content_type: decrypted.contentType,
+        try {
+          await mcp.notification({
+            method: "notifications/claude/channel",
+            params: {
+              content: decrypted.content,
+              meta: {
+                task_id: unread.taskId,
+                task_title: unread.taskTitle,
+                from_agent: msg.senderAgentId,
+                event_type: "new_message",
+                content_type: decrypted.contentType,
+              },
             },
-          },
-        });
+          });
+          console.error(`[pairai] channel notification sent: new_message in ${unread.taskId}`);
+        } catch (err) {
+          console.error(`[pairai] channel notification FAILED: ${(err as Error).message}`);
+        }
       }
     }
 
-    await hubPost("/updates/ack");
+    // Do NOT ack the hub here — the hub's lastSeenRowid is only advanced
+    // when the user explicitly calls pairai_check_updates (authoritative ack).
+    // The seenMessages Set prevents duplicate notifications within this session.
+    debugLog(`poll: processed cursor=${updates.cursor} (hub NOT acked — seenMessages dedup only)`);
+
+    // Prevent unbounded memory growth
+    if (seenMessages.size > SEEN_MESSAGES_MAX) {
+      const excess = seenMessages.size - SEEN_MESSAGES_MAX;
+      const iter = seenMessages.values();
+      for (let i = 0; i < excess; i++) seenMessages.delete(iter.next().value!);
+    }
   } catch (err) {
     console.error(`[pairai] poll error: ${(err as Error).message}`);
+    debugLog(`poll error: ${(err as Error).message}`);
   }
 }
 
 // ── Start ────────────────────────────────────────────────────────────────────
 
 await mcp.connect(new StdioServerTransport());
+console.error(`[pairai] connected. provider=${serveProvider} channel=${!!capabilities.experimental?.["claude/channel"]} agent=${myAgentId || "(loading)"}`);
 await loadAgentInfo();
+if (!myAgentId) {
+  console.error("[pairai] failed to load agent info from hub. Cannot start polling.");
+  process.exit(1);
+}
 await loadPublicKeys();
+
+// Acquire polling lock — only one channel process per agent
+const lockDir = process.env.PAIRAI_LOCK_DIR || undefined;
+if (!acquireLock(myAgentId, lockDir)) {
+  console.error(`[pairai] another instance is already polling for agent ${myAgentId}. Exiting.`);
+  process.exit(0);
+}
+const cleanupLock = () => { try { releaseLock(myAgentId, lockDir); } catch {} };
+process.on("SIGTERM", cleanupLock);
+process.on("SIGINT", cleanupLock);
+process.on("beforeExit", cleanupLock);
+process.on("exit", cleanupLock);
+
+// Detect parent death — when the MCP host (Claude/Gemini) exits, stdin closes.
+// Without this, the process becomes an orphan reparented to systemd.
+process.stdin.on("end", () => {
+  console.error("[pairai] stdin closed (parent exited). Shutting down.");
+  cleanupLock();
+  process.exit(0);
+});
+process.stdin.resume(); // ensure 'end' fires even if nothing reads stdin
+
+console.error(`[pairai] agent=${myAgentId} keys=${pubKeyCache.size} polling every ${POLL_MS}ms`);
 setInterval(poll, POLL_MS);
 poll();