[P0] Local agent discovery fails — misdetects installed agents and reads wrong provider configuration

[Ryder-Sun]

Problem

Meldwork's local agent auto-discovery has two critical defects that break core functionality:

1. Agent installed but reported as not downloaded

Hermes is installed locally (workspace at ~/.hermes/), yet Meldwork reports it as not found / not downloaded. The discovery mechanism fails to locate existing agent installations.

2. Wrong provider configuration detected

The system reads the active provider as official, when the actual local configuration uses custom and openrouter. This means Meldwork is either:

• Reading the wrong config file
• Reading the right file but parsing the wrong field
• Falling back to a hardcoded default instead of reading the user's actual config

Impact: Any agent invocation through Meldwork uses the wrong provider, resulting in failed API calls (wrong endpoint, wrong auth credentials) or unexpected behavior.

---

Root Cause Analysis

The auto-discovery mechanism relies on hardcoded or heuristic search paths to find agent installations and their config files. This is fundamentally fragile because:

• Agent workspaces are not standardized — different users install agents in different locations (~/.hermes/, ~/WorkBuddy/, ~/.codex/, ~/.config/codex/, etc.)
• Config file formats differ per agent (Codex uses config.toml + auth.json; Hermes uses auth.json + config.yaml; etc.)
• The discovery logic likely searches default install paths, and when those don't match, it silently falls back to defaults instead of reporting the miss

---

Proposed Solution: Manual Workspace Path Configuration

Instead of relying solely on auto-discovery (which is inherently fragile across diverse setups), add a user-configurable workspace path mapping for each agent.

Design

Settings → Agent Workspaces

┌─────────────────────────────────────────────┐
│ Agent     │ Workspace Path                  │
├───────────┼─────────────────────────────────┤
│ Hermes    │ ~/.hermes                       │
│ Codex     │ ~/.codex                        │
│ WorkBuddy │ ~/WorkBuddy                     │
│ ...       │ ...                             │
└─────────────────────────────────────────────┘
[+ Add Agent Path]

With the workspace path known, Meldwork can directly read the agent's config files at well-known relative locations:

Agent	Config Files
Codex	config.toml, auth.json
Hermes	auth.json, config.yaml
Claude	config.json, .credentials.json
...	...

Workflow

1. Auto-discovery as fallback, manual config as source of truth. If the user has manually set a workspace path, use it. If not, fall back to auto-discovery with a clear warning.
2. Validate on save. When the user sets a workspace path, verify the expected config files exist at that path. Show a green checkmark or red X with the missing file names.
3. Read provider from the actual config. Once the workspace path is known, read the provider field directly from the agent's config file instead of guessing or defaulting to official.

Benefits

• Deterministic. No more guessing where agents are installed.
• Transparent. User can see and edit the exact paths Meldwork uses.
• Extensible. New agents just need a new row in the mapping + a known config file schema.
• Backward compatible. Auto-discovery still works as a fallback for users who don't configure paths.

---

Acceptance Criteria

• User can manually configure workspace storage path for each agent
• Meldwork reads agent config files (provider, auth, model preferences) from the configured path
• Provider detection correctly reflects the user's actual config (e.g., custom, openrouter instead of official)
• Agent presence detection correctly reports installed agents when workspace path is set
• Auto-discovery remains as fallback with a visible warning when manual path is not configured
• Config file existence validation when saving a workspace path

---

Environment

• OS: macOS
• Affected agents: Hermes (confirmed), potentially others
• Actual Hermes config location: ~/.hermes/
• Actual provider: custom + openrouter
• Detected provider: official (incorrect)

---

Priority Justification

P0 — This breaks core functionality. Users cannot reliably use agents through Meldwork because (a) installed agents are reported as missing and (b) the wrong provider is used for API calls. There is no workaround within Meldwork's current UI.