@rubytech/create-maxy-code 0.1.295 → 0.1.297

package/payload/platform/plugins/browser/lib/mcp-spawn-tee/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — parent-side stderr capture + lifecycle observability.
+ *
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This wrapper sits between Claude Code and the real
+ * MCP server: Claude Code runs `node <this> <real-entry>`, and the wrapper
+ * spawns the real entry with `stdio:['inherit','inherit','pipe']` so stdin
+ * and stdout (the JSON-RPC channel) pass through byte-identical. Only stderr
+ * is intercepted, and only for logging.
+ *
+ * Because the wrapper IS the helper's parent, it observes the helper's true
+ * exit code, signal, and lifetime for every death mode — including a SIGKILL
+ * or a transport-layer crash that an in-process handler would miss.
+ *
+ *   Claude Code CLI → wrapper (this file) → child = node <real-entry>
+ *        child stdin/stdout : inherited (Claude Code pipe, untouched)
+ *        child stderr       : piped → per-date log + per-session log + passthrough
+ *
+ * Destinations (Task 706):
+ *   - `${LOG_DIR}/mcp-<name>-stderr-<date>.log`  — per-date raw (back-compat;
+ *     the in-process mcp-stderr-tee and the [mcp-init-error] probe read it).
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — per-session raw + lifecycle
+ *     lines; wrapper-only, so it never mixes the enumeration copy with the
+ *     live copy. Authoritative sink. Absent when SESSION_ID is unset
+ *     (enumeration spawn) — then the per-date file is the fallback.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines. A dropped POST loses nothing because
+ *     the per-session file already holds the line (written synchronously).
+ *
+ * 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=   (always)
+ *
+ * The wrapper never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ * SIGTERM/SIGINT are forwarded to the child so a Claude Code shutdown does
+ * not orphan it; the child exit code/signal is propagated verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+const ENTRY = process.argv[2];
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+// Per-session raw + lifecycle log (Task 706). Wrapper-only. Empty SESSION_ID
+// (enumeration spawn) → undefined, and the per-date file is the fallback.
+const perSessionPath = LOG_DIR && SESSION_ID
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-${SESSION_ID}.log`)
+    : undefined;
+const perDatePath = LOG_DIR
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${new Date(spawnStamp).toISOString().slice(0, 10)}.log`)
+    : undefined;
+// Rolling tail of child stderr for op=exit. Capped so a chatty child cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+function appendSafe(path, data) {
+    if (!path || !LOG_DIR)
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+        (0, node_fs_1.appendFileSync)(path, data);
+    }
+    catch {
+        /* unwritable destination — never mask primary output */
+    }
+}
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative,
+// so a dropped POST (unreachable port, process exiting) loses nothing.
+function postToServerLog(suffix, level) {
+    if (!PLATFORM_PORT)
+        return;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 500);
+        t.unref?.(); // never let the abort timer keep the wrapper's event loop alive
+        void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+            signal: ctrl.signal,
+        }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
+    }
+    catch {
+        /* fetch threw synchronously — best-effort only */
+    }
+}
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the wrapper's own stderr (journald / Claude Code
+// visibility), 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) {
+    const line = `[mcp-helper] ${suffix}\n`;
+    appendSafe(perSessionPath, line);
+    try {
+        process.stderr.write(line);
+    }
+    catch { /* stderr closed */ }
+    postToServerLog(suffix, level);
+}
+if (!ENTRY) {
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
+    process.exit(2);
+}
+const child = (0, node_child_process_1.spawn)(process.execPath, [ENTRY], {
+    stdio: ["inherit", "inherit", "pipe"],
+    env: process.env,
+});
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}`, "info");
+child.on("error", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}`, "error");
+    process.exit(127);
+});
+if (child.stderr) {
+    child.stderr.on("data", (chunk) => {
+        appendSafe(perDatePath, chunk); // per-date raw (back-compat)
+        appendSafe(perSessionPath, chunk); // per-session raw (Task 706)
+        try {
+            process.stderr.write(chunk);
+        }
+        catch { /* stderr closed */ } // passthrough
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-TAIL_CAP);
+        if (!bootEmitted) {
+            bootEmitted = true;
+            const head = chunk.toString("utf8").split("\n")[0].slice(0, 200);
+            emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+        }
+    });
+}
+const forward = (signal) => { if (!child.killed)
+    child.kill(signal); };
+process.on("SIGTERM", () => forward("SIGTERM"));
+process.on("SIGINT", () => forward("SIGINT"));
+// Signal → number, so a signal-killed child propagates as 128+signum (the
+// shell convention). `code` is null on a signal exit, so `128 + (code ?? 0)`
+// would collapse every signal to 128 and lose the signal identity in the
+// wrapper's own exit status.
+const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+child.on("exit", (code, signal) => {
+    const lifetimeMs = Date.now() - spawnStamp;
+    const tail = stderrTail.slice(-200);
+    const level = signal || (code ?? 0) !== 0 ? "error" : "info";
+    emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} ` +
+        `code=${code ?? "—"} signal=${signal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+    if (signal)
+        process.exit(128 + (SIGNUM[signal] ?? 0));
+    process.exit(code ?? 0);
+});
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/browser/lib/mcp-spawn-tee/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/payload/platform/plugins/contacts/.claude-plugin/plugin.json

@@ -10,8 +10,12 @@
       "type": "stdio",
       "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
         "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
-      ]
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "contacts"
+      }
     }
   }
 }

package/payload/platform/plugins/contacts/lib/mcp-spawn-tee/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — parent-side stderr capture + lifecycle observability.
+ *
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This wrapper sits between Claude Code and the real
+ * MCP server: Claude Code runs `node <this> <real-entry>`, and the wrapper
+ * spawns the real entry with `stdio:['inherit','inherit','pipe']` so stdin
+ * and stdout (the JSON-RPC channel) pass through byte-identical. Only stderr
+ * is intercepted, and only for logging.
+ *
+ * Because the wrapper IS the helper's parent, it observes the helper's true
+ * exit code, signal, and lifetime for every death mode — including a SIGKILL
+ * or a transport-layer crash that an in-process handler would miss.
+ *
+ *   Claude Code CLI → wrapper (this file) → child = node <real-entry>
+ *        child stdin/stdout : inherited (Claude Code pipe, untouched)
+ *        child stderr       : piped → per-date log + per-session log + passthrough
+ *
+ * Destinations (Task 706):
+ *   - `${LOG_DIR}/mcp-<name>-stderr-<date>.log`  — per-date raw (back-compat;
+ *     the in-process mcp-stderr-tee and the [mcp-init-error] probe read it).
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — per-session raw + lifecycle
+ *     lines; wrapper-only, so it never mixes the enumeration copy with the
+ *     live copy. Authoritative sink. Absent when SESSION_ID is unset
+ *     (enumeration spawn) — then the per-date file is the fallback.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines. A dropped POST loses nothing because
+ *     the per-session file already holds the line (written synchronously).
+ *
+ * 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=   (always)
+ *
+ * The wrapper never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ * SIGTERM/SIGINT are forwarded to the child so a Claude Code shutdown does
+ * not orphan it; the child exit code/signal is propagated verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+const ENTRY = process.argv[2];
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+// Per-session raw + lifecycle log (Task 706). Wrapper-only. Empty SESSION_ID
+// (enumeration spawn) → undefined, and the per-date file is the fallback.
+const perSessionPath = LOG_DIR && SESSION_ID
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-${SESSION_ID}.log`)
+    : undefined;
+const perDatePath = LOG_DIR
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${new Date(spawnStamp).toISOString().slice(0, 10)}.log`)
+    : undefined;
+// Rolling tail of child stderr for op=exit. Capped so a chatty child cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+function appendSafe(path, data) {
+    if (!path || !LOG_DIR)
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+        (0, node_fs_1.appendFileSync)(path, data);
+    }
+    catch {
+        /* unwritable destination — never mask primary output */
+    }
+}
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative,
+// so a dropped POST (unreachable port, process exiting) loses nothing.
+function postToServerLog(suffix, level) {
+    if (!PLATFORM_PORT)
+        return;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 500);
+        t.unref?.(); // never let the abort timer keep the wrapper's event loop alive
+        void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+            signal: ctrl.signal,
+        }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
+    }
+    catch {
+        /* fetch threw synchronously — best-effort only */
+    }
+}
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the wrapper's own stderr (journald / Claude Code
+// visibility), 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) {
+    const line = `[mcp-helper] ${suffix}\n`;
+    appendSafe(perSessionPath, line);
+    try {
+        process.stderr.write(line);
+    }
+    catch { /* stderr closed */ }
+    postToServerLog(suffix, level);
+}
+if (!ENTRY) {
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
+    process.exit(2);
+}
+const child = (0, node_child_process_1.spawn)(process.execPath, [ENTRY], {
+    stdio: ["inherit", "inherit", "pipe"],
+    env: process.env,
+});
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}`, "info");
+child.on("error", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}`, "error");
+    process.exit(127);
+});
+if (child.stderr) {
+    child.stderr.on("data", (chunk) => {
+        appendSafe(perDatePath, chunk); // per-date raw (back-compat)
+        appendSafe(perSessionPath, chunk); // per-session raw (Task 706)
+        try {
+            process.stderr.write(chunk);
+        }
+        catch { /* stderr closed */ } // passthrough
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-TAIL_CAP);
+        if (!bootEmitted) {
+            bootEmitted = true;
+            const head = chunk.toString("utf8").split("\n")[0].slice(0, 200);
+            emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+        }
+    });
+}
+const forward = (signal) => { if (!child.killed)
+    child.kill(signal); };
+process.on("SIGTERM", () => forward("SIGTERM"));
+process.on("SIGINT", () => forward("SIGINT"));
+// Signal → number, so a signal-killed child propagates as 128+signum (the
+// shell convention). `code` is null on a signal exit, so `128 + (code ?? 0)`
+// would collapse every signal to 128 and lose the signal identity in the
+// wrapper's own exit status.
+const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+child.on("exit", (code, signal) => {
+    const lifetimeMs = Date.now() - spawnStamp;
+    const tail = stderrTail.slice(-200);
+    const level = signal || (code ?? 0) !== 0 ? "error" : "info";
+    emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} ` +
+        `code=${code ?? "—"} signal=${signal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+    if (signal)
+        process.exit(128 + (SIGNUM[signal] ?? 0));
+    process.exit(code ?? 0);
+});
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/contacts/lib/mcp-spawn-tee/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/payload/platform/plugins/docs/references/getting-started.md

@@ -60,7 +60,7 @@ When the text field is empty, a microphone button appears in place of the send b
 
 Voice recording requires a secure connection (HTTPS). When accessing {{productName}} over the local network via HTTP, use the tunnel URL for voice notes.
 
-You can also drop, paste, or pick an audio file (`.opus`, `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`) into the chat composer — for example a voice note forwarded from WhatsApp. The file is transcribed the same way the in-browser recording is, and only the transcript reaches {{productName}}; the audio itself is discarded after transcription.
+You can also drop, paste, or pick an audio file (`.opus`, `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`) into the chat composer — for example a voice note forwarded from WhatsApp. The file is transcribed the same way the in-browser recording is, and only the transcript reaches {{productName}}; the audio itself is discarded after transcription. If you type a message and attach an audio file on the same send, both arrive — the transcript follows your typed text.
 
 ## What {{productName}} Remembers
 

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

@@ -31,7 +31,7 @@ Everything {{productName}} can do is provided by a plugin. Each plugin is a self
 
 **How tools and roles reach the session.** Each `claude` PTY spawn registers every plugin's MCP server and every bundled subagent directory before the operator's first turn — a per-spawn `mcp-config.json` written by the session manager and passed as `--mcp-config` on the PTY argv, plus one `--add-dir` per agents directory. Admin sessions see every plugin and every role; public sessions see only plugins with at least one public-allowlisted tool. The manager refuses to start when a plugin's `PLUGIN.md` declares tools without a matching `mcp:` block (forensic signal: `boot-failed reason=mcp-allowlist-without-server …`). See `internals.md` "Spawn-time MCP and subagent registration" for the full mechanism and `internals.md` "Tool Eagerness" for the separate ToolSearch-vs-eager registration concern.
 
-**MCP helper death observability (Task 706).** `claude` spawns each plugin MCP helper as its own child, so the manager cannot see a helper die. Every spawn-capable plugin therefore wraps its `mcp:` command with `lib/mcp-spawn-tee`, a parent-side node wrapper that is the helper's real parent and observes its true exit code, signal, and lifetime (including SIGKILL / transport crashes). The wrapper tees the helper's stderr to a wrapper-only per-session file `~/.{brand}/logs/mcp-<server>-<sessionId>.log` — never mixed with the admin-server enumeration copy — and emits lifecycle lines keyed `session=<id8> server=<name>`: `[mcp-helper] op=spawn … pid= entry=`, `[mcp-helper] op=boot … head=<first stderr bytes>`, and `[mcp-helper] op=exit … code= signal= lifetimeMs= stderr-tail=` on every exit (including a clean one). Lines are written synchronously to the per-session file and best-effort mirrored to `server.log` via the loopback log-ingest route. Diagnose a dead helper by `grep '\[mcp-helper\]' ~/.{brand}/logs/server.log` filtered by `session=<id8>`, then read the per-session file for its last output. Full contract and diagnostic path in [`.docs/mcp-helper-observability.md`](../../../.docs/mcp-helper-observability.md). The alive-but-wedged case (no process exit) is the deferred `[mcp-helper-census]` reconciler (Task 710).
+**MCP helper death observability (Task 706).** `claude` spawns each plugin MCP helper as its own child, so the manager cannot see a helper die. Every spawn-capable plugin therefore wraps its `mcp:` command with `lib/mcp-spawn-tee`, a parent-side node wrapper that is the helper's real parent and observes its true exit code, signal, and lifetime (including SIGKILL / transport crashes). The wrapper tees the helper's stderr to a wrapper-only per-session file `~/.{brand}/logs/mcp-<server>-<sessionId>.log` — never mixed with the admin-server enumeration copy — and emits lifecycle lines keyed `session=<id8> server=<name>`: `[mcp-helper] op=spawn … pid= entry=`, `[mcp-helper] op=boot … head=<first stderr bytes>`, and `[mcp-helper] op=exit … code= signal= lifetimeMs= stderr-tail=` on every exit (including a clean one). Lines are written synchronously to the per-session file and best-effort mirrored to `server.log` via the loopback log-ingest route. Diagnose a dead helper by `grep '\[mcp-helper\]' ~/.{brand}/logs/server.log` filtered by `session=<id8>`, then read the per-session file for its last output. Both spawn paths are wrapped: the manager's per-spawn `.mcp.json` (Task 706) and the generated `.claude-plugin/plugin.json` manifests that channel sessions take helpers from (Task 807) — the manifest generator copies the tee into each `mcp-manifest: auto` plugin at `lib/mcp-spawn-tee/index.js`, because the plugin-install cache snapshot severs `${PLATFORM_ROOT}`-relative paths, and a missing tee dist at generation time is FATAL. Full contract and diagnostic path in [`.docs/mcp-helper-observability.md`](../../../.docs/mcp-helper-observability.md). The alive-but-wedged case (no process exit) is the deferred `[mcp-helper-census]` reconciler (Task 710).
 
 **Where premium bundle subs live.** Bundle subs (`loop`, `property-data`, `brochures`, etc. inside `real-agent`) live exclusively at `premium-plugins/<bundle>/plugins/<sub>/` and are registered via the resolver's bundle-descent walk. Standalone premiums (no `BUNDLE.md`, e.g. `writer-craft`, `teaching`, `venture-studio`) live exclusively at `premium-plugins/<name>/` and are registered via the resolver's dual-root scan (`platform/plugins/` and `premium-plugins/` are both `pluginsRoots`). Neither shape is flat-copied into `platform/plugins/<name>/`. A divergent flat copy of a bundle sub is treated as an operator override: the resolver refuses to boot with `boot-failed reason=mcp-plugin-duplicate <plugin> declared by more than one plugins root: <pathA> (sha=…) vs <pathB> (sha=…)` so the operator can `sha256sum` both paths and remove the stale one. Byte-identical bundle-sub flat copies left over from installer versions that flat-copied bundle subs are reaped on the first post-upgrade boot (`[premium-auto-deliver] reaped sub=<name> reason=duplicate-of-premium-tree`). Standalone flat copies (leaked by the pre-fix `autoDeliverPremiumPlugins` standalone branch) are reaped unconditionally — there is no documented override path for standalones at `platform/plugins/<name>/` — and the reaper logs `[premium-auto-deliver] reaped standalone=<name> matches-source=<true|false>` so divergent reaps leave a forensic trail.
 
@@ -171,16 +171,6 @@ Both flows run on the native Claude Code PTY surface in admin chat (Task 287). T
 
 **Authorisation** is inherited from the same `canAccessAdmin()` gate that wraps every `/api/admin/*` route.
 
-## AI Content Provenance
-
-When your public agent sends a message to someone — via email, WhatsApp, Telegram, or SMS — the platform automatically includes a brief disclosure that the content was generated by AI. This is transparent and cannot be turned off.
-
-- **Email:** an `X-AI-Generated` header and a footer line are added to every outbound email
-- **WhatsApp and Telegram:** a short line is appended to the message body
-- **SMS:** a brief suffix is appended when the message is AI-composed
-
-Messages you write yourself (e.g. typing directly in WhatsApp) are not marked — the disclosure applies only to content composed by the AI agent.
-
 ## Session Slot Safeguards
 
 {{productName}} runs each chat — yours and every visitor's — as a separate `claude` process on your Pi. Three safeguards keep these processes from piling up:

package/payload/platform/plugins/email/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "email",
-  "description": "Email — dedicated email account. Retrieval: email-graph-query for stored email-thread history as :ConversationArchive {source:'email'} with :Section chunks (recall, search, 'threads about X', 'what did Y send?'); email-read / email-search for live IMAP inbox (with best-effort per-archive section hints from the graph). Ingestion (operator-initiated, human-in-the-loop): email-fetch lists new messages, email-ingest writes the operator-approved subset via the conversation-archive pipeline. Sending: email-send (new), email-reply (threaded — resolves the original via IMAP Message-ID search). Config: email-provider-info (pre-password host + app-password lookup from an address alone), email-setup, email-status, email-otp-extract.",
+  "description": "Email — dedicated email account. Retrieval: email-graph-query for stored email-thread history as :ConversationArchive {source:'email'} with :Section chunks (recall, search, 'threads about X', 'what did Y send?'); email-read / email-search for live IMAP inbox (with best-effort per-archive section hints from the graph). Ingestion (operator-initiated, human-in-the-loop): email-fetch lists new messages, email-ingest writes the operator-approved subset via the conversation-archive pipeline. Sending: email-send (new), email-reply (threaded — resolves the original via IMAP Message-ID search), email-draft (compose to the mailbox Drafts folder, unsent, for operator review). Config: email-provider-info (pre-password host + app-password lookup from an address alone), email-setup, email-status, email-otp-extract.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"
@@ -10,8 +10,12 @@
       "type": "stdio",
       "command": "node",
       "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
         "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
-      ]
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "email"
+      }
     }
   }
 }

package/payload/platform/plugins/email/PLUGIN.md

@@ -1,6 +1,6 @@
 ---
 name: email
-description: "Email — dedicated email account. Retrieval: email-graph-query for stored email-thread history as :ConversationArchive {source:'email'} with :Section chunks (recall, search, 'threads about X', 'what did Y send?'); email-read / email-search for live IMAP inbox (with best-effort per-archive section hints from the graph). Ingestion (operator-initiated, human-in-the-loop): email-fetch lists new messages, email-ingest writes the operator-approved subset via the conversation-archive pipeline. Sending: email-send (new), email-reply (threaded — resolves the original via IMAP Message-ID search). Config: email-provider-info (pre-password host + app-password lookup from an address alone), email-setup, email-status, email-otp-extract."
+description: "Email — dedicated email account. Retrieval: email-graph-query for stored email-thread history as :ConversationArchive {source:'email'} with :Section chunks (recall, search, 'threads about X', 'what did Y send?'); email-read / email-search for live IMAP inbox (with best-effort per-archive section hints from the graph). Ingestion (operator-initiated, human-in-the-loop): email-fetch lists new messages, email-ingest writes the operator-approved subset via the conversation-archive pipeline. Sending: email-send (new), email-reply (threaded — resolves the original via IMAP Message-ID search), email-draft (compose to the mailbox Drafts folder, unsent, for operator review). Config: email-provider-info (pre-password host + app-password lookup from an address alone), email-setup, email-status, email-otp-extract."
 tools:
   - name: email-provider-info
     publicAllowlist: false
@@ -17,6 +17,9 @@ tools:
   - name: email-reply
     publicAllowlist: false
     adminAllowlist: false
+  - name: email-draft
+    publicAllowlist: false
+    adminAllowlist: false
   - name: email-search
     publicAllowlist: false
     adminAllowlist: false
@@ -68,6 +71,7 @@ Manages the agent's own dedicated email account — IMAP for reading, SMTP for s
 - **Search inbox:** `email-search` — live IMAP search by sender, subject, body keyword, date range. Same per-archive hint and attachment footer as `email-read`.
 - **Send:** `email-send` — new outbound email. Pass `cc`/`bcc` (each an array of email addresses) to copy or blind-copy recipients — CC appears in the message header, BCC recipients receive the message without appearing in any header. Pass `attachments` (absolute file paths under the account directory, ≤25 MB each) to attach files as SMTP attachments; an invalid path fails the send with no email dispatched. The success message names the CC recipients and reports the BCC count without naming them.
 - **Reply:** `email-reply` — threaded reply to an existing email by `messageId`. Resolves the original envelope via IMAP `SEARCH HEADER Message-ID` (INBOX then `\Sent`), so threading works for any message still present on the server even if the graph never ingested it. Supports `replyAll`, `cc`/`bcc`, and `attachments` (same path rules as `email-send`). Explicit `cc`/`bcc` are added in addition to whatever `replyAll` places in `To`, passed through as given (no overlap de-duplication against `To`).
+- **Compose to Drafts:** `email-draft` — builds the same MIME message as `email-send` (same `cc`/`bcc`/`attachments` rules; unlike a dispatched send, the stored draft keeps its `Bcc:` header, because the draft bytes are the only recipient carrier) but APPENDs it to the mailbox's `\Drafts` special-use folder with the `\Draft` flag instead of dispatching it. Nothing is sent. The success message names the Drafts folder and the APPEND UID so a saved draft is never indistinguishable from a silent no-op. Fails naming the mailbox when the server advertises no `\Drafts` special-use folder — no fallback folder is picked. Use when the operator wants to review and send by hand.
 - **Ingestion — fetch:** `email-fetch` — list new IMAP messages since the stored high-water mark. Metadata + body preview only — including attachment names, mimetypes, and sizes so the operator sees what's attached before approving (Task 402). No bytes downloaded, no graph writes. Stages the batch in-memory for `email-ingest`.
 - **Ingestion — apply:** `email-ingest` — apply the operator's per-message decisions to the staged batch. Each Message-ID must carry a disposition (`ingest` or `discard`). Approved messages land on `:ConversationArchive {source:'email'}` via the source-agnostic conversation-archive pipeline (one archive per thread, sessionised into `:Section` chunks). Attachment bytes are fetched, archived to `{accountDir}/archive/email/<uidValidity>-<uid>/<sha256>-<filename>` (0o600, 25 MB cap), and each attachment lands as a content-addressed `:DigitalDocument` keyed on `attachmentId = sha256(bytes)`; the `:HAS_ENCLOSURE` edge from the parent `:ConversationArchive` is wired by `memory-ingest` on its next pass via the `pendingArchiveEdges` queue (Task 402). Advances the inbox high-water mark only after a successful write.
 - **Recall/history:** `email-graph-query` — search stored email archives in Neo4j by natural language, participant address, or date range. Each thread is one `:ConversationArchive {source:'email'}` with `:Section` chunks; operator participants attach via `:PARTICIPANT_IN` edges from `:Person`/`:AdminUser`. List mode surfaces a per-archive summary built from concatenated `:Section.summary` values; query mode runs vector search over the `section_embedding` index and dedups to the parent archive.
@@ -89,7 +93,7 @@ Email ingestion is **operator-initiated and human-in-the-loop**. There is no bac
 | Skill | Purpose |
 |-------|---------|
 | [email-ingest](skills/email-ingest/SKILL.md) | Operator-initiated ingestion. Drives "check my emails" → list via `email-fetch` → summarise → ask the operator per message → write the approved subset via `email-ingest`. |
-| [email-composition](skills/email-composition/SKILL.md) | Conversational wrapper for drafting replies, new emails, and inbox triage. Orchestrates the five `email-*` tools with human-in-the-loop approval on every send. |
+| [email-composition](skills/email-composition/SKILL.md) | Conversational wrapper for drafting replies, new emails, and inbox triage. Orchestrates the six `email-*` tools with human-in-the-loop approval on every send; draft intent ("leave it in drafts", "don't send yet") routes to `email-draft`. |
 
 ## References
 

package/payload/platform/plugins/email/lib/mcp-spawn-tee/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — parent-side stderr capture + lifecycle observability.
+ *
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This wrapper sits between Claude Code and the real
+ * MCP server: Claude Code runs `node <this> <real-entry>`, and the wrapper
+ * spawns the real entry with `stdio:['inherit','inherit','pipe']` so stdin
+ * and stdout (the JSON-RPC channel) pass through byte-identical. Only stderr
+ * is intercepted, and only for logging.
+ *
+ * Because the wrapper IS the helper's parent, it observes the helper's true
+ * exit code, signal, and lifetime for every death mode — including a SIGKILL
+ * or a transport-layer crash that an in-process handler would miss.
+ *
+ *   Claude Code CLI → wrapper (this file) → child = node <real-entry>
+ *        child stdin/stdout : inherited (Claude Code pipe, untouched)
+ *        child stderr       : piped → per-date log + per-session log + passthrough
+ *
+ * Destinations (Task 706):
+ *   - `${LOG_DIR}/mcp-<name>-stderr-<date>.log`  — per-date raw (back-compat;
+ *     the in-process mcp-stderr-tee and the [mcp-init-error] probe read it).
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — per-session raw + lifecycle
+ *     lines; wrapper-only, so it never mixes the enumeration copy with the
+ *     live copy. Authoritative sink. Absent when SESSION_ID is unset
+ *     (enumeration spawn) — then the per-date file is the fallback.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines. A dropped POST loses nothing because
+ *     the per-session file already holds the line (written synchronously).
+ *
+ * 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=   (always)
+ *
+ * The wrapper never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ * SIGTERM/SIGINT are forwarded to the child so a Claude Code shutdown does
+ * not orphan it; the child exit code/signal is propagated verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+const ENTRY = process.argv[2];
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+// Per-session raw + lifecycle log (Task 706). Wrapper-only. Empty SESSION_ID
+// (enumeration spawn) → undefined, and the per-date file is the fallback.
+const perSessionPath = LOG_DIR && SESSION_ID
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-${SESSION_ID}.log`)
+    : undefined;
+const perDatePath = LOG_DIR
+    ? (0, node_path_1.resolve)(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${new Date(spawnStamp).toISOString().slice(0, 10)}.log`)
+    : undefined;
+// Rolling tail of child stderr for op=exit. Capped so a chatty child cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+function appendSafe(path, data) {
+    if (!path || !LOG_DIR)
+        return;
+    try {
+        (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+        (0, node_fs_1.appendFileSync)(path, data);
+    }
+    catch {
+        /* unwritable destination — never mask primary output */
+    }
+}
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative,
+// so a dropped POST (unreachable port, process exiting) loses nothing.
+function postToServerLog(suffix, level) {
+    if (!PLATFORM_PORT)
+        return;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 500);
+        t.unref?.(); // never let the abort timer keep the wrapper's event loop alive
+        void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+            signal: ctrl.signal,
+        }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
+    }
+    catch {
+        /* fetch threw synchronously — best-effort only */
+    }
+}
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the wrapper's own stderr (journald / Claude Code
+// visibility), 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) {
+    const line = `[mcp-helper] ${suffix}\n`;
+    appendSafe(perSessionPath, line);
+    try {
+        process.stderr.write(line);
+    }
+    catch { /* stderr closed */ }
+    postToServerLog(suffix, level);
+}
+if (!ENTRY) {
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
+    process.exit(2);
+}
+const child = (0, node_child_process_1.spawn)(process.execPath, [ENTRY], {
+    stdio: ["inherit", "inherit", "pipe"],
+    env: process.env,
+});
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}`, "info");
+child.on("error", (err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}`, "error");
+    process.exit(127);
+});
+if (child.stderr) {
+    child.stderr.on("data", (chunk) => {
+        appendSafe(perDatePath, chunk); // per-date raw (back-compat)
+        appendSafe(perSessionPath, chunk); // per-session raw (Task 706)
+        try {
+            process.stderr.write(chunk);
+        }
+        catch { /* stderr closed */ } // passthrough
+        stderrTail = (stderrTail + chunk.toString("utf8")).slice(-TAIL_CAP);
+        if (!bootEmitted) {
+            bootEmitted = true;
+            const head = chunk.toString("utf8").split("\n")[0].slice(0, 200);
+            emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+        }
+    });
+}
+const forward = (signal) => { if (!child.killed)
+    child.kill(signal); };
+process.on("SIGTERM", () => forward("SIGTERM"));
+process.on("SIGINT", () => forward("SIGINT"));
+// Signal → number, so a signal-killed child propagates as 128+signum (the
+// shell convention). `code` is null on a signal exit, so `128 + (code ?? 0)`
+// would collapse every signal to 128 and lose the signal identity in the
+// wrapper's own exit status.
+const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+child.on("exit", (code, signal) => {
+    const lifetimeMs = Date.now() - spawnStamp;
+    const tail = stderrTail.slice(-200);
+    const level = signal || (code ?? 0) !== 0 ? "error" : "info";
+    emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} ` +
+        `code=${code ?? "—"} signal=${signal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+    if (signal)
+        process.exit(128 + (SIGNUM[signal] ?? 0));
+    process.exit(code ?? 0);
+});
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/email/lib/mcp-spawn-tee/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/payload/platform/plugins/email/mcp/dist/__tests__/email-draft.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=email-draft.test.d.ts.map

package/payload/platform/plugins/email/mcp/dist/__tests__/email-draft.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-draft.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/email-draft.test.ts"],"names":[],"mappings":""}