Add OpenCode v2 port (src/v2) + OOC lock parity

[famewolf]

[PR] OpenCode v2 port (src/v2/index.ts) on the stable @opencode/plugin API

Full disclosure — this is a port, and it was done with the assistance of AI.

src/v2/index.ts is a port of v1's behavior, not new functionality. Every recovery path it contains already exists in src/index.ts; the work was re-expressing that behavior against v2's plugin API, and keeping the two in step. The same holds for the test suite: its 188 tests exist to prove the port matches v1, not to specify anything new.

The implementation, the tests and these docs were produced with the assistance of an AI coding agent (via OpenCode) working from the v1 source, and were reviewed by the author. Flagging it plainly because a reviewer is entitled to know how the code was produced before reading it. A port this size is exactly the kind of change where "the tests pass" is weaker evidence than it looks: the tests and the code came out of the same session. Every claim in this description is checkable against the diff, and the v1 module is untouched precisely so the comparison is easy to make by hand.

One defect in v1 fell out of the port work and is not addressed here: a revert does not clear watch state, so a rewind carries one turn's watch state into the next. This PR does not touch v1, and the revert is written up separately against master with a patch. A related v1 bug — an idle nudge firing while a question awaited input — was found earlier and is #27, fixed on master in 7796b2f. The same stand-down guard is in the v2 port.

A second plugin module for the same recovery behavior, written against the stable v2 API. src/index.ts (v1) is not touched: the PR's diff is 21 files, none of them v1.

Branch	pr20-v2port (famewolf/opencode-auto-resume)
Port	src/v2/index.ts, 3,514 lines
Options	all 31 v1 options read and applied, plus 2 v2-only
Tests	13 v2 test files, 188 tests; 780 pass / 0 fail / 48 files repo-wide
Docs	docs/known-issues-v2.md, docs/v2/installing.md, docs/v2/migration.md

Problem

This plugin only works on OpenCode v1. On v2 the v1 file does not load at all — a different plugin API, so the entrypoint fails with Cannot find package '@opencode/plugin'. Anyone who has moved to v2 has no auto-resume, and there is no partial option: the module either loads or it does not.

What the v2 API required

Concern	v1	v2
Plugin shape	hooks object + ctx.client	{ id, setup }, setup returns a cleanup fn
Events	event hook, { type, properties }	ctx.event.subscribe() AsyncIterable, flat { type, data }
Calls	ctx.client.session.* over HTTP	flattened onto ctx.session.*; no list/active, so discovery goes through callSessionApi with client-side verification
Assistant text	session.messages() polling	accumulated from session.text.delta, with ctx.session.context() as the authority
Logging	ctx.app.log	no log sink exists in v2 — the port writes its own log file

Two shape differences are worth naming because they would have made a detector inert rather than wrong, which is the harder failure to notice: AssistantTool carries its name in part.name with no callID, and the tool lifecycle is session.tool.called (increment) against .success/.failed (decrement).

Feature parity, and what running it live turned up

Every recovery path v1 has is here — stalled-stream watchdog, execution/step failure recovery, provider-retry awareness, tool-call-as-text detection, ready-to-continue and stalled-intent nudges, done-claim verification, the hallucination-loop guard, subagent and permission awareness, the visible recovery notification.

Parity was the bar. The first push was a port of the architecture rather than the behavior; running it live found the rest, one commit each. The ones that changed what the plugin does:

• Unknown tool calls — v1 suggests the closest real tool name; the first v2 version silently ignored them.
• Silent dead streams — a finished assistant message with no text part and enough output tokens is a stream that died mid-response. It is the case where every text-based check has nothing to read, so it is caught on the idle event rather than after the settle delay.
• Premature stop — a turn that ends mid-thought without claiming completion, and activeUserWindowMs made real instead of decorative.
• Context saturation — routes a saturated parent to magic-context ctx-wrapup, a saturated subagent to native compaction.
• Todo list — read from the session message log (GET /api/session/<id>/message), because ctx.storage is namespaced per plugin and can never see another plugin's writes; ctx.storage.get("todos/<id>") survives only as a last-resort fallback. The open-todos nudge is gated on the list rather than on the model's emoji.

Since the above was written, six commits landed on this branch, all about the
todo list, its tests, and its docs — no behavior change except the first:

• a83e158 — the todo read described above (message log first, storage last).
  Before it, the port read only ctx.storage, which is namespaced per plugin
  and can never see another plugin's list, so it concluded "no todos" while
  work was still listed and fired false done-claim nudges.

• 801e22e, a355db3, 5f3fb0a — docs/comments only: why the storage key
  can never work cross-plugin, why the parser is a copy rather than an
  import, and the same correction in docs/known-issues-v2.md (which had
  contradicted the README) plus the test count 774 → 780.

• ef25e39 — test only: one intermittent failure in 9 runs
  (index.options.test.ts, expected >= 2 nudges got 1). The test pushed two
  idles 10ms apart with a 0ms pattern delay and assumed the first timer fired
  inside the gap; under load the second idle replaced the first pass (the
  replace-don't-stack semantics above, working as designed) instead of
  following it. The test now gates on the observed nudge. Product code
  untouched.

• f773ea6 — docs only: README and docs/known-issues-v2.md now name opencode-todo-fork as the confirmed todo plugin; others unconfirmed.

• Explicit completion — a task_complete tool, so "done" is a signal instead of a string to pattern-match.

• Reasoning-tool recovery — a tool call written into reasoning is asked for again properly.

• Orphan parent recovery — a parent left waiting on a subagent that will not answer, which no amount of nudging fixes.

• The settle delay — see below.

Every option is now applied

FEATURE_GATED_OPTIONS is empty. Earlier pushes accepted options the port did not yet act on, and the startup line reported them as accepted-but-inert=…. The last of those was toolTextCheckDelayMs, and the reason it took longest is that its absence was a real bug, not a plumbing gap.

v1 never judges a finished turn on the session.idle event. It arms a timer 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 — a check that reads too early sees a half-finished turn. The v2 port judged on the idle event, using the live delta buffer, which usually has the final turn by then and is empty when the plugin loads mid-turn. The fallback in exactly that case is the history that may not have flushed.

So inspectOnIdle is now two passes:

Pass	When	Decides
structural	on session.idle	dead stream, user hand-off, user recently active
pattern	+ toolTextCheckDelayMs	celebration, tool-call-as-text, ready-to-continue, action intent, done-claim

The pattern pass re-reads the history — that is the point — and re-runs the structural guards rather than trusting the first verdict, because three seconds is long enough for the user to have replied. A new turn cancels a pending pass, a second idle replaces rather than stacks, and cleanup drops any pending timer.

The inert-reporting machinery is kept rather than deleted. It is the only signal a user gets that an option is being ignored, so with nothing left to report at runtime, a test asserts the invariant on the source instead: a test fails if an option joins the recognized set without being implemented.

How the port is tested

188 tests across 13 files, one per feature area, driven through the real event stream with a harness that reproduces v2's ordering. The gotchas that cost time are documented in the tests, because each one produces a failure that looks like a logic bug:

• a finished assistant message with no text part is a dead stream and fires first, so reasoning and unknown-tool fixtures need an explicit text part
• an idled session must be removed from the harness's active set, and a reset needs a full execution.started → step.started → step.ended → idle cycle
• a per-request re-arm derived from history cannot run before the history read — a real ordering bug, found this way

The settle-delay file is 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 turn it red. Two of its tests were vacuous on the first pass and are only meaningful because of that check.

docs/known-issues-v2.md and the README's option list are checked against FEATURE_GATED_OPTIONS in both directions, so a documented-but-unimplemented option cannot pass quietly.

Installation

Nothing to install first. src/v2/index.ts imports only node:fs, node:os and node:path and defines its own { id, setup } helper, so a local-file install needs no bun add — copy the file into ~/.config/opencode/plugins/ (or <project>/.opencode/plugins/) for auto-discovery, or register it in config:

{
  "plugins": [
    { "package": "./plugins/auto-resume-v2.ts",
      "options": { "chunkTimeoutMs": 180000, "maxRetries": 3 } }
  ]
}

@opencode/plugin@2.0.5 is a typecheck dependency, not a runtime one. Full steps and a v1→v2 migration checklist are in docs/v2/.

The install guide had been telling users to bun add @opencode/plugin@2.0.5 because the beta port did import the package. This one does not, so that step is gone, along with the troubleshooting row describing the Cannot find package '@opencode/plugin' failure this build cannot produce. docs/v2/installing.md also had chunkTimeoutMs at 45000 in three places and a 12-test count that stopped being true a while ago.

Relationship to the other open PR

The companion PR ("Stop the recovery-continue infinite loop") fixes v1's retry-counter reset and adds an OOC lock to src/index.ts. This port is independent — a separate module, unaffected by that patch — and carries the same exceeds the available context size lock-out, plus maxRetries and a continueTimestamps loop guard.

master was merged into this branch (27 commits ahead). The only hand-resolved conflict was two rows in the README option table, where both sides had rewritten them; the port's version is kept, because it is the one that also covers the subagent case.

---

The deployed v2 build running on the author's box is a build of this module; this PR is its source of truth.

[famewolf]

While landing the v2 "Step interrupted" fix I checked the v1 plugin (src/index.ts, v1 API) to see whether it needed a back-port. It does not — v1 is not affected by this bug — and I wanted to record why so the PR history is clear:

1. Different prompt model. v1 sends recovery turns with ctx.client.session.prompt, which does not interrupt a session's in-flight step when a new turn lands. v2's ctx.session.prompt does — that is the whole source of the "Step interrupted" error. v1 cannot hit this failure mode.
2. v1 already had the guard v2 was missing. v1 carries the continue-loop hard-stop (a maxRecoveryRetries cap plus a gaveUp latch that re-arms only on a genuine user message). The v2 port had dropped that; the OOC-lock commit in this PR (0a0a961) restores it. So the one place v2 needed to match v1 is already done.
3. The new v2 guards are net-new. The compaction guard and the inject-time live-busy guard (9a44699) address a v2-only failure mode. v1 has no compacting flag and no compaction/inject guard — not because it's less careful, but because its prompt model can't interrupt an in-flight step, so it never needed them.

Bottom line: v1 is unaffected; no back-port to v1. The v2 fix (9a44699) is v2-specific and is what this PR carries (already on this branch).

[famewolf]

Added a hand-off guard in 0dd0403:

isUserHandoff() detects a turn that cleanly ends by handing control back to the user — a question, or an explicit prompt — and inspectOnIdle() now skips its targeted continue nudge for such a turn.

This closes the last source of "Step interrupted": previously the plugin could inject a synthetic continue right after a hand-off turn (its last assistant message matched a tool-call/done-claim heuristic), starting an in-flight step; when the user then answered the question, their reply interrupted that step. A hand-off turn is, by design, awaiting the user, so it is never nudged now.

Purely additive — no change to the existing stall / compaction / OOC-loop guards. tsc clean; running on my box (md5 226d48ed63757983f4fd4c4512e30fcc).

[valentimarco]

i will try the branch. Also on my code there was a bug where the tools (like questions) where interruped, will update if occurs again

[famewolf]

@valentimarco the question interruption bug you mentioned is fixed — it's in 67c34ff on this branch, so the checkout you're testing already has it.

There were two independent defects behind it, both in src/v2/index.ts:

1. The stand-down guard could never fire. shouldStandDownForUser tested

part?.state?.status === "pending"

but the v2 message projection never writes pending — an in-flight tool part reads running and settles to completed or error. pending was the v1 spelling. With that branch unreachable, auto-resume injected a synthetic continue over an unanswered question, which is what interrupted the tool call.

It now stands down on running/pending, and additionally on interactive tools (question, permission, ask, confirm) unless they reached completed — a question that comes back error was interrupted, not answered, so it still holds the turn.

2. markIdle() destroyed the permission guard before it was read. The session.idle case calls markIdle(sid) and then inspectOnIdle(sid), and markIdle set w.permissionPending = false. So the flag was always false by the time the guard that honours it ran — dead on exactly the transition it exists for. permission.replied is now the only thing that clears it, plus a TTL stale-clear mirroring the existing compaction one, so a permission.asked whose reply never arrives can't strand a session forever.

Two details worth knowing when reading the store, since both are easy to get wrong: ctx.session.context() returns a plain array, not { messages }. And across a live v2 session the tool-part states are completed 390, error 7, running 1 — no pending anywhere, which is what made the old condition look plausible in review.

Tests — src/v2/index.stand-down.test.ts drives the real v2 seam (ctx.event.subscribe async iterable → session.synthetic), so it asserts on real injections rather than grepping source. It carries a mandatory control that recovery does fire when nothing is pending — without it every other case passes vacuously — plus over-blocking controls (answered question, non-interactive tool erroring, permission asked-then-replied), so the fix can't silently disable auto-resume. 7 of its 13 assertions fail against the previous code. Full suite 591 pass / 0 fail, tsc --noEmit clean.

[famewolf]

Small addition rather than a change: the port's revert handling documents the
v2 event names but doesn't handle them yet, and this fills that in — your
session.reverted shim is left exactly as it is.

The switch has:

// v1 legacy: not emitted in v2 (reverts now surface as
// `session.revert.cleared` / `session.revert.committed`). Kept
// defensively so older runtimes still drop their watch state.
case "session.reverted": {

That comment names the two v2 events, but neither is handled anywhere in the
switch — on a real v2 runtime a revert matches no case, so the session's watch
state (including any armed recovery) survives the rewind of the conversation
it was tracking.

Checked against a running v2 server — all three are declared event schemas with
live store handlers:

type:"session.revert.staged"      case "session.revert.staged":    … "revert", C.data.revert
type:"session.revert.committed"   case "session.revert.committed": … "revert", void
type:"session.revert.cleared"     (same shape)

staged is intermediate — the server holds a revert payload there, so the
user can still clear or commit it. committed and cleared are terminal; the
server clears the field on both.

The change

Adds the three events alongside your existing case (which stays byte-for-byte
untouched):

case "session.revert.staged": {
    const sid = sidOf(ev)
    if (!sid) return
    touch(sid)   // staging is activity, not terminal — keep the state
    return
}
case "session.revert.cleared":
case "session.revert.committed": {
    const sid = sidOf(ev)
    if (!sid) return
    sessions.delete(sid)
    return
}

Terminal stages drop the state, consistent with how the port already handles
session.deleted. staged only touches, so a revert the user then abandons
doesn't needlessly tear down the watch. The commit is purely additive.

tsc --noEmit is clean. The new cases only ever fire on v2 event names, so
the shim's behaviour is unchanged and the watchdog logic is untouched.

If you'd rather keep this PR to the port itself, happy to split it into its
own PR — it's one self-contained commit with no interaction with the rest of
the port.

[famewolf]

One more v1-parity item for this port.

The v1 plugin detects subagent sessions and excludes them from recovery. Two
places in src/index.ts on master:

• handleEvent (~L2675):
  w.isSubagent = typeof parentID === "string" && parentID.length > 0
• startTimer (L2247): if (w.isSubagent) continue — a subagent is never the
  target of the stall "continue" prompt.

The v2 port dropped both. Consequence: a child session (spawned as a subagent)
is indistinguishable from the parent, and both injection paths here —
injectOnce() and tryAbortAndResume() — can target it. That matters because a
child never reads the parent's AGENTS.md, so a "stand down on injected
continues" rule in the parent gives it no protection once the prompt arrives as
a task turn in the child, mid-task.

I have the port-side fix on my fork, branch local/v2-subagent-guard:
famewolf/opencode-auto-resume@pr20-v2port...local/v2-subagent-guard
(three commits, all additive on top of this PR's head). It re-adds the
parentID-based skip at the top of both injection paths, tracks open shells from
the shell.created/shell.exited registry events so a busy parent isn't
force-resumed, and aligns the stall window with v1
(DEFAULT_CHUNK_TIMEOUT_MS 45s → 180s — proposed for v1 master as a separate,
independent PR).

Happy to either fold this into PR #37 as a follow-up commit or open it as its
own PR stacked on pr20-v2port — whichever you prefer.

[famewolf]

Fix for the test failure on 1667832 — follow-up commit b27cda5 (test-only, CI green)

The 1/1026 failure (v2: silent tool completions defeat the exact-duplicate skip > a tool that ran silently between prods re-arms the stall prod — expected ≥ 2 prods, got 1) was a racy test, not a production bug.

Root cause: the test scheduled its session.tool.success at t+300ms, but with 20ms stall ticks the default lifetime cap (9 continues) burns in ~230ms and stands the session down before the event arrives — so no second prod could fire regardless of what the duplicate-skip logic did. The skip defeat itself was always correct (completedSinceProd increments on session.tool.success in src/v2/index.ts:6397, per-stall ladder restarts via succeededSinceProd at :3245); I verified that with isolation probes where the session was still alive. It passed or failed by machine speed, which is why it went red on this run.

Fix in src/v2/index.dup-progress.test.ts:

• tool event 300ms → 100ms (mid-ladder, before the cap burn)
• lifetimeMaxContinues: 99 in the test options, so the test exercises the skip gate instead of racing the lifetime gate

Deliberately did not touch lifetime-cap semantics — clearing it on tool completions would gut real loop protection.