triss-coworker 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.30.0] — 2026-08-06
+
+### Added
+
+- **OpenCode coder runs can switch provider and the complete main/small pair
+  for one invocation.** `triss coder run --provider <name> --model <p/m>
+  [--small-model <p/m>]` uses an in-memory OpenCode overlay and never rewrites
+  `.env` or `opencode.json`; omitted `--small-model` defaults to the one-shot
+  main. CLI help, MCP (`provider` / `model` / `small_model`), README, config
+  reference, and generated agent instructions document the same contract.
+- Added docs-first implementation and process-lifecycle contracts with focused
+  RED/GREEN coverage for GLM ↔ Triss worker switching.
+
+### Changed
+
+- The MCP server now advertises the package version instead of a stale
+  hard-coded protocol version.
+- `--model` without `--provider` retains its existing main-only semantics.
+  An explicit provider requires a fully qualified model, both transient roles
+  must share its exact prefix, and Crush remains Z.AI-only. Worker credentials
+  and the managed provider can coexist with GLM while either pair is selected
+  per run.
+
+### Fixed
+
+- `coder run` no longer resolves when the immediate OpenCode CLI exits but a
+  same-process-group tool descendant remains alive. Triss now terminates and
+  waits for residual processes before computing the final envelope, preventing
+  late edits and lingering database/WAL contention.
+- MCP request cancellation/timeout signals now reach `runCoderRun()` and the
+  selected engine's detached process group instead of leaving OpenCode or
+  Crush running after the client regains control. Timeout, host SIGINT/SIGTERM,
+  caller cancellation, and normal-close cleanup preserve SIGKILL escalation
+  for descendants that survive SIGTERM.
+- A successful child exit now immediately disarms its execution timeout and
+  host/AbortSignal listeners while bounded residual cleanup and stdio close
+  continue. A delayed `close` can no longer relabel a completed OpenCode or
+  Crush run as `timeout` or signal a recycled numeric process group.
+
+### Security
+
+- Detached OpenCode and Crush group signalling now rejects missing,
+  non-integer, zero, and `1` child PIDs before negation. This prevents a failed
+  or test-double spawn from issuing POSIX `kill(-1, SIGTERM)` to every process
+  the current user can signal, or `kill(0, SIGTERM)` to Triss's own group.
+  Custom spawn seams also receive no real group-signalling authority unless
+  they explicitly inject the matching process-group owner.
+- One-shot runs overlay only model fields and never assume that overlay has
+  final precedence. Before any real selected credential reaches OpenCode,
+  Triss audits every file-backed source loaded by pinned OpenCode 1.18.7:
+  global `config.json`/`opencode.json(c)`, `~/.opencode/opencode.json(c)`, and
+  runtime-directory ancestors through the Git root or `/` outside Git. It then
+  resolves the final merged config with `debug config --pure` under the exact
+  sanitized child environment and a random canary instead of the real key.
+  Final main/small models and the selected provider must match, catching later
+  account/org, managed-directory, and macOS MDM overrides. The actual run also
+  uses `--pure`; unreadable, JSONC, unknown, or unverified config fails closed.
+  Concurrent same-user mutation between preflight and spawn remains outside
+  the guard's threat model.
+
+## [0.29.0] — 2026-08-06
+
+### Added
+
+- **Existing OpenAI-compatible worker profiles are now available in coder
+  mode.** `triss coder init --provider worker` registers an env-backed
+  `triss-worker` provider through `@ai-sdk/openai-compatible`, reusing
+  `TRISS_WORKER_API_KEY`, `TRISS_WORKER_BASE_URL`, and the configured
+  flash/pro model ids instead of introducing another credential. Init, run,
+  model inspection/switching, status, MCP, wizard/help output, and generated
+  agent instructions all understand `triss-worker/<model-id>`. V1 supports one
+  custom profile and the Chat Completions protocol; Crush remains Z.AI-only.
+
+### Changed
+
+- Worker setup resolves credentials, endpoint, and model ids from the selected
+  local/global scope while preserving genuine parent-shell overrides. Worker
+  readiness now has one shared definition across `triss status` and MCP, and
+  the MCP coder-status description names `TRISS_WORKER_API_KEY` explicitly.
+- OpenCode init, persistent model changes, and rollback now coordinate through
+  the same PID/token `(engine, scope)` filesystem lock with dead-PID recovery.
+
+### Security
+
+- Worker init and run fail closed before forwarding credentials when the
+  effective project/global `provider["triss-worker"]`, endpoint, env-backed key
+  binding, package, or complete flash/pro model allowlist is missing, stale, or
+  conflicting. A global init cannot persist project-local endpoint settings or
+  report success over a higher-precedence unsafe project provider.
+- Jira issue output and its model-summarization corpus no longer include the
+  presence or absence of the worker credential.
+
 ## [0.28.0] — 2026-08-06
 
 ### Added
@@ -841,7 +933,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of `triss-coworker`.
 
-[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.27.0...HEAD
+[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/ayleen/triss-coworker/compare/v0.29.0...v0.30.0
+[0.29.0]: https://github.com/ayleen/triss-coworker/compare/v0.28.0...v0.29.0
+[0.28.0]: https://github.com/ayleen/triss-coworker/compare/v0.27.1...v0.28.0
+[0.27.1]: https://github.com/ayleen/triss-coworker/compare/v0.27.0...v0.27.1
 [0.27.0]: https://github.com/ayleen/triss-coworker/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/ayleen/triss-coworker/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/ayleen/triss-coworker/compare/v0.24.2...v0.25.0

package/README.md

@@ -237,7 +237,8 @@ The exposed tool set is **filtered by configured credentials**:
 - **`triss_github_*`** when `GITHUB_TOKEN` is set (or `gh` CLI logged in).
 - **`triss_gitlab_*`** when `GITLAB_TOKEN` is set.
 - **`triss_coder_run` + `triss_coder_status`** when any coder provider key is
-  set — `ZHIPU_API_KEY` (Z.AI GLM), `OPENCODE_API_KEY` (OpenCode Zen or Go),
+  set — `TRISS_WORKER_API_KEY` (the existing OpenAI-compatible worker),
+  `ZHIPU_API_KEY` (Z.AI GLM), `OPENCODE_API_KEY` (OpenCode Zen or Go),
   `MOONSHOT_API_KEY` (Moonshot Kimi), or `KIMI_API_KEY` (Kimi for Coding)
   (setup: `triss coder init`). `triss_coder_run` takes an optional `engine`
   (`opencode` default, or `crush`); its timeout defaults to
@@ -271,8 +272,8 @@ and writing**.
 | `triss review`     | Code review on current branch or a PR (diff + linked ticket) | The agent reading the whole diff |
 | `triss commit-msg` | Generates a commit message from staged diff           | Hand-writing or copy-pasting from web LLMs |
 | `triss usage`      | Cumulative cost / token usage with per-project breakdown | Squinting at stderr after each call |
-| `triss coder init` | Sets up a coding agent (default `opencode` engine; `--engine crush` for crush): provider key (Z.AI GLM default; `--provider opencode-zen` for free rotating Zen models; `--provider opencode-go` for the paid OpenCode Go subscription; `--provider moonshot` / `kimi-for-coding` for Kimi), config, permission policy, and agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model`. | Manually installing/configuring opencode |
-| `triss coder run` | Spawns the coding agent (GLM, Kimi, OpenCode Zen, or OpenCode Go) and prints one JSON envelope (`--engine opencode\|crush`; `--isolate` for a disposable worktree — opencode defaults to isolate-OFF, crush defaults to isolate-ON; crush adds opt-in `--restrict`/`--no-restrict` for its CLI allowlist). **POSIX only** (macOS/Linux) — refuses to run on Windows. | Manually driving `opencode run` and parsing its ndjson stream |
+| `triss coder init` | Sets up a coding agent (default `opencode` engine; `--engine crush` for crush): provider key/profile (`--provider worker` reuses `TRISS_WORKER_*`; Z.AI GLM default; Zen, Go, and Kimi are also supported), config, permission policy, and agent templates. Blocks (non-zero) on an unsafe existing `opencode.json` — missing deny-first bash policy (override with `--allow-unsafe-bash`) or a stale/cross-provider `small_model`. | Manually installing/configuring opencode |
+| `triss coder run` | Spawns the coding agent (the OpenAI-compatible Triss worker, GLM, Kimi, OpenCode Zen, or OpenCode Go) and prints one JSON envelope (`--engine opencode\|crush`; `--isolate` for a disposable worktree — opencode defaults to isolate-OFF, crush defaults to isolate-ON; crush adds opt-in `--restrict`/`--no-restrict` for its CLI allowlist). **POSIX only** (macOS/Linux) — refuses to run on Windows. | Manually driving `opencode run` and parsing its ndjson stream |
 | `triss coder clean` | Removes finished `.triss/wt` isolation worktrees (`--all` forces all) | Manually finding and deleting stale git worktrees |
 | `triss init`       | Drops a tiny (~15 line) delegation block into `CLAUDE.md` / `AGENTS.md` | Hand-writing routing rules         |
 | `triss agent-help` | Prints the full delegation cookbook on demand (the nano block points here) | A 200-line CLAUDE.md that always loads |
@@ -453,7 +454,8 @@ default timeout, configurable via `--timeout <ms>`.
 
 ### `triss coder`
 
-Delegates an implementation task to a cheap coding agent — GLM, Kimi,
+Delegates an implementation task to a cheap coding agent — the existing
+OpenAI-compatible Triss worker, GLM, Kimi,
 OpenCode Zen, or OpenCode Go models (the `opencode` engine by default; `crush` is an
 alternative — see **Engines** below) instead of the primary model writing
 the code itself.
@@ -467,7 +469,8 @@ triss coder clean                                 # remove finished isolation wo
 ```
 
 `triss coder init` first asks which provider to configure — **Z.AI GLM**
-(default), **OpenCode Zen** (`--provider opencode-zen`, free rotating
+(default), the existing **Triss worker** (`--provider worker`, aliases
+`openai` / `openai-compatible`), **OpenCode Zen** (`--provider opencode-zen`, free rotating
 models), **OpenCode Go** (`--provider opencode-go`, paid subscription),
 **Moonshot Kimi** (`--provider moonshot`, pay-as-you-go
 `moonshotai/*` models like `kimi-k2.7-code`), or **Kimi for Coding**
@@ -486,7 +489,10 @@ endpoint. Either way it lets you pick the model interactively. See the
 Prints one JSON envelope to stdout — `files_changed`, `diff_stat`, and
 `worktree` tell you what to review; `--isolate` runs the agent in a
 disposable `.triss/wt/<slug>` git worktree so it never touches your
-working tree directly. `--session <slug>` continues the same opencode
+working tree directly. Before returning the envelope, Triss terminates and
+waits for any residual process in the selected engine's process group, so tests or DB
+clients cannot keep locks or write files after completion. MCP cancellation is
+forwarded to the same cleanup path. `--session <slug>` continues the same opencode
 conversation across calls. **POSIX only** (macOS/Linux) for now. See
 `docs/glm-clients.md` for the full picture of how Triss talks to GLM
 (both engines, key/endpoint routing, models, and every usage mode),
@@ -513,7 +519,9 @@ natively; triss also forwards it as `ZAI_API_KEY` for older binaries; see
 `docs/crush-restrict-issues.md` for the live-verified bug facts.
 
 **Providers** — the `opencode` engine isn't limited to Z.AI. The required
-API key follows the model's `<provider>/` prefix: `zai-coding-plan/*` and
+API key follows the model's `<provider>/` prefix: `triss-worker/*` reuses
+the existing `TRISS_WORKER_API_KEY` + `TRISS_WORKER_BASE_URL` profile;
+`zai-coding-plan/*` and
 `zai/*` (GLM) use `ZHIPU_API_KEY`; `opencode/*` models — served free by
 [OpenCode Zen](https://opencode.ai/docs/zen/) — and paid `opencode-go/*`
 models use the shared `OPENCODE_API_KEY`;
@@ -523,6 +531,55 @@ models use the shared `OPENCODE_API_KEY`;
 **`kimi-for-coding/k3`** (Kimi K3) — use `KIMI_API_KEY`. Zen ids rotate
 freely, so discover the current id and pass it rather than hard-coding one:
 
+```bash
+triss coder init --provider worker
+triss coder run "mechanical task" \
+  --provider worker --model triss-worker/deepseek-v4-flash
+```
+
+The worker route uses Chat Completions through `@ai-sdk/openai-compatible`.
+It creates no second API key and is supported by the OpenCode engine only.
+After changing the worker base URL or flash/pro model ids, rerun
+`triss coder init --provider worker`; `coder model set --provider worker`
+fails closed until the matching env-backed provider block is present. Global
+init reads only global worker settings (except genuine shell exports) and
+rejects a conflicting higher-precedence project provider. Every worker run
+revalidates the registered global/project endpoint and model allowlist before
+forwarding the key, and prints an exact scope-specific init command when the
+saved provider is missing or stale. The broader runtime-tree snapshot described
+below applies to explicit one-shot `--provider worker` runs.
+
+Worker init is a one-time provider registration, not an exclusive provider
+choice: GLM and worker credentials/configuration can coexist. After the worker
+provider has been registered, switch the complete main/small pair for one task
+without changing the persistent default:
+
+```bash
+# Worker for this task; small defaults to the same model.
+triss coder run "mechanical task" \
+  --provider worker --model triss-worker/deepseek-v4-flash
+
+# GLM for this task, with an explicit fast model.
+triss coder run "hard task" \
+  --provider zai --model zai-coding-plan/glm-5.2 \
+  --small-model zai-coding-plan/glm-5-turbo
+```
+
+`--provider` is OpenCode-only, requires a provider-qualified `--model`, and
+never rewrites `.env` or `opencode.json`. `--small-model` is available only
+with `--provider`; when omitted it equals the one-shot main model. The worker
+run still validates the previously registered env-backed provider before the
+key is forwarded. During a one-shot provider run, Triss first audits every
+file-backed source loaded by the pinned OpenCode version: global `config.json`
+and `opencode.json(c)`, `~/.opencode/opencode.json(c)`, and runtime-directory
+ancestors up to the Git root (or `/` outside Git). It then asks OpenCode for the
+final merged config under the exact sanitized child environment, with a random
+canary instead of the real credential, and verifies the final main/small models
+and selected provider. Both the preflight and actual run use `--pure` to disable
+external plugins. Unreadable/JSONC/unknown layers fail closed. Concurrent
+same-user config mutation between preflight and spawn remains outside this
+guard's threat model.
+
 ```bash
 triss coder init --provider opencode-zen              # guided: key + opencode.json
 triss coder models --provider opencode-zen            # see live Zen ids
@@ -563,8 +620,10 @@ MAIN model only (it sits in the OpenCode-main precedence chain: one-run `--model
 default), so it changes the main model for every run until unset.
 `TRISS_CODER_SMALL_MODEL` is setup intent consumed by `triss coder init` /
 `triss coder model` — it does not swap the small model mid-run (opencode reads
-`small_model` from `opencode.json`); use `--model` for a one-run main-model
-override. The deny-first `opencode.json` bash policy applies to every provider.
+`small_model` from `opencode.json`). Use `--model` alone for a one-run main-only
+override within the current provider; use `--provider` + `--model` and optional
+`--small-model` to switch the complete pair for one run. The deny-first
+`opencode.json` bash policy applies to every provider.
 Full details, the model catalogue, and every configuration path are in
 [docs/opencode-zen.md](docs/opencode-zen.md) and [docs/opencode-go.md](docs/opencode-go.md).
 
@@ -581,26 +640,29 @@ confusion is conflating them:
 - **Engine** = *how* the agent is launched: `opencode` (default) or
   `crush`. Set at `triss coder init --engine …` or per run with
   `triss coder run --engine …`.
-- **Provider** = *which* API serves the model: Z.AI GLM, OpenCode Zen, OpenCode Go,
-  Moonshot Kimi, Kimi for Coding. Set at `triss coder init --provider …`.
+- **Provider** = *which* API serves the model: Triss worker, Z.AI GLM, OpenCode Zen, OpenCode Go,
+  Moonshot Kimi, Kimi for Coding. Register/set the persistent default with
+  `triss coder init --provider …`, or select a complete one-shot pair with
+  `triss coder run --provider … --model … [--small-model …]`.
 
 Not every engine speaks every provider:
 
 | Engine     | Providers served                                  |
 | ---------- | ------------------------------------------------- |
-| `opencode` | Z.AI GLM, OpenCode Zen, OpenCode Go, Moonshot, Kimi for Coding |
+| `opencode` | Triss worker, Z.AI GLM, OpenCode Zen, OpenCode Go, Moonshot, Kimi for Coding |
 | `crush`    | Z.AI GLM (coding-plan only)                       |
 
 `triss coder init` drives setup in that order — **engine, then provider,
 then it asks for only that provider's credential** and writes the matching
-model prefix (`opencode/<id>`, `opencode-go/<id>`, `zai-coding-plan/*`, `moonshotai/*`, or
+model prefix (`triss-worker/<id>`, `opencode/<id>`, `opencode-go/<id>`, `zai-coding-plan/*`, `moonshotai/*`, or
 `kimi-for-coding/*`).
 
-**Choosing a model.** `--model` on `triss coder run` is a
-**single-run override of the main model only** — it does not persist
-and does not change the small/summarization model. To persist a
-choice, use `triss coder model set` — positional main plus `--small` —
-which requires you to name the engine and the scope explicitly:
+**Choosing a model.** `--model` by itself on `triss coder run` remains a
+**single-run override of the main model only**. For a non-persistent provider
+switch, pass `--provider` with a provider-qualified `--model`; add
+`--small-model` when the small role should differ, otherwise it defaults to the
+one-shot main. To persist a choice, use `triss coder model set` — positional
+main plus `--small` — which requires the engine and scope explicitly:
 
 ```bash
 # global, opencode engine: positional main + --small; --yes for noninteractive use

package/bin/triss.js

@@ -183,7 +183,7 @@ config
   .option('--standard', 'API key + one model only — skip the standard/advanced prompt')
   .option('--advanced', 'full wizard with presets, base URL, integrations — skip the prompt')
   .option('--coder-engine <name>', 'coder target only: coding engine to configure (opencode default, or crush). `coder init` uses --engine')
-  .option('--coder-provider <name>', 'coder target only: opencode engine provider (zai, opencode-zen, opencode-go, moonshot, kimi-for-coding). `coder init` uses --provider')
+  .option('--coder-provider <name>', 'coder target only: opencode engine provider (zai, worker, opencode-zen, opencode-go, moonshot, kimi-for-coding). `coder init` uses --provider')
   .action(wrap(runWizard));
 
 config
@@ -238,19 +238,21 @@ coder
   .option('-g, --global', 'save to the global scope (~/.config/triss/.env, ~/.config/opencode/)')
   .option('-l, --local', 'save to the project scope (./.triss.env, ./opencode.json)')
   .option('--engine <name>', 'coding engine to configure: opencode (default) or crush')
-  .option('--provider <name>', 'opencode engine model provider: zai (Z.AI GLM, default), opencode-zen (free rotating models), opencode-go (paid Go subscription), moonshot (Kimi pay-as-you-go), or kimi-for-coding (subscription)')
+  .option('--provider <name>', 'opencode engine model provider: zai, worker (existing OpenAI-compatible TRISS_WORKER_* profile), opencode-zen, opencode-go, moonshot, or kimi-for-coding')
   .option('--allow-unverified', 'requires explicit --provider opencode-go (alias: go): allow the built-in fallback only after a temporary network or HTTP 408/429/500/502/503/504 catalogue failure (never bypasses 401/403, empty, or invalid responses)')
   .option('--allow-unsafe-bash', 'proceed even if an existing opencode.json has no deny-first bash policy (the agent runs with --auto)')
   .action(wrap(runCoderInit));
 
 coder
   .command('run [prompt]')
-  .description('Spawn a coding agent — GLM, Kimi, OpenCode Zen, or OpenCode Go models (opencode default, or --engine crush) — and print a JSON envelope to stdout')
+  .description('Spawn a coding agent — GLM, the OpenAI-compatible Triss worker, Kimi, OpenCode Zen, or OpenCode Go (opencode default, or --engine crush) — and print a JSON envelope to stdout')
   .option('--engine <name>', 'coding engine: opencode (default) or crush')
   .option('--session <id>', 'triss-side session slug, mapped to a real opencode session id in .triss/sessions.json')
   .option('--continue', 'continue the most recent opencode session (maps to opencode --continue)')
   .option('--agent <name>', 'opencode agent template to use', 'coder')
+  .option('--provider <name>', 'OpenCode only: select a provider for one run; requires --model and does not modify .env or opencode.json')
   .option('--model <p/m>', 'override the MAIN model for this one run only (does not change small_model or repair persistent config; use `triss coder model set` for that)')
+  .option('--small-model <p/m>', 'with --provider, override small_model for one run (defaults to the one-shot main model)')
   .option('--isolate', 'run in a disposable git worktree under .triss/wt/<slug>')
   .option('--no-isolate', 'disable worktree isolation (opencode defaults to OFF; crush defaults to ON)')
   .option('--restrict', 'crush only: enforce the allowlist via CLI --allow-bash/--allow-tool flags (--restrict-run). Opt-in (default OFF)')
@@ -274,7 +276,7 @@ coder
     '  • opencode: project opencode.json (local) or ~/.config/opencode/opencode.json (global)\n' +
     '  • crush: ./.crush/crush.json (local) or ~/.local/share/crush/crush.json (global)')
   .option('--engine <name>', 'coding engine: opencode (default) or crush')
-  .option('--provider <name>', 'provider kind: zai, opencode-zen, opencode-go, moonshot, or kimi-for-coding')
+  .option('--provider <name>', 'provider kind: zai, worker, opencode-zen, opencode-go, moonshot, or kimi-for-coding')
   .option('--json', 'print the stable machine-readable state object (no secrets)')
   .action(wrap(runCoderModels));
 
@@ -296,7 +298,7 @@ coderModel
   )
   .option('--small <model>', 'small/fast model id (omit to keep the current compatible value)')
   .option('--engine <name>', 'coding engine: opencode (default) or crush')
-  .option('--provider <name>', 'provider kind: zai, opencode-zen, opencode-go, moonshot, or kimi-for-coding')
+  .option('--provider <name>', 'provider kind: zai, worker, opencode-zen, opencode-go, moonshot, or kimi-for-coding')
   .option('-g, --global', 'write to the global scope (OpenCode: ~/.config/opencode/opencode.json + global .env; Crush: ~/.local/share/crush/crush.json)')
   .option('-l, --local', 'write to the project scope (OpenCode: ./opencode.json + ./.triss.env; Crush: ./.crush/crush.json)')
   .option('--allow-unverified', 'with explicit main + --small, bypass only a provider-defined transient catalogue failure (Go: transport or HTTP 408/429/500/502/503/504; Zen: timeout/http-error/parse-error; never auth or authoritative failure)')

package/docs/coder-model-management-plan.md

@@ -30,7 +30,7 @@ management and recovery workflow.
 
 | Engine | Supported providers | Persistent model store |
 | --- | --- | --- |
-| `opencode` | Z.AI GLM, OpenCode Zen, Moonshot Kimi, Kimi for Coding | `opencode.json` plus `TRISS_CODER_MODEL` / `TRISS_CODER_SMALL_MODEL` |
+| `opencode` | Triss worker (OpenAI-compatible), Z.AI GLM, OpenCode Zen, OpenCode Go, Moonshot Kimi, Kimi for Coding | `opencode.json` plus `TRISS_CODER_MODEL` / `TRISS_CODER_SMALL_MODEL` |
 | `crush` | Z.AI GLM only | crush large/fast model roles in `crush.json` |
 
 OpenCode Zen is not an engine and `hy3-free` was not a GLM model. It was one
@@ -648,7 +648,7 @@ verification contract as OpenCode applies (Corrective Blocker A):
   released on every exit (success, failure, rollback-failed).
 - `deps.lock` is an OVERRIDE seam for deterministic unit tests ONLY. Absence of
   `deps.lock` MUST NEVER mean unlocked: when `deps.lock` is not supplied the
-  operation MUST use the built-in filesystem lock via `acquireDefaultLock`.
+  operation MUST use the shared filesystem lock via `acquireCoderMutationLock`.
 - The lock seam is `deps.lock(engine, scope)` returning `{ release() }`. When
   `deps.lock` is injected, the apply MUST call it; tests assert acquire happens
   before the config read and release happens after verification completes.

package/docs/coder-one-shot-provider-plan.md

@@ -0,0 +1,126 @@
+# One-shot coder provider selection
+
+Status: implementation contract for v0.30.0.
+
+## Problem
+
+`triss coder run --model` currently overrides only OpenCode's main model. The
+persisted `small_model` remains active, so changing from GLM to the Triss worker
+(or back) for one run can create a cross-provider pair and is rejected. Users
+must persistently switch both roles even when they only want another provider
+for one task.
+
+## User contract
+
+The OpenCode engine accepts an explicit one-shot provider pair:
+
+```bash
+triss coder run "mechanical task" \
+  --provider worker \
+  --model triss-worker/deepseek-v4-flash
+
+triss coder run "hard task" \
+  --provider zai \
+  --model zai-coding-plan/glm-5.2 \
+  --small-model zai-coding-plan/glm-5-turbo
+```
+
+- `--provider` is one-run only and never rewrites the project `.triss.env`,
+  the global Triss `.env`, or any `opencode.json`.
+- `--provider` requires a provider-qualified `--model`. This keeps Z.AI
+  coding-plan versus pay-as-you-go selection explicit and avoids guessing a
+  model from whichever credentials happen to be present.
+- `--small-model` is valid only with `--provider`. When omitted, the one-shot
+  small model equals the explicit main model.
+- Main and small must resolve to the selected provider and must use the same
+  raw provider prefix. A regional/plan mix is rejected before credentials are
+  forwarded.
+- The feature is OpenCode-only. Crush remains Z.AI-only and rejects
+  `--provider`/`--small-model` before spawning.
+- Existing `--model` without `--provider` keeps its v0.29 main-only semantics.
+
+The MCP `triss_coder_run` tool exposes the same operation through `provider`,
+`model`, and `small_model` fields.
+
+## Runtime design and security invariants
+
+For an explicit provider run, Triss supplies an in-memory
+`OPENCODE_CONFIG_CONTENT` overlay containing only the selected `model` and
+`small_model`. No temporary or persistent config file is published. The
+overlay is not assumed to have final precedence: OpenCode 1.18.7 can merge
+account/organization, managed-directory, and macOS MDM configuration after it.
+
+The overlay must not define or replace providers. OpenCode deep-merges provider
+objects, which could retain untrusted lower-precedence options such as custom
+headers. Before forwarding any selected credential, Triss audits the pinned
+OpenCode version's global `config.json` and `opencode.json(c)`, the legacy
+`~/.opencode/opencode.json(c)` source, and direct config ancestors from the
+actual runtime directory to its Git root (or filesystem root outside Git).
+Built-in providers reject any persistent block for the selected provider id;
+managed worker blocks must match the complete expected definition in every
+layer. JSONC is rejected because Triss cannot prove that commented config
+contains no hidden endpoint/header override.
+
+After this file audit, Triss runs `opencode debug config --pure` under the exact
+sanitized child environment. The real selected credential is absent; a random
+canary is supplied instead so the managed worker's env binding can still be
+verified. The final merged main model, small model, and selected-provider block
+must match. The actual one-shot `opencode run` also receives `--pure`, disabling
+external plugins in both phases. Any probe failure or unknown final shape is
+fail-closed. This remains a pre-spawn check; concurrent same-user mutation
+between preflight and spawn is outside the guard's threat model. Unverified
+OpenCode versions fail closed so changed discovery rules cannot silently bypass
+the audit. The runtime directory is explicit `--cwd`, inherited `process.cwd()`,
+or the created/reused isolation worktree. The Triss worker
+therefore retains its existing setup prerequisite:
+`triss coder init --engine opencode --provider worker --global|--local`
+registers the env-backed provider once. Every worker run then verifies the
+effective provider package, endpoint, credential binding, and complete model
+allowlist before forwarding `TRISS_WORKER_API_KEY`. In one-shot mode the audit
+checks the selected transient pair rather than requiring the persisted
+main/small pair to be worker models.
+
+Only the credential required by the explicit main model is forwarded. The
+selected provider must equal the provider implied by both model prefixes, so a
+flag cannot relabel a model to obtain a different credential.
+
+## Failure contract
+
+All usage failures happen before isolation. Provider-config auditing happens
+after an isolation worktree is resolved but before engine spawn or credential
+forwarding; a newly created clean worktree is removed if that audit fails, while
+a reused worktree is preserved for inspection. Failure cases are:
+
+- missing `--model` with `--provider`;
+- `--small-model` without `--provider`;
+- unknown provider or model/provider mismatch;
+- empty or whitespace-containing provider/model id;
+- different main/small raw prefixes;
+- non-Z.AI provider flags on Crush;
+- missing selected-provider credential;
+- missing, stale, or conflicting managed worker provider;
+- selected-provider overrides or unauditable JSONC in effective config layers;
+- an installed OpenCode version other than the audited pin.
+
+Errors name the invalid flags and include the exact worker init recovery
+command when applicable. No failure writes model pins or OpenCode config.
+
+## TDD and acceptance
+
+RED tests must establish:
+
+1. Commander help exposes `--provider` and `--small-model` with one-shot and
+   non-persistent wording.
+2. GLM-persisted config can run a worker one-shot pair, and worker-persisted
+   config can run a GLM one-shot pair.
+3. Spawn receives a matching in-memory main/small overlay and only the selected
+   provider credential.
+4. The persistent env/config bytes are unchanged after success and failure.
+5. Every failure case above occurs before spawn.
+6. Legacy main-only `--model` behavior remains unchanged.
+7. MCP forwards `provider` and `small_model` without changing isolation
+   defaults.
+
+Acceptance requires focused tests, the full Node test/lint suite, package
+smoke, a live synthetic worker run from a GLM-persisted temporary project, and
+sequential GLM 5.2 plus independent agent reviews.

package/docs/coder-process-lifecycle-plan.md

@@ -0,0 +1,62 @@
+# Coder process-group lifecycle
+
+Status: remediation contract for v0.30.0.
+
+## User report
+
+An OpenCode Go user observed that Triss returned control while several
+OpenCode-related processes remained alive. Repository edits sometimes appeared
+after the JSON completion envelope, and lingering database users caused WAL
+contention.
+
+## Reproduction and root cause
+
+A minimal live `opencode-go/deepseek-v4-flash` completion on OpenCode 1.18.7
+left no process behind. A live synthetic `npm test` child was also cleaned up
+by OpenCode itself. The report is nevertheless valid at Triss's boundary:
+
+1. A deterministic process-group test demonstrated that the immediate
+   OpenCode CLI can close its stdio and exit while a same-group tool descendant
+   remains alive. `spawnEngine()` resolved on the immediate child's `close`
+   event and never checked the rest of the detached process group.
+2. The MCP SDK supplies an `AbortSignal` when the client cancels or times out a
+   tool request. The Triss MCP server discarded that signal, so a client could
+   return control while `runCoderRun()` and OpenCode continued in the server.
+3. On timeout, `close` cleared the pending SIGKILL escalation, which could also
+   leave a descendant that survived SIGTERM.
+
+## Contract
+
+- The coder completion envelope is emitted only after the selected engine's
+  detached process group can no longer execute or write files.
+- On immediate-child close, Triss probes the group, sends SIGTERM to residual
+  members, waits a short grace period, escalates to SIGKILL, and waits for group
+  disappearance before resolving.
+- Signal permission failures and a group that remains observable after SIGKILL
+  fail the coder run closed; Triss must not emit a successful completion
+  envelope for either condition.
+- MCP request cancellation is forwarded server → tool handler →
+  `runCoderRun()` → `spawnEngine()` / `spawnCrush()`, which terminates the same
+  process group.
+- Timeout, rate-limit, host-signal, normal completion, spawn error, and MCP
+  cancellation use the same cleanup boundary.
+- Triss never kills processes outside the detached group it created for the
+  current engine call.
+- A missing, non-integer, zero, or `1` child pid is never negated or passed to
+  `process.kill`; in particular, Triss can never issue POSIX `kill(-1, ...)`
+  against every signalable process in the user's login session.
+- A custom/injected spawn function cannot signal an arbitrary real process
+  group unless its caller also injects the matching group-signalling owner.
+
+## Verification
+
+- A real-process regression spawns a fake OpenCode group leader that emits a
+  valid fixture, leaves a 30-second same-group descendant, and exits. The test
+  proves the descendant is gone before `runCoderRun()` returns.
+- An abort regression proves cancellation sends SIGTERM to the negative process
+  group and produces a killed envelope when partial events exist.
+- MCP unit tests prove the SDK signal reaches the coder lifecycle.
+- Crush regressions prove cancellation, residual-child cleanup, and the
+  degenerate-pid guard use the same lifecycle boundary.
+- Live OpenCode Go smoke is repeated after the fix, followed by a process-list
+  and delayed-file check.