fix: comprehensive state-backend fixes (bundles #1192 + Bug C/F/WI-1/upgrade flow)

.changeset/fix-externalized-state-paths.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+Fix runtime commands to correctly resolve externalized state paths

.changeset/fix-permission-contract.md

@@ -0,0 +1,6 @@
+---
+"@bradygaster/squad-sdk": patch
+"@bradygaster/squad-cli": patch
+---
+
+Fix permission handler to use `approve-once` instead of deprecated `approved` kind, aligning with Copilot CLI v1.0.54+ permission contract

.changeset/fix-state-backend-upgrade-regressions.md

@@ -0,0 +1,38 @@
+---
+"@bradygaster/squad-cli": patch
+"@bradygaster/squad-sdk": patch
+---
+
+Fix state-backend and upgrade regressions (#1163, #1185, #1190, #1191, #1194)
+
+**Bug A (P0) — Permission contract mismatch** (#1191)
+The Copilot SDK changed the valid permission result `kind` from `"approved"` to
+`"approve-once"`. Squad was still returning `{ kind: 'approved' }`, causing all
+agent sessions to fail permission checks immediately. Fixed in:
+- `cli/shell/index.ts` — `approveAllPermissions` handler now returns `{ kind: 'approve-once' }`
+- `adapter/types.ts` — `SquadPermissionRequestResult.kind` union includes `'approve-once'`
+- `adapter/client.ts` — error hint updated to reference the correct `kind` value
+
+**Bug B (P1) — Hard-throw in `resolveStateBackend()` when explicit backend fails** (#1185, #1190)
+When a backend configured in `config.json` failed to initialize (e.g., no git repo
+available), Squad threw a fatal error and refused to start. Now always warns and
+falls back to `local` so operators can fix config without losing work.
+
+**Bug C (P1) — Silent git-notes→two-layer migration** (#1163)
+`normalizeBackendType()` silently mapped `'git-notes'` to `'two-layer'` with no
+user notification. Now emits a `console.warn()` directing users to update their
+`config.json`.
+
+**Bug F (P3) — Windows `toRelative()` drive-letter case mismatch**
+`StateBackendStorageAdapter.toRelative()` used a simple string prefix comparison
+after normalizing separators. On Windows, `C:\` vs `c:\` drive-letter case
+differences caused the prefix check to fail, returning full absolute paths as
+git-notes keys (corruption). Now uses `path.resolve()` and case-insensitive
+comparison on `process.platform === 'win32'`.
+
+**Issue #1194 — Externalized state paths not followed by runtime commands**
+Adds `effectiveSquadDir()` and `resolveStateDir()` helpers that follow the
+`stateLocation: 'external'` marker in `.squad/config.json`. Updates `loop`,
+`watch`, `plugin`, `doctor` commands and `shell` (lifecycle, coordinator, index)
+to use the effective state dir for reading `team.md`, `routing.md`, `agents/`,
+`plugins/`, and other state files.

.changeset/iter9-non-interactive-mcp-load.md

@@ -0,0 +1,5 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+iter-9: inject `--yolo --additional-mcp-config @.mcp.json` in all non-interactive copilot spawns; fix path regression from `.copilot/mcp-config.json` (iter-7) to `.mcp.json` (iter-8 canonical location); add fallback warning when `.mcp.json` is absent; add `--yolo` deduplication guard; document Copilot CLI 1.0.59+ folder-trust security gate

.changeset/state-backend-hardening.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-sdk': patch
+---
+
+State backend hardening: retry with exponential backoff for transient git errors, circuit-breaker to prevent cascading failures, read-only startup verification, and observable error surfacing replacing silent swallowing.

.gitattributes

@@ -7,3 +7,7 @@
 .squad/decisions/decisions.md merge=union
 # Squad: union merge for append-only team state files
 .squad/rai/audit-trail.md merge=union
+
+# Squad: pin LF for YAML to prevent CRLF<->LF flip on Windows checkouts (PR #1200 concern G)
+*.yml text eol=lf
+*.yaml text eol=lf

.github/agents/squad.agent.md

@@ -128,7 +128,7 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
-**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"worktree"` (default), `"git-notes"`, `"orphan"`, `"two-layer"`. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
+**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"local"` (default), `"orphan"`, `"two-layer"`. Legacy alias: `"worktree"` maps to `"local"`. Deprecated: `"git-notes"` maps to `"two-layer"` with a deprecation warning. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
 
 **⚡ Context caching:** After the first message in a session, `team.md`, `routing.md`, and `registry.json` are already in your context. Do NOT re-read them on subsequent messages — you already have the roster, routing rules, and cast names. Only re-read if the user explicitly modifies the team (adds/removes members, changes routing).
 
@@ -607,8 +607,8 @@ prompt: |
   0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools. 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: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`, merge entries into `decisions.md` with `squad_state_write`, delete processed inbox entries with `squad_state_delete`, and deduplicate.
-  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value.
-  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value.
+  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
+  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
   5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
   7. GIT COMMIT: Do not commit mutable squad state. If non-state repo files changed, report them for coordinator handling.

.github/workflows/squad-ci.yml

@@ -310,15 +310,15 @@ jobs:
               const pkgPath = path.join('packages', dir, 'package.json');
               if (!fs.existsSync(pkgPath)) continue;
               const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-              // Allow x.y.z-preview (CONTRIBUTING.md canonical dev suffix); block all other prerelease tags
-              if (pkg.version && /-/.test(pkg.version) && !/^\d+\.\d+\.\d+-preview$/.test(pkg.version)) {
+              // Allow x.y.z, x.y.z-preview, x.y.z-preview.N, x.y.z-insider.N; block all other prerelease tags
+              if (pkg.version && !/^\d+\.\d+\.\d+(-(preview|insider)(\.\d+)?)?$/.test(pkg.version)) {
                 violations.push({ name: pkg.name, version: pkg.version, path: pkgPath });
               }
             }
             if (violations.length > 0) {
               console.error('::error::UNSANCTIONED PRERELEASE VERSION DETECTED — cannot merge to dev/main.');
               violations.forEach(v => console.error('  ' + v.name + '@' + v.version + ' (' + v.path + ')'));
-              console.error('Fix: use x.y.z-preview (CONTRIBUTING.md) or a clean semver. Skip: add \"skip-version-check\" label.');
+              console.error('Fix: use X.Y.Z, X.Y.Z-preview, X.Y.Z-preview.N, or X.Y.Z-insider.N. Skip: add \"skip-version-check\" label.');
               process.exit(1);
             }
             console.log('✅ All package versions are release versions');

.gitignore

@@ -33,3 +33,7 @@ docs/tests/screenshots/
 /images/
 # Squad: ignore runtime state (logs, inbox, sessions)
 .squad/.scratch/
+
+# Squad: PR-1200 picard local artifacts (do not commit)
+.pr-body-new.md
+.followup-issue-body.md

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

@@ -47,8 +47,8 @@ prompt: |
   2. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`,
      merge entries into `decisions.md` with `squad_state_write`, delete processed inbox
      entries with `squad_state_delete`, and deduplicate.
-  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use ISO 8601 UTC timestamp.
-  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use ISO 8601 UTC timestamp.
+  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
+  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
   5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
   7. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized with `squad_state_write` or `squad_state_append`.

.squad-templates/scribe-charter.md

@@ -28,7 +28,7 @@
 
 After every substantial work session:
 
-1. **Log the session** to `log/{timestamp}-{topic}.md` with `squad_state_write`:
+1. **Log the session** to `log/{timestamp}-{topic}.md` with `squad_state_write` (replace `:` with `-` in `{timestamp}` so the filename is valid on all platforms, e.g. `2026-06-02T21-15-30Z`):
    - Who worked
    - What was done
    - Decisions made

.squad-templates/squad.agent.md

@@ -128,7 +128,7 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
-**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"worktree"` (default), `"git-notes"`, `"orphan"`, `"two-layer"`. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
+**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"local"` (default), `"orphan"`, `"two-layer"`. Legacy alias: `"worktree"` maps to `"local"`. Deprecated: `"git-notes"` maps to `"two-layer"` with a deprecation warning. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
 
 **⚡ Context caching:** After the first message in a session, `team.md`, `routing.md`, and `registry.json` are already in your context. Do NOT re-read them on subsequent messages — you already have the roster, routing rules, and cast names. Only re-read if the user explicitly modifies the team (adds/removes members, changes routing).
 
@@ -607,8 +607,8 @@ prompt: |
   0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools. 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: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`, merge entries into `decisions.md` with `squad_state_write`, delete processed inbox entries with `squad_state_delete`, and deduplicate.
-  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value.
-  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value.
+  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
+  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
   5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
   7. GIT COMMIT: Do not commit mutable squad state. If non-state repo files changed, report them for coordinator handling.