feat(headless-examples): adopt SYNADIA_* identity env vars

[M64GitHub]

Seventh PR in the identity env var series — covers the two published headless controller examples, which register full 5-token identities (agents.*.pi-headless/cc-headless.<owner>.<name>) but used a bare per-example env prefix (a fifth naming family).

What

owner: --owner > SYNADIA_PI_HEADLESS_OWNER > SYNADIA_OWNER > PI_HEADLESS_OWNER (legacy) > $USER > "anon"
name:  --name  > SYNADIA_PI_HEADLESS_NAME  > SYNADIA_NAME  > PI_HEADLESS_NAME  (legacy) > config "name" > "control"

claude-code-headless mirrors with SYNADIA_CLAUDE_CODE_HEADLESS_* / legacy CLAUDE_CODE_HEADLESS_* (hyphens → underscores per the convention settled in #154). Purely additive — legacy vars keep working. cc-headless's fail-fast invalid-owner error message now names the SYNADIA_* overrides. READMEs + CHANGELOGs updated.

Note: env plumbing only — no SDK surface involved, so per the release ladder this does not depend on any npm publish.

Verification

• cc-headless tsc --noEmit clean; pi-headless shows the same single pre-existing error as unmodified main (type-only @earendil-works/pi-ai import in pi-session-manager.ts, module absent from the transitive install — untouched by this PR, worth its own look).
• Live smoke against an isolated nats-server: controllers register agents.prompt.pi-headless.peragent.ctl1 and agents.prompt.cc-headless.peragent.ctl2 — per-agent vars beating fleet-wide (SYNADIA_OWNER=fleet) and legacy (PI_HEADLESS_OWNER=legacy, PI_HEADLESS_NAME=old) exactly per the chain.

🤖 Generated with Claude Code

[M64GitHub]

@claude - please review

[synadia-claude-reviewer]

Claude finished @M64GitHub's task in 1m 17s —— View job

---

PR Review: feat(headless-examples): adopt SYNADIA_* identity env vars

• Read changed files
• Review config.ts changes
• Review README/CHANGELOG updates
• Post final review

---

Summary

The implementation is clean, correct, and consistent across both examples. The identity chain (CLI > per-agent > fleet-wide > legacy > config/fallback) is identical in structure to the pattern from the earlier PRs in this series, and legacy vars are correctly preserved at the right priority level. No concerns with the core logic.

One minor oversight to address before merge:

---

Finding: cc-headless name error message not updated

In examples/claude-code-headless/src/config.ts, the owner error message was updated (line 207) but the name error message at line 212 was not — it still points users to the legacy var only:

// Line 207 — owner error (updated ✓):
`...Override with --owner, SYNADIA_CLAUDE_CODE_HEADLESS_OWNER, or SYNADIA_OWNER.`

// Line 212 — name error (NOT updated ✗):
`...Override with --name or CLAUDE_CODE_HEADLESS_NAME.`

A user hitting an invalid-name error would only be told about the legacy env var. For consistency this should read something like:

`claude-code-headless: invalid name "${name}" — must match [a-z0-9_-]{1,63}. Override with --name, SYNADIA_CLAUDE_CODE_HEADLESS_NAME, or SYNADIA_NAME.`

Fix this →

---

Everything else looks good

• Identity chains (examples/pi-headless/src/config.ts and examples/claude-code-headless/src/config.ts): Both are correctly ordered and symmetric. owner and name chains are parallel.
• Legacy compatibility: Both PI_HEADLESS_OWNER/NAME and CLAUDE_CODE_HEADLESS_OWNER/NAME remain in the chain at the right slot — purely additive as described.
• pi-headless has no owner/name validation (pre-existing), so no parallel issue there.
• READMEs: The two-var column format (SYNADIA_..., SYNADIA_OWNER) is clear and the description column explains the full chain including the legacy alias.
• CHANGELOGs: Both entries are under [Unreleased] and describe the resolution chain correctly.
• No SDK surface touched — no npm publish dependency needed, as noted in the PR body.

[M64GitHub]

Fixed in the latest commit — the invalid-name error now lists --name, SYNADIA_CLAUDE_CODE_HEADLESS_NAME, or SYNADIA_NAME, symmetric with the owner error. Typecheck clean.

🤖 Generated with Claude Code