fix: make apply-patch default to v2

scripts/src/apply-patch-v2.ts

@@ -75,18 +75,18 @@ export function isApplyPatchV2HelpArgs(args: string[] = []): boolean {
 export function applyPatchV2HelpPayload() {
   return {
     ok: true,
-    command: "ssh <route> v2 < patch.diff",
+    command: "ssh <route> apply-patch < patch.diff",
     summary: "Apply a standard apply_patch patch to a remote route with the local v2 line-based engine.",
     usage: [
-      "tran G14:/root/hwlab/.worktree/task v2 < patch.diff",
-      "bun scripts/cli.ts ssh D601:/tmp v2 < patch.diff"
+      "tran G14:/root/hwlab/.worktree/task apply-patch < patch.diff",
+      "bun scripts/cli.ts ssh D601:/tmp apply-patch < patch.diff"
     ],
     input: {
       required: true,
       firstLine: beginMarker,
       lastLine: endMarker
     },
-    note: "v2 reads patch text from stdin. Use `script -- ...` for ordinary remote shell commands."
+    note: "apply-patch reads patch text from stdin and uses the v2 engine by default. Use `apply-patch-v1` only for the legacy helper."
   };
 }
 
@@ -167,13 +167,25 @@ export async function runApplyPatchV2(options: ApplyPatchV2Options): Promise<num
     options.stdout.write(`${JSON.stringify(applyPatchV2HelpPayload(), null, 2)}\n`);
     return 0;
   }
+  if ((options.argv?.length ?? 0) > 0) {
+    options.stdout.write(`${JSON.stringify({
+      ok: false,
+      error: {
+        code: "apply_patch_unsupported_args",
+        message: "ssh apply-patch uses the v2 engine and accepts no helper flags. Use apply-patch-v1 for legacy helper options."
+      },
+      unsupportedArgs: options.argv,
+      help: applyPatchV2HelpPayload()
+    }, null, 2)}\n`);
+    return 2;
+  }
   const patchText = await readStreamText(options.stdin);
   if (!patchText.trim()) {
     options.stdout.write(`${JSON.stringify({
       ok: false,
       error: {
-        code: "v2_patch_stdin_required",
-        message: "ssh v2 requires patch text on stdin."
+        code: "apply_patch_stdin_required",
+        message: "ssh apply-patch requires patch text on stdin."
       },
       help: applyPatchV2HelpPayload()
     }, null, 2)}\n`);

scripts/src/help.ts

@@ -20,15 +20,15 @@ export function rootHelp(): unknown {
       { command: "server rebuild <backend-core|frontend|dev-frontend-proxy|provider-gateway|todo-note|code-queue-mgr|project-manager|baidu-netdisk|oa-event-flow>", description: "Maintenance-only local Compose rebuild for reviewed main-server services; frontend standard release must use CI artifact plus deploy apply dev/prod artifact consumers." },
       { command: "provider attach <providerId> [--master-server URL] [--up] [--force] | provider triage <providerId> [--observed-error text] [--observed-scope scope] [--microservice id ...] [--full|--raw]", description: "Generate the minimal external provider-gateway env/compose bundle or run the low-noise read-only provider health triage contract." },
       { command: "ssh <route> [operation args...]", description: "Open a Host SSH / WSL SSH maintenance session through the provider-gateway bridge; route syntax such as `G14:k3s` or `D601:win/c/test` only locates distributed targets." },
-      { command: "ssh <route> v2 < patch.diff", description: "Preferred remote text patch entry: apply a standard patch with the local TypeScript v2 engine while the remote route only reads and writes files." },
-      { command: "ssh <providerId> apply-patch [tool args...] < patch.diff", description: "Fallback to the injected remote apply_patch helper directly over SSH passthrough and stream the patch from local stdin." },
+      { command: "ssh <route> apply-patch < patch.diff", description: "Default remote text patch entry: apply a standard patch with the local TypeScript v2 engine while the remote route only reads and writes files." },
+      { command: "ssh <providerId> apply-patch-v1 [tool args...] < patch.diff", description: "Fallback to the injected legacy remote apply_patch helper directly over SSH passthrough and stream the patch from local stdin." },
       { command: "ssh <providerId> py [script-args...] < script.py", description: "Run remote Python from local stdin through SSH passthrough without nested shell quoting; extra args become script argv." },
       { command: "ssh <providerId> script [--shell sh|bash] [script-args...] <<'SCRIPT' ...", description: "Run a remote shell script from local stdin using shell -s; the default sh inherits provider proxy env, so --shell bash is only for bash-specific syntax." },
       { command: "ssh <providerId> skills [--scope all|wsl|windows] [--limit N]", description: "Discover WSL/Linux and, for WSL providers, Windows skill directories in one SSH passthrough call." },
       { command: "ssh <providerId> find <path...> [--max-depth N] [--type d|f|l] [--contains TEXT] [--iname PATTERN] [--limit N] [--sort]", description: "Run a structured remote find command without nested shell quoting or parentheses." },
       { command: "ssh <providerId> glob [--root DIR] [--pattern PATTERN] [--contains TEXT] [--type any|f|d] [--limit N] [--sort]", description: "Run remote glob matching through the injected helper without shell glob expansion." },
       { command: "ssh <providerId>:/absolute/workspace <operation args...>", description: "Route directly into a host workspace while keeping the operation parser independent from the location." },
-      { command: "ssh <providerId>:k3s[:namespace:workload[:container]] <kubectl|logs|exec|script|v2|apply-patch|command> ...", description: "Locate a native k3s control plane or workload with route syntax, then run a separate operation with KUBECONFIG fixed and argv assembled by the CLI." },
+      { command: "ssh <providerId>:k3s[:namespace:workload[:container]] <kubectl|logs|exec|script|apply-patch|apply-patch-v1|command> ...", description: "Locate a native k3s control plane or workload with route syntax, then run a separate operation with KUBECONFIG fixed and argv assembled by the CLI." },
       { command: "ssh <providerId> argv <command> [args...]", description: "Run a non-interactive remote command with each argv token shell-quoted by UniDesk before SSH passthrough; use `ssh <providerId> script` when shell features are required." },
       { command: "microservice list", description: "List UniDesk-managed user services and their provider/runtime mapping." },
       { command: "microservice status <id>", description: "Show one user service config, repository reference, backend mapping, and runtime status." },
@@ -149,8 +149,8 @@ export function sshHelp(): unknown {
     usage: [
       "bun scripts/cli.ts ssh <route>",
       "bun scripts/cli.ts ssh <providerId> argv <command> [args...]",
-      "bun scripts/cli.ts ssh <providerId>:/absolute/workspace v2 < patch.diff",
-      "bun scripts/cli.ts ssh <providerId> apply-patch [--allow-loose] < patch.diff",
+      "bun scripts/cli.ts ssh <providerId>:/absolute/workspace apply-patch < patch.diff",
+      "bun scripts/cli.ts ssh <providerId> apply-patch-v1 [--allow-loose] < patch.diff",
       "bun scripts/cli.ts ssh <providerId> py [script-args...] < script.py",
       "bun scripts/cli.ts ssh <providerId> script [--shell sh|bash] [script-args...] <<'SCRIPT'",
       "bun scripts/cli.ts ssh <providerId> shell [--shell sh|bash] \"sed -n '1,20p' a && sed -n '1,20p' b\"",
@@ -167,8 +167,8 @@ export function sshHelp(): unknown {
       "bun scripts/cli.ts ssh G14:k3s kubectl get pipelineruns -n hwlab-ci",
       "bun scripts/cli.ts ssh D601:k3s script <<'SCRIPT'",
       "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api/app pwd",
-      "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api/app v2 <<'PATCH'",
-      "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api apply-patch <<'PATCH'",
+      "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api/app apply-patch <<'PATCH'",
+      "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api apply-patch-v1 <<'PATCH'",
       "tar -C /path/to/files -cf - . | bun scripts/cli.ts ssh D601:k3s:unidesk:code-queue/root/unidesk exec --stdin -- tar -xf - -C /root/unidesk",
       "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api node -e 'console.log(process.version)'",
       "bun scripts/cli.ts ssh D601:k3s:hwlab-dev:hwlab-cloud-api script <<'SCRIPT'",
@@ -180,8 +180,8 @@ export function sshHelp(): unknown {
       "For one-line remote shell logic without a heredoc, use `script -- '<command && command>'`; outer shell operators written outside tran, such as `tran G14:/repo sed ... && sed ...`, are parsed by the local shell before UniDesk starts and therefore cannot be redirected by the CLI. The explicit `shell '<command>'` operation remains available for the same sh -c path.",
       "When a one-line shell command is easier to type through the script path, `script -- '<command && command>'` runs that single string through the remote shell without waiting for stdin. When `script --` is followed by multiple tokens, it stays a direct argv form for commands such as `tran D601:/work script -- sed -n '1,20p' file`.",
       "For arbitrary stdin streams into a workload command, use a workload route plus `exec --stdin -- <command> ...`; this keeps the route as location-only and avoids heredoc/base64/tar shell wrapping.",
-      "For remote text patches, prefer `v2`; it keeps the legacy apply-patch command unchanged but uses a local line-based patch engine and remote read/write operations, so long Unicode/Chinese lines and pure insertion hunks avoid the legacy remote shell hunk parser.",
-      "Legacy apply-patch is a fallback: it rejects low-context update hunks by default, reports the matched file:line for each hunk on stderr, and only accepts --allow-loose when the caller has manually reviewed an intentionally ambiguous insertion.",
+      "`apply-patch` is the default remote text patch entry and uses the v2 local line-based patch engine with remote read/write operations, so long Unicode/Chinese lines and pure insertion hunks avoid the legacy remote shell hunk parser.",
+      "`apply-patch-v1` is the only legacy fallback entry: it rejects low-context update hunks by default, reports the matched file:line for each hunk on stderr, and only accepts --allow-loose when the caller has manually reviewed an intentionally ambiguous insertion.",
       "script defaults to target /bin/sh and inherits provider proxy variables such as HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY; use --shell bash only for bash syntax such as pipefail, arrays, or [[ ... ]], not as a proxy workaround.",
       "Route syntax is `{provider}:{plane}[:{scope...}] {operation} [operation-args...]`: the first argv token locates a distributed target only, and every following token belongs to the operation parser. Host workspace routes use `<provider>:/absolute/workspace`; WSL providers can use `<provider>:win cmd <command-line>` to run Windows host cmd.exe with UTF-8 defaults, and `<provider>:win/c/test cmd cd` maps the Windows cwd to `C:\\test`; native k3s providers such as D601 and G14 use <provider>:k3s for the control plane, <provider>:k3s:<namespace>:<workload> for a workload, and <provider>:k3s:<namespace>:<workload>/<pod-workspace> for a pod workspace.",
       "Use `win`, not `win32`; the win route sets chcp 65001, PYTHONUTF8=1, and PYTHONIOENCODING=utf-8 before running the requested cmd command line.",

scripts/src/remote.ts

@@ -1253,7 +1253,7 @@ export function remoteSshFrontendPlanForTest(target: string, args: string[]): Re
 async function runRemoteSshOverFrontend(session: FrontendSession, target: string | undefined, args: string[]): Promise<number> {
   if (!target) throw new Error("remote ssh requires a route, for example: bun scripts/cli.ts --main-server-ip 74.48.78.17 ssh D601 hostname");
   const invocation = parseSshInvocation(target, args);
-  if ((args[0] ?? "") === "v2") {
+  if ((args[0] ?? "") === "apply-patch") {
     const executor: ApplyPatchV2Executor = {
       run: (command, input) => runRemoteSshWebSocketCapture(session, invocation, command, input),
     };

scripts/src/ssh.ts

@@ -93,6 +93,9 @@ const legacyK3sOperationRouteSegments = new Set([
   "exec",
   "script",
   "apply-patch",
+  "apply-patch-v1",
+  "patch",
+  "patch-v1",
   "v2",
   "logs",
   "get",
@@ -825,16 +828,19 @@ export function parseSshArgs(args: string[]): ParsedSshArgs {
     const toolArgs = subcommand === "skill" ? ["skill-discover", ...args.slice(2)] : ["skill-discover", ...args.slice(1)];
     return { remoteCommand: shellArgv(toolArgs), requiresStdin: false, invocationKind: "helper", requiredHelpers: ["skill-discover"] };
   }
-  if (subcommand === "apply-patch" || subcommand === "patch") {
-    const toolArgs = ["apply_patch", ...args.slice(1)];
-    return { remoteCommand: shellArgv(toolArgs), requiresStdin: true, invocationKind: "helper", requiredHelpers: ["apply_patch"] };
-  }
-  if (subcommand === "v2") {
+  if (subcommand === "apply-patch") {
     if (isApplyPatchV2HelpArgs(args.slice(1))) {
       return { remoteCommand: null, requiresStdin: false, invocationKind: "helper" };
     }
     return { remoteCommand: null, requiresStdin: true, invocationKind: "helper" };
   }
+  if (subcommand === "apply-patch-v1") {
+    const toolArgs = ["apply_patch", ...args.slice(1)];
+    return { remoteCommand: shellArgv(toolArgs), requiresStdin: true, invocationKind: "helper", requiredHelpers: ["apply_patch"] };
+  }
+  if (subcommand === "patch" || subcommand === "patch-v1" || subcommand === "v2") {
+    throw new Error("remote patch entrypoints are `apply-patch` for the default v2 engine and `apply-patch-v1` for the legacy helper");
+  }
   if (subcommand === "py") {
     return { remoteCommand: buildPythonStdinCommand(args.slice(1)), requiresStdin: true, invocationKind: "helper" };
   }
@@ -1163,6 +1169,9 @@ function isK3sResourceKindAlias(value: string): boolean {
 
 function k3sOperationInRouteMessage(target: string, operation: string): string {
   const providerId = target.split(":")[0] || "<provider>";
+  if (operation === "v2" || operation === "patch" || operation === "patch-v1") {
+    return `ssh k3s route must locate a target only; remote patch entrypoints are "apply-patch" for the default v2 engine and "apply-patch-v1" for the legacy helper instead of "${target}"`;
+  }
   const operationExample = operation === "guard" ? "guard" : `${operation} ...`;
   return `ssh k3s route must locate a target only; put operation "${operation}" after the route, for example "ssh ${providerId}:k3s ${operationExample}" or "ssh ${providerId}:k3s:<namespace>:<workload> ${operationExample}" instead of "${target}"`;
 }
@@ -1283,11 +1292,11 @@ function parseK3sRouteArgs(route: ParsedSshRoute, args: string[]): ParsedSshArgs
 
 function parseK3sControlPlaneOperation(route: ParsedSshRoute, args: string[]): ParsedSshArgs {
   const operation = args[0] ?? "guard";
-  if (operation === "apply-patch" || operation === "patch") {
+  if (operation === "apply-patch" || operation === "apply-patch-v1") {
     throw new Error(`ssh ${route.providerId}:k3s apply-patch requires a workload route: ssh ${route.providerId}:k3s:<namespace>:<workload> apply-patch`);
   }
-  if (operation === "v2") {
-    throw new Error(`ssh ${route.providerId}:k3s v2 requires a workload route: ssh ${route.providerId}:k3s:<namespace>:<workload> v2`);
+  if (operation === "patch" || operation === "patch-v1" || operation === "v2") {
+    throw new Error("remote patch entrypoints are `apply-patch` for the default v2 engine and `apply-patch-v1` for the legacy helper");
   }
   if (operation === "script" || operation === "sh") {
     return { remoteCommand: buildK3sScriptCommand(args.slice(1)), requiresStdin: true, invocationKind: "helper" };
@@ -1314,8 +1323,16 @@ function parseK3sTargetOperation(route: ParsedSshRoute, args: string[]): ParsedS
   }
   const operation = args[0] ?? "";
   const operationArgs = args.slice(1);
-  if (operation === "apply-patch" || operation === "patch") return buildK3sApplyPatchCommand([...targetArgs, ...operationArgs]);
-  if (operation === "v2") return { remoteCommand: null, requiresStdin: true, invocationKind: "helper" };
+  if (operation === "apply-patch") {
+    if (isApplyPatchV2HelpArgs(operationArgs)) {
+      return { remoteCommand: null, requiresStdin: false, invocationKind: "helper" };
+    }
+    return { remoteCommand: null, requiresStdin: true, invocationKind: "helper" };
+  }
+  if (operation === "apply-patch-v1") return buildK3sApplyPatchCommand([...targetArgs, ...operationArgs]);
+  if (operation === "patch" || operation === "patch-v1" || operation === "v2") {
+    throw new Error("remote patch entrypoints are `apply-patch` for the default v2 engine and `apply-patch-v1` for the legacy helper");
+  }
   if (operation === "script") return { remoteCommand: buildK3sScriptCommand([...targetArgs, ...operationArgs]), requiresStdin: true, invocationKind: "helper" };
   if (operation === "shell") {
     const parsed = parseShellStringOperationArgs(operationArgs, `ssh ${route.raw} shell`);
@@ -2057,7 +2074,7 @@ function terminalSize(): { cols: number; rows: number } {
 
 export function remoteCommandForRoute(route: ParsedSshRoute, command: string[]): string {
   if (route.plane === "k3s") return buildK3sTargetCommand(route, command);
-  if (route.plane === "win") throw new Error(`ssh v2 does not support win routes yet: ${route.raw}`);
+  if (route.plane === "win") throw new Error(`ssh apply-patch does not support win routes yet: ${route.raw}`);
   return shellArgv(command);
 }
 
@@ -2167,7 +2184,7 @@ export async function runSsh(config: UniDeskConfig, providerId: string, args: st
   const invocation = parseSshInvocation(providerId, args);
   const parsed = invocation.parsed;
   const operationName = args[0] ?? "";
-  if (operationName === "v2") {
+  if (operationName === "apply-patch") {
     const executor: ApplyPatchV2Executor = { run: (command, input) => runSshCaptureCommand(config, invocation, command, input) };
     return await runApplyPatchV2({
       executor,

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

@@ -330,24 +330,30 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
   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, "k3s apply-patch operation must stream local patch stdin", routeApplyPatch);
-  assertCondition(routeApplyPatch.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 must enter pod with stdin", routeApplyPatch);
-  assertCondition(routeApplyPatch.parsed.stdinPrefix?.includes("apply_patch") && routeApplyPatch.parsed.stdinPrefix.includes("__UNIDESK_APPLY_PATCH_PAYLOAD__"), "k3s apply-patch operation must inject pod helper before patch stdin", routeApplyPatch);
-  assertCondition(routeApplyPatch.parsed.stdinPrefix?.includes("#!/bin/sh"), "k3s apply-patch operation must inject the same sh helper used by host apply-patch", routeApplyPatch);
-  assertCondition(!routeApplyPatch.parsed.stdinPrefix?.includes("python3") && !routeApplyPatch.parsed.stdinPrefix?.includes("node "), "k3s apply-patch operation must use the sh-only pod helper", routeApplyPatch);
-  assertCondition(routeApplyPatch.parsed.stdinSuffix === "\n__UNIDESK_APPLY_PATCH_PAYLOAD__\n", "k3s apply-patch operation must terminate patch heredoc", routeApplyPatch);
+  assertCondition(routeApplyPatch.parsed.requiresStdin === true && routeApplyPatch.parsed.remoteCommand === null, "k3s apply-patch operation must use the default v2 local engine", routeApplyPatch);
 
-  const hostApplyPatchLoose = parseSshArgs(["apply-patch", "--allow-loose"]);
-  assertCondition(hostApplyPatchLoose.remoteCommand === "'apply_patch' '--allow-loose'", "host apply-patch must pass --allow-loose as an explicit helper argument", hostApplyPatchLoose);
-  assertCondition(hostApplyPatchLoose.requiredHelpers?.length === 1 && hostApplyPatchLoose.requiredHelpers.includes("apply_patch"), "host apply-patch must request only the apply_patch helper bootstrap", hostApplyPatchLoose);
+  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(["v2"]);
-  assertCondition(hostApplyPatchV2.requiresStdin === true && hostApplyPatchV2.requiredHelpers === undefined && hostApplyPatchV2.remoteCommand === null, "host v2 must be a local engine operation, not a remote helper bootstrap", hostApplyPatchV2);
-  const hostApplyPatchV2Help = parseSshArgs(["v2", "--help"]);
-  assertCondition(hostApplyPatchV2Help.requiresStdin === false && hostApplyPatchV2Help.remoteCommand === null, "host v2 --help must not wait for patch stdin", hostApplyPatchV2Help);
-  const podApplyPatchV2 = parseSshInvocation("D601:k3s:hwlab-dev:hwlab-cloud-api/app", ["v2"]);
-  assertCondition(podApplyPatchV2.parsed.requiresStdin === true && podApplyPatchV2.parsed.remoteCommand === null, "pod v2 must be handled by the local v2 engine instead of injecting the legacy helper", podApplyPatchV2);
+  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",
@@ -647,7 +653,11 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
 
   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 === "'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 must set cwd before injecting the sh helper", 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);
@@ -714,9 +724,9 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
   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 apply-patch <<'PATCH'"), "ssh help must document k3s pod apply-patch 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 [--allow-loose]") && helpText.includes("low-context update hunks"), "ssh help must document apply-patch loose-context guard", 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);
@@ -733,11 +743,11 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
   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(String(frontendRemoteHostPatchPlan.wrappedRemoteCommand ?? "").includes("UNIDESK_SSH_TOOL_DIR=/tmp/unidesk-ssh-tools"), "host apply-patch must bootstrap the remote apply_patch helper", frontendRemoteHostPatchPlan);
-  assertCondition(String(frontendRemoteHostPatchPlan.wrappedRemoteCommand ?? "").includes("/apply_patch") && !String(frontendRemoteHostPatchPlan.wrappedRemoteCommand ?? "").includes("/glob") && !String(frontendRemoteHostPatchPlan.wrappedRemoteCommand ?? "").includes("/skill-discover"), "host apply-patch must not bootstrap unrelated helper tools", frontendRemoteHostPatchPlan);
+  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 frontendRemoteV2Plan = remoteSshFrontendPlanForTest("D601:/tmp", ["v2"]);
-  assertCondition(frontendRemoteV2Plan.requiresStdin === true && frontendRemoteV2Plan.remoteCommand === null && !String(frontendRemoteV2Plan.wrappedRemoteCommand ?? "").includes("UNIDESK_SSH_TOOL_DIR"), "frontend v2 plan must stay a local engine operation and not bootstrap legacy helpers", frontendRemoteV2Plan);
+  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);
@@ -783,9 +793,9 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
       "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 injects helper and forwards patch stdin",
+      "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 uses one sh helper for host and pod paths and rejects low-context hunks unless --allow-loose is explicit",
+      "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",
@@ -798,7 +808,7 @@ export async function runSshArgvGuidanceContract(): Promise<JsonRecord> {
       "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 bootstraps only the apply_patch helper and uses a Perl fast path for large files",
+      "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",