name: Bug Report
about: Report a bug to help us improve
title: 'archon setup --spawn fails on Windows when repo path contains spaces'
labels: bug

Summary

• What broke: archon setup --spawn opens a Windows error dialog ("could not be found") instead of launching the setup wizard, when the Archon repo path contains a space (e.g. C:\Users\kiyan\Documents\Code\GitHub Libraries\Archon).
• When it started (if known): Unknown — present in the current CLI (v0.2.13, commit 95679fa6).
• Severity: major (blocks the documented setup flow on any Windows machine whose checkout path contains a space, including the default GitHub folder that GitHub Desktop creates, Program Files, My Documents, etc.)

Steps to Reproduce

1. Clone Archon into a path that contains a space, e.g. C:\Users\<you>\Documents\Code\GitHub Libraries\Archon.
2. bun install and cd packages/cli && bun link.
3. From any git repo, run archon setup --spawn.

Expected vs Actual

• Expected: A new terminal window opens in the Archon repo directory running archon setup, exactly as the guides/setup.md wizard documents.

• Actual: The CLI prints Opening setup wizard in a new terminal window... and Setup wizard opened. — but the OS immediately shows a Windows error dialog (German locale in my case):

  "Libraries\Archon\packages\cli" konnte nicht gefunden werden. Stellen Sie sicher, dass Sie den Namen richtig eingegeben haben und wiederholen Sie den Vorgang.

  The path has been truncated at the first space (C:\Users\kiyan\Documents\Code\GitHub is consumed as one argument, and everything after the space is treated as a separate command to run). No setup wizard window opens.

User Flow

  User                           Archon CLI                         OS
  ────                           ──────────                         ──
  runs archon setup --spawn ───▶ spawnWindowsTerminal(repoPath)
                                 tries wt.exe -d <repoPath> ...
                                 [X] path split on space ─────────▶ Windows: "Libraries\Archon\packages\cli"
                                                                    could not be found (error dialog)
                                 falls back to cmd.exe /c start
                                   "" /D <repoPath> ... {shell:true}
                                 [X] cmd.exe /D parses only up ───▶ Same error — path truncated at first space
                                     to first whitespace, treats
                                     the rest as a command
  sees OS error dialog ◀──────── CLI already printed
                                 "Setup wizard opened."
                                 (false positive — trySpawn
                                 returned true because child.pid
                                 was defined, even though the
                                 child failed post-launch)

Environment

• Platform: CLI
• Database: SQLite (default)
• Running in worktree? No
• OS: Windows 11 Pro 10.0.26200, shell invocation via Git Bash. Bun 1.3.12. Archon CLI v0.2.13, source build, git commit 95679fa6.

Logs

$ archon setup --spawn
Opening setup wizard in a new terminal window...
Setup wizard opened. Complete the setup in the new terminal window.

Accompanying OS error dialog (title is the truncated path, not an Archon message):

Title:  Libraries\Archon\packages\cli
Body:   "Libraries\Archon\packages\cli" konnte nicht gefunden werden.
        Stellen Sie sicher, dass Sie den Namen richtig eingegeben haben
        und wiederholen Sie den Vorgang.

Impact

• Affected workflows/commands: archon setup --spawn (the primary credential-configuration path documented in .claude/skills/archon/guides/setup.md). The non-spawn archon setup still works if run directly by a human, but the skill's setup wizard explicitly tells the AI assistant not to run archon setup inline because it needs interactive input.
• Reproduction rate: Always, on Windows, whenever the repo path contains a space.
• Workaround available? Yes — either (a) clone Archon into a path without spaces (e.g. C:\dev\archon), or (b) manually run archon setup in a terminal the user opens themselves. The skill's setup flow currently has no fallback path if --spawn "succeeds" but silently fails.
• Data loss risk? No.

Scope

• Package(s) likely involved: cli
• Module (if known): packages/cli/src/commands/setup.ts — spawnWindowsTerminal() at lines 1225–1248, and its interaction with trySpawn() at lines 1203–1219.

Root Cause Analysis

Two related issues:

1. cmd.exe fallback (line 1238): With shell: true, Node/Bun flattens the args array into a single command string that it passes to cmd.exe. The result is roughly:

   cmd.exe /c start "" /D C:\Users\kiyan\Documents\Code\GitHub Libraries\Archon\packages\cli cmd /k archon setup
   

   cmd.exe's start built-in parses the /D switch's argument up to the first whitespace, so /D gets C:\Users\kiyan\Documents\Code\GitHub, and Libraries\Archon\packages\cli is then treated as the program to launch — which is the exact string shown in the OS error dialog. The path needs to be explicitly wrapped in quotes for the shell.

2. wt.exe primary path (line 1228): trySpawn returns true as soon as child.pid is defined, even when the child process fails immediately afterward. On Windows this means a wt.exe invocation that spawns successfully but then errors out during its own argument parsing is indistinguishable from a successful launch. Combined with { stdio: 'ignore' }, there is no way for the CLI to observe the failure and fall through to the cmd.exe path. If wt.exe also has a quoting issue here (possible — Bun's child_process.spawn argument escaping on Windows has historically differed from Node's), the user hits the same error on the first attempt and the fallback is never even tried.

Suggested Fix

• In the cmd.exe fallback, either drop shell: true entirely (let Node/Bun quote the args itself via CreateProcess argv) or explicitly wrap repoPath with "${repoPath}". Example without shell: true:

  trySpawn(
    'cmd.exe',
    ['/c', 'start', '""', '/D', repoPath, 'cmd', '/k', 'archon setup'],
    { detached: true, stdio: 'ignore' }  // no shell:true
  )

• For the wt.exe branch, double-check the argument by manually building the command string (Windows Terminal accepts a single -d "<path>" token). One robust form:

  trySpawn(
    'wt.exe',
    ['-d', repoPath, 'cmd.exe', '/k', 'archon setup'],
    { detached: true, stdio: 'ignore', windowsVerbatimArguments: false }
  )

  and add a short post-spawn sanity check (e.g. a small setTimeout + child.exitCode !== null check) before returning success, so a child that dies within a few ms doesn't produce a false-positive "Setup wizard opened." message.

• Independently, the user-facing message from packages/cli/src/commands/setup.ts around line 1352 should not unconditionally print Setup wizard opened. Complete the setup in the new terminal window. — it should only print that after confirming the child is still alive, and otherwise fall through to the "run it manually" branch.