OpenCode 2.x: fails to load — V1 entrypoint, no V2 setup(ctx)

[alanjholiveira]

Summary

The plugin does not load on OpenCode 2.x. It still ships a V1-only entrypoint, so OpenCode's plugin loader rejects it before setup ever runs.

Error

PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function.
(cause: SchemaError(Expected object at ["default"])))

Logged as level=WARN message="failed to load plugin" target=opencode-auto-resume on every load, in both opencode run and the desktop/background service.

Environment

• OpenCode 2.0.12 / 2.0.14 (desktop + CLI), config key is plugins
• opencode-auto-resume@1.1.18
• Reproduced by adding it with opencode plugin add opencode-auto-resume and starting any session

Why

V2 requires a default-exported object with an id and a setup(ctx) (or effect(ctx)). The published entrypoint has no default export matching that shape, so the schema check fails during module load.

Migration reference: https://opencode.ai/v2/docs/build/plugins/migrate-v1

The dual-entrypoint escape hatch documented upstream would keep V1 working while adding V2:

export default {
  ...Plugin.define({
    id: "auto-resume",
    async setup(ctx) {
      // V2 hooks
    },
  }),
  async server() {
    return {
      // existing V1 hooks
    }
  },
}

Port scope (heads-up, this is the non-obvious part)

Beyond renaming the entrypoint, several V1 APIs the plugin relies on are not exposed on the V2 plugin context, so a straight server() → setup() copy will not be enough:

Missing on ctx (verified by logging Object.keys(ctx) and Object.keys(ctx.session) in a V2 plugin):

• client.session.list, session.status, session.abort, session.summarize, session.todo, session.messages
• client.app.log
• client.provider, client.config, client.tool.ids
• client.tui (TUI is a separate plugin surface in V2)

V2 ctx.session only exposes: hook, create, get, switchAgent, switchModel, prompt, generate, command, synthetic, interrupt, update, move, wait, context.

Hooks with no direct V2 equivalent:

• chat.message → closest is ctx.session.hook("prompt", ...) (runs at prompt admission, not per message)
• command.execute.before → docs say to use a command transform or the prompt hook depending on intent
• tool.execute.before → ctx.tool.hook("execute.before", ...) (note: args arrive as event.input, and the shell tool is now named shell, not bash)
• tool.execute.after → ctx.tool.hook("execute.after", ...)

Happy to test a next/V2 build if you want a hand verifying it.

Workaround currently used

None — the plugin has to be removed from plugins to keep the log clean.

[Mte90]

There is a PR about it #20

[famewolf]

I'"ve completed a working v2 port based on the current v1.1.19 (commit 02b2e01).

The branch is at famewolf/opencode-auto-resume:pr20-v2port — 5 commits that:

• Target the stable @opencode/plugin 2.0.5 API
• Use event-driven architecture (ctx.session.hook / ctx.tool.hook) instead of the old event pump
• Preserve all detection/recovery features: stall watchdog, failure recovery, tool-call-as-text, ready-to-continue nudges, hallucination loop guard, block-site naming, abort guard
• Built with: bun build src/v2/index.ts --outdir dist-v2 --target bun

Verified working on opencode 2.0.12 CLI (all 7 plugins load, zero errors, nudge fires correctly on task_complete with pending todos).

PR #20 was based on the older v1.1.11 alpha API. This port supersedes it with the stable API.

Happy to submit as a PR if you want. Branch: https://github.com/famewolf/opencode-auto-resume/tree/pr20-v2port

[Mte90]

now there are 2 PRs for opencode v2 support...

[famewolf]

Apologies for the duplicate. I was sending multiple PR's for several plugins that I did v2 changes for and wasn't paying enough attention. Right after that I found several fixes v1 had I needed to add to my v2. If you want I can consolidate mine into the other one and/or only include the additions to what the original had? Just let me know. Rudi

…

On Mon, Sep 28, 2026 at 3:11 AM Daniele Scasciafratte < ***@***.***> wrote: *Mte90* left a comment (Mte90/opencode-auto-resume#33) <#33 (comment)> now there are 2 PRs for opencode v2 support... — Reply to this email directly, view it on GitHub <#33?email_source=notifications&email_token=ABCY74CS6KA6CO6HPTT3IVL5RIFKTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBWGUYTQNRZGM4KM4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5865186938>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABCY74DQFO3E3Y73BHHVGN35RIFKTAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMBTG4ZDOOJXG45US43TOVSTWNJVGQYDQMZSHE2DTILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ABCY74AJ7YLJYMCJOAAXJZL5RIFKTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBWGUYTQNRZGM4KM4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/ABCY74HOAEVCMK5ZWE6G5JD5RIFKTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKOBWGUYTQNRZGM4KM4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you commented.Message ID: <Mte90/opencode-auto-resume/issues/33/5865186938 ***@***.*** .com>

[Mte90]

I am not using opencode v2 so right now I don't know what are the differences and also compared to the other PR.
Also what this means for retrocompatibility etc

[famewolf]

@Mte90 I am not using opencode v2 so right now I don't know what are the differences and also compared to the other PR.
Also what this means for retrocompatibility etc

Thanks for the clear questions, and apologies for the duplicate PR — that was my mistake. Let me answer both directly.

The two PRs are not competing: #37 already contains everything in #20

• feat!: migrations for opencode v2 #20 — valentimarco, head b5fd8aa — is the v2 port.
• Add OpenCode v2 port (src/v2) + OOC lock parity #37 — mine, head 875d7e4 — was started independently and then rebased on top of yours.

b5fd8aa is a direct ancestor of 875d7e4, so #37 is a strict superset. Every commit in #20 is in #37, unchanged — nothing in #20 is dropped.

To be explicit about credit: the v2 port is valentimarco's work and stays credited in #20. The five commits on top are mine, and they are attributed to me.

The five additional commits (all v2-only)

Commit	Change
0a0a961	OOC lock — restores v1's continue-loop hard stop (maxRecoveryRetries + gaveUp latch), which the port had dropped
9a44699	never interrupt a session that is compacting or already busy
0dd0403	never nudge a turn that hands off to the user (a question, or an explicit prompt)
3c1d88c	shouldStandDownForUser guard (v1 parity) + activeUserWindowMs option (default 15 min)
875d7e4	stop self-inflicted "Step interrupted" and synthetic-continue bursts

875d7e4 is the one with visible user impact. On v2, ctx.session.prompt() interrupts an in-flight step, so a recovery prompt injected into a live session produced Step interrupted — and the port could inject several synthetic continue messages at the same timestamp. The fix routes all three recovery paths through a single injectOnce() choke point with a rate limit and a busy check, and stops the plugin reacting to its own abort events. v1 cannot hit this failure mode, because its prompt path does not interrupt a running step — that reasoning is written up in the #37 comment.

Retrocompatibility: v1 is untouched

None of the five commits touch src/index.ts — they are confined to src/v2/index.ts (plus one lockfile and a .gitignore entry). The v1 entry point, its hooks and its behaviour are exactly what they were. Existing v1 users are unaffected by anything in #37; #37 only adds a v2 file and docs.

The v2 side is a separate entry point (export default define({ id: "auto-resume.v2", ... })), so today it is a manual swap: a v2 user replaces the plugin file, a v1 user keeps theirs. That is precisely the thing you asked about on #20 — the plugin identifying the OpenCode version and serving both from one entry point. That is still not implemented in either PR. The dual-entrypoint shape sketched in this issue ({ ...Plugin.define(...), server() { ... } }) would do it. I would rather implement it deliberately than guess at it, so: if you want it, say the word and I will add it on top of #37.

Tests — the honest gap

Neither PR has tests for the v2 port. src/v2/ contains only index.ts. v1 has 578 tests across 32 files; the port has none committed. I used a standalone behavioural harness while developing, but it is not in the repo and should not count as a test suite. I can port the v1 test structure over to src/v2/*.test.ts — that is real work, not a checkbox, and I would rather commit to it than claim it.

One implementation difference worth your review

Our v2 file has no runtime import of the plugin API (it defines the { id, setup } helper locally), so the built artefact is dependency-free. docs/v2/installing.md — currently inherited unchanged from #20 — still tells users to install @opencode/plugin next to the plugin. Those two need to be reconciled one way or the other, and I did not want to rewrite the install instructions on my own since they are yours.

What I would suggest

Land #37 and close #20 as superseded, rather than cherry-picking: the five fixes depend on each other and on the port's structure, so a selective port would be fragile. If you would rather keep #20 as the canonical PR, I can rebase my five commits onto it and open that instead — attribution stays as described either way. Your call.

[Mte90]

So to move on this integration I have some questions:

• there will be duplicated code? like the same stuff in different path to cover both versions?
• the documentation is updated in the readme? maybe it make sense to do a different file with the list of issues because probably between versions it will change
• the actual settings it will works?

[famewolf]

Thanks, and these were the right questions to ask before landing. The third one turned up a
real gap in #37, so please read it even if you skip the first two.

1. Duplicated code

The two entry points stay separate, and that is the right call. v1 registers through the
hooks-object Plugin.define; v2 registers { id, setup } and reads ctx.event.subscribe().
They cannot be one file, and I would not try to make them one.

Worth keeping separate from that decision: separate entry points do not require the code
between them to be separate too. What exists today:

• src/index.ts — 3,038 lines, 3 imports
• src/v2/index.ts — 1,411 lines, 0 imports
• lines literally shared between the two files: 26

src/v2/ contains only index.ts, so the port shares no module with src/. Everything the
two files have in common is detection and recovery logic that has nothing to do with which
plugin API is in play: the stall watchdog, the hallucination-loop guard, done-claim detection,
the backoff curve, block-site naming. That logic is written twice today. A shared src/core/
with two thin entry points would remove most of it, so the duplication is an implementation
choice rather than something the API difference forces.

I would not do that inside #37, because it rewrites the v1 path while you are reviewing it.

2. Documentation, and splitting the issue tracker

The docs are already updated in the PR. README lines 5 to 9 flag both entry points at the
top, there is an "OpenCode v2 (stable)" section at line 397, and docs/v2/installing.md and
docs/v2/migration.md are new files.

On the per-version known-issues list, that is the part I will act on: a list in docs/v2/
that says which version each known issue affects. Tell me where you want it and I will write
it.

On splitting the tracker, I would use labels instead of two trackers. Most reports will be
the same bug in both versions, because the symptom does not depend on the plugin API and only
the stack trace differs. Splitting fragments the history and doubles your triage, and since
you are on v1 it would leave the v2 side with fewer eyes rather than more. A v1 / v2 label
on one tracker gives the same routing.

If you would rather split them, tell me and I will set it up.

3. The settings: partly, and currently silently

This is the one I would fix before you merge, and the reason is your third question.

v1 reads 30 option names. v2 reads 15. Sixteen options a v1 user can set are not read by v2,
and v2 logs nothing when it ignores them, so a v1 config carried over to v2 fails quietly into
defaults:

v1 option	what v2 does with it
maxRecoveryRetries	renamed, v2 calls it maxRetries
resumeOnActionIntent	ignored, and the feature is unconditional in v2
streamingFailureErrorNames	ignored
streamingFailureMessagePatterns	ignored
doneClaimPatterns	ignored, v2 uses a built-in list
busyStallStrategy	ignored
contextSaturationThreshold	ignored
doneWithoutDetailsPrompt	ignored
minActivityGapMs	ignored
readyToContinuePatterns	ignored
silentDeadStreamMinTokens	ignored
subagentNativeCompactionEnabled	ignored
subagentWaitMs	ignored
thinkingToolRecoveryPrompt	ignored
toolTextCheckDelayMs	ignored
warmupMs	ignored

Two of these change behaviour rather than just falling back to a default:

resumeOnActionIntent cannot be expressed in v2 at all. In v1 it defaults to true and
setting it false disables action-intent recovery. In v2 that path runs unconditionally at
src/v2/index.ts:1003, with no option to turn it off. Anyone who turned it off in v1 gets it
back on, with no message saying so.

streamingFailureErrorNames and streamingFailureMessagePatterns decide what counts as a
recoverable failure. v2 ignores both and uses its own list, so custom patterns do not carry
over.

To be clear about one thing that is not a regression: maxRecoveryRetries is a rename, not a
removal. v2 caps the same loop with maxRetries at src/v2/index.ts:831, so the hard stop
restored in 0a0a961 is intact. A v1 user who set maxRecoveryRetries: 5 still gets the
default for maxRetries, which is the same silent-fallback problem as the rest.

The fix I can do small. At startup, log the option keys v2 does not recognise, once, at
info level. One line like
auto-resume.v2: ignoring unsupported options: warmupMs, subagentWaitMs, ... turns all
sixteen of these from a silent behaviour change into something a user can see. That is a
self-contained commit, and I would send it as a follow-up PR rather than adding it to #37
while you are reading this one.

One question, because you are the only one who can answer it. Which of these are your
users actually setting? If it is nobody, the fix is the log line and nothing else. If people
are setting resumeOnActionIntent: false or custom streaming patterns, then v2 is missing
capabilities rather than just option names, and that is a bigger piece of work I would want to
scope with you before writing it.

Rudi

[Mte90]

Ideally we should keep one codebase at best to support both the version with a test suite.
We need to keep the compatibility between 1/2 so we can't remove settings.

[famewolf]

Thanks, Daniele — and agreed on the test suite: both versions need one.

On keeping one codebase that supports both versions, I can't honestly answer whether that's achievable — it's an open question and I won't claim it one way or the other. What I do know is that the install is necessarily version-specific: a user installs for OpenCode v1 or for v2, not both at once, so whatever shape we land on has to serve that.

On keeping the settings: I don't see how that can work as stated. v1 and v2 are totally different APIs with different calls, and about half of v1's calls don't exist in v2 at all — the issue body lists them (the client.session.* calls, client.app.log, client.provider / client.config / client.tool.ids, client.tui, plus the hooks with no direct v2 equivalent). A setting that only makes sense on top of a call that doesn't exist on the other side can't be carried over. The most I can promise is the small fix from my last comment — log at startup the options v2 doesn't recognise, and map the ones that do have a v2 equivalent — rather than true 1/2 settings compatibility.

If you can tell me which of the 16 options your users actually set, I can tell you precisely which of those are mappable and which are not.

Rudi

[Mte90]

I use some options but I added them because user requested them so we need to keep them, the one that are not usable we can remove it.

For the codebase we have to see how to keep just one like a mini library.

[famewolf]

Thanks — and one correction to my last comment, because it changes what you can decide here.

The settings can be kept

My "I don't see how that can work as stated" was too strong, and the reason I gave for it doesn't
hold. Options don't come from an API. They come from the plugin loader, on both versions:

• v1 — src/index.ts:493, async (ctx, options). Every setting is read in one contiguous block
  at 495-561, as (options?.X as T) ?? DEFAULT_X.
• v2 — src/v2/index.ts:470, const opts = (ctx.options ?? {}) as AutoResumeOptions. Same shape.

So none of the 16 options I listed is blocked by a call that only exists on one side. Of those 16:

• 14 are plain values — numbers, prompt strings, regex lists, one enum. They carry over as-is.
• 1 is a rename, not a removal. maxRecoveryRetries → maxRetries: v2 already caps the same
  loop at src/v2/index.ts:831 (0a0a961 restored the hard stop). Aliasing the old name is two
  lines.
• 2 wait on a decision that is already open between us. subagentWaitMs and
  subagentNativeCompactionEnabled both gate subagent handling, and the v2 port has no subagent
  detection at all today — isSubagent / parentID appear nowhere in src/v2/index.ts, where v1
  has them at 2253, 2383 and 2681.

That last one is not a limitation, it's an unanswered question, and the code is already written.
Branch local/v2-subagent-guard on my fork is 3 commits ahead of pr20-v2port and 0 behind:

4828e73  never inject into or interrupt a subagent; widen stall window to 180s
62f87e3  track open shells from the registry events; don't recover a busy parent
c19f1f6  gate the proactive nudge on open shells too, and cover it with tests

src/v2/index.ts (+171/−4) and a new src/v2/index.open-shell.test.ts (+238). It adds the
parentID-based detection v1 has, which is exactly the prerequisite both options need — after that
they are a one-line gate each, or a drop if the v2 equivalent turns out to be unconditional.

I asked on #37 whether to fold it into this PR or open it separately and haven't had an answer. So
the honest status is: the code exists, the mapping is not written, and both are waiting on you.

That gives you the "keep what works, drop what doesn't" split you're after: keep the 14, alias the
rename, and hold the 2 until you decide on the guard. I'm not volunteering to write the option
mapping on top of it. None of it blocks landing #37.

One thing I said that isn't true

In the #33 report I listed client.session.*, client.app.log, client.provider,
client.config, client.tool.ids and client.tui as missing on the v2 context, and then used
that to argue settings couldn't carry over. The API list is accurate; the conclusion I drew from it
was wrong. Those calls matter for detection — which is where they actually bite:

• v1 detects the magic-context plugin through ctx.client.config.get()
  (src/index.ts:1282). v2 exposes no equivalent, so if magic-context is installed, the v2
  plugin will not know and will not stand down for it. That one needs a real answer and I don't
  have one yet.
• contextSaturationThreshold needs usable, which is the client.session.messages dependency
  above.

The rest of the missing surface isn't reachable from a setting, so it doesn't affect the option
list. But it does mean one genuine interop gap that I should have flagged separately instead of
folding into an argument about settings.

On the single codebase / mini library

Also feasible — and not inside #37. The two entry points can't merge: v1 registers through
Plugin.define's hooks object, v2 registers { id, setup } and consumes ctx.event.subscribe().
But separate entry points don't have to mean separate code. Only 26 lines are literally shared
today, and what's duplicated is version-agnostic logic — the stall watchdog, the
hallucination-loop guard, done-claim detection, the backoff curve, block-site naming. A src/core/
with two thin entry points would remove most of it. That's a refactor of the path you're reviewing,
so it belongs in its own PR once #37 lands, not stacked on it.

If you want the extraction, say so and I'll scope it separately and let you decide from the shape
of it. #37 doesn't need it.

The one piece I'd commit to

There's a piece here I'd commit to, because it's self-contained and it turns every silent fallback
in the table above into something a user can see:

auto-resume.v2: ignoring unsupported options: warmupMs, subagentWaitMs, ...

One line at startup, info level, listing the option keys v2 doesn't recognise. No behaviour change,
no risk to the recovery loop — it just means a v1 config carried over to v2 says so instead of
quietly falling back to defaults. Say the word and I'll send it as a follow-up PR rather than
adding it to #37 while you're reading that one.

Three questions, no code

1. local/v2-subagent-guard: fold into Add OpenCode v2 port (src/v2) + OOC lock parity #37, or take it as its own PR? Still open from my Add OpenCode v2 port (src/v2) + OOC lock parity #37
   comment. It's the gate on the two subagent options, and it's the one thing where the work is
   already done and just needs a home.
2. Which options do your users actually set? You said "I use some options" — naming them is
   what decides whether the remaining mapping is a 30-line commit or a real port. I've asked twice;
   it's the only thing gating my answer on scope.
3. docs/v2/installing.md still tells users to install @opencode/plugin, but src/v2/index.ts
   has zero imports and defines the { id, setup } helper locally, so the built artefact is
   dependency-free. Those two contradict each other. The install instructions are yours, so I didn't
   rewrite them — but one of us should fix it before Add OpenCode v2 port (src/v2) + OOC lock parity #37 lands.

Rudi

[Mte90]

I would like a single PR with everything to port this plugin to support v2 and keep compatibility with v1.

I use some options again, but we need to support all of them and remove the one that aren't compatible with v2 only for v2, we don't want to break the UX.

[famewolf]

Where the v2 port stands, and the one part of the request I did not do.

The request I am declining

A single PR that ports the plugin to v2 and keeps v1 compatibility, as one shared codebase rather than two modules, is outside what I am comfortable doing on this codebase.

The concrete reason: the two plugin APIs do not overlap enough for a shared module to be a simplification. v2 has no ctx.client.session.list, no ctx.app.log, and no client.tui; its event stream is a flat AsyncIterable instead of a hook with properties; AssistantTool has no callID; the tool lifecycle is increment/decrement events rather than before/after hooks. Every one of those is a different code path, not a different spelling of the same one. Unifying them means a module where large stretches are version-conditional, and where the v1 test suite has to keep passing against an API that only one of the two runtimes provides. I would be making the plugin harder to change in both versions to make one file, which is the opposite of what I want out of it.

So the port stays a separate module. That is a decision about my own contribution, not a recommendation about what the project should do.

The goal was a working v2 plugin for personal use. The branch is a contribution; how it gets used, folded in, or set aside is entirely a call for the maintainer, and nothing below depends on the answer.

What the port is, in numbers

• src/v2/index.ts, 3,514 lines, a new module. src/index.ts is not touched — the diff is 21 files and none of them are v1.
• All 31 of v1's options are read and all 31 are applied. I write "applied" deliberately: reading an option without acting on it is the usual way a port looks finished and behaves inert. The first push that read all of v1's options gated 8 of them — contextSaturationThreshold, discoveryDelayMs, doneWithoutWorkPrompt, silentDeadStreamMinTokens, subagentNativeCompactionEnabled, subagentWaitMs, thinkingToolRecoveryPrompt, toolTextCheckDelayMs — held them in FEATURE_GATED_OPTIONS, and named them on the startup line as accepted-but-inert=… so a config quietly doing nothing was visible rather than silent. Each was then closed in its own commit. That list is now empty, and a test fails if an option is ever added to the recognized set without being implemented, so the count cannot drift back up unnoticed. Two options are v2-only, because v2 removed the thing they configure: logFile (there is no server log endpoint any more) and injectIntervalMs.
• 188 tests across 13 files, one per feature area, driven through the real event stream. 774 pass / 0 fail / 48 files with v1 included.
• Three new docs: docs/known-issues-v2.md, docs/v2/installing.md, docs/v2/migration.md.
• 27 commits ahead of master, with master merged in so the branch is not conflicting.

Duplicated code? Yes. Two modules, two test suites, the same option names. The v2 module defines its own { id, setup } helper and imports only node:fs, node:os and node:path.

Documentation? A separate file per version: docs/known-issues-v2.md records every way the v2 build differs from v1, including the API changes that forced a different implementation, so the README's shared parts stay shared. A test asserts that file's accepted-but-not-applied list against FEATURE_GATED_OPTIONS in both directions, so neither can drift.

Do the settings work? On the v2 port, yes — all 31 are read and all 31 are applied. I checked the second half rather than trusting the empty gate list, which only shows the list was emptied: each option's value was traced to the code that consumes it. The last one to close was toolTextCheckDelayMs (below).

What v2's API changed, and what is missing because of it

The port was written against v2, using v1 as the base. Four things v1 had no longer exist, and each one cost a feature rather than a line of code:

• The server log endpoint is gone. v1 logged through ctx.client.app.log(); in v2 ctx.app is only { name, version, channel }, there is no app group in the protocol, and a hosted plugin's console.log is not captured by the OpenChamber process. A console-only build is silent, so a running watchdog and a dead one look the same. This build appends to ~/.local/state/opencode-v2/auto-resume.log instead — overridable with logFile or AUTO_RESUME_LOG_FILE, truncated at 2 MB, every write best-effort so an unwritable directory never breaks the watchdog.
• The todo table is unreachable. v2 creates it in the database but exposes no route to it and emits no todo.updated event, so there is no way to watch the list change. auto-resume reads the key the installed todo tool already writes, ctx.storage.get("todos/<sessionID>"), and only ever calls get — a consumer, not a second owner, so it works with whichever todo tool is installed, and there is no second copy to fall out of step. It is also why the block-site message on v2 names the blocking items, which is the v1 fix for #28. One v1 behavior is not ported as a result: todoCheckAttempts, the two chances a turn gets when it says "ready to continue" while every todo is already closed. With no ctx.storage, or a record it cannot parse, it falls back to "no list" — the older behavior, latch on the emoji and ask for details on a bare done-claim — never a nudge on the strength of a list it failed to read.
• The tool name registry moved. v1 asked ctx.client.tool.ids(); that route does not exist in v2, so the port uses ctx.tool.list(). With no registry, an empty one, or one that throws, the check abstains rather than guessing — with no list every name looks invented, and a check that guesses is worse than one that abstains.
• The plugin session domain is a narrowed Pick. session.active() and session.list() are both omitted from it. Both are read defensively, from the plugin domain first and then the raw client, and a host that supplies neither degrades to the event-derived busy set rather than failing.

Smaller shape changes that had to be coded around: v1's "pending" tool status does not exist in v2, so the v1 check that tests for it has no equivalent; session.summarize() is now session.compact(); v1's config.get() has no counterpart, so the magic-context lookup goes through ctx.plugin.list(); and v2 has no built-in task_complete, so the port registers it through ctx.tool.transform.

Things that were never mentioned and should have been

A doc bug in the port's own install guide. It opened with a mandatory bun add @opencode/plugin@2.0.5, inherited from the beta port that did import the package. This one does not import it — the built file is self-contained — so that step was telling users to install a package the plugin never loads, and the troubleshooting table carried a row for a Cannot find package '@opencode/plugin' failure this build cannot produce. Fixed, along with chunkTimeoutMs documented as 45000 in three places, and a "12 tests" claim in the migration notes that had gone stale.

toolTextCheckDelayMs, the last option to close. Ignoring it loses a race. v1 never judges a finished turn on the session.idle event: it arms a timer for that option and runs the done/tool checks from there, because session.idle can arrive while the assistant's closing text is still being written into the message history, so a check that reads too early sees a half-finished turn. Judging on idle works most of the time on v2 because the plugin sees text as it streams — and fails in exactly the case that matters, when the plugin loads mid-turn and the buffer is empty, leaving the not-yet-flushed history as the fallback. The idle handler is now two passes: structural checks immediately (a dead stream has no text for the pattern checks to read, so deferring it would only delay a certain recovery), then the pattern checks after the delay, re-reading the history and re-running the structural guards, because three seconds is long enough for a person to have replied.

Two of the new tests were vacuous. A hand-off test that set up the hand-off from the start proved nothing: the structural pass refuses and never arms anything, so the assertion held whether or not the pattern phase looked at the text again. It only became a real test once the hand-off arrived during the wait. Every test in the port is now mutation-checked — removing the delay, the arming, the history re-read, either guard re-run, the cancel latch, the new-turn cancel or the cleanup each turns the file red.

v1 issues filed and closed along the way

All of these are on Mte90/opencode-auto-resume, all are closed, and all six fixes are on master. #26 looping "your last response" prompt, #27 idle nudges firing while a question awaited input, #28 block-site message not naming open todos, #32 "aborted due to timeout" not treated as retriable, #35 the test suite hanging, #38 the 45s chunk timeout. #38 is the one that moved chunkTimeoutMs to 180s.

The subagent guard was added to the port and is on the branch: a turn that has spawned a subagent, or that has a live shell open, is not nudged or resumed out from under itself.

Suggestion

If one codebase matters more than a duplicated module, the shape I would trust is a shared core — the detectors and the recovery decisions as plain functions over a small interface, with a thin v1 adapter and a thin v2 adapter on top. That gets one copy of the logic without making either version's runtime shape conditional at every call site, and v1's tests can keep running against the core directly. It is a bigger change than a port, though, and it wants its own branch and its own review rather than being folded into a port that is already large.

The useful parts survive as individual commits. The test files are the part worth keeping either way — they document what v2's API actually does, including the ordering traps.