@envarai/connect 2026.1031.1 → 2026.1107.1

package/README.md

@@ -34,6 +34,13 @@ Use `--framework openclaw` for OpenClaw. Restart the existing native gateway whe
 
 The default state remains `~/.envarpay/connectors/AGENT_UUID` for compatibility. Connection IDs, credentials, journal format, process locks and original order/task IDs are preserved. Run only one receiver for a journal. Rerun `connect` against the same Agent/profile to update its native MCP command; an active connection is reused without another pairing. Keep the original directory when reinstalling or rolling back.
 
+Linux receivers require `flock` from util-linux and a filesystem that supports
+file locks. The kernel releases the receiver lock when its process exits, so
+container restarts and reused PIDs cannot strand the connection. When upgrading
+an orphaned legacy PID lock, first stop the old receiver and verify no other
+receiver uses that journal, then move only `receiver.lock` aside once. Preserve
+the SQLite journal, credentials and native binding. Never remove an active lock.
+
 EnvarPay retains seller charging and exposes the old `envarpay connector ...` command as a compatibility entry. EnvarConnect does not depend on EnvarPay. Free tasks need no payment setup. Optional order tools use separate owner spending grants enforced by Envar; a connection alone cannot spend.
 
 ## API and development

package/dist/connector/state.d.ts

@@ -35,8 +35,9 @@ export declare class ConnectorJournal {
     private readonly db;
     private lock?;
     constructor(path: string, binding: ConnectorBinding);
-    /** A stale process can be replaced only after proving that PID no longer exists. */
+    /** One receiver per journal; Linux kernel locks survive PID reuse safely. */
     acquireProcessLock(path: string): void;
+    private acquireKernelLock;
     ingest(delivery: Delivery): void;
     save(record: LocalWork): void;
     get(id: string): LocalWork | undefined;

package/dist/connector/state.js

@@ -1,5 +1,6 @@
 /** Owner-only durable journal. Transport receipts never imply a second execution. */
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { DatabaseSync } from 'node:sqlite';
@@ -49,10 +50,14 @@ export class ConnectorJournal {
         }
         this.db.prepare("INSERT OR IGNORE INTO connector_meta VALUES ('binding',?)").run(JSON.stringify(binding));
     }
-    /** A stale process can be replaced only after proving that PID no longer exists. */
+    /** One receiver per journal; Linux kernel locks survive PID reuse safely. */
     acquireProcessLock(path) {
         if (this.lock)
             throw new Error('Connector already owns a process lock');
+        if (process.platform === 'linux') {
+            this.acquireKernelLock(path);
+            return;
+        }
         if (existsSync(path)) {
             privateFile(path);
             const value = parseStored(readFileSync(path, 'utf8'));
@@ -77,6 +82,55 @@ export class ConnectorJournal {
         }
         this.lock = { path, nonce };
     }
+    acquireKernelLock(path) {
+        const guard = `${path}.flock`;
+        if (existsSync(guard))
+            privateFile(guard);
+        const fd = openSync(guard, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+        try {
+            // The child inherits this open file description. Its exit keeps the lock
+            // held by our descriptor; process death releases it even after SIGKILL.
+            const result = spawnSync('flock', ['--nonblock', '3'], { stdio: ['ignore', 'ignore', 'ignore', fd] });
+            if (result.status === 1)
+                throw new Error('Another Connector process is using this journal');
+            if (result.error || result.status !== 0)
+                throw new Error('Linux Connector locking requires util-linux flock and filesystem lock support');
+            if (existsSync(path)) {
+                privateFile(path);
+                const stored = readFileSync(path, 'utf8');
+                const value = parseStored(stored);
+                if (value.locking !== 'flock') {
+                    // Do not steal a legacy PID lock during an upgrade. An operator must
+                    // confirm an orphaned container lock before moving it aside once.
+                    if (!Number.isSafeInteger(value.pid) || value.pid < 1)
+                        throw new Error('Inspect the original Connector lock');
+                    try {
+                        process.kill(value.pid, 0);
+                        throw new Error('Another Connector process is using this journal (legacy PID lock)');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ESRCH')
+                            throw error;
+                    }
+                }
+                unlinkSync(path);
+            }
+            const nonce = randomUUID();
+            // Exclusive creation also excludes a legacy receiver racing this upgrade.
+            const metadata = openSync(path, 'wx', 0o600);
+            try {
+                writeFileSync(metadata, JSON.stringify({ pid: process.pid, nonce, locking: 'flock' }), { flush: true });
+            }
+            finally {
+                closeSync(metadata);
+            }
+            this.lock = { path, nonce, fd };
+        }
+        catch (error) {
+            closeSync(fd);
+            throw error;
+        }
+    }
     ingest(delivery) {
         const work = delivery.work;
         const incoming = ['work', 'input', 'cancel'].includes(delivery.kind);
@@ -176,12 +230,19 @@ export class ConnectorJournal {
     sameObservation(record, observation) { return record.lastObservation === digest(observation); }
     close() {
         this.db.close();
-        if (this.lock && existsSync(this.lock.path)) {
-            privateFile(this.lock.path);
-            const value = parseStored(readFileSync(this.lock.path, 'utf8'));
-            if (value.nonce === this.lock.nonce)
-                unlinkSync(this.lock.path);
+        try {
+            if (this.lock && existsSync(this.lock.path)) {
+                privateFile(this.lock.path);
+                const value = parseStored(readFileSync(this.lock.path, 'utf8'));
+                if (value.nonce === this.lock.nonce)
+                    unlinkSync(this.lock.path);
+            }
+        }
+        finally {
+            // The guard inode stays in place while the kernel releases its lock.
+            if (this.lock?.fd !== undefined)
+                closeSync(this.lock.fd);
+            this.lock = undefined;
         }
-        this.lock = undefined;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/connect",
-  "version": "2026.1031.1",
+  "version": "2026.1107.1",
   "description": "Connect your own Agent to Envar: tasks, native adapters and recovery",
   "type": "module",
   "license": "MIT",