Session Init Reference

If the environment variable SQUAD_NO_UPDATE_CHECK is set to 1, skip Step 1 entirely and show the normal greeting. This is the same kill switch as the upstream CLI banner — one opt-out disables both.

1.2 Channel Detection

Read the stamped version from the <!-- version: X --> HTML comment at the top of squad.agent.md (or from the - **Version:** X identity line as fallback). Classify the channel:

Store the stamped version as currentVersion and the detected channel.

1.3 Hybrid Cache Strategy

The strategy differs by channel to avoid redundant network calls for the common (latest) case.

For latest channel — read upstream OS-specific cache

The upstream Squad CLI (self-update.ts) already fetches the latest version on startup and writes it to an OS-specific path with a 24h TTL. Read that cache instead of making a new npm call.

One-liner to read the upstream cache:

Output semantics:

• Valid JSON {"latestVersion":"X.Y.Z","checkedAt":N} → cache hit; use latestVersion
• STALE → cache expired (older than 24h); treat as no data
• MISS → cache missing or corrupt; treat as no data

On STALE or MISS, show the normal greeting (no notice). Do not make an independent npm call for latest-channel users — the upstream CLI will refresh the cache on its next run.

OS-specific cache path for reference:

• Windows: %APPDATA%\squad-cli\update-check.json
• Linux: ~/.config/squad-cli/update-check.json
• macOS: ~/Library/Application Support/squad-cli/update-check.json

For insider / preview channels — own probe with repo-local cache

The upstream cache only stores the latest dist-tag and is not useful for pre-release channels. Use a separate probe.

Step A — Check repo-local cache:

Read .squad/.cache/version-check.json. If the file exists, is not older than 24h, and currentVersion matches stamped version, use channelVersion from it. Skip the npm probe.

Repo-local cache schema:

Step B — npm probe (on cache miss / stale / version mismatch):

• Timeout: 5 seconds. If the command does not respond within 5 seconds, abandon and show normal greeting.
• On success: extract dist-tags[channel] (e.g., dist-tags["insider"]). Write .squad/.cache/version-check.json with the schema above. Create .squad/.cache/ if it does not exist.
• On any error (network failure, registry unreachable, parse error): show normal greeting.

1.4 Comparison

Compare currentVersion against the resolved latestVersionForChannel using semver ordering (pre-release suffixes sort lower than their release counterpart, e.g., 0.9.5-insider.1 < 0.9.5).

• latestVersionForChannel > currentVersion → update available
• Equal or older → no notice

1.5 Greeting Append

When an update is available, append to the normal greeting (on the same line, separated by ·):

Example complete greeting line:

Do not mention the update check, the cache, or the mechanism. Just the notice.

1.6 Upgrade Flow

Trigger phrases (case-insensitive, match anywhere in user message):

• “upgrade squad”
• “update squad”
• “what’s new” (when a version notice has been shown in this session)
• “install the update”
• “yes upgrade”

Flow:

1. Confirm — ask the user to confirm before running the upgrade:

   “I’ll run squad upgrade now. This overwrites squad.agent.md and casting files but preserves config.json, team.md, decisions.md, and all agent history. Ready?” Wait for affirmative response before proceeding.

2. Run upgrade:

   Copy

   squad upgrade

   Capture output. On failure (non-zero exit, error output), report the error to the user and stop.

3. What’s-new digest — after successful upgrade, fetch and summarize release notes:

   Copy

   gh api repos/bradygaster/squad/releases --jq '[.[] | select(.tag_name | test("^v"))]'

   • Extract 3–6 bullet points from releases between oldVersion and newVersion, inclusive.
   • Priority: feat entries first, then fix, then docs.
   • Format:

     Copy

     📋 What's new in v{newVersion}:
     • {feat summary 1}
     • {feat summary 2}
     • {fix summary}

   • Fallback chain:
     • gh not authenticated → “See full release notes at: https://github.com/bradygaster/squad/releases (opens in a new tab)“
     • No releases found → “No release notes found for this version range.”
     • Network failure → link to releases page

4. Restart prompt — after showing the digest, prompt the user:

   “squad.agent.md has been updated. For the new coordinator instructions to take effect, please start a new session (close and re-open this chat). Your team state and decisions are unchanged.”

1.7 Failure Modes

Every failure path ends at “show normal greeting.” The update check never interrupts or delays the session.

(Future steps reserved)

• Step 2: <reserved> — e.g., dependency drift check
• Step 3: <reserved> — e.g., repo policy / state-backend audit