fix(install): gentle-ai hardcodes resolved engram symlink path in opencode.jsonc — breaks after brew upgrade

[DialeDev]

Pre-flight Checklist

• I have searched existing issues and this is not a duplicate
• I understand that PRs will be rejected if the linked issue does not have status:approved

📝 Bug Description

When gentle-ai configures Engram for OpenCode, it writes the resolved symlink path into opencode.jsonc instead of using the bare binary name or the stable symlink path.

For example, it resolves:
engram → /home/linuxbrew/.linuxbrew/bin/engram → ../Cellar/engram/1.16.1/bin/engram
And writes:

"command": ["/home/linuxbrew/.linuxbrew/Cellar/engram/1.16.1/bin/engram", "mcp", "--tools=agent"]
When Homebrew upgrades Engram (e.g., 1.16.1 → 1.16.3), the old Cellar version directory is removed, and OpenCode gets ENOENT: no such file or directory, posix_spawn at startup.
The opencode.json (main config) correctly uses ["engram", "mcp", "--tools=agent"] — the bug is specifically in the opencode.jsonc override that gentle-ai generates with the resolved path.

🔄 Steps to Reproduce

1. Run brew upgrade gentleman-programming/tap/engram (via gentle-ai upgrade)
2. Open OpenCode — Engram MCP fails silently
3. Log shows: "server unavailable" key=engram type=local status=failed
4. OpenCode shows: ENOENT: no such file or directory, posix_spawn /home/linuxbrew/.linuxbrew/Cellar/engram/1.16.1/bin/engram

✅ Expected Behavior

gentle-ai should write the binary name or the stable symlink path (e.g., "engram" or "/home/linuxbrew/.linuxbrew/bin/engram") instead of the resolved Cellar version path. This way OpenCode resolves the symlink dynamically and survives Homebrew upgrades.

// Should write this:
"command": ["engram", "mcp", "--tools=agent"]
// or:
"command": ["/home/linuxbrew/.linuxbrew/bin/engram", "mcp", "--tools=agent"]

❌ Actual Behavior

gentle-ai resolves the symlink to the concrete Cellar version path and hardcodes it in opencode.jsonc. After any brew upgrade, the old version path becomes stale and OpenCode cannot spawn the Engram MCP server.

Gentle AI Version

v1.40.2

Operating System

Linux (Ubuntu/Debian)

AI Agent / Client

OpenCode

📋 Affected Area

Installation Pipeline

💡 Logs / Error Output

OpenCode log entries:
"server unavailable" key=engram type=local status=failed
Config that breaks (in ~/.config/opencode/opencode.jsonc):
"command": ["/home/linuxbrew/.linuxbrew/Cellar/engram/1.16.1/bin/engram", "mcp", "--tools=agent"]

Additional Context

• Root cause: the code that writes the MCP command resolves the binary path through symlinks into the Cellar version directory instead of preserving the original command.
• Workaround: edit ~/.config/opencode/opencode.jsonc and replace the hardcoded path with "engram", then restart OpenCode.
• Affects all Homebrew-managed installations (Linuxbrew on Linux, likely macOS too with /opt/homebrew/Cellar/engram/...).
• The opencode.json main config is NOT affected — it correctly uses ["engram", "mcp", "--tools=agent"].
• Multiple OpenCode sessions on June 14 all failed with the same error after the Engram upgrade from 1.16.1 to 1.16.3.

[Alan-TheGentleman]

Good diagnosis of the symptom, but the root cause is misattributed. gentle-ai already migrates versioned Cellar paths to a stable command in opencode.json (covered by TestInjectOpenCodeMigratesCellarEngramCommandToStablePath) and never writes opencode.jsonc. The versioned .../Cellar/engram/1.16.1/bin/engram path comes from engram setup: resolveEngramCommand() runs os.Executable() + filepath.EvalSymlinks(), which resolves the engram symlink down to the Cellar version directory that brew upgrade then deletes, leaving the stale command that fails with ENOENT.

Moved this to where the fix belongs: engram issue Gentleman-Programming/engram#498 and PR Gentleman-Programming/engram#499, which map versioned Cellar paths back to the stable <brew-prefix>/bin/engram symlink (falling back to bare engram) and leave non-Cellar paths untouched. Closing here. Tracking in engram.