diagnose-stale-core-binary

Diagnose serde unknown-variant errors caused by stale running core binaries after updates.

10|1|Updated Jul 7, 2026
One-click install
npx skills add https://github.com/catalystctl/catcode --skill diagnose-stale-core-binary-catalystctl
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose-stale-core-binary
Source: https://github.com/catalystctl/catcode/tree/main/.catalyst-code/skills/diagnose-stale-core-binary
Command: npx skills add https://github.com/catalystctl/catcode --skill diagnose-stale-core-binary-catalystctl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? After updating or reinstalling CatCode, users see bad command: unknown variant '<X>' errors from the core even though the source code already contains that variant. This Skill pinpoints the real cause: a stale, still-running core process using a deleted old binary, rather than an actual code bug. ## Core Features & Use Cases - Source Verification: Confirms the variant exists in core/src/protocol.rs and is dispatched in core/src/main.rs, ruling out a genuine code gap. - Stale Process Detection: Enumerates running core processes via /proc and flags deleted-inode executables that predate the current binary. - Empirical Binary Validation: Tests the on-disk binary directly with a JSON-lines init/command exchange instead of unreliable strings checks. - Use Case: A user updates CatCode and pastes unknown variant 'list_plugin_commands' from the TUI. The Skill confirms the source has the variant, finds an old web live-session core still running a deleted binary, and resolves the issue by killing the stale process with no rebuild needed. ## Quick Start Diagnose why the core reports an unknown variant error after I updated CatCode, and tell me whether I need to rebuild or just restart stale core processes.

Frequently Asked Questions about diagnose-stale-core-binary

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why do I get 'unknown variant' errors after updating CatCode?

The error comes from a stale running core process, not a code bug. Reinstalling the binary does not restart already-running cores, so an old deleted-inode process receives commands its serde Command enum does not recognize.

How do I find stale core processes running a deleted binary?

Iterate over /proc entries and readlink each process's exe path, filtering for core or catcode-core names. A '(deleted)' suffix on the executable path identifies a stale core that is the source of the error.

How can I verify the on-disk core binary is current?

Pipe an init message followed by the suspect command as JSON lines into the binary with a temp workspace and check whether it returns the expected event. Avoid anchored strings grep, since serde rename strings are packed without NUL terminators and produce false negatives.

Do I need to rebuild the core to fix unknown variant errors?

Usually no. If the on-disk binary accepts the command empirically, just kill the stale cores; the TUI and web harnesses auto-respawn from the current binary. Rebuild only when the on-disk binary itself is stale.

Why does the error persist after restarting the app?

A different long-lived core, such as a web live-session or a second TUI window, may still be running the old binary. Enumerate all core processes, not just the current window's, since idle cores can survive for hours.