pikasTech-unidesk/scripts/ssh-argv-guidance-contract-test.ts

import { PassThrough, Writable } from "node:stream";
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { sshHelp } from "./src/help";
import { runApplyPatchV2 } from "./src/apply-patch-v2";
import { providerTriageRecommendedCrossChecks } from "./src/provider-triage";
import { extractRemoteCliOptions, remoteSshFrontendPlanForTest } from "./src/remote";
import {
  formatSshFailureHint,
  formatSshRuntimeTimeoutHint,
  formatSshRuntimeTimingHint,
  parseSshArgs,
  parseSshInvocation,
  remoteApplyPatchSource,
  sshFailureHint,
  sshRuntimeTimeoutHint,
  sshRuntimeTimeoutMs,
  sshRuntimeTimingHint,
} from "./src/ssh";

type JsonRecord = Record<string, unknown>;

function assertCondition(condition: unknown, message: string, detail: unknown = {}): void {
  if (!condition) throw new Error(`${message}: ${JSON.stringify(detail)}`);
}

function assertThrows(fn: () => unknown, pattern: RegExp, message: string): void {
  try {
    fn();
  } catch (error) {
    const text = error instanceof Error ? error.message : String(error);
    assertCondition(pattern.test(text), message, { error: text });
    return;
  }
  throw new Error(`${message}: expected throw`);
}

function sha256Hex(value: string): string {
  return createHash("sha256").update(Buffer.from(value, "utf8")).digest("hex");
}

function decodeWinEncodedCommand(remoteCommand: string | null | undefined): string {
  const text = String(remoteCommand ?? "");
  const match = /'-EncodedCommand' '([^']+)'/u.exec(text);
  assertCondition(match !== null, "win command must use PowerShell -EncodedCommand", remoteCommand);
  return Buffer.from(match[1] ?? "", "base64").toString("utf16le");
}

function applyPatchFixture(args: string[], patch: string, files: Record<string, string>): { status: number | null; stdout: string; stderr: string; files: Record<string, string> } {
  const root = mkdtempSync(path.join(os.tmpdir(), "unidesk-apply-patch-contract-"));
  try {
    const helperPath = path.join(root, "apply_patch");
    writeFileSync(helperPath, remoteApplyPatchSource, "utf8");
    for (const [relativePath, content] of Object.entries(files)) {
      const target = path.join(root, relativePath);
      writeFileSync(target, content, "utf8");
    }
    const run = spawnSync("sh", [helperPath, ...args], {
      cwd: root,
      input: patch,
      encoding: "utf8",
    });
    const outputFiles: Record<string, string> = {};
    for (const relativePath of Object.keys(files)) {
      outputFiles[relativePath] = readFileSync(path.join(root, relativePath), "utf8");
    }
    return {
      status: run.status,
      stdout: run.stdout,
      stderr: run.stderr,
      files: outputFiles,
    };
  } finally {
    rmSync(root, { recursive: true, force: true });
  }
}

async function applyPatchV2FixtureAttempt(patch: string, files: Record<string, string>): Promise<{ stdout: string; files: Record<string, string>; commands: string[]; error: unknown | null }> {
  const state = new Map(Object.entries(files));
  const commands: string[] = [];
  const stdin = new PassThrough();
  stdin.end(patch);
  let stdout = "";
  const stdoutSink = new Writable({
    write(chunk, _encoding, callback) {
      stdout += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
      callback();
    },
  });
  let error: unknown | null = null;
  try {
    await runApplyPatchV2({
      stdin,
      stdout: stdoutSink,
      executor: {
        async run(command, input) {
          const operation = command[4] ?? "";
          const target = command[5] ?? "";
          commands.push([operation, ...command.slice(5)].join(" "));
          if (operation === "read") {
            if (!state.has(target)) return { exitCode: 1, stdout: "", stderr: `missing ${target}` };
            return { exitCode: 0, stdout: state.get(target) ?? "", stderr: "" };
          }
          if (operation === "write-b64-argv") {
            const expectedBytes = Number(command[6] ?? "-1");
            const expectedSha256 = command[7] ?? "";
            const content = Buffer.from(command.slice(8).join(""), "base64").toString("utf8");
            if (Buffer.byteLength(content, "utf8") !== expectedBytes || sha256Hex(content) !== expectedSha256) {
              return { exitCode: 23, stdout: "", stderr: "mock integrity mismatch" };
            }
            state.set(target, content);
            return { exitCode: 0, stdout: "", stderr: "" };
          }
          if (operation === "write-b64-stdin") {
            const expectedBytes = Number(command[6] ?? "-1");
            const expectedSha256 = command[7] ?? "";
            const content = Buffer.from(input ?? "", "base64").toString("utf8");
            if (Buffer.byteLength(content, "utf8") !== expectedBytes || sha256Hex(content) !== expectedSha256) {
              return { exitCode: 23, stdout: "", stderr: "mock integrity mismatch" };
            }
            state.set(target, content);
            return { exitCode: 0, stdout: "", stderr: "" };
          }
          if (operation === "delete") {
            state.delete(target);
            return { exitCode: 0, stdout: "", stderr: "" };
          }
          if (operation === "move") {
            state.set(command[6] ?? "", state.get(target) ?? "");
            state.delete(target);
            return { exitCode: 0, stdout: "", stderr: "" };
          }
          return { exitCode: 2, stdout: "", stderr: "bad op" };
        },
      },
    });
  } catch (caught) {
    error = caught;
  }
  return { stdout, files: Object.fromEntries(state), commands, error };
}

async function applyPatchV2ActualShellFixtureAttempt(
  patch: string,
  files: Record<string, string>,
  mutateInput?: (operation: string, input: string | undefined) => string | undefined,
): Promise<{ stdout: string; files: Record<string, string>; commands: string[]; error: unknown | null }> {
  const root = mkdtempSync(path.join(os.tmpdir(), "unidesk-apply-patch-v2-shell-"));
  const commands: string[] = [];
  const stdin = new PassThrough();
  stdin.end(patch);
  let stdout = "";
  const stdoutSink = new Writable({
    write(chunk, _encoding, callback) {
      stdout += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
      callback();
    },
  });
  try {
    for (const [relativePath, content] of Object.entries(files)) {
      const target = path.join(root, relativePath);
      mkdirSync(path.dirname(target), { recursive: true });
      writeFileSync(target, content, "utf8");
    }
    let error: unknown | null = null;
    try {
      await runApplyPatchV2({
        stdin,
        stdout: stdoutSink,
        executor: {
          async run(command, input) {
            const operation = command[4] ?? "";
            commands.push([operation, ...command.slice(5)].join(" "));
            const run = spawnSync(command[0] ?? "sh", command.slice(1), {
              cwd: root,
              input: mutateInput ? mutateInput(operation, input) : input,
              encoding: "utf8",
            });
            return {
              exitCode: run.status ?? 255,
              stdout: run.stdout,
              stderr: run.stderr,
            };
          },
        },
      });
    } catch (caught) {
      error = caught;
    }
    const outputFiles: Record<string, string> = {};
    for (const relativePath of Object.keys(files)) {
      outputFiles[relativePath] = readFileSync(path.join(root, relativePath), "utf8");
    }
    return { stdout, files: outputFiles, commands, error };
  } finally {
    rmSync(root, { recursive: true, force: true });
  }
}

async function applyPatchV2Fixture(patch: string, files: Record<string, string>): Promise<{ stdout: string; files: Record<string, string>; commands: string[] }> {
  const result = await applyPatchV2FixtureAttempt(patch, files);
  if (result.error !== null) throw result.error;
  return { stdout: result.stdout, files: result.files, commands: result.commands };
}

export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
  const argv = parseSshArgs(["argv", "true"]);
  assertCondition(argv.invocationKind === "argv", "argv subcommand must be classified as argv", argv);
  assertCondition(argv.remoteCommand === "'true'", "argv command must shell-quote each token", argv);
  assertCondition(argv.requiresStdin === false, "argv command must not require stdin", argv);
  assertCondition(sshFailureHint("D601", argv, 255, "kex_exchange_identification: Connection closed by remote host") === null, "argv failures must not produce ssh-like friction hint", argv);

  const shortcut = parseSshArgs(["pwd"]);
  assertCondition(shortcut.invocationKind === "argv", "safe command shortcuts must use argv quoting", shortcut);
  assertCondition(shortcut.remoteCommand === "'pwd'", "safe command shortcut should be shell-quoted", shortcut);

  const hostWorkspace = parseSshInvocation("D601:/home/ubuntu/workspace/hwlab-dev", ["pwd"]);
  assertCondition(hostWorkspace.route.plane === "host" && hostWorkspace.route.workspace === "/home/ubuntu/workspace/hwlab-dev", "host workspace route must parse provider:/absolute/path", hostWorkspace);
  assertCondition(hostWorkspace.parsed.remoteCommand === "'pwd'", "host workspace route must leave operation argv independent from location", hostWorkspace);

  const hostWorkspaceLongForm = parseSshInvocation("D601:host:/home/ubuntu/workspace/hwlab-dev", ["argv", "git", "status", "--short"]);
  assertCondition(hostWorkspaceLongForm.route.workspace === "/home/ubuntu/workspace/hwlab-dev", "host: workspace route must parse as the same location model", hostWorkspaceLongForm);
  assertCondition(hostWorkspaceLongForm.parsed.remoteCommand === "'git' 'status' '--short'", "host workspace argv operation must stay argv-quoted", hostWorkspaceLongForm);

  const winCmd = parseSshInvocation("D601:win", ["cmd", "ver"]);
  assertCondition(winCmd.route.plane === "win" && winCmd.route.workspace === null, "win route must parse as the Windows cmd plane", winCmd);
  const winCmdScript = decodeWinEncodedCommand(winCmd.parsed.remoteCommand);
  assertCondition(
    String(winCmd.parsed.remoteCommand).startsWith("'/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe'")
      && winCmdScript.includes("C:\\Windows\\System32\\cmd.exe")
      && winCmdScript.includes("chcp 65001>nul")
      && winCmdScript.includes('set "PYTHONUTF8=1"')
      && winCmdScript.includes('set "PYTHONIOENCODING=utf-8"'),
    "win route must execute cmd.exe through a UTF-8 Windows launcher without trailing-space cmd set values",
    { winCmd, winCmdScript },
  );

  const winCmdCwd = parseSshInvocation("D601:win/c/test", ["cmd", "echo", "中文"]);
  assertCondition(winCmdCwd.route.plane === "win" && winCmdCwd.route.workspace === String.raw`C:\test`, "win route slash workspace must map to a Windows drive cwd", winCmdCwd);
  const winCmdCwdScript = decodeWinEncodedCommand(winCmdCwd.parsed.remoteCommand);
  assertCondition(winCmdCwdScript.includes('cd /d "C:\\test"') && winCmdCwdScript.includes("echo 中文"), "win route workspace must cd in Windows cmd before running the command", { winCmdCwd, winCmdCwdScript });

  const winSkills = parseSshInvocation("D601:win", ["skills", "--scope", "all", "--limit", "20"]);
  assertCondition(winSkills.route.plane === "win" && winSkills.parsed.invocationKind === "helper", "win skills route must be a Windows helper operation", winSkills);
  const winSkillsScript = decodeWinEncodedCommand(winSkills.parsed.remoteCommand);
  assertCondition(winSkillsScript.includes(".agents\\skills") && winSkillsScript.includes(".codex\\skills") && winSkillsScript.includes("$limit = 20") && winSkillsScript.includes("ConvertTo-Json"), "win skills must discover Windows user skill roots as JSON", { winSkills, winSkillsScript });

  assertThrows(
    () => parseSshInvocation("D601:win32", ["cmd", "ver"]),
    /use D601:win/u,
    "win32 route spelling must be rejected in favor of win",
  );

  const script = parseSshArgs(["script", "--shell", "bash", "--", "alpha beta"]);
  assertCondition(script.invocationKind === "helper", "script stdin helper must be classified as helper", script);
  assertCondition(script.remoteCommand === "'bash' '-s' '--' 'alpha beta'", "script helper must pass stdin to shell directly", script);
  assertCondition(script.requiresStdin === true, "script helper must require stdin", script);

  const directScriptCommand = parseSshArgs(["script", "--", "sed", "-n", "1,2p", "file.txt"]);
  assertCondition(directScriptCommand.invocationKind === "argv", "script -- command form must run as direct argv without stdin", directScriptCommand);
  assertCondition(directScriptCommand.remoteCommand === "'sed' '-n' '1,2p' 'file.txt'", "script -- command form must preserve dash-prefixed command args", directScriptCommand);
  assertCondition(directScriptCommand.requiresStdin === false, "script -- command form must not wait for stdin", directScriptCommand);

  const directScriptOneLiner = parseSshArgs(["script", "--", "cd /root/hwlab && git status --short --branch"]);
  assertCondition(directScriptOneLiner.invocationKind === "helper", "script -- single-string command should run through a remote shell", directScriptOneLiner);
  assertCondition(directScriptOneLiner.remoteCommand === "'sh' '-c' 'cd /root/hwlab && git status --short --branch'", "script -- single-string command should match the intuitive remote shell one-liner form", directScriptOneLiner);
  assertCondition(directScriptOneLiner.requiresStdin === false, "script -- single-string command should not wait for stdin", directScriptOneLiner);

  const shellOneLiner = parseSshArgs(["shell", "sed -n '1,2p' a && sed -n '1,2p' b"]);
  assertCondition(shellOneLiner.invocationKind === "helper", "shell one-liner must be a helper operation", shellOneLiner);
  assertCondition(shellOneLiner.remoteCommand === "'sh' '-c' 'sed -n '\\''1,2p'\\'' a && sed -n '\\''1,2p'\\'' b'", "shell one-liner must keep command operators inside the remote shell", shellOneLiner);
  assertCondition(shellOneLiner.requiresStdin === false, "shell one-liner must not require stdin", shellOneLiner);

  const k3sGuard = parseSshInvocation("D601:k3s", ["guard"]).parsed;
  assertCondition(k3sGuard.invocationKind === "helper", "k3s guard must be classified as helper", k3sGuard);
  assertCondition(k3sGuard.remoteCommand?.includes("KUBECONFIG") && k3sGuard.remoteCommand.includes("/etc/rancher/k3s/k3s.yaml"), "k3s guard must force native k3s kubeconfig", k3sGuard);

  const k3sExec = parseSshInvocation("D601:k3s", ["exec", "--namespace", "hwlab-dev", "--deployment", "hwlab-cloud-api", "--", "node", "-e", "console.log(process.version)"]).parsed;
  assertCondition(k3sExec.invocationKind === "helper", "k3s exec must be classified as helper", k3sExec);
  assertCondition(k3sExec.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'node' '-e' 'console.log(process.version)'", "k3s exec must assemble kubectl argv without nested shell quoting", k3sExec);

  const routeKubectl = parseSshInvocation("D601:k3s", ["kubectl", "get", "pods", "-n", "hwlab-dev"]);
  assertCondition(routeKubectl.providerId === "D601", "route must preserve provider id", routeKubectl);
  assertCondition(routeKubectl.route.plane === "k3s" && routeKubectl.route.entry === null, "route must keep kubectl as an operation, not as a route entry", routeKubectl);
  assertCondition(routeKubectl.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'get' 'pods' '-n' 'hwlab-dev'", "D601:k3s kubectl must map to kubectl argv", routeKubectl);

  const routeK3sShell = parseSshInvocation("D601:k3s", ["shell", "kubectl get nodes && kubectl get pods -A"]);
  assertCondition(routeK3sShell.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'sh' '-c' 'kubectl get nodes && kubectl get pods -A'", "D601:k3s shell must run one-line shell logic on the k3s host with native kubeconfig", routeK3sShell);

  const g14Guard = parseSshInvocation("G14:k3s", []);
  assertCondition(g14Guard.providerId === "G14" && g14Guard.route.plane === "k3s", "G14:k3s must parse as a native k3s route", g14Guard);
  assertCondition(g14Guard.parsed.remoteCommand?.includes("UNIDESK_K3S_PROVIDER_ID") && g14Guard.parsed.remoteCommand.includes("ubuntu-rog-zephyrus-g14-ga401iv-ga401iv"), "G14:k3s guard must use the G14 node profile", g14Guard);

  assertThrows(
    () => parseSshInvocation("G14", ["k3s", "kubectl", "get", "nodes"]),
    /unsupported.*ssh G14:k3s/u,
    "k3s must be a route plane, not a post-provider shorthand",
  );

  const routeTarget = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api", ["node", "-e", "console.log(process.version)"]);
  assertCondition(routeTarget.route.namespace === "hwlab-dev" && routeTarget.route.resource === "hwlab-cloud-api", "route target must parse namespace and workload", routeTarget);
  assertCondition(routeTarget.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'node' '-e' 'console.log(process.version)'", "D601:k3s:<namespace>:<workload> must default to deployment exec", routeTarget);

  const routeTargetArgv = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api", ["argv", "sh", "-c", "printf ok"]);
  assertCondition(routeTargetArgv.parsed.invocationKind === "argv", "k3s target argv operation must stay explicit argv", routeTargetArgv);
  assertCondition(routeTargetArgv.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'sh' '-c' 'printf ok'", "D601:k3s:<namespace>:<workload> argv must exec the argv payload instead of treating argv as a pod command", routeTargetArgv);

  const routeTargetShell = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["shell", "pwd && ls"]);
  assertCondition(routeTargetShell.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'sh' '-c' 'cd \"$1\" || exit; shift; exec \"$@\"' 'unidesk-cwd' '/app' 'sh' '-c' 'pwd && ls'", "D601:k3s:<namespace>:<workload>/<workspace> shell must run shell logic after cd inside the pod", routeTargetShell);

  const routeScript = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api", ["script", "--shell", "bash", "--", "arg"]);
  assertCondition(routeScript.parsed.requiresStdin === true, "k3s script operation must stream local stdin", routeScript);
  assertCondition(routeScript.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-i' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'bash' '-s' '--' 'arg'", "D601:k3s:<namespace>:<workload> script must map stdin to shell -s", routeScript);

  const routeControlScript = parseSshInvocation("D601:k3s", ["script", "--shell", "bash", "--", "arg"]);
  assertCondition(routeControlScript.parsed.requiresStdin === true, "k3s control-plane script operation must stream local stdin", routeControlScript);
  assertCondition(routeControlScript.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'bash' '-s' '--' 'arg'", "D601:k3s script must inject native kubeconfig without manual export", routeControlScript);

  const topLevelScriptSeparator = extractRemoteCliOptions(["ssh", "D601:/tmp", "script", "--", "sed", "-n", "1,2p", "file.txt"]);
  assertCondition(JSON.stringify(topLevelScriptSeparator.args) === JSON.stringify(["ssh", "D601:/tmp", "script", "--", "sed", "-n", "1,2p", "file.txt"]), "top-level remote option parser must preserve command-local -- after the command starts", topLevelScriptSeparator);
  const topLevelScriptInvocation = parseSshInvocation(topLevelScriptSeparator.args[1] as string, topLevelScriptSeparator.args.slice(2));
  assertCondition(topLevelScriptInvocation.parsed.remoteCommand === "'sed' '-n' '1,2p' 'file.txt'", "script -- must allow argv such as sed -n to execute without being parsed as script options", topLevelScriptInvocation);
  assertCondition(topLevelScriptInvocation.parsed.requiresStdin === false, "script -- direct command must not require stdin after top-level parsing", topLevelScriptInvocation);

  const remoteOptionSeparator = extractRemoteCliOptions(["--main-server-ip", "74.48.78.17", "--", "ssh", "D601:/tmp", "script", "--", "sed", "-n", "1,2p", "file.txt"]);
  assertCondition(remoteOptionSeparator.host === "74.48.78.17", "global remote options before -- must still be parsed", remoteOptionSeparator);
  assertCondition(JSON.stringify(remoteOptionSeparator.args) === JSON.stringify(["ssh", "D601:/tmp", "script", "--", "sed", "-n", "1,2p", "file.txt"]), "global -- must not strip nested command separators", remoteOptionSeparator);

  const routeApplyPatch = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api", ["apply-patch"]);
  assertCondition(routeApplyPatch.parsed.requiresStdin === true && routeApplyPatch.parsed.remoteCommand === null, "k3s apply-patch operation must use the default v2 local engine", routeApplyPatch);

  const routeApplyPatchV1 = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api", ["apply-patch-v1"]);
  assertCondition(routeApplyPatchV1.parsed.requiresStdin === true, "k3s apply-patch-v1 operation must stream local patch stdin", routeApplyPatchV1);
  assertCondition(routeApplyPatchV1.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-i' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'sh' '-s' '--'", "D601:k3s:<namespace>:<workload> apply-patch-v1 must enter pod with stdin", routeApplyPatchV1);
  assertCondition(routeApplyPatchV1.parsed.stdinPrefix?.includes("apply_patch") && routeApplyPatchV1.parsed.stdinPrefix.includes("__UNIDESK_APPLY_PATCH_PAYLOAD__"), "k3s apply-patch-v1 operation must inject pod helper before patch stdin", routeApplyPatchV1);
  assertCondition(routeApplyPatchV1.parsed.stdinPrefix?.includes("#!/bin/sh"), "k3s apply-patch-v1 operation must inject the same sh helper used by host apply-patch-v1", routeApplyPatchV1);
  assertCondition(!routeApplyPatchV1.parsed.stdinPrefix?.includes("python3") && !routeApplyPatchV1.parsed.stdinPrefix?.includes("node "), "k3s apply-patch-v1 operation must use the sh-only pod helper", routeApplyPatchV1);
  assertCondition(routeApplyPatchV1.parsed.stdinSuffix === "\n__UNIDESK_APPLY_PATCH_PAYLOAD__\n", "k3s apply-patch-v1 operation must terminate patch heredoc", routeApplyPatchV1);

  const hostApplyPatchLoose = parseSshArgs(["apply-patch-v1", "--allow-loose"]);
  assertCondition(hostApplyPatchLoose.remoteCommand === "'apply_patch' '--allow-loose'", "host apply-patch-v1 must pass --allow-loose as an explicit helper argument", hostApplyPatchLoose);
  assertCondition(hostApplyPatchLoose.requiredHelpers?.length === 1 && hostApplyPatchLoose.requiredHelpers.includes("apply_patch"), "host apply-patch-v1 must request only the apply_patch helper bootstrap", hostApplyPatchLoose);
  assertCondition(remoteApplyPatchSource.includes("replace_once_with_perl") && remoteApplyPatchSource.includes("perl -0777"), "apply_patch helper must keep a fast path for large files", {});

  const hostApplyPatchV2 = parseSshArgs(["apply-patch"]);
  assertCondition(hostApplyPatchV2.requiresStdin === true && hostApplyPatchV2.requiredHelpers === undefined && hostApplyPatchV2.remoteCommand === null, "host apply-patch must be a local v2 engine operation, not a remote helper bootstrap", hostApplyPatchV2);
  const hostApplyPatchV2Help = parseSshArgs(["apply-patch", "--help"]);
  assertCondition(hostApplyPatchV2Help.requiresStdin === false && hostApplyPatchV2Help.remoteCommand === null, "host apply-patch --help must not wait for patch stdin", hostApplyPatchV2Help);
  const podApplyPatchV2 = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["apply-patch"]);
  assertCondition(podApplyPatchV2.parsed.requiresStdin === true && podApplyPatchV2.parsed.remoteCommand === null, "pod apply-patch must be handled by the local v2 engine instead of injecting the legacy helper", podApplyPatchV2);
  assertThrows(() => parseSshArgs(["v2"]), /remote patch entrypoints/u, "v2 must not remain as an independent patch subcommand");
  assertThrows(() => parseSshArgs(["patch"]), /remote patch entrypoints/u, "patch must not remain as a patch alias");
  assertThrows(() => parseSshArgs(["patch-v1"]), /remote patch entrypoints/u, "patch-v1 must not remain as a legacy patch alias");

  const longChinesePatch = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: story.md",
    "@@",
    "+这是一个很长很长的中文段落，用来证明远端 v2 不再依赖 shell hunk 拼接和手写长中文 search block。它只是通过本地行级 patch engine 计算新内容，然后把完整文件写回远端，所以中文、标点、长句都不应该影响 patch 解析和匹配。",
    "*** End Patch",
    "",
  ].join("\n"), {
    "story.md": "开头\n",
  });
  assertCondition(longChinesePatch.files["story.md"]?.includes("很长很长的中文段落"), "v2 should accept pure insertion with long Chinese text", longChinesePatch);
  assertCondition(longChinesePatch.stdout.includes("Success. Updated the following files:"), "v2 must print visible success output", longChinesePatch);

  const lowContextV1Baseline = applyPatchFixture([], [
    "*** Begin Patch",
    "*** Update File: story.md",
    "@@",
    " 开头",
    "+低上下文纯插入在 v1 会失败，但 v2 应该按 Codex 行级语义允许。",
    "*** End Patch",
    "",
  ].join("\n"), {
    "story.md": "开头\n结尾\n",
  });
  assertCondition(lowContextV1Baseline.status !== 0 && lowContextV1Baseline.stderr.includes("insert-only without both leading and trailing context"), "v1 baseline should reject low-context pure insertion", lowContextV1Baseline);
  const lowContextV2 = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: story.md",
    "@@",
    " 开头",
    "+低上下文纯插入在 v1 会失败，但 v2 应该按 Codex 行级语义允许。",
    "*** End Patch",
    "",
  ].join("\n"), {
    "story.md": "开头\n结尾\n",
  });
  assertCondition(lowContextV2.files["story.md"]?.includes("v2 应该按 Codex 行级语义允许"), "v2 should fix v1 low-context insertion friction", lowContextV2);
  assertCondition(lowContextV2.commands.some((command) => command.includes("write-b64-argv")), "v2 should use argv write path for small remote files to work inside k3s pod exec capture", lowContextV2);

  const unicodePunctuationV1Baseline = applyPatchFixture([], [
    "*** Begin Patch",
    "*** Update File: notes.txt",
    "@@",
    "-alpha - beta",
    "+alpha - gamma",
    "*** End Patch",
    "",
  ].join("\n"), {
    "notes.txt": "alpha – beta\n",
  });
  assertCondition(unicodePunctuationV1Baseline.status !== 0, "v1 baseline should miss ASCII dash against typographic dash", unicodePunctuationV1Baseline);
  const unicodePunctuationV2 = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: notes.txt",
    "@@",
    "-alpha - beta",
    "+alpha - gamma",
    "*** End Patch",
    "",
  ].join("\n"), {
    "notes.txt": "alpha – beta\n",
  });
  assertCondition(unicodePunctuationV2.files["notes.txt"] === "alpha - gamma\n", "v2 should normalize common Unicode punctuation while matching expected lines", unicodePunctuationV2);

  const repeatedBlockWithContext = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: repeated.txt",
    "@@ section two",
    "-marker",
    "+patched",
    "*** End Patch",
    "",
  ].join("\n"), {
    "repeated.txt": "section one\nmarker\nsection two\nmarker\n",
  });
  assertCondition(repeatedBlockWithContext.files["repeated.txt"] === "section one\nmarker\nsection two\npatched\n", "v2 should use @@ context to target repeated blocks", repeatedBlockWithContext);

  const longChineseReplace = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: novel.md",
    "@@",
    "-林深在透明的舷窗前停下脚步，远处的群星像被压进黑色玻璃里的碎银，安静得让人怀疑整个宇宙都屏住了呼吸。",
    "+林深在透明的舷窗前停下脚步，远处的群星像被压进黑色玻璃里的碎银，安静得让人怀疑整个宇宙正在等待他重新命名。",
    "*** End Patch",
    "",
  ].join("\n"), {
    "novel.md": "林深在透明的舷窗前停下脚步，远处的群星像被压进黑色玻璃里的碎银，安静得让人怀疑整个宇宙都屏住了呼吸。\n",
  });
  assertCondition(longChineseReplace.files["novel.md"]?.includes("等待他重新命名"), "v2 should replace long Chinese lines without remote shell search blocks", longChineseReplace);

  const largeV2 = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: large.txt",
    "@@",
    "+large insert",
    "*** End Patch",
    "",
  ].join("\n"), {
    "large.txt": `${"0123456789abcdef\n".repeat(4096)}`,
  });
  assertCondition(largeV2.commands.some((command) => command.includes("write-b64-stdin")), "v2 should use stdin write path for large remote files to avoid E2BIG", largeV2.commands);

  const multiChunkTailV2 = await applyPatchV2ActualShellFixtureAttempt([
    "*** Begin Patch",
    "*** Update File: two_chunks.txt",
    "@@",
    "-b",
    "+B",
    "@@",
    "-d",
    "+D",
    "*** End Patch",
    "",
  ].join("\n"), {
    "two_chunks.txt": "a\nb\nc\nd\ne\nf\n",
  });
  assertCondition(multiChunkTailV2.error === null, "v2 should apply explicit multi-chunk patches through the real shell writer", multiChunkTailV2);
  assertCondition(multiChunkTailV2.files["two_chunks.txt"] === "a\nB\nc\nD\ne\nf\n", "v2 must preserve untouched tail lines when applying multiple chunks", multiChunkTailV2);

  const truncatedLargeWriteV2 = await applyPatchV2ActualShellFixtureAttempt([
    "*** Begin Patch",
    "*** Update File: large.txt",
    "@@",
    "+large insert that forces a rewritten full-file payload",
    "*** End Patch",
    "",
  ].join("\n"), {
    "large.txt": `${"0123456789abcdef\n".repeat(4096)}`,
  }, (operation, input) => {
    if (operation !== "write-b64-stdin" || input === undefined) return input;
    return input.slice(0, Math.max(0, input.length - 32));
  });
  assertCondition(truncatedLargeWriteV2.error !== null, "v2 should reject truncated stdin write payloads", truncatedLargeWriteV2);
  assertCondition(truncatedLargeWriteV2.files["large.txt"] === `${"0123456789abcdef\n".repeat(4096)}`, "v2 must keep the original file when decoded payload integrity fails", truncatedLargeWriteV2);
  assertCondition(
    String((truncatedLargeWriteV2.error as Error | null)?.message ?? "").includes("remote apply-patch v2 operation failed"),
    "v2 truncated payload failure should be visible to the caller",
    truncatedLargeWriteV2,
  );

  const failedCompoundV2 = await applyPatchV2FixtureAttempt([
    "*** Begin Patch",
    "*** Update File: first.txt",
    "@@",
    "-old first",
    "+new first",
    "*** Update File: second.txt",
    "@@",
    "-missing second",
    "+new second",
    "*** End Patch",
    "",
  ].join("\n"), {
    "first.txt": "old first\n",
    "second.txt": "old second\n",
  });
  assertCondition(failedCompoundV2.error !== null, "v2 compound patch should fail when a later hunk does not match", failedCompoundV2);
  assertCondition(failedCompoundV2.files["first.txt"] === "old first\n", "v2 must not partially write earlier files when a later hunk fails", failedCompoundV2);
  assertCondition(failedCompoundV2.files["second.txt"] === "old second\n", "v2 must leave later failed files unchanged", failedCompoundV2);
  assertCondition(!failedCompoundV2.commands.some((command) => command.startsWith("write-b64") || command.startsWith("delete")), "v2 must finish all local planning before any remote mutation", failedCompoundV2.commands);

  const sequentialCompoundV2 = await applyPatchV2Fixture([
    "*** Begin Patch",
    "*** Update File: sequence.txt",
    "@@",
    "-alpha",
    "+beta",
    "*** Update File: sequence.txt",
    "@@",
    "-beta",
    "+gamma",
    "*** End Patch",
    "",
  ].join("\n"), {
    "sequence.txt": "alpha\n",
  });
  assertCondition(sequentialCompoundV2.files["sequence.txt"] === "gamma\n", "v2 should plan later hunks against earlier planned edits before remote writes", sequentialCompoundV2);

  const safePatch = applyPatchFixture([], [
    "*** Begin Patch",
    "*** Update File: sample.txt",
    "@@",
    " function alpha() {",
    "   return 1;",
    " }",
    "+function inserted() {",
    "+  return 3;",
    "+}",
    " function beta() {",
    "   return 2;",
    " }",
    "*** End Patch",
    "",
  ].join("\n"), {
    "sample.txt": [
      "function alpha() {",
      "  return 1;",
      "}",
      "function beta() {",
      "  return 2;",
      "}",
      "",
    ].join("\n"),
  });
  assertCondition(safePatch.status === 0, "apply_patch sh helper should accept anchored insertions", safePatch);
  assertCondition(safePatch.stderr.includes("apply_patch: hunk 1 matched sample.txt:1"), "apply_patch sh helper must report matched file:line", safePatch);
  assertCondition(safePatch.files["sample.txt"]?.includes("function inserted()"), "apply_patch sh helper should apply anchored insertion", safePatch);

  const lowContextPatch = applyPatchFixture([], [
    "*** Begin Patch",
    "*** Update File: sample.txt",
    "@@",
    " function alpha() {",
    "   return 1;",
    " }",
    "+function misplaced() {",
    "+  return 9;",
    "+}",
    "*** End Patch",
    "",
  ].join("\n"), {
    "sample.txt": [
      "function alpha() {",
      "  return 1;",
      "}",
      "function beta() {",
      "  return 2;",
      "}",
      "",
    ].join("\n"),
  });
  assertCondition(lowContextPatch.status !== 0, "apply_patch sh helper should reject insert-only hunks without trailing context", lowContextPatch);
  assertCondition(lowContextPatch.stderr.includes("insert-only without both leading and trailing context"), "low-context rejection must explain the risk", lowContextPatch);

  const duplicateContextPatch = applyPatchFixture([], [
    "*** Begin Patch",
    "*** Update File: sample.txt",
    "@@",
    " marker",
    "+inserted",
    " x",
    "*** End Patch",
    "",
  ].join("\n"), {
    "sample.txt": "marker\nx\nmarker\nx\n",
  });
  assertCondition(duplicateContextPatch.status !== 0, "apply_patch sh helper should reject hunks whose context matches multiple locations", duplicateContextPatch);
  assertCondition(duplicateContextPatch.stderr.includes("matched multiple locations"), "duplicate context rejection must explain the risk", duplicateContextPatch);

  const reviewedLoosePatch = applyPatchFixture(["--allow-loose"], [
    "*** Begin Patch",
    "*** Update File: sample.txt",
    "@@",
    " marker",
    "+reviewed",
    " x",
    "*** End Patch",
    "",
  ].join("\n"), {
    "sample.txt": "marker\nx\nmarker\nx\n",
  });
  assertCondition(reviewedLoosePatch.status === 0, "--allow-loose should allow an explicitly reviewed ambiguous hunk", reviewedLoosePatch);
  assertCondition(reviewedLoosePatch.files["sample.txt"] === "marker\nreviewed\nx\nmarker\nx\n", "--allow-loose should still apply only one hunk", reviewedLoosePatch);

  assertThrows(
    () => parseSshInvocation("D601:k3s:kubectl", ["get", "pods"]),
    /route must locate a target only.*ssh D601:k3s kubectl/u,
    "operation names must not be accepted as k3s route segments",
  );
  assertThrows(
    () => parseSshInvocation("D601:k3s:hwlab-ci:kubectl", ["get", "pods"]),
    /route must locate a target only.*operation "kubectl" after the route/u,
    "operation names must not be accepted as nested k3s route segments",
  );
  assertThrows(
    () => parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api:logs", []),
    /route must locate a target only.*operation "logs" after the route/u,
    "operation names must not be accepted as k3s container route segments",
  );
  assertThrows(
    () => parseSshInvocation("D601:k3s:apply-patch:hwlab-dev:hwlab-cloud-api", []),
    /route must locate a target only.*apply-patch/u,
    "pod apply-patch must be an operation after the route",
  );

  const routePodTarget = parseSshInvocation("D601:k3s:hwlab-dev:pod/hwlab-cloud-api-abc:api", ["printenv", "HOSTNAME"]);
  assertCondition(routePodTarget.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'pod/hwlab-cloud-api-abc' '-c' 'api' '--' 'printenv' 'HOSTNAME'", "pod route with container must preserve explicit pod kind", routePodTarget);

  const routePodWorkspace = parseSshInvocation("D601:k3s:hwlab-dev:pod/hwlab-cloud-api-abc/workspace/app:api", ["pwd"]);
  assertCondition(routePodWorkspace.route.resource === "pod/hwlab-cloud-api-abc" && routePodWorkspace.route.container === "api" && routePodWorkspace.route.workspace === "/workspace/app", "pod route must support a workspace suffix after the pod id", routePodWorkspace);
  assertCondition(routePodWorkspace.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'hwlab-dev' 'pod/hwlab-cloud-api-abc' '-c' 'api' '--' 'sh' '-c' 'cd \"$1\" || exit; shift; exec \"$@\"' 'unidesk-cwd' '/workspace/app' 'pwd'", "pod workspace route must run commands through a fixed cwd wrapper", routePodWorkspace);

  const routeDeploymentWorkspaceScript = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["script"]);
  assertCondition(routeDeploymentWorkspaceScript.route.resource === "hwlab-cloud-api" && routeDeploymentWorkspaceScript.route.workspace === "/app", "deployment shorthand route must support workspace suffix", routeDeploymentWorkspaceScript);
  assertCondition(routeDeploymentWorkspaceScript.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-i' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'sh' '-c' 'cd \"$1\" || exit; shift; exec \"$@\"' 'unidesk-cwd' '/app' 'sh' '-s' '--'", "pod workspace script must set cwd before shell -s consumes stdin", routeDeploymentWorkspaceScript);

  const routeApplyPatchWorkspace = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["apply-patch"]);
  assertCondition(routeApplyPatchWorkspace.parsed.requiresStdin === true, "pod workspace apply-patch must still stream patch stdin", routeApplyPatchWorkspace);
  assertCondition(routeApplyPatchWorkspace.parsed.remoteCommand === null, "pod workspace apply-patch must use the default v2 local engine", routeApplyPatchWorkspace);

  const routeApplyPatchV1Workspace = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["apply-patch-v1"]);
  assertCondition(routeApplyPatchV1Workspace.parsed.requiresStdin === true, "pod workspace apply-patch-v1 must still stream patch stdin", routeApplyPatchV1Workspace);
  assertCondition(routeApplyPatchV1Workspace.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-i' '-n' 'hwlab-dev' 'deployment/hwlab-cloud-api' '--' 'sh' '-c' 'cd \"$1\" || exit; shift; exec \"$@\"' 'unidesk-cwd' '/app' 'sh' '-s' '--'", "pod workspace apply-patch-v1 must set cwd before injecting the sh helper", routeApplyPatchV1Workspace);

  const routeExecStdin = parseSshInvocation("D601:k3s:unidesk:code-queue/root/unidesk", ["exec", "--stdin", "--", "tar", "-xf", "-", "-C", "/root/unidesk"]);
  assertCondition(routeExecStdin.parsed.requiresStdin === true, "pod route exec --stdin must stream local stdin into kubectl exec", routeExecStdin);
  assertCondition(routeExecStdin.parsed.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'unidesk' 'deployment/code-queue' '-i' '--' 'sh' '-c' 'cd \"$1\" || exit; shift; exec \"$@\"' 'unidesk-cwd' '/root/unidesk' 'tar' '-xf' '-' '-C' '/root/unidesk'", "pod route exec --stdin must keep exec flags before -- and command argv after --", routeExecStdin);

  const sshLike = parseSshArgs(["echo hello"]);
  const hint = sshFailureHint("D601", sshLike, 255, "kex_exchange_identification: Connection closed by remote host");
  assertCondition(hint !== null, "ssh-like kex failure must produce a hint", sshLike);
  assertCondition(hint?.try === "bun scripts/cli.ts ssh D601 script <<'SCRIPT'", "hint must provide canonical stdin script retry", hint);
  assertCondition(hint?.triage.includes("provider triage D601"), "hint must provide provider triage command", hint);
  const formatted = formatSshFailureHint(hint!);
  assertCondition(formatted.startsWith("UNIDESK_SSH_HINT "), "formatted hint must have structured prefix", formatted);
  assertCondition(!formatted.includes("echo hello"), "formatted hint must not echo the original remote command", formatted);

  const timingInfo = sshRuntimeTimingHint({
    invocation: parseSshInvocation("D601:/home/ubuntu/workspace/hwlab-dev", ["argv", "true"]),
    transport: "backend-core-broker",
    exitCode: 0,
    startedAtMs: 1000,
    finishedAtMs: 5200,
    thresholdMs: 10_000,
  });
  assertCondition(timingInfo.level === "info" && timingInfo.slow === false, "short ssh operation should stay below the timing warning threshold", timingInfo);
  assertCondition(timingInfo.elapsedMs === 4200 && timingInfo.elapsedSeconds === 4.2, "timing hint must include elapsed ms and seconds", timingInfo);
  assertCondition(formatSshRuntimeTimingHint(timingInfo) === "", "short ssh operation must not write routine timing noise to stderr", timingInfo);
  const slowTiming = sshRuntimeTimingHint({
    invocation: parseSshInvocation("D601", ["apply-patch"]),
    transport: "frontend-websocket",
    exitCode: 0,
    startedAtMs: 0,
    finishedAtMs: 12_345,
    thresholdMs: 10_000,
  });
  assertCondition(slowTiming.level === "warning" && slowTiming.slow === true, "slow ssh operation should emit a warning timing hint", slowTiming);
  assertCondition(slowTiming.message.includes("above the 10s warning threshold"), "slow timing warning must explain the threshold", slowTiming);
  const formattedTiming = formatSshRuntimeTimingHint(slowTiming);
  assertCondition(formattedTiming.startsWith("UNIDESK_SSH_TIMING "), "formatted timing hint must have structured prefix", formattedTiming);
  assertCondition(formattedTiming.includes("\"exitCode\":0"), "slow successful ssh operation must still emit timing warning as a performance signal", formattedTiming);
  assertCondition(!formattedTiming.includes("apply_patch"), "timing hint must not echo the original remote command", formattedTiming);

  const timeoutHint = sshFailureHint("D601", sshLike, 255, "unidesk ssh bridge timed out waiting for provider session");
  assertCondition(timeoutHint?.trigger === "timeout-or-kex", "provider session timeout must map to timeout-or-kex", timeoutHint);
  assertCondition(sshRuntimeTimeoutMs({ UNIDESK_SSH_RUNTIME_TIMEOUT_MS: "120000" } as NodeJS.ProcessEnv) === 60_000, "ssh runtime timeout must cap at 60s", {});
  assertCondition(sshRuntimeTimeoutMs({ UNIDESK_TRAN_RUNTIME_TIMEOUT_MS: "2500" } as NodeJS.ProcessEnv) === 2500, "ssh runtime timeout must accept smaller explicit limits", {});
  const runtimeTimeout = sshRuntimeTimeoutHint({
    invocation: parseSshInvocation("G14:k3s", ["script"]),
    transport: "backend-core-broker",
    timeoutMs: 60_000,
  });
  const formattedRuntimeTimeout = formatSshRuntimeTimeoutHint(runtimeTimeout);
  assertCondition(formattedRuntimeTimeout.startsWith("UNIDESK_SSH_RUNTIME_TIMEOUT "), "runtime timeout hint must have structured prefix", formattedRuntimeTimeout);
  assertCondition(formattedRuntimeTimeout.includes("short query plus poll semantics"), "runtime timeout hint must point to short polling", formattedRuntimeTimeout);
  assertCondition(!formattedRuntimeTimeout.includes("kubectl"), "runtime timeout hint must not echo remote command text", formattedRuntimeTimeout);

  const helpText = JSON.stringify(sshHelp());
  assertCondition(helpText.includes("ssh <providerId> script [--shell sh|bash] [script-args...] <<'SCRIPT'"), "ssh help must recommend stdin script passthrough for shell scripts", helpText);
  assertCondition(helpText.includes("ssh <providerId> shell [--shell sh|bash]") && helpText.includes("outer shell operators written outside tran"), "ssh help must document one-line shell passthrough and the local operator boundary", helpText);
  assertCondition(helpText.includes("inherits provider proxy variables"), "ssh help must state default script inherits provider proxy env", helpText);
  assertCondition(helpText.includes("not as a proxy workaround"), "ssh help must reserve --shell bash for bash syntax instead of proxy workarounds", helpText);
  assertCondition(helpText.includes("ssh D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch"), "ssh help must document host workspace routes", helpText);
  assertCondition(helpText.includes("ssh D601:win cmd ver") && helpText.includes("ssh D601:win/c/test cmd cd") && helpText.includes("ssh D601:win skills"), "ssh help must document Windows cmd and skills win routes", helpText);
  assertCondition(helpText.includes("Use `win`, not `win32`") && helpText.includes("chcp 65001") && helpText.includes("PYTHONIOENCODING=utf-8"), "ssh help must document win route UTF-8 defaults and naming", helpText);
  assertCondition(helpText.includes("ssh D601:k3s kubectl get pods -n hwlab-dev"), "ssh help must document k3s kubectl operation", helpText);
  assertCondition(helpText.includes("ssh G14:k3s kubectl get pipelineruns -n hwlab-ci"), "ssh help must document G14 k3s route operation", helpText);
  assertCondition(helpText.includes("ssh D601:k3s:hwlab-dev:hwlab-cloud-api/app pwd"), "ssh help must document k3s pod workspace route", helpText);
  assertCondition(helpText.includes("ssh D601:k3s script <<'SCRIPT'"), "ssh help must document k3s control-plane script operation", helpText);
  assertCondition(helpText.includes("ssh D601:k3s:hwlab-dev:hwlab-cloud-api/app apply-patch <<'PATCH'"), "ssh help must document k3s pod apply-patch operation", helpText);
  assertCondition(helpText.includes("ssh D601:k3s:unidesk:code-queue/root/unidesk exec --stdin -- tar -xf - -C /root/unidesk"), "ssh help must document one-step stdin file streaming into pod exec", helpText);
  assertCondition(helpText.includes("apply-patch-v1 [--allow-loose]") && helpText.includes("low-context update hunks"), "ssh help must document apply-patch-v1 loose-context guard", helpText);
  assertCondition(helpText.includes("ssh D601:k3s:hwlab-dev:hwlab-cloud-api script <<'SCRIPT'"), "ssh help must document k3s script operation", helpText);
  assertCondition(helpText.includes("UNIDESK_SSH_HINT"), "ssh help must document structured failure hint", helpText);
  assertCondition(helpText.includes("UNIDESK_SSH_RUNTIME_TIMEOUT") && helpText.includes("UNIDESK_TRAN_TIMEOUT_HINT") && helpText.includes("60s") && helpText.includes("submit-and-poll"), "ssh help must document top-level runtime timeout and short polling discipline", helpText);
  assertCondition(helpText.includes("UNIDESK_SSH_TIMING") && helpText.includes("10s") && helpText.includes("slow successful calls are a distributed performance monitoring signal") && helpText.includes("Routine short calls do not emit timing noise"), "ssh help must document slow-only runtime timing hints", helpText);
  assertCondition(helpText.includes("must not add provider/plane directory locks") && helpText.includes("k8s/Tekton/Argo/Lease"), "ssh help must document tran's no-local-lock boundary", helpText);

  const crossChecks = providerTriageRecommendedCrossChecks("D601");
  assertCondition(crossChecks.includes("bun scripts/cli.ts ssh D601 argv true"), "provider triage cross-checks must keep argv true", crossChecks);

  const frontendRemoteK3sPlan = remoteSshFrontendPlanForTest("D601:k3s", ["kubectl", "get", "nodes", "-o", "name"]);
  assertCondition(frontendRemoteK3sPlan.transport === "frontend-websocket", "remote frontend ssh must use the streaming websocket bridge", frontendRemoteK3sPlan);
  assertCondition(frontendRemoteK3sPlan.providerId === "D601", "remote frontend ssh must dispatch route target to the provider id", frontendRemoteK3sPlan);
  assertCondition(frontendRemoteK3sPlan.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'get' 'nodes' '-o' 'name'", "remote frontend ssh must preserve k3s route command construction", frontendRemoteK3sPlan);
  assertCondition(!String(frontendRemoteK3sPlan.wrappedRemoteCommand ?? "").includes("UNIDESK_SSH_TOOL_DIR=/tmp/unidesk-ssh-tools"), "remote frontend ssh must not bootstrap helper tools for plain kubectl argv", frontendRemoteK3sPlan);

  const frontendRemoteHostPatchPlan = remoteSshFrontendPlanForTest("D601", ["apply-patch"]);
  assertCondition(frontendRemoteHostPatchPlan.requiresStdin === true && frontendRemoteHostPatchPlan.remoteCommand === null && !String(frontendRemoteHostPatchPlan.wrappedRemoteCommand ?? "").includes("UNIDESK_SSH_TOOL_DIR"), "frontend apply-patch plan must stay a local v2 engine operation and not bootstrap legacy helpers", frontendRemoteHostPatchPlan);

  const frontendRemoteV1Plan = remoteSshFrontendPlanForTest("D601:/tmp", ["apply-patch-v1"]);
  assertCondition(String(frontendRemoteV1Plan.wrappedRemoteCommand ?? "").includes("UNIDESK_SSH_TOOL_DIR=/tmp/unidesk-ssh-tools"), "frontend apply-patch-v1 must bootstrap the remote apply_patch helper", frontendRemoteV1Plan);
  assertCondition(String(frontendRemoteV1Plan.wrappedRemoteCommand ?? "").includes("/apply_patch") && !String(frontendRemoteV1Plan.wrappedRemoteCommand ?? "").includes("/glob") && !String(frontendRemoteV1Plan.wrappedRemoteCommand ?? "").includes("/skill-discover"), "frontend apply-patch-v1 must not bootstrap unrelated helper tools", frontendRemoteV1Plan);

  const frontendRemotePodArgvPlan = remoteSshFrontendPlanForTest("G14:k3s:unidesk:code-queue", ["argv", "sh", "-c", "command -v tran"]);
  assertCondition(frontendRemotePodArgvPlan.providerId === "G14", "remote frontend pod route must dispatch through G14 provider", frontendRemotePodArgvPlan);
  assertCondition(frontendRemotePodArgvPlan.remoteCommand === "'env' 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' 'kubectl' 'exec' '-n' 'unidesk' 'deployment/code-queue' '--' 'sh' '-c' 'command -v tran'", "remote frontend pod argv route must be fully assembled before dispatch", frontendRemotePodArgvPlan);

  const frontendRemoteWorkspacePlan = remoteSshFrontendPlanForTest("D601:/home/ubuntu/workspace/hwlab-dev", ["git", "status", "--short"]);
  assertCondition(frontendRemoteWorkspacePlan.payloadCwd === "/home/ubuntu/workspace/hwlab-dev", "remote frontend host workspace route must pass cwd to host.ssh payload", frontendRemoteWorkspacePlan);
  assertCondition(frontendRemoteWorkspacePlan.remoteCommand === "'git' 'status' '--short'", "remote frontend host workspace route must keep command argv-quoted", frontendRemoteWorkspacePlan);

  const frontendRemoteWinPlan = remoteSshFrontendPlanForTest("D601:win/c/test", ["cmd", "cd"]);
  assertCondition(frontendRemoteWinPlan.providerId === "D601" && frontendRemoteWinPlan.payloadCwd === "/mnt/c/Windows", "remote frontend win route must dispatch through provider host.ssh from a Windows-mounted cwd", frontendRemoteWinPlan);
  const frontendRemoteWinScript = decodeWinEncodedCommand(String(frontendRemoteWinPlan.remoteCommand));
  assertCondition(frontendRemoteWinScript.includes("cmd.exe") && frontendRemoteWinScript.includes("cd /d \"C:\\test\""), "remote frontend win route must assemble Windows cmd cwd internally", { frontendRemoteWinPlan, frontendRemoteWinScript });

  const tranScript = readFileSync(new URL("./tran", import.meta.url), "utf8");
  assertCondition(tranScript.includes("CODE_QUEUE_DEV_CONTAINER_MASTER_HOST") && tranScript.includes("--main-server-ip"), "tran wrapper must auto-select frontend transport inside Code Queue runner pods", tranScript);
  assertCondition(tranScript.includes("UNIDESK_TRAN_LOCAL"), "tran wrapper must keep an explicit local override for diagnostics", tranScript);
  assertCondition(!tranScript.includes("tran_lock_scope") && !tranScript.includes("UNIDESK_TRAN_LOCK_DIR") && !tranScript.includes("mkdir \"$lock_path\""), "tran wrapper must not add local provider/plane directory locks", tranScript);

  const remoteSource = readFileSync(new URL("./src/remote.ts", import.meta.url), "utf8");
  assertCondition(remoteSource.includes("UNIDESK_REMOTE_HTTP_CLIENT") && remoteSource.includes("isCodeQueueRunnerEnv(env) ? \"curl\" : \"fetch\""), "remote frontend transport must default to curl HTTP in Code Queue runner environments", remoteSource);
  assertCondition(remoteSource.includes("frontendSshWebSocketUrl") && remoteSource.includes("runRemoteSshWebSocket"), "remote frontend ssh must go through the streaming websocket implementation", remoteSource);
  assertCondition(!remoteSource.includes("remote frontend transport does not stream stdin"), "remote frontend ssh must not reject stdin-backed helpers", remoteSource);
  assertCondition(!remoteSource.includes("source: \"cli-remote-ssh\""), "remote frontend ssh must not use host.ssh dispatch task polling", remoteSource);

  const frontendSource = readFileSync(new URL("../src/components/frontend/src/index.ts", import.meta.url), "utf8");
  assertCondition(frontendSource.includes('url.pathname === "/ws/ssh"') && frontendSource.includes("proxySshWebSocket"), "frontend must expose an authenticated /ws/ssh proxy", frontendSource);
  assertCondition(frontendSource.includes("coreSshWebSocketUrl") && frontendSource.includes('url.searchParams.set("token"'), "frontend /ws/ssh proxy must connect to backend-core ssh bridge with the provider token", frontendSource);
  assertCondition(frontendSource.includes("PROVIDER_TOKEN_FILE") && frontendSource.includes("/run/secrets/unidesk_provider_token"), "frontend ssh proxy must support file-based provider token injection for runtime hotfix and secret mounts", frontendSource);

  const composeSource = readFileSync(new URL("../docker-compose.yml", import.meta.url), "utf8");
  assertCondition(composeSource.includes('PROVIDER_TOKEN: "${UNIDESK_PROVIDER_TOKEN}"'), "frontend compose service must receive provider token for the ssh proxy", composeSource);

  const devCoreManifest = readFileSync(new URL("../src/components/microservices/k3sctl-adapter/k3s/dev/unidesk-dev-core.k8s.yaml", import.meta.url), "utf8");
  assertCondition(devCoreManifest.includes("name: frontend-dev") && devCoreManifest.includes("name: PROVIDER_TOKEN"), "dev frontend manifest must receive provider token for the ssh proxy", devCoreManifest);

  const codeQueueDockerfile = readFileSync(new URL("../src/components/microservices/code-queue/Dockerfile", import.meta.url), "utf8");
  assertCondition(codeQueueDockerfile.includes("COPY scripts/tran /usr/local/bin/tran") && codeQueueDockerfile.includes("chmod 755 /usr/local/bin/tran"), "Code Queue runner image must install tran on PATH", codeQueueDockerfile);

  return {
    ok: true,
    checks: [
      "argv form is classified and quoted as the success path for non-interactive commands",
      "stdin script form removes shell-command strings for host and k3s workload scripts",
      "script -- single-string runs as a remote shell one-liner while multi-token form keeps dash-prefixed argv",
      "pod apply-patch operation uses the v2 local engine and apply-patch-v1 injects the legacy helper",
      "pod exec --stdin streams arbitrary local stdin through workload routes without shell wrapping",
      "apply-patch-v1 uses one sh helper for host and pod paths and rejects low-context hunks unless --allow-loose is explicit",
      "legacy operation-in-route forms are rejected in any k3s route segment with canonical route-plus-operation guidance",
      "post-provider k3s shorthand is rejected so location and operation stay separated",
      "k3s route stays location-only while operations fix native kubeconfig and assemble kubectl exec as argv",
      "win route runs Windows cmd.exe with UTF-8 defaults and slash cwd syntax such as D601:win/c/test",
      "win skills discovers the current Windows user's skill roots without hand-written cmd dir or PowerShell",
      "top-level remote option parsing preserves command-local -- separators for script -- sed -n style commands",
      "ssh-like timeout/kex failures emit one structured argv retry hint",
      "ssh runtime emits structured timing for slow operations over 10 seconds, including successful slow calls",
      "help text documents stdin script passthrough and UNIDESK_SSH_HINT",
      "provider triage recommendedCrossChecks keeps ssh D601 argv true",
      "remote frontend ssh uses the same structured route parser for host, k3s and pod argv routes",
      "ssh helper bootstrap is lazy so plain argv/script commands do not transfer helper sources",
      "host apply-patch-v1 bootstraps only the apply_patch helper and uses a Perl fast path for large files",
      "remote frontend ssh uses authenticated /ws/ssh streaming instead of host.ssh dispatch task polling",
      "Code Queue runner image installs the tran wrapper and runner tran auto-selects remote frontend transport",
      "tran does not add local provider/plane directory locks and leaves coordination to k8s/Tekton/Argo/Lease",
      "Code Queue runner remote frontend HTTP uses curl by default for non-ssh API calls to avoid Bun response-body native crashes",
    ],
  };
}

if (import.meta.main) {
  const result = await runSshArgvGuidanceContract();
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}