feat(opencode): close the matching Engram session when an OpenCode session is archived

[jemanuelp]

🔍 Problem Description

Archiving an OpenCode session does not currently close its corresponding Engram session. This leaves the Engram session open after the user has archived the conversation, requiring separate lifecycle management.

In the inspected OpenCode adapter, plugin/opencode/engram.ts handles session.created and session.deleted; deletion only cleans local maps. There is no archive-to-session-close integration. The adapter already registers the native OpenCode session ID unchanged and excludes subagents, so the integration should retain that identity boundary rather than infer a session from a project name or title.

💡 Proposed Solution

Handle OpenCode session archival in the thin Engram OpenCode adapter and request closure of the exact, already-registered matching Engram session. Upstream documentation/source indicates archival is represented by session.updated with time.archived, not a dedicated session.archived event. Verify the installed SDK/runtime payload contract during implementation; this issue does not claim that contract has been tested locally.

Acceptance criteria:

• Detect archival through the verified OpenCode event payload. Ignore ordinary session updates and unrelated, subagent, or unregistered sessions. Do not synthesize an Engram session solely to close it.
• Use the existing native OpenCode session identity. Keep event translation in the plugin and closure semantics in the Engram core.
• Make closure idempotent and summary-preserving in the core, including repeated archive events and retries. The current POST /sessions/{id}/end path calls Store.EndSession; an empty payload can overwrite an existing summary with NULL, repeated calls can rewrite the close timestamp, and an unknown ID currently produces no error. Do not blindly forward an empty close request without addressing those safeguards.
• Establish and test an inactive-state check or an explicit safe policy for archival while a session is busy; an archive update must not silently terminate active work.
• Explicitly define and document unarchive/resume behavior. Re-registering the same ID currently does not clear ended_at; do not silently assume that registration reopens a session or introduce reopening as an incidental side effect.
• Preserve observations and prompts. Archival is session closure, not data deletion, and must not fabricate or automatically generate a summary.
• Add focused plugin and core tests for the installed event payload, ordinary updates, identity isolation, excluded sessions, repeated events/retries, summary preservation, unknown IDs, busy-session handling, and the chosen unarchive/resume policy. Update the relevant plugin/lifecycle documentation.

Keep this scoped to the archive integration and the safeguards needed to make it safe, not a broad lifecycle redesign.

📦 Affected Area

Other

🔄 Alternatives Considered

No response

📎 Additional Context

Related closed reports: #48, #1083 and #1131 concern missing session closure or accumulated open sessions; #972 concerns re-registering an already-ended session. The reviewed bodies do not describe handling OpenCode archival through session.updated / time.archived. This request specifically tracks that archive-triggered integration and its safety requirements.

Relevant implementation locations from the inspected checkout: plugin/opencode/engram.ts, internal/server/server.go, and internal/store/store.go. Existing sync application preserves a prior ended_at when an incoming value is null, which must be considered when defining resume behavior. No implementation is included in this request.

Delivery slices

• PR #1250 — Core closure semantics (383 changed lines).
• Issue #1259 — Delayed closure sync.
• Issue #1263 — OpenCode archive-to-idle feature (may require a maintainer-approved size:exception).
• Issue #1264 — Archive lifecycle hardening.
• Issue #1235 — Later adapter-to-core refactor.

Sequential main-target PR order: #1250, then a PR for #1259, then a PR for #1263, then a PR for #1264, and then a PR for #1235.

[jemanuelp]

Minimal archive-event wiring example, to adapt into Engram's existing event hook rather than necessarily adding a separate plugin:

import type { Plugin } from "@opencode-ai/plugin"

export const ArchiveListener: Plugin = async () => ({
  event: async ({ event }) => {
    if (event.type !== "session.updated") return

    const session = event.properties.info
    if (session.time.archived === undefined) return

    // React to an archived session.
  },
})

This observes updates carrying archived state, not a guaranteed one-time archive transition. Actual closure must match the exact registered session ID, be idempotent, preserve the existing summary, and handle active execution and unarchive/resume according to this issue. This is event wiring only, not a complete implementation or a claim of test coverage.

[danielgap]

@FerEnoch posted independent evidence in #1247 (comment) that complements this issue's archival scope, cross-linking here so it stays visible while #1226 and #1250 are in flight:

• session.deleted also never closes the Engram session. Today it only clears in-memory maps (toolCounts, knownSessions, subAgentSessions), so deletion leaves the row open exactly like archival does. Archival (session.updated + time.archived) and deletion are two different events, and the deletion path falls outside this issue's acceptance criteria as written.
• Dead intent confirming the gap: toolCounts is maintained with the comment "Count tool calls per session (for session end stats)" but that statistic is never sent anywhere — the end path looks planned and left unimplemented.
• Repro without any stale state: two concurrent OpenCode sessions in the same directory are enough for mem_save / mem_session_summary to fail closed with multiple active runtime sessions (engram 2.0.0 stable, 297/327 sessions unclosed on one node).
• A complementary direction: injecting the explicit session_id into Engram write tool calls through tool.execute.before would make the fail-closed ambiguity untriggerable regardless of how many sessions are open, and would unblock concurrent OpenCode sessions in one directory. That may be scope beyond this issue — flagging it for maintainers to split if they agree.

For operators in the meantime, #1252 adds the CLI cleanup tier (engram session end) and a stale_open_sessions doctor check, and #1253 tracks the unbounded --project-only bulk window found in its review.

[jimmybathrooms]

Caso real: sesiones acumuladas bloquean mem_save (opencode v2.2.1, workspace multi-repo)

Evidencia fresca (2026-09-27) que refuerza este issue.

Entorno

• engram v2.2.1 (homebrew, gentleman-programming/tap)
• Agente: opencode, sesiones con y sin TUI (opencode run --print)
• Workspace con 2 git repos en el mismo cwd: dom4in-asesor + dom4in-asesor-api

Síntoma

mem_save / mem_session_summary fallan siempre con:
multiple active runtime sessions match the current project and directory; provide session_id...

Detalles que importan:

1. El fallo persiste incluso pasando project explícito + recovery_token (eso resuelve solo la ambigüedad de proyecto, no la de sesiones runtime).
2. engram doctor --project dom4in-asesor reporta 12 sesiones runtime activas candidatas en un único directorio (ambiguous_active_runtime_sessions, warning con requires_confirmation: true). Ninguna se cerró tras archivarse las sesiones de opencode.
3. El doctor es diagnóstico-only (no cierra nada), así que el usuario no tiene ruta de reparación desde las tools MCP.
4. El workaround engram save ... --project desde CLI sí funciona (atribución por proyecto), pero los agentes MCP no pueden usarlo porque el runtime no expone el session_id autoritativo.

Por qué refuerza #1192

Esto es exactamente el ciclo de vida que #1192 propone cerrar: al archivar una sesión de opencode, su sesión Engram queda abierta para siempre. Con el tiempo se acumulan y bloquean toda escritura con session_id omitido (fail-closed por diseño). La suma de #1192 + #1270 (bindings autoritativos) cubriría tanto el cierre como la atribución.

Puedo aportar el dump de doctor --json con los 12 session_ids si se necesita para el conformance suite de #1270.

[danielgap]

Gracias por la evidencia: reproduce exactamente el ciclo que este issue propone cerrar, y además en v2.2.1, que ya incluye el runtime owner liveness de #1267. Eso es consistente con lo que ves: archivar la sesión de opencode no mata el proceso, así que el dueño sigue vivo para el liveness check y la sesión Engram queda abierta indefinidamente. El fail-closed con session_id omitido es comportamiento esperado; lo que falta es que el disparador no exista, y ahí entran #1192 (cierre en archivo) y #1270 (bindings autoritativos que eliminan la necesidad de pasar session_id, que es tu punto 4).

Una corrección a mi comentario anterior: el tier de limpieza que cité (engram session end + check stale_open_sessions) era el PR #1252 y se cerró sin mergear el 20/09; las ramas siguen en el fork pero no hay nada publicado. Tu punto 3 (sin ruta de reparación) es correcto para toda versión publicada, no solo v2.2.1.

• Sí al dump: puedes adjuntar el doctor --json con los 12 session_ids en feat(sessions): add authoritative bindings for concurrent agents #1270; sirve tanto para el conformance suite como fixture de aceptación de este issue.
• Para desbloquearte hoy: los session_ids que lista el doctor se pueden cerrar contra la API local (POST /sessions/{id}/end, con el server local corriendo). Un detalle a cuidar: un payload vacío puede sobrescribir un summary existente con NULL (uno de los endurecimientos pendientes listados arriba), así que revisa cuáles tienen summary antes de cerrarlas.