oh-my-opencode 4.5.12 → 4.7.0

package/.agents/skills/opencode-qa/references/sdk.md

@@ -0,0 +1,96 @@
+# opencode SDK (@opencode-ai/sdk) - reference only
+
+A TypeScript/Bun way to drive opencode for QA. Prefer the tested CLI/curl scripts for portability; reach for the SDK when you want typed access from a Bun script.
+
+> IMPORTANT: method signatures differ between SDK versions and between the published docs and the generated client. ALWAYS check the installed version's types (node_modules/@opencode-ai/sdk) before relying on a signature, and verify against `GET /doc` (the OpenAPI spec the SDK is generated from).
+
+## Entry points and exports
+
+Package `@opencode-ai/sdk` subpath exports:
+
+- `.` (src/index.ts)
+- `./client`
+- `./server`
+- `./v2` (src/v2/index.ts)
+- `./v2/client`
+- `./v2/server`
+- `./v2/gen/client`
+
+Root and v2 entries export `createOpencode()`, `createOpencodeClient(...)`, `createOpencodeServer(...)`.
+
+`createOpencodeServer()` spawns `opencode serve ...` and waits for the startup line. `createOpencodeClient({ baseUrl })` wraps the generated client, rewrites directory/workspace headers, installs error interception.
+
+## Two ways to connect
+
+```ts
+import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk/v2"
+
+// A) embedded server (spawns opencode serve)
+const server = await createOpencodeServer()
+const client = createOpencodeClient({ baseUrl: server.url })
+// ... use client ...
+server.close()
+
+// B) connect to an already-running server
+const client2 = createOpencodeClient({ baseUrl: "http://127.0.0.1:4096" })
+```
+
+## Client namespaces
+
+Top-level on OpencodeClient:
+
+auth, app, global, event, config, experimental, tool, worktree, find, file, instance, path, vcs, command, lsp, formatter, mcp, project, pty, question, permission, provider, session, part, sync, v2, tui.
+
+## Useful methods (shapes vary by version)
+
+- `client.global.health()`, `client.global.event()`
+- `client.app.log(...)`, `client.app.agents(...)`, `client.app.skills(...)`
+- `client.config.get()`, `client.config.providers()`
+- `client.event.subscribe()` - SSE on /event; iterate `for await (const event of events.stream) { event.type, event.properties }`
+- `client.session` (legacy surface): list, create, status, get, update, delete, children, todo, diff, messages, message, deleteMessage, prompt, promptAsync, command, shell, fork, abort, init, share, unshare, summarize, revert, unrevert
+- `client.v2.session` (newer read/stream surface): list, prompt, compact, wait, context, messages
+- `client.part.delete(...)`, `client.part.update(...)`
+
+## Minimal QA snippet
+
+Arg shapes may differ by version. Treat this as a starting point, not a contract.
+
+```ts
+import { createOpencodeClient, createOpencodeServer } from "@opencode-ai/sdk/v2"
+
+const server = await createOpencodeServer()
+const client = createOpencodeClient({ baseUrl: server.url })
+
+try {
+  const session = await client.session.create({ title: "QA session" })
+  await client.session.promptAsync({
+    sessionID: session.id,
+    parts: [{ type: "text", text: "Say hello in one line." }],
+  })
+
+  const sessions = await client.session.list({ limit: 10 })
+  console.log(sessions[0]?.title)
+
+  const messages = await client.v2.session.messages({
+    sessionID: session.id,
+    limit: 20,
+  })
+  console.log(messages.items.length)
+} finally {
+  server.close()
+}
+```
+
+## Key types
+
+- Legacy Session: id, slug, projectID, directory, title, version, time.created/updated, optional workspaceID, path, parentID, summary, cost, tokens, share, agent, model, metadata, permission, revert.
+- Message = UserMessage | AssistantMessage (role "user" | "assistant"; assistant adds time.completed?, modelID, providerID, agent, tokens, finish?, error?).
+- Part union: TextPart, ReasoningPart, FilePart, ToolPart, StepStartPart, StepFinishPart, SnapshotPart, PatchPart, AgentPart, RetryPart, CompactionPart, SubtaskPart.
+
+## How it is generated
+
+`packages/sdk/js/script/build.ts` runs `bun dev generate > openapi.json` from the opencode repo, feeds it to `@hey-api/openapi-ts.createClient`, writes output to `packages/sdk/js/src/v2/gen`, patches an SSE generic, prettifies and typechecks. Regenerate with `./packages/sdk/js/script/build.ts`.
+
+---
+
+For version-stable QA, prefer the curl/CLI scripts in this skill; cross-check any SDK call against `GET /doc`.

package/.agents/skills/opencode-qa/references/server-api.md

@@ -0,0 +1,200 @@
+# opencode HTTP server API for QA (Case B)
+
+## Table of Contents
+
+- [Start a server](#start-a-server)
+- [Authentication](#authentication)
+- [Per-request workspace routing](#per-request-workspace-routing)
+- [Introspect the API](#introspect-the-api)
+- [Tested smoke calls](#tested-smoke-calls)
+- [Route catalog](#route-catalog)
+- [Triggering a prompt over HTTP](#triggering-a-prompt-over-http)
+
+## Start a server
+
+Run the server with a fixed port and host:
+
+```bash
+opencode serve --port 4096 --hostname 127.0.0.1
+```
+
+Output:
+
+```
+opencode server listening on http://127.0.0.1:4096
+```
+
+Port 0 means the server will pick 4096, then fall back to a free port if that one is taken.
+
+A bundled isolated smoke test is available at `scripts/server-smoke.sh`. It spawns an isolated server, checks `/global/health`, checks that `/doc` returns at least 100 paths, and confirms that no-auth requests get 401, then tears the server down.
+
+## Authentication
+
+Set the environment variable `OPENCODE_SERVER_PASSWORD` to require authentication. If it is unset, the server runs UNSECURED and prints a warning.
+
+The username defaults to `opencode`. Override it with `OPENCODE_SERVER_USERNAME`.
+
+Two ways to authenticate:
+
+1. HTTP Basic Auth: `-u opencode:$PASS`
+2. Query parameter: `?auth_token=<base64(user:pass)>`
+
+Unauthenticated requests to protected routes return HTTP 401. This was verified.
+
+## Per-request workspace routing
+
+Most instance routes need the target project directory. Pass it as either:
+
+- Query parameter: `?directory=$PWD`
+- Header: `x-opencode-directory: $PWD`
+
+Aliases also work: `x-opencode-workspace` header or `?workspace=` query parameter.
+
+The server resolves an instance per request, so a single `serve` process can handle many projects.
+
+## Introspect the API
+
+The `/doc` endpoint returns the full OpenAPI spec. To list all documented paths:
+
+```bash
+curl -s -u opencode:$PASS http://127.0.0.1:4096/doc | jq '.paths | keys'
+```
+
+On v1.15.13 this returned 113 paths. This is the source of truth for exact request and response schemas.
+
+## Tested smoke calls
+
+```bash
+curl -s -u opencode:$PASS http://127.0.0.1:4096/global/health | jq .
+# {"healthy":true,"version":"1.15.13"}
+
+curl -s -u opencode:$PASS http://127.0.0.1:4096/doc | jq '.paths|length'
+# 113
+
+curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4096/session?directory=$PWD
+# 401 (no credentials)
+
+curl -s -u opencode:$PASS "http://127.0.0.1:4096/session?directory=$PWD" | jq 'length'
+```
+
+## Route catalog
+
+This mirrors the structure returned by `/doc`. Each entry is grouped as `method path - purpose`.
+
+### Global
+
+- `GET /global/health` - health check
+- `GET /global/event` - server-wide SSE event stream
+- `GET /global/config` - read global configuration
+- `PATCH /global/config` - update global configuration
+- `POST /global/dispose` - dispose the server instance
+- `GET /doc` - OpenAPI specification
+
+### Session
+
+- `GET /session` - list sessions
+- `GET /session/status` - session status overview
+- `GET /session/:id` - get session by ID
+- `GET /session/:id/children` - list child sessions
+- `GET /session/:id/todo` - get session todo items
+- `GET /session/:id/diff` - get session diff
+- `GET /session/:id/message` - list session messages
+- `GET /session/:id/message/:messageID` - get a specific message
+- `POST /session` - create a new session
+- `DELETE /session/:id` - delete a session
+- `PATCH /session/:id` - update a session
+- `POST /session/:id/fork` - fork a session
+- `POST /session/:id/abort` - abort a session
+- `POST /session/:id/init` - initialize a session
+- `POST /session/:id/share` - share a session
+- `POST /session/:id/summarize` - summarize a session
+- `POST /session/:id/revert` - revert a session
+- `POST /session/:id/unrevert` - unrevert a session
+- `DELETE /session/:id/share` - unshare a session
+
+### Prompting
+
+- `POST /session/:id/message` - send a prompt; streams JSON
+- `POST /session/:id/prompt_async` - fire-and-forget prompt; returns 204
+- `POST /session/:id/command` - execute a command in a session
+- `POST /session/:id/shell` - run a shell command in a session
+
+### Files and find
+
+- `GET /find` - text search via ripgrep
+- `GET /find/file` - file search
+- `GET /find/symbol` - symbol search
+- `GET /file` - file metadata
+- `GET /file/content` - file contents
+- `GET /file/status` - file status
+
+### Instance and app
+
+- `GET /path` - path resolution
+- `GET /vcs` - version control info
+- `GET /vcs/status` - VCS status
+- `GET /vcs/diff` - VCS diff
+- `GET /command` - available commands
+- `GET /agent` - available agents
+- `GET /skill` - available skills
+- `GET /lsp` - LSP info
+- `GET /formatter` - formatter info
+
+### Permission and question
+
+- `GET /permission` - list pending permission requests
+- `POST /permission/:requestID/reply` - reply to a permission request
+- `GET /question` - list pending questions
+- `POST /question/:requestID/reply` - reply to a question
+- `POST /question/:requestID/reject` - reject a question
+
+### TUI control
+
+These endpoints drive a running TUI over HTTP.
+
+- `POST /tui/append-prompt` - append text to the TUI prompt
+- `POST /tui/submit-prompt` - submit the current TUI prompt
+- `POST /tui/execute-command` - execute a TUI command
+- `POST /tui/show-toast` - show a toast in the TUI
+- `GET /tui/control/next` - get the next TUI control event
+- `POST /tui/control/response` - respond to a TUI control event
+
+### PTY
+
+- `GET /pty` - list PTY sessions
+- `POST /pty` - create a PTY session
+- `GET /pty/:id` - get PTY session info
+- `DELETE /pty/:id` - delete a PTY session
+- `POST /pty/:id/connect-token` - generate a PTY connect token
+- `GET /pty/:id/connect` - WebSocket connection to the PTY
+
+### Event
+
+- `GET /event` - instance-level SSE event stream
+
+### V2 API
+
+- `GET /api/session` - list sessions (v2)
+- `POST /api/session/:id/prompt` - prompt a session (v2)
+- `POST /api/session/:id/compact` - compact a session (v2)
+- `POST /api/session/:id/wait` - wait for a session (v2)
+- `GET /api/session/:id/context` - get session context (v2)
+- `GET /api/session/:id/message` - get session messages (v2)
+- `GET /api/model` - list models (v2)
+- `GET /api/provider` - list providers (v2)
+
+## Triggering a prompt over HTTP (for hook and event QA)
+
+Use `prompt_async` so the event stream is not blocked.
+
+```bash
+curl -X POST -u opencode:$PASS -H 'Content-Type: application/json' \
+  -d '{"parts":[{"type":"text","text":"hello"}]}' \
+  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"
+```
+
+This returns HTTP 204. Watching events is covered in `references/events-hooks.md`.
+
+---
+
+Schemas are authoritative in `GET /doc`; for the event stream see `references/events-hooks.md`.

package/.agents/skills/opencode-qa/references/testing-harness.md

@@ -0,0 +1,218 @@
+# opencode Test Harness (how opencode QAs itself)
+
+This is reference material for writing and running tests against the opencode source. The skill's own QA scripts (CLI, curl, sqlite) do not require this, but it is the authoritative pattern when you need a unit or integration test.
+
+## Table of Contents
+
+1. [Runner and the root guard](#runner-and-the-root-guard)
+2. [Test bootstrap (in-memory, isolated)](#test-bootstrap-in-memory-isolated)
+3. [Effect-based harness (test/lib/effect.ts)](#effect-based-harness-testlibeffectts)
+4. [Instance and tmpdir fixtures (test/fixture/fixture.ts)](#instance-and-tmpdir-fixtures-testfixturefixturets)
+5. [CLI subprocess harness (test/lib/cli-process.ts)](#cli-subprocess-harness-testlibcli-processts)
+6. [Fake LLM server (test/lib/llm-server.ts)](#fake-llm-server-testlibllm-serverts)
+7. [Representative test shapes](#representative-test-shapes)
+8. [App e2e (Playwright)](#app-e2e-playwright)
+9. [Test style conventions](#test-style-conventions)
+
+## Runner and the root guard
+
+The runner is `bun test` (Bun built-in, not vitest or jest).
+
+Tests cannot run from the repo root. Two guards enforce this:
+
+- `bunfig.toml` at repo root sets `root = "./do-not-run-tests-from-root"`
+- Root `package.json` has `"test": "echo 'do not run tests from root' && exit 1"`
+
+Run from a package directory instead:
+
+```bash
+cd packages/opencode && bun test --timeout 30000
+```
+
+Run a single file:
+
+```bash
+bun test test/tool/read.test.ts
+```
+
+Filter by test name:
+
+```bash
+bun test --grep "truncates large file"
+```
+
+CI variant:
+
+```bash
+bun run test:ci
+```
+
+Turbo dependency: `opencode#test` depends on `^build`.
+
+## Test bootstrap (in-memory, isolated)
+
+The preload file is `packages/opencode/test/preload.ts`. It is wired via `packages/opencode/bunfig.toml`:
+
+```toml
+[test]
+preload = ["@opentui/solid/preload", "./test/preload.ts"]
+```
+
+What it does:
+
+- Sets `XDG_DATA_HOME`, `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, and `XDG_STATE_HOME` to temp directories
+- Sets `OPENCODE_TEST_HOME`
+- Sets `OPENCODE_DB=":memory:"` (SQLite in-memory)
+- Wipes all provider API keys from `process.env`
+- Sets `OPENCODE_EXPERIMENTAL_EVENT_SYSTEM=true`
+- Sets `OPENCODE_EXPERIMENTAL_WORKSPACES=true`
+- Initializes `Log.init({ print: false })`
+- Calls `initProjectors()`
+
+## Effect-based harness (test/lib/effect.ts)
+
+The `it` factory wraps `bun:test` with three variants:
+
+- `it.effect(name, body)` ... TestClock + TestConsole (isolated time)
+- `it.live(name, body)` ... real clock + TestConsole
+- `it.instance(name, body, opts)` ... real clock + scoped tmpdir + a real Instance context
+
+`testEffect(layer)` builds an `it` bound to an Effect layer:
+
+```typescript
+const it = testEffect(Layer.mergeAll(readLayer(), testInstanceStoreLayer))
+```
+
+## Instance and tmpdir fixtures (test/fixture/fixture.ts)
+
+- `tmpdirScoped(options?)` ... scoped temp directory. Optional `git: true`, optional `config` (writes `opencode.json`), optional `init`.
+- `provideInstance(directory)(effect)` ... runs an Effect inside a real instance for that directory.
+- `withTmpdirInstance({ git?, config?, init? })(effect)` ... one-liner: make tmpdir, optional git init + config, provide instance.
+- `testInstanceStoreLayer` ... instance store with a no-op bootstrap.
+
+## CLI subprocess harness (test/lib/cli-process.ts)
+
+`cliIt.live(name, body, timeoutMs?)` and `cliIt.concurrent(...)` spawn the real CLI (`bun run --conditions=browser src/index.ts`) in an isolated environment.
+
+Exposed helpers:
+
+- `opencode.run()`
+- `opencode.serve()`
+- `opencode.acp()`
+- `expectExit`
+- `parseJsonEvents`
+
+Isolation environment keys:
+
+- `OPENCODE_TEST_HOME`
+- `OPENCODE_CONFIG_CONTENT` (inline provider config)
+- `OPENCODE_DISABLE_PROJECT_CONFIG=1`
+- `OPENCODE_PURE=1`
+- `OPENCODE_DISABLE_AUTOUPDATE=1`
+- `OPENCODE_DISABLE_AUTOCOMPACT=1`
+- `OPENCODE_DISABLE_MODELS_FETCH=1`
+
+Real example from `packages/opencode/test/cli/serve/serve-process.test.ts`:
+
+```typescript
+cliIt.live("spawns serve and health responds", async ({ opencode, expectExit }) => {
+  const server = await opencode.serve()
+  expect(server.port).toBeGreaterThan(0)
+  const res = await fetch(`${server.url}/global/health`)
+  expect(res.status).toBe(200)
+})
+```
+
+## Fake LLM server (test/lib/llm-server.ts)
+
+`TestLLMServer` is an in-process OpenAI-compatible SSE server to mock model responses deterministically.
+
+Methods:
+
+- `llm.text("hello")`
+- `llm.tool("read", { filePath: "x" })`
+- `llm.pushMatch(matchFn, reply)`
+
+This is how tests avoid real provider calls.
+
+## Representative test shapes
+
+### 1. Tool test
+
+From `packages/opencode/test/tool/read.test.ts`:
+
+```typescript
+const it = testEffect(Layer.mergeAll(readLayer(), testInstanceStoreLayer))
+
+it.instance("truncates large file over maxReadFileSize", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    // ... exercise the read tool, assert truncation
+  })
+)
+```
+
+### 2. Session/event test
+
+From `packages/opencode/test/session/session.test.ts`:
+
+```typescript
+test("session.created fires after session.create", async () => {
+  const deferred = Deferred.unsafeMake<void>(FiberId.none)
+  // ... listen for session.created event
+  await session.create({})
+  // ... assert deferred resolves
+})
+```
+
+### 3. Plain unit test
+
+From `packages/opencode/test/cli/run/runtime.boot.test.ts`:
+
+```typescript
+import { describe, expect, mock, spyOn, test } from "bun:test"
+
+test("boots runtime without errors", () => {
+  // ... standard assertions, no Effect
+})
+```
+
+## App e2e (Playwright)
+
+The app lives in `packages/app` (SolidJS). Config is `packages/app/playwright.config.ts`. It starts the Vite dev server via `webServer`; the backend is expected at `localhost:4096`.
+
+Commands (run from `packages/app`):
+
+```bash
+bunx playwright install chromium
+bun run test:e2e:local
+```
+
+Filter with grep:
+
+```bash
+bun run test:e2e:local -- --grep "settings"
+```
+
+UI mode:
+
+```bash
+bun run test:e2e:ui
+```
+
+App unit tests:
+
+```bash
+bun run test:unit
+```
+
+This equals `bun test --preload ./happydom.ts ./src`.
+
+## Test style conventions
+
+Per opencode AGENTS.md:
+
+- Avoid mocks where possible. Test the real implementation. Do not duplicate logic into tests.
+- Run `bun typecheck` from the package directory (uses tsgo). Never run bare `tsc`.
+
+For runtime or scriptable QA without writing tests, use the opencode-qa scripts (Cases A-D in SKILL.md).

package/.agents/skills/opencode-qa/references/tui-tmux.md

@@ -0,0 +1,52 @@
+# QAing the opencode TUI under tmux (Case C)
+
+## Verdict first (be honest)
+
+- tmux CAN launch the opencode TUI and `capture-pane` reads the rendered frame; `send-keys` delivers keystrokes to the composer. This is proven and good for SMOKE checks: did it boot, does it render, does it accept input.
+- The TUI is a 60fps full-screen app (built on @opentui/solid) with a custom renderer, animations, and a worker thread. Asserting on conversation OUTPUT by scraping the frame is FRAGILE and not recommended.
+- For real behavior assertions prefer: `opencode run` (Case A, references/cli-commands.md), the server API + SSE (Case B, references/server-api.md + events-hooks.md), or the TUI control HTTP API (below). The TUI talks to the same server, so API-level QA is equivalent to driving the screen.
+
+## Safety: isolate so QA never pollutes the real DB
+
+Launching the real TUI would create sessions in the real ~/.local/share/opencode DB. Run it under an isolated XDG sandbox. The bundled `scripts/tui-smoke.sh` does exactly this and verifies the real session count is unchanged before/after.
+
+## Smoke test (bundled)
+
+- `scripts/tui-smoke.sh --self-test` launches the TUI under tmux in an isolated sandbox, polls capture-pane for a render marker (version string / "Ask anything" / footer), sends a sentinel keystroke, then kills the tmux session and confirms the real DB is untouched.
+
+## Manual tmux recipe (fenced) - for ad hoc smoke
+
+```
+SESS=oqa_tui_demo
+DIR=$(mktemp -d)
+tmux new-session -d -s "$SESS" -x 200 -y 50
+# isolate XDG so no real session is written
+tmux send-keys -t "$SESS" "XDG_DATA_HOME=$DIR/data XDG_CONFIG_HOME=$DIR/cfg XDG_STATE_HOME=$DIR/state XDG_CACHE_HOME=$DIR/cache OPENCODE_DISABLE_AUTOUPDATE=1 OPENCODE_DISABLE_MODELS_FETCH=1 opencode $DIR" Enter
+sleep 7
+tmux capture-pane -t "$SESS" -p | sed -n '1,30p'   # inspect the rendered frame
+tmux send-keys -t "$SESS" "hello"                    # type into the composer
+sleep 1
+tmux capture-pane -t "$SESS" -p | sed -n '1,30p'
+tmux kill-session -t "$SESS"                          # teardown (kills the TUI)
+rm -rf "$DIR"
+```
+
+Explain: capture-pane -p prints the visible frame; send-keys injects input; kill-session tears down the process tree. Always teardown and remove the temp dir.
+
+## The reliable alternative: TUI control HTTP API
+
+A running TUI is a client of the local server, so you can drive it over HTTP without scraping the screen:
+
+- POST /tui/append-prompt - append text to the composer
+- POST /tui/submit-prompt - submit the composer
+- POST /tui/execute-command - run a TUI command
+- POST /tui/show-toast - show a toast
+- GET /tui/control/next + POST /tui/control/response - the control channel
+
+Use these (with auth + ?directory=) to deterministically drive a TUI you launched, then assert via the event stream (references/events-hooks.md).
+
+## Headless component testing (for source-level TUI tests)
+
+opencode unit-tests TUI components headlessly with @opentui/core/testing `createTestRenderer` (see packages/opencode/test/cli/tui/, e.g. app-lifecycle.test.ts). This is the route for asserting TUI component behavior in the source repo; see references/testing-harness.md.
+
+Bottom line: tmux for smoke, server/SSE or /tui/* control for assertions, createTestRenderer for source unit tests.

package/.agents/skills/opencode-qa/scripts/db-session-by-id.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# db-session-by-id.sh - investigate an opencode session by its id (ses_...).
+# Read-only against the LIVE opencode DB via `opencode db ... --format json`.
+#
+# Usage:
+#   db-session-by-id.sh ses_3a4ee6335ffedFB8f76BPU1Eb3
+#   db-session-by-id.sh --self-test
+#
+# Output: a JSON array with one row (id, slug, title, directory, agent, model,
+# cost, token counts, human-readable created/updated times) or [] if not found.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+oqa_session_by_id() {
+  local id esc
+  id="$1"
+  esc="$(oqa_sql_escape "$id")"
+  oqa_db_query "SELECT
+      id, slug, title, directory, agent,
+      json_extract(model,'\$.modelID')   AS model,
+      json_extract(model,'\$.providerID') AS provider,
+      cost, tokens_input, tokens_output,
+      datetime(time_created/1000,'unixepoch') AS created,
+      datetime(time_updated/1000,'unixepoch') AS updated
+    FROM session WHERE id='$esc'"
+}
+
+oqa_self_test() {
+  oqa_require opencode jq || return 1
+  local id out got
+  id="$(oqa_db_query "SELECT id FROM session ORDER BY time_created DESC LIMIT 1" | jq -r '.[0].id // empty')"
+  if [ -z "$id" ]; then
+    oqa_log "FAIL: no sessions in DB to test against"; return 1
+  fi
+  out="$(oqa_session_by_id "$id")"
+  got="$(printf '%s' "$out" | jq -r '.[0].id // empty')"
+  if [ "$got" = "$id" ]; then
+    oqa_pass "db-session-by-id round-trips id ($id)"
+    return 0
+  fi
+  oqa_log "FAIL: expected id '$id', got '$got'"; return 1
+}
+
+case "${1:-}" in
+  --self-test) oqa_self_test; exit $? ;;
+  -h|--help|"")
+    sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    [ -z "${1:-}" ] && exit 2 || exit 0 ;;
+  *)
+    oqa_require opencode jq || exit 1
+    oqa_session_by_id "$1" ;;
+esac

package/.agents/skills/opencode-qa/scripts/db-session-by-name.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# db-session-by-name.sh - find opencode sessions whose TITLE matches a substring.
+# Read-only against the LIVE opencode DB. Title search is cheap (the session
+# table is small; ~21k rows scan in milliseconds), so no bounding is needed.
+#
+# Usage:
+#   db-session-by-name.sh "auth refactor"        # newest 20 matches
+#   db-session-by-name.sh "auth refactor" 50     # newest 50 matches
+#   db-session-by-name.sh --self-test
+#
+# Output: JSON array of {id, title, created, updated} ordered newest first.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/lib/common.sh"
+
+oqa_session_by_name() {
+  local needle limit esc
+  needle="$1"
+  limit="${2:-20}"
+  case "$limit" in (*[!0-9]*|"") limit=20 ;; esac
+  esc="$(oqa_sql_escape "$needle")"
+  oqa_db_query "SELECT
+      id, title,
+      datetime(time_created/1000,'unixepoch') AS created,
+      datetime(time_updated/1000,'unixepoch') AS updated
+    FROM session
+    WHERE title LIKE '%$esc%'
+    ORDER BY time_created DESC
+    LIMIT $limit"
+}
+
+oqa_self_test() {
+  oqa_require opencode jq || return 1
+  # Derive a guaranteed-present needle: the first 5 chars of a real title.
+  local needle out n
+  needle="$(oqa_db_query "SELECT substr(title,1,5) AS t FROM session WHERE length(title)>=5 ORDER BY time_created DESC LIMIT 1" | jq -r '.[0].t // empty')"
+  if [ -z "$needle" ]; then
+    oqa_log "FAIL: could not derive a title needle"; return 1
+  fi
+  out="$(oqa_session_by_name "$needle" 5)"
+  n="$(printf '%s' "$out" | jq 'length')"
+  if [ "${n:-0}" -ge 1 ]; then
+    oqa_pass "db-session-by-name found $n row(s) for needle '$needle'"
+    return 0
+  fi
+  oqa_log "FAIL: expected >=1 row for needle '$needle', got '$n'"; return 1
+}
+
+case "${1:-}" in
+  --self-test) oqa_self_test; exit $? ;;
+  -h|--help|"")
+    sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    [ -z "${1:-}" ] && exit 2 || exit 0 ;;
+  *)
+    oqa_require opencode jq || exit 1
+    oqa_session_by_name "$1" "${2:-20}" ;;
+esac