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

apps/server/src/cli/triage.ts

@@ -17,6 +17,7 @@ import { Command, Flag } from "effect/cli";
 
 import packageJson from "../../package.json" with { type: "json" };
 import * as BootService from "../cloud/bootService.ts";
+import * as ManagedEndpointRuntime from "../cloud/ManagedEndpointRuntime.ts";
 import * as ServerConfig from "../config.ts";
 import { resolveBaseDir } from "../os-jank.ts";
 import { isProcessAlive, readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
@@ -185,6 +186,10 @@ export const triageCommand = Command.make("triage", {
             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,

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

@@ -44,6 +44,7 @@ it("context file labels the CLI version as the CLI's, not the user's build", ()
       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/cli/triagePrompt.ts

@@ -185,6 +185,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;
@@ -213,6 +214,7 @@ Generated by \`t3 triage\` at ${input.generatedAt}.
 - 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/cloud/ManagedEndpointRuntime.test.ts

@@ -1,13 +1,17 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import { describe, expect, it } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
 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 Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as PlatformError from "effect/PlatformError";
 import * as Queue from "effect/Queue";
+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";
@@ -17,6 +21,7 @@ import type { RelayManagedEndpointRuntimeConfig } from "@t3tools/contracts/relay
 import * as RelayClient from "@t3tools/shared/relayClient";
 
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerConfig from "../config.ts";
 import * as ManagedEndpointRuntime from "./ManagedEndpointRuntime.ts";
 
 const layerRelayClientAvailable = Layer.succeed(
@@ -36,6 +41,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 runtimeDependencies = (
   spawner: ReturnType<typeof ChildProcessSpawner.make>,
   relayClientLayer = layerRelayClientAvailable,
@@ -48,7 +62,8 @@ const runtimeDependencies = (
     Layer.mock(ServerSecretStore.ServerSecretStore)({
       get: () => Effect.succeedNone,
     }),
-  );
+    ServerConfig.layerTest(process.cwd(), { prefix: "t3-managed-endpoint-" }),
+  ).pipe(Layer.provideMerge(NodeServices.layer));
 
 const buildCloudManagedEndpointRuntime = (
   spawner: ReturnType<typeof ChildProcessSpawner.make>,
@@ -321,6 +336,48 @@ describe("CloudManagedEndpointRuntime", () => {
     }),
   );
 
+  it.effect("keeps the connector's log lines in a file with the token redacted", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-relay-client-log-" });
+      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);
+
+      const log = yield* fs.readFileString(
+        path.join(baseDir, "userdata", "logs", "relay-client.ndjson"),
+      );
+      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");
+    }).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";
@@ -19,6 +22,8 @@ import { HttpClient, HttpClientResponse } from "effect/http";
 import * as ChildProcess from "effect/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 
+import * as ServerConfig from "../config.ts";
+
 export type CloudManagedEndpointRuntimeStatus =
   | {
       readonly status: "disabled";
@@ -119,6 +124,12 @@ const QUIC_STALL_WINDOW_MS = 5 * 60_000;
 // 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;
+// The connector's fibers outlive the span that started them, so the trace file
+// misses their messages, and a desktop backend's stdout reaches disk only after
+// a crash. This file keeps what the runtime logs, connector output included.
+export const RELAY_CLIENT_LOG_FILE = "relay-client.ndjson";
+const RELAY_CLIENT_LOG_MAX_BYTES = 1024 * 1024;
+const RELAY_CLIENT_LOG_MAX_FILES = 2;
 
 /**
  * A PATH binary or an explicit override is the user's choice, and the CLI asks
@@ -214,6 +225,40 @@ 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);
+  // A synchronous append per line keeps a timer off an idle server; the
+  // connector logs a few lines a minute.
+  const relayClientLog = yield* Effect.try(
+    () =>
+      new RotatingFileSink({
+        filePath: relayClientLogPath,
+        maxBytes: RELAY_CLIENT_LOG_MAX_BYTES,
+        maxFiles: RELAY_CLIENT_LOG_MAX_FILES,
+      }),
+  ).pipe(
+    Effect.map((sink) =>
+      Logger.make((options) => {
+        try {
+          sink.write(`${Logger.formatJson.log(options)}\n`);
+        } catch {
+          // A log file that stops taking writes must not fail the connector fibers.
+        }
+      }),
+    ),
+    Effect.catch((error) =>
+      Effect.logWarning("Relay client log unavailable", {
+        filePath: relayClientLogPath,
+        cause: error,
+      }).pipe(Effect.as(undefined)),
+    ),
+  );
+  // Fibers inherit their loggers, so the connector fibers forked under
+  // applyConfig write here too.
+  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);
@@ -747,6 +792,7 @@ export const make = Effect.gen(function* () {
           return yield* reconcileConfig(config);
         }),
       ),
+    withRelayClientLog,
   );
 
   const readMetrics = <S extends Schema.Decoder<unknown>>(url: string, schema: S) =>

docs/user/t3-connect-troubleshooting.md

@@ -149,3 +149,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.