@rubytech/create-realagent-code 0.1.614 → 0.1.616

package/payload/platform/plugins/dispatch/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

package/payload/platform/plugins/docs/references/aeo.md

@@ -21,7 +21,7 @@ Returns the parsed JSON-LD object and a ready-to-inline script block string. Inl
 
 ### `aeo-write-llms-txt`
 
-Generates the `llms.txt` / `llms-full.txt` pair for the account. Source is every `KnowledgeDocument` for the account that has a `url` property. Returns both files as strings plus a count of pages skipped because they had no URL.
+Generates the `llms.txt` / `llms-full.txt` pair for one site. Pass `siteOrigin` (e.g. `https://maxy.institute`); source is every `KnowledgeDocument` for the account whose `url` starts with it. `llms-full.txt` carries each page's prose from its `:Section` chain, in reading order. Returns both files as strings, plus counts of pages skipped for having no URL, pages skipped as belonging to another site, and pages that carried no full text. If no page carried full text, `llms.txt` is written and `llms-full.txt` is refused rather than filled with the index's own summaries.
 
 Wire the output to your site host. Convention: `/llms.txt` (index) and `/llms-full.txt` (concatenated content), served as `text/plain`. Format follows the current draft at `https://llmstxt.org/`.
 
@@ -68,7 +68,9 @@ Pass `persist: true` plus `targetKnowledgeDocumentId` to write the result as an
 Every tool emits a single log line per invocation:
 
 - `[aeo-emit-jsonld] entityId=… schemaType=… source=graph|inline`
-- `[aeo-llms-txt] site=… pages=… skippedNoUrl=… indexBytes=… fullBytes=…`
+- `[aeo-llms-txt] site=… origin=… pages=… skippedNoUrl=… skippedOtherSite=… pagesWithFullText=… pagesWithoutFullText=… sections=… indexBytes=… fullBytes=…`
+- `[aeo-llms-txt] WARN op=full-text-missing pages=… shown=… urls=[…]` — pages that reached the file with only a summary behind them.
+- `[aeo-llms-txt] refuse op=write-full reason=no-full-text-any-page site=…` — `llms-full.txt` was left untouched.
 - `[aeo-audit] target=… score=… fails=… warns=…`
 
 Diagnostic path: `grep -E '^\[aeo-' platform-logs/*.log | grep <urlOrEntityId>`.
@@ -77,7 +79,6 @@ Diagnostic path: `grep -E '^\[aeo-' platform-logs/*.log | grep <urlOrEntityId>`.
 
 - **No citation monitor — out of scope.** Tracking whether your brand is cited by Claude / ChatGPT / Perplexity / Gemini would require multi-engine answer harvesting that doesn't fit maxy-code's no-API-key architecture. Archived without sprinting. Check citation manually when needed.
 - **No auto-emission on page render.** `aeo-emit-jsonld` is callable on demand. Wiring it into the platform's page-generator render path is per-renderer work, filed as a follow-up.
-- **No publish-hook regeneration of `llms.txt`.** The tool runs on demand. Hooking it into the publish event is a follow-up.
 
 ## See also
 

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -89,7 +89,7 @@ There is no per-account purchase record; the brand decides the shipping set.
 | Plugin | Type | What it does | Public agent |
 |--------|------|-------------|-------------|
 | `teaching` | Skills | Interactive tutoring, lesson planning, and study pack generation from your knowledge base | Yes — all 3 skills serve students and parents |
-| `real-agent` | Bundle (13 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM (five value pillars: auto-respond, viewing lifecycle, pipeline mining, listings prospecting, maintenance & preferences), PropertyData market analytics (valuation, sold prices, £/sqft baselines, £/sqft growth, demand-rent, area risk, planning precedent, UPRN matching, property-type distribution), gov.uk EPC floor-area lookup, property brochures, social-share image cards, A4 market reports, and single-address preval packs (full UK address → 4-page A4 PDF covering valuation, area, and demand). 3 specialist roles (negotiator, valuer, compliance) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching) |
+| `real-agent` | Bundle (13 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM (five value pillars: auto-respond, viewing lifecycle, pipeline mining, listings prospecting, maintenance & preferences; every read states which Loop API version it reached and can return the raw field set received from Loop, so a figure of zero is never mistaken for one nobody entered), PropertyData market analytics (valuation, sold prices, £/sqft baselines, £/sqft growth, demand-rent, area risk, planning precedent, UPRN matching, property-type distribution), gov.uk EPC floor-area lookup, property brochures, social-share image cards, A4 market reports, and single-address preval packs (full UK address → 4-page A4 PDF covering valuation, area, and demand). 3 specialist roles (negotiator, valuer, compliance) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching) |
 | `writer-craft` | Skills + Agent | Manuscript review and writing craft — story architecture, reader engagement, prose craft, editorial practice, and multi-level review | No — writing craft serves the author |
 | `venture-studio` | Skills + Agent | Founding-a-business workflow — office-hours discovery, brand pack, zero-to-prototype validation, the full investor data room (business plan, prospectus, term sheet, deck blueprint, A4 print pipeline), and a `legal-essentials` skill that drafts an NDA and a UK-GDPR/PECR privacy policy. Carries citation-routed method references for market sizing (TAM/SAM/SOM), pricing, monetization, competitor analysis, battlecards, strategy frameworks (SWOT/PESTLE/Porter's/Ansoff), and a pre-fundraise strategy red-team. Pre-seeds a `Project` with one `Task` per artefact so nothing gets forgotten. | No — founder-facing only |
 | `management-consulting` | Skills | 21 MBB-style strategy skills for client engagements — situation assessment, growth-barrier and assumption diagnosis, market mapping, competitive intel, segmentation, profit-pool analysis, strategic options, pricing, business cases, portfolio review, operating-model design, initiative prioritization, transformation roadmaps, war-gaming, risk registers, KPI design, value realization, stakeholder alignment, executive narrative, and decision memos. No MCP server. | No — consultant-facing only |

package/payload/platform/plugins/email/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

package/payload/platform/plugins/filesystem/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