fix: suppress ExperimentalWarning, PEP 668 guidance, setup help

- All 5 CLI bins: shebang --disable-warning=ExperimentalWarning
- Remove NODE_OPTIONS injection from thread.ts spawn (redundant now)
- Bootstrap pip install: venv (recommended) / pipx / source options
- setup --help mentions interactive wizard mode
- Update shebang test to accept -S flag

Fixes #116

packages/cli/src/cli.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
 import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
@@ -542,7 +542,7 @@ prompt
 
 program
   .command("setup")
-  .description("Configure provider, model, and agent")
+  .description("Configure provider, model, and agent. Run without options for interactive wizard.")
   .option("--provider <name>", "Provider name")
   .option("--base-url <url>", "OpenAI-compatible API base URL")
   .option("--api-key <key>", "API key")

packages/cli/src/commands/prompt.ts

@@ -103,9 +103,16 @@ Install an agent adapter (at least one is required):
 | uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly |
 | uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) |
 
-**uwf-hermes** also requires the Hermes ACP plugin. After installing \`hermes-agent\`, run:
+**uwf-hermes** also requires the Hermes ACP plugin:
 \`\`\`bash
-pip install hermes-agent[acp]   # or: pip install -e .[acp] if installed from source
+# Option A: install into hermes venv (recommended)
+source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp]
+
+# Option B: pipx
+pipx install 'hermes-agent[acp]'
+
+# Option C: if installed from source
+pip install -e '.[acp]'
 \`\`\`
 
 Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose).

packages/cli/src/commands/thread.ts

@@ -1001,12 +1001,6 @@ function spawnAgent(
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
       cwd,
-      env: {
-        ...process.env,
-        NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
-          .filter(Boolean)
-          .join(" "),
-      },
     });
   } catch (e) {
     const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
@@ -1254,12 +1248,6 @@ async function cmdThreadStepBackground(
   const child = spawn(scriptPath, args, {
     detached: true,
     stdio: "ignore",
-    env: {
-      ...process.env,
-      NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"]
-        .filter(Boolean)
-        .join(" "),
-    },
   });
 
   child.unref();