PR #74397: fix(feishu): repair stale channel state in doctor

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

Description (problem / solution / changelog)

Summary

• Problem: Feishu can keep reprocessing stale/corrupt local channel state or direct channel session entries, which can leave the gateway hot-looping after startup.
• Why it matters: Reinstalling the plugin or re-entering Feishu App ID/secret does not clear these local runtime/session files, so users can remain stuck with high CPU even when credentials are valid.
• What changed: Added a Feishu-owned doctor sequence that detects corrupt Feishu JSON state and suspicious Feishu direct session transcripts, then openclaw doctor --fix archives/rebuilds only Feishu local state and Feishu-scoped direct session entries.
• What did NOT change (scope boundary): This does not change Feishu credentials, App ID/secret config, network behavior, message handling, or ACP binding session entries.

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 #74237
• Related #74237
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: Feishu had persistent local runtime/session state that could become stale or corrupt independently from plugin installation and credentials. The channel did not have a doctor-owned repair path to rebuild that channel-local state while preserving configured App ID/secret values.
• Missing detection / guardrail: openclaw doctor did not inspect Feishu local state JSON or Feishu direct channel session transcript integrity, so the recovery step was manual and easy to over-delete.
• Contributing context (if known): A fresh plugin reinstall can still reuse existing ~/.openclaw/feishu files and agent session store entries, so the problem is not solved by reinstalling the Feishu plugin alone.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/feishu/src/doctor.test.ts
• Scenario the test should lock in: Feishu doctor stays quiet for healthy state, warns before repair for corrupt Feishu local JSON, and --fix archives Feishu local state plus direct Feishu session entries while preserving non-Feishu sessions and ACP binding session entries.
• Why this is the smallest reliable guardrail: The bug is in channel-local state repair behavior, so the test can cover the doctor sequence directly without requiring a live Feishu tenant.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

openclaw doctor can now warn when Feishu local channel state appears repairable. openclaw doctor --fix can archive/rebuild Feishu local runtime state and Feishu-scoped direct session entries while preserving Feishu App ID/secret config.

Diagram (if applicable)

Before:
[stale Feishu local state] -> [gateway restart] -> [same bad state reused]

After:
[openclaw doctor --fix] -> [archive Feishu state/session entries] -> [gateway rebuilds clean Feishu local state]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) Yes
• If any Yes, explain risk + mitigation: Feishu doctor now reads Feishu local state JSON and configured/discovered session stores under the OpenClaw state directory, and repair mode renames/removes only Feishu-scoped direct channel state. It creates timestamped backups and intentionally preserves Feishu App ID/secret config, non-Feishu sessions, and ACP binding session entries.

Repro + Verification

Environment

• OS: Linux VM observed during debugging; local tests run on macOS
• Runtime/container: OpenClaw CLI/gateway local mode
• Model/provider: N/A
• Integration/channel (if any): Feishu
• Relevant config (redacted): Feishu channel configured with App ID/secret; local Feishu state/session data present

Steps

1. Configure Feishu and start the gateway.
2. Leave stale/corrupt Feishu local state or Feishu direct session entries on disk.
3. Restart the gateway.
4. Run openclaw doctor and then openclaw doctor --fix.

Expected

• Doctor identifies Feishu-local repairable state.
• Repair archives Feishu-local state and Feishu-scoped direct session entries.
• Feishu App ID/secret config remains intact.
• Non-Feishu sessions and ACP binding session entries remain intact.

Actual

• Before this PR, users had to manually delete Feishu local state/session files to recover.
• After this PR, doctor provides a scoped repair path.

Evidence

Attach at least one:

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

Local verification:

node --no-maglev node_modules/vitest/vitest.mjs run --config test/vitest/vitest.extension-feishu.config.ts extensions/feishu/src/doctor.test.ts
Test Files  1 passed (1)
Tests       4 passed (4)

node_modules/.bin/oxfmt --check extensions/feishu/src/doctor.ts extensions/feishu/src/doctor.test.ts extensions/feishu/src/channel.ts
All matched files use the correct format.

node_modules/.bin/oxlint extensions/feishu/src/doctor.ts extensions/feishu/src/doctor.test.ts extensions/feishu/src/channel.ts
Found 0 warnings and 0 errors.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: Healthy Feishu state is quiet; corrupt Feishu local JSON warns before repair; repair archives Feishu local state and direct Feishu sessions while preserving App ID/secret config, non-Feishu sessions, and ACP binding session entries.
• Edge cases checked: Legacy feishu:* session keys, agent:<id>:feishu:* session keys, ACP binding keys containing feishu, missing transcript paths, blank user message transcripts, local JSON parse failures.
• What you did not verify: Full pnpm check / pnpm test; this local checkout does not currently have pnpm/corepack available, and the broader Feishu channel test import path is missing typebox in node_modules.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A. Users affected by stale Feishu local state can run openclaw doctor --fix.

Risks and Mitigations

• Risk: Repair could remove more Feishu session state than intended.
  • Mitigation: The repair only targets direct Feishu channel session keys (feishu:* and agent:<id>:feishu:*), explicitly preserves ACP binding Feishu session keys, backs up session stores, and archives transcript artifacts by renaming them instead of deleting them.

Changed files

• extensions/feishu/src/channel.ts (modified, +2/-0)
• extensions/feishu/src/doctor.test.ts (added, +237/-0)
• extensions/feishu/src/doctor.ts (added, +721/-0)