fix(server): T3 Connect keeps a log file of its tunnel connector

apps/server/src/cloud/ManagedEndpointRuntime.test.ts

@@ -6,12 +6,15 @@ import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as PlatformError from "effect/PlatformError";
 import * as Queue from "effect/Queue";
 import * as References from "effect/References";
+import * as Schema from "effect/Schema";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
@@ -42,6 +45,15 @@ const layerRelayClientAvailable = Layer.succeed(
 
 const unusedHttpClient = HttpClient.make(() => Effect.die("unused"));
 
+const decodeLogEntry = Schema.decodeUnknownSync(
+  Schema.fromJsonString(
+    Schema.Struct({
+      level: Schema.String,
+      message: Schema.Tuple([Schema.String, Schema.Unknown]),
+    }),
+  ),
+);
+
 const emptySecretStoreLayer = Layer.mock(ServerSecretStore.ServerSecretStore)({
   get: () => Effect.succeedNone,
   set: () => Effect.void,
@@ -59,7 +71,8 @@ const runtimeDependencies = (
     Layer.succeed(HttpClient.HttpClient, httpClient),
     relayClientLayer,
     secretStoreLayer,
-  );
+    ServerConfig.layerTest(process.cwd(), { prefix: "t3-managed-endpoint-" }),
+  ).pipe(Layer.provideMerge(NodeServices.layer));
 
 const buildCloudManagedEndpointRuntime = (
   spawner: ReturnType<typeof ChildProcessSpawner.make>,
@@ -543,6 +556,97 @@ describe("CloudManagedEndpointRuntime", () => {
     }),
   );
 
+  it.effect("keeps redacted connector logs bounded even when rotation fails", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      for (const rotationBlocked of [false, true]) {
+        const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-relay-client-log-" });
+        const logPath = path.join(baseDir, "userdata", "logs", "relay-client.ndjson");
+        const existingLog = "x".repeat(1024 * 1024);
+        if (rotationBlocked) {
+          yield* fs.makeDirectory(`${logPath}.2`, { recursive: true });
+          yield* fs.writeFileString(`${logPath}.2/blocked`, "blocks rotation");
+          yield* fs.writeFileString(logPath, existingLog);
+        }
+        const warnings: unknown[] = [];
+        const logger = Logger.make(({ message }) => {
+          if (Array.isArray(message) && message[0] === "Relay client log unavailable") {
+            warnings.push(message);
+          }
+        });
+        const fixture = yield* makeTransportSpawner();
+        yield* Effect.gen(function* () {
+          const context = yield* Layer.build(
+            ManagedEndpointRuntime.layer.pipe(
+              Layer.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+              Layer.provide(runtimeDependencies(fixture.spawner)),
+            ),
+          );
+          const runtime = yield* Effect.service(
+            ManagedEndpointRuntime.CloudManagedEndpointRuntime,
+          ).pipe(Effect.provide(context));
+          yield* runtime.applyConfig({ ...tunnelConfig, connectorToken: "connector-secret" });
+          yield* fixture.observe(
+            runtime,
+            0,
+            '2026-10-16T20:29:40Z ERR Failed to serve tunnel connection error="rejected connector-secret" connIndex=0\n',
+          );
+        }).pipe(Effect.scoped, Effect.withLogger(logger));
+
+        const log = yield* fs.readFileString(logPath);
+        if (rotationBlocked) {
+          expect(log.length).toBe(existingLog.length);
+          expect(warnings).toHaveLength(1);
+          continue;
+        }
+        const entries = log
+          .trim()
+          .split("\n")
+          .map((line) => decodeLogEntry(line));
+        expect(entries.map((entry) => [entry.level, entry.message[0]])).toEqual([
+          ["INFO", "Relay client process started; waiting for tunnel connection"],
+          ["WARN", "Relay client reported a transport warning"],
+          ["INFO", "Relay client tunnel connection registered"],
+          ["INFO", "Relay client stopped"],
+        ]);
+        expect(log).toContain("rejected <redacted>");
+        expect(log).not.toContain("connector-secret");
+        const oversizedFixture = yield* makeTransportSpawner();
+        yield* Effect.gen(function* () {
+          const context = yield* Layer.build(
+            ManagedEndpointRuntime.layer.pipe(
+              Layer.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
+              Layer.provide(runtimeDependencies(oversizedFixture.spawner)),
+            ),
+          );
+          const runtime = yield* Effect.service(
+            ManagedEndpointRuntime.CloudManagedEndpointRuntime,
+          ).pipe(Effect.provide(context));
+          yield* runtime.applyConfig(tunnelConfig);
+          yield* oversizedFixture.observe(runtime, 0, "ERR " + "界".repeat(1024 * 1024) + "\n");
+        }).pipe(Effect.scoped);
+        const files = yield* fs.readDirectory(path.dirname(logPath));
+        const allEntries = [];
+        for (const file of files.filter((name) => name.startsWith("relay-client.ndjson"))) {
+          const contents = yield* fs.readFileString(path.join(path.dirname(logPath), file));
+          expect(Buffer.byteLength(contents)).toBeLessThanOrEqual(1024 * 1024);
+          allEntries.push(
+            ...contents
+              .trim()
+              .split("\n")
+              .map((line) => decodeLogEntry(line)),
+          );
+        }
+        expect(
+          allEntries.some(
+            (entry) => entry.message[0] === "Relay client log entry omitted: exceeds 1 MiB",
+          ),
+        ).toBe(true);
+      }
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
   it.effect("discards a pending fallback when its connector is replaced or removed", () =>
     Effect.gen(function* () {
       for (const nextConfig of [{ ...tunnelConfig, connectorToken: "replacement" }, null]) {

apps/server/src/cloud/ManagedEndpointRuntime.ts

@@ -1,4 +1,5 @@
 import type { RelayManagedEndpointRuntimeConfig } from "@t3tools/contracts/relay";
+import { RotatingFileSink } from "@t3tools/shared/logging";
 import * as RelayClient from "@t3tools/shared/relayClient";
 import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
@@ -7,7 +8,9 @@ import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as Queue from "effect/Queue";
 import * as Ref from "effect/Ref";
 import * as Result from "effect/Result";
@@ -20,6 +23,7 @@ import * as ChildProcess from "effect/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerConfig from "../config.ts";
 import * as ManagedLimits from "../policy/managedLimits.ts";
 import * as ManagedPolicy from "../policy/ManagedPolicy.ts";
 
@@ -123,6 +127,7 @@ const encodeHttp2Fallback = Schema.encodeSync(Http2Fallback);
 // than this, so a crash-looping connector or an offline host does not redownload
 // on every reconcile.
 const RELAY_CLIENT_INSTALL_RETRY_INTERVAL_MS = 10 * 60_000;
+export const RELAY_CLIENT_LOG_FILE = "relay-client.ndjson";
 
 /** Preserve user-chosen PATH binaries and overrides; CLI downloads require consent. */
 function needsPinnedRelayClient(executable: RelayClient.RelayClientStatus): boolean {
@@ -227,6 +232,60 @@ export const make = Effect.gen(function* () {
   const quicStallsRef = yield* Ref.make<ReadonlyArray<number>>([]);
   let reconcileConfig: CloudManagedEndpointRuntime["Service"]["applyConfig"];
 
+  const { logsDir } = yield* ServerConfig.ServerConfig;
+  const path = yield* Path.Path;
+  const relayClientLogPath = path.join(logsDir, RELAY_CLIENT_LOG_FILE);
+  // Synchronous appends avoid a flush timer for this low-volume log.
+  const fallbackLoggers = yield* Effect.service(Logger.CurrentLoggers);
+  let writeFailureReported = false;
+  const relayClientLog = yield* Effect.try(
+    () =>
+      new RotatingFileSink({
+        filePath: relayClientLogPath,
+        maxBytes: 1024 * 1024,
+        maxFiles: 2,
+        throwOnError: true,
+      }),
+  ).pipe(
+    Effect.map((sink) =>
+      Logger.make((options) => {
+        try {
+          const entry = Logger.formatJson.log(options);
+          const bytes = Buffer.byteLength(entry) + 1;
+          sink.write(
+            bytes <= 1024 * 1024
+              ? `${entry}\n`
+              : `${JSON.stringify({
+                  timestamp: options.date.toISOString(),
+                  level: options.logLevel.toUpperCase(),
+                  message: ["Relay client log entry omitted: exceeds 1 MiB", { bytes }],
+                })}\n`,
+          );
+        } catch {
+          if (!writeFailureReported) {
+            writeFailureReported = true;
+            for (const logger of fallbackLoggers) {
+              logger.log({
+                ...options,
+                logLevel: "Warn",
+                message: ["Relay client log unavailable", { filePath: relayClientLogPath }],
+              });
+            }
+          }
+        }
+      }),
+    ),
+    Effect.catch((error) =>
+      Effect.logWarning("Relay client log unavailable", {
+        filePath: relayClientLogPath,
+        cause: error,
+      }).pipe(Effect.as(undefined)),
+    ),
+  );
+  // Forked connector fibers inherit this logger after the applyConfig span ends.
+  const withRelayClientLog = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    relayClientLog ? Effect.withLogger(effect, relayClientLog) : effect;
+
   const stopActive = Effect.gen(function* () {
     const active = yield* Ref.getAndSet(activeRef, null);
     yield* stopConnector(active);
@@ -760,6 +819,7 @@ export const make = Effect.gen(function* () {
           return yield* reconcileConfig(config);
         }),
       ),
+    withRelayClientLog,
   );
 
   const readMetrics = <S extends Schema.Decoder<unknown>>(url: string, schema: S) =>

apps/server/src/triage/triagePrompt.test.ts

@@ -72,6 +72,7 @@ const contextInput = {
     logsDir: "/home/u/.t3/userdata/logs",
     serviceLogPath: "/home/u/.t3/userdata/logs/boot-service.log",
     desktopBackendLogGlob: "/home/u/.t3/userdata/logs/server-child*.log*",
+    relayClientLogPath: "/home/u/.t3/userdata/logs/relay-client.ndjson",
     serverTracePath: "/home/u/.t3/userdata/logs/server.trace.ndjson",
     providerEventLogPath: "/home/u/.t3/userdata/logs/provider/events.log",
     terminalLogsDir: "/home/u/.t3/userdata/logs/terminals",

apps/server/src/triage/triagePrompt.ts

@@ -217,6 +217,7 @@ export interface TriageContextInput {
     readonly logsDir: string;
     readonly serviceLogPath: string;
     readonly desktopBackendLogGlob: string;
+    readonly relayClientLogPath: string;
     readonly serverTracePath: string;
     readonly providerEventLogPath: string;
     readonly terminalLogsDir: string;
@@ -302,6 +303,7 @@ ${input.entry.kind === "app" ? IN_APP_SECTION : ""}${input.sourceClone === undef
 - Logs dir: ${input.paths.logsDir}
 - Service log (systemd/launchd service installs only): ${input.paths.serviceLogPath}
 - Desktop backend logs (glob; one file per backend plus rotated copies; written only when a backend crashes or fails to start): ${input.paths.desktopBackendLogGlob}
+- T3 Connect tunnel log (ndjson; what the server logged about its cloudflared connector, with rotated copies \`.1\` and \`.2\`): ${input.paths.relayClientLogPath}
 - Server trace (ndjson): ${input.paths.serverTracePath}
 - Provider event log: ${input.paths.providerEventLogPath}
 - Terminal logs: ${input.paths.terminalLogsDir}

apps/server/src/triage/triageSession.ts

@@ -10,6 +10,7 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 
 import * as BootService from "../cloud/bootService.ts";
+import * as ManagedEndpointRuntime from "../cloud/ManagedEndpointRuntime.ts";
 import type * as ServerConfig from "../config.ts";
 import { isProcessAlive, readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 import {
@@ -80,6 +81,7 @@ export const writeTriageSession = Effect.fn("triage.writeTriageSession")(functio
         logsDir: paths.logsDir,
         serviceLogPath: path.join(paths.logsDir, BootService.BOOT_SERVICE_LOG_FILE),
         desktopBackendLogGlob: path.join(paths.logsDir, "server-child*.log*"),
+        relayClientLogPath: path.join(paths.logsDir, ManagedEndpointRuntime.RELAY_CLIENT_LOG_FILE),
         serverTracePath: paths.serverTracePath,
         providerEventLogPath: paths.providerEventLogPath,
         terminalLogsDir: paths.terminalLogsDir,

docs/user/t3-connect-troubleshooting.md

@@ -151,3 +151,7 @@ If none of this helps, open an issue on
 - The text from **Copy diagnostics** in the environment's **Details**.
 - The output of `t3 connect status` on the host.
 - The trace ID, if one is shown.
+- If the tunnel dropped earlier, the host's tunnel log, `relay-client.ndjson`
+  in the logs folder (`~/.t3/userdata/logs` by default). It records when the
+  tunnel connected, warned, exited, and restarted, with the tunnel token
+  removed.