release-2.7.1 (#1296)

* Add Helm and GitOps deployment setup * fix: build better-sqlite3 from source in Docker (#1267) * fix: preserve runtime SSL settings (#1268) * fix: support forwarding from the memory SSH agent (#1269) * fix: support forwarding from the memory agent * style: format memory agent test * fix: prompt for encrypted SFTP key passphrases (#1270) * fix: prompt for SFTP key passphrases * style: format SSH key utility test * fix: include host context in automation notifications (#1271) * fix: include host context in automation notifications * style: format automation notification changes * fix: reserve sidebar height for host tags (#1272) * fix: keep host action rows stable at large font sizes (#1273) * fix: honor certificate setting during server probe (#1274) * fix: package standard Linux icon sizes (#1275) * fix: avoid duplicate Docker HTTPS listener (#1276) * Fix host status without metrics collection (#1277) * fix: allow eight-digit secure auth codes (#1263) Allow TOTP prompts to accept secure auth codes longer than six digits without blocking valid authentication attempts. Generated with Codebuff 🤖 Co-authored-by: Chetan <chetan.development@gmail.com> Co-authored-by: Codebuff <noreply@codebuff.com> * Harden Helm deployment defaults * Update Helm workflow action * Exclude Helm templates from Prettier * Fix browser RDP file drops (#1279) * Fix Proxmox guest credential usernames (#1280) * Add WSL local terminal option (#1281) * refactor: split the transfer engine into focused modules (#1282) * refactor: extract SFTP promisify helpers into sftp-promisify module * refactor: extract transfer timing and rate stats into transfer-stats module * refactor: extract transfer error classes and recovery checks into transfer-errors module * refactor: extract host/path utility helpers into transfer-host-utils module * refactor: extract SFTP directory tree helpers into transfer-sftp-dir module * refactor: extract segment copy job builder into transfer-segment-copy module * refactor: extract file scan and sample helpers into transfer-scan module * refactor: move throttled progress helper into transfer-stats module * style: format transfer modules * perf: optimize tmux monitor aggregation (#1283) * fix: reserve credential tag row height (#1284) * feat: edit AI provider model settings (#1285) * fix: clarify click-to-expand host setting (#1286) * fix: allow portable imports on remote databases (#1287) * fix: allow HTTPS to share the configured port (#1288) * fix: resolve synced jump hosts on the server (#1289) * fix: make terminal clipboard shortcuts layout independent (#1290) * fix: use compatible fetch dispatcher for Tailscale (#1291) * fix: add OIDC environment recovery override (#1292) * fix: coalesce rapid mobile terminal input (#1293) * fix: coalesce rapid mobile terminal input * fix: support clean xterm patch installs * fix: resolve synced remote desktop host IDs (#1295) * feat: make the SFTP file manager path bar editable (#1294) Co-authored-by: Maxime Bonillo <257463937+dropafterfree@users.noreply.github.com> Co-authored-by: ZacharyZcR <zacharyzcr1984@gmail.com> * feat: add passkey sign in to the login screen * fix: remove rounded corners from the host list search bar * fix: stop image storage settings text wrapping to one word per line * fix: prevent malformed websocket messages from crashing the server * chore: increment version * fix: remove gaps between host rows in the sidebar list Keep sub-pixel row measurements and stop wiping the size cache on hover. * fix: Failed to connect through jump hosts (#1180) https://github.com/Termix-SSH/Support/issues/1180 * feat: Progress bar for file downloads in the file manager (#1158) https://github.com/Termix-SSH/Support/issues/1158 * feat: Allow setting Silent OIDC Login via ENV var (#1174) https://github.com/Termix-SSH/Support/issues/1174 * feat: `IdentityFile` to limit the number of attempts by agents (#1165) https://github.com/Termix-SSH/Support/issues/1165 * feat: Credentials clone (#1159) https://github.com/Termix-SSH/Support/issues/1159 * chore: update release notes * docs: move helm setup guide to the docs site * fix: type errors in FilteredAgent agent identity handling * fix: remove stale better-sqlite3 prebuilds so the source build is used * fix: actually build better-sqlite3 from source so arm64 docker images work * fix: credential edit pencil in host editor and add clone action to credential list * fix: clear editingHost so the credential pencil actually opens the editor * chore: run format and lint * fix: folder drag and drop upload failing in the file manager * chore: sync Crowdin translations for 2.7.1 --------- Co-authored-by: alex-ctms <alex-ctms@users.noreply.github.com> Co-authored-by: ZacharyZcR <zacharyzcr1984@gmail.com> Co-authored-by: Chetan Kumar <74929596+ckloop@users.noreply.github.com> Co-authored-by: Chetan <chetan.development@gmail.com> Co-authored-by: Codebuff <noreply@codebuff.com> Co-authored-by: ZacharyZcR <payasonorahc@protonmail.com> Co-authored-by: dropafterfree <maxime.bonillo@gmail.com> Co-authored-by: Maxime Bonillo <257463937+dropafterfree@users.noreply.github.com>
2026-08-29 18:31:33 +00:00 · 2026-08-22 19:47:40 -05:00
parent 566b908daf
commit 76fd9eedbf
165 changed files with 6778 additions and 2090 deletions
@@ -10,6 +10,7 @@ import {
 } from "../../types/automations.js";
 import { createCurrentAutomationRepository } from "../database/repositories/factory.js";
 import { statsLogger } from "../utils/logger.js";
+import { resolveHostById } from "../hosts/host-resolver.js";
 import { executeStep } from "./actions/index.js";
 import type { StepExecutionContext, StepResult } from "./actions/types.js";
 import { compare } from "./conditions.js";
@@ -175,8 +176,33 @@ export class AutomationEngine {

    if (!claimed) this.running.add(automation.id);

+    const trigger = { ...(request.triggerContext ?? {}) };
+    trigger.type ??= request.triggerType;
+    let host: TemplateContext["host"];
+    if (request.triggerHostId) {
+      try {
+        const resolved = await resolveHostById(
+          request.triggerHostId,
+          automation.userId,
+        );
+        if (resolved) {
+          host = {
+            id: request.triggerHostId,
+            name: resolved.name || resolved.ip,
+            ip: resolved.ip,
+            username: resolved.username,
+            port: resolved.port,
+          };
+          trigger.hostName ??= host.name;
+        }
+      } catch {
+        // A notification should still run with its numeric host id.
+      }
+    }
+
    const template: TemplateContext = {
-      trigger: request.triggerContext ?? {},
+      host,
+      trigger,
      steps: {},
      vars: {},
      run: {
@@ -88,6 +88,16 @@ async function sendWebhook(
    headers,
    body: JSON.stringify({
      title: notification.title,
+      hostName:
+        notification.context?.host?.name ??
+        notification.context?.trigger?.hostName,
+      hostId:
+        notification.context?.host?.id ?? notification.context?.trigger?.hostId,
+      ruleName: notification.title,
+      ruleId: notification.context?.run?.automationId,
+      triggerType: notification.context?.trigger?.type,
+      value: notification.context?.trigger?.value,
+      threshold: notification.context?.trigger?.threshold,
      message: notification.body,
      severity: notification.severity,
      timestamp: new Date().toISOString(),
@@ -2052,7 +2052,12 @@ if (sslConfig.enabled) {
    ssl_port: sslConfig.port,
    backend_http_port: HTTP_PORT,
  });
+}

+if (
+  sslConfig.enabled &&
+  process.env.TERMIX_SSL_TERMINATED_BY_NGINX !== "true"
+) {
  try {
    const httpsServer = https.createServer(
      {
@@ -23,21 +23,17 @@ export async function withSqliteForeignKeysDisabled<T>(
 * Backup restore writes tables in an order that is not dependency-safe, so the
 * constraints have to stand down for the duration.
 *
- * **This has no equivalent on Postgres or MySQL here.** Postgres needs
- * superuser to disable triggers, and MySQL's `SET FOREIGN_KEY_CHECKS = 0` is
- * per-connection, which a pool does not guarantee. Rather than run the import
- * with constraints enforced and have it fail partway through — leaving a
- * half-restored database — it refuses with a message that says why.
+ * Postgres and MySQL keep their constraints enabled. The portable importer
+ * writes through repositories and handles individual row failures, so it must
+ * still be allowed to run there; only SQLite needs this connection-local
+ * relaxation for legacy backups whose rows are not dependency ordered.
 */
 export async function withCurrentSqliteForeignKeysDisabled<T>(
  operation: () => Promise<T>,
 ): Promise<T> {
  const dialect = resolveDatabaseDialect();
  if (!needsExplicitPersist(dialect)) {
-    throw new Error(
-      `Importing a backup is only supported on SQLite; this deployment uses ${dialect}. ` +
-        `Restore into the database directly with its own tooling instead.`,
-    );
+    return operation();
  }

  return withSqliteForeignKeysDisabled(getCurrentRepositorySqlite(), operation);
@@ -388,6 +388,165 @@ router.get(
  },
 );

+/**
+ * @openapi
+ * /credentials/{id}/duplicate:
+ *   post:
+ *     summary: Duplicate a credential
+ *     description: Creates a new credential from an existing one, optionally overriding fields (e.g. password), leaving the original credential untouched.
+ *     tags:
+ *       - Credentials
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: integer
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               name:
+ *                 type: string
+ *               username:
+ *                 type: string
+ *               password:
+ *                 type: string
+ *               key:
+ *                 type: string
+ *               keyPassword:
+ *                 type: string
+ *     responses:
+ *       201:
+ *         description: New credential created from the duplicate.
+ *       400:
+ *         description: Invalid request.
+ *       404:
+ *         description: Credential not found.
+ *       500:
+ *         description: Failed to duplicate credential.
+ */
+router.post(
+  "/:id/duplicate",
+  authenticateJWT,
+  requireDataAccess,
+  async (req: Request, res: Response) => {
+    const userId = (req as AuthenticatedRequest).userId;
+    const id = Array.isArray(req.params.id) ? req.params.id[0] : req.params.id;
+    const { name, username, password, key, keyPassword, certPublicKey } =
+      req.body ?? {};
+
+    if (!isNonEmptyString(userId) || !id) {
+      authLogger.warn("Invalid request for credential duplicate");
+      return res.status(400).json({ error: "Invalid request" });
+    }
+    if (!isNonEmptyString(name)) {
+      return res.status(400).json({ error: "Name is required" });
+    }
+
+    const credentialId = parseInt(id);
+
+    try {
+      const credentialRepository = createCurrentCredentialRepository();
+      const source = await credentialRepository.findDecryptedByIdForUser(
+        userId,
+        credentialId,
+      );
+
+      if (!source) {
+        return res.status(404).json({ error: "Credential not found" });
+      }
+
+      const authType = source.authType;
+      const plainPassword =
+        password !== undefined ? password || null : source.password;
+      const plainKey = key !== undefined ? key || null : source.key;
+      const plainKeyPassword =
+        keyPassword !== undefined ? keyPassword || null : source.keyPassword;
+
+      let keyInfo = null;
+      if (authType === "key" && plainKey) {
+        keyInfo = parseSSHKey(plainKey, plainKeyPassword);
+        if (!keyInfo.success) {
+          return res.status(400).json({
+            error: keyInfo.error
+              ? `Invalid SSH key: ${keyInfo.error}`
+              : "Unrecognized SSH key format. Use an OpenSSH, PEM, or PuTTY PPK v2 RSA/DSA private key.",
+          });
+        }
+      }
+
+      const credentialData = {
+        userId,
+        name: name.trim(),
+        description: source.description,
+        folder: source.folder,
+        tags: source.tags,
+        authType,
+        username:
+          username !== undefined ? username?.trim() || null : source.username,
+        password: authType === "password" ? plainPassword : null,
+        key: authType === "key" ? plainKey : null,
+        privateKey: authType === "key" ? keyInfo?.privateKey || plainKey : null,
+        publicKey: authType === "key" ? keyInfo?.publicKey || null : null,
+        keyPassword: authType === "key" ? plainKeyPassword : null,
+        keyType: source.keyType,
+        detectedKeyType: authType === "key" ? keyInfo?.keyType || null : null,
+        certPublicKey:
+          authType === "key"
+            ? certPublicKey !== undefined
+              ? certPublicKey?.trim() || null
+              : source.certPublicKey
+            : null,
+        usageCount: 0,
+        lastUsed: null,
+      };
+
+      const created = await credentialRepository.createEncryptedForUser(
+        userId,
+        credentialData,
+      );
+
+      const { ipAddress: dupIp, userAgent: dupUa } = getRequestMeta(req);
+      await logAudit({
+        userId,
+        username: await getAuditUsername(userId),
+        action: "duplicate_credential",
+        resourceType: "credential",
+        resourceId: String(created.id),
+        resourceName: name,
+        ipAddress: dupIp,
+        userAgent: dupUa,
+        success: true,
+      });
+
+      authLogger.success(
+        `SSH credential duplicated: ${name} (from ${credentialId}) by user ${userId}`,
+        {
+          operation: "credential_duplicate_success",
+          userId,
+          sourceCredentialId: credentialId,
+          credentialId: created.id,
+        },
+      );
+
+      res.status(201).json(formatCredentialOutput(created));
+    } catch (err) {
+      authLogger.error("Failed to duplicate credential", err, {
+        operation: "credential_duplicate",
+        userId,
+        credentialId,
+      });
+      res.status(500).json({
+        error: getErrorMessage(err, "Failed to duplicate credential"),
+      });
+    }
+  },
+);
+
 /**
 * @openapi
 * /credentials/{id}:
@@ -32,7 +32,7 @@ export function resolveProxmoxImportAuth(
    return {
      authType: "credential",
      credentialId,
-      overrideCredentialUsername: 1,
+      overrideCredentialUsername: 0,
    };
  }

@@ -689,6 +689,12 @@ async function syncProxmoxHost(
          ? existing.connectionType
          : null;
      const connectionType = existingConnectionType ?? guest.connectionType;
+      const usesImportCredential =
+        connectionType === "ssh" && importAuth.authType === "credential";
+      const existingUsesImportCredential =
+        usesImportCredential &&
+        existing?.authType === "credential" &&
+        existing?.credentialId === importAuth.credentialId;
      const port =
        typeof existing?.port === "number"
          ? existing.port
@@ -696,11 +702,13 @@ async function syncProxmoxHost(
            ? 3389
            : 22;
      const username =
-        typeof existing?.username === "string" && existing.username
-          ? existing.username
-          : connectionType === "rdp"
-            ? ""
-            : "root";
+        usesImportCredential && (!existing || existingUsesImportCredential)
+          ? ""
+          : typeof existing?.username === "string" && existing.username
+            ? existing.username
+            : connectionType === "rdp"
+              ? ""
+              : "root";
      const update: Record<string, unknown> = {
        name: guest.name,
        ip: guest.ip || existing?.ip || "0.0.0.0",
@@ -714,6 +722,10 @@ async function syncProxmoxHost(
      };

      if (existing) {
+        if (existingUsesImportCredential) {
+          update.credentialId = importAuth.credentialId;
+          update.overrideCredentialUsername = false;
+        }
        await createCurrentHostRepository().updateEncryptedForUser(
          userId,
          existing.id as number,
@@ -7,7 +7,10 @@ import { authLogger } from "../../utils/logger.js";
 import { AuthManager } from "../../utils/auth-manager.js";
 import type { SSOProviderType } from "../../../types/index.js";
 import { createCurrentSsoProviderRepository } from "../repositories/factory.js";
-import { getOIDCConfigFromEnv } from "./user-oidc-utils.js";
+import {
+  getOIDCConfigFromEnv,
+  isOIDCEnvOverrideEnabled,
+} from "./user-oidc-utils.js";
 import {
  decryptSsoConfigSecrets,
  encryptSsoConfigSecrets,
@@ -18,6 +21,19 @@ function isOidcLike(type: SSOProviderType): boolean {
  return type === "oidc" || type === "github" || type === "google";
 }

+export function isValidOidcIssuer(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return (
+      ["http:", "https:"].includes(url.protocol) &&
+      !/\/userinfo\/?$/i.test(url.pathname)
+    );
+  } catch {
+    return false;
+  }
+}
+
 const authManager = AuthManager.getInstance();

 /**
@@ -95,13 +111,19 @@ export function registerSSOProviderRoutes(router: Router): void {
   */
  router.get("/sso-providers", async (_req, res) => {
    try {
+      const envConfig = getOIDCConfigFromEnv();
+      if (envConfig && isOIDCEnvOverrideEnabled()) {
+        return res.json([
+          { id: 0, name: "SSO", type: "oidc", displayOrder: 0 },
+        ]);
+      }
+
      const providers =
        await createCurrentSsoProviderRepository().listEnabledPublic();

      // If no DB providers exist, synthesize one from env vars so SSO login
      // remains available when configured purely via environment variables.
      if (providers.length === 0) {
-        const envConfig = getOIDCConfigFromEnv();
        if (envConfig) {
          providers.push({ id: 0, name: "SSO", type: "oidc", displayOrder: 0 });
        }
@@ -222,6 +244,12 @@ export function registerSSOProviderRoutes(router: Router): void {
            error: `Missing required OIDC fields: ${missing.join(", ")}`,
          });
        }
+        if (c.issuer_url && !isValidOidcIssuer(c.issuer_url)) {
+          return res.status(400).json({
+            error:
+              "Issuer URL must be an HTTP(S) issuer and not a userinfo endpoint",
+          });
+        }
        if (
          (type === "github" || type === "google") &&
          (!c.client_id || !c.client_secret)
@@ -353,6 +381,16 @@ export function registerSSOProviderRoutes(router: Router): void {
          ),
          ...rawConfig,
        };
+        if (
+          isOidcLike(effectiveType) &&
+          mergedConfig.issuer_url &&
+          !isValidOidcIssuer(mergedConfig.issuer_url)
+        ) {
+          return res.status(400).json({
+            error:
+              "Issuer URL must be an HTTP(S) issuer and not a userinfo endpoint",
+          });
+        }
        encryptedConfig = await encryptProviderConfig(
          mergedConfig,
          userId,
@@ -4,7 +4,7 @@ import {
  type Router as ExpressRouter,
 } from "express";
 import { apiLogger } from "../../utils/logger.js";
-import { getFetchDispatcher } from "../../utils/proxy-agent.js";
+import { fetchWithProxy } from "../../utils/proxy-agent.js";
 import { createCurrentSettingsRepository } from "../repositories/factory.js";

 interface TailscaleDevice {
@@ -74,12 +74,11 @@ export function registerTailscaleRoutes(
      );

      const url = `${apiBase}/tailnet/-/devices?fields=all`;
-      const response = await fetch(url, {
+      const response = await fetchWithProxy(url, {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "User-Agent": "Termix/1.0",
        },
-        dispatcher: getFetchDispatcher(url),
      });

      if (!response.ok) {
@@ -105,6 +105,10 @@ export function getOIDCConfigFromEnv(): OIDCConfig | null {
  };
 }

+export function isOIDCEnvOverrideEnabled(): boolean {
+  return process.env.OIDC_ENV_OVERRIDE?.toLowerCase() === "true";
+}
+
 /**
 * Normalizes a group name for comparison. Providers are inconsistent about
 * whether they emit bare names (`devops-interns`) or full paths
@@ -438,6 +442,11 @@ export async function loadProviderConfig(
  providerType: SSOProviderType;
  providerDbId: number | null;
 } | null> {
+  const envConfig = getOIDCConfigFromEnv();
+  if (envConfig && isOIDCEnvOverrideEnabled()) {
+    return { config: envConfig, providerType: "oidc", providerDbId: null };
+  }
+
  if (providerId != null) {
    try {
      const row =
@@ -485,7 +494,6 @@ export async function loadProviderConfig(
  }

  // Fallback: env vars
-  const envConfig = getOIDCConfigFromEnv();
  if (envConfig) {
    return { config: envConfig, providerType: "oidc", providerDbId: null };
  }
@@ -542,6 +550,14 @@ export async function resolveProviderByIssuer(issuer: string): Promise<{
  providerDbId: number | null;
 } | null> {
  const target = normalizeIssuer(issuer);
+  const envConfig = getOIDCConfigFromEnv();
+  if (
+    envConfig?.issuer_url &&
+    isOIDCEnvOverrideEnabled() &&
+    normalizeIssuer(envConfig.issuer_url) === target
+  ) {
+    return { config: envConfig, providerType: "oidc", providerDbId: null };
+  }

  try {
    const rows = await createCurrentSsoProviderRepository().listEnabled();
@@ -569,7 +585,6 @@ export async function resolveProviderByIssuer(issuer: string): Promise<{
    });
  }

-  const envConfig = getOIDCConfigFromEnv();
  if (
    envConfig?.issuer_url &&
    normalizeIssuer(envConfig.issuer_url) === target
@@ -137,6 +137,12 @@ function isPasswordResetAllowed(): boolean {
  }
 }

+function getOidcSilentLoginDefaultFromEnv(): boolean | undefined {
+  const envVal = process.env.OIDC_SILENT_LOGIN_DEFAULT;
+  if (envVal === undefined) return undefined;
+  return envVal.trim().toLowerCase() === "true";
+}
+
 function isNativeAppRequest(req: Request): boolean {
  return (
    (req.get("User-Agent") || "").startsWith("Termix-Mobile/") ||
@@ -2460,7 +2466,7 @@ router.patch("/oidc-auto-provision", authenticateJWT, async (req, res) => {
 * /users/oidc-silent-login-default:
 *   get:
 *     summary: Get OIDC silent login default setting
- *     description: Returns whether silent OIDC login is enabled as the default behavior.
+ *     description: Returns whether silent OIDC login is enabled as the default behavior. Can be pinned via the OIDC_SILENT_LOGIN_DEFAULT env var.
 *     tags:
 *       - Users
 *     responses:
@@ -2471,11 +2477,17 @@ router.patch("/oidc-auto-provision", authenticateJWT, async (req, res) => {
 */
 router.get("/oidc-silent-login-default", async (_req, res) => {
  try {
+    const envVal = getOidcSilentLoginDefaultFromEnv();
+    if (envVal !== undefined) {
+      res.json({ enabled: envVal, locked: true });
+      return;
+    }
    res.json({
      enabled: await createCurrentSettingsRepository().getBoolean(
        "oidc_silent_login_default",
        false,
      ),
+      locked: false,
    });
  } catch (err) {
    authLogger.error("Failed to get OIDC silent login default", err);
@@ -2507,6 +2519,8 @@ router.get("/oidc-silent-login-default", async (_req, res) => {
 *         description: Invalid value.
 *       403:
 *         description: Not authorized.
+ *       409:
+ *         description: Setting is pinned by the OIDC_SILENT_LOGIN_DEFAULT env var.
 *       500:
 *         description: Failed to update setting.
 */
@@ -2520,6 +2534,12 @@ router.patch(
      if (!user) {
        return res.status(403).json({ error: "Not authorized" });
      }
+      if (getOidcSilentLoginDefaultFromEnv() !== undefined) {
+        return res.status(409).json({
+          error:
+            "OIDC silent login default is set via the OIDC_SILENT_LOGIN_DEFAULT env var and cannot be changed here",
+        });
+      }
      const { enabled } = req.body;
      if (typeof enabled !== "boolean") {
        return res.status(400).json({ error: "Invalid value for enabled" });
@@ -9,7 +9,7 @@ import { createCorsMiddleware } from "../../utils/cors-config.js";
 import { createCompressionMiddleware } from "../../utils/compression-config.js";
 import cookieParser from "cookie-parser";
 import axios from "axios";
-import { Client as SSHClient } from "ssh2";
+import ssh2Pkg, { Client as SSHClient } from "ssh2";
 import { SSH_ALGORITHMS } from "../../utils/ssh-algorithms.js";
 import { createCurrentHostResolutionRepository } from "../../database/repositories/factory.js";
 import { fileLogger } from "../../utils/logger.js";
@@ -42,8 +42,11 @@ import {
 } from "./transfer-engine.js";
 import { registerFileContentRoutes } from "./content-routes.js";
 import { createConnectionLog } from "../connection-log.js";
-import { createJumpHostChain } from "../jump-host-chain.js";
-import { preparePrivateKeyForSSH2 } from "../../utils/ssh-key-utils.js";
+import { createJumpHostChain, JumpHostChainError } from "../jump-host-chain.js";
+import {
+  isPrivateKeyPassphraseError,
+  preparePrivateKeyForSSH2,
+} from "../../utils/ssh-key-utils.js";
 import {
  ChannelOpenSerializer,
  execChannel,
@@ -840,7 +843,7 @@ app.post("/ssh/file_manager/ssh/connect", async (req, res) => {
        resolvedCredentials = {
          password: resolvedHost.password,
          sshKey: resolvedHost.key,
-          keyPassword: resolvedHost.keyPassword,
+          keyPassword: keyPassword || resolvedHost.keyPassword,
          authType: resolvedHost.authType,
          sudoPassword: resolvedHost.sudoPassword as string | undefined,
          certPublicKey: (resolvedHost as { certPublicKey?: string })
@@ -909,7 +912,7 @@ app.post("/ssh/file_manager/ssh/connect", async (req, res) => {
        resolvedCredentials = {
          password: resolvedHost.password,
          sshKey: resolvedHost.key,
-          keyPassword: resolvedHost.keyPassword,
+          keyPassword: keyPassword || resolvedHost.keyPassword,
          authType: resolvedHost.authType,
          sudoPassword: resolvedHost.sudoPassword as string | undefined,
          certPublicKey: (resolvedHost as { certPublicKey?: string })
@@ -1049,6 +1052,12 @@ app.post("/ssh/file_manager/ssh/connect", async (req, res) => {
        resolvedCredentials.keyPassword,
      );

+      const parsedKey = ssh2Pkg.utils.parseKey(
+        config.privateKey as Buffer,
+        resolvedCredentials.keyPassword,
+      );
+      if (parsedKey instanceof Error) throw parsedKey;
+
      if (resolvedCredentials.keyPassword)
        config.passphrase = resolvedCredentials.keyPassword;

@@ -1071,6 +1080,10 @@ app.post("/ssh/file_manager/ssh/connect", async (req, res) => {
        ),
      );
    } catch (keyError) {
+      if (isPrivateKeyPassphraseError(keyError)) {
+        return res.json({ status: "passphrase_required", connectionLogs });
+      }
+
      fileLogger.error("SSH key format error for file manager", {
        operation: "file_connect",
        sessionId,
@@ -1832,7 +1845,10 @@ app.post("/ssh/file_manager/ssh/connect", async (req, res) => {
        ),
      );
      return res.status(500).json({
-        error: "Failed to connect through jump hosts",
+        error:
+          error instanceof JumpHostChainError
+            ? `Failed to connect through jump hosts: ${error.message}`
+            : "Failed to connect through jump hosts",
        connectionLogs,
      });
    }
@@ -0,0 +1,120 @@
+type SFTPWrapper = import("ssh2").SFTPWrapper;
+
+export const SFTP_OPEN_READ = 0x00000001;
+export const SFTP_OPEN_WRITE = 0x00000002 | 0x00000008 | 0x00000010;
+export const SFTP_OPEN_WRITE_RESUME = 0x00000001 | 0x00000002 | 0x00000008;
+
+export function promisifySftpStat(
+  sftp: SFTPWrapper,
+  path: string,
+): Promise<import("ssh2").Stats> {
+  return new Promise((resolve, reject) => {
+    sftp.stat(path, (err, stats) => {
+      if (err) reject(err);
+      else resolve(stats);
+    });
+  });
+}
+
+export function promisifySftpUnlink(
+  sftp: SFTPWrapper,
+  path: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.unlink(path, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+export function promisifySftpRmdir(
+  sftp: SFTPWrapper,
+  path: string,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.rmdir(path, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+export function promisifySftpMkdir(
+  sftp: SFTPWrapper,
+  path: string,
+  mode: number,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.mkdir(path, { mode }, (err) => {
+      if (err && (err as NodeJS.ErrnoException).code !== "EEXIST") {
+        reject(err);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+export function promisifySftpChmod(
+  sftp: SFTPWrapper,
+  path: string,
+  mode: number,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.chmod(path, mode, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+export function promisifySftpReaddir(
+  sftp: SFTPWrapper,
+  path: string,
+): Promise<Array<{ filename: string; attrs: import("ssh2").Stats }>> {
+  return new Promise((resolve, reject) => {
+    sftp.readdir(path, (err, list) => {
+      if (err) reject(err);
+      else resolve(list);
+    });
+  });
+}
+
+export function promisifySftpOpen(
+  sftp: SFTPWrapper,
+  path: string,
+  flags: number,
+  mode: number,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    sftp.open(path, flags, mode, (err, handle) => {
+      if (err) reject(err);
+      else resolve(handle);
+    });
+  });
+}
+
+export function promisifySftpClose(
+  sftp: SFTPWrapper,
+  handle: Buffer,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    sftp.close(handle, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}
+
+export function promisifySftpFstat(
+  sftp: SFTPWrapper,
+  handle: Buffer,
+): Promise<import("ssh2").Stats> {
+  return new Promise((resolve, reject) => {
+    sftp.fstat(handle, (err, stats) => {
+      if (err) reject(err);
+      else resolve(stats);
+    });
+  });
+}
@@ -1,12 +1,10 @@
 import { getErrorMessage } from "../../utils/error-message.js";
 import { randomUUID } from "crypto";
-import { networkInterfaces } from "os";
 import { performance } from "node:perf_hooks";
 import type { ClientChannel } from "ssh2";
 import { fileLogger } from "../../utils/logger.js";
 import {
  basename,
-  buildPathFromSegments,
  dirname,
  getWorkingDir,
  inferPlatformFromPath,
@@ -14,7 +12,6 @@ import {
  normalizeSftpPath,
  pathsOverlap,
  sftpPathToLocalPath,
-  splitPathSegments,
  type TransferPlatform,
 } from "../transfer-paths.js";
 import {
@@ -26,6 +23,60 @@ import {
  type TransferScanSummary,
 } from "./transfer-routing.js";
 import { verifySftpFileIntegrity } from "./transfer-integrity.js";
+import {
+  promisifySftpChmod,
+  promisifySftpClose,
+  promisifySftpFstat,
+  promisifySftpOpen,
+  promisifySftpStat,
+  promisifySftpUnlink,
+} from "./sftp-promisify.js";
+import {
+  buildTransferHopTimings,
+  computeTransferMbPerSec,
+  createEmptyXferStats,
+  createHopWallClock,
+  createThrottledProgress,
+  elapsedMs,
+  hopSpanMs,
+  mergeXferStats,
+  noteHopEnd,
+  noteHopStart,
+  type PipelinedXferStats,
+  type TransferTimings,
+} from "./transfer-stats.js";
+import {
+  TransferCancelledError,
+  TransferStalledError,
+  isRecoverableTransferError,
+} from "./transfer-errors.js";
+import {
+  escapeShell,
+  isLocalSshEndpoint,
+  isPermissionError,
+  isRootOnlyPath,
+} from "./transfer-host-utils.js";
+import {
+  SFTP_OPEN_READ,
+  SFTP_OPEN_WRITE,
+  SFTP_OPEN_WRITE_RESUME,
+} from "./sftp-promisify.js";
+import {
+  collectFileWorkItems,
+  readSftpSample,
+  type FileWorkItem,
+} from "./transfer-scan.js";
+import {
+  deletePathSftp,
+  ensureDirectoryTreeSftp,
+} from "./transfer-sftp-dir.js";
+import {
+  DEFAULT_PARALLEL_SEGMENT_COUNT,
+  SFTP_XFER_SEGMENT_SIZE,
+  buildSegmentCopyJobs,
+  clampParallelSegmentCount,
+  type SegmentCopyJob,
+} from "./transfer-segment-copy.js";
 import {
  buildDirectProbeCommand,
  buildDirectRsyncCommand,
@@ -107,31 +158,11 @@ export type TransferStatus =
  "running" | "success" | "partial" | "error" | "cancelled";
 export type TransferMethod = "stream" | "tar" | "item_sftp" | "direct_rsync";

-export type TransferHopId =
-  "source_read" | "dest_sftp_write" | "dest_local_write";
-
-export interface TransferHopMetrics {
-  id: TransferHopId;
-  bytes: number;
-  /** Wall-clock span from first I/O on this hop to last I/O complete. */
-  spanMs: number;
-  mbPerSec: number;
-}
-
-export interface TransferTimings {
-  prepareDestMs?: number;
-  compressMs?: number;
-  transferMs?: number;
-  extractMs?: number;
-  verifyMs?: number;
-  directBenchmarkMs?: number;
-  relayBenchmarkMs?: number;
-  sourceDeleteMs?: number;
-  totalMs?: number;
-  transferBytes?: number;
-  endToEndMbPerSec?: number;
-  hops?: TransferHopMetrics[];
-}
+export type {
+  TransferHopId,
+  TransferHopMetrics,
+  TransferTimings,
+} from "./transfer-stats.js";

 export interface TransferProgress {
  transferId: string;
@@ -204,34 +235,6 @@ interface ActiveXferControl {
 const activeXferControls = new Map<string, ActiveXferControl>();
 const cancelWatchdogs = new Map<string, ReturnType<typeof setTimeout>>();

-class TransferCancelledError extends Error {
-  constructor() {
-    super("Transfer cancelled");
-    this.name = "TransferCancelledError";
-  }
-}
-
-class TransferStalledError extends Error {
-  readonly byteOffset?: number;
-  readonly segmentIndex?: number;
-
-  constructor(byteOffset?: number, segmentIndex?: number) {
-    const pos = byteOffset !== undefined ? ` at byte offset ${byteOffset}` : "";
-    const seg = segmentIndex !== undefined ? ` (segment ${segmentIndex})` : "";
-    super(`Transfer stalled — no data moved for 45 seconds${pos}${seg}`);
-    this.name = "TransferStalledError";
-    this.byteOffset = byteOffset;
-    this.segmentIndex = segmentIndex;
-  }
-}
-
-class TransferConnectionLostError extends Error {
-  constructor(message = "Transfer SSH connection lost") {
-    super(message);
-    this.name = "TransferConnectionLostError";
-  }
-}
-
 function throwIfCancelled(transferId: string): void {
  if (cancelRequestedTransfers.has(transferId)) {
    throw new TransferCancelledError();
@@ -315,8 +318,6 @@ const SMALL_FILE_SYNC_THRESHOLD = 10 * 1024 * 1024;
 const SFTP_XFER_CHUNK_SIZE = 256 * 1024;
 /** Pipelined in-flight READ requests per leg (ssh2 fastGet/fastPut default is 64). */
 const SFTP_XFER_CONCURRENCY = 32;
-/** Reset pipelined scheduler every segment to avoid long-run deadlocks at GiB boundaries. */
-const SFTP_XFER_SEGMENT_SIZE = 256 * 1024 * 1024;
 /** Files above this size use segmented copy; smaller files use a single scheduler run. */
 const SFTP_XFER_SEGMENT_THRESHOLD = 32 * 1024 * 1024;
 /** Per-segment attempts before giving up (sequential and parallel). */
@@ -328,17 +329,9 @@ const SFTP_SEQUENTIAL_COPY_MAX_ATTEMPTS = 2;
 const SFTP_PARALLEL_COPY_MAX_ATTEMPTS = 2;
 /** Short backoff before opening fresh dedicated SSH sessions. */
 const TRANSFER_SESSION_RESET_DELAYS_MS = [1000, 2000, 3000];
-const DEFAULT_PARALLEL_SEGMENT_COUNT = 2;
-const MAX_PARALLEL_SEGMENT_COUNT = 8;
 const TRANSFER_HANDLE_CLOSE_TIMEOUT_MS = 2500;
 const HUNG_TRANSFER_MS = 90_000;
 const HUNG_RECONNECTING_MS = 180_000;
-const TRANSFER_PROGRESS_INTERVAL_MS = 200;
-const SFTP_OPEN_READ = 0x00000001;
-/** WRITE | CREATE | TRUNCATE — new file or overwrite from start. */
-const SFTP_OPEN_WRITE = 0x00000002 | 0x00000008 | 0x00000010;
-/** READ | WRITE | CREATE — resume into an existing partial file without truncating. */
-const SFTP_OPEN_WRITE_RESUME = 0x00000001 | 0x00000002 | 0x00000008;

 interface TransferReconnectContext {
  deps: HostTransferDeps;
@@ -364,31 +357,6 @@ function buildTransferReconnectContext(
  return { deps, transferId, ...meta };
 }

-function isRecoverableTransferConnectionError(err: unknown): boolean {
-  if (!(err instanceof Error)) return false;
-  const msg = err.message.toLowerCase();
-  return (
-    msg.includes("no response from server") ||
-    msg.includes("connection lost") ||
-    msg.includes("not connected") ||
-    msg.includes("econnreset") ||
-    msg.includes("econnrefused") ||
-    msg.includes("etimedout") ||
-    msg.includes("socket hang up") ||
-    msg.includes("protocol error") ||
-    msg.includes("connection closed") ||
-    msg.includes("channel open failure")
-  );
-}
-
-function isRecoverableTransferError(err: unknown): boolean {
-  return (
-    err instanceof TransferStalledError ||
-    err instanceof TransferConnectionLostError ||
-    isRecoverableTransferConnectionError(err)
-  );
-}
-
 async function probeDestResumeOffset(
  destSftp: SFTPWrapper,
  destPath: string,
@@ -560,69 +528,6 @@ async function resetDedicatedTransferSessions(
  return { sourceSession, destSession, sourceSftp, destSftp };
 }

-let cachedLocalAddresses: Set<string> | null = null;
-
-function normalizeHostAddress(host: string): string {
-  const trimmed = host.trim().toLowerCase();
-  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed.split(":")[0] ?? trimmed;
-}
-
-function getLocalAddresses(): Set<string> {
-  if (cachedLocalAddresses) return cachedLocalAddresses;
-
-  const addresses = new Set(["127.0.0.1", "::1", "localhost"]);
-  for (const ifaces of Object.values(networkInterfaces())) {
-    if (!ifaces) continue;
-    for (const iface of ifaces) {
-      if (!iface.internal && iface.family === "IPv4") {
-        addresses.add(iface.address.toLowerCase());
-      }
-    }
-  }
-  cachedLocalAddresses = addresses;
-  return addresses;
-}
-
-export function isLocalSshEndpoint(ip?: string): boolean {
-  if (!ip) return false;
-  const bare = normalizeHostAddress(ip);
-  if (bare === "localhost" || bare === "127.0.0.1" || bare === "::1") {
-    return true;
-  }
-  return getLocalAddresses().has(bare);
-}
-
-function createThrottledProgress(onProgress?: (bytes: number) => void) {
-  let pending = 0;
-  let lastFlush = 0;
-
-  const flush = () => {
-    if (pending > 0) {
-      onProgress?.(pending);
-      pending = 0;
-      lastFlush = Date.now();
-    }
-  };
-
-  return {
-    add(bytes: number) {
-      pending += bytes;
-      const now = Date.now();
-      if (now - lastFlush >= TRANSFER_PROGRESS_INTERVAL_MS) {
-        flush();
-      }
-    },
-    flush,
-  };
-}
-
-function escapeShell(s: string): string {
-  return s.replace(/'/g, "'\"'\"'");
-}
-
 async function detectTransferPlatform(
  deps: HostTransferDeps,
  session: SSHSessionLike,
@@ -680,150 +585,6 @@ async function detectTransferPlatform(
  return "unix";
 }

-function isRootOnlyPath(path: string): boolean {
-  const normalized = normalizeSftpPath(path);
-  return (
-    normalized === "/" ||
-    /^\/[A-Za-z]:$/.test(normalized) ||
-    /^[A-Za-z]:$/.test(normalized)
-  );
-}
-
-function isPermissionError(err: Error): boolean {
-  const msg = err.message.toLowerCase();
-  return (
-    msg.includes("permission denied") ||
-    msg.includes("eacces") ||
-    msg.includes("access denied")
-  );
-}
-
-function promisifySftpStat(
-  sftp: SFTPWrapper,
-  path: string,
-): Promise<import("ssh2").Stats> {
-  return new Promise((resolve, reject) => {
-    sftp.stat(path, (err, stats) => {
-      if (err) reject(err);
-      else resolve(stats);
-    });
-  });
-}
-
-function promisifySftpUnlink(sftp: SFTPWrapper, path: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    sftp.unlink(path, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
-function promisifySftpRmdir(sftp: SFTPWrapper, path: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    sftp.rmdir(path, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
-async function ensureDirectoryTreeSftp(
-  sftp: SFTPWrapper,
-  dirPath: string,
-  created: Set<string> = new Set(),
-): Promise<void> {
-  const normalized = normalizeSftpPath(dirPath);
-  if (!normalized || isRootOnlyPath(normalized)) return;
-
-  const { root, segments } = splitPathSegments(normalized);
-  if (segments.length === 0) return;
-
-  for (let i = 0; i < segments.length; i++) {
-    const current = buildPathFromSegments(root, segments, i + 1);
-    if (created.has(current)) continue;
-
-    try {
-      await promisifySftpMkdir(sftp, current, 0o755);
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== "EEXIST") {
-        try {
-          const stats = await promisifySftpStat(sftp, current);
-          if (!stats.isDirectory()) throw err;
-        } catch {
-          throw err;
-        }
-      }
-    }
-    created.add(current);
-  }
-}
-
-async function deletePathSftp(sftp: SFTPWrapper, path: string): Promise<void> {
-  let stats: import("ssh2").Stats;
-  try {
-    stats = await promisifySftpStat(sftp, path);
-  } catch {
-    return;
-  }
-
-  if (stats.isDirectory()) {
-    const entries = await promisifySftpReaddir(sftp, path);
-    for (const entry of entries) {
-      if (entry.filename === "." || entry.filename === "..") continue;
-      await deletePathSftp(sftp, joinPath(path, entry.filename));
-    }
-    await promisifySftpRmdir(sftp, path);
-    return;
-  }
-
-  if (stats.isFile()) {
-    await promisifySftpUnlink(sftp, path);
-  }
-}
-
-function promisifySftpMkdir(
-  sftp: SFTPWrapper,
-  path: string,
-  mode: number,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    sftp.mkdir(path, { mode }, (err) => {
-      if (err && (err as NodeJS.ErrnoException).code !== "EEXIST") {
-        reject(err);
-      } else {
-        resolve();
-      }
-    });
-  });
-}
-
-function promisifySftpChmod(
-  sftp: SFTPWrapper,
-  path: string,
-  mode: number,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    sftp.chmod(path, mode, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
-function promisifySftpReaddir(
-  sftp: SFTPWrapper,
-  path: string,
-): Promise<Array<{ filename: string; attrs: import("ssh2").Stats }>> {
-  return new Promise((resolve, reject) => {
-    sftp.readdir(path, (err, list) => {
-      if (err) reject(err);
-      else resolve(list);
-    });
-  });
-}
-
 function execCommand(
  deps: HostTransferDeps,
  session: SSHSessionLike,
@@ -1157,10 +918,6 @@ function finalizeTransfer(
  return result;
 }

-function elapsedMs(start: number): number {
-  return Date.now() - start;
-}
-
 async function verifyTransferredFile(
  deps: HostTransferDeps,
  transferId: string,
@@ -1208,103 +965,6 @@ async function verifyTransferredFile(
  });
 }

-export function computeTransferMbPerSec(
-  bytes: number,
-  ms: number,
-): number | undefined {
-  if (ms <= 0 || bytes <= 0) return undefined;
-  return ((bytes / ms) * 1000) / (1024 * 1024);
-}
-
-interface HopWallClock {
-  firstAt: number | null;
-  lastAt: number | null;
-}
-
-function createHopWallClock(): HopWallClock {
-  return { firstAt: null, lastAt: null };
-}
-
-function noteHopStart(
-  clock: HopWallClock,
-  t: number = performance.now(),
-): void {
-  if (clock.firstAt === null) clock.firstAt = t;
-}
-
-function noteHopEnd(clock: HopWallClock, t: number = performance.now()): void {
-  clock.lastAt = t;
-}
-
-function hopSpanMs(clock: HopWallClock): number {
-  if (clock.firstAt === null || clock.lastAt === null) return 0;
-  return Math.max(0, clock.lastAt - clock.firstAt);
-}
-
-interface PipelinedXferStats {
-  bytes: number;
-  sourceReadSpanMs: number;
-  destWriteSpanMs: number;
-  destWriteKind: "sftp" | "local";
-}
-
-function createEmptyXferStats(): PipelinedXferStats {
-  return {
-    bytes: 0,
-    sourceReadSpanMs: 0,
-    destWriteSpanMs: 0,
-    destWriteKind: "sftp",
-  };
-}
-
-function mergeXferStats(
-  target: PipelinedXferStats,
-  source: PipelinedXferStats,
-): void {
-  target.bytes += source.bytes;
-  target.sourceReadSpanMs += source.sourceReadSpanMs;
-  target.destWriteSpanMs += source.destWriteSpanMs;
-  target.destWriteKind = source.destWriteKind;
-}
-
-function buildTransferHopTimings(
-  stats: PipelinedXferStats,
-  transferMs: number,
-): Pick<TransferTimings, "transferBytes" | "endToEndMbPerSec" | "hops"> {
-  const hops: TransferHopMetrics[] = [];
-
-  const sourceRate = computeTransferMbPerSec(
-    stats.bytes,
-    stats.sourceReadSpanMs,
-  );
-  if (sourceRate !== undefined) {
-    hops.push({
-      id: "source_read",
-      bytes: stats.bytes,
-      spanMs: stats.sourceReadSpanMs,
-      mbPerSec: sourceRate,
-    });
-  }
-
-  const destHopId: TransferHopId =
-    stats.destWriteKind === "local" ? "dest_local_write" : "dest_sftp_write";
-  const destRate = computeTransferMbPerSec(stats.bytes, stats.destWriteSpanMs);
-  if (destRate !== undefined) {
-    hops.push({
-      id: destHopId,
-      bytes: stats.bytes,
-      spanMs: stats.destWriteSpanMs,
-      mbPerSec: destRate,
-    });
-  }
-
-  return {
-    transferBytes: stats.bytes,
-    endToEndMbPerSec: computeTransferMbPerSec(stats.bytes, transferMs),
-    hops,
-  };
-}
-
 async function deleteSourcePathsAfterSuccess(
  deps: HostTransferDeps,
  transferId: string,
@@ -1334,63 +994,6 @@ async function ensureDestParentForFile(
  await ensureDestDirectory(deps, destSession, parent);
 }

-interface FileWorkItem {
-  sourcePath: string;
-  destPath: string;
-  mode: number;
-  size: number;
-}
-
-async function collectFileWorkItems(
-  sftp: SFTPWrapper,
-  sourcePath: string,
-  destRoot: string,
-  destBaseName?: string,
-): Promise<FileWorkItem[]> {
-  const stats = await promisifySftpStat(sftp, sourcePath);
-  const name = destBaseName ?? basename(sourcePath);
-  const destPath = joinPath(destRoot, name);
-
-  if (stats.isFile()) {
-    return [
-      {
-        sourcePath,
-        destPath,
-        mode: stats.mode & 0o7777,
-        size: stats.size,
-      },
-    ];
-  }
-
-  if (!stats.isDirectory()) {
-    return [];
-  }
-
-  const items: FileWorkItem[] = [];
-  const walk = async (srcDir: string, dstDir: string) => {
-    const entries = await promisifySftpReaddir(sftp, srcDir);
-    for (const entry of entries) {
-      if (entry.filename === "." || entry.filename === "..") continue;
-      const srcChild = joinPath(srcDir, entry.filename);
-      const dstChild = joinPath(dstDir, entry.filename);
-
-      if (entry.attrs.isDirectory()) {
-        await walk(srcChild, dstChild);
-      } else if (entry.attrs.isFile()) {
-        items.push({
-          sourcePath: srcChild,
-          destPath: dstChild,
-          mode: entry.attrs.mode & 0o7777,
-          size: entry.attrs.size,
-        });
-      }
-    }
-  };
-
-  await walk(sourcePath, destPath);
-  return items;
-}
-
 async function scanSourcePathsForRouting(
  sftp: SFTPWrapper,
  sourcePaths: string[],
@@ -1430,63 +1033,6 @@ async function scanSourcePathsForRouting(
  return summary;
 }

-async function readSftpSample(
-  sftp: SFTPWrapper,
-  path: string,
-  fileSize: number,
-): Promise<Buffer> {
-  const sampleSize = Math.min(64 * 1024, fileSize);
-  const position = Math.max(0, Math.floor((fileSize - sampleSize) / 2));
-  const handle = await promisifySftpOpen(sftp, path, SFTP_OPEN_READ, 0o666);
-  try {
-    const buffer = Buffer.alloc(sampleSize);
-    const bytesRead = await new Promise<number>((resolve, reject) => {
-      sftp.read(handle, buffer, 0, sampleSize, position, (err, count) => {
-        if (err) reject(err);
-        else resolve(count);
-      });
-    });
-    return buffer.subarray(0, bytesRead);
-  } finally {
-    await promisifySftpClose(sftp, handle).catch(() => {});
-  }
-}
-
-function promisifySftpOpen(
-  sftp: SFTPWrapper,
-  path: string,
-  flags: number,
-  mode: number,
-): Promise<Buffer> {
-  return new Promise((resolve, reject) => {
-    sftp.open(path, flags, mode, (err, handle) => {
-      if (err) reject(err);
-      else resolve(handle);
-    });
-  });
-}
-
-function promisifySftpClose(sftp: SFTPWrapper, handle: Buffer): Promise<void> {
-  return new Promise((resolve, reject) => {
-    sftp.close(handle, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
-function promisifySftpFstat(
-  sftp: SFTPWrapper,
-  handle: Buffer,
-): Promise<import("ssh2").Stats> {
-  return new Promise((resolve, reject) => {
-    sftp.fstat(handle, (err, stats) => {
-      if (err) reject(err);
-      else resolve(stats);
-    });
-  });
-}
-
 interface PipelinedXferOptions {
  fileSize?: number;
  initialOffset?: number;
@@ -1500,43 +1046,6 @@ interface PipelinedXferOptions {
  onResumeOffset?: (offset: number) => void;
 }

-interface SegmentCopyJob {
-  offset: number;
-  length: number;
-  segmentIndex: number;
-}
-
-function clampParallelSegmentCount(value?: number): number {
-  const n = value ?? DEFAULT_PARALLEL_SEGMENT_COUNT;
-  return Math.max(1, Math.min(MAX_PARALLEL_SEGMENT_COUNT, Math.floor(n)));
-}
-
-function buildSegmentCopyJobs(
-  fileSize: number,
-  initialOffset: number,
-  destResumeSize: number,
-): SegmentCopyJob[] {
-  const jobs: SegmentCopyJob[] = [];
-  for (
-    let offset = initialOffset;
-    offset < fileSize;
-    offset += SFTP_XFER_SEGMENT_SIZE
-  ) {
-    const length = Math.min(SFTP_XFER_SEGMENT_SIZE, fileSize - offset);
-    const segmentIndex = Math.floor(offset / SFTP_XFER_SEGMENT_SIZE);
-    if (destResumeSize >= offset + length) {
-      continue;
-    }
-    const start = destResumeSize > offset ? destResumeSize : offset;
-    jobs.push({
-      offset: start,
-      length: offset + length - start,
-      segmentIndex,
-    });
-  }
-  return jobs;
-}
-
 function closeAllTransferSessions(
  deps: HostTransferDeps,
  ctx: TransferReconnectContext,
@@ -0,0 +1,52 @@
+export class TransferCancelledError extends Error {
+  constructor() {
+    super("Transfer cancelled");
+    this.name = "TransferCancelledError";
+  }
+}
+
+export class TransferStalledError extends Error {
+  readonly byteOffset?: number;
+  readonly segmentIndex?: number;
+
+  constructor(byteOffset?: number, segmentIndex?: number) {
+    const pos = byteOffset !== undefined ? ` at byte offset ${byteOffset}` : "";
+    const seg = segmentIndex !== undefined ? ` (segment ${segmentIndex})` : "";
+    super(`Transfer stalled — no data moved for 45 seconds${pos}${seg}`);
+    this.name = "TransferStalledError";
+    this.byteOffset = byteOffset;
+    this.segmentIndex = segmentIndex;
+  }
+}
+
+export class TransferConnectionLostError extends Error {
+  constructor(message = "Transfer SSH connection lost") {
+    super(message);
+    this.name = "TransferConnectionLostError";
+  }
+}
+
+export function isRecoverableTransferConnectionError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes("no response from server") ||
+    msg.includes("connection lost") ||
+    msg.includes("not connected") ||
+    msg.includes("econnreset") ||
+    msg.includes("econnrefused") ||
+    msg.includes("etimedout") ||
+    msg.includes("socket hang up") ||
+    msg.includes("protocol error") ||
+    msg.includes("connection closed") ||
+    msg.includes("channel open failure")
+  );
+}
+
+export function isRecoverableTransferError(err: unknown): boolean {
+  return (
+    err instanceof TransferStalledError ||
+    err instanceof TransferConnectionLostError ||
+    isRecoverableTransferConnectionError(err)
+  );
+}
@@ -0,0 +1,59 @@
+import { networkInterfaces } from "os";
+import { normalizeSftpPath } from "../transfer-paths.js";
+
+let cachedLocalAddresses: Set<string> | null = null;
+
+export function normalizeHostAddress(host: string): string {
+  const trimmed = host.trim().toLowerCase();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed.split(":")[0] ?? trimmed;
+}
+
+function getLocalAddresses(): Set<string> {
+  if (cachedLocalAddresses) return cachedLocalAddresses;
+
+  const addresses = new Set(["127.0.0.1", "::1", "localhost"]);
+  for (const ifaces of Object.values(networkInterfaces())) {
+    if (!ifaces) continue;
+    for (const iface of ifaces) {
+      if (!iface.internal && iface.family === "IPv4") {
+        addresses.add(iface.address.toLowerCase());
+      }
+    }
+  }
+  cachedLocalAddresses = addresses;
+  return addresses;
+}
+
+export function isLocalSshEndpoint(ip?: string): boolean {
+  if (!ip) return false;
+  const bare = normalizeHostAddress(ip);
+  if (bare === "localhost" || bare === "127.0.0.1" || bare === "::1") {
+    return true;
+  }
+  return getLocalAddresses().has(bare);
+}
+
+export function escapeShell(s: string): string {
+  return s.replace(/'/g, "'\"'\"'");
+}
+
+export function isRootOnlyPath(path: string): boolean {
+  const normalized = normalizeSftpPath(path);
+  return (
+    normalized === "/" ||
+    /^\/[A-Za-z]:$/.test(normalized) ||
+    /^[A-Za-z]:$/.test(normalized)
+  );
+}
+
+export function isPermissionError(err: Error): boolean {
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes("permission denied") ||
+    msg.includes("eacces") ||
+    msg.includes("access denied")
+  );
+}
@@ -0,0 +1,89 @@
+import { basename, joinPath } from "../transfer-paths.js";
+import {
+  SFTP_OPEN_READ,
+  promisifySftpClose,
+  promisifySftpOpen,
+  promisifySftpReaddir,
+  promisifySftpStat,
+} from "./sftp-promisify.js";
+
+type SFTPWrapper = import("ssh2").SFTPWrapper;
+
+export interface FileWorkItem {
+  sourcePath: string;
+  destPath: string;
+  mode: number;
+  size: number;
+}
+
+export async function collectFileWorkItems(
+  sftp: SFTPWrapper,
+  sourcePath: string,
+  destRoot: string,
+  destBaseName?: string,
+): Promise<FileWorkItem[]> {
+  const stats = await promisifySftpStat(sftp, sourcePath);
+  const name = destBaseName ?? basename(sourcePath);
+  const destPath = joinPath(destRoot, name);
+
+  if (stats.isFile()) {
+    return [
+      {
+        sourcePath,
+        destPath,
+        mode: stats.mode & 0o7777,
+        size: stats.size,
+      },
+    ];
+  }
+
+  if (!stats.isDirectory()) {
+    return [];
+  }
+
+  const items: FileWorkItem[] = [];
+  const walk = async (srcDir: string, dstDir: string) => {
+    const entries = await promisifySftpReaddir(sftp, srcDir);
+    for (const entry of entries) {
+      if (entry.filename === "." || entry.filename === "..") continue;
+      const srcChild = joinPath(srcDir, entry.filename);
+      const dstChild = joinPath(dstDir, entry.filename);
+
+      if (entry.attrs.isDirectory()) {
+        await walk(srcChild, dstChild);
+      } else if (entry.attrs.isFile()) {
+        items.push({
+          sourcePath: srcChild,
+          destPath: dstChild,
+          mode: entry.attrs.mode & 0o7777,
+          size: entry.attrs.size,
+        });
+      }
+    }
+  };
+
+  await walk(sourcePath, destPath);
+  return items;
+}
+
+export async function readSftpSample(
+  sftp: SFTPWrapper,
+  path: string,
+  fileSize: number,
+): Promise<Buffer> {
+  const sampleSize = Math.min(64 * 1024, fileSize);
+  const position = Math.max(0, Math.floor((fileSize - sampleSize) / 2));
+  const handle = await promisifySftpOpen(sftp, path, SFTP_OPEN_READ, 0o666);
+  try {
+    const buffer = Buffer.alloc(sampleSize);
+    const bytesRead = await new Promise<number>((resolve, reject) => {
+      sftp.read(handle, buffer, 0, sampleSize, position, (err, count) => {
+        if (err) reject(err);
+        else resolve(count);
+      });
+    });
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    await promisifySftpClose(sftp, handle).catch(() => {});
+  }
+}
@@ -0,0 +1,40 @@
+export const SFTP_XFER_SEGMENT_SIZE = 256 * 1024 * 1024;
+export const DEFAULT_PARALLEL_SEGMENT_COUNT = 2;
+export const MAX_PARALLEL_SEGMENT_COUNT = 8;
+
+export interface SegmentCopyJob {
+  offset: number;
+  length: number;
+  segmentIndex: number;
+}
+
+export function clampParallelSegmentCount(value?: number): number {
+  const n = value ?? DEFAULT_PARALLEL_SEGMENT_COUNT;
+  return Math.max(1, Math.min(MAX_PARALLEL_SEGMENT_COUNT, Math.floor(n)));
+}
+
+export function buildSegmentCopyJobs(
+  fileSize: number,
+  initialOffset: number,
+  destResumeSize: number,
+): SegmentCopyJob[] {
+  const jobs: SegmentCopyJob[] = [];
+  for (
+    let offset = initialOffset;
+    offset < fileSize;
+    offset += SFTP_XFER_SEGMENT_SIZE
+  ) {
+    const length = Math.min(SFTP_XFER_SEGMENT_SIZE, fileSize - offset);
+    const segmentIndex = Math.floor(offset / SFTP_XFER_SEGMENT_SIZE);
+    if (destResumeSize >= offset + length) {
+      continue;
+    }
+    const start = destResumeSize > offset ? destResumeSize : offset;
+    jobs.push({
+      offset: start,
+      length: offset + length - start,
+      segmentIndex,
+    });
+  }
+  return jobs;
+}
@@ -0,0 +1,74 @@
+import {
+  buildPathFromSegments,
+  joinPath,
+  normalizeSftpPath,
+  splitPathSegments,
+} from "../transfer-paths.js";
+import { isRootOnlyPath } from "./transfer-host-utils.js";
+import {
+  promisifySftpMkdir,
+  promisifySftpReaddir,
+  promisifySftpRmdir,
+  promisifySftpStat,
+  promisifySftpUnlink,
+} from "./sftp-promisify.js";
+
+type SFTPWrapper = import("ssh2").SFTPWrapper;
+
+export async function ensureDirectoryTreeSftp(
+  sftp: SFTPWrapper,
+  dirPath: string,
+  created: Set<string> = new Set(),
+): Promise<void> {
+  const normalized = normalizeSftpPath(dirPath);
+  if (!normalized || isRootOnlyPath(normalized)) return;
+
+  const { root, segments } = splitPathSegments(normalized);
+  if (segments.length === 0) return;
+
+  for (let i = 0; i < segments.length; i++) {
+    const current = buildPathFromSegments(root, segments, i + 1);
+    if (created.has(current)) continue;
+
+    try {
+      await promisifySftpMkdir(sftp, current, 0o755);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "EEXIST") {
+        try {
+          const stats = await promisifySftpStat(sftp, current);
+          if (!stats.isDirectory()) throw err;
+        } catch {
+          throw err;
+        }
+      }
+    }
+    created.add(current);
+  }
+}
+
+export async function deletePathSftp(
+  sftp: SFTPWrapper,
+  path: string,
+): Promise<void> {
+  let stats: import("ssh2").Stats;
+  try {
+    stats = await promisifySftpStat(sftp, path);
+  } catch {
+    return;
+  }
+
+  if (stats.isDirectory()) {
+    const entries = await promisifySftpReaddir(sftp, path);
+    for (const entry of entries) {
+      if (entry.filename === "." || entry.filename === "..") continue;
+      await deletePathSftp(sftp, joinPath(path, entry.filename));
+    }
+    await promisifySftpRmdir(sftp, path);
+    return;
+  }
+
+  if (stats.isFile()) {
+    await promisifySftpUnlink(sftp, path);
+  }
+}
@@ -0,0 +1,157 @@
+import { performance } from "node:perf_hooks";
+
+const TRANSFER_PROGRESS_INTERVAL_MS = 200;
+
+export type TransferHopId =
+  "source_read" | "dest_sftp_write" | "dest_local_write";
+
+export interface TransferHopMetrics {
+  id: TransferHopId;
+  bytes: number;
+  /** Wall-clock span from first I/O on this hop to last I/O complete. */
+  spanMs: number;
+  mbPerSec: number;
+}
+
+export interface TransferTimings {
+  prepareDestMs?: number;
+  compressMs?: number;
+  transferMs?: number;
+  extractMs?: number;
+  verifyMs?: number;
+  directBenchmarkMs?: number;
+  relayBenchmarkMs?: number;
+  sourceDeleteMs?: number;
+  totalMs?: number;
+  transferBytes?: number;
+  endToEndMbPerSec?: number;
+  hops?: TransferHopMetrics[];
+}
+
+export function elapsedMs(start: number): number {
+  return Date.now() - start;
+}
+
+export function computeTransferMbPerSec(
+  bytes: number,
+  ms: number,
+): number | undefined {
+  if (ms <= 0 || bytes <= 0) return undefined;
+  return ((bytes / ms) * 1000) / (1024 * 1024);
+}
+
+export interface HopWallClock {
+  firstAt: number | null;
+  lastAt: number | null;
+}
+
+export function createHopWallClock(): HopWallClock {
+  return { firstAt: null, lastAt: null };
+}
+
+export function noteHopStart(
+  clock: HopWallClock,
+  t: number = performance.now(),
+): void {
+  if (clock.firstAt === null) clock.firstAt = t;
+}
+
+export function noteHopEnd(
+  clock: HopWallClock,
+  t: number = performance.now(),
+): void {
+  clock.lastAt = t;
+}
+
+export function hopSpanMs(clock: HopWallClock): number {
+  if (clock.firstAt === null || clock.lastAt === null) return 0;
+  return Math.max(0, clock.lastAt - clock.firstAt);
+}
+
+export function createThrottledProgress(onProgress?: (bytes: number) => void) {
+  let pending = 0;
+  let lastFlush = 0;
+
+  const flush = () => {
+    if (pending > 0) {
+      onProgress?.(pending);
+      pending = 0;
+      lastFlush = Date.now();
+    }
+  };
+
+  return {
+    add(bytes: number) {
+      pending += bytes;
+      const now = Date.now();
+      if (now - lastFlush >= TRANSFER_PROGRESS_INTERVAL_MS) {
+        flush();
+      }
+    },
+    flush,
+  };
+}
+
+export interface PipelinedXferStats {
+  bytes: number;
+  sourceReadSpanMs: number;
+  destWriteSpanMs: number;
+  destWriteKind: "sftp" | "local";
+}
+
+export function createEmptyXferStats(): PipelinedXferStats {
+  return {
+    bytes: 0,
+    sourceReadSpanMs: 0,
+    destWriteSpanMs: 0,
+    destWriteKind: "sftp",
+  };
+}
+
+export function mergeXferStats(
+  target: PipelinedXferStats,
+  source: PipelinedXferStats,
+): void {
+  target.bytes += source.bytes;
+  target.sourceReadSpanMs += source.sourceReadSpanMs;
+  target.destWriteSpanMs += source.destWriteSpanMs;
+  target.destWriteKind = source.destWriteKind;
+}
+
+export function buildTransferHopTimings(
+  stats: PipelinedXferStats,
+  transferMs: number,
+): Pick<TransferTimings, "transferBytes" | "endToEndMbPerSec" | "hops"> {
+  const hops: TransferHopMetrics[] = [];
+
+  const sourceRate = computeTransferMbPerSec(
+    stats.bytes,
+    stats.sourceReadSpanMs,
+  );
+  if (sourceRate !== undefined) {
+    hops.push({
+      id: "source_read",
+      bytes: stats.bytes,
+      spanMs: stats.sourceReadSpanMs,
+      mbPerSec: sourceRate,
+    });
+  }
+
+  const destHopId: TransferHopId =
+    stats.destWriteKind === "local" ? "dest_local_write" : "dest_sftp_write";
+  const destRate = computeTransferMbPerSec(stats.bytes, stats.destWriteSpanMs);
+  if (destRate !== undefined) {
+    hops.push({
+      id: destHopId,
+      bytes: stats.bytes,
+      spanMs: stats.destWriteSpanMs,
+      mbPerSec: destRate,
+    });
+  }
+
+  return {
+    transferBytes: stats.bytes,
+    endToEndMbPerSec: computeTransferMbPerSec(stats.bytes, transferMs),
+    hops,
+  };
+}
@@ -2,6 +2,8 @@ import { Client as SSHClient } from "ssh2";
 import { fileLogger } from "../utils/logger.js";
 import { createSocks5Connection } from "../utils/socks5-helper.js";
 import { SSH_ALGORITHMS } from "../utils/ssh-algorithms.js";
+import { preparePrivateKeyForSSH2 } from "../utils/ssh-key-utils.js";
+import { getErrorMessage } from "../utils/error-message.js";
 import { SSHHostKeyVerifier } from "./host-key-verifier.js";
 import { getJumpHostSocks5Config } from "./jump-host-proxy.js";
 import { applyAgentAuth } from "./terminal-auth-helpers.js";
@@ -46,6 +48,17 @@ async function resolveJumpHost(
  }
 }

+export class JumpHostChainError extends Error {
+  constructor(
+    message: string,
+    readonly hopIndex: number,
+    readonly totalHops: number,
+  ) {
+    super(message);
+    this.name = "JumpHostChainError";
+  }
+}
+
 export async function createJumpHostChain(
  jumpHosts: Array<{ hostId: number }>,
  userId: string,
@@ -76,7 +89,11 @@ export async function createJumpHostChain(
          totalHops,
        });
        clients.forEach((c) => c.end());
-        return null;
+        throw new JumpHostChainError(
+          `Jump host ${i + 1} of ${totalHops} was not found`,
+          i,
+          totalHops,
+        );
      }
    }

@@ -106,11 +123,20 @@ export async function createJumpHostChain(
        true,
      );

+      let lastError: Error | null = null;
+
      // eslint-disable-next-line no-async-promise-executor
      const connected = await new Promise<boolean>(async (resolve) => {
+        const readyTimeoutMs = 60000;
        const timeout = setTimeout(() => {
+          lastError = new Error(
+            `Timed out waiting for jump host ${i + 1}/${totalHops} to authenticate`,
+          );
          resolve(false);
-        }, 30000);
+          // ssh2 has no explicit cancel; ending the client stops it from
+          // firing "ready"/"error" after we've already resolved.
+          jumpClient.end();
+        }, readyTimeoutMs + 5000);

        jumpClient.on("ready", () => {
          clearTimeout(timeout);
@@ -119,6 +145,7 @@ export async function createJumpHostChain(

        jumpClient.on("error", (err) => {
          clearTimeout(timeout);
+          lastError = err;
          fileLogger.error(
            `Jump host ${i + 1}/${totalHops} connection failed`,
            err,
@@ -145,7 +172,7 @@ export async function createJumpHostChain(
          port: jumpHostConfig.port || 22,
          username: jumpHostConfig.username,
          tryKeyboard: jumpHostConfig.authType !== "none",
-          readyTimeout: 60000,
+          readyTimeout: readyTimeoutMs,
          hostVerifier: jumpHostVerifier,
          algorithms: {
            kex: [
@@ -190,11 +217,19 @@ export async function createJumpHostChain(
        if (jumpHostConfig.authType === "password" && jumpHostConfig.password) {
          connectConfig.password = jumpHostConfig.password;
        } else if (jumpHostConfig.authType === "key" && jumpHostConfig.key) {
-          const cleanKey = jumpHostConfig.key
-            .trim()
-            .replace(/\r\n/g, "\n")
-            .replace(/\r/g, "\n");
-          connectConfig.privateKey = Buffer.from(cleanKey, "utf8");
+          try {
+            connectConfig.privateKey = preparePrivateKeyForSSH2(
+              jumpHostConfig.key,
+              jumpHostConfig.keyPassword,
+            );
+          } catch (keyError) {
+            clearTimeout(timeout);
+            lastError = new Error(
+              `Jump host ${i + 1}/${totalHops} key error: ${getErrorMessage(keyError, "Invalid private key format")}`,
+            );
+            resolve(false);
+            return;
+          }
          if (jumpHostConfig.keyPassword) {
            connectConfig.passphrase = jumpHostConfig.keyPassword;
          }
@@ -237,6 +272,7 @@ export async function createJumpHostChain(
            (err, stream) => {
              if (err) {
                clearTimeout(timeout);
+                lastError = err;
                resolve(false);
                return;
              }
@@ -254,7 +290,14 @@ export async function createJumpHostChain(

      if (!connected) {
        clients.forEach((c) => c.end());
-        return null;
+        throw new JumpHostChainError(
+          getErrorMessage(
+            lastError,
+            `Jump host ${i + 1} of ${totalHops} failed to connect`,
+          ),
+          i,
+          totalHops,
+        );
      }

      currentClient = jumpClient;
@@ -262,6 +305,7 @@ export async function createJumpHostChain(

    return currentClient;
  } catch (error) {
+    if (error instanceof JumpHostChainError) throw error;
    fileLogger.error("Failed to create jump host chain", error, {
      operation: "jump_host_chain",
    });
@@ -576,16 +576,32 @@ class PollingManager {
      } else {
        isOnline = await tcpPing(refreshedHost.ip, pingPort, 5000);
      }
+      const config = this.pollingConfigs.get(refreshedHost.id);
+      let authenticated: boolean | undefined;
+      if (
+        isOnline &&
+        supportsMetrics(refreshedHost) &&
+        !config?.statsConfig.metricsEnabled
+      ) {
+        try {
+          await withSshConnection(refreshedHost, async () => undefined);
+          authenticated = true;
+        } catch {
+          authenticated = false;
+        }
+      }
      const statusEntry: StatusEntry = {
-        status: statusAfterReachabilityCheck(
-          isOnline,
-          this.statusStore.get(refreshedHost.id)?.status,
-        ),
+        status:
+          authenticated === undefined
+            ? statusAfterReachabilityCheck(
+                isOnline,
+                this.statusStore.get(refreshedHost.id)?.status,
+              )
+            : statusAfterAuthentication(authenticated),
        lastChecked: new Date().toISOString(),
      };
      this.statusStore.set(refreshedHost.id, statusEntry);
      if (isOnline && this.activeViewers.has(refreshedHost.id)) {
-        const config = this.pollingConfigs.get(refreshedHost.id);
        if (config?.statsConfig.metricsEnabled) {
          this.scheduleInitialMetricsPoll(config.host, config.viewerUserId);
        }
@@ -4,6 +4,7 @@ import { SerialPort } from "serialport";
 import { AuthManager } from "../utils/auth-manager.js";
 import { DataCrypto } from "../utils/data-crypto.js";
 import { sshLogger } from "../utils/logger.js";
+import { parseWsMessage } from "../utils/ws-message.js";

 interface SerialConnectData {
  path: string;
@@ -13,11 +14,6 @@ interface SerialConnectData {
  parity?: "none" | "even" | "odd";
 }

-interface WebSocketMessage {
-  type: string;
-  data?: SerialConnectData | string | unknown;
-}
-
 const authManager = AuthManager.getInstance();

 const wss = new WebSocketServer({ port: 30011 });
@@ -93,109 +89,117 @@ wss.on("connection", async (ws: WebSocket, req) => {
  };

  ws.on("message", async (raw: RawData) => {
-    let parsed: WebSocketMessage;
+    let type: string;
+    let data: unknown;
    try {
-      parsed = JSON.parse(raw.toString()) as WebSocketMessage;
+      ({ type, data } = parseWsMessage(raw));
    } catch {
      return;
    }

-    const { type, data } = parsed;
-
-    switch (type) {
-      case "list_ports": {
-        try {
-          const ports = await SerialPort.list();
-          send({ type: "ports_list", data: ports });
-        } catch (err) {
-          send({
-            type: "error",
-            data: getErrorMessage(err, "Failed to list ports"),
-          });
-        }
-        break;
-      }
-
-      case "connect": {
-        if (port?.isOpen) {
-          port.close();
-          port = null;
-        }
-
-        const cfg = data as SerialConnectData;
-        if (!cfg?.path || !cfg?.baudRate) {
-          send({ type: "error", data: "Missing port path or baud rate" });
+    try {
+      switch (type) {
+        case "list_ports": {
+          try {
+            const ports = await SerialPort.list();
+            send({ type: "ports_list", data: ports });
+          } catch (err) {
+            send({
+              type: "error",
+              data: getErrorMessage(err, "Failed to list ports"),
+            });
+          }
          break;
        }

-        try {
-          port = new SerialPort({
-            path: cfg.path,
-            baudRate: cfg.baudRate,
-            dataBits: cfg.dataBits ?? 8,
-            stopBits: cfg.stopBits ?? 1,
-            parity: cfg.parity ?? "none",
-            autoOpen: false,
-          });
+        case "connect": {
+          if (port?.isOpen) {
+            port.close();
+            port = null;
+          }

-          port.open((err) => {
-            if (err) {
-              sshLogger.error("Serial port open failed", err, {
-                operation: "serial_open",
-                path: cfg.path,
-                userId,
-              });
-              send({ type: "error", data: err.message });
-              port = null;
-              return;
-            }
-            sshLogger.info("Serial port opened", {
-              operation: "serial_open",
+          const cfg = data as SerialConnectData;
+          if (!cfg?.path || !cfg?.baudRate) {
+            send({ type: "error", data: "Missing port path or baud rate" });
+            break;
+          }
+
+          try {
+            port = new SerialPort({
              path: cfg.path,
              baudRate: cfg.baudRate,
-              userId,
+              dataBits: cfg.dataBits ?? 8,
+              stopBits: cfg.stopBits ?? 1,
+              parity: cfg.parity ?? "none",
+              autoOpen: false,
            });
-            send({ type: "connected" });
-          });

-          port.on("data", (chunk: Buffer) => {
-            send({ type: "data", data: chunk.toString("binary") });
-          });
+            port.open((err) => {
+              if (err) {
+                sshLogger.error("Serial port open failed", err, {
+                  operation: "serial_open",
+                  path: cfg.path,
+                  userId,
+                });
+                send({ type: "error", data: err.message });
+                port = null;
+                return;
+              }
+              sshLogger.info("Serial port opened", {
+                operation: "serial_open",
+                path: cfg.path,
+                baudRate: cfg.baudRate,
+                userId,
+              });
+              send({ type: "connected" });
+            });

-          port.on("error", (err) => {
-            send({ type: "error", data: err.message });
-          });
+            port.on("data", (chunk: Buffer) => {
+              send({ type: "data", data: chunk.toString("binary") });
+            });

-          port.on("close", () => {
-            send({ type: "disconnected" });
-            port = null;
-          });
-        } catch (err) {
-          send({
-            type: "error",
-            data: getErrorMessage(err, "Failed to open serial port"),
-          });
-        }
-        break;
-      }
+            port.on("error", (err) => {
+              send({ type: "error", data: err.message });
+            });

-      case "input": {
-        if (!port?.isOpen) break;
-        const input = typeof data === "string" ? data : "";
-        if (!input) break;
-        port.write(Buffer.from(input, "binary"), (err) => {
-          if (err) {
-            send({ type: "error", data: err.message });
+            port.on("close", () => {
+              send({ type: "disconnected" });
+              port = null;
+            });
+          } catch (err) {
+            send({
+              type: "error",
+              data: getErrorMessage(err, "Failed to open serial port"),
+            });
          }
-        });
-        break;
-      }
+          break;
+        }

-      case "disconnect": {
-        cleanup();
-        send({ type: "disconnected" });
-        break;
+        case "input": {
+          if (!port?.isOpen) break;
+          const input = typeof data === "string" ? data : "";
+          if (!input) break;
+          port.write(Buffer.from(input, "binary"), (err) => {
+            if (err) {
+              send({ type: "error", data: err.message });
+            }
+          });
+          break;
+        }
+
+        case "disconnect": {
+          cleanup();
+          send({ type: "disconnected" });
+          break;
+        }
      }
+    } catch (err) {
+      sshLogger.error("Error handling serial WebSocket message", err, {
+        operation: "serial_message_handler_error",
+        userId,
+        messageType: type,
+      });
+      send({ type: "error", data: "Failed to process message" });
    }
  });

@@ -1,13 +1,18 @@
 import dgram from "dgram";
 import net from "net";
 import ssh2Pkg, {
+  type BaseAgent as BaseAgentType,
+  type GetStreamCallback,
  type IdentityCallback,
+  type KnownPublicKeys,
  type ParsedKey,
  type SignCallback,
  type SigningRequestOptions,
 } from "ssh2";

-const { BaseAgent } = ssh2Pkg;
+type KnownPublicKey = KnownPublicKeys[number];
+
+const { AgentProtocol, BaseAgent } = ssh2Pkg;
 const DEFAULT_PORT_KNOCK_TIMEOUT_MS = 1000;

 type Sleep = (ms: number) => Promise<void>;
@@ -34,6 +39,23 @@ export class MemoryAgent extends BaseAgent {
    cb(null, [this.key]);
  }

+  getStream(cb: GetStreamCallback): void {
+    const protocol = new AgentProtocol(false);
+
+    protocol.on("identities", (request) => {
+      protocol.getIdentitiesReply(request, [this.key]);
+    });
+
+    protocol.on("sign", (request, publicKey, data, options) => {
+      this.sign(publicKey, data, options, (error, signature) => {
+        if (error || !signature) return protocol.failureReply(request);
+        protocol.signReply(request, signature);
+      });
+    });
+
+    cb(null, protocol);
+  }
+
  sign(
    _pubKey: ParsedKey | Buffer | string,
    data: Buffer,
@@ -85,6 +107,84 @@ export async function resolveAgentSocket(
  return { socketPath: resolved };
 }

+/**
+ * Wraps an agent so only identities matching a specific public key are
+ * offered to the server, mirroring ssh_config's IdentityFile + IdentitiesOnly
+ * for agent auth. Prevents exhausting the server's MaxAuthTries when the
+ * agent holds many keys.
+ */
+export class FilteredAgent extends BaseAgent {
+  private inner: BaseAgentType;
+  private publicKeyBlob: Buffer;
+
+  constructor(inner: BaseAgentType, publicKeyBlob: Buffer) {
+    super();
+    this.inner = inner;
+    this.publicKeyBlob = publicKeyBlob;
+  }
+
+  private matches(key: KnownPublicKey): boolean {
+    try {
+      const blob =
+        typeof key === "string"
+          ? Buffer.from(key)
+          : Buffer.isBuffer(key)
+            ? key
+            : "getPublicSSH" in key
+              ? key.getPublicSSH()
+              : null;
+      return (
+        Buffer.isBuffer(blob) && Buffer.compare(blob, this.publicKeyBlob) === 0
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  getIdentities(cb: IdentityCallback): void {
+    this.inner.getIdentities((err, keys) => {
+      if (err || !keys) return cb(err, keys);
+      cb(
+        null,
+        keys.filter((key) => this.matches(key)),
+      );
+    });
+  }
+
+  getStream(cb: GetStreamCallback): void {
+    if (typeof this.inner.getStream !== "function") {
+      return cb(new Error("Agent does not support forwarding."));
+    }
+    this.inner.getStream(cb);
+  }
+
+  sign(
+    pubKey: ParsedKey | Buffer | string,
+    data: Buffer,
+    optionsOrCb: SigningRequestOptions | SignCallback,
+    cb?: SignCallback,
+  ): void {
+    this.inner.sign(
+      pubKey,
+      data,
+      optionsOrCb as SigningRequestOptions,
+      cb as SignCallback,
+    );
+  }
+}
+
+function parseAgentIdentityBlob(agentIdentity: string): Buffer | null {
+  const { utils } = ssh2Pkg;
+  const parsed = utils.parseKey(agentIdentity.trim());
+  if (parsed instanceof Error || !parsed) return null;
+  const key = Array.isArray(parsed) ? parsed[0] : parsed;
+  try {
+    return key.getPublicSSH();
+  } catch {
+    return null;
+  }
+}
+
 export async function applyAgentAuth(
  connectConfig: Record<string, unknown>,
  terminalConfig: Record<string, unknown> | undefined,
@@ -93,7 +193,21 @@ export async function applyAgentAuth(
  if ("error" in result) return result;

  const { createAgent } = ssh2Pkg;
-  connectConfig.agent = createAgent(result.socketPath);
+  const agent = createAgent(result.socketPath);
+
+  const agentIdentity = (
+    terminalConfig?.agentIdentity as string | undefined
+  )?.trim();
+  if (agentIdentity) {
+    const publicKeyBlob = parseAgentIdentityBlob(agentIdentity);
+    if (!publicKeyBlob) {
+      return { error: "Invalid public key provided for agent identity." };
+    }
+    connectConfig.agent = new FilteredAgent(agent, publicKeyBlob);
+  } else {
+    connectConfig.agent = agent;
+  }
+
  return result;
 }

@@ -55,6 +55,15 @@ export const HOST_NOT_ON_THIS_SERVER_MESSAGE =
  "This host does not exist on the sync server, so the connection was refused. " +
  'Run a sync so the server knows about it, or set the connection origin to "This device" for this host.';

+export function resolveServerJumpHosts(
+  clientJumpHosts: Array<{ hostId: number }> | undefined,
+  serverJumpHosts: Array<{ hostId: number }> | undefined,
+  hostSyncId?: string | null,
+): Array<{ hostId: number }> | undefined {
+  if (hostSyncId) return serverJumpHosts ?? [];
+  return clientJumpHosts?.length ? clientJumpHosts : serverJumpHosts;
+}
+
 /**
 * Thrown where a mismatch is reported by rejecting rather than by messaging
 * the socket. Callers whose host-resolution is wrapped in a "failed to resolve
@@ -177,8 +177,8 @@ export function buildPaneMetrics(
    const treePids: number[] = [];
    const queue = [pane.pid];
    const seen = new Set<number>();
-    while (queue.length > 0) {
-      const pid = queue.shift()!;
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+      const pid = queue[cursor];
      if (seen.has(pid)) continue;
      seen.add(pid);
      if (byPid.has(pid)) treePids.push(pid);
@@ -225,9 +225,19 @@ export function attachPanesToWindows(
  windows: Map<string, TmuxWindow[]>,
  panes: RawPane[],
 ): void {
+  const windowsBySessionAndIndex = new Map<string, Map<number, TmuxWindow>>();
+  for (const [sessionName, sessionWindows] of windows) {
+    const byIndex = new Map<number, TmuxWindow>();
+    for (const window of sessionWindows) {
+      if (!byIndex.has(window.index)) byIndex.set(window.index, window);
+    }
+    windowsBySessionAndIndex.set(sessionName, byIndex);
+  }
+
  for (const pane of panes) {
-    const sessionWindows = windows.get(pane.sessionName) || [];
-    const window = sessionWindows.find((w) => w.index === pane.windowIndex);
+    const window = windowsBySessionAndIndex
+      .get(pane.sessionName)
+      ?.get(pane.windowIndex);
    if (window) {
      const { sessionName: _s, windowIndex: _w, ...paneFields } = pane;
      window.panes.push(paneFields);
@@ -384,18 +384,36 @@ async function provisionLocalDesktopUserIfNeeded(): Promise<void> {
      }
    });

+    // A single bad request must not take the server down. Exit only on errors
+    // that leave the process genuinely unusable; log and keep serving
+    // otherwise, since these are almost always scoped to one connection.
+    const isFatalError = (error: unknown): boolean => {
+      const code = (error as NodeJS.ErrnoException)?.code;
+      if (code === "ERR_WORKER_OUT_OF_MEMORY") return true;
+      if (error instanceof RangeError) {
+        return /call stack|heap out of memory/i.test(error.message);
+      }
+      return false;
+    };
+
    process.on("uncaughtException", (error) => {
      systemLogger.error("Uncaught exception occurred", error, {
        operation: "error_handling",
+        fatal: isFatalError(error),
      });
-      process.exit(1);
+      if (isFatalError(error)) {
+        process.exit(1);
+      }
    });

    process.on("unhandledRejection", (reason) => {
      systemLogger.error("Unhandled promise rejection", reason, {
        operation: "error_handling",
+        fatal: isFatalError(reason),
      });
-      process.exit(1);
+      if (isFatalError(reason)) {
+        process.exit(1);
+      }
    });
  } catch (error) {
    systemLogger.error("Failed to initialize backend services", error, {
@@ -47,6 +47,12 @@ const repository = {
  }),
 };

+const resolveHostById = vi.fn();
+
+vi.mock("../../hosts/host-resolver.js", () => ({
+  resolveHostById: (...args: unknown[]) => resolveHostById(...args),
+}));
+
 vi.mock("../../database/repositories/factory.js", () => ({
  createCurrentAutomationRepository: () => repository,
 }));
@@ -93,12 +99,41 @@ beforeEach(() => {
  nextRunId = 1;
  nextStepRowId = 1;
  vi.clearAllMocks();
+  resolveHostById.mockResolvedValue(null);
  executeStep.mockResolvedValue({ success: true, output: "ok" });
  // The singleton carries in-flight state between tests.
  (AutomationEngine as unknown as { instance?: unknown }).instance = undefined;
 });

 describe("AutomationEngine.run", () => {
+  it("adds the trigger host name to the template context", async () => {
+    defineAutomation([step({ id: "notify", type: "notify" })]);
+    resolveHostById.mockResolvedValue({
+      name: "Proxmox Node",
+      ip: "10.0.0.11",
+      username: "root",
+      port: 22,
+    });
+
+    await AutomationEngine.getInstance().run({
+      automationId: 1,
+      triggerType: "metric_threshold",
+      triggerHostId: 11,
+      triggerContext: { hostId: 11, value: 97 },
+    });
+
+    const context = executeStep.mock.calls[0][1] as {
+      template: {
+        host: { id: number; name: string };
+        trigger: { hostName: string };
+      };
+    };
+    expect(context.template.host).toMatchObject({
+      id: 11,
+      name: "Proxmox Node",
+    });
+    expect(context.template.trigger.hostName).toBe("Proxmox Node");
+  });
  it("runs steps in order and records each one", async () => {
    defineAutomation([
      step({ id: "a", type: "run_command" }),
@@ -0,0 +1,44 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const automationFetch = vi.fn();
+
+vi.mock("../../automations/http.js", () => ({
+  automationFetch: (...args: unknown[]) => automationFetch(...args),
+}));
+
+const { sendAutomationNotification } =
+  await import("../../automations/notify.js");
+
+beforeEach(() => {
+  automationFetch.mockReset();
+  automationFetch.mockResolvedValue({ ok: true });
+});
+
+describe("sendAutomationNotification", () => {
+  it("keeps alert-compatible host and rule fields in webhook payloads", async () => {
+    await sendAutomationNotification(
+      { id: 1, type: "webhook", config: '{"url":"https://example.com"}' },
+      {
+        title: "CPU warning",
+        body: "cpu.percent is at 97",
+        severity: "warning",
+        context: {
+          host: { id: 11, name: "Proxmox Node" },
+          trigger: { value: 97, threshold: 90 },
+          run: { automationId: 42 },
+        },
+      },
+    );
+
+    const options = automationFetch.mock.calls[0][1] as RequestInit;
+    expect(JSON.parse(options.body as string)).toMatchObject({
+      hostName: "Proxmox Node",
+      hostId: 11,
+      ruleName: "CPU warning",
+      ruleId: 42,
+      value: 97,
+      threshold: 90,
+      message: "cpu.percent is at 97",
+    });
+  });
+});
@@ -1,7 +1,8 @@
 import { sql } from "drizzle-orm";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { TestSqliteDatabase } from "./test-support.js";
 import { HostRepository } from "../../../database/repositories/host-repository.js";
+import { DataCrypto } from "../../../utils/data-crypto.js";

 describe("HostRepository.reorderForUser", () => {
  let adapter: TestSqliteDatabase | null = null;
@@ -72,3 +73,100 @@ describe("HostRepository.reorderForUser", () => {
    await expect(repo.reorderForUser("user-1", [])).resolves.toBe(0);
  });
 });
+
+describe("HostRepository Proxmox sync inserts", () => {
+  let adapter: TestSqliteDatabase | null = null;
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await adapter?.close();
+    adapter = null;
+  });
+
+  it("creates a discovered guest using the scheduled-sync payload", async () => {
+    adapter = new TestSqliteDatabase();
+    const context = await adapter.connect();
+    await adapter.exec(`
+      INSERT INTO users (id, username, password_hash)
+      VALUES ('user-1', 'alice', 'hash');
+      INSERT INTO ssh_credentials (id, user_id, name, auth_type, username)
+      VALUES (7, 'user-1', 'guest key', 'key', 'alice');
+    `);
+    const repository = new HostRepository(context);
+    const now = new Date().toISOString();
+    vi.spyOn(DataCrypto, "validateUserAccess").mockReturnValue(
+      Buffer.alloc(32, 1),
+    );
+
+    const created = await repository.createEncryptedForUser("user-1", {
+      userId: "user-1",
+      name: "guest",
+      ip: "10.0.0.8",
+      port: 22,
+      username: "",
+      connectionType: "ssh",
+      folder: "Proxmox",
+      tags: "proxmox,qemu,node-1,vm-100",
+      proxmoxConfig: JSON.stringify({
+        source: {
+          source: "proxmox",
+          sourceHostId: 1,
+          node: "node-1",
+          vmid: 100,
+          type: "qemu",
+        },
+      }),
+      updatedAt: now,
+      createdAt: now,
+      pin: false,
+      authType: "credential",
+      credentialId: 7,
+      overrideCredentialUsername: 0,
+      password: null,
+      key: null,
+      keyPassword: null,
+      keyType: null,
+      enableTerminal: true,
+      enableFileManager: true,
+      enableTunnel: true,
+      enableDocker: false,
+      enableSsh: true,
+      enableRdp: false,
+      rdpUser: null,
+      rdpPassword: null,
+      rdpDomain: null,
+      rdpSecurity: null,
+      rdpIgnoreCert: 0,
+      rdpPort: null,
+      vncUser: null,
+      vncPassword: null,
+      vncPort: null,
+      telnetUser: null,
+      telnetPassword: null,
+      telnetPort: null,
+      defaultPath: "/",
+      tunnelConnections: "[]",
+      jumpHosts: null,
+      quickActions: null,
+      statsConfig: null,
+      dockerConfig: null,
+      terminalConfig: null,
+      forceKeyboardInteractive: "false",
+      useSocks5: 0,
+      socks5Host: null,
+      socks5Port: null,
+      socks5Username: null,
+      socks5Password: null,
+      socks5ProxyChain: null,
+      portKnockSequence: null,
+      showTerminalInSidebar: 0,
+      showFileManagerInSidebar: 0,
+      showTunnelInSidebar: 0,
+      showDockerInSidebar: 0,
+      showServerStatsInSidebar: 0,
+    });
+
+    expect(created.username).toBe("");
+    expect(created.credentialId).toBe(7);
+  });
+});
@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const factory = vi.hoisted(() => ({
+  getCurrentRepositorySqlite: vi.fn(),
+}));
+
+vi.mock("../../../database/repositories/factory.js", () => factory);
+
+import {
+  withCurrentSqliteForeignKeysDisabled,
+  withSqliteForeignKeysDisabled,
+} from "../../../database/repositories/sqlite-foreign-keys.js";
+
+const previousDatabaseDialect = process.env.DATABASE_DIALECT;
+
+afterEach(() => {
+  if (previousDatabaseDialect === undefined)
+    delete process.env.DATABASE_DIALECT;
+  else process.env.DATABASE_DIALECT = previousDatabaseDialect;
+  vi.clearAllMocks();
+});
+
+describe("withSqliteForeignKeysDisabled", () => {
+  it("restores foreign keys after an import", async () => {
+    const sqlite = { exec: vi.fn() };
+
+    await expect(
+      withSqliteForeignKeysDisabled(sqlite, async () => "imported"),
+    ).resolves.toBe("imported");
+    expect(sqlite.exec.mock.calls).toEqual([
+      ["PRAGMA foreign_keys = OFF"],
+      ["PRAGMA foreign_keys = ON"],
+    ]);
+  });
+});
+
+describe("withCurrentSqliteForeignKeysDisabled", () => {
+  it.each(["postgres", "mysql"])(
+    "runs portable imports with constraints enabled on %s",
+    async (dialect) => {
+      process.env.DATABASE_DIALECT = dialect;
+      const operation = vi.fn().mockResolvedValue("imported");
+
+      await expect(
+        withCurrentSqliteForeignKeysDisabled(operation),
+      ).resolves.toBe("imported");
+      expect(operation).toHaveBeenCalledOnce();
+      expect(factory.getCurrentRepositorySqlite).not.toHaveBeenCalled();
+    },
+  );
+});
@@ -9,7 +9,7 @@ describe("resolveProxmoxImportAuth", () => {
    expect(resolveProxmoxImportAuth("key", 7)).toEqual({
      authType: "credential",
      credentialId: 7,
-      overrideCredentialUsername: 1,
+      overrideCredentialUsername: 0,
    });
  });

@@ -17,7 +17,7 @@ describe("resolveProxmoxImportAuth", () => {
    expect(resolveProxmoxImportAuth("password", 7)).toEqual({
      authType: "credential",
      credentialId: 7,
-      overrideCredentialUsername: 1,
+      overrideCredentialUsername: 0,
    });
  });

@@ -35,7 +35,7 @@ describe("resolveProxmoxImportAuth", () => {
    expect(resolveProxmoxImportAuth(undefined, 42)).toEqual({
      authType: "credential",
      credentialId: 42,
-      overrideCredentialUsername: 1,
+      overrideCredentialUsername: 0,
    });
    expect(resolveProxmoxImportAuth(undefined, null)).toEqual({
      authType: "none",
@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("../../../utils/auth-manager.js", () => ({
+  AuthManager: {
+    getInstance: () => ({ createAdminMiddleware: vi.fn() }),
+  },
+}));
+
+const { isValidOidcIssuer } =
+  await import("../../../database/routes/sso-provider-routes.js");
+
+describe("isValidOidcIssuer", () => {
+  it("rejects userinfo endpoints used as issuer URLs", () => {
+    expect(
+      isValidOidcIssuer("https://auth.example/application/o/userinfo/"),
+    ).toBe(false);
+  });
+
+  it("accepts an Authentik application issuer", () => {
+    expect(isValidOidcIssuer("https://auth.example/application/o/termix")).toBe(
+      true,
+    );
+  });
+});
@@ -21,6 +21,7 @@ const {
  resolveOidcMappedRoles,
  verifyOIDCToken,
  describeFetchFailure,
+  isOIDCEnvOverrideEnabled,
 } = await import("../../../database/routes/user-oidc-utils.js");

 const BACKCHANNEL_LOGOUT_EVENT =
@@ -281,6 +282,7 @@ describe("getOIDCConfigFromEnv", () => {
    "OIDC_SCOPES",
    "OIDC_ALLOWED_USERS",
    "OIDC_ADMIN_GROUP",
+    "OIDC_ENV_OVERRIDE",
  ];
  const saved: Record<string, string | undefined> = {};

@@ -334,6 +336,12 @@ describe("getOIDCConfigFromEnv", () => {
    expect(config?.identifier_path).toBe("email");
    expect(config?.scopes).toBe("openid");
  });
+
+  it("only enables database recovery override when explicitly requested", () => {
+    expect(isOIDCEnvOverrideEnabled()).toBe(false);
+    process.env.OIDC_ENV_OVERRIDE = "true";
+    expect(isOIDCEnvOverrideEnabled()).toBe(true);
+  });
 });

 describe("extractOidcGroups", () => {
@@ -0,0 +1,35 @@
+import { createRequire } from "node:module";
+import { describe, expect, it } from "vitest";
+
+const require = createRequire(import.meta.url);
+const { resolveLocalShell } =
+  require("../../../../electron/local-shell.cjs") as {
+    resolveLocalShell: (
+      platform: NodeJS.Platform,
+      requestedShell?: string,
+      env?: NodeJS.ProcessEnv,
+    ) => { file: string; args: string[] };
+  };
+
+describe("resolveLocalShell", () => {
+  it("starts the default WSL distribution without PowerShell arguments", () => {
+    expect(resolveLocalShell("win32", "wsl", {})).toEqual({
+      file: "wsl.exe",
+      args: [],
+    });
+  });
+
+  it("keeps PowerShell as the default Windows shell", () => {
+    expect(resolveLocalShell("win32", "default", {})).toEqual({
+      file: "powershell.exe",
+      args: ["-NoLogo"],
+    });
+  });
+
+  it("preserves the configured shell on non-Windows platforms", () => {
+    expect(resolveLocalShell("linux", "wsl", { SHELL: "/bin/fish" })).toEqual({
+      file: "/bin/fish",
+      args: ["-l"],
+    });
+  });
+});
@@ -1,4 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { generateKeyPairSync } from "crypto";
+import ssh2Pkg, { type ParsedKey } from "ssh2";

 const mockAccess = vi.fn();

@@ -6,7 +8,57 @@ vi.mock("fs/promises", () => ({
  access: mockAccess,
 }));

-import { resolveAgentSocket } from "../../hosts/terminal-auth-helpers.js";
+import {
+  MemoryAgent,
+  FilteredAgent,
+  resolveAgentSocket,
+} from "../../hosts/terminal-auth-helpers.js";
+
+describe("MemoryAgent", () => {
+  it("serves identities and signatures over the agent protocol", async () => {
+    const { privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const parsed = ssh2Pkg.utils.parseKey(
+      privateKey.export({ type: "pkcs1", format: "pem" }),
+    );
+    expect(parsed).not.toBeInstanceOf(Error);
+
+    const agent = new MemoryAgent(parsed as ParsedKey);
+    const stream = await new Promise<NodeJS.ReadWriteStream>(
+      (resolve, reject) => {
+        agent.getStream((error, result) => {
+          if (error || !result)
+            reject(error ?? new Error("Missing agent stream"));
+          else resolve(result);
+        });
+      },
+    );
+    const client = new ssh2Pkg.AgentProtocol(true);
+    client.pipe(stream).pipe(client);
+
+    const identities = await new Promise<ParsedKey[]>((resolve, reject) => {
+      client.getIdentities((error, keys) => {
+        if (error || !keys) reject(error ?? new Error("Missing identities"));
+        else resolve(keys);
+      });
+    });
+    expect(identities).toHaveLength(1);
+    expect(identities[0].getPublicSSH()).toEqual(
+      (parsed as ParsedKey).getPublicSSH(),
+    );
+
+    const data = Buffer.from("forwarded-agent-test");
+    const signature = await new Promise<Buffer>((resolve, reject) => {
+      client.sign(identities[0], data, (error, result) => {
+        if (error || !result) reject(error ?? new Error("Missing signature"));
+        else resolve(result);
+      });
+    });
+    expect((parsed as ParsedKey).verify(data, signature)).toBe(true);
+
+    client.destroy();
+    stream.destroy();
+  });
+});

 describe("resolveAgentSocket", () => {
  const originalEnv = process.env.SSH_AUTH_SOCK;
@@ -101,3 +153,78 @@ describe("resolveAgentSocket", () => {
    expect(mockAccess).not.toHaveBeenCalled();
  });
 });
+
+describe("FilteredAgent", () => {
+  it("only returns identities matching the configured public key", async () => {
+    const { privateKey: keyA } = generateKeyPairSync("rsa", {
+      modulusLength: 2048,
+    });
+    const { privateKey: keyB } = generateKeyPairSync("rsa", {
+      modulusLength: 2048,
+    });
+    const parsedA = ssh2Pkg.utils.parseKey(
+      keyA.export({ type: "pkcs1", format: "pem" }),
+    ) as ParsedKey;
+    const parsedB = ssh2Pkg.utils.parseKey(
+      keyB.export({ type: "pkcs1", format: "pem" }),
+    ) as ParsedKey;
+
+    const inner = {
+      getIdentities: (cb: (err: Error | null, keys: ParsedKey[]) => void) =>
+        cb(null, [parsedA, parsedB]),
+      getStream: vi.fn(),
+      sign: vi.fn(),
+    };
+
+    const filtered = new FilteredAgent(
+      inner as unknown as ConstructorParameters<typeof FilteredAgent>[0],
+      parsedB.getPublicSSH(),
+    );
+
+    const identities = await new Promise<ParsedKey[]>((resolve, reject) => {
+      filtered.getIdentities((err, keys) => {
+        if (err || !keys) reject(err ?? new Error("Missing identities"));
+        else resolve(keys);
+      });
+    });
+
+    expect(identities).toHaveLength(1);
+    expect(identities[0].getPublicSSH()).toEqual(parsedB.getPublicSSH());
+  });
+
+  it("returns no identities when nothing matches", async () => {
+    const { privateKey: keyA } = generateKeyPairSync("rsa", {
+      modulusLength: 2048,
+    });
+    const { privateKey: keyB } = generateKeyPairSync("rsa", {
+      modulusLength: 2048,
+    });
+    const parsedA = ssh2Pkg.utils.parseKey(
+      keyA.export({ type: "pkcs1", format: "pem" }),
+    ) as ParsedKey;
+    const parsedB = ssh2Pkg.utils.parseKey(
+      keyB.export({ type: "pkcs1", format: "pem" }),
+    ) as ParsedKey;
+
+    const inner = {
+      getIdentities: (cb: (err: Error | null, keys: ParsedKey[]) => void) =>
+        cb(null, [parsedA]),
+      getStream: vi.fn(),
+      sign: vi.fn(),
+    };
+
+    const filtered = new FilteredAgent(
+      inner as unknown as ConstructorParameters<typeof FilteredAgent>[0],
+      parsedB.getPublicSSH(),
+    );
+
+    const identities = await new Promise<ParsedKey[]>((resolve, reject) => {
+      filtered.getIdentities((err, keys) => {
+        if (err || !keys) reject(err ?? new Error("Missing identities"));
+        else resolve(keys);
+      });
+    });
+
+    expect(identities).toHaveLength(0);
+  });
+});
@@ -6,6 +6,7 @@ import {
  HostAddressMismatchError,
  HostNotOnThisServerError,
  normalizeHostAddress,
+  resolveServerJumpHosts,
 } from "../../../hosts/terminal/host-identity.js";

 /**
@@ -59,6 +60,20 @@ describe("hostAddressMismatch", () => {
  });
 });

+describe("resolveServerJumpHosts", () => {
+  it("uses server-side ids for a sync-delegated connection", () => {
+    expect(
+      resolveServerJumpHosts([{ hostId: 7 }], [{ hostId: 42 }], "host-sync-id"),
+    ).toEqual([{ hostId: 42 }]);
+  });
+
+  it("keeps client ids for a local id-based connection", () => {
+    expect(resolveServerJumpHosts([{ hostId: 7 }], [{ hostId: 42 }])).toEqual([
+      { hostId: 7 },
+    ]);
+  });
+});
+
 describe("HostAddressMismatchError", () => {
  it("survives the catch blocks that swallow resolution failures", () => {
    // SFTP host resolution sits inside "failed to resolve credentials, carry
@@ -9,6 +9,8 @@ import {
  buildPaneMetrics,
  attachPanesToWindows,
  shellEscape,
+  type ProcessInfo,
+  type TmuxWindow,
 } from "../../../hosts/tmux/monitor-helpers.js";

 function join(...fields: (string | number)[]): string {
@@ -194,6 +196,28 @@ describe("buildPaneMetrics", () => {
    const metrics = buildPaneMetrics(pane, cyclic, new Map());
    expect(metrics[0].processCount).toBe(2);
  });
+
+  it("aggregates a wide process tree without dropping children", () => {
+    const childCount = 2_000;
+    const wideTree: ProcessInfo[] = [
+      { pid: 1, ppid: 0, cpu: 0, mem: 0, rss: 1, comm: "bash" },
+      ...Array.from({ length: childCount }, (_, index) => ({
+        pid: index + 2,
+        ppid: 1,
+        cpu: 0.1,
+        mem: 0,
+        rss: 1,
+        comm: `worker-${index}`,
+      })),
+    ];
+    const pane = parsePanes(
+      join("wide", 0, "%1", 0, 1, 1, 80, 24, "bash", "/", "t"),
+    );
+
+    const [metrics] = buildPaneMetrics(pane, wideTree, new Map());
+    expect(metrics.processCount).toBe(childCount + 1);
+    expect(metrics.memRssKb).toBe(childCount + 1);
+  });
 });

 describe("attachPanesToWindows", () => {
@@ -214,6 +238,29 @@ describe("attachPanesToWindows", () => {
    expect(windows.get("s1")![0].panes[0].id).toBe("%1");
    expect(windows.get("s1")![1].panes[0].id).toBe("%2");
  });
+
+  it("preserves first-match behavior for duplicate window indexes", () => {
+    const first: TmuxWindow = {
+      index: 0,
+      name: "first",
+      active: true,
+      panes: [],
+    };
+    const duplicate: TmuxWindow = {
+      index: 0,
+      name: "duplicate",
+      active: false,
+      panes: [],
+    };
+    const windows = new Map([["s1", [first, duplicate]]]);
+    const panes = parsePanes(
+      join("s1", 0, "%1", 0, 100, 1, 80, 24, "bash", "/", "t"),
+    );
+
+    attachPanesToWindows(windows, panes);
+    expect(first.panes).toHaveLength(1);
+    expect(duplicate.panes).toHaveLength(0);
+  });
 });

 describe("shellEscape", () => {
@@ -0,0 +1,41 @@
+import { createServer } from "node:http";
+import { afterEach, describe, expect, it } from "vitest";
+import { fetchWithProxy } from "../../utils/proxy-agent.js";
+
+describe("fetchWithProxy", () => {
+  const savedProxies = {
+    HTTP_PROXY: process.env.HTTP_PROXY,
+    HTTPS_PROXY: process.env.HTTPS_PROXY,
+    http_proxy: process.env.http_proxy,
+    https_proxy: process.env.https_proxy,
+  };
+
+  afterEach(() => {
+    for (const [name, value] of Object.entries(savedProxies)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("uses a dispatcher compatible with the selected fetch implementation", async () => {
+    delete process.env.HTTP_PROXY;
+    delete process.env.HTTPS_PROXY;
+    delete process.env.http_proxy;
+    delete process.env.https_proxy;
+    const server = createServer((_request, response) => response.end("ok"));
+    await new Promise<void>((resolve) =>
+      server.listen(0, "127.0.0.1", resolve),
+    );
+
+    try {
+      const address = server.address();
+      if (!address || typeof address === "string") throw new Error("No port");
+      const response = await fetchWithProxy(`http://127.0.0.1:${address.port}`);
+      expect(await response.text()).toBe("ok");
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve())),
+      );
+    }
+  });
+});
@@ -4,6 +4,7 @@ import {
  parseSSHKey,
  parsePublicKey,
  preparePrivateKeyForSSH2,
+  isPrivateKeyPassphraseError,
  getFriendlyKeyTypeName,
  validateKeyPair,
 } from "../../utils/ssh-key-utils.js";
@@ -97,6 +98,22 @@ describe("parseSSHKey", () => {
  });
 });

+describe("isPrivateKeyPassphraseError", () => {
+  it("recognizes missing and incorrect passphrase errors", () => {
+    expect(
+      isPrivateKeyPassphraseError(
+        new Error(
+          "Encrypted OpenSSH private key detected, but no passphrase given",
+        ),
+      ),
+    ).toBe(true);
+    expect(isPrivateKeyPassphraseError(new Error("Bad passphrase"))).toBe(true);
+    expect(
+      isPrivateKeyPassphraseError(new Error("Unsupported key format")),
+    ).toBe(false);
+  });
+});
+
 describe("getFriendlyKeyTypeName", () => {
  it("maps known key types to friendly names", () => {
    expect(getFriendlyKeyTypeName("ssh-rsa")).toBe("RSA");
@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseWsMessage,
+  asObject,
+  asString,
+  toTerminalDimension,
+  WsMessageError,
+} from "../../utils/ws-message.js";
+
+const frame = (s: string) => Buffer.from(s, "utf8");
+
+describe("parseWsMessage", () => {
+  it("parses a well-formed message", () => {
+    expect(parseWsMessage(frame('{"type":"ping"}'))).toEqual({
+      type: "ping",
+      data: undefined,
+    });
+    expect(parseWsMessage(frame('{"type":"input","data":"ls"}'))).toEqual({
+      type: "input",
+      data: "ls",
+    });
+  });
+
+  it("rejects JSON that parses but cannot be destructured", () => {
+    // The original DoS: JSON.parse("null") succeeds, so it escaped the
+    // try/catch and threw a TypeError on destructure.
+    for (const payload of ["null", "123", '"str"', "[1,2]", "true"]) {
+      expect(() => parseWsMessage(frame(payload))).toThrow(WsMessageError);
+    }
+  });
+
+  it("rejects invalid JSON", () => {
+    expect(() => parseWsMessage(frame("{oops"))).toThrow(WsMessageError);
+    expect(() => parseWsMessage(frame(""))).toThrow(WsMessageError);
+  });
+
+  it("rejects a missing or non-string type", () => {
+    expect(() => parseWsMessage(frame("{}"))).toThrow(WsMessageError);
+    expect(() => parseWsMessage(frame('{"type":5}'))).toThrow(WsMessageError);
+    expect(() => parseWsMessage(frame('{"type":null}'))).toThrow(
+      WsMessageError,
+    );
+  });
+
+  it("rejects oversized frames", () => {
+    const huge = Buffer.alloc(1024 * 1024 + 1, 0x20);
+    expect(() => parseWsMessage(huge)).toThrow(WsMessageError);
+  });
+
+  it("never throws a TypeError for any malformed input", () => {
+    const payloads = [
+      "null",
+      "0",
+      "[]",
+      "{}",
+      '{"type":{}}',
+      '{"data":"x"}',
+      "undefined",
+      '{"type":"a","data":null}',
+    ];
+    for (const p of payloads) {
+      try {
+        parseWsMessage(frame(p));
+      } catch (e) {
+        expect(e).toBeInstanceOf(WsMessageError);
+      }
+    }
+  });
+});
+
+describe("asObject / asString", () => {
+  it("narrows without throwing", () => {
+    expect(asObject({ a: 1 })).toEqual({ a: 1 });
+    expect(asObject(null)).toEqual({});
+    expect(asObject([1])).toEqual({});
+    expect(asObject("x")).toEqual({});
+    expect(asString("x")).toBe("x");
+    expect(asString(5)).toBe("");
+    expect(asString(undefined)).toBe("");
+  });
+});
+
+describe("toTerminalDimension", () => {
+  it("accepts sane values", () => {
+    expect(toTerminalDimension(80)).toBe(80);
+    expect(toTerminalDimension("120")).toBe(120);
+    expect(toTerminalDimension(24.7)).toBe(24);
+  });
+
+  it("rejects values that would poison setWindow", () => {
+    for (const bad of [0, -1, NaN, Infinity, null, undefined, "abc", {}]) {
+      expect(toTerminalDimension(bad)).toBe(0);
+    }
+  });
+
+  it("clamps absurdly large values", () => {
+    expect(toTerminalDimension(1e9)).toBe(10000);
+  });
+});
@@ -1,4 +1,4 @@
-import { Agent, ProxyAgent } from "undici";
+import { Agent, ProxyAgent, fetch as undiciFetch } from "undici";
 import type { Dispatcher } from "undici-types";

 const directAgent = new Agent({
@@ -39,3 +39,13 @@ export function getProxyAgent(targetUrl?: string): Dispatcher | undefined {
 export function getFetchDispatcher(targetUrl: string): Dispatcher {
  return getProxyAgent(targetUrl) ?? (directAgent as unknown as Dispatcher);
 }
+
+export function fetchWithProxy(
+  url: string,
+  init: RequestInit = {},
+): Promise<Response> {
+  return undiciFetch(url, {
+    ...init,
+    dispatcher: getFetchDispatcher(url),
+  });
+}
@@ -256,6 +256,10 @@ export function preparePrivateKeyForSSH2(
  return Buffer.from(cleanKey, "utf8");
 }

+export function isPrivateKeyPassphraseError(error: unknown): boolean {
+  return /passphrase/i.test(getErrorMessage(error, ""));
+}
+
 export function parseSSHKey(
  privateKeyData: string,
  passphrase?: string,
@@ -0,0 +1,76 @@
+import type { RawData } from "ws";
+
+// Cap on a single decoded text frame. Anything larger is almost certainly
+// abuse - the legitimate control messages here are tiny, and terminal input is
+// bounded by what a user can type or paste.
+const MAX_MESSAGE_BYTES = 1024 * 1024;
+
+export class WsMessageError extends Error {}
+
+function rawByteLength(raw: RawData): number {
+  if (Buffer.isBuffer(raw)) return raw.length;
+  if (Array.isArray(raw))
+    return raw.reduce((sum, part) => sum + part.length, 0);
+  if (raw instanceof ArrayBuffer) return raw.byteLength;
+  return 0;
+}
+
+/**
+ * Parse a WebSocket frame into a plain message object.
+ *
+ * Throws WsMessageError - never a TypeError - for anything malformed, so
+ * callers can reject the frame instead of the parse blowing up the handler.
+ * `JSON.parse` happily returns null, numbers and arrays, none of which are
+ * safe to destructure, so the shape is checked here rather than at each site.
+ */
+export function parseWsMessage(raw: RawData): {
+  type: string;
+  data: unknown;
+} {
+  if (rawByteLength(raw) > MAX_MESSAGE_BYTES) {
+    throw new WsMessageError("Message too large");
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw.toString());
+  } catch {
+    throw new WsMessageError("Invalid JSON");
+  }
+
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new WsMessageError("Message must be a JSON object");
+  }
+
+  const { type, data } = parsed as { type?: unknown; data?: unknown };
+  if (typeof type !== "string") {
+    throw new WsMessageError("Message type must be a string");
+  }
+
+  return { type, data };
+}
+
+/** Narrow unknown payload data to a plain object without throwing. */
+export function asObject(data: unknown): Record<string, unknown> {
+  return data !== null && typeof data === "object" && !Array.isArray(data)
+    ? (data as Record<string, unknown>)
+    : {};
+}
+
+/** Narrow unknown payload data to a string without throwing. */
+export function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Coerce a client-supplied terminal width/height to a sane integer.
+ * Returns 0 when the value is unusable, so callers can skip the resize
+ * rather than pass NaN or a negative into ssh2's setWindow.
+ */
+export function toTerminalDimension(value: unknown): number {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return 0;
+  const rounded = Math.floor(n);
+  if (rounded < 1) return 0;
+  return Math.min(rounded, 10000);
+}