feat(identity): hardening + kickstart sync quick wins

.changeset/auto-install-app.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+Auto-open browser for GitHub App installation after manifest creation, with polling fallback

.changeset/env-var-credentials.md

@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-sdk': minor
+'@bradygaster/squad-cli': minor
+---
+
+Support environment variable credentials for CI/CD workflows. `resolveToken()` now checks `SQUAD_{ROLE}_APP_ID`, `SQUAD_{ROLE}_PRIVATE_KEY`, and `SQUAD_{ROLE}_INSTALLATION_ID` before reading from filesystem. Added `squad identity export` subcommand to output `gh secret set` commands.

.changeset/exec-with-role-token.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-sdk': minor
+---
+
+Add `execWithRoleToken` and `withRoleToken` utilities for running shell commands or async functions under a role's GitHub App installation token, with graceful fallback and guaranteed GH_TOKEN restoration.

.changeset/gitignore-identity-secrets.md

@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-sdk': patch
+'@bradygaster/squad-cli': patch
+---
+
+Auto-ignore identity secrets on `squad init` and `squad upgrade`. `.squad/identity/keys/` (GitHub App private PEMs), `.squad/identity/apps/` (per-role installation metadata), `.squad/identity/config.json`, and per-role token caches matching `.squad-*-token` / `.squad-*-token.json` (e.g. `.squad-hermes-token` holding `ghs_*` installation tokens) are now appended to `.gitignore` so they cannot be accidentally committed.

.changeset/identity-hardening.md

@@ -0,0 +1,17 @@
+---
+"@bradygaster/squad-sdk": minor
+"@bradygaster/squad-cli": minor
+---
+
+feat(identity): hardening + kickstart sync quick wins
+
+- **Structured error reporting** (`TokenResolveError`): typed `kind` field (`not-configured` | `runtime`) with human message
+- **Fetch timeout** (H-01): `AbortController` + `Promise.race` 10-second cap on installation token requests
+- **PEM validation** (H-02): `createPrivateKey()` validates key before signing; rejects with descriptive error
+- **Partial env detection** (H-03): logs loud error when only 1-2 of 3 required env vars are set
+- **Mock hook** (H-07): `SQUAD_IDENTITY_MOCK=1` bypasses real credentials; `SQUAD_IDENTITY_MOCK_TOKEN` sets custom token value
+- **Role aliases**: `resolveRoleSlug()` maps shorthand aliases (`core`, `ui`, `qa`, `ops`, `writer`, `sec`, `ml`, `note`) to canonical role slugs
+- **Scribe role**: `'scribe'` added to `RoleSlug` union; `ALL_ROLES` constant exported from SDK
+- **ESM dual-mode guard**: `isCliInvocation` IIFE prevents CLI side-effects when `resolve-token.mjs` is imported as a module
+- **`resolveTokenWithDiagnostics()`**: full diagnostic result type; `clearTokenCache()` for test isolation
+- **Cache key fix**: token cache keyed by `${projectRoot}:${roleKey}` to prevent cross-test pollution

.changeset/identity-import-multi-repo.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+Add `--import` flag to `squad identity create` for multi-repo identity reuse. When a GitHub App already exists from another repo, `--import /path/to/source-repo` copies credentials and triggers installation on the current repo. Also improves error handling when app name is already taken, suggesting the `--import` flag.

.changeset/identity-module.md

@@ -0,0 +1,10 @@
+---
+'@bradygaster/squad-sdk': minor
+'@bradygaster/squad-cli': minor
+---
+
+Add identity module for GitHub App-based agent identity
+
+New SDK module (`identity/`) with role slug resolution, credential storage,
+and comment/commit attribution formatting. New CLI command `squad identity status`
+shows configured identity tier, app registrations, and key status.

.changeset/identity-rotate-command.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+Add `squad identity rotate --role <role>` command for key rotation. Opens GitHub App settings for manual key regeneration, and supports `--import path/to/key.pem` to import a new PEM file and clear the token cache.

.changeset/identity-token-lifecycle.md

@@ -0,0 +1,6 @@
+---
+'@bradygaster/squad-sdk': minor
+'@bradygaster/squad-cli': minor
+---
+
+Add token lifecycle (JWT generation, installation token exchange, caching) and `squad identity create` command for GitHub App Manifest flow

.changeset/team-aware-identity-create.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+`squad identity create` is now team-aware: when run with no flags and `.squad/team.md` exists, it auto-detects roles from the team roster, deduplicates them, and creates GitHub Apps only for the team's actual roles.

.changeset/wire-gh-token-spawn.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': minor
+---
+
+Wire GH_TOKEN injection into agent spawn logic. When an agent is spawned, its role is mapped to a canonical identity slug via `resolveRoleSlug()`, and `resolveToken()` is called to obtain an installation token. If a token is found, `process.env.GH_TOKEN` is set before creating the session so that `gh` CLI calls automatically use the bot identity. The token is always restored/cleaned up in a `finally` block. Identity failures are gracefully ignored — spawn works exactly as before when no identity is configured.

.github/agents/squad.agent.md

@@ -340,6 +340,10 @@ prompt: |
   **WORKTREE:** Working in `{WORKTREE_PATH}`. All operations relative to this path. Do NOT switch branches.
   {% endif %}
 
+  {only if identity configured:}
+  GIT IDENTITY: Commit as `{app_slug}[bot]`. Push with token: `TOKEN=$(node {team_root}/.squad/scripts/resolve-token.mjs '{role_slug}'); if [ -n "$TOKEN" ]; then git push https://x-access-token:${TOKEN}@github.com/{owner}/{repo}.git {branch}; else git push; fi`. PR: `if [ -n "$TOKEN" ]; then GH_TOKEN=$TOKEN gh pr create --repo {owner}/{repo} ...; else gh pr create ...; fi`. PR body: `🤖 [{app_slug}](https://github.com/apps/{app_slug})`.
+  {end identity block}
+
   TASK: {specific task description}
   TARGET FILE(S): {exact file path(s)}
 
@@ -694,6 +698,30 @@ The coordinator passes a **spawn manifest** (who ran, why, what mode, outcome) t
 
 Each entry records: agent routed, why chosen, mode (background/sync), files authorized to read, files produced, and outcome. See `.squad/templates/orchestration-log.md` for the field format.
 
+### Pre-Spawn: Identity Resolution
+
+When spawning an agent that may do git operations (commit, push, PR), resolve the identity context:
+
+1. **Check identity config:** Does `.squad/identity/config.json` exist?
+   - **No** → omit the identity block entirely. Agents use default auth.
+   - **Yes** → read the config to get the tier and app registrations.
+
+2. **Resolve the role slug:** Map the agent's role to an identity role slug using `resolveRoleSlug()` semantics:
+   - Lead/Architect → `lead`
+   - Backend/Core Dev → `backend` (falls back to `lead` if no backend app)
+   - Frontend → `frontend` (falls back to `lead`)
+   - Tester → `tester` (falls back to `lead`)
+   - For `shared` tier: all agents use the single shared app
+   - For `per-role` tier: try role-specific app first, fall back to `lead`
+
+3. **Get the app slug:** From the identity config, look up the app registration for the resolved role slug. The `appSlug` is the GitHub App's URL slug (e.g., `sabbour-squad-lead`).
+
+4. **Get the repo owner/name:** From the git remote origin URL, parse `{owner}/{repo}`.
+
+5. **Include the identity block** in the spawn prompt with the resolved values.
+
+**If any step fails, omit the identity block silently.** Identity is always graceful — never block a spawn because identity resolution failed.
+
 ### Pre-Spawn: Worktree Setup
 
 When spawning an agent for issue-based work (user request references an issue number, or agent is working on a GitHub issue):
@@ -811,6 +839,27 @@ prompt: |
   MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable.
   {end MCP block}
 
+  {only if .squad/identity/config.json exists — omit entirely if no identity configured:}
+  ## GIT IDENTITY — Bot Authentication
+  This project uses GitHub App identity for git operations. When pushing code or creating PRs, authenticate as the bot.
+
+  **Resolve token at runtime:**
+  ```bash
+  TOKEN=$(node {team_root}/.squad/scripts/resolve-token.mjs '{role_slug}')
+  ```
+  If token resolution fails (no identity configured), fall back to default git auth — do NOT block on identity.
+
+  **Git commit identity:**
+  - `git -c user.name="{app_slug}[bot]" -c user.email="{app_slug}[bot]@users.noreply.github.com" commit ...`
+
+  **Push:** `if [ -n "$TOKEN" ]; then git push https://x-access-token:${TOKEN}@github.com/{owner}/{repo}.git {branch}; else git push; fi`
+  **PR create:** `if [ -n "$TOKEN" ]; then GH_TOKEN=$TOKEN gh pr create --repo {owner}/{repo} ...; else gh pr create ...; fi`
+  **PR body must include:** `🤖 Created by [{app_slug}](https://github.com/apps/{app_slug})`
+
+  **Never log or echo the token value.**
+  **Parallel safety:** Each agent resolves exactly one token. If you need multiple tokens in one shell block (e.g., batch operations), use newline-separated statements — NOT `&&` chains — before backgrounding with `&`. Bash variable scoping causes `&&`-chained assignments to lose values in child subshells.
+  {end identity block}
+
   **Requested by:** {current user name}
 
   INPUT ARTIFACTS: {list exact file paths to review/modify}

.gitignore

@@ -20,6 +20,9 @@ docs/src/content/docs/reference/api/
 
 # Docs test screenshots (local verification only)
 docs/tests/screenshots/
+# Squad: private keys must never be committed
+.squad/identity/keys/
+
 # Squad: SubSquad activation file (local to this machine)
 .squad-workstream
 .squad/.first-run