Agent PLATFORM segment must be auto-detected at boot, not guessed from the roster

Agent PLATFORM segment must be auto-detected at boot, not guessed from the roster

The rule

Every fleet agent MUST programmatically detect its PLATFORM segment at boot before constructing its 5-segment name (PROVIDER-PLATFORM-DEVICE-PROJECT-INSTANCE). Reading the roster table and assuming a platform is forbidden.

Detection procedure

Claude Code sessions: Check CLAUDE_CODE_ENTRYPOINT env var:

• claude-desktop → PLATFORM = DESKTOP
• cli or absent (with TERM populated) → PLATFORM = CLI

Codex sessions: Check __CFBundleIdentifier:

• Contains codex or Codex app bundle → PLATFORM = DESKTOP

Gemini sessions: Check TERM:

• Populated + running in terminal emulator → PLATFORM = CLI

Fallback: If TERM is empty and no terminal emulator is detected, assume DESKTOP.

Retired PLATFORM tokens

The following tokens are retired as ambiguous and MUST NOT be used in new agent names:

• CODE — does not distinguish Claude Code CLI from Claude Code desktop app
• CHAT — does not distinguish Claude Desktop chat from other chat surfaces
• COWORK — product-specific, not a platform distinction

Use CLI or DESKTOP only.

Known repeat offender: Desktop sessions (amended 2026-04-21)

Claude Code Desktop sessions have a chronic, documented tendency to assume CLI. This is the most common platform-detection failure in the fleet. The drift is one-directional: Desktop→CLI (never CLI→Desktop). Root cause: Desktop has full Bash access and "feels" like a terminal. Tool output, shell commands, and Bash results create a false signal. Having Bash access does NOT make you CLI.

Evidence of recurrence:

• ORA-2026-0004 (2026-04-15): Desktop session misidentified as CLI, caused name collision
• ORA-2026-0032 (2026-04-20): Two Desktop windows both claiming CLAUDE-DESKTOP-MacBook-Air-ORA-01, one producing ARCHITECTURE_LLM_AT_JOINTS.md — identity collision not caught at boot

Enforcement for Desktop sessions: The first tool call in any Desktop session SHOULD be echo $CLAUDE_CODE_ENTRYPOINT to confirm platform before signing any artifact. This is not optional for Desktop — it is the chronic offender and must self-check harder than other platforms.

Scope

• Applies to: every fleet agent across all providers and all surfaces. The PLATFORM segment is the second element of the 5-segment naming convention.
• Enforcement: memory (feedback_agent_naming_convention.md, feedback_desktop_platform_identity_failure.md), canonical bundle (next stamp), boot protocols.

Rationale

On 2026-04-15, a Claude Code desktop app session misidentified itself as CLI because the naming convention said PLATFORM was "Known at boot" — which in practice meant the agent read the fleet roster table, saw "Claude Code CLI", and assumed. The CLAUDE_CODE_ENTRYPOINT=claude-desktop env var was available the entire time. This produced a name collision with an active CLI session.

The fix mirrors the existing DEVICE detection discipline: DEVICE has always been programmatic (scutil --get LocalHostName). PLATFORM was the only naming segment that relied on agent guesswork instead of machine truth. This doctrine closes that gap.

Same pattern as ORA-2026-0003

ORA-2026-0003 documented how a single default Google launcher hid which mailbox it impersonated. This failure is structurally identical: a single default assumption hid which surface the agent ran on. The fix is the same shape: make the implicit choice explicit and programmatic.

References

• Failure record: ORA-2026-0004
• Memory: feedback_agent_naming_convention.md (updated 2026-04-15)
• Env vars: CLAUDE_CODE_ENTRYPOINT, __CFBundleIdentifier, TERM
• Canonical bundle: v1.7 §Fleet roster naming convention (pending stamp to v1.8)