fix: context overflow sentinel and coordinator size reduction

.changeset/context-overflow-sentinel.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+Add context overflow sentinel to copilot-instructions.md and reduce squad.agent.md from ~84KB to ~55KB by extracting detailed sections into on-demand reference files. This prevents silent coordinator drop in long sessions when context budget is exceeded.

.github/copilot-instructions.md

@@ -2,6 +2,25 @@
 
 You are working on **Squad**, an AI team framework. Follow these guidelines for autonomous issue work.
 
+## Squad Coordinator Check
+
+**IMPORTANT — run this check on EVERY session start, before doing any work:**
+
+Look for the exact canary token `SQUAD_COORDINATOR_CANARY_a8f3` in your agent_instructions. This token is placed at the end of `squad.agent.md` — if it's missing, the coordinator either failed to load or was truncated.
+
+**When the canary token is missing, you MUST:**
+1. **STOP** — do not proceed with any work requests silently.
+2. **WARN the user** with this exact message:
+   ```
+   ⚠️ Squad coordinator failed to load (context budget exceeded or file truncated).
+   This session has NO squad safety rails — no agent routing, no PRs, no branch protection.
+   → Start a fresh session to restore Squad.
+   → If this keeps happening, reduce conversation history before starting.
+   ```
+3. **Refuse task requests** until the user acknowledges. Do NOT fall back to working as a plain agent — that bypasses all squad safety (PRs, branch protection, reviewer gates).
+
+This check exists because `squad.agent.md` is a large file that can be silently dropped when context is tight. Without it, the session runs as a vanilla Copilot agent with none of the team's safety rules.
+
 ## Team Context
 
 1. Read `.squad/team.md` for roster, roles, and your capability profile.

.squad-templates/after-agent-reference.md

@@ -0,0 +1,52 @@
+# After Agent Work — Post-Work Reference
+
+<!-- KNOWN PLATFORM BUGS: (1) "Silent Success" — ~7-10% of background spawns complete
+     file writes but return no text. Mitigated by RESPONSE ORDER + filesystem checks.
+     (2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
+     post-work turn + Scribe delegation + compact result presentation. -->
+
+## Post-Work Steps
+
+After each batch of agent work:
+
+1. **Collect results** via `read_agent` (wait: true, timeout: 300).
+
+2. **Silent success detection** — when `read_agent` returns empty/no response:
+   - Check filesystem: history.md modified? New decision inbox files? Output files created?
+   - Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
+   - No files → `"❌ {Name} failed — no work product."` Consider re-spawn.
+
+3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
+
+4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
+
+```
+agent_type: "general-purpose"
+model: "claude-haiku-4.5"
+mode: "background"
+name: "scribe"
+description: "📋 Scribe: Log session & merge decisions"
+prompt: |
+  You are the Scribe. Read .squad/agents/scribe/charter.md.
+  TEAM ROOT: {team_root}
+  CURRENT_DATETIME: {current_datetime}
+
+  SPAWN MANIFEST: {spawn_manifest}
+
+  Tasks (in order):
+  0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements.
+  1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
+  2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate.
+  3. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp.
+  4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp.
+  5. CROSS-AGENT: Append team updates to affected agents' history.md.
+  6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
+  7. GIT COMMIT: Stage only the exact `.squad/` files Scribe wrote in this session. Use `git status --porcelain` filtered to allowed paths (decisions.md, decisions-archive.md, agents/{name}/history.md, agents/{name}/history-archive.md, log/*, orchestration-log/*). Stage each file individually with `git add -- <path>`. Handle renames by extracting destination path (`-replace '^.* -> ',''`). Commit with -F (write msg to temp file). Skip if nothing staged. ⚠️ NEVER use `git add .squad/` or broad globs.
+  8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized.
+
+  Never speak to user. ⚠️ End with plain text summary after all tool calls.
+```
+
+5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
+
+6. **Ralph check:** If Ralph is active, after chaining any follow-up work, IMMEDIATELY run Ralph's work-check cycle (Step 1). Do NOT stop. Do NOT wait for user input. Ralph keeps the pipeline moving until the board is clear.

.squad-templates/casting-reference.md

@@ -1,5 +1,7 @@
 # Casting Reference
 
+> **Note:** This content is new specification material that fills a gap in the original `squad.agent.md`. The coordinator referenced this file but the content was never previously written inline. This is additive, not extracted.
+
 On-demand reference for Squad's casting system. Loaded during Init Mode or when adding team members.
 
 ## Universe Table

.squad-templates/client-compatibility-reference.md

@@ -0,0 +1,42 @@
+# Client Compatibility Reference
+
+## Platform Detection
+
+Before spawning agents, determine the platform by checking available tools:
+
+1. **CLI mode** — `task` tool is available → full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`.
+
+2. **VS Code mode** — `runSubagent` or `agent` tool is available → conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically — no `read_agent` needed.
+
+3. **Fallback mode** — neither `task` nor `runSubagent`/`agent` available → work inline. Do not apologize or explain the limitation. Execute the task directly.
+
+If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface).
+
+## VS Code Spawn Adaptations
+
+When in VS Code mode, the coordinator changes behavior in these ways:
+
+- **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter — pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI.
+- **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling.
+- **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains — they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker.
+- **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable.
+- **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done.
+- **`read_agent`:** Skip entirely. Results return automatically when subagents complete.
+- **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools.
+- **`description`:** Drop it. The agent name is already in the prompt.
+- **Prompt content:** Keep ALL prompt structure — charter, identity, task, hygiene, response order blocks are surface-independent.
+
+## Feature Degradation Table
+
+| Feature | CLI | VS Code | Degradation |
+|---------|-----|---------|-------------|
+| Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None — equivalent concurrency |
+| Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent |
+| Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group |
+| Launch table UX | Show table → results later | Skip table → results with response | UX only — results are correct |
+| SQL tool | Available | Not available | Avoid SQL in cross-platform code paths |
+| Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block — harmless if unnecessary |
+
+## SQL Tool Caveat
+
+The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.squad/` files) for anything that must work everywhere.

.squad-templates/copilot-instructions.md

@@ -2,6 +2,25 @@
 
 You are working on a project that uses **Squad**, an AI team framework. When picking up issues autonomously, follow these guidelines.
 
+## Squad Coordinator Check
+
+**IMPORTANT — run this check on EVERY session start, before doing any work:**
+
+Look for the exact canary token `SQUAD_COORDINATOR_CANARY_a8f3` in your agent_instructions. This token is placed at the end of `squad.agent.md` — if it's missing, the coordinator either failed to load or was truncated.
+
+**When the canary token is missing, you MUST:**
+1. **STOP** — do not proceed with any work requests silently.
+2. **WARN the user** with this exact message:
+   ```
+   ⚠️ Squad coordinator failed to load (context budget exceeded or file truncated).
+   This session has NO squad safety rails — no agent routing, no PRs, no branch protection.
+   → Start a fresh session to restore Squad.
+   → If this keeps happening, reduce conversation history before starting.
+   ```
+3. **Refuse task requests** until the user acknowledges. Do NOT fall back to working as a plain agent — that bypasses all squad safety (PRs, branch protection, reviewer gates).
+
+This check exists because `squad.agent.md` is a large file that can be silently dropped when context is tight. Without it, the session runs as a vanilla Copilot agent with none of the team's safety rules.
+
 ## Team Context
 
 Before starting work on any issue:

.squad-templates/model-selection-reference.md

@@ -0,0 +1,101 @@
+# Model Selection Reference
+
+## 4-Layer Hierarchy (Details)
+
+Check these layers in order — first match wins:
+
+**Layer 0 — Persistent Config (`.squad/config.json`):** On session start, read `.squad/config.json`. If `agentModelOverrides.{agentName}` exists, use that model for this specific agent. Otherwise, if `defaultModel` exists, use it for ALL agents. This layer survives across sessions — the user set it once and it sticks.
+
+- **When user says "always use X" / "use X for everything" / "default to X":** Write `defaultModel` to `.squad/config.json`. Acknowledge: `✅ Model preference saved: {model} — all future sessions will use this until changed.`
+- **When user says "use X for {agent}":** Write to `agentModelOverrides.{agent}` in `.squad/config.json`. Acknowledge: `✅ {Agent} will always use {model} — saved to config.`
+- **When user says "switch back to automatic" / "clear model preference":** Remove `defaultModel` (and optionally `agentModelOverrides`) from `.squad/config.json`. Acknowledge: `✅ Model preference cleared — returning to automatic selection.`
+
+**Layer 1 — Session Directive:** Did the user specify a model for this session? ("use opus for this session", "save costs"). If yes, use that model. Session-wide directives persist until the session ends or contradicted.
+
+**Layer 2 — Charter Preference:** Does the agent's charter have a `## Model` section with `Preferred` set to a specific model (not `auto`)? If yes, use that model.
+
+**Layer 3 — Task-Aware Auto-Selection:** Use the governing principle: **cost first, unless code is being written.** Match the agent's task to determine output type, then select accordingly:
+
+| Task Output | Model | Tier | Rule |
+|-------------|-------|------|------|
+| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. |
+| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. |
+| NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. |
+| Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. |
+
+**Role-to-model mapping** (applying cost-first principle):
+
+| Role | Default Model | Why | Override When |
+|------|--------------|-----|---------------|
+| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` |
+| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` |
+| Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku |
+| Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku |
+| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` |
+| Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
+| DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — |
+| Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) |
+| Git / Release | `claude-haiku-4.5` | Mechanical ops — changelogs, tags, version bumps | — (never bump mechanical ops) |
+
+**Task complexity adjustments** (apply at most ONE — no cascading):
+- **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents)
+- **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps
+- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines)
+- **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection
+
+**Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced.
+
+## Fallback Chains
+
+If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback.
+
+```
+Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param)
+Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param)
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param)
+```
+
+`(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works.
+
+**Fallback rules:**
+- If the user specified a provider ("use Claude"), fall back within that provider only before hitting nuclear
+- Never fall back UP in tier — a fast/cheap task should not land on a premium model
+- Log fallbacks to the orchestration log for debugging, but never surface to the user unless asked
+
+## Passing the Model to Spawns
+
+Pass the resolved model as the `model` parameter on every `task` tool call:
+
+```
+agent_type: "general-purpose"
+model: "{resolved_model}"
+mode: "background"
+name: "{name}"
+description: "{emoji} {Name}: {brief task summary}"
+prompt: |
+  ...
+```
+
+Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default.
+
+If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
+
+## Spawn Output Format
+
+When spawning, include the model in your acknowledgment:
+
+```
+🔧 Fenster (claude-sonnet-4.6) — refactoring auth module
+🎨 Redfoot (claude-opus-4.5 · vision) — designing color system
+📋 Scribe (claude-haiku-4.5 · fast) — logging session
+⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal
+📝 McManus (claude-haiku-4.5 · fast) — updating docs
+```
+
+Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name.
+
+## Valid Models (Current Platform Catalog)
+
+Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `claude-opus-4.5`
+Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gemini-3-pro-preview`
+Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1`