PR #74438: fix: honor the configured default agent in models status and doctor

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

Description (problem / solution / changelog)

Summary

• Problem: openclaw models status and openclaw models status --probe fell back to the compatibility agent dir when --agent was omitted, instead of using the configured default agent.
• Why it matters: this made model/auth status inconsistent with the documented default-agent contract and could inspect the wrong auth store when the configured default agent was not main.
• What changed: added shared agent-scope resolution for models status, threaded that scope through the probe path, and taught openclaw doctor not to flag the live compatibility agent dir as an orphan.
• What did NOT change (scope boundary): this PR does not remove the legacy compatibility main store, and it does not rewrite unrelated resolveOpenClawAgentDir() call sites outside this issue.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #74313
• Related #N/A
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: models status and its --probe path resolved omitted --agent calls through resolveOpenClawAgentDir() instead of the configured default agent, while doctor’s orphan-dir scan only compared on-disk agent dirs against agents.list and had no exception for the live compatibility store.
• Missing detection / guardrail: there was no regression coverage for a non-main configured default agent with omitted --agent, and no doctor coverage for exempting the live compatibility dir.
• Contributing context (if known): auth profile resolution intentionally still supports read-through compatibility from the main store, so the status/probe path and doctor warning drifted into contradictory behavior.

Regression Test Plan (if applicable)

• Unit test
• Seam / integration test
• End-to-end test
• Existing coverage already sufficient
• Target test or file: src/commands/models/list.status.test.ts, src/commands/models/list.probe.targets.test.ts, src/commands/doctor-state-integrity.test.ts
• Scenario the test should lock in: when the configured default agent is not main, models status and models status --probe use that default agent unless an agent-dir env override is set, and doctor does not warn on the live compatibility agent dir.
• Why this is the smallest reliable guardrail: the bug lives at the command/config/path-resolution seam, so isolated helper tests would miss the real precedence and store-selection behavior.
• Existing test that already covers this (if any): explicit --agent behavior already had coverage in src/commands/models/list.status.test.ts, but the omitted---agent default-agent path did not.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• openclaw models status now uses the configured default agent when --agent is omitted and no OPENCLAW_AGENT_DIR / PI_CODING_AGENT_DIR override is active.
• openclaw models status --probe now probes the same resolved agent scope instead of silently reading the compatibility main store.
• openclaw doctor no longer warns that the live compatibility agent dir is orphaned just because it is not listed in agents.list.

Diagram (if applicable)

Before:
[models status with no --agent] -> [resolveOpenClawAgentDir()] -> [compatibility main store]
[doctor orphan scan] -> [compare dirs only to agents.list] -> [warn on live compatibility dir]

After:
[models status with no --agent]
  -> [explicit --agent? else env override? else configured default agent]
  -> [correct agent dir]
  -> [status/probe use same store]

[doctor orphan scan]
  -> [exclude current live compatibility agent dir]
  -> [warn only on real orphan dirs]

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? Yes
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? Yes
• If any Yes, explain risk + mitigation: the commands now read the intended configured default agent auth store instead of the compatibility main store when no explicit agent or env override is present; explicit --agent and env overrides still take precedence, and regression tests cover both the default-agent and compatibility-store paths.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22.14.0 for final verification
• Model/provider: N/A for regression tests
• Integration/channel (if any): None
• Relevant config (redacted): agents.list default agent set to a non-main id; OPENCLAW_AGENT_DIR unset for the default-agent scenario and set for the compatibility-override scenario

Steps

1. Configure agents.list so the default agent is not main, and keep the compatibility agents/main/agent dir on disk.
2. Run openclaw models status and openclaw models status --probe without --agent.
3. Run openclaw doctor.

Expected

• models status and --probe inspect the configured default agent store unless an env override is active.
• doctor does not warn that the live compatibility agent dir is orphaned.

Actual

• Before this fix, models status and --probe read the compatibility store, and doctor warned on the live compatibility dir.
• After this fix, the behavior matches the expected default-agent and compatibility-override contract.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Trace/log snippets:

• npx -y [email protected] /usr/local/lib/node_modules/pnpm/bin/pnpm.cjs test src/commands/models/list.status.test.ts src/commands/models/list.probe.targets.test.ts src/commands/doctor-state-integrity.test.ts
• Result: Test Files 3 passed, Tests 35 passed
• npx -y [email protected] /usr/local/lib/node_modules/pnpm/bin/pnpm.cjs check:changed
• Result: passed

Human Verification (required)

• Verified scenarios: configured non-main default agent for models status, configured non-main default agent for models status --probe, explicit --agent, compatibility env override precedence, and doctor orphan-dir reporting.
• Edge cases checked: env override still wins over configured default agent; doctor exempts only the current live compatibility dir rather than suppressing all orphan warnings.
• What you did not verify: live provider probe traffic against real credentials, and a full end-to-end manual CLI repro outside the Node 22 test harness.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: some users may have relied on the old implicit models status compatibility-store fallback even when their configured default agent differed.
• Mitigation: explicit --agent still works, env overrides still preserve the compatibility path, and regression tests lock the intended precedence.
• Risk: doctor could suppress one warning that previously appeared.
• Mitigation: the exemption is limited to the single currently resolved live compatibility dir; real orphan dirs are still reported.

Changed files

• scripts/check-deadcode-unused-files.mjs (modified, +8/-1)
• src/commands/doctor-state-integrity.test.ts (modified, +40/-0)
• src/commands/doctor-state-integrity.ts (modified, +16/-2)
• src/commands/models/list.probe.targets.test.ts (modified, +9/-2)
• src/commands/models/list.probe.ts (modified, +0/-1)
• src/commands/models/list.status-command.ts (modified, +75/-20)
• src/commands/models/list.status.test.ts (modified, +194/-2)
• test/scripts/check-deadcode-unused-files.test.ts (modified, +12/-0)