fix(gateway): clarify pairing and node auth guidance

src/node-host/invoke-system-run.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { formatSystemRunAllowlistMissMessage } from "./invoke-system-run.js";
+
+describe("formatSystemRunAllowlistMissMessage", () => {
+  it("returns legacy allowlist miss message by default", () => {
+    expect(formatSystemRunAllowlistMissMessage()).toBe("SYSTEM_RUN_DENIED: allowlist miss");
+  });
+
+  it("adds Windows shell-wrapper guidance when blocked by cmd.exe policy", () => {
+    expect(
+      formatSystemRunAllowlistMissMessage({
+        windowsShellWrapperBlocked: true,
+      }),
+    ).toContain("Windows shell wrappers like cmd.exe /c require approval");
+  });
+});

src/node-host/invoke-system-run.ts

@@ -33,6 +33,19 @@ type SystemRunInvokeResult = {
   error?: { code?: string; message?: string } | null;
 };
 
+export function formatSystemRunAllowlistMissMessage(params?: {
+  windowsShellWrapperBlocked?: boolean;
+}): string {
+  if (params?.windowsShellWrapperBlocked) {
+    return (
+      "SYSTEM_RUN_DENIED: allowlist miss " +
+      "(Windows shell wrappers like cmd.exe /c require approval; " +
+      "approve once/always or run with --ask on-miss|always)"
+    );
+  }
+  return "SYSTEM_RUN_DENIED: allowlist miss";
+}
+
 export async function handleSystemRunInvoke(opts: {
   client: GatewayClient;
   params: SystemRunParams;
@@ -163,7 +176,8 @@ export async function handleSystemRunInvoke(opts: {
   const cmdInvocation = shellCommand
     ? opts.isCmdExeInvocation(segments[0]?.argv ?? [])
     : opts.isCmdExeInvocation(argv);
-  if (security === "allowlist" && isWindows && cmdInvocation) {
+  const windowsShellWrapperBlocked = security === "allowlist" && isWindows && cmdInvocation;
+  if (windowsShellWrapperBlocked) {
     analysisOk = false;
     allowlistSatisfied = false;
   }
@@ -317,7 +331,10 @@ export async function handleSystemRunInvoke(opts: {
     );
     await opts.sendInvokeResult({
       ok: false,
-      error: { code: "UNAVAILABLE", message: "SYSTEM_RUN_DENIED: allowlist miss" },
+      error: {
+        code: "UNAVAILABLE",
+        message: formatSystemRunAllowlistMissMessage({ windowsShellWrapperBlocked }),
+      },
     });
     return;
   }