fix: three-state coordinator canary + HEAD canary (Closes #1461)#1517
Open
bradygaster wants to merge 14 commits into
Open
fix: three-state coordinator canary + HEAD canary (Closes #1461)#1517bradygaster wants to merge 14 commits into
bradygaster wants to merge 14 commits into
Conversation
Add a HEAD canary near the start of the coordinator prompt while retaining the EOF canary. Update the Canary Check to skip non-coordinator agents, accept fully loaded coordinators, and halt only on positive truncation detection. Closes #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Contributor
🟠 Impact Analysis — PR #1517Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (3 files)
docs (2 files)
root (3 files)
scripts (1 file)
squad-cli (2 files)
squad-sdk (2 files)
templates (2 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 🔧 Infrastructure
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 14 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 (4 outdated skipped) |
| ✅ | CI passing | All checks passing |
Files Changed (15 files, +896 −12)
| File | +/− |
|---|---|
.changeset/canary-false-positives.md |
+6 −0 |
.github/agents/squad.agent.md |
+2 −0 |
.github/size-budget.json |
+10 −0 |
.github/workflows/size-regression-report.yml |
+44 −0 |
.squad-templates/copilot-instructions.md |
+7 −3 |
.squad-templates/squad.agent.md |
+2 −0 |
docs/canary-identity-matrix.md |
+80 −0 |
docs/open-issue-runtime-identity-beacon.md |
+166 −0 |
packages/squad-cli/templates/copilot-instructions.md |
+7 −3 |
packages/squad-cli/templates/squad.agent.md.template |
+2 −0 |
packages/squad-sdk/templates/copilot-instructions.md |
+7 −3 |
packages/squad-sdk/templates/squad.agent.md.template |
+2 −0 |
scripts/size-regression-guard.mjs |
+552 −0 |
templates/copilot-instructions.md |
+7 −3 |
templates/squad.agent.md.template |
+2 −0 |
Total: +896 −12
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Squad’s coordinator canary mechanism to reduce false halts in spawned/non-Squad agents by adding a distinct HEAD canary and switching the canary check to a three-state, coordinator-scoped flow. The change is applied across canonical templates and all mirrored template locations, with a patch changeset added for CLI/SDK releases.
Changes:
- Add
SQUAD_COORDINATOR_CANARY_HEAD_b7d2immediately after coordinator front matter (retain EOF canarySQUAD_COORDINATOR_CANARY_a8f3). - Rewrite
copilot-instructions.mdcanary logic into a 3-state decision: non-coordinator agents skip silently; fully loaded coordinators proceed; positive truncation halts with a specific warning. - Sync workflow wiring guide + appendices across template mirrors and add a patch changeset.
Show a summary per file
| File | Description |
|---|---|
| templates/squad.agent.md.template | Adds HEAD canary to coordinator template. |
| templates/copilot-instructions.md | Updates canary check to three-state coordinator-scoped flow. |
| templates/workflow-wiring-guide.md | Sync formatting/content with canonical template mirror set. |
| templates/workflow-wiring-appendix-a-code-reviewer.md | Sync formatting/content with canonical template mirror set. |
| templates/workflow-wiring-appendix-b-documenter.md | Sync formatting/content with canonical template mirror set. |
| packages/squad-cli/templates/squad.agent.md.template | Mirror: adds HEAD canary. |
| packages/squad-cli/templates/copilot-instructions.md | Mirror: updates three-state canary check instructions. |
| packages/squad-cli/templates/workflow-wiring-guide.md | Mirror sync of wiring guide. |
| packages/squad-cli/templates/workflow-wiring-appendix-a-code-reviewer.md | Mirror sync of appendix A. |
| packages/squad-cli/templates/workflow-wiring-appendix-b-documenter.md | Mirror sync of appendix B. |
| packages/squad-sdk/templates/squad.agent.md.template | Mirror: adds HEAD canary. |
| packages/squad-sdk/templates/copilot-instructions.md | Mirror: updates three-state canary check instructions. |
| packages/squad-sdk/templates/workflow-wiring-guide.md | Mirror sync of wiring guide. |
| packages/squad-sdk/templates/workflow-wiring-appendix-a-code-reviewer.md | Mirror sync of appendix A. |
| packages/squad-sdk/templates/workflow-wiring-appendix-b-documenter.md | Mirror sync of appendix B. |
| .squad-templates/squad.agent.md | Canonical: adds HEAD canary to coordinator prompt. |
| .squad-templates/copilot-instructions.md | Canonical: updates three-state canary check instructions. |
| .github/agents/squad.agent.md | Special mirror: adds HEAD canary to coordinator agent file. |
| .changeset/canary-false-positives.md | Patch changeset for CLI/SDK describing the canary fix. |
Review details
- Files reviewed: 10/19 changed files
- Comments generated: 4
- Review effort level: Low
Comment on lines
+9
to
+13
| Inspect your `agent_instructions` for the coordinator canaries: | ||
|
|
||
| **When the token is missing, you MUST:** | ||
| 1. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **absent**, you are **not** running the Squad coordinator prompt. You are a spawned sub-agent, a `squad:{member}` coding agent, or a non-Squad/third-party agent. **Skip this check entirely. Do not warn, do not halt.** Proceed with your assigned task normally. | ||
| 2. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** and the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **present**, the coordinator prompt loaded fully. Proceed with normal Squad behavior. | ||
| 3. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** but the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **absent**, the coordinator prompt loaded but was **truncated** before the end. |
Comment on lines
+9
to
+13
| Inspect your `agent_instructions` for the coordinator canaries: | ||
|
|
||
| **When the token is missing, you MUST:** | ||
| 1. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **absent**, you are **not** running the Squad coordinator prompt. You are a spawned sub-agent, a `squad:{member}` coding agent, or a non-Squad/third-party agent. **Skip this check entirely. Do not warn, do not halt.** Proceed with your assigned task normally. | ||
| 2. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** and the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **present**, the coordinator prompt loaded fully. Proceed with normal Squad behavior. | ||
| 3. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** but the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **absent**, the coordinator prompt loaded but was **truncated** before the end. |
Comment on lines
+9
to
+13
| Inspect your `agent_instructions` for the coordinator canaries: | ||
|
|
||
| **When the token is missing, you MUST:** | ||
| 1. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **absent**, you are **not** running the Squad coordinator prompt. You are a spawned sub-agent, a `squad:{member}` coding agent, or a non-Squad/third-party agent. **Skip this check entirely. Do not warn, do not halt.** Proceed with your assigned task normally. | ||
| 2. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** and the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **present**, the coordinator prompt loaded fully. Proceed with normal Squad behavior. | ||
| 3. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** but the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **absent**, the coordinator prompt loaded but was **truncated** before the end. |
Comment on lines
+9
to
+13
| Inspect your `agent_instructions` for the coordinator canaries: | ||
|
|
||
| **When the token is missing, you MUST:** | ||
| 1. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **absent**, you are **not** running the Squad coordinator prompt. You are a spawned sub-agent, a `squad:{member}` coding agent, or a non-Squad/third-party agent. **Skip this check entirely. Do not warn, do not halt.** Proceed with your assigned task normally. | ||
| 2. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** and the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **present**, the coordinator prompt loaded fully. Proceed with normal Squad behavior. | ||
| 3. If the HEAD canary `SQUAD_COORDINATOR_CANARY_HEAD_b7d2` is **present** but the EOF canary `SQUAD_COORDINATOR_CANARY_a8f3` is **absent**, the coordinator prompt loaded but was **truncated** before the end. |
Adds scripts/size-regression-guard.mjs (report-only, exits 0): Tier-1 artifact byte/token ceiling and Tier-2 governance-golden regression (head+eof canaries, dispatch-STOP gate, STATE_BACKEND, reviewer-lockout, mention-guard), plus a local-estimate-only net-resident dimension and a reviewed-override budget file (.github/size-budget.json). Includes --backtest mode and a report-only CI workflow. Part of #1461; adds to PR #1517. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Reverts spurious LF->CRLF churn on workflow-wiring mirror files introduced by the sync-templates run in 197b19a. Content-identical; restores mirror parity with LF canonicals so template-sync check mode passes and the PR delta reflects only intended changes. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
…etector Records the peer-agreed reclassification: the dual markers detect payload integrity (loaded vs truncated) within an independently-known Squad session only; "no markers" is externally unobservable and is NOT a success state. Documents the owning runtime surface for cases 3/4 (host-level untruncatable pre-ingestion identity beacon) and adds the payload-removal test requirement. squad.agent.md artifact sha256 unchanged (525a919f...). Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Clarifies that the runtime beacon must be captured when the host resolves the custom agent selection, before any .agent.md file read or prompt assembly. Documents that packages/squad-cli only installs and passes through --agent selection while Copilot CLI owns the resolver/read path, and adds the four-fixture runtime acceptance matrix. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Defines the runtime identity beacon as an explicit host-owned state machine with separate selection, payload-read, and prompt-attach fields. Adds the decision function and four-fixture acceptance test requiring raw selection records and status transitions. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Extends the host-owned coordinator identity state machine with attach_integrity computed on the assembled artifact. Documents the refined decision function, frozen transition invariants, and ordered event-sequence acceptance requirements for assembly-time truncation. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Clarifies payload_read_status=TRUNCATED as read-dimension only and maps attach clipping to LOADED plus ATTACHED_PARTIAL. Updates the state machine and matrix to fail closed: only selected+LOADED+ATTACHED_FULL+INTACT succeeds; absent or partial evidence becomes UNKNOWN/halt. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Clarifies that attach integrity can only compare against an expected SHA from a trusted host-side registry keyed by agent and client version. Adds selection-record version keys and distinguishes host-computed attached_sha from trusted-registry expected_sha. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Restructures the host-owned runtime beacon into orthogonal transport and release verdicts. Transport integrity is the fail-closed enforcement axis, while release integrity reports verified, mismatched, or unregistered artifacts without false-halting healthy local or fresh artifacts. Adds six acceptance fixtures and the Caveman telemetry join protocol. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Splits transport halt outcomes into HALT_CORRUPT for proven read/assembly loss and UNKNOWN_HALT for insufficient evidence. Keeps release mismatch and unregistered-local outcomes distinct so telemetry can measure corruption, missing evidence, and false-halt risk separately. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
Adds host tool inventory to the preregistered execution envelope. Defines per-turn inventory snapshots, manifest hashing provenance, inventory_drift outcomes, variant/quarantine rules, and telemetry-join invalidation semantics orthogonal to artifact integrity. Refs #1461 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 09d05820-0b7e-482b-b942-c86b1225dcf9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
SQUAD_COORDINATOR_CANARY_HEAD_b7d2immediately after coordinator front matter while retaining EOF canarySQUAD_COORDINATOR_CANARY_a8f3.Closes #1461. Mitigates #1498 false-halts for spawned/non-Squad agents.
Validation
node scripts/sync-templates.mjsnpx vitest run test/template-sync.test.ts --reporter=dot(249 passed)SKIP_BUILD_BUMP=1 npm run build(after using a local node_modules overlay so workspace package symlinks resolve to this worktree)npm test -- --reporter=dot --silent: 7 failures in pre-existing externalized-state/acceptance areas unrelated to this template-only change; no source/test files changed.