sensorium-mcp 3.0.103 → 3.1.0-board.0

package/dist/services/passive-notice.service.js

@@ -0,0 +1,274 @@
+/**
+ * Passive-notice channel — "context, not command" (design §5).
+ *
+ * A general capability, independent of the board: notices pushed here are
+ * DRAINED into the next delivered turn of the target thread as an FYI block
+ * (message-delivery renders them next to the Persistent Context block). They
+ * never wake the agent and are never framed as tasks — the agent is aware,
+ * not commanded. This fixes the notification/command conflation of the
+ * pending-task inbox for updates that carry no instruction.
+ *
+ * Storage: per-thread JSON queue under ~/.remote-copilot-mcp/passive-notices/,
+ * write-then-rename (same durability pattern as schedules). Bounded to the
+ * most recent MAX_NOTICES entries.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log } from "../lib/logger.js";
+import { errorMessage } from "../lib/utils.js";
+const NOTICES_DIR = join(homedir(), ".remote-copilot-mcp", "passive-notices");
+const MAX_NOTICES = 10;
+function noticesFilePath(threadId) {
+    return join(NOTICES_DIR, `${threadId}.json`);
+}
+// ── Cross-process safety (H4 of the board kernel review) ───────────────────
+// Writers live in DIFFERENT OS processes (a worker's own MCP tool call vs the
+// server's orchestrator/cleanup loops). The bare read→modify→write→rename pair
+// is atomic only in the rename, so concurrent pushes were last-writer-wins and
+// a push landing inside drain's read→unlink window was destroyed. Same lock
+// pattern as dispatcher/lock.ts (wx-create + dead-pid/stale takeover), scoped
+// per thread; drain claims the file by atomic rename so a concurrent push
+// simply starts a fresh queue file and survives.
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 5;
+const LOCK_MAX_ATTEMPTS = 60;
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Acquire the per-thread mutation lock. Hold time is sub-millisecond (tiny
+ *  file ops), so bounded spinning is fine. Returns false only under pathological
+ *  contention — callers then proceed unlocked (a rare racy write beats losing
+ *  the notice outright). */
+function acquireNoticeLock(threadId) {
+    const lockPath = join(NOTICES_DIR, `${threadId}.lock`);
+    for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
+        try {
+            writeFileSync(lockPath, JSON.stringify({ pid: process.pid, ts: Date.now() }), {
+                encoding: "utf8",
+                flag: "wx",
+            });
+            return true;
+        }
+        catch {
+            try {
+                const holder = JSON.parse(readFileSync(lockPath, "utf8"));
+                if (!isPidAlive(holder.pid) || Date.now() - holder.ts > LOCK_STALE_MS) {
+                    unlinkSync(lockPath); // dead or stale holder — take over next attempt
+                    continue;
+                }
+            }
+            catch {
+                // Corrupt/vanished lock — remove and retry.
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* already gone */
+                }
+                continue;
+            }
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+    log.warn(`[passive-notice] lock contention for thread ${threadId} — proceeding unlocked`);
+    return false;
+}
+function releaseNoticeLock(threadId) {
+    const lockPath = join(NOTICES_DIR, `${threadId}.lock`);
+    try {
+        const holder = JSON.parse(readFileSync(lockPath, "utf8"));
+        if (holder.pid === process.pid)
+            unlinkSync(lockPath);
+    }
+    catch {
+        /* already gone or not ours */
+    }
+}
+function readNotices(threadId) {
+    const file = noticesFilePath(threadId);
+    try {
+        if (!existsSync(file))
+            return [];
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch (err) {
+        log.warn(`[passive-notice] Failed to read notices for thread ${threadId}: ${errorMessage(err)}`);
+        return [];
+    }
+}
+/** Queue an FYI notice for a thread's next delivered turn. Never wakes the agent. */
+export function pushPassiveNotice(threadId, text) {
+    try {
+        mkdirSync(NOTICES_DIR, { recursive: true });
+        const locked = acquireNoticeLock(threadId);
+        try {
+            const notices = readNotices(threadId);
+            notices.push({ text, createdAt: new Date().toISOString() });
+            // Bounded: keep only the freshest MAX_NOTICES — stale FYIs have no value.
+            const bounded = notices.slice(-MAX_NOTICES);
+            const file = noticesFilePath(threadId);
+            const tmp = `${file}.tmp.${process.pid}`;
+            writeFileSync(tmp, JSON.stringify(bounded, null, 2), "utf8");
+            renameSync(tmp, file);
+        }
+        finally {
+            if (locked)
+                releaseNoticeLock(threadId);
+        }
+    }
+    catch (err) {
+        log.warn(`[passive-notice] Failed to push notice for thread ${threadId}: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Read-and-clear (delivered-once semantics). Returns oldest→newest.
+ *
+ * Drain claims the queue file via atomic rename (under the same lock pushes
+ * take), so a push landing mid-drain writes a FRESH queue file and survives.
+ * Claims are per-pid; claims left by a crashed process are swept in too
+ * (redelivery of an FYI beats losing it).
+ */
+export function drainPassiveNotices(threadId) {
+    const file = noticesFilePath(threadId);
+    const claimPath = `${file}.claim.${process.pid}`;
+    const drained = [];
+    // Sweep litter left by crashed peers: claims orphaned by a dead drainer AND
+    // `.tmp.<pid>` half-writes left by a push that died between write and rename.
+    // Both are keyed by the writer's pid; anything owned by a gone pid is dead.
+    try {
+        const claimPrefix = `${threadId}.json.claim.`;
+        const tmpPrefix = `${threadId}.json.tmp.`;
+        for (const entry of readdirSync(NOTICES_DIR)) {
+            if (entry.startsWith(claimPrefix)) {
+                const pid = Number(entry.slice(claimPrefix.length));
+                if (!Number.isInteger(pid) || pid === process.pid || isPidAlive(pid))
+                    continue;
+                const orphanPath = join(NOTICES_DIR, entry);
+                try {
+                    const parsed = JSON.parse(readFileSync(orphanPath, "utf8"));
+                    if (Array.isArray(parsed))
+                        drained.push(...parsed);
+                }
+                catch {
+                    /* corrupt orphan — drop it */
+                }
+                try {
+                    unlinkSync(orphanPath);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            else if (entry.startsWith(tmpPrefix)) {
+                // A crashed push's temp file: its contents never became the live queue
+                // (the rename never ran), so it may be a partial write — discard rather
+                // than risk resurrecting corrupt/duplicate notices. Only reap dead pids
+                // so a concurrent live push's in-flight temp is never deleted.
+                const pid = Number(entry.slice(tmpPrefix.length));
+                if (!Number.isInteger(pid) || pid === process.pid || isPidAlive(pid))
+                    continue;
+                try {
+                    unlinkSync(join(NOTICES_DIR, entry));
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+        }
+    }
+    catch {
+        /* dir missing — nothing queued yet */
+    }
+    // A same-pid claim left by THIS process's earlier crashed drain (renamed but
+    // never consumed) would be silently clobbered by the rename below, losing its
+    // notices. Consume it first so the notices survive.
+    if (existsSync(claimPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(claimPath, "utf8"));
+            if (Array.isArray(parsed))
+                drained.push(...parsed);
+            unlinkSync(claimPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                log.warn(`[passive-notice] stale claim recovery failed for thread ${threadId}: ${errorMessage(err)}`);
+        }
+    }
+    if (existsSync(file)) {
+        const locked = acquireNoticeLock(threadId);
+        try {
+            renameSync(file, claimPath);
+        }
+        catch (err) {
+            log.debug(`[passive-notice] drain claim failed for thread ${threadId}: ${errorMessage(err)}`);
+        }
+        finally {
+            if (locked)
+                releaseNoticeLock(threadId);
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(claimPath, "utf8"));
+            if (Array.isArray(parsed))
+                drained.push(...parsed);
+            unlinkSync(claimPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                log.warn(`[passive-notice] drain read failed for thread ${threadId}: ${errorMessage(err)}`);
+        }
+    }
+    return drained;
+}
+/** Non-destructive peek (dashboard/diagnostics). */
+export function peekPassiveNotices(threadId) {
+    return readNotices(threadId);
+}
+/**
+ * Drain and render the FYI block appended to a delivered turn (next to the
+ * Persistent Context block in message-delivery). Empty string when quiet.
+ * The framing does the "aware, not commanded" work: explicit no-action wording
+ * so a later operator voice about these makes sense without triggering work.
+ */
+export function renderPassiveNoticeBlock(threadId) {
+    const notices = drainPassiveNotices(threadId);
+    if (notices.length === 0)
+        return "";
+    // Per-item fault isolation: one malformed record (bad createdAt, non-string
+    // text) must not throw AFTER the drain already consumed the batch — that
+    // would lose every notice in the turn. Bad records are skipped, not fatal.
+    const lines = [];
+    for (const n of notices) {
+        try {
+            const stamp = typeof n.createdAt === "string" ? n.createdAt.slice(0, 16).replace("T", " ") : "?";
+            if (typeof n.text !== "string" || n.text.length === 0)
+                continue;
+            lines.push(`- [${stamp}] ${n.text}`);
+        }
+        catch {
+            /* skip malformed record */
+        }
+    }
+    if (lines.length === 0)
+        return "";
+    // Delivery-loss note: drain happens at render time, inside the poll loop's
+    // transport-liveness guards — the same consumption bar the system applies to
+    // operator messages themselves. A deeper delivered-ack protocol was reviewed
+    // and deliberately not built (FYI notices must not carry more delivery
+    // guarantees than operator messages do).
+    return (`\n\n## Situational Notices (FYI — context, not command)\n` +
+        `These are awareness-only updates. Do NOT act on them, reply to them, or treat them as tasks; ` +
+        `they exist so later operator messages about them make sense.\n` +
+        lines.join("\n"));
+}
+//# sourceMappingURL=passive-notice.service.js.map

package/dist/services/passive-notice.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-notice.service.js","sourceRoot":"","sources":["../../src/services/passive-notice.service.ts"],"names":[],"mappings":"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"}

package/dist/services/process.service.d.ts

@@ -30,11 +30,28 @@ export declare const clearTaskConsumed: (threadId: number) => void;
 /** Delete a worker's pending-task mailbox (and any in-flight .processing temp)
  *  so a retired worker can never be re-fed a late append. */
 export declare function deletePendingTaskMailbox(threadId: number): void;
-export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Liveness + identity in one question: is `pid` alive AND (when `spawnedAtMs`
+ * is given) still the process we spawned?
+ *
+ * Two-step check, neither of which ever spawns a child process:
+ *   1. `process.kill(pid, 0)` — a plain syscall. ESRCH (any non-EPERM error) is
+ *      a definitive "dead" and needs no broker (this also keeps dev mode
+ *      without a supervisor fully functional for the common case).
+ *   2. Otherwise the answer is NOT trustworthy on Windows — kill(0) succeeds
+ *      for kernel-zombie PIDs held open by a lingering handle, and EPERM is
+ *      what a parent sees for its own terminated child. Ask the supervisor's
+ *      process broker, which answers from a native process snapshot and also
+ *      verifies creation-time identity (PID-reuse guard).
+ *
+ * Broker unreachable → "cannot confirm → treat alive", exactly the audited-safe
+ * degradation the deleted tasklist/Get-Process breakers had.
+ */
+export declare function isProcessAlive(pid: number, spawnedAtMs?: number): Promise<boolean>;
 export declare function readPidFiles(): PidFileEntry[];
-export declare function findAliveThread(threadId: number): SpawnedThread | undefined;
-export declare const isThreadRunning: (threadId: number) => boolean;
-export declare function getActiveThreadIds(): number[];
+export declare function findAliveThread(threadId: number): Promise<SpawnedThread | undefined>;
+export declare const isThreadRunning: (threadId: number) => Promise<boolean>;
+export declare function getActiveThreadIds(): Promise<number[]>;
 export declare function ensureDirs(): void;
 /** Thread transcripts (logs/threads/*.json) are append-only debug artifacts with
  *  one file per thread per day. Nothing consumes them at runtime except the
@@ -47,10 +64,15 @@ export declare function ensureDirs(): void;
 export declare function pruneOldThreadLogs(): void;
 /**
  * Check liveness of a thread directly via its PID file, bypassing the
- * spawnedThreads[] in-memory cache.  Returns the live PID, or undefined
- * if no PID file exists or the process is dead (stale file is deleted).
+ * spawnedThreads[] in-memory cache. Returns the live PID together with its
+ * recorded spawn identity (startedAt) so callers can make identity-checked
+ * kill/alive calls, or undefined if no PID file exists or the process is dead
+ * (stale file is deleted).
  */
-export declare function findAliveThreadViaPidFile(threadId: number): number | undefined;
+export declare function findAliveThreadViaPidFile(threadId: number): Promise<{
+    pid: number;
+    startedAt?: number;
+} | undefined>;
 /**
  * Reconcile in-memory state (spawnedThreads[]) with the two authoritative
  * sources of truth at startup:
@@ -59,7 +81,19 @@ export declare function findAliveThreadViaPidFile(threadId: number): number | un
  *
  * Replaces the old restoreFromPidFiles() + cleanupStalePidFiles() pair.
  */
-export declare function reconcileState(db: Database, threadLifecycle: ThreadLifecycleService): void;
-export declare function killProcessTree(pid: number, threadId: number, caller?: string): Promise<void>;
+export declare function reconcileState(db: Database, threadLifecycle: ThreadLifecycleService): Promise<void>;
+/**
+ * Kill the process tree rooted at `pid` via the supervisor's broker (native
+ * TerminateProcess over the whole tree, identity-checked when `spawnedAtMs` is
+ * given, outcome recorded in the broker's on-disk registry). Never spawns a
+ * child process and never blocks the event loop.
+ *
+ * Broker unreachable → degraded best-effort: one native `process.kill(pid)`
+ * (root only — Node cannot enumerate a tree without shelling out, and that
+ * machinery is gone by design) followed by a conservative liveness re-check.
+ * A survived kill keeps the PID file so the keeper/cleanup policy loops retry
+ * and escalate — same contract as before.
+ */
+export declare function killProcessTree(pid: number, threadId: number, caller?: string, spawnedAtMs?: number): Promise<void>;
 export {};
 //# sourceMappingURL=process.service.d.ts.map

package/dist/services/process.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.service.d.ts","sourceRoot":"","sources":["../../src/services/process.service.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAoB5E,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AACjE,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,eAAO,MAAM,eAAe,QAA4B,CAAC;AACzD,eAAO,MAAM,gBAAgB,QAAW,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAClC;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,aAAa,EAAO,CAAC;AAYlD,eAAO,MAAM,gBAAgB,GAAI,UAAU,MAAM,KAAG,IAA8C,CAAC;AACnG,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAA4C,CAAC;AAChG,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,IAAiD,CAAC;AAEvG;6DAC6D;AAC7D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAuBnD;AAkKD,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAuB7C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAc3E;AAED,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAAkD,CAAC;AAEtG,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAW7C;AAED,wBAAgB,UAAU,IAAI,IAAI,CAMjC;AAED;;;;;;;uCAOuC;AACvC,wBAAgB,kBAAkB,IAAI,IAAI,CAczC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ9E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,sBAAsB,GAAG,IAAI,CA8D1F;AAUD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoF7F"}
+{"version":3,"file":"process.service.d.ts","sourceRoot":"","sources":["../../src/services/process.service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAuB5E,eAAO,MAAM,iBAAiB,QAAkC,CAAC;AACjE,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,eAAO,MAAM,eAAe,QAA4B,CAAC;AACzD,eAAO,MAAM,gBAAgB,QAAW,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAClC;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,aAAa,EAAO,CAAC;AAYlD,eAAO,MAAM,gBAAgB,GAAI,UAAU,MAAM,KAAG,IAEnD,CAAC;AACF,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAA4C,CAAC;AAChG,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,IAEpD,CAAC;AAEF;6DAC6D;AAC7D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxF;AAED,wBAAgB,YAAY,IAAI,YAAY,EAAE,CAiC7C;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CA2B1F;AAED,eAAO,MAAM,eAAe,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CACvB,CAAC;AAElD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAW5D;AAED,wBAAgB,UAAU,IAAI,IAAI,CAMjC;AAED;;;;;;;uCAOuC;AACvC,wBAAgB,kBAAkB,IAAI,IAAI,CAsBzC;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAY1D;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,QAAQ,EACZ,eAAe,EAAE,sBAAsB,GACtC,OAAO,CAAC,IAAI,CAAC,CA4Hf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAgEf"}