PR #74438: fix(doctor): don't flag the live compatibility agent dir as orphan

• Repository: openclaw/openclaw
• Author: carlos4s
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/74438

Description (problem / solution / changelog)

Description

Closes #74313

Summary

openclaw doctor could report the live legacy compatibility agent dir as an orphan when the configured default agent was not main. This PR exempts only the realpath-matching live compatibility store while preserving warnings for genuine orphan agent dirs.

Root Cause

listOrphanAgentDirs built its configured id set from resolveDefaultAgentId(cfg) plus agents.list[].id. When agents.list used a non-main default and ~/.openclaw/agents/main/agent still existed as the legacy compatibility store, main was treated like stale state because the orphan scan never compared it with resolveOpenClawAgentDir().

What Changed

• Add a strict realpath comparison helper for agent-dir equality.
• Skip the on-disk nested agent/ dir whose realpath matches resolveOpenClawAgentDir().
• Add regression coverage for the non-main default-agent case and OPENCLAW_AGENT_DIR compatibility override.

What This Does Not Fix

A separate gateway write-side issue can recreate agents/main/{models.json,sessions.json} even after the directory is archived. This PR only fixes the doctor read-side warning so users are not guided toward deleting live compatibility state.

Real behavior proof

• Behavior or issue addressed: openclaw doctor no longer reports the live legacy compatibility agent dir as orphaned when the configured default agent is not main; genuine orphan dirs are still reported.
• Real environment tested: Linux x86_64, kernel 6.8.0-111-generic, Node v24.11.0, OpenClaw built from this branch at a296a342a8, isolated state under /tmp/openclaw-real-test/.
• Exact steps or command run after this patch: Created /tmp/openclaw-real-test/openclaw.json with default agent alfred, created agents/{alfred,main,zzz-stale}/agent, then ran OPENCLAW_STATE_DIR=/tmp/openclaw-real-test OPENCLAW_HOME=/tmp/openclaw-real-test OPENCLAW_CONFIG=/tmp/openclaw-real-test/openclaw.json pnpm openclaw doctor.
• Evidence after fix: Terminal output from the real command showed doctor reporting only zzz-stale:

◇  State integrity ────────────────────────────────────────────────────────╮
│  - Found 1 agent directory on disk without a matching agents.list        │
│    Examples: zzz-stale                                                   │
│    Restore the missing agents.list entries or remove stale dirs after    │
│    confirming they are no longer needed: …/agents                        │

• Observed result after fix: main was exempted because its realpath matched resolveOpenClawAgentDir(), while zzz-stale was still flagged as a real orphan. Additional live checks covered OPENCLAW_AGENT_DIR pointing at legacy/agent, a non-existent override path, and mixed env override plus non-main default.
• What was not tested: The separate gateway write-side recreation behavior was not tested or fixed here.

Tests

• pnpm test src/commands/doctor-state-integrity.test.ts
• Contributor also reported pnpm tsgo:core, pnpm tsgo:test, and pnpm check:changed clean on the branch.

Security Impact

No new permissions, secrets handling, network calls, or data access scope. Doctor only reads local filesystem state and suppresses one unsafe false-positive warning.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/commands/doctor-state-integrity.test.ts (modified, +40/-0)
• src/commands/doctor-state-integrity.ts (modified, +13/-1)