@holon-run/agentinbox 1.5.0 → 1.5.2

package/dist/src/cli.js

@@ -1019,6 +1019,25 @@ async function runServe(args) {
     const daemonPaths = (0, paths_1.resolveDaemonPaths)(process.env, homeOverride);
     const logLevel = (0, logging_1.parseLogLevel)(takeFlagValue(args, "--log-level") ?? process.env.AGENTINBOX_LOG_LEVEL);
     const logger = new logging_1.JsonLogger(logLevel, "agentinbox");
+    // Socket transport: take the admission lock and publish the pid file before
+    // opening the store, so concurrent starters and status checks see this
+    // process during the (possibly slow) store open instead of racing it.
+    let daemonLock = null;
+    if (serveConfig.transport.kind === "socket") {
+        daemonLock = (0, paths_1.daemonLockPath)(serveConfig.transport.socketPath);
+        const acquisition = (0, daemon_1.acquireDaemonLock)(daemonLock);
+        if (!acquisition.acquired) {
+            const holderPid = acquisition.holder?.pid ?? null;
+            logger.warn("daemon.already_running", {
+                pid: holderPid,
+                socketPath: serveConfig.transport.socketPath,
+                lockPath: daemonLock,
+            });
+            console.error(`agentinbox daemon already running${holderPid != null ? ` (pid ${holderPid})` : ""}; not starting a second instance`);
+            process.exit(0);
+        }
+        (0, daemon_1.writePidFile)(daemonPaths.pidPath, process.pid);
+    }
     const store = await store_1.AgentInboxStore.open(serveConfig.dbPath);
     let service;
     const adapters = new adapters_1.AdapterRegistry(store, async (input) => service.appendSourceEvent(input), {
@@ -1029,9 +1048,6 @@ async function runServe(args) {
     await adapters.start();
     await service.start();
     const controlServer = await (0, control_server_1.startControlServer)(server, serveConfig.transport);
-    if (serveConfig.transport.kind === "socket") {
-        (0, daemon_1.writePidFile)(daemonPaths.pidPath, process.pid);
-    }
     (0, daemon_1.writeDaemonMetadata)(daemonPaths.metadataPath, { logLevel });
     logger.info("daemon.ready", {
         homeDir: serveConfig.homeDir,
@@ -1050,8 +1066,11 @@ async function runServe(args) {
             void adapters.stop();
             void service.stop();
             store.close();
-            if (serveConfig.transport.kind === "socket") {
-                (0, daemon_1.removePidFile)(daemonPaths.pidPath);
+            if (serveConfig.transport.kind === "socket" && daemonLock != null) {
+                // Ownership: only remove files that still belong to this process so a
+                // replaced or rebound instance keeps its own pid file and socket.
+                (0, daemon_1.removePidFileIfOwned)(daemonPaths.pidPath, process.pid);
+                (0, daemon_1.releaseDaemonLock)(daemonLock, process.pid);
             }
             (0, daemon_1.removePidFile)(daemonPaths.metadataPath);
             process.exit(0);

package/dist/src/daemon.js

@@ -3,12 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.autostartDisabled = autostartDisabled;
 exports.ensureDaemonForClient = ensureDaemonForClient;
 exports.startDaemon = startDaemon;
 exports.stopDaemon = stopDaemon;
 exports.daemonStatus = daemonStatus;
 exports.writePidFile = writePidFile;
 exports.removePidFile = removePidFile;
+exports.removePidFileIfOwned = removePidFileIfOwned;
+exports.readDaemonLock = readDaemonLock;
+exports.isLockHolderLive = isLockHolderLive;
+exports.readLiveDaemonLockHolder = readLiveDaemonLockHolder;
+exports.acquireDaemonLock = acquireDaemonLock;
+exports.releaseDaemonLock = releaseDaemonLock;
+exports.resolveStartTimeoutMs = resolveStartTimeoutMs;
 exports.resolveDaemonLogLevel = resolveDaemonLogLevel;
 exports.writeDaemonMetadata = writeDaemonMetadata;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -17,11 +25,20 @@ const node_child_process_1 = require("node:child_process");
 const client_1 = require("./client");
 const paths_1 = require("./paths");
 const logging_1 = require("./logging");
-const START_TIMEOUT_MS = 15_000;
+const util_1 = require("./util");
+const DEFAULT_START_TIMEOUT_MS = 60_000;
+// A freshly created but still-empty lock file may belong to a process between
+// create and write; never steal it within this grace window.
+const STALE_LOCK_GRACE_MS = 5_000;
 const PACKAGE_VERSION = readOwnPackageVersion();
+/** AGENTINBOX_NO_AUTOSTART disables implicit daemon spawning (systemd-style deployments). */
+function autostartDisabled(env = process.env) {
+    return (0, util_1.isEnvFlagEnabled)(env.AGENTINBOX_NO_AUTOSTART);
+}
 async function ensureDaemonForClient(options = {}) {
+    const env = options.env ?? process.env;
     const transport = resolveDaemonClientTransport(options);
-    if (options.noAutoStart || transport.kind !== "socket") {
+    if (options.noAutoStart || autostartDisabled(env) || transport.kind !== "socket") {
         return transport;
     }
     if (await canReachHealthz(transport)) {
@@ -37,7 +54,6 @@ async function startDaemon(options = {}) {
     const homeDir = (0, paths_1.resolveAgentInboxHome)(env, options.homeDirOverride);
     const { pidPath, logPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
     node_fs_1.default.mkdirSync(homeDir, { recursive: true });
-    cleanupStalePidFile(pidPath);
     if (await canReachHealthz(transport)) {
         const pid = readPidFile(pidPath);
         return {
@@ -49,6 +65,31 @@ async function startDaemon(options = {}) {
             transport,
         };
     }
+    // Admission: a live lock holder is starting (or serving) this socket — never
+    // spawn a competing daemon. This check is advisory; the spawned serve
+    // process enforces the lock authoritatively.
+    const lockPath = (0, paths_1.daemonLockPath)(transport.socketPath);
+    const timeoutMs = resolveStartTimeoutMs(env);
+    let pendingHolder = readLiveDaemonLockHolder(lockPath);
+    while (pendingHolder) {
+        const outcome = await waitForDaemonReady(transport, lockPath, timeoutMs);
+        if (outcome === "ready") {
+            const pid = readPidFile(pidPath) ?? pendingHolder.pid;
+            return {
+                started: false,
+                pid,
+                logLevel,
+                pidPath,
+                logPath,
+                transport,
+            };
+        }
+        if (outcome === "timeout") {
+            throw new Error(`AgentInbox daemon is already starting (pid ${pendingHolder.pid}) but did not become ready within ${timeoutMs}ms`);
+        }
+        // The pending holder exited before becoming ready; re-check admission.
+        pendingHolder = readLiveDaemonLockHolder(lockPath);
+    }
     const logFd = openLogFile(logPath);
     let child;
     try {
@@ -69,7 +110,7 @@ async function startDaemon(options = {}) {
         node_fs_1.default.closeSync(logFd);
     }
     child.unref();
-    await waitForHealthz(transport, START_TIMEOUT_MS);
+    await waitForHealthz(transport, timeoutMs);
     return {
         started: true,
         pid: child.pid ?? -1,
@@ -83,42 +124,69 @@ async function stopDaemon(options = {}) {
     const env = options.env ?? process.env;
     const transport = requireSocketTransport(resolveDaemonClientTransport(options), "daemon stop");
     const { pidPath, logPath, metadataPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
-    const pid = readPidFile(pidPath);
-    if (pid != null && isProcessAlive(pid)) {
+    let pid = readPidFile(pidPath);
+    if (pid == null || !(0, util_1.isPidAlive)(pid)) {
+        // The pid file may be stale or overwritten while the live daemon still
+        // owns the socket; fall back to the admission lock holder.
+        pid = readLiveDaemonLockHolder((0, paths_1.daemonLockPath)(transport.socketPath))?.pid ?? pid;
+    }
+    if (pid != null && (0, util_1.isPidAlive)(pid)) {
         process.kill(pid, "SIGTERM");
         await waitForProcessExit(pid, 3_000);
     }
-    cleanupStalePidFile(pidPath, true);
-    cleanupFile(transport.socketPath);
-    cleanupFile(metadataPath);
+    // Ownership: if an instance we did not stop still serves the socket, the
+    // files may now belong to it — leave them untouched. Otherwise remove the
+    // pid file only when it no longer references a live process.
+    if (!(await canReachHealthz(transport))) {
+        cleanupStalePidFile(pidPath);
+        cleanupFile(transport.socketPath);
+        cleanupFile(metadataPath);
+    }
     return daemonStatus(options);
 }
 async function daemonStatus(options = {}) {
     const env = options.env ?? process.env;
     const transport = requireSocketTransport(resolveDaemonClientTransport(options), "daemon status");
     const { pidPath, logPath, metadataPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
-    const pid = readPidFile(pidPath);
-    if (pid != null && !isProcessAlive(pid)) {
-        cleanupStalePidFile(pidPath, true);
-        cleanupFile(transport.socketPath);
-        cleanupFile(metadataPath);
-        return {
-            running: false,
-            pid: null,
-            logLevel: null,
-            version: null,
-            startedAt: null,
-            command: null,
-            nodeVersion: null,
-            pidPath,
-            logPath,
-            transport,
-        };
+    let pid = readPidFile(pidPath);
+    if (pid != null && !(0, util_1.isPidAlive)(pid)) {
+        const holder = readLiveDaemonLockHolder((0, paths_1.daemonLockPath)(transport.socketPath));
+        if (holder != null) {
+            // The admission lock identifies the live daemon even when the pid file
+            // is stale (e.g. overwritten by a mixed-version writer).
+            pid = holder.pid;
+        }
+        else if (!(await canReachHealthz(transport))) {
+            // Nothing is serving and no live owner exists: clean stale files.
+            cleanupStalePidFile(pidPath);
+            cleanupFile(transport.socketPath);
+            cleanupFile(metadataPath);
+            return {
+                running: false,
+                starting: false,
+                pid: null,
+                logLevel: null,
+                version: null,
+                startedAt: null,
+                command: null,
+                nodeVersion: null,
+                pidPath,
+                logPath,
+                transport,
+            };
+        }
+        else {
+            // Something answers healthz (e.g. an older daemon without a lock);
+            // report it without owning its files.
+            pid = null;
+        }
     }
     const processInfo = pid == null ? null : readProcessMetadata(pid);
     const daemonMetadata = readDaemonMetadata(metadataPath);
+    const running = await canReachHealthz(transport);
     return {
-        running: await canReachHealthz(transport),
+        running,
+        starting: !running && pid != null && (0, util_1.isPidAlive)(pid),
         pid,
         logLevel: daemonMetadata?.logLevel ?? null,
         version: pid == null ? null : PACKAGE_VERSION,
@@ -137,6 +205,127 @@ function writePidFile(pidPath, pid) {
 function removePidFile(pidPath) {
     cleanupFile(pidPath);
 }
+/** Removes the pid file only when it still belongs to the given pid. */
+function removePidFileIfOwned(pidPath, pid) {
+    if (readPidFile(pidPath) !== pid) {
+        return false;
+    }
+    cleanupFile(pidPath);
+    return true;
+}
+function readDaemonLock(lockPath) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(lockPath, "utf8"));
+        if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
+            return null;
+        }
+        return {
+            pid: parsed.pid,
+            processStartedAt: typeof parsed.processStartedAt === "string" ? parsed.processStartedAt : null,
+            acquiredAt: typeof parsed.acquiredAt === "string" ? parsed.acquiredAt : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isLockHolderLive(holder) {
+    if (!(0, util_1.isPidAlive)(holder.pid)) {
+        return false;
+    }
+    if (holder.processStartedAt == null) {
+        return true;
+    }
+    const current = readProcessMetadata(holder.pid);
+    if (current?.startedAt == null) {
+        return true;
+    }
+    return current.startedAt === holder.processStartedAt;
+}
+function readLiveDaemonLockHolder(lockPath) {
+    const holder = readDaemonLock(lockPath);
+    return holder != null && isLockHolderLive(holder) ? holder : null;
+}
+/**
+ * Atomically (O_EXCL) acquires the daemon admission lock for this process.
+ * A stale lock (dead pid or pid reuse) is removed and retried once. A freshly
+ * created but still-empty lock is treated as held to avoid racing a concurrent
+ * creator between create and write.
+ */
+function acquireDaemonLock(lockPath) {
+    let holder = null;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        holder = null;
+        try {
+            const metadata = readProcessMetadata(process.pid);
+            const info = {
+                pid: process.pid,
+                processStartedAt: metadata?.startedAt ?? null,
+                acquiredAt: new Date().toISOString(),
+            };
+            node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(info)}\n`, { encoding: "utf8", flag: "wx" });
+            return { acquired: true, lockPath, holder: null };
+        }
+        catch (error) {
+            if (!isFileExistsError(error)) {
+                throw error;
+            }
+        }
+        holder = readDaemonLock(lockPath);
+        if (holder != null && isLockHolderLive(holder)) {
+            return { acquired: false, lockPath, holder };
+        }
+        if (holder == null && isLockFileFresh(lockPath)) {
+            return { acquired: false, lockPath, holder: null };
+        }
+        cleanupFile(lockPath);
+    }
+    return { acquired: false, lockPath, holder };
+}
+/** Releases the lock only when it still belongs to the given pid. */
+function releaseDaemonLock(lockPath, pid) {
+    const holder = readDaemonLock(lockPath);
+    if (holder?.pid === pid) {
+        cleanupFile(lockPath);
+    }
+}
+function resolveStartTimeoutMs(env = process.env) {
+    const raw = env.AGENTINBOX_START_TIMEOUT_MS;
+    if (raw == null || raw.trim() === "") {
+        return DEFAULT_START_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_START_TIMEOUT_MS;
+}
+function isFileExistsError(error) {
+    return typeof error === "object" && error != null && error.code === "EEXIST";
+}
+function isLockFileFresh(lockPath) {
+    try {
+        return Date.now() - node_fs_1.default.statSync(lockPath).mtimeMs < STALE_LOCK_GRACE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Waits for the daemon holding the lock to serve healthz. Returns "lost" when
+ * the holder disappears without becoming ready so the caller can re-check
+ * admission instead of timing out.
+ */
+async function waitForDaemonReady(transport, lockPath, timeoutMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (await canReachHealthz(transport)) {
+            return "ready";
+        }
+        if (readLiveDaemonLockHolder(lockPath) == null) {
+            return "lost";
+        }
+        await sleep(100);
+    }
+    return "timeout";
+}
 function daemonChildArgs() {
     const execArgv = [...process.execArgv];
     return [...execArgv, process.argv[1], "serve"];
@@ -232,20 +421,20 @@ async function waitForHealthz(transport, timeoutMs) {
 async function waitForProcessExit(pid, timeoutMs) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
-        if (!isProcessAlive(pid)) {
+        if (!(0, util_1.isPidAlive)(pid)) {
             return;
         }
         await sleep(100);
     }
     throw new Error(`timed out waiting for process ${pid} to exit`);
 }
-function cleanupStalePidFile(pidPath, force = false) {
+function cleanupStalePidFile(pidPath) {
     const pid = readPidFile(pidPath);
     if (pid == null) {
         cleanupFile(pidPath);
         return;
     }
-    if (force || !isProcessAlive(pid)) {
+    if (!(0, util_1.isPidAlive)(pid)) {
         cleanupFile(pidPath);
     }
 }
@@ -325,15 +514,6 @@ function inferNodeVersionFromCommand(command) {
     const match = command.match(/node\/(v\d+\.\d+\.\d+)\//);
     return match ? match[1] : null;
 }
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function cleanupFile(filePath) {
     try {
         if (node_fs_1.default.existsSync(filePath)) {

package/dist/src/paths.js

@@ -7,6 +7,7 @@ exports.DEFAULT_AGENTINBOX_PORT = void 0;
 exports.resolveAgentInboxHome = resolveAgentInboxHome;
 exports.resolveServeConfig = resolveServeConfig;
 exports.resolveDaemonPaths = resolveDaemonPaths;
+exports.daemonLockPath = daemonLockPath;
 exports.resolveClientTransport = resolveClientTransport;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -74,6 +75,13 @@ function resolveDaemonPaths(env = process.env, homeDirOverride) {
         metadataPath: node_path_1.default.join(homeDir, "agentinbox.daemon.json"),
     };
 }
+/**
+ * Admission lock for the daemon serving a given socket. Scoped to the socket
+ * identity (not the home dir) so an explicit --socket gets its own lock.
+ */
+function daemonLockPath(socketPath) {
+    return `${socketPath}.lock`;
+}
 function resolveClientTransport(input = {}) {
     const env = input.env ?? process.env;
     const homeDir = resolveAgentInboxHome(env, input.homeDirOverride);

package/dist/src/service.js

@@ -2243,9 +2243,15 @@ class AgentInboxService {
                 return;
             }
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
+            // Within an active notify lease, buffered entries merge into the pending
+            // set (below) instead of re-dispatching. Webhook targets used to
+            // re-dispatch every flush window during the lease, which queued one
+            // wake per window downstream and produced empty wake turns when the
+            // consuming turn acked everything (issue #233). Merge semantics now
+            // match terminal targets: re-dispatch happens on ack (when pending new
+            // items exist) or lease expiry.
             const shouldAttemptDispatch = !state
-                || (state.status === "dirty" && state.leaseExpiresAt == null)
-                || (state.status === "notified" && buffer.targetKind === "webhook");
+                || (state.status === "dirty" && state.leaseExpiresAt == null);
             if (shouldAttemptDispatch) {
                 const pendingState = state?.status === "dirty" ? state : null;
                 const inbox = this.ensureInboxForAgent(buffer.agentId);
@@ -2427,6 +2433,13 @@ class AgentInboxService {
         if (reason === "ack" && state.status !== "dirty") {
             return;
         }
+        if (reason === "ack" && target.kind === "webhook" && state.pendingNewItemCount <= 0) {
+            // Ack-driven re-dispatch for webhook targets requires items that no
+            // previous notification covered. Without new information a POST would
+            // only wake the runtime about entries it already knows. Terminal
+            // targets keep ack-driven re-render behavior.
+            return;
+        }
         if (reason === "lease" && state.status === "notified") {
             // No new items since last notification — just renew lease for both
             // terminal and webhook targets. Re-dispatching would cause an infinite

package/dist/src/store.js

@@ -35,8 +35,10 @@ class AgentInboxStore {
         this.dbPath = dbPath;
         this.db = db;
     }
-    static async open(dbPath) {
+    static async open(dbPath, options = {}) {
+        const env = options.env ?? process.env;
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
+        removeOrphanBackupTmps(dbPath);
         const existedBeforeOpen = node_fs_1.default.existsSync(dbPath);
         let db = await this.openDatabaseWithRecovery(dbPath);
         let store = new AgentInboxStore(dbPath, db);
@@ -46,7 +48,7 @@ class AgentInboxStore {
             db = this.openDatabase(dbPath);
             store = new AgentInboxStore(dbPath, db);
         }
-        else if (existedBeforeOpen) {
+        else if (existedBeforeOpen && startupBackupEnabled(env)) {
             await store.backupHealthyDatabase();
         }
         store.migrate();
@@ -2382,3 +2384,40 @@ function uniqueSorted(values) {
 function summarizeBackfilledItemEntry(item) {
     return `${item.eventVariant} from ${item.sourceId}`;
 }
+function startupBackupEnabled(env) {
+    return !(0, util_1.isEnvFlagDisabled)(env.AGENTINBOX_STARTUP_BACKUP);
+}
+/**
+ * Removes leftover `<db>.bak.<pid>.tmp` files whose owning process is dead.
+ * Tmp files owned by a live pid belong to a concurrent open and are preserved.
+ */
+function removeOrphanBackupTmps(dbPath) {
+    const dir = node_path_1.default.dirname(dbPath);
+    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.bak\\.(\\d+)\\.tmp$`);
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        const match = pattern.exec(name);
+        if (!match) {
+            continue;
+        }
+        const pid = Number.parseInt(match[1], 10);
+        if (Number.isInteger(pid) && pid > 0 && (0, util_1.isPidAlive)(pid)) {
+            continue;
+        }
+        try {
+            node_fs_1.default.rmSync(node_path_1.default.join(dir, name), { force: true });
+        }
+        catch {
+            // Best-effort GC.
+        }
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/src/util.js

@@ -4,6 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nowIso = nowIso;
+exports.isPidAlive = isPidAlive;
+exports.isEnvFlagDisabled = isEnvFlagDisabled;
+exports.isEnvFlagEnabled = isEnvFlagEnabled;
 exports.generateCanonicalId = generateCanonicalId;
 exports.generateId = generateId;
 exports.generateShortToken = generateShortToken;
@@ -21,6 +24,32 @@ const ENTRY_THREAD_ID_PATTERN = new RegExp(`^(ent|thr)_[${CANONICAL_ID_ALPHABET}
 function nowIso() {
     return new Date().toISOString();
 }
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Treats an env flag as disabled only when it holds an explicit falsy word.
+ * Missing or empty values mean "unset" and keep the default behavior.
+ */
+function isEnvFlagDisabled(raw) {
+    if (raw == null) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off";
+}
+/**
+ * Treats an env flag as set only when it holds a non-empty, non-falsy value.
+ */
+function isEnvFlagEnabled(raw) {
+    return raw != null && raw.trim() !== "" && !isEnvFlagDisabled(raw);
+}
 function generateCanonicalId(prefix, length = CANONICAL_ID_TOKEN_LENGTH) {
     return `${prefix}_${generateShortToken(length)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {