fix(claude): repository launcher finds squad on PATH; launcher argv tested on Windows by bradygaster · Pull Request #2483 · github/squad

bradygaster · 2026-11-12T15:00:36Z

Tests the launcher on Windows, as #2469 asked ("Test the Windows launcher's npx quoting"). Writing the test turned up a bug from #2470.

Bug: the repository launcher never found `squad` on PATH

onPath skips the launcher's own bin directory. It compared realpathSync(dir) with realpathSync(ownBin) inside one try, and continued on any error. The plugin has a bin/, but the repository launcher's .squad/bin doesn't exist, so every PATH entry was skipped. A repository whose only Squad CLI was a global install failed with "no Squad CLI found". The existing tests covered the project install, SQUAD_CLI and ~/.squad/cli.json, but not PATH. The fix resolves ownBin once and only skips it when it exists. The plugin's scripts/squad.mjs is regenerated (still pinned to 2.0.0-preview.4).

Windows argv test

New test/launcher-argv.test.ts sends arguments that a shell or cmd.exe would rewrite (&echo pwned, pipe|more, %PATH%, ^caret, !bang!, quotes, an empty string, a trailing backslash, non-ASCII text) through each way the launcher finds a CLI: a global squad, npx with SQUAD_ALLOW_NPX=1, SQUAD_CLI and the project's install. It checks they arrive byte for byte.

On Windows the fakes are npm-style squad.cmd and npx.cmd shims that print SHELL-USED if cmd.exe ever runs them, beside the JavaScript entry the launcher should run instead. A Windows-only case checks that a shim with no entry fails closed.

The main CI runs on Linux only, so the new workflow squad-launcher-platforms.yml runs this test and portable-launch.test.ts on windows-latest and ubuntu-latest when the launcher template, the plugin scripts or these tests change.

Testing

Before the fix, the new test failed on macOS with "no Squad CLI found"; after it, the launcher tests pass (61 tests, with the Windows-only case skipped).
The Windows evidence is this PR's squad-launcher-platforms run.
actionlint is clean.

🤖 Generated with Claude Code

The repo launcher skipped every PATH entry because realpath of its (nonexistent) .squad/bin threw inside the comparison. New test/launcher-argv.test.ts checks hostile argv round-trips through a global squad, npx, SQUAD_CLI and a project install, through .cmd shims on Windows without cmd.exe. A new workflow runs the launcher tests on Windows and Linux. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-11-12T15:01:10Z

🟠 Impact Analysis — PR #2483

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	9
Files added	3
Files modified	6
Files deleted	0
Modules touched	5

🎯 Risk Factors

9 files changed (6-20 → MEDIUM)
5 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (1 file)

.github/workflows/squad-launcher-platforms.yml

root (3 files)

.changeset/launcher-path-lookup.md
CHANGELOG.md
plugins/squad/scripts/squad.mjs

scripts (1 file)

scripts/release/test-reconciliation.mjs

squad-sdk (1 file)

packages/squad-sdk/src/client/adapters/claude-plugin.ts

tests (3 files)

test/claude-plugin.test.ts
test/claude-projection-v3-plugin.test.ts
test/launcher-argv.test.ts

This report is generated automatically for every PR. See #733 for details.

github-actions · 2026-11-12T15:01:20Z

🏗️ Architectural Review

Authoritative evidence: scanners from the PR base commit, posted by the default-branch workflow_run reporter.
Results for head commit 5b3ba99547d7db8d5786de424e2505a43e6af2ee.

⚠️ Architectural review: 1 info.

Severity	Category	Finding	Files
ℹ️ info	template-sync	Template files changed in .github/workflows/ but not in other template locations. If these templates should stay in sync, consider updating the others too.	`Changed: .github/workflows/`, `Unchanged: templates/, .squad-templates/, packages/squad-cli/templates/`

Automated architectural review — informational only.

github-actions · 2026-11-12T15:01:25Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 5b3ba99

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	5 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	2 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	1 check(s) still running

Files Changed (9 files, +219 −9)

File	+/−
`.changeset/launcher-path-lookup.md`	+6 −0
`.github/workflows/squad-launcher-platforms.yml`	+59 −0
`CHANGELOG.md`	+1 −0
`packages/squad-sdk/src/client/adapters/claude-plugin.ts`	+6 −3
`plugins/squad/scripts/squad.mjs`	+6 −3
`scripts/release/test-reconciliation.mjs`	+1 −0
`test/claude-plugin.test.ts`	+3 −1
`test/claude-projection-v3-plugin.test.ts`	+2 −2
`test/launcher-argv.test.ts`	+135 −0

Total: +219 −9

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

~/.squad/cli.json (since #2470) is found by the launcher, so tests that expect the npx fallback or a missing CLI failed on any machine that had run squad init from a source build. Point SQUAD_HOME at an empty dir. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

🟡 Changes recommended

A missing reconciliation rule for the Windows-only test blocks release verification and publishing, while the npx tests can run a globally installed CLI instead of their fixtures.

2 open issues

What changed in this PR

Fixes PATH lookup in the repository launcher used by Squad’s MCP configs and Claude Code hooks, and adds cross-platform argument-forwarding coverage requested in #2469.

Changes:

Fixes shared launcher logic so a missing launcher-owned bin directory no longer prevents PATH lookup.
Adds tests for literal argument forwarding through global installs, npx, SQUAD_CLI, and project installs.
Adds Windows/Linux CI coverage and records the fix in release notes.

File	Description
`test/launcher-argv.test.ts`	Adds argument-forwarding and Windows shim tests.
`plugins/squad/scripts/squad.mjs`	Regenerates the plugin launcher with the PATH fix.
`packages/squad-sdk/src/client/adapters/claude-plugin.ts`	Fixes own-directory handling in the shared launcher template.
`CHANGELOG.md`	Documents the PATH fix and cross-platform coverage.
`.github/workflows/squad-launcher-platforms.yml`	Runs launcher tests on Windows and Linux.
`.changeset/launcher-path-lookup.md`	Declares SDK and CLI patch releases.

_{Review effort: Max (auto)}

+    expect(parsed(run(HOSTILE))).toEqual(HOSTILE);
+  });
+
+  it.runIf(win)('fails closed when a .cmd shim has no JavaScript entry beside it', () => {


+  return spawnSync(process.execPath, [path.join(root, '.squad', 'squad.mjs'), ...args], {
+    cwd: os.tmpdir(),
+    encoding: 'utf8',
+    env: {
+      ...base,
+      // The fake bin first, then Node's own directory; no real squad or npx.
+      PATH: [bin, path.dirname(process.execPath)].join(path.delimiter),


Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

bradygaster requested a review from tamirdresher as a code owner November 12, 2026 15:00

Copilot AI auto review requested due to automatic review settings November 12, 2026 15:00

Copilot started reviewing on behalf of bradygaster November 12, 2026 15:01

View session

Copilot AI reviewed Nov 12, 2026

View reviewed changes

test: avoid a retired term in a test name

dae92d4

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

bradygaster mentioned this pull request Nov 12, 2026

Claude Code host: remaining work before 2.0 (#2438) #2469

Open

15 of 32 tasks

bradygaster and others added 2 commits November 12, 2026 07:41

test(release): explain the Windows-only launcher-argv skip

cad519b

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge branch 'dev' into squad/claude-launcher-path-windows

5b3ba99

bradygaster merged commit f229547 into dev Nov 12, 2026
34 checks passed

Navigation Menu

Repository navigation

fix(claude): repository launcher finds squad on PATH; launcher argv tested on Windows - #2483

fix(claude): repository launcher finds squad on PATH; launcher argv tested on Windows#2483
bradygaster merged 5 commits into
devfrom
squad/claude-launcher-path-windows

bradygaster commented Nov 12, 2026

Uh oh!

github-actions Bot commented Nov 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bradygaster commented Nov 12, 2026

Bug: the repository launcher never found squad on PATH

Windows argv test

Testing

Uh oh!

github-actions Bot commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠 Impact Analysis — PR #2483

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

github-actions Bot commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🏗️ Architectural Review

Uh oh!

github-actions Bot commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 4 item(s) to address before review

Files Changed (9 files, +219 −9)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Bug: the repository launcher never found `squad` on PATH

github-actions Bot commented Nov 12, 2026 •

edited

Loading

github-actions Bot commented Nov 12, 2026 •

edited

Loading

github-actions Bot commented Nov 12, 2026 •

edited

Loading