[tamirdresher]

What

Second slice of the standalone distribution work, following #1595 (now merged). Adds the pieces that turn the bundle mechanism into something you can actually consume: a composite action, a container image, and a fix for a gap that made the first slice incomplete.

Thanks for merging #1595, @bradygaster. This is rebased onto current dev, so it targets dev directly rather than stacking.

Why

While verifying what squad init actually produces, I found the first slice only solved half the problem.

Installing from a bundle removed npm from installation. But squad init still wrote this into .mcp.json:

{ "command": "npx", "args": ["-y", "@bradygaster/squad-cli@0.11.0", "state-mcp"] }

…and called registry.npmjs.org to decide which version to pin. So on a firewalled machine the CLI would install cleanly and then the squad_state MCP server would silently fail to launch on first use. That's exactly the failure this work exists to prevent, and the npm-free install would have shipped looking complete while being broken.

How

Tier-0 in the MCP resolver. resolveSquadStateMcpSpec gains a tier ahead of the two npx ones. When SQUAD_STANDALONE_HOME is set — exported by the bundle launchers — it emits the bundle's own launcher:

{ "command": "/opt/squad/squad", "args": ["state-mcp"] }

Two deliberate details:

• It short-circuits before the registry probe, so a machine with no route to npm makes no network call at all. There's an explicit test asserting the probe never fires.
• The path is absolute, because Copilot spawns the MCP server in its own environment where neither PATH nor that env var is guaranteed.

describeMcpSpec bug caught on the way. It read args[1] to name the package. Standalone specs have nothing there, so the success message would have printed <unknown>. Now reports the launcher path.

squad-init composite action. Installs from a release bundle and runs init — the direct replacement for npx @bradygaster/squad-cli init in the gh-aw activation job. It also fails the step if the resulting .mcp.json still mentions npx, so this can't silently regress.

Dockerfile. Built from a bundle rather than npm install -g, following the contract already documented in reference/container-image.md (WORKDIR /app, non-root uid 1001, SIGTERM, squad watch --execute). Uses --include-optional because that contract documents OTLP export, which lives in the optional OpenTelemetry packages.

Verification

Container, on linux/amd64:

Check	Result
squad --version as non-root squad user	0.11.0
which squad	/opt/squad/squad
squad init → .mcp.json command	/opt/squad/squad — no npx
squad state-mcp JSON-RPC initialize	{"serverInfo":{"name":"squad-state",...}}

That last one is the one I cared about: the MCP server completes a real handshake inside a container that cannot reach npm.

Also: 13 new tests (23/23 in mcp-spec-init.test.ts) · bundle on win32-x64 writes command=<bundle>\squad.cmd · npm run lint ✅ · docs-build, mcp-root-write, state-mcp ✅ · cspell + markdownlint ✅

What is NOT verified

The Dockerfile builder stage has never run. My machine intercepts TLS, so every container fails to reach registry.npmjs.org:

$ docker run --rm node:22-slim npm view lodash
npm error ... ssl3_read_bytes:ssl/tls alert handshake failure

That's environmental, not a Dockerfile defect — and there's some irony in being blocked by the exact firewall condition this PR addresses. But it means the full image has never been built end to end, and CI needs to prove it. I verified the runtime stage by feeding it a host-built bundle, which covers every line where I made a decision, but not the npm ci + build layer.

The squad-init action has never run either — it downloads a release asset, and no release with bundle assets exists yet. Same chicken-and-egg as #1595.

Changeset

Included (patch for squad-cli) — unlike #1595, this slice does touch packages/squad-cli/src/.

---

⚠️ Quick Check

• Changeset added (.changeset/standalone-mcp-spec-1593.md)

PR Readiness Checklist

Branch & Commit

• Branch created from dev
• Branch is up to date with dev (rebased onto 543d0eac)
• Verified diff contains only intended changes
• PR is not in draft mode
• Commit history is clean (single commit)

Build & Test

• npm run build passes
• npm test — 41 test files fail identically on clean dev on Windows (pre-existing path-separator issues, measured in feat(dist): standalone npm-free bundles for squad-cli (#1593) #1595). This branch adds none. Deferring to CI.
• npm run lint passes
• npm run lint:eslint passes (0 errors)

Docs

• Docs feature page updated — added the MCP spec behavior, the action, and the container section

Exports

• N/A — no new SDK modules

---

Breaking Changes

None. The npx tiers are untouched when SQUAD_STANDALONE_HOME is unset, which is every existing npm install.

Waivers

None requested. Flagging rather than waiving: the Dockerfile builder stage and the composite action are both unproven end to end, for the environmental reasons above. I would rather that be stated plainly than have CI be the first place anyone finds out.

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	2 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/mcp-spec.ts, packages/squad-cli/src/cli/core/upgrade.ts

---

Automated architectural review — informational only.

[github-actions]

🛫 PR Readiness Check

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

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 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	0 active Copilot thread(s) resolved (2 outdated skipped)
✅	CI passing	All checks passing

Files Changed (12 files, +675 −23)

File	+/−
.changeset/standalone-cross-build-fix.md	+5 −0
.changeset/standalone-mcp-spec-1593.md	+5 −0
.dockerignore	+15 −0
.gitattributes	+5 −0
.github/actions/squad-init/action.yml	+189 −0
Dockerfile	+71 −0
docs/src/content/docs/features/standalone-install.md	+69 −3
packages/squad-cli/src/cli/core/mcp-spec.ts	+62 −6
packages/squad-cli/src/cli/core/upgrade.ts	+6 −1
scripts/build-standalone.mjs	+33 −11
test/mcp-spec-init.test.ts	+106 −2
test/standalone-build.test.ts	+109 −0

Total: +675 −23

---

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

[github-actions]

🟠 Impact Analysis — PR #1610

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	12
Files added	6
Files modified	6
Files deleted	0
Modules touched	6

🎯 Risk Factors

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

📦 Modules Affected

ci-workflows (1 file)

• .github/actions/squad-init/action.yml

docs (1 file)

• docs/src/content/docs/features/standalone-install.md

root (5 files)

• .changeset/standalone-cross-build-fix.md
• .changeset/standalone-mcp-spec-1593.md
• .dockerignore
• .gitattributes
• Dockerfile

scripts (1 file)

• scripts/build-standalone.mjs

squad-cli (2 files)

• packages/squad-cli/src/cli/core/mcp-spec.ts
• packages/squad-cli/src/cli/core/upgrade.ts

tests (2 files)

• test/mcp-spec-init.test.ts
• test/standalone-build.test.ts

---

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

[Copilot]

Pull request overview

Adds an npm-free path for the squad_state MCP server spec when running Squad from a standalone bundle, plus distribution helpers (composite action + container image) to consume those bundles in CI and containers.

Changes:

• Add a new “standalone bundle” tier in the MCP spec resolver (driven by SQUAD_STANDALONE_HOME) and fix describeMcpSpec for standalone specs.
• Add a squad-init composite action that installs from release bundles and runs squad init.
• Add a root Dockerfile + docs updates for building/running an image from a bundle (no npm registry dependency at runtime).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/mcp-spec-init.test.ts	Adds tests for standalone-tier resolution, standalone launcher detection, and describeMcpSpec behavior.
scripts/build-standalone.mjs	Exports SQUAD_STANDALONE_HOME from bundle launchers (cmd/ps1/sh).
packages/squad-cli/src/cli/core/mcp-spec.ts	Adds standalone tier + launcher detection and exposes STANDALONE_HOME_ENV.
packages/squad-cli/src/cli/core/upgrade.ts	Fixes describeMcpSpec to correctly describe standalone launcher specs.
docs/src/content/docs/features/standalone-install.md	Documents squad-init, container usage, and the npx-free .mcp.json behavior.
Dockerfile	Builds a container image from a standalone bundle (multi-stage).
.github/actions/squad-init/action.yml	Composite action to install from bundle + run squad init, and summarize results.
.gitattributes	Forces LF endings for Docker-related files to prevent build issues.
.dockerignore	Reduces build context / prevents host artifacts from leaking into the image build.
.changeset/standalone-mcp-spec-1593.md	Changeset for the squad-cli patch release.

[tamirdresher]

Pushed two follow-ups: the review fixes (b121030) and a real bug I found while testing (4756266).

Both review comments addressed

The unpinned raw.githubusercontent.com/.../HEAD fetch is gone — the action now runs the install.sh that ships beside it, so it is pinned by whatever SHA a consumer pins the action to. And the npx check now exits 1 instead of writing a warning, which is what the description claimed all along. Replies are on the individual threads.

curl | bash is now actually proven

I built a fake release and ran the real installer against it in a container with no Node and no npm:

→ Downloading squad-linux-x64.tar.gz (v9.9.9)
→ Checksum verified
→ Installing to /opt/squadtest/lib/squad
✓ Squad v9.9.9 installed to /opt/squadtest/bin/squad

which squad: /opt/squadtest/bin/squad
squad --version: 0.11.0

Then corrupted the asset to confirm the checksum path actually rejects it:

error: Checksum mismatch for squad-linux-x64.tar.gz. Expected 5736…, got 1bb8…

So download, checksum verification, unpack, symlink resolution and PATH all work. That was speculation in #1595 and it isn't anymore.

The bug that found

Getting there surfaced a genuine defect in the builder. Cross-building a linux bundle from Windows fails:

node-v22.20.0-linux-x64/bin/npx: Can't create '...': Invalid argument
tar: Error exit delayed from previous errors.

The posix Node archives contain symlinks (bin/npm, bin/npx, bin/corepack) that Windows cannot create, and the builder was extracting the whole archive. Only the node binary is ever shipped, so extraction is now scoped to that one member.

Worth noting the release workflow would not have caught this — it builds on ubuntu-latest, where extracting the full archive works fine. It would only have bitten someone building non-linux targets from a Windows runner or locally on Windows. That is exactly the class of thing that sits latent for months.

New tests

Added test/standalone-build.test.ts (11 cases) for the behaviors that fail silently rather than loudly: selective extraction, SQUAD_STANDALONE_HOME in all three launchers, symlink resolution in the posix launcher, optional-dep omission, checksum verification, VERSION/PREFIX/REPO overrides, and an assertion that install.sh never reaches the npm registry.

One of those tests failed on the first run because I asserted against the raw file and install.sh mentions registry.npmjs.org in a comment explaining what it avoids. Fixed the test to check executable lines.

Still unverified

Unchanged from the PR description: the Dockerfile builder stage (my machine's TLS interception blocks npm from any container) and the composite action itself, which needs a release with bundle assets to exist. Both need CI.