discover untracked OpenCode sessions during session attach

Problem

Issue #1876 covers OpenCode sessions that exist in OpenCode’s native store but were never observed by Entire’s hooks. PR #1877 handles the known-ID case by letting session attach export the transcript on demand:

entire session attach ses_abc123 --agent opencode

That still assumes the user knows ses_abc123. If the session started through an external host, before Entire was enabled, or outside a hooked terminal, Entire has no state from which to recover the ID. The user has to inspect OpenCode’s store manually and copy the result back into Entire:

opencode session list --format json
entire session attach ses_abc123 --agent opencode

I’d like Entire to own that selection flow. When an interactive user omits the ID:

entire session attach --agent opencode

Entire could list native OpenCode sessions for the current worktree, show a picker using the title, directory, and update time, and pass the selected ID into the attach path from PR #1877. The explicit-ID form would stay unchanged for scripts and users who already know the session.

The picker should only include sessions whose reported directory is the current worktree or a directory below it. Sessions already tracked by Entire should be left out. A user working in another linked worktree can run the command there. Non-interactive callers should still provide an ID because choosing the newest session automatically could attach unrelated work.

I don’t think these records belong in the normal session list. That command currently returns persisted Entire sessions. A native OpenCode record has an ID and some display metadata, but no Entire checkpoint, phase, transcript path, turn count, or token data. Showing it in session list would leave session info <id> unable to find the same session, and filling the missing fields with zeroes or an “idle” phase would give those values meaning they do not have.

A separate session discover command would keep the data models separate, but its main purpose would be to produce an ID for session attach. Putting the picker in attach completes the recovery flow without adding another command.

Dependency on OpenCode

This proposal depends on PR #1877 and on a released OpenCode fix that makes native-session enumeration non-mutating.

The picker needs a small amount of native metadata: session ID, title, directory, and update time. OpenCode 1.18.16 already returns those fields from:

opencode session list --format json

Running that command from this repository can rewrite .opencode/package-lock.json. I reproduced the same behavior with --pure. Entire cannot invoke session discovery if it may change the target checkout, and it cannot safely restore the file afterward because the user may already have edits there.

OpenCode already has work in progress for this. OpenCode issue #37435 identifies the full InstanceBootstrap performed by session list as unnecessary. OpenCode PR #37477 changes the command to skip instance bootstrap, resolve the project from the current directory, and query sessions by project ID.

The PR includes coverage showing that plugins are not initialized and that project filtering still works. It does not explicitly assert that session list leaves project files unchanged. Before implementing the picker, Entire should verify the behavior against a released OpenCode version and confirm that JSON listing no longer creates or modifies .opencode/package.json, .opencode/package-lock.json, other lockfiles, or node_modules.

If this direction is accepted here, the next upstream step is to add Entire’s concrete reproduction and use case to #37435 or #37477:

opencode --pure session list --format json

The useful acceptance condition for Entire is stronger than “plugins were not initialized.” Session enumeration must be safe when the target worktree is already dirty.

OpenCode issue #42490 proposes the same no-bootstrap treatment for export and import. That work is related to PR #1877’s transcript-fetching path but is not required to decide whether the attach picker is the right Entire interface.

Decisions needed here

Before taking the reproduction upstream or starting a draft PR, I’d like maintainer direction on five points:

• Does native-session discovery belong inside session attach?
• When the ID is omitted, should Entire open the picker directly or require an explicit --select flag?
• Is the current worktree the right scope, including sessions started from its subdirectories but excluding other linked worktrees?
• Should --agent opencode be required when the ID is omitted?
• Should native-only sessions remain excluded from session list until they have been attached and persisted by Entire?

Historical OpenCode import should remain separate. Importing old sessions as read-only history has different checkpoint and lifecycle semantics, even if it eventually reuses the same enumeration code.

If the proposed direction is accepted, the next step is to comment on OpenCode #37435 or #37477 with Entire’s reproduction and request a filesystem-level regression test. Implementation can start after the fix is merged, released, and verified against a dirty worktree.

PR #1877 does not need to wait for this issue. Fetching a transcript by known ID is useful independently, and its export-error handling can be tightened separately.

Start with the entire session attach --agent opencode entry point and reproduce opencode --pure session list --format json in a dirty worktree. Check whether .opencode/package.json, .opencode/package-lock.json, other lockfiles, or node_modules change; done means the interface decisions are resolved and released OpenCode listing is proven non-mutating before picker implementation begins.