@zieglar/pi-chat-exchange 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## 0.2.0
+
+First packaged release line of this extension. Version 0.1.1 was an internal
+private version only; it was never published to npm, so nothing below is an
+upgrade from a public release.
+CE's own code is owner-authorized MIT, Copyright (c) 2026 zieglar.
+Third-party license evidence is complete and `private: true` is removed from the manifest.
+
+### Messaging
+
+- Add the default-disabled, opt-in `ce_ack` MCP tool, advertised only when the
+  binding declares the Session-authorized ACK capability. The host supplies all
+  authority fields and equivalent calls replay the original receipt. An ACK
+  records a recipient reception statement — not proof of delivery, reading,
+  processing or task completion. BUSY rollback and uncertain outcomes never grant
+  retry permission.
+
+### Tunnel lifecycle commands
+
+- Add `/ce-tunnel doctor`: read-only qualification diagnostics. With no trusted
+  client installed it reports a safe refusal such as `CE_EXECUTABLE_UNTRUSTED`.
+  That refusal is the expected diagnosis, not an install failure, and `doctor` is
+  never an exit proof.
+- Add `/ce-tunnel deactivate`: bounded, normal release of this Session's own
+  binding, retaining registration and history. It is not revoke and not Recovery.
+
+### Multi-session and runtime
+
+- Support independent Pi Sessions on a shared Tunnel: `/ce-tunnel convert` keeps
+  the current native Session's original endpoint and `/ce-tunnel register` gives a
+  new Session its own stable endpoint without starting transport.
+- Support trusted portable runtime installations for the pinned Node launch path.
+
+### Runtime qualification
+
+- The 0.2.0 certification target is exactly **Node 24.21.0 + Pi 1.3.0 +
+  macOS arm64**.
+- Node **24.22.1** was admitted earlier as a second permitted runtime and remains
+  declared in `engines`. That historical admission is **not** part of 0.2.0's
+  certification. Linux is experimental and unverified.
+
+### Packaging and documentation
+
+- Prepare the prebuilt Pi extension npm distribution and consumer documentation
+  closure. The consumer tarball ships the operating guides plus the protocol,
+  ownership, storage, ACK and Store-security contracts, so no repository access
+  is required to operate the package safely. `private: true` was removed once the third-party audit closed with three-layer evidence. The
+  owner-authorized MIT LICENSE ships in the prebuilt tarball; dependency licenses
+  remain separate and must be preserved at installation/redistribution.
+- Document owned transport Stop, independently confirmed STOPPED, normal binding
+  release and then native Pi removal; Store, profile, credentials and history are
+  retained.
+- Keep managed npm, physical tarball fallback and monorepo source development
+  routes distinct.
+- Cloud transport is NOT_VERIFIED; offline synthetic fixtures only.
+
+### Release-process note
+
+The queued `.changeset/ce-e2b-ack-mcp.md` patch entry describes the same `ce_ack`
+behavior change, and its content is already reflected in this 0.2.0 entry. It is
+deliberately **not** consumed by this entry: Changesets remains the repository's
+version authority, and a future Changesets version PR must reconcile and consume
+it together with this hand-written 0.2.0 entry and the 0.2.0 version pins. Root
+Changesets configuration and queued entries are untouched by this delta. With
+`private` now removed, `privatePackages.version: false` no longer keeps the queued
+changeset inert — the next Changesets version PR owns that reconciliation explicitly.
+
+**Third-party evidence complete; `private: true` removed.** The 101-item dependency closure is fully audited: the two former evidence gaps (pi-tui and the Host peer) closed with three-layer exact-version evidence — registry tarball MIT declarations plus the upstream `v1.3.0` tag root LICENSE (MIT, (c) 2025 Mario Zechner); their artifacts omit license text (upstream packaging omission, not incompatibility). The per-version audit record is `docs/license-audit.md`, which is repo-only and not distributed in the tarball. Owner authorization covers CE's own code only — not a grant to relicense dependencies.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zieglar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Pi Chat Exchange
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 ChatGPT 与 Pi 通过显式工具交换持久化消息：发送、发现收件箱、授权读取，以及独立授权的接收回执（ACK）。它不是自动任务调度器，也不把 ACK 或对话回复当作任务完成。
+
+本包版本为 **0.2.0**。CE 自有代码已获所有者授权采用 **MIT**（见 [LICENSE](LICENSE)）；第三方许可证证据已按三层证据闭合（逐版本审计记录为 `docs/license-audit.md`，仅仓库保留、不随 tarball 分发）。0.2.0 的认证范围仅 **Node 24.21.0 / Pi 1.3.0 / macOS arm64**；cloud transport 为 NOT_VERIFIED，Linux 未验证。
+
+## 当前能力与典型用法
+
+- **持久化消息**：ChatGPT 发来计划或问题，Pi 显式查看 inbox、授权读取，再以新 Message 回复检查结果。
+- **独立接收回执**：按需授权 payload read 与 ACK；接收回执不等于任务完成，也不触发正文执行。
+- **多 Session**：多个项目中的真实 Pi Session 使用独立 Endpoint，共享 Tunnel；ChatGPT inbox 仍不隔离对话。
+
+当前不提供自动任务调度、自动执行或 exactly-once delivery/execution。只需自动远端执行而不逐次授权时，本项目不适用。
+
+## 选择连接方式
+
+- **推荐：Secure MCP Tunnel。** `/ce-tunnel` 提供设置向导、显式激活、后台 Start/Stop 和健康状态；无需 Desktop stdio 插件。按 [Tunnel 快速开始](docs/tunnel-setup.md)操作。
+- **Desktop 本地 stdio 插件。** 由支持本地插件的 ChatGPT Desktop 启动 bundled MCP server；需配置本机 Node 与外置 binding。见 [ChatGPT 安装](docs/chatgpt-installation.md)。不要与 Tunnel 同时争用同一 Endpoint。
+
+## 安装 Pi 扩展
+
+**信任提示：Pi 扩展以你的完整用户权限运行。安装前审查源码与制品来源；消息授权门槛不等于操作系统沙箱。**
+
+正式日常使用请用**独立安装路径**：作者交付预构建私有 tarball，消费者物理安装后 `pi install` 注册，无需仓库/build，见 [独立安装指南](docs/independent-install.md)。下面是开发者源码路径。
+
+先安装 Pi **1.3.0**、pnpm **12.9.1** 和批准的 Node **24.21.0 或 24.22.1**。Node 还必须通过完整 SQLite 身份、编译选项与 API 门槛，不是任意 `24.x`。Pi host 与 MCP child 分别校验；mise 或其他版本管理器均不是必需品。
+
+从仓库根目录，在已选中批准 Node 的 shell 中执行：
+
+```sh
+node --version
+pnpm install --frozen-lockfile
+pnpm --dir packages/pi-chat-exchange run build
+pi -e ./packages/pi-chat-exchange/pi-extension/index.ts
+```
+
+扩展入口会导入包内 `dist/`；修改源码后须重新运行上述 build，再在已加载的 Session 中 `/reload`。`/reload` 不会编译源码，旧 `dist/` 会继续运行旧逻辑。
+
+这是临时加载。若要长期从不同项目使用，在 build 后执行 `pi install /absolute/path/to/packages/pi-chat-exchange` 注册本地包，再正常启动 Pi。本地安装引用该目录，不复制源码；不要同时安装和 `-e` 加载第二份。本包不提供独立的 `ce` 安装 CLI；安装只经 Pi 的 managed npm / tarball / 本地目录三条路径。
+
+进入交互 TUI 后：
+
+```text
+/ce-tunnel doctor
+/ce-tunnel setup
+/reload
+/ce-tunnel activate
+/ce-status
+```
+
+Setup 的 Advanced · Messaging 必须显式授权当前 Session；只保存基本 transport 设置时默认不能通信。首次 reload 缺少 mapping 时可能拒绝，随后显式 activate，不清理数据库。启动真实 Tunnel 还需父 Pi 环境的 `CE_TUNNEL_BACKGROUND_ALLOW=1` 和单独 `/ce-tunnel start`；完整步骤、可信绝对路径启动方式和 ChatGPT 自定义 MCP 配置见 [Tunnel 指南](docs/tunnel-setup.md)。
+
+## 多项目、多 Session
+
+每个真实 Pi Session 注册不同的稳定 Endpoint；项目目录本身不是身份。共享的 `chatgpt/main` inbox **不是 ChatGPT 对话隔离**。
+
+- `/ce-status`：当前 Pi / CE 身份与 Ownership 状态。
+- `/ce-tunnel sessions`：经当前运行时授权的、所选配置中 active Endpoint 列表，不证明 MCP 已加载。
+- `/ce-tunnel deactivate`：确认后正常解绑当前本地 CE binding，不删注册/历史，也不停止 Tunnel。
+- `/ce-tunnel revoke <exact-endpoint>`：撤销注册的后续权限；需先核实 transport STOPPED，不等于正常解绑。
+- `/reload`：有效 binding 重新校验并恢复；已正常释放或未绑定的 Session 需要显式 activate。
+
+转换、注册、权限和生效顺序见 [多 Session 使用指南](docs/multi-session-usage.md)。不要直接修改生成文件或删除 Store/Owner 作为排障。
+
+## 阅读导航
+
+| 目标 | 文档 |
+|---|---|
+| **独立安装（正式日常使用，预构建 tarball）** | [独立安装指南](docs/independent-install.md) |
+| 首次设置、可信安装诊断、ChatGPT 连接、启动与排障 | [Tunnel 用户指南](docs/tunnel-setup.md) |
+| Desktop stdio 打包与本机配置 | [ChatGPT 安装](docs/chatgpt-installation.md) |
+| 工具参数、Inbox、payload/ACK、生命周期 | [Pi 扩展指南](pi-extension/README.md) |
+| 多项目/Session 注册、解绑、撤销 | [多 Session 使用](docs/multi-session-usage.md) |
+| 分层、身份、授权、验证与扩展点 | [架构指南](docs/architecture.md) |
+| 后台进程所有权与停止约束 | [后台 Manager](docs/tunnel-manager-background.md) |
+| 精确安全契约 | [协议 v2](docs/protocol-v2.md) · [Ownership](docs/ownership-contract.md) · [Storage](docs/storage-contract.md) · [ACK](docs/delivery-ack-contract.md) · [Store 安全边界](docs/storage-security.md) |
+
+独立安装包（tarball）随包分发上表所有文档、CHANGELOG 与本版本 release notes，消费者无需访问仓库即可取得操作与安全契约。仅作者侧的治理与证据记录（如 `docs/license-audit.md`、`docs/runtime-qualification.md` 及各阶段审计记录）仅仓库保留，不进入消费者制品。
+
+## 边界与验证
+
+**Configured ≠ Pi-bound ≠ Connected ≠ 消息实证。** `CONNECTED` 只证明测得的传输健康；ACK 仅为 reception receipt，不证明 delivery、read、processing 或 task completion。
+
+不自动启动/重连、接管过期 Owner、排空 Inbox、执行 payload、合并 Store 或重试未知结果。`DELIVERY_UNKNOWN != CANCELLED`。凭据文件不是加密保险箱；不要把 key、capability、正文或完整日志贴入诊断。
+
+Store 平台 allowlist 为 macOS arm64 / Linux x64；两种批准 Node 的实测为 macOS arm64，不等于 Linux 或每种 Desktop UI 均已验收。已有本地人工双向消息与 Tunnel 启停验收不替代本次变更的隔离测试，也不证明机器冷启动或所有终端交互。
+
+开发检查：从包目录执行 `pnpm run verify`（check → typecheck → build → test → plugin-package test）；扩展测试前须 build。证据层次见[架构指南](docs/architecture.md#验证层次)。
+
+许可证：**MIT**，Copyright (c) 2026 zieglar。第三方依赖保留各自许可，不由 CE 的 MIT 重新授权；`@earendil-works/pi-tui@1.3.0` 与 Host peer 的制品未随包附带 LICENSE 文本（上游打包省略；经 registry 制品与上游 v1.3.0 标签根 LICENSE 三层核实为 MIT）。完整逐版本审计记录为 `docs/license-audit.md`（仅仓库保留，不随 tarball 分发）。0.2.0 的认证范围仅 Node 24.21.0 / Pi 1.3.0 / macOS arm64；cloud NOT_VERIFIED，Linux 未验证。见 [0.2.0 release notes](docs/releases/0.2.0.md) 与 [安全卸载/升级/回滚](docs/independent-install.md#5-安全卸载升级与回滚)。

package/dist/bin/mcp-stdio.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * stdio entrypoint for the pi-chat-exchange MCP server (composition only).
+ *
+ * Intended launch forms:
+ *   node dist/bin/mcp-stdio.js
+ *     Phase 1 smoke surface: exactly the `ping` tool, no durable state.
+ *
+ *   node dist/bin/mcp-stdio.js --config /abs/path/binding.json
+ *     CE-0002 B3-P3B messaging surface: binds ONE Endpoint from trusted,
+ *     operator-controlled launch configuration (never from tool arguments,
+ *     never from the environment), acquires its ownership lease with
+ *     `requireUnowned`, renews it on a heartbeat, and releases it on clean
+ *     shutdown. A prior crashed instance leaves an ownership row that refuses
+ *     startup — fail closed, no takeover.
+ *
+ *   tunnel-client run --profile pi-chat-exchange   (with --mcp-command "node .../mcp-stdio.js")
+ *
+ * stdout is reserved for MCP protocol frames; diagnostics go to stderr and
+ * carry status codes only — never configuration values, identifiers from
+ * tool arguments, payloads, or capability secrets.
+ */
+import { readFileSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { runStdioServer, createExchangeMcpServer } from "../control/mcp/server.js";
+import { CE_ACK_TOOL, MESSAGING_TOOL_NAMES } from "../control/mcp/messaging-tools.js";
+import { PING_TOOL_NAME } from "../control/mcp/ping.js";
+import { CeEndpointHost } from "../host/endpoint-host.js";
+import { CeBoundEndpoint } from "../host/bound-endpoint.js";
+import { McpBindingConfigError, MCP_BINDING_CONFIG_MAX_BYTES, parseMcpBindingConfig, } from "../host/mcp-binding-config.js";
+import { debugEvent, errorSummary } from "../control/debug-log.js";
+import { observeTransport } from "../control/mcp/debug-transport.js";
+import { initializeStore, openStore } from "../storage/store.js";
+import { createMcpPolicyAdmission } from "../tunnel/multi-session-admission.js";
+debugEvent("server", "SERVER_ENTRY", { version: process.version });
+// Monitor rather than handle exceptions: preserve Node's fatal exit behavior.
+process.on("uncaughtExceptionMonitor", (error, origin) => {
+    debugEvent("process", origin === "unhandledRejection" ? "UNHANDLED_REJECTION" : "UNCAUGHT_EXCEPTION", { ...errorSummary(error), origin });
+});
+process.on("exit", (exitCode) => debugEvent("process", "PROCESS_EXIT", { exitCode }));
+function fail(code, detail) {
+    debugEvent("server", "MCP_ERROR", { code, stage: "startup" });
+    console.error(detail === undefined ? code : `${code} ${detail}`);
+    process.exit(1);
+}
+/** Read the binding configuration from an absolute path, refusing anything
+ * oversized or unreadable before a single durable write can happen. */
+function loadBindingConfig(path) {
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return fail("CE_MCP_CONFIG_INVALID", "config.unreadable");
+    }
+    if (size > MCP_BINDING_CONFIG_MAX_BYTES)
+        return fail("CE_MCP_CONFIG_INVALID", "config.too_large");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return fail("CE_MCP_CONFIG_INVALID", "config.unreadable");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return fail("CE_MCP_CONFIG_INVALID", "config.not_json");
+    }
+    try {
+        return parseMcpBindingConfig(parsed);
+    }
+    catch (error) {
+        if (error instanceof McpBindingConfigError)
+            return fail(error.code, error.field);
+        return fail("CE_MCP_CONFIG_INVALID", "config.unexpected");
+    }
+}
+/** Open (or initialize on first use) the shared durable store. */
+function openBindingStore(config) {
+    const options = { directory: config.store.directory, filename: config.store.file, busyTimeoutMs: 5_000 };
+    debugEvent("store", "STORE_OPEN_STARTED");
+    const store = existsSync(join(options.directory, options.filename)) ? openStore(options) : initializeStore(options);
+    debugEvent("store", "STORE_OPEN_COMPLETED");
+    return store;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        await runStdioServer();
+        return;
+    }
+    const [flag, configPath] = argv;
+    if (argv.length !== 2 || flag !== "--config" || configPath === undefined || !configPath.startsWith("/")) {
+        fail("CE_MCP_LAUNCH_INVALID", "usage: mcp-stdio.js [--config /absolute/path.json]");
+    }
+    const config = loadBindingConfig(configPath);
+    // Verify actual launch bytes before Store creation; managed provenance grants nothing.
+    const admission = createMcpPolicyAdmission(config, configPath);
+    admission?.({ kind: "begin" });
+    const host = new CeEndpointHost(openBindingStore(config), {
+        adapter: config.endpoint.adapter,
+        allowlist: [{ endpointId: config.endpoint.endpointId }],
+        recipients: config.recipients,
+        exchangeNamespace: config.exchange.namespace,
+        exchangeIdempotencyKey: config.exchange.idempotencyKey,
+        leaseTtlSeconds: config.lease.ttlSeconds,
+        payloadRead: { enabled: config.payloadRead.enabled },
+        ack: { enabled: config.ack.enabled },
+    });
+    debugEvent("authority", "AUTHORITY_CHECK_STARTED", { stage: "requireUnowned" });
+    const bound = CeBoundEndpoint.start(host, config.endpoint.endpointId, {
+        renewIntervalMs: config.lease.renewIntervalSeconds * 1_000,
+        ...(admission === undefined ? {} : { admission }),
+        onEvent: (event) => {
+            debugEvent("authority", "AUTHORITY_CHECK_RESULT", { stage: event.kind });
+            if (event.kind === "renewed")
+                return;
+            // Codes only; renewal_deferred is retryable at the next tick,
+            // renewal_stopped has already blocked new sends.
+            console.error(event.kind === "renewal_deferred"
+                ? `CE_MCP_RENEWAL_DEFERRED code=${event.code}`
+                : `CE_MCP_RENEWAL_STOPPED code=${event.code}`);
+        },
+    });
+    debugEvent("authority", "OWNERSHIP_ACQUIRED", { owned: true });
+    // HANDOFF-CE-E2B-01: advertise `ce_ack` only when the validated binding
+    // declares the ack opt-in; the default surface stays exactly four tools.
+    const server = createExchangeMcpServer(undefined, {
+        port: bound, ackEnabled: config.ack.enabled, executionGuard: config.debugExecutionGuard,
+        ...(admission === undefined ? {} : { admission: () => admission({ kind: "inbox" }) }),
+    });
+    if (config.debugExecutionGuard.enabled) {
+        debugEvent("server", "EXECUTION_GUARD_ARMED", { scope: "tools/call", stage: "unified-dispatch-entry" });
+    }
+    const transport = observeTransport(new StdioServerTransport());
+    debugEvent("server", "TRANSPORT_CREATED");
+    let initiated = false;
+    const initiateShutdown = async () => {
+        if (initiated)
+            return;
+        initiated = true;
+        try {
+            await server.close();
+        }
+        catch {
+            // Transport already gone; the lease release below is what matters.
+        }
+        const shutdown = await bound.shutdown();
+        debugEvent("authority", "OWNERSHIP_RELEASED", { released: shutdown.released, detached: shutdown.detached });
+        console.error(shutdown.released
+            ? `CE_MCP_STOPPED released=true detached=${shutdown.detached}`
+            : `CE_MCP_STOPPED released=false code=${shutdown.code ?? "CE_HOST_UNAVAILABLE"}`);
+    };
+    let resolveShutdown;
+    const shutdownRequested = new Promise((resolvePromise) => {
+        resolveShutdown = resolvePromise;
+    });
+    const requestShutdown = () => resolveShutdown();
+    // `on`, not `once`: a repeat SIGTERM/SIGINT during the drain window must be
+    // absorbed by this idempotent request instead of hitting Node's default
+    // disposition and killing the process before the lease is released.
+    process.on("SIGTERM", () => { debugEvent("process", "PROCESS_SIGNAL", { signal: "SIGTERM" }); requestShutdown(); });
+    process.on("SIGINT", () => { debugEvent("process", "PROCESS_SIGNAL", { signal: "SIGINT" }); requestShutdown(); });
+    process.stdin.once("end", requestShutdown);
+    process.stdin.once("close", requestShutdown);
+    server.onclose = requestShutdown;
+    await server.connect(transport);
+    debugEvent("server", "TRANSPORT_CONNECTED");
+    debugEvent("server", "SERVER_READY", { mode: "bound" });
+    // HANDOFF-CE-E2B-01: the diagnostic mirrors exactly what the server above
+    // advertises for this binding (same construction, same order) — ce_ack
+    // appears only when the operator ack opt-in is enabled.
+    const advertisedTools = [
+        PING_TOOL_NAME,
+        ...MESSAGING_TOOL_NAMES,
+        ...(config.ack.enabled ? [CE_ACK_TOOL.name] : []),
+    ];
+    console.error(`CE_MCP_STARTED tools=${advertisedTools.join(",")}`);
+    await shutdownRequested;
+    await initiateShutdown();
+}
+main().catch((error) => {
+    debugEvent("server", "MCP_ERROR", { stage: "startup", ...errorSummary(error) });
+    // Sanitized: host refusals carry fixed codes; anything else collapses
+    // without echoing message text (which could contain operator paths).
+    const code = typeof error.code === "string"
+        ? String(error.code)
+        : "CE_MCP_START_FAILED";
+    console.error(code.startsWith("CE_") ? code : "CE_MCP_START_FAILED");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=mcp-stdio.js.map

package/dist/control/debug-log.js

@@ -0,0 +1,67 @@
+/** DIAG-01 development diagnostics: always on, best effort, never stdout.
+ * Only explicitly projected metadata is accepted; never pass raw args/results/errors.
+ * The built module's ../../.debug-logs is inside the independent debug artifact.
+ */
+import { appendFileSync, closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { join, resolve } from "node:path";
+const FIELDS = new Set(["stage", "method", "requestId", "requestIdType", "requestIdLength", "tool", "args", "errorType", "stackFrames", "code", "isError", "durationMs", "count", "released", "detached", "signal", "exitCode", "version", "fencing", "owned", "mode", "origin", "reason", "scope"]);
+export function createDebugLog(directory) {
+    return (component, event, metadata = {}) => {
+        // Include serialization in the guard: even hostile getters/cycles cannot
+        // turn diagnostics into a business/protocol failure.
+        try {
+            const context = Object.fromEntries(Object.entries(metadata).filter(([key]) => FIELDS.has(key)));
+            const line = `${JSON.stringify({ ts: new Date().toISOString(), pid: process.pid, component, event, ...context })}\n`;
+            try {
+                mkdirSync(directory, { recursive: true, mode: 0o700 });
+                if (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink())
+                    throw new Error("unsafe log directory");
+                const fd = openSync(join(directory, `ce-debug-${process.pid}.jsonl`), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+                try {
+                    const stat = fstatSync(fd);
+                    if (!stat.isFile() || (process.getuid !== undefined && stat.uid !== process.getuid()))
+                        throw new Error("unsafe log file");
+                    appendFileSync(fd, line);
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch { /* diagnostics file unavailable: stderr mirror remains best effort */ }
+            try {
+                writeSync(2, line);
+            }
+            catch { /* closed stderr must not alter behavior */ }
+        }
+        catch { /* diagnostics must never escape */ }
+    };
+}
+export const debugEvent = createDebugLog(resolve(import.meta.dirname, "../../.debug-logs"));
+const ARG_FIELDS = new Set(["to", "text", "idempotencyKey", "afterAuditSequence", "pageSize", "rawScanLimit", "messageId", "payloadDigest", "payloadLength", "messageCreatedAuditSequence"]);
+export function argumentShape(args) {
+    try {
+        if (args === null || typeof args !== "object")
+            return [];
+        return Object.entries(args).slice(0, 32).map(([key, value]) => ({
+            field: ARG_FIELDS.has(key) ? key : "unknown-field",
+            type: value === null ? "null" : Array.isArray(value) ? "array" : typeof value,
+            ...(typeof value === "string" ? { length: value.length } : {}),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export function errorSummary(error) {
+    try {
+        // Error messages and first stack line can contain payloads/credentials.
+        // Retain source basenames/line:column only, never function names or paths.
+        const stackFrames = error instanceof Error ? (error.stack ?? "").split("\n").slice(1, 9)
+            .flatMap((line) => line.match(/[/\\]([A-Za-z0-9_.-]+\.[cm]?[jt]s:\d+:\d+)\)?$/)?.[1] ?? []) : [];
+        return { errorType: error instanceof TypeError ? "TypeError" : error instanceof Error ? "Error" : typeof error, stackFrames };
+    }
+    catch {
+        return { errorType: "unknown" };
+    }
+}
+//# sourceMappingURL=debug-log.js.map

package/dist/control/mcp/debug-transport.js

@@ -0,0 +1,48 @@
+import { debugEvent, errorSummary } from "../debug-log.js";
+const METHODS = new Set(["initialize", "notifications/initialized", "tools/list", "tools/call", "ping", "notifications/cancelled"]);
+function frameMetadata(frame) {
+    const id = "id" in frame ? frame.id : undefined;
+    return {
+        ...("method" in frame ? { method: METHODS.has(frame.method) ? frame.method : "other" } : {}),
+        ...(typeof id === "number" ? { requestId: id } : typeof id === "string" ? { requestIdType: "string", requestIdLength: id.length } : {}),
+        ...("error" in frame ? { code: frame.error.code } : {}),
+    };
+}
+/** Observe the existing stdio transport without parsing/rewriting wire data.
+ * SDK connect installs callbacks before start. Preserve frame/extra/options,
+ * this binding, return/rejection semantics, and existing close/error callbacks.
+ */
+export function observeTransport(transport, log = debugEvent) {
+    const start = transport.start.bind(transport);
+    const send = transport.send.bind(transport);
+    transport.start = async () => {
+        const receive = transport.onmessage;
+        const close = transport.onclose;
+        const error = transport.onerror;
+        transport.onmessage = (frame, extra) => {
+            log("mcp", "MCP_REQUEST_RECEIVED", frameMetadata(frame));
+            if ("method" in frame) {
+                const aliases = new Map([["initialize", "MCP_INITIALIZE"], ["notifications/initialized", "MCP_INITIALIZED"], ["tools/list", "MCP_TOOLS_LIST"], ["tools/call", "MCP_TOOLS_CALL"]]);
+                const event = aliases.get(frame.method);
+                if (event !== undefined)
+                    log("mcp", event, frameMetadata(frame));
+            }
+            receive?.call(transport, frame, extra);
+        };
+        transport.onclose = () => { log("mcp", "SERVER_STOPPED"); close?.call(transport); };
+        transport.onerror = (e) => { log("mcp", "MCP_ERROR", errorSummary(e)); error?.call(transport, e); };
+        return start();
+    };
+    transport.send = async (frame, options) => {
+        try {
+            await send(frame, options);
+            log("mcp", "error" in frame ? "MCP_ERROR" : "MCP_RESPONSE_SENT", frameMetadata(frame));
+        }
+        catch (error) {
+            log("mcp", "MCP_ERROR", errorSummary(error));
+            throw error;
+        }
+    };
+    return transport;
+}
+//# sourceMappingURL=debug-transport.js.map