Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

bug(opencode): early local identity failures hide actionable recovery diagnostics

Open
  • Is something wrong?
#2,170 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@dnlrsls is already working on this.

Since Oct 27, 2026.

  • #2167 by @dnlrsls — open

Assessment

This issue has not been assessed yet.

Description

status:approved type:bug
Existing Issue Search
  • I searched existing issues and will add evidence to a canonical tracker when applicable.

Searched open and closed issues for OpenCode diagnostics and stale binaries. #2016 remains the tracker for the original healthy-server registration failure. Its disk-migration occurrence supplies evidence for this narrower diagnostic defect. #1705 concerned setup reconciliation of an existing MCP command, not this early plugin-readiness diagnostic.

📝 Observed Consequence

When the OpenCode plugin cannot execute its selected Engram binary or obtain a valid local identity, attributed writes expose the generic session-registration error without actionable detail. After moving an installation, users cannot distinguish a stale baked binary path from another identity-command failure, even when doctor or a separately invoked CLI works.

🔄 Steps to Reproduce
  1. Use the OpenCode adapter from main at 2ceda3cc35ac76e50cca64db20b74aaeba8107e7.
  2. In isolated adapter fixtures, select a nonexistent baked binary path and simulate spawnSync ENOENT; similarly exercise a stale explicit override, failed launch/nonzero exit, invalid identity stdout, and health identity mismatch.
  3. Invoke the attributed mem_save hook and inspect its error and queued degraded warning.
  4. On the base, six new diagnostic cases fail because the output remains generic; the valid-override compatibility control passes. No real installation, database or service changes are needed.

Field evidence: https://github.com/Gentleman-Programming/engram/issues/2016#issuecomment-6447034366 reports Core 3.6.0 on Windows after disk migration, a nonexistent baked ENGRAM_BIN, no health/registration requests, and recovery after rerunning setup from the current installation and restarting OpenCode. This explains that occurrence only, not the original healthy-server report.

✅ Expected Behavior

Expose privacy-safe, actionable diagnostics for missing selected binary, failed identity command, invalid identity output, and health identity mismatch. Identify explicit override versus setup-default selection without paths, identity values or raw command output. Give supported setup-and-restart recovery for a stale baked path and override correction guidance where applicable.

Preserve binary precedence, explicit ENGRAM_URL behavior, identity/auth/session guards, registration rejection and acknowledgement handling. A valid override must still succeed despite a stale baked default. No automatic PATH fallback, automatic server replacement/termination, guard weakening or self-healing framework.

❌ Actual Behavior

On the investigated base, localInstanceID failure is caught before health/session registration and surfaces as: gentle-engram could not confirm Engram session registration for engram_mem_save; verify that the Engram server is available and retry. Startup/readiness categories do not identify the selected-binary failure or recovery.

Operating System

Windows; deterministic adapter fixtures also run through existing cross-platform OpenCode suites.

Release Version (Report Context)

Field occurrence: Core 3.6.0. Investigated current-main base: 2ceda3cc35ac76e50cca64db20b74aaeba8107e7. Candidate: c0ee4ebfac3ad765ce08f526f73a28ba17d00dea in PR #2167. No claim of reproducing the original healthy-server failure.

Agent / Client

OpenCode (field report: V2).

📋 Relevant Logs
Base diagnostic regression: 7 tests, 1 pass, 6 fail.
Candidate focused diagnostics: 8 pass, 0 fail, 0 skip.
Candidate OpenCode three-file suites: 281 pass, 0 fail, 0 skip.
💡 Additional Context

Root-cause evidence on the base: plugin/opencode/engram.ts:219-255 validates instance-id and catches failure without exposing cause; :668-705 registers sessions only after readiness/project resolution; :895 emits the generic error when no registration cause exists. internal/setup/setup.go:488-543 bakes the selected absolute fallback into the installed plugin.

Accepted narrow correction is implemented in PR #2167: diagnostics and recovery documentation only; source/embedded parity and setup literal-patch compatibility preserved. Native RDD review approved and acknowledged the exact candidate without corrections. Local Go 1.26.10 setup patch/install tests pass. Hosted Unit/E2E/plugin/platform checks passed when inspected; Go Race Tests failed in a separate unchanged CLI test, tracked under #2169 and not declared resolved.

This tracker is intentionally split from #2016 after review identified that closing the original issue would overstate the result. The maintainer authorized creating, approving and assigning this bounded diagnostic tracker to dnlrsls and changing PR linkage. #2016 must remain open. No new source scope or CI rerun is authorized by this metadata correction.

Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
9h 12m
Merged PRs (30d)
331

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.