create-principles-disciple 1.147.7 → 1.147.9

package/pd-cli/dist/services/zip-writer.js

@@ -0,0 +1,97 @@
+/**
+ * Minimal ZIP writer (deflate + UTF-8 names) for the MCP log export command.
+ *
+ * The repository ships no zip dependency and the export must work offline on
+ * an Owner machine; the format needed here is the small, well-specified subset:
+ * local headers, one central directory, end-of-central-directory. Archives are
+ * bounded by the caller (≤20 MiB) and contain only text files.
+ */
+import { deflateRawSync } from 'node:zlib';
+const LOCAL_FILE_HEADER = 0x04034b50;
+const CENTRAL_DIRECTORY_HEADER = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+const UTF8_FLAG = 0x0800;
+const DEFLATE_METHOD = 8;
+const VERSION_NEEDED = 20;
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i += 1) {
+        let value = i;
+        for (let bit = 0; bit < 8; bit += 1) {
+            value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+        }
+        table[i] = value >>> 0;
+    }
+    return table;
+})();
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer) {
+        const table = CRC_TABLE[(crc ^ byte) & 0xff] ?? 0;
+        crc = table ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** DOS date/time (local); fixed to the generation time. */
+function dosDateTime(date) {
+    const time = (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2);
+    const dosDate = ((date.getFullYear() - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+    return { time, date: dosDate };
+}
+export function buildZip(entries, generatedAt = new Date()) {
+    const stamp = dosDateTime(generatedAt);
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name, 'utf8');
+        const compressed = deflateRawSync(entry.data);
+        const crc = crc32(entry.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(LOCAL_FILE_HEADER, 0);
+        local.writeUInt16LE(VERSION_NEEDED, 4);
+        local.writeUInt16LE(UTF8_FLAG, 6);
+        local.writeUInt16LE(DEFLATE_METHOD, 8);
+        local.writeUInt16LE(stamp.time, 10);
+        local.writeUInt16LE(stamp.date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(entry.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        chunks.push(local, name, compressed);
+        const directory = Buffer.alloc(46);
+        directory.writeUInt32LE(CENTRAL_DIRECTORY_HEADER, 0);
+        directory.writeUInt16LE(VERSION_NEEDED, 4);
+        directory.writeUInt16LE(VERSION_NEEDED, 6);
+        directory.writeUInt16LE(UTF8_FLAG, 8);
+        directory.writeUInt16LE(DEFLATE_METHOD, 10);
+        directory.writeUInt16LE(stamp.time, 12);
+        directory.writeUInt16LE(stamp.date, 14);
+        directory.writeUInt32LE(crc, 16);
+        directory.writeUInt32LE(compressed.length, 20);
+        directory.writeUInt32LE(entry.data.length, 24);
+        directory.writeUInt16LE(name.length, 28);
+        directory.writeUInt16LE(0, 30);
+        directory.writeUInt16LE(0, 32);
+        directory.writeUInt16LE(0, 34);
+        directory.writeUInt16LE(0, 36);
+        directory.writeUInt32LE(0, 38);
+        directory.writeUInt32LE(offset, 42);
+        central.push(directory, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    const centralOffset = offset;
+    const centralSize = central.reduce((size, chunk) => size + chunk.length, 0);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(END_OF_CENTRAL_DIRECTORY, 0);
+    end.writeUInt16LE(0, 4);
+    end.writeUInt16LE(0, 6);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralSize, 12);
+    end.writeUInt32LE(centralOffset, 16);
+    end.writeUInt16LE(0, 20);
+    return Buffer.concat([...chunks, ...central, end]);
+}
+//# sourceMappingURL=zip-writer.js.map

package/pd-cli/dist/services/zip-writer.js.map

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

package/pd-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/pd-cli",
-  "version": "1.164.0",
+  "version": "1.165.0",
   "description": "PD CLI — Pain recording, sample management, and governance tasks for Principles Disciple",
   "type": "module",
   "bin": {

package/pd-mcp-server/dist/index.d.ts

@@ -3,6 +3,7 @@ export { resolveWorkspaceBinding, WORKSPACE_DIR_ENV, HOST_ENV } from './workspac
 export { RESPONSE_BUDGET_BYTES, withinBudget, measureTextBytes } from './budget.js';
 export { DEFAULT_DEADLINE_MS, MAX_TRACKED_ORPHANS, runWithDeadline, OrphanLimiter } from './deadline.js';
 export { SERVER_NAME, SERVER_VERSION, MCP_SDK_PIN } from './version.js';
+export { LOG_ENV, LOG_DIR_ENV, LOG_FILE_ENV, LOG_MAX_FILE_BYTES, LOG_MAX_DIR_BYTES, LOG_RETENTION_MS, createMcpFileLog, combineSinks, } from './log-file.js';
 /**
  * Run the stdio server against the real process env. Returns the intended
  * process exit code: 0 after a clean shutdown, 1 for a fail-closed startup.

package/pd-mcp-server/dist/index.js

@@ -11,7 +11,10 @@
  * suppressed), release resources, exit 0.
  *
  * stdout carries MCP protocol messages ONLY (§5.3). This module never
- * console.log's; logs go through the sanitized stderr logger.
+ * console.log's; logs go through the sanitized stderr logger and, when
+ * enabled, the durable JSONL file sink (`~/.pd/logs/mcp`). File logging is
+ * strictly observational: every failure is swallowed and can never change a
+ * result, the protocol stream, the 32 KiB budget or the 10 s deadline.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createHash } from 'node:crypto';
@@ -19,27 +22,166 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createPdMcpServer } from './server.js';
 import { resolveWorkspaceBinding } from './workspace.js';
-import { stderrLog } from './logging.js';
+import { combineSinks, createMcpFileLog } from './log-file.js';
+import { createLogger, stderrSink } from './logging.js';
 export { createPdMcpServer, TOOL_NAME, toolInputSchema } from './server.js';
 export { resolveWorkspaceBinding, WORKSPACE_DIR_ENV, HOST_ENV } from './workspace.js';
 export { RESPONSE_BUDGET_BYTES, withinBudget, measureTextBytes } from './budget.js';
 export { DEFAULT_DEADLINE_MS, MAX_TRACKED_ORPHANS, runWithDeadline, OrphanLimiter } from './deadline.js';
 export { SERVER_NAME, SERVER_VERSION, MCP_SDK_PIN } from './version.js';
+export { LOG_ENV, LOG_DIR_ENV, LOG_FILE_ENV, LOG_MAX_FILE_BYTES, LOG_MAX_DIR_BYTES, LOG_RETENTION_MS, createMcpFileLog, combineSinks, } from './log-file.js';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Bounded, path-free label for client names / versions / protocol ids. */
+function safeLabel(value, max = 48) {
+    if (typeof value !== 'string')
+        return undefined;
+    const cleaned = value.replace(/[^\x20-\x7e]/g, '').replace(/[^\w.#/+:@-]/g, '').slice(0, max);
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+function safeId(value) {
+    if (typeof value === 'string')
+        return safeLabel(value, 40);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
+const OBSERVED_METHODS = ['initialize', 'tools/list'];
+/**
+ * Stdio transport that observes — never alters — the JSON-RPC stream.
+ * `initialize` / `tools/list` are otherwise invisible to the server layer:
+ * MCP only exposes tool callbacks, so a handshake failure would leave no
+ * evidence at all. Observation is wrapped in try/catch and always forwards
+ * the untouched message to the SDK.
+ */
+class ObservingStdioTransport extends StdioServerTransport {
+    observeLog;
+    pending = new Map();
+    constructor(observeLog) {
+        super();
+        this.observeLog = observeLog;
+    }
+    async start() {
+        const inner = this.onmessage;
+        this.onmessage = (message) => {
+            try {
+                this.observeInbound(message);
+            }
+            catch {
+                // Observation must never break the protocol.
+            }
+            inner?.(message);
+        };
+        return super.start();
+    }
+    async send(message) {
+        try {
+            this.observeOutbound(message);
+        }
+        catch {
+            // Observation must never break the protocol.
+        }
+        return super.send(message);
+    }
+    observeInbound(message) {
+        if (!isRecord(message) || typeof message.method !== 'string')
+            return;
+        const { method } = message;
+        if (!OBSERVED_METHODS.includes(method))
+            return;
+        const id = safeId(message.id);
+        if (id === undefined)
+            return;
+        const params = isRecord(message.params) ? message.params : {};
+        const clientInfo = isRecord(params.clientInfo) ? params.clientInfo : {};
+        const capabilities = isRecord(params.capabilities) ? params.capabilities : {};
+        this.pending.set(id, {
+            method: method === 'initialize' ? 'initialize' : 'tools/list',
+            startedAt: Date.now(),
+        });
+        if (method === 'initialize') {
+            this.observeLog('info', 'initialize', {
+                phase: 'request',
+                requestId: id,
+                clientName: safeLabel(clientInfo.name) ?? 'unknown',
+                clientVersion: safeLabel(clientInfo.version) ?? 'unknown',
+                protocolVersion: safeLabel(params.protocolVersion) ?? 'unknown',
+                capabilityKeysCount: Object.keys(capabilities).length,
+            });
+        }
+        else {
+            this.observeLog('info', 'tools_list', { phase: 'request', requestId: id });
+        }
+    }
+    observeOutbound(message) {
+        if (!isRecord(message))
+            return;
+        const id = safeId(message.id);
+        if (id === undefined)
+            return;
+        const pending = this.pending.get(id);
+        if (pending === undefined)
+            return;
+        this.pending.delete(id);
+        const error = isRecord(message.error) ? message.error : undefined;
+        const result = isRecord(message.result) ? message.result : undefined;
+        const ok = error === undefined;
+        const baseFields = {
+            phase: 'response',
+            requestId: id,
+            ok,
+            durationMs: Date.now() - pending.startedAt,
+            responseBytes: byteLength(message),
+        };
+        if (pending.method === 'initialize') {
+            const fields = { ...baseFields };
+            if (!ok)
+                fields.errorCode = safeId(error.code) ?? 'unknown_error';
+            this.observeLog(ok ? 'info' : 'error', 'initialize', fields);
+        }
+        else {
+            const tools = Array.isArray(result?.tools) ? result?.tools : undefined;
+            const fields = {
+                ...baseFields,
+                toolCount: tools?.length ?? 0,
+            };
+            if (!ok)
+                fields.errorCode = safeId(error.code) ?? 'unknown_error';
+            this.observeLog(ok ? 'info' : 'error', 'tools_list', fields);
+        }
+    }
+}
 /**
  * Run the stdio server against the real process env. Returns the intended
  * process exit code: 0 after a clean shutdown, 1 for a fail-closed startup.
  */
 export async function main(env = process.env) {
+    const fileLog = createMcpFileLog(env);
+    const sink = fileLog.enabled ? combineSinks(stderrSink, fileLog.sink) : stderrSink;
+    const log = createLogger(sink);
     const binding = resolveWorkspaceBinding(env);
     if (!binding.ok) {
         // Fail-closed BEFORE initialize: one sanitized stderr line with the
-        // reason and the next action; nothing about values or paths.
-        stderrLog('error', 'startup_binding_failed', {
-            envVar: binding.envVar,
+        // reason and the next action; nothing about values or paths. The same
+        // fact lands on disk as `startup_failure` so a host that cannot even
+        // reach `initialize` still leaves PD-side evidence.
+        log('error', 'startup_failure', {
+            stage: 'server',
             reasonCategory: 'invalid_binding',
-            reason: binding.reason,
+            reasonCode: binding.reasonCode,
+            envVar: binding.envVar,
             nextAction: binding.nextAction,
         });
+        fileLog.flushSync();
         return 1;
     }
     // Workspace fingerprint (NOT the path): lets operators and acceptance runs
@@ -50,16 +192,31 @@ export async function main(env = process.env) {
         .update(path.resolve(binding.binding.workspaceDir))
         .digest('hex')
         .slice(0, 16);
-    stderrLog('info', 'startup', { host: binding.binding.host ?? 'unspecified', workspaceFingerprint });
-    const handle = createPdMcpServer({ workspaceDir: binding.binding.workspaceDir, host: binding.binding.host });
-    const transport = new StdioServerTransport();
+    log('info', 'startup', {
+        host: binding.binding.host ?? 'unspecified',
+        workspaceFingerprint,
+        nodeVersion: process.version,
+        platform: process.platform,
+    });
+    const handle = createPdMcpServer({
+        workspaceDir: binding.binding.workspaceDir,
+        host: binding.binding.host,
+        logSink: sink,
+    });
+    const transport = new ObservingStdioTransport(log);
     await handle.mcpServer.connect(transport);
     // Host-driven shutdown: stdin close → SDK closes the transport → we stop
     // accepting new work, let in-flight calls drain (bounded by the deadline)
     // and exit cleanly. The transport close callback is the single trigger.
     transport.onclose = () => {
         handle.beginShutdown();
-        stderrLog('info', 'transport_closed', { orphans: handle.orphans.size });
+        log('info', 'shutdown', {
+            reason: 'stdin_closed',
+            orphans: handle.orphans.size,
+            active: handle.admissions.active,
+            uptimeMs: Math.round(process.uptime() * 1000),
+        });
+        fileLog.flushSync();
     };
     return 0;
 }

package/pd-mcp-server/dist/log-file.d.ts

@@ -0,0 +1,26 @@
+export declare const LOG_ENV: 'PD_MCP_LOG';
+export declare const LOG_DIR_ENV: 'PD_MCP_LOG_DIR';
+/** Internal launcher → server contract (basename only, never a path). */
+export declare const LOG_FILE_ENV: 'PD_MCP_LOG_FILE';
+export declare const LOG_RUN_ID_ENV: 'PD_MCP_LOG_RUN_ID';
+export declare const LOG_SEQ_ENV: 'PD_MCP_LOG_SEQ';
+export declare const LOG_MAX_FILE_BYTES: number;
+export declare const LOG_MAX_DIR_BYTES: number;
+export declare const LOG_RETENTION_MS: number;
+export declare const LOG_MAX_SHARDS = 3;
+export interface McpFileLog {
+    /** False when `PD_MCP_LOG=0` or the log directory cannot be resolved. */
+    readonly enabled: boolean;
+    readonly sink: (line: string) => void;
+    /** Flush pending lines synchronously; used on startup failure/shutdown. */
+    flushSync(): void;
+    readonly dir: string | null;
+    readonly file: string | null;
+}
+/**
+ * Create the process log sink. Never throws: an unusable directory degrades to
+ * a running-but-silent sink (stderr logging stays untouched).
+ */
+export declare function createMcpFileLog(env?: Record<string, unknown>, clock?: () => Date): McpFileLog;
+/** Compose sinks; a broken sink never prevents the others from running. */
+export declare function combineSinks(...sinks: readonly ((line: string) => void)[]): (line: string) => void;

package/pd-mcp-server/dist/log-file.js

@@ -0,0 +1,312 @@
+/**
+ * Durable JSONL sink for PD MCP observability (default ON).
+ *
+ * Every entry the process already emits through `createLogger` is also appended
+ * to `~/.pd/logs/mcp/mcp-<host>-<pid>-<stamp>.jsonl`. This module is
+ * deliberately defensive: no export ever throws, and a failure to write logs
+ * can only lose log lines — it can never change a tool result, the stdio
+ * protocol stream, the 32 KiB budget or the 10 s deadline.
+ *
+ * Privacy: the sink only enriches entries the existing scalar-whitelist logger
+ * produced. It never accepts bodies, paths or env values; fields are counts,
+ * enums, booleans and fingerprints.
+ *
+ * Limits: one file per process (the launcher opens the file first and passes
+ * its basename through the internal env so the server appends instead of
+ * opening a second one), 2 MiB per file, at most 3 shards per process, 64 MiB
+ * per directory, 14 days retention. Maintenance runs best-effort at open and
+ * rotation time.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+export const LOG_ENV = 'PD_MCP_LOG';
+export const LOG_DIR_ENV = 'PD_MCP_LOG_DIR';
+/** Internal launcher → server contract (basename only, never a path). */
+export const LOG_FILE_ENV = 'PD_MCP_LOG_FILE';
+export const LOG_RUN_ID_ENV = 'PD_MCP_LOG_RUN_ID';
+export const LOG_SEQ_ENV = 'PD_MCP_LOG_SEQ';
+export const LOG_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const LOG_MAX_DIR_BYTES = 64 * 1024 * 1024;
+export const LOG_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+export const LOG_MAX_SHARDS = 3;
+const MAX_BUFFER_LINES = 200;
+const MAX_BUFFER_BYTES = 256 * 1024;
+const DISABLED_VALUES = ['0', 'false', 'off'];
+const ADOPTED_FILE = /^mcp-[^\\/:*?"<>|\s]{1,120}\.jsonl$/;
+const RUN_ID = /^[0-9a-f]{8}$/;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function envString(env, key) {
+    const value = env[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function isEnabled(env) {
+    const value = envString(env, LOG_ENV);
+    if (value === undefined)
+        return true;
+    return !DISABLED_VALUES.includes(value.trim().toLowerCase());
+}
+function resolveDir(env) {
+    const override = envString(env, LOG_DIR_ENV);
+    if (override !== undefined && override.trim().length > 0)
+        return path.resolve(override);
+    try {
+        return path.join(os.homedir(), '.pd', 'logs', 'mcp');
+    }
+    catch {
+        return null;
+    }
+}
+function resolveAdoptedFile(env) {
+    const name = envString(env, LOG_FILE_ENV);
+    return name !== undefined && ADOPTED_FILE.test(name) ? name : null;
+}
+function resolveRunId(env) {
+    const given = envString(env, LOG_RUN_ID_ENV);
+    if (given !== undefined && RUN_ID.test(given))
+        return given;
+    return randomBytes(4).toString('hex');
+}
+function resolveSeq(env) {
+    const raw = envString(env, LOG_SEQ_ENV);
+    const parsed = raw === undefined ? Number.NaN : Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed >= 0 && parsed < 1_000_000 ? parsed : 0;
+}
+function pad(value, width = 2) {
+    return String(value).padStart(width, '0');
+}
+/** RFC3339 with a numeric local offset, plus the offset in minutes. */
+function localTimestamp(date) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const abs = Math.abs(offsetMinutes);
+    const ts = `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+    return { ts, tzOffsetMinutes: offsetMinutes };
+}
+function utcStamp(date) {
+    return (`${pad(date.getUTCFullYear(), 4)}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}` +
+        `T${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}Z`);
+}
+function listOwnLogFiles(dir) {
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const out = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^mcp-.*\.jsonl$/.test(entry.name))
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            try {
+                const stat = fs.statSync(fullPath);
+                out.push({ fullPath, size: stat.size, mtimeMs: stat.mtimeMs });
+            }
+            catch {
+                // Concurrent cleanup removed it — ignore.
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Best-effort retention + directory cap. Never throws, never deletes non-PD files. */
+function maintainDirectory(dir, nowMs, keepPath) {
+    try {
+        const files = listOwnLogFiles(dir);
+        const survivors = [];
+        for (const file of files) {
+            if (nowMs - file.mtimeMs > LOG_RETENTION_MS) {
+                if (file.fullPath === keepPath) {
+                    survivors.push(file);
+                    continue;
+                }
+                try {
+                    fs.unlinkSync(file.fullPath);
+                }
+                catch {
+                    survivors.push(file);
+                }
+            }
+            else {
+                survivors.push(file);
+            }
+        }
+        let total = survivors.reduce((sum, file) => sum + file.size, 0);
+        if (total <= LOG_MAX_DIR_BYTES)
+            return;
+        const removable = survivors
+            .filter((file) => file.fullPath !== keepPath)
+            .sort((left, right) => left.mtimeMs - right.mtimeMs);
+        for (const file of removable) {
+            if (total <= LOG_MAX_DIR_BYTES)
+                break;
+            try {
+                fs.unlinkSync(file.fullPath);
+                total -= file.size;
+            }
+            catch {
+                // Another process owns it or it vanished — leave it.
+            }
+        }
+    }
+    catch {
+        // Maintenance is advisory only.
+    }
+}
+function sanitizeSegment(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40);
+    return cleaned.length > 0 ? cleaned : 'unknown';
+}
+const NOOP_LOG = {
+    enabled: false,
+    sink: () => undefined,
+    flushSync: () => undefined,
+    dir: null,
+    file: null,
+};
+/**
+ * Create the process log sink. Never throws: an unusable directory degrades to
+ * a running-but-silent sink (stderr logging stays untouched).
+ */
+export function createMcpFileLog(env = process.env, clock = () => new Date()) {
+    try {
+        if (!isEnabled(env))
+            return NOOP_LOG;
+        const dir = resolveDir(env);
+        if (dir === null)
+            return NOOP_LOG;
+        const openedAt = clock();
+        try {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            if (!fs.statSync(dir).isDirectory())
+                return { ...NOOP_LOG, enabled: true, dir };
+        }
+        catch {
+            // Directory unavailable (e.g. a file occupies the path): stay silent.
+            return { ...NOOP_LOG, enabled: true, dir };
+        }
+        maintainDirectory(dir, openedAt.getTime(), null);
+        const host = sanitizeSegment(envString(env, 'PD_MCP_HOST') ?? 'unknown');
+        const adopted = resolveAdoptedFile(env);
+        const baseName = adopted ?? `mcp-${host}-${process.pid}-${utcStamp(openedAt)}.jsonl`;
+        const runId = resolveRunId(env);
+        let seq = resolveSeq(env);
+        let shard = 1;
+        let currentPath = shard === 1 ? path.join(dir, baseName) : path.join(dir, baseName.replace(/\.jsonl$/, `-${shard}.jsonl`));
+        let currentBytes = 0;
+        try {
+            currentBytes = fs.statSync(currentPath).size;
+        }
+        catch {
+            currentBytes = 0;
+        }
+        if (currentBytes >= LOG_MAX_FILE_BYTES) {
+            shard = 2;
+            currentPath = path.join(dir, baseName.replace(/\.jsonl$/, `-${shard}.jsonl`));
+            currentBytes = 0;
+        }
+        let buffer = [];
+        let bufferBytes = 0;
+        let scheduled = false;
+        let exhausted = shard > LOG_MAX_SHARDS;
+        function rotate() {
+            if (shard >= LOG_MAX_SHARDS) {
+                exhausted = true;
+                return;
+            }
+            shard += 1;
+            currentPath = path.join(dir, baseName.replace(/\.jsonl$/, `-${shard}.jsonl`));
+            currentBytes = 0;
+            maintainDirectory(dir, clock().getTime(), currentPath);
+        }
+        function flush() {
+            scheduled = false;
+            if (buffer.length === 0)
+                return;
+            const batch = buffer.join('');
+            buffer = [];
+            bufferBytes = 0;
+            try {
+                const bytes = Buffer.byteLength(batch, 'utf8');
+                if (currentBytes + bytes > LOG_MAX_FILE_BYTES)
+                    rotate();
+                if (exhausted || currentBytes + bytes > LOG_MAX_FILE_BYTES)
+                    return;
+                fs.appendFileSync(currentPath, batch, { mode: 0o600 });
+                currentBytes += bytes;
+            }
+            catch {
+                // Drop the batch. Logging must never affect the caller.
+            }
+        }
+        function flushSync() {
+            try {
+                flush();
+            }
+            catch {
+                // Swallow even a synchronous flush defect.
+            }
+        }
+        function sink(line) {
+            try {
+                const parsed = JSON.parse(line);
+                if (!isRecord(parsed))
+                    return;
+                const stamp = localTimestamp(clock());
+                parsed.ts = stamp.ts;
+                parsed.tzOffsetMinutes = stamp.tzOffsetMinutes;
+                parsed.runId = runId;
+                parsed.seq = (seq += 1);
+                const enriched = JSON.stringify(parsed);
+                buffer.push(enriched + '\n');
+                bufferBytes += Buffer.byteLength(enriched, 'utf8');
+                if (buffer.length >= MAX_BUFFER_LINES || bufferBytes >= MAX_BUFFER_BYTES)
+                    flushSync();
+                else if (!scheduled) {
+                    scheduled = true;
+                    setImmediate(() => {
+                        try {
+                            flush();
+                        }
+                        catch {
+                            // Swallow.
+                        }
+                    });
+                }
+            }
+            catch {
+                // Swallow: enrichment/serialization errors must not reach the server.
+            }
+        }
+        return {
+            enabled: true,
+            sink,
+            flushSync,
+            dir,
+            get file() {
+                return currentPath;
+            },
+        };
+    }
+    catch {
+        return { ...NOOP_LOG, enabled: true };
+    }
+}
+/** Compose sinks; a broken sink never prevents the others from running. */
+export function combineSinks(...sinks) {
+    return (line) => {
+        for (const sink of sinks) {
+            try {
+                sink(line);
+            }
+            catch {
+                // Isolate sinks from each other.
+            }
+        }
+    };
+}