[tbrandenburg]

Summary

Follow up on the merged OpenCode V2 adapter (#3367) with typed 404 handling and changed-file timeline preservation, adapted to current main after #3456.

Changes

• Decode V2 _tag errors on session routes, including message history. Only SessionNotFoundError means the session is unavailable; missing commands, models, locations, permissions, and forms retain execution-error diagnostics. Malformed or oversized error bodies cannot establish session absence.
• Preserve typed V2 errors during resumed-session setup and reconciliation, while retaining unavailable/waiting handling for host outages and missing sessions. Regression tests check that setup errors do not interrupt or replace user-supplied sessions.
• Normalize assistant snapshot.files into a stable patch event. Append it after usage normalization so a snapshot appearing during refresh does not duplicate the usage timeline event. Repeated refresh tests verify updated files, stable sequence/timestamp, and no redundant progress update.
• Extend real OpenCode 2.1.4 validation with an unknown command, a real file write and snapshot, and missing-session responses. Existing question/resume and cancellation-settlement checks remain in that test.
• Link managed OpenCode sessions from the README action table.

Scope boundary

Command timeout policy is deliberately not changed. The old handoff removed the HTTP timeout using the caller context; current upstream instead uses context.WithoutCancel to learn the outcome of potentially accepted submissions. Removing its remaining bound would require a separate decision. Admission, deduplication, interruption, and settlement logic from #3456 is not replaced.

A separate temporary diagnostic against the new patch and OpenCode 2.1.4 confirms the remaining gap: a command containing a 31-second shell substitution returned after 30.568 seconds with unavailable, PromptSent=true, and zero provider calls. This diagnostic is not part of the submitted patch. The preexisting command-admission failure path's unconditional interrupt also remains outside this PR's scope.

Validation

New regressions were run before their fixes and failed for typed 404 classification, snapshot omission, resumed-host routing, swallowed history errors, malformed trailing JSON, and snapshot/usage timeline duplication.

Verified on Linux with Go 1.27.3 and OpenCode 2.1.4, using isolated temporary state and a local deterministic HTTP provider:

go test -race -count=1 ./internal/runtime/builtin/harness/... ./internal/opencodehost/...
go test -race -run '^TestV2' -count=20 ./internal/runtime/builtin/harness/
DAGU_TEST_OPENCODE_V2_EXECUTABLE=/path/to/opencode-2.1.4 \
  go test -race -run '^TestRealV2Run$' -count=2 ./internal/runtime/builtin/harness/
go vet ./internal/runtime/builtin/harness/... ./internal/opencodehost/...
go fix -embedlit=false -diff ./internal/runtime/builtin/harness/... ./internal/opencodehost/...

The affected package race suite passed; the real-V2 test passed twice; scoped vet/fix and formatting checks produced no findings. Repository-configured golangci-lint 2.13.2 reported zero issues. Independent review findings were addressed and re-reviewed.

Validation limitations: directory-boundary-corrected lint exposes the same 22 findings on untouched upstream and this patch; the changed-lines comparison reports zero new issues (see #3465). Windows/Darwin lint attempts exceeded three-minute package-loading budgets. Full make fmt/make check, repository-wide Go tests, frontend/API suites, and conformance were not run; this is a package-scoped harness change with no schema, frontend, workflow-language, or CLI changes.

Related Issues

Closes #3467 (tracking issue for the fixes in this PR).

Replaces the remaining applicable work from philo-x/dagu#1. Related: #3367, #3456, and the lint-exclusion follow-up #3465. This does not reopen or claim to resolve the closed cancellation issue #3448.

Checklist

• Code follows the project style guidelines
• Self-review of the code has been performed
• Tests have been added or updated as needed
• Documentation has been updated as needed
• Changes have been tested locally

---

Summary by cubic

Classifies OpenCode v2 HTTP 404 responses so a session is marked unavailable only when the error is SessionNotFoundError. Missing commands, models, locations, permissions, and forms keep execution-error diagnostics instead, and typed errors survive resume and history reconciliation.

• A run that cannot reach the host before it has a session now fails immediately, so the step can fall back to the CLI or retry; only resumed sessions wait for the host to return.
• History polling fails a step only on typed 404s naming a missing resource; transient errors such as 5xx or unreadable pages retry on the next poll as with v1 hosts.

Assistant snapshot.files are normalized into a stable patch timeline event appended after usage normalization, so a snapshot appearing during refresh does not duplicate the usage event. Regression tests cover 404 classification, malformed and trailing error bodies, host-down and resume routing, transient vs. typed history errors, and snapshot/usage timeline stability. Real OpenCode 2.1.4 validation now includes an unknown command, a real file write with snapshot, and missing-session responses, and the README action table links managed OpenCode sessions via a relative doc link. Command timeout and admission/interruption policy are unchanged.

^{Written for commit 626c4b8. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Assistant messages now include file changes from content snapshots as patches.
• Bug Fixes
  • Managed OpenCode sessions now report unavailable or missing sessions more clearly, while preserving other session and history errors.
  • Failed message refreshes on newer OpenCode sessions now surface their errors.
• Documentation
  • The harness.run action description now links to documentation for managed OpenCode sessions.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 8112c585-089b-43d5-ba9d-c90f3d90d786

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• Trigger review

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: ce677877-d170-49e8-a88e-27792b040cc5

Commits

Reviewing files that changed from the base of the PR and between ddda00c and 5a41ec7.

Files selected for processing: 5

• README.md
• internal/runtime/builtin/harness/opencode_client.go
• internal/runtime/builtin/harness/opencode_managed.go
• internal/runtime/builtin/harness/opencode_v2.go
• internal/runtime/builtin/harness/opencode_v2_test.go

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

Walkthrough

OpenCode v2 now classifies typed API errors, propagates selected managed-session errors, and includes snapshot file paths in normalized assistant messages. The changes also add v2 run and error tests, plus a README link to managed-session documentation.

Changes: Managed OpenCode

Layer / File(s)	Summary
V2 error classification and managed-session handling internal/runtime/builtin/harness/opencode_client.go, internal/runtime/builtin/harness/opencode_managed.go, internal/runtime/builtin/harness/opencode_v2.go, internal/runtime/builtin/harness/opencode_v2_test.go	Non-2xx responses use typed error handling. V2 managed-session paths preserve or propagate selected errors. Tests cover tagged 404 responses, resume errors, history errors, and unavailable sessions.
Snapshot files in normalized messages internal/runtime/builtin/harness/opencode_v2.go, internal/runtime/builtin/harness/opencode_v2_test.go	Assistant messages with snapshot files include a patch part. Tests check patch contents, identity, and refresh behavior.
Real-run coverage and documentation internal/runtime/builtin/harness/opencode_v2_test.go, README.md	The real-run test initializes a Git worktree and checks command and tool-call behavior. The README links to managed OpenCode documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• dagucloud/dagu#3367: This PR changes the OpenCode v2 routes and message normalization introduced there.
• dagucloud/dagu#3331: This PR extends the normalized message path with snapshot patch parts and tests usage-event ordering.
• dagucloud/dagu#3456: This PR refines error handling in the managed OpenCode session flows added there.

Merge Risk: Minimal · previous review 5a41e

No actionable merge-blocking issue was identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main changes: OpenCode v2 error classification and snapshot retention.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The pull request description follows the required template. It includes a clear summary, detailed changes, scope boundaries, related issues, validation results and limitations, and a completed checkli…

Full details: Description check

Explanation

The pull request description follows the required template. It includes a clear summary, detailed changes, scope boundaries, related issues, validation results and limitations, and a completed checklist.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 5 functions across 4 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[yohamta0]

Thanks Tom, nice work on this, especially the real 2.1.4 coverage.

I pushed two small fixes on top:

• A fresh run that can't reach the host fails again instead of waiting, so the CLI fallback and retries still work.
• One flaky history read no longer fails the step. Typed 404s still do.

[cubic-dev-ai]

1 issue found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/runtime/builtin/harness/opencode_client.go">

<violation number="1" location="internal/runtime/builtin/harness/opencode_client.go:180">
P2: The V2 create-session route is excluded from typed 404 decoding because its client path is exactly `/session`. A typed 404 from `POST /api/session` therefore loses its `_tag` and `errManagedNotFound` classification; include the exact create route in decoding while preserving the existing-session unavailable mapping only where appropriate.</violation>
</file>

<sub>Reply to a comment to ask cubic a question or push back. It learns from your replies.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The V2 create-session route is excluded from typed 404 decoding because its client path is exactly /session. A typed 404 from POST /api/session therefore loses its _tag and errManagedNotFound classification; include the exact create route in decoding while preserving the existing-session unavailable mapping only where appropriate.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At internal/runtime/builtin/harness/opencode_client.go, line 180:

<comment>The V2 create-session route is excluded from typed 404 decoding because its client path is exactly `/session`. A typed 404 from `POST /api/session` therefore loses its `_tag` and `errManagedNotFound` classification; include the exact create route in decoding while preserving the existing-session unavailable mapping only where appropriate.</comment>

<file context>
@@ -180,6 +176,36 @@ func (c *openCodeClient) json(ctx context.Context, method, path string, body, ta
 }
 
+func (c *openCodeClient) apiError(resp *http.Response, method, path string) error {
+	if resp.StatusCode != http.StatusNotFound || !strings.HasPrefix(path, "/session/") {
+		return fmt.Errorf("OpenCode API %s %s returned %s", method, path, resp.Status)
+	}
</file context>

[yohamta0]

Thanks again, Tom. Careful work, and the real OpenCode runs made this easy to trust. Merging.