Troubleshooting

Common issues#

CLI or App cannot find the coordinator or a specialist#

Confirm that both hve-squad and hve-squad-hve-core are installed in the current client's plugin home. Select the coordinator agent, not a skill, then ask for squad-doctor. Follow the plugin guide for missing domains and companion reinstalls. A terminal update does not update an app using another COPILOT_HOME.

Exactly 11 dependencies fail during apm install#

This is a known APM regression, not a network or project-environment problem. The tested compatibility results are:

Pin APM CLI 0.29.0, remove the partial dependency state, and reinstall the HVE Squad package. The CLI pin is separate from the package pin in Peter-N91/hve-squad#vX.Y.z.

Windows (PowerShell)

# 1. Install the required APM CLI version.
$env:VERSION = 'v0.29.0'; irm https://aka.ms/apm-windows | iex

# 2. Verify it. Open a new terminal first if this still reports another version.
apm --version

# 3. From the affected project root, remove the partial APM state.
Set-Location C:\Temp\myapp
Remove-Item -Recurse -Force apm_modules, apm.lock.yaml, apm.yml -ErrorAction SilentlyContinue

# 4. Reinstall the HVE Squad release you need.
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

macOS (Apple Silicon or Intel)

# 1. Remove the Homebrew copy if it is installed; the pinned installer cannot overwrite it.
brew uninstall apm

# 2. Install the required APM CLI version.
curl -sSL https://aka.ms/apm-unix | sh -s -- @v0.29.0

# 3. Make the install visible to this shell and verify it.
export PATH="$HOME/.local/bin:$PATH"
hash -r
apm --version

# 4. From the affected project root, remove the partial APM state and reinstall.
cd /path/to/myapp
rm -rf apm_modules apm.lock.yaml apm.yml
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc to keep the path after reopening the terminal. As an isolated alternative, use uv tool install apm-cli@0.29.0.

For the workshop release that exposed this issue (v0.16.2), a healthy install reported Installed 302 APM dependencies after about one to two minutes. Later HVE Squad releases may report a different dependency count.

First apm install takes 30+ minutes (but never errors)#

Almost always GitHub API rate limiting. This package references hundreds of individual files from microsoft/hve-core, and APM fetches each one over GitHub's HTTP path. Unauthenticated callers are capped at 60 requests/hour; once the cap is hit APM waits for the window to reset (honoring GitHub's Retry-After header) and keeps going, so the install crawls instead of failing. A fresh machine also has a cold APM cache, so every file is fetched.

Authenticate before installing to raise the limit to 5,000 requests/hour:

gh auth login            # recommended — APM picks it up automatically
# or set a token (public read is enough; hve-core is public)
$env:GITHUB_TOKEN = "ghp_xxx"
apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

APM's GitHub token precedence is GITHUB_APM_PAT_<ORG> → GITHUB_APM_PAT → GITHUB_TOKEN → GH_TOKEN → gh auth token → your git credential helper. Once authenticated the install completes quickly, and the warm cache makes later installs near-instant.

Raising --parallel-downloads does not help an unauthenticated install — the cap is per hour, so more concurrency just reaches it faster.

A few packages fail with HTTP 502 (or 503) — Failed to download virtual package#

[x] 2 packages failed:
    +- hve-core-github-execute-backlog -- Failed to download virtual package:
       Failed to download .github/prompts/github/github-execute-backlog.prompt.md: HTTP 502

This is a transient GitHub server error, not a problem with your manifest or pins. 502 Bad Gateway (and 503) mean GitHub's file endpoint briefly failed to respond while APM was fetching one of the hundreds of individual files this package references. The tell-tale sign it is transient: only a handful of packages fail while the rest succeed, and they fail on the download step even though the pin resolved fine.

Just run the install again — cached files are skipped, so only the missing packages are retried:

apm install

Do not confuse this with 404 / "File not found (tried refs: main, master)", which means a file no longer exists at that ref (upstream drift or a bad pin), or with the slow-but-never-erroring rate-limit case above. If 502s persist across several retries, GitHub itself may be degraded — check githubstatus.com. Authenticating first (gh auth login) also makes installs more resilient.

[x] No harness detected after apm install (APM 0.18.0+)#

APM downloaded the sources into apm_modules/ but skipped the deploy step because no harness marker was found in your project (no .github/agents/, .github/prompts/, .claude/, .cursor/, etc.). Re-run with --target copilot:

apm install "Peter-N91/hve-squad#vX.Y.z" --target copilot

Or add a targets: block to your project's apm.yml so future installs work without the flag (see Getting Started → Option B).

apm_modules/ populated but .github/ is empty and no error visible#

Same root cause as above — scroll up in your terminal for the No harness detected message and apply the --target copilot fix.

No scripts found#

Check the scripts block in apm.yml and run apm list.

Access failures to HVE Core#

Confirm git authentication and repository visibility.

Dependencies look stale#

Run apm run sync-deps, then apm lock.

A role never produces its artifact, or the coordinator quietly “reroutes” to another agent#

Symptoms: a stage reports blocked and the run continues anyway; no history/<agent>.md entry for that role; later gates pass without evidence. The usual cause is a roster row whose Primary cannot accept a role-scoped dispatch — either the agent is no longer deployed after an HVE Core upgrade, or it is a delegated worker that refuses to act without a full input contract. Both look identical at run time.

Check the role’s Primary in .copilot-tracking/squad/team.md against the cast catalog in the squad skill's references/roster-catalog.md, and confirm the agent file exists under .github/agents/. The squad skill's squad-roster.instructions.md still carries the dispatchability and safety rules. A role whose Deliverable Root its Primary cannot write is always a wrong row. After any hve-core bump, re-run apm install and compare the cast with scripts/Get-HveCoreCastDelta.ps1.

Cost-ceiling issues#

A fresh squad initialized before showing its Cost Preflight result#

This is expected. Initialization is outside admission because it creates the state and rate files the estimate needs. The setup Scribe dispatch is still recorded as estimated spend, but it consumes no ceiling slot. The supplied ceiling applies to the original request before its first work dispatch after initialization.

The run stops at over-ceiling before implementation starts#

This is a forecast decision, not proof that the amount was already billed. Cost Preflight prices the planned dispatch manifest, applies eligible calibration, and multiplies the point estimate by the conservative 3.0 admission reserve. Open the Decision Ref in the gate message and inspect the ## Cost Preflight demand table in .copilot-tracking/squad/decisions.md. The current estimate is in consumption.md; rates and calibration are in consumption-rates.md.

With medium confidence and accumulated estimated spend still below the ceiling, you can stop or approve bounded proceed. With cannot-confirm, fix the unresolved model, missing rate, incomplete demand, invalid table, or stale calibration first. Approval does not replace evidence the forecast could not establish. See Cost admission control.

A later request unexpectedly still uses the old ceiling#

Omission means inherit when the request continues the same run. This prevents a guard from disappearing because a later prompt did not repeat it. Replace it with another positive value, or remove it explicitly:

A federation ceiling appears inside each selected sub-squad#

This is the ordinary federation contract. Targeted and meta-routed requests forward the same ceiling lifecycle to every selected sub-squad, and each squad compares it with its own accumulated estimate. A shared aggregate ceiling exists only for untargeted mode=autopilot. That mode uses the federation root's consumption-rates.md and does not double-apply the ceiling inside child runs.

/squad request="continue without a cost ceiling" cost-ceiling=unset

A new run ID with no supplied value starts as not-requested. Ceilings do not carry across run IDs.

The last dispatch took estimated spend above the ceiling#

Enforcement occurs between dispatch units because an in-flight model call cannot be stopped safely and its Scribe handoff must record the consumption. The coordinator records the updated total, writes a terminal over-ceiling round, and starts no later child. This bounded overshoot is expected.

The run is not blocked forever. Set a new ceiling above the current estimate, use cost-ceiling=unset, reduce or reprice the remaining demand, or begin a new run. Re-approving the already exceeded value is not allowed because that value can no longer act as a stopping boundary.

A ceiling of $10 stops immediately after an earlier ungated request spent $10.80#

A ceiling added to an existing run is compared with the run's accumulated estimate, not only the newest request. Remaining budget is max(0, 10.00 - 10.80) = 0.00, so no new dispatch starts. Raise or remove the ceiling, or start a new run if the new request should have an independent budget boundary.

.github still appears in git status after ignoring#

Run git rm -r --cached .github once, then git add .github/workflows (if you track workflows here), then commit.

Azure-icon diagrams (HLD/LLD) won't render#

When the Squad Azure Architect produces a committed PNG/SVG with real Azure icons via the python-diagrams skill, the render needs both Python and the Graphviz dot binary. On a typical Windows dev box two things commonly block it:

• python is the Microsoft Store stub. Running python prints "Python was not found" and does nothing. Use the py launcher, or better, uv — which supplies its own Python and the diagrams package even when neither is on PATH:
  Copy

  uv run --with diagrams python docs/architecture/your-diagram.py

• Graphviz is installed but not on PATH. The render fails with ExecutableNotFound / "dot not found". Install it and reopen the shell, or prepend it for the session:
  Copy

  winget install Graphviz.Graphviz   # then reopen the terminal
  # or, for the current session only:
  $env:PATH = "C:\Program Files\Graphviz\bin;$env:PATH"

Verify the toolchain before authoring with the skill's checker: uv run --with diagrams python .github/skills/python-diagrams/scripts/verify_installation.py. If the diagram still won't render and you only need a quick visual, the architect falls back to an inline Mermaid diagram automatically.

Versioning#

• Releases follow Semantic Versioning.
• See CHANGELOG.md for what is included in each version.
• Consumers can pin to a tagged version, for example apm install "Peter-N91/hve-squad#vX.Y.z".
• Releases are cut by hand when the pending work is judged ready, not on a schedule.
• Between releases, everything already merged is installable from a rolling pre-release: see the current pre-release tag and install command. That tag moves on every merge, so it is for testing rather than for anything you depend on. A pre-release never shows as Latest.
• Installing with no ref at all resolves to the default branch, not to the latest release, and APM warns about the drift. Always pin.

Notes#

• .gitignore ignores apm_modules/, generated .github assets, and keeps .github/workflows/ tracked.
• The package remains reproducible through apm.lock.yaml.