@rubytech/create-sitedesk-code 0.1.615 → 0.1.616

package/payload/platform/services/claude-session-manager/dist/mcp-helper-census.js

@@ -0,0 +1,201 @@
+// Task 2787 — the standing dark-helper check. Task 710's central deliverable
+// (`mcp-helper-reconcile.ts`) was never written — `git log --all --` on that
+// path returns nothing, though 710 is Archived and the observability doc cited
+// it as live cover — so a plugin MCP server could go dark for hours and the
+// operator learned of it only when the agent happened to call the tool, failed,
+// and said so on Telegram.
+//
+// It reads FILE TRUTH, not the session JSONL. 710's design tailed the
+// transcript for `Connection closed` / `No such tool available`; those strings
+// are the agent's symptom, not the helper's state, and they appear only if the
+// agent happens to call the tool. The spawn-tee already writes the helper's own
+// lifecycle line to `${LOG_DIR}/mcp-<server>-<sessionId>.log` at the instant it
+// happens, so the last such line IS the server's state.
+//
+// Not covered, by construction: the alive-but-wedged helper that emits no
+// process exit and no fatal. This census reads lifecycle truth, so a server
+// that never exits is outside it. That was 710's stated target and remains
+// uncovered.
+//
+// Shape mirrors public-surface-audit.ts: PURE parsers and formatter (no I/O,
+// unit-tested) + an injectable IO surface + a start/stop factory whose
+// setInterval is unref'd and cleared on shutdown.
+import { readFileSync, readdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseMcpLogServerName } from './public-surface-audit.js';
+const TAG = '[mcp-helper-census]';
+/** Bytes read from the end of each per-session log. For a DEAD server the
+ *  lifecycle line is the last thing in the file, so a small window always finds
+ *  it. For a live chatty server the window may hold only stderr and no
+ *  lifecycle line, which classifies healthy — correct, because only a live
+ *  server writes stderr. */
+export const TAIL_BYTES = 16384;
+/** PURE. The last `[mcp-helper]` lifecycle line in a tail, or null when the
+ *  window holds none. Taking the LAST line is the whole "with no later
+ *  op=spawn" rule: a respawn writes op=spawn after the exit it followed, and
+ *  that spawn is then the last line. */
+export function lastLifecycleLine(tail) {
+    const lines = tail.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const l = lines[i];
+        if (l.startsWith('[mcp-helper] op='))
+            return l;
+    }
+    return null;
+}
+/** PURE. Whether a server whose last lifecycle line is this one has gone dark.
+ *
+ *  Task 2788 — an `op=fatal` is dark only when `disposition=exit`, because a
+ *  fatal no longer always kills: one arriving on a connected transport is
+ *  recorded and survived, and reporting that as dark would name a serving
+ *  helper in a dark list. `deferred=yes` is likewise not dark — the entry
+ *  installed its own handler and decided to survive, as the email plugin does
+ *  for imapflow and nodemailer socket errors. Either way, when the process does
+ *  then die, an op=exit follows and becomes the last line, which is dark on its
+ *  own terms.
+ *
+ *  A line carrying no `disposition=` at all was written by the Task 2787 shim,
+ *  where `deferred=no` always exited, and is read that way. That is reachable
+ *  only for a session already live when the install upgraded.
+ *
+ *  The space-delimited tests are load-bearing: the shim's `op=fatal-stack`
+ *  header shares the tag, and a loose `op=fatal` test would classify a stack
+ *  block as a state. */
+export function classifyLifecycleLine(line) {
+    if (line.includes(' op=exit ')) {
+        const sig = /\bsignal=(\S+)/.exec(line)?.[1];
+        if (sig && sig !== '—')
+            return { dark: true, reason: 'exit-signal' };
+        const code = /\bcode=(\S+)/.exec(line)?.[1];
+        if (code !== undefined && code !== '—' && code !== '0')
+            return { dark: true, reason: 'exit-code' };
+        return { dark: false };
+    }
+    if (line.includes(' op=fatal ')) {
+        // Field-anchored, like the code=/signal= reads above: the error= payload
+        // carries an arbitrary message, and a bare substring test would let a
+        // message quoting the field flip the classification.
+        const disposition = /\bdisposition=(\S+)/.exec(line)?.[1];
+        if (disposition !== undefined) {
+            return disposition === 'exit' ? { dark: true, reason: 'fatal' } : { dark: false };
+        }
+        return line.includes('deferred=no') ? { dark: true, reason: 'fatal' } : { dark: false };
+    }
+    if (line.includes(' op=error '))
+        return { dark: true, reason: 'import-error' };
+    return { dark: false };
+}
+/** PURE. One dark server. `last` is JSON-quoted so the line it carries — which
+ *  itself contains spaces and its own quoted stderr-tail — cannot be mistaken
+ *  for further fields. */
+export function formatMcpHelperCensusDark(p) {
+    return (`${TAG} session=${p.sessionId.slice(0, 8)} dark=[${p.server}] ` +
+        `reason=${p.reason} last=${JSON.stringify(p.last)}`);
+}
+/** Reads the spawn-tee's own sinks under `logDir`. Session liveness is injected
+ *  rather than imported so this module holds no dependency on the PTY tracker. */
+export function defaultMcpHelperCensusIo(logDir, listSessionIds) {
+    return {
+        listSessionIds,
+        serversForSession(sessionId) {
+            try {
+                return readdirSync(logDir)
+                    .map((f) => parseMcpLogServerName(f, sessionId))
+                    .filter((s) => s !== null);
+            }
+            catch {
+                return [];
+            }
+        },
+        readLogTail(sessionId, server, maxBytes) {
+            const path = join(logDir, `mcp-${server}-${sessionId}.log`);
+            let fd;
+            try {
+                const size = statSync(path).size;
+                if (size <= maxBytes)
+                    return readFileSync(path, 'utf8');
+                // A raw stderr sink can be tens of MB; read only the window.
+                const buf = Buffer.allocUnsafe(maxBytes);
+                fd = openSync(path, 'r');
+                const read = readSync(fd, buf, 0, maxBytes, size - maxBytes);
+                return buf.subarray(0, read).toString('utf8');
+            }
+            catch {
+                return null;
+            }
+            finally {
+                if (fd !== undefined) {
+                    try {
+                        closeSync(fd);
+                    }
+                    catch {
+                        /* already closed */
+                    }
+                }
+            }
+        },
+    };
+}
+export function createMcpHelperCensus(deps) {
+    // `<sessionId>|<server>` -> the reason already logged, so a steady-state dark
+    // server logs once rather than every 60s for the life of the session; a
+    // changed reason re-logs. Pruned when the pair is no longer dark or the
+    // session is no longer live. Same rule, and same reasoning, as
+    // public-surface-audit.ts's loggedBreach map.
+    const logged = new Map();
+    let timer = null;
+    function tickOnce() {
+        const seen = new Set();
+        for (const sessionId of deps.io.listSessionIds()) {
+            for (const server of deps.io.serversForSession(sessionId)) {
+                const tail = deps.io.readLogTail(sessionId, server, TAIL_BYTES);
+                if (tail === null)
+                    continue;
+                const last = lastLifecycleLine(tail);
+                if (last === null)
+                    continue;
+                const verdict = classifyLifecycleLine(last);
+                const key = `${sessionId}|${server}`;
+                if (!verdict.dark) {
+                    logged.delete(key);
+                    continue;
+                }
+                seen.add(key);
+                if (logged.get(key) === verdict.reason)
+                    continue;
+                deps.logger(formatMcpHelperCensusDark({ sessionId, server, reason: verdict.reason, last }));
+                logged.set(key, verdict.reason);
+            }
+        }
+        for (const key of logged.keys())
+            if (!seen.has(key))
+                logged.delete(key);
+    }
+    return {
+        tickOnce,
+        start() {
+            if (timer)
+                return;
+            timer = setInterval(() => {
+                try {
+                    tickOnce();
+                }
+                catch (err) {
+                    deps.logger(`${TAG} op=census-tick-failed message=${err instanceof Error ? err.message : String(err)}`);
+                }
+            }, deps.intervalMs);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            // The per-tick line is silent while healthy, so without this a census
+            // that never started is indistinguishable from one finding nothing.
+            deps.logger(`${TAG} op=census-started intervalMs=${deps.intervalMs}`);
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=mcp-helper-census.js.map

package/payload/platform/services/claude-session-manager/dist/mcp-helper-census.js.map

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

package/payload/premium-plugins/sitedesk/plugins/sitedesk-job/lib/mcp-spawn-tee/index.js

@@ -25,10 +25,13 @@
  *   - `server.log` via the loopback log-ingest route — best-effort mirror of
  *     the [mcp-helper] lifecycle lines.
  *
- * Lifecycle lines, correlation key `session=<id8> server=<name>` — unchanged:
+ * Lifecycle lines, correlation key `session=<id8> server=<name>`:
  *   [mcp-helper] op=spawn ... pid= entry=
  *   [mcp-helper] op=boot  ... head=<first stderr bytes>
  *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=
+ *   [mcp-helper] op=fatal ... kind=uncaught|rejection deferred=yes|no
+ *                              disposition=survived|exit error=
+ *     preceded by an `op=fatal-stack` block carrying the full stack (Task 2787).
  *
  * Process model (Task 989): the shim IS the server's process. op=exit fires
  * from process.on("exit"), so it covers a normal exit, a non-zero exit, an
@@ -37,6 +40,17 @@
  * and leaves no op=exit line — the per-session stderr tail already on disk and
  * Claude Code's own transport-drop are the evidence for that death mode.
  *
+ * op=exit records THAT a fatal killed the process; it never records WHICH one,
+ * because Node's fatal printer writes beneath the tee (Task 2787). The op=fatal
+ * pair is what names the error.
+ *
+ * Task 2788 — a fatal no longer always kills. `disposition=` says what the guard
+ * did: the shim exits 1 only when it is the sole listener for the event AND no
+ * stdio transport is connected. A fatal on a connected transport is recorded
+ * and survived, because Claude Code's policy after a helper dies is one
+ * reconnect then stop, so killing a live server removes its whole tool surface
+ * for the rest of the session.
+ *
  * The shim never writes to fd 1 (stdout) — that is the JSON-RPC channel.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -114,14 +128,22 @@ function postToServerLog(suffix, level) {
 // Claude Code visibility, never re-teed), and a best-effort server.log mirror.
 // `suffix` is the line body after the tag and carries no newline (the
 // log-ingest route rejects newlines).
-function emitLifecycle(suffix, level) {
+//
+// Task 2787 — `mirror` is false for op=exit and op=fatal. Both fire while the
+// loop is stopping, so the async fetch cannot flush: server.log held 2 op=exit
+// lines against 160 op=spawn and 135 op=boot. The sync raw sink is the
+// authoritative carrier for those two; posting them was a near-total loss
+// dressed as a mirror. op=spawn/op=boot/op=error keep it — they fire while the
+// loop is live and land.
+function emitLifecycle(suffix, level, mirror = true) {
     const line = `[mcp-helper] ${suffix}\n`;
     appendSafe(rawSinkPath, line);
     try {
         rawStderrWrite(line);
     }
     catch { /* stderr closed */ }
-    postToServerLog(suffix, level);
+    if (mirror)
+        postToServerLog(suffix, level);
 }
 if (!ENTRY) {
     emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
@@ -165,6 +187,97 @@ function onSignal(sig, code) {
 process.on("SIGTERM", onSignal("SIGTERM", 143));
 process.on("SIGINT", onSignal("SIGINT", 130));
 process.on("SIGHUP", onSignal("SIGHUP", 129));
+// Task 2787 — the fatal guard. Three measured facts drove it here rather than
+// into the 26 plugin entries: Node's default fatal printer writes to fd 2
+// BENEATH the JS `process.stderr.write` the tee replaces, so on both 18 Aug
+// deaths the stack reached neither the raw sink nor Claude Code's own
+// `Server stderr:` capture; the shim is the single seam every entry already
+// loads through; and 26 copies would have to stay in step for ever.
+//
+// The stack is written through appendSafe and rawStderrWrite directly, never
+// through teeWrite — the tee is the thing that was blind to it.
+/** The three fields a fatal contributes. A rejection reason need not be an
+ *  Error, in which case there is no stack and the stringified reason stands in
+ *  for all three. */
+function describeFatal(err) {
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message, stack: err.stack ?? `${err.name}: ${err.message}` };
+    }
+    const s = String(err);
+    return { name: typeof err, message: s, stack: s };
+}
+/** Write a fatal's full stack as its own block, before the lifecycle line that
+ *  summarises it. Multi-line by nature, which is why it is not a field on that
+ *  line. Goes through appendSafe and the RAW writer — never teeWrite, which is
+ *  the thing Node's own fatal printer writes beneath. */
+function writeFatalStack(kind, stack) {
+    const block = `[mcp-helper] op=fatal-stack session=${SESSION_ID8} server=${SERVER_NAME} kind=${kind}\n${stack}\n`;
+    appendSafe(rawSinkPath, block);
+    try {
+        rawStderrWrite(block);
+    }
+    catch { /* stderr closed */ }
+}
+/** Task 2788 — has a stdio transport connected in this process?
+ *
+ *  `server.connect(transport)` calls `StdioServerTransport.start()`, whose body
+ *  is `this._stdin.on("data", …)`. So a stdin `data` listener exists if and only
+ *  if a stdio transport has started, and `close()` removes it again — a fatal
+ *  after the transport closed correctly reads as not connected.
+ *
+ *  Read at the moment of the fatal rather than latched at first connect, so a
+ *  transport that has since closed is not remembered as live. Nothing is
+ *  patched: all 26 plugin entries construct a StdioServerTransport and none
+ *  reads stdin itself, so this listener has exactly one source. The three
+ *  channel services carry no stdio transport, so every fatal in them still
+ *  exits — unchanged from before this task. */
+function transportConnected() {
+    return process.stdin.listenerCount("data") > 0;
+}
+// Task 2788 — the disposition. `disposition=` names what THIS guard did with
+// the process: `exit` means it called process.exit(1); `survived` means it
+// returned and left the process running.
+//
+// Claude Code owns the spawn (Task 706: no ChildProcess handle; Task 989: the
+// shim IS the server process) and its post-failure policy is one reconnect then
+// stop — measured on 18 Aug, when the retry died the same way 2.6s in and the
+// CLI never spawned again, leaving that session with `No such tool available`
+// for the rest of its life. Nothing in this tree can change that policy, so not
+// dying is the only mechanism available.
+//
+// The boundary is the connect, not a time window, because that is the fact that
+// separates "a live server hit a bad request" from "this server never came up".
+// Masking the second as the first would replace a visible outage with a silent
+// one.
+//
+//   * another listener present -> record and STAND DOWN, exactly as before. The
+//     email plugin installs its own pair (plugins/email/mcp/src/lib/setup-probe.ts)
+//     and deliberately survives errors it attributes to imapflow/nodemailer.
+//     The guard does not exit, so disposition=survived; if that handler then
+//     exits, the op=exit line that follows is the death record, and the census
+//     reads it as dark on its own terms.
+//   * sole listener, transport connected -> record and keep serving.
+//   * sole listener, no transport -> exit 1, which is Node's own default for an
+//     uncaught throw and (Node >= 15) for an unhandled rejection.
+//
+// The stack is written either way: surviving must not cost the diagnosis, which
+// is what Task 2787 exists to preserve.
+function onFatal(event, kind) {
+    return (err) => {
+        const sole = process.listenerCount(event) === 1;
+        const exiting = sole && !transportConnected();
+        const d = describeFatal(err);
+        // The stack first, so it is on disk before anything else can fail.
+        writeFatalStack(kind, d.stack);
+        emitLifecycle(`op=fatal session=${SESSION_ID8} server=${SERVER_NAME} kind=${kind} ` +
+            `deferred=${sole ? "no" : "yes"} disposition=${exiting ? "exit" : "survived"} ` +
+            `error=${JSON.stringify(JSON.stringify({ name: d.name, message: d.message }))}`, "error", false);
+        if (exiting)
+            process.exit(1);
+    };
+}
+process.on("uncaughtException", onFatal("uncaughtException", "uncaught"));
+process.on("unhandledRejection", onFatal("unhandledRejection", "rejection"));
 // op=exit, emitted once from the process "exit" event. Sync-only — the loop is
 // stopping. When a catchable signal caused the exit, report code=— signal=<sig>
 // to match the prior wrapper's format; otherwise code=<exit code> signal=—.
@@ -177,7 +290,7 @@ process.on("exit", (code) => {
     const codeField = exitSignal ? "—" : String(code);
     const level = exitSignal || code !== 0 ? "error" : "info";
     emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} ` +
-        `code=${codeField} signal=${exitSignal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+        `code=${codeField} signal=${exitSignal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level, false);
 });
 emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} entry=${ENTRY}`, "info");
 // Task 2356 — present argv as a direct `node <entry>` invocation before the
@@ -194,11 +307,20 @@ process.argv = [process.argv[0], ENTRY, ...process.argv.slice(3)];
 // Run the real MCP server in THIS process. Dynamic import() (not top-level
 // await — this file compiles to CommonJS) loads the ESM entry; a load-time
 // failure mirrors the old child spawn-error path (op=error, exit 127). The
-// op=exit handler is suppressed on this path so op=error stays the sole record.
+// op=exit handler is suppressed on this path so op=error stays the sole
+// lifecycle record.
+//
+// Task 2787 — this .catch() settles the rejection, so a throw during the
+// entry's module EVALUATION never reaches the uncaughtException guard above.
+// The stack is written here explicitly; without it a boot-time death leaves
+// its message on the op=error line and nothing else — no type, no frames. The
+// op=error line itself is unchanged: `describeFatal().message` is the same
+// value the old inline expression produced.
 import((0, node_url_1.pathToFileURL)(ENTRY).href).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
+    const d = describeFatal(err);
     exitEmitted = true;
-    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`import error: ${msg}`)}`, "error");
+    writeFatalStack("import", d.stack);
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`import error: ${d.message}`)}`, "error");
     process.exit(127);
 });
 //# sourceMappingURL=index.js.map