local_embedded: daemon ignores shell env — HINDSIGHT_API_LLM_API_KEY only works via config dict, error message is misleading

[fanaticalfishing]

Bug Description

In local_embedded mode, DaemonEmbedManager.ensure_running() spawns the per-profile daemon detached, so env vars exported in the parent shell (e.g. HINDSIGHT_API_LLM_API_KEY) are not inherited. The only reliable way to pass the key is via the config dict (llm_api_key) passed to ensure_running.

Steps to Reproduce

1. export HINDSIGHT_API_LLM_API_KEY= in the shell
2. In Python: get_embed_manager().ensure_running(cfg, profile) for a profile with a queued reflect/mental-model job (cfg has no llm_api_key)
3. Observe daemon log / startup result

Expected Behavior

The daemon inherits the parent process env (or, if the detached design is intentional, the error message names the missing config key rather than an env var that can never reach the daemon, and the local_embedded docs state the contract).

Actual Behavior

Daemon crashes at boot with "ValueError: LLM API key is required. Set HINDSIGHT_API_LLM_API_KEY environment variable." despite that env var being set in the parent shell, and ensure_running just times out (~178s). Profiles with no LLM call at boot start fine without the key, so the setup looks healthy until one profile fails — masking the cause.

Version

0.9.0 (hindsight-all / hindsight-api-slim / hindsight-embed; hermes-agent 0.19.0)

LLM Provider

OpenAI-compatible

[Sanderhoff-alt]

Root cause

This was not “detached spawn drops parent env”.

DaemonEmbedManager already builds the child env from os.environ.copy() and then overlays config. The bug was that HindsightEmbedded put HINDSIGHT_API_LLM_API_KEY="" into the config when no key was provided. That empty string was treated as a real override and replaced a key inherited from the parent shell.

So:

export HINDSIGHT_API_LLM_API_KEY=...
HindsightEmbedded()

looked like “env is ignored”, but it was actually “the default empty config value overwrote parent env”.

Fix

The daemon already preserves parent environment variables and accepts an explicit empty string as an override, so no daemon change is needed.

HindsightEmbedded now distinguishes omitted and explicitly empty keys:

• omitted / None: do not write HINDSIGHT_API_LLM_API_KEY, allowing the profile or parent environment value to be inherited
• "": explicitly use no API key, for local LLM services without authentication
• non-empty string: explicitly override the inherited key

Effective precedence:

explicit config (including "") > profile .env > parent process env

About the other symptoms

• Error message (Set HINDSIGHT_API_LLM_API_KEY environment variable): correct once env inheritance works again. No message change is needed for this bug.
• ~178s timeout: a secondary effect of daemon boot failure when the key was overwritten. With the inherited key preserved, that path should not wait on a failed boot.
• Docs saying “key only works via config”: not the intended contract. Shell / parent env inheritance is supported.

Status

Fix submitted in #3359.

Regression coverage verifies omitted, empty, and non-empty API key values.