triss-coworker 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -7,10 +7,213 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] — 2026-08-18
+
+### Added
+
+- **Reliable delegation (Release C)** — sequential sharding per
+  `docs/reliable-delegation-contract-plan.md`:
+  - `--payload-mode shard` CLI + MCP shard parity: source-ordered
+    whole-file shards (a file is never split across shards);
+  - sequential executor with first-failure stop, cancellation
+    between/in-flight shards, fresh limit re-checks, and per-shard
+    attempt/usage facts;
+  - **no global verdict**: completed sharded execution prints
+    `global verdict: unavailable_for_sharded`; no aggregation call, no
+    cross-shard analysis, no global approval;
+  - structured partial errors carry completed shard verdicts only —
+    never completed prose or raw diff content;
+  - `evidence + shard` and `shard + --stream` rejected before any model
+    call;
+  - Release C synthetic acceptance (`--synthetic --release C`) and live
+    acceptance (`--live --release C`; PASS / SKIPPED_NO_CREDENTIALS /
+    BLOCKED_ENVIRONMENT recorded separately, never upgraded to success).
+
+- **Reliable delegation (Release B)** — bounded single review, exact PR
+  diff acquisition, and the issue trust boundary per
+  `docs/reliable-delegation-contract-plan.md`:
+  - reloadable review limits (`TRISS_REVIEW_SINGLE_MAX_BYTES`,
+    `TRISS_REVIEW_SHARD_MAX_BYTES`, `TRISS_REVIEW_TOTAL_MAX_BYTES`,
+    `TRISS_REVIEW_MAX_SHARDS`) with atomic validation and full-default
+    fallback on contradictions;
+  - pure diff parser with exact byte accounting and coverage model
+    (repository vs requested-scope axes);
+  - exact merge-base-to-head comparison identity with sanitized Git
+    execution (no external diff/textconv/config, grafts and nonempty
+    shallow repositories rejected) and sealed empty-attribute projection;
+  - inventory-first rename expansion (old-only/new-only selection keeps
+    both sides) and selected-content acquisition bounded by pathspec;
+  - bounded PR acquisition: canonical input, minimum-field `gh`
+    metadata, disposable bare repository under a registry lock (three
+    concurrent runs, 120 MiB pack / 128 MiB filesystem quotas), exact
+    OID re-verification, source-common-dir immutability;
+  - streaming bounded stdin with no partial buffering;
+  - issue trust boundary: PR prose never triggers tracker access;
+    explicit `--issue` uses minimum-field bounded queries; `--skip-issue`
+    deprecated;
+  - shared single-review executor with stable error codes
+    (`TRISS_REVIEW_LIMIT`, `TRISS_REVIEW_INVALID_INPUT`,
+    `TRISS_PROVIDER_EMPTY`, `TRISS_CANCELLED`) and scoped verdict
+    framing; MCP single-review parity with root enforcement and
+    structured coverage.
+
+### Fixed
+
+- `triss coder run --isolate` / `triss_coder_run` isolation downgrade
+    (`--allow-best-effort-caller-worktree` /
+    `allowBestEffortCallerWorktree`): exact opt-in semantics, stable
+    public codes `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED` and
+    `TRISS_CODER_ISOLATION_DOWNGRADED` in message + `err.code` +
+    stderr + envelope warnings, and `effective_isolation:
+    best_effort_caller_worktree` (advisory-only); mechanism
+    unavailability downgrades while slug/branch conflicts
+    (`already exists`) fail closed even with the opt-in via stable
+    `err.code` dispatch (no message parsing).
+
+### Artifact integrity (0.37.0)
+
+- `triss-dsh-provider-bundle-0.37.0.tgz` — sha256
+  `6fd343622443b8e2b15a0d0365fa6a893054d7eb51a26fc1bca5db3c0e068b2d`,
+  integrity `sha512-lBTCSU8kRHm5YN9twwnw1F5wH0OXuU8iwkKyQjXSZVaVCq5ga7z20BirXCJo65rMfcMLVBrbsl1GMXYXCqzpyw==`
+  (computed with the pinned release npm 11.6.2 via
+  `scripts/publish-gate.js pack-inspect`; `npm pack` output is
+  byte-deterministic — tar entries carry the fixed npm epoch mtime — so a
+  test pins this value against every future pack of the same content).
+- Root `triss-coworker-0.37.0.tgz` sha256 is reproducible via
+  `npm pack` at tag `v0.37.0` (the root tarball ships `CHANGELOG.md`, so its
+  hash cannot be recorded inside this file); registry verification compares
+  the packed artifact against the published tarball byte-for-byte
+  (`scripts/publish-gate.js pack-inspect`).
+
+## [0.36.0] — 2026-08-18
+
+### Added
+
+- **OpenCode 2 coder engine (beta)**: `triss coder run --engine opencode2`
+  and `triss coder init --engine opencode2`, pinned to the exact verified
+  build `@opencode-ai/cli@0.0.0-next-17430` (`TRISS_CODER_OPENCODE2_VERSION`
+  to override). The beta runs every managed invocation `--standalone` with
+  auto-update disabled, isolates V2 state under `<project>/.triss/opencode2/`
+  (0700), folds the V2 event stream into the shared usage envelope
+  (`usage_source: "opencode2"`, terminal-error precedence, no fabricated
+  zeros), namespaces sessions per engine, and rides the shared opencode-v1
+  configuration backend for `coder model set` / rollback. See
+  docs/opencode2.md and docs/opencode2-engine-plan.md.
+
+### Security (opencode2 engine beta)
+
+- Fail-closed effective-configuration preflight for `coder run --engine
+  opencode2`: the managed provider projection (exact package, settings keys,
+  credential placeholder, and the worker `baseURL` compared against the
+  configured Triss worker endpoint), `provider.api` and model-level
+  transport overrides are rejected before any credential is forwarded, and
+  the permission gate requires deny-everything shell policy (no live
+  allow/ask rule — the credential sits in the child environment), proven
+  with a real last-match-wins evaluator.
+- `opencode2` runs resolve the engine binary to an absolute path
+  (`which` + `realpath`) and spawn exactly that path, re-verifying the same
+  path and version after the run.
+- Session store reads fail closed on malformed namespaces (no silent data
+  loss on rewrite); the lookup happens inside the isolation cleanup guard so
+  a malformed store never leaks a worktree/branch.
+- XDG runtime roots reject symlinked path components anywhere in the chain
+  below the project root.
+- `opencode init --engine opencode2` owns its flow: credential prompt and
+  `--local`/`--global` scope are honored, an exact-pin mismatch is terminal
+  before any config mutation, and the post-setup audit is the full provider
+  + permission preflight (not just the plugin/agent scan).
+- The full run preflight parses config layers through the JSONC-aware
+  canonical parser (comments and trailing commas no longer abort the run),
+  and `parseOpenCodeDocument` drops trailing commas followed by comments.
+
+### Fixed (review rounds 4–6)
+
+- Dual legacy/native config forms (`provider`+`providers`,
+  `plugin`+`plugins`, `permission`+`permissions`) reject — the pinned build
+  prefers the native value while a legacy-first projection audits the other
+  one; the worker key/endpoint provenance gate resolves each field's
+  EFFECTIVE source from the pre-dotenv snapshot (a decoy key in the project
+  `.triss.env` cannot mask a shell key); unrelated provider definitions
+  (in-process npm code) reject; the audit walks the canonical
+  (`realpathSync.native`) runtime directory; audited sources are re-audited
+  immediately before the credential-bearing spawn (TOCTOU); the top-level
+  key table is captured from the official schema (benign keys no longer
+  false-reject; object `lsp`/`formatter` and `experimental` reject).
+- A held session-store lock no longer discards a finished run:
+  `persistSessionMapping` retries with backoff and degrades to the lock-free
+  protocol (mapping kept, warning emitted, foreign lock untouched).
+- A corrupted `sessions.json` on the V1 `--isolate` path no longer strands
+  the `.triss/wt/<slug>` worktree and `coder/<slug>` branch.
+- `TRISS_CODER_ENGINE=opencode2` from a `.env` file now routes `coder init`
+  to the V2 flow (the engine is resolved after the env files load); the
+  pre-dotenv snapshots are threaded through so the provenance and
+  pin-shadow checks stay exact.
+- `coder init --engine opencode2` on a tree carrying the V1 bash allowlist
+  rejects BEFORE any credential/config write with actionable guidance; a
+  fresh V2 init warns that the shared deny-everything policy removes the
+  allowlisted commands from plain V1 runs (documented in
+  docs/opencode2.md, including two new troubleshooting rows).
+- Model inspection tolerates unrelated hostile config shapes (a non-string
+  plugin reference, unreadable directories) — the post-commit audit of a
+  successful `coder model set` no longer rolls back over them; `coder
+  models` warnings use the OpenCode branch for `opencode2` (no false
+  `configured-model-unavailable` for a shell-exported foreign model);
+  rollback of an `opencode2` record reports engine `opencode2`.
+- `opencode-go/` routes price as unknown (the Go reseller's tariffs are
+  unmodeled); the prefixed `TRISS_PRICE_OPENCODE_GO_<MODEL>` override is
+  the documented way to price them.
+- Unknown `engines.*` namespaces in the session store fail closed;
+  `ensureOpenCode2RuntimeDirs` reports the directories it created;
+  `.env.example` documents `TRISS_CODER_OPENCODE2_VERSION`.
+
+### Artifact integrity (0.36.0)
+
+- `triss-dsh-provider-bundle-0.36.0.tgz` — sha256
+  `0e3100362fc02d242deac114ec6e0c4c966bbe5edde4f156a2ffdb76ef2eb329`,
+  integrity `sha512-P2QoA6Ahu/J9swIJhk9IkuP1OLR+bzn4zJdUKyuskutbis2GUSt5m3n+QmqP7B0rB1JAqi0WGIMkUrTBcmf9cQ==`
+  (computed with the pinned release npm 11.6.2 via
+  `scripts/publish-gate.js pack-inspect`; `npm pack` output is
+  byte-deterministic — tar entries carry the fixed npm epoch mtime — so a
+  test pins this value against every future pack of the same content).
+- Root `triss-coworker-0.36.0.tgz` sha256 is reproducible via
+  `npm pack` at tag `v0.36.0` (the root tarball ships `CHANGELOG.md`, so its
+  hash cannot be recorded inside this file); registry verification compares
+  the packed artifact against the published tarball byte-for-byte
+  (`scripts/publish-gate.js pack-inspect`).
+
 ## [0.35.0] — 2026-08-14
 
 ### Added
 
+- **Reliable delegation (Release A)** — coder envelope v2 orchestration per
+  `docs/reliable-delegation-contract-plan.md`:
+  - envelope fields `session_slug`, `result_retention`, `result_id`, and
+    `execution_capabilities` (eight honest `enforced|best_effort|unavailable`
+    values + `effective_isolation`) on every safe envelope
+    (`docs/reliable-delegation-release-a.md`);
+  - v2 session CLI: `triss coder session list`, `triss coder session clean
+    <slug> --engine <opencode|crush>` (per-engine store only, legacy
+    `.triss/sessions.json` never touched);
+  - retained-result registry: `triss coder result list`, `triss coder result
+    clean <run-id>`, and the exact result-registry codec/transitions
+    (1 GiB reservation / 3 GiB payload budget + 1 GiB headroom,
+    `TRISS_CODER_RESULT_CAP`, `TRISS_CODER_RESULT_QUOTA_REQUIRED`);
+  - rollback contract: `triss coder state backup|validate|adopt|reset` with
+    bounded no-follow backup, completion marker, and
+    `TRISS_CODER_ROLLBACK_RESULTS_PENDING` guard;
+  - quarantine transaction and quarantine clean (`quarantine-v1`,
+    phase-aware manifest machine, completion-marker hashing);
+  - credential proxy (loopback one-run token) on both engines — the real
+    provider key never reaches the engine environment; every run requires
+    the proxy (Release A rejects runs when it is unavailable);
+  - pure provider error classifier with stable public codes
+    (`TRISS_PROVIDER_AUTH/POLICY/RATE/TIMEOUT/NOT_FOUND/CONNECTION/UNKNOWN/
+    CONFLICT/EMPTY`);
+  - bounded blocker diagnostics (`environment_permission`,
+    `execution_policy`, `lock_or_process_state`, `unknown`; ≤16 entries,
+    duplicate categories collapsed);
+  - MCP: `allowBestEffortCallerWorktree` (default false),
+    `triss_coder_result_list`, `triss_coder_result_clean`.
 - `triss-dsh-provider-bundle`, a standalone npm package (workspace
   `packages/dsh-provider-bundle`) that activates the DeepSeek Harness
   `llm-pi-ai` adapter for `opencode`, `opencode-go`, and `zai` routes in a
@@ -80,6 +283,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the packed artifact against the published tarball byte-for-byte
   (`scripts/publish-gate.js pack-inspect`).
 
+### Changed
+
+- Non-isolated `files_changed` is now `null` rather than `[]`;
+  `run_files_changed` is the only changes-expectation evidence. Consumers
+  must branch on `envelope_version` and `change_detection.status`.
+- Bare `--continue` is rejected with migration guidance; v2 state is
+  selected only via `--session <slug>`.
+- `ask`/`review`/MCP fail empty responses with the stable
+  `TRISS_PROVIDER_EMPTY` code instead of a direct `process.exit`.
+- Capability-dependent Windows npm support wording: an unavailable OS
+  sandbox/cleanup/lock/quota never blocks a non-isolated/best-effort run but
+  provides none of those guarantees; unavailable credential isolation always
+  blocks before spawn.
+
+### Fixed
+
+- `fd.readFile` position semantics in fixed-kernel-lock release (marker
+  clearing reads via path, keeping the fixed inode).
+- Quarantine `readdir` import; result-state deletion moved to an immutable
+  tombstone sidecar.
+
 ## [0.34.0] — 2026-08-13
 
 ### Added

package/README.md

@@ -279,7 +279,8 @@ The exposed tool set is **filtered by configured credentials**:
   `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
+  (`opencode` V1 default; `--engine opencode2` beta — see
+  [opencode2.md](docs/opencode2.md) — or `crush`); its timeout defaults to
   1500s (25 min) over MCP, above the CLI's 900s, since coding runs are
   expected to be long; override per call via the `timeout` arg. For
   runs that may exceed it, use `triss coder run` on the CLI instead.
@@ -311,8 +312,8 @@ and writing**.
 | `triss review`     | Code review on a branch, PR, or explicitly piped diff (linked ticket only for branch/PR) | 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/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 init` | Sets up a coding agent (default `opencode` V1 engine; `--engine opencode2` for the V2 beta — shares the `opencode.json` config, see [docs/opencode2.md](docs/opencode2.md); `--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|opencode2|crush` — opencode V1 default, opencode2 beta per [docs/opencode2.md](docs/opencode2.md); `--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 |
@@ -532,8 +533,44 @@ git diff main...HEAD | triss review --stdin  # review this branch's merge-base d
 triss review --skip-issue    # don't try ticket lookup
 triss review --provider glm  # same review flow, one-shot GLM inference
 triss review --provider kimi # …or Kimi (pro preset = kimi-k3)
+triss review --files src/a.js test/b.test.js  # literal file selection (after --)
+triss review --issue ENG-42  # explicit tracker issue (never inferred from prose)
 ```
 
+### Reliable delegation — review safety (Release B)
+
+Review runs are bounded and fail closed (see
+[`docs/reliable-delegation-release-a.md`](docs/reliable-delegation-release-a.md)):
+
+- **Limits**: single request (256 KiB default / 1 MiB hard max), shard
+  (96 KiB / 256 KiB), total corpus (4 MiB / 16 MiB), shard count (64 /
+  256) — all reloadable via `TRISS_REVIEW_*_BYTES` / `TRISS_REVIEW_MAX_SHARDS`;
+  any contradiction falls back to the complete default set.
+- **Git**: exact merge-base-to-head identity, one unique merge base, a
+  sanitized environment (no external diff/textconv/config injection,
+  grafts and nonempty shallow repositories rejected).
+- **Selection**: literal `--files` selectors are expanded across renames
+  and only the selected content is acquired — a huge change with a small
+  selected file never buffers the full diff first.
+- **PRs**: canonical input only, exact OID re-verification, disposable
+  bare repository under a registry lock (3 concurrent runs, 120 MiB pack /
+  128 MiB filesystem quotas); the source directory is never mutated.
+- **Issues**: PR or branch prose NEVER triggers tracker access. Only an
+  explicit `--issue KEY` performs a bounded minimum-field lookup;
+  `--skip-issue` is deprecated.
+- **Empty responses** fail with `TRISS_PROVIDER_EMPTY` instead of
+  producing a clean verdict; usable non-empty text is never trimmed.
+
+### Sharding (Release C)
+
+`triss review --payload-mode shard` runs source-ordered whole-file shards
+sequentially. A file is never split across shards; the first failure or
+cancellation stops the sequence. **Completed sharded execution is not a
+global review**: there is no aggregation call, no cross-shard analysis, and
+no global approval — the CLI prints `global verdict: unavailable_for_sharded`.
+Partial errors carry completed shard verdicts only (never raw diff content).
+`evidence + shard` and `shard + --stream` are rejected before any model call.
+
 The three diff sources are mutually exclusive: local Git (`triss review` or
 `--base`), a GitHub PR (`triss review <PR>`), or UTF-8 text piped to
 `triss review --stdin`. `--stdin` cannot be combined with a PR number or
@@ -587,8 +624,9 @@ default timeout, configurable via `--timeout <ms>`.
 
 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
+OpenCode Zen, or OpenCode Go models (the `opencode` V1 engine by default;
+`opencode2` beta — see [docs/opencode2.md](docs/opencode2.md) — or `crush`; see
+**Engines** below) instead of the primary model writing
 the code itself.
 
 ```bash
@@ -597,8 +635,37 @@ triss coder run "add input validation to /signup" --isolate
 triss coder run "..." --engine crush              # crush engine (isolates by default; restrict is opt-in)
 triss coder run "..." --engine crush --restrict   # crush + CLI allowlist on top of the worktree
 triss coder clean                                 # remove finished isolation worktrees
+triss coder session list                          # list v2 sessions (per engine)
+triss coder session clean <slug> --engine opencode # remove one inactive isolated session
+triss coder result list                           # list retained result artifacts
+triss coder state backup --project <path>         # Section 15 rollback backup
+triss coder state validate --project <path> --backup <dir>
 ```
 
+Every `triss coder run` envelope (and the matching MCP tool) carries the
+Release A contract fields: `session_slug` (explicit slug or an anonymous
+generated one — never an implicit persistent conversation), `result_retention`
+/ `result_id` (`retained` only for isolated changed runs with enforced
+result-store quota and a successful reservation), and `execution_capabilities`
+(eight honest `enforced|best_effort|unavailable` values plus
+`effective_isolation`). Non-isolated `files_changed` is `null`; the only
+changes-expectation evidence is `run_files_changed`. Process completion is not
+task satisfaction — use `--expect changes --isolate` and inspect `git status`
+yourself. Unavailable OS sandbox/cleanup/lock/quota does not block a
+non-isolated/best-effort run but provides none of those guarantees; explicit
+or default isolation needs `--allow-best-effort-caller-worktree` (default
+off) or fails before spawn with `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED`
+(stable `err.code`; retry hint when the isolation mechanism is unavailable),
+and unavailable credential isolation always blocks before spawn. With the
+opt-in and only when the isolation mechanism itself is unavailable (no git
+repository or worktree creation failure — slug/branch conflicts like
+`already exists` still fail closed), the run downgrades to
+`best_effort_caller_worktree`: stderr and envelope `warnings` carry
+`TRISS_CODER_ISOLATION_DOWNGRADED` and `effective_isolation` becomes
+`best_effort_caller_worktree` (advisory-only, `files_changed` is `null`,
+edits may reach the caller worktree). Full details:
+`docs/reliable-delegation-release-a.md`.
+
 `triss coder init` first asks which provider to configure — **Z.AI GLM**
 (default), the existing **Triss worker** (`--provider worker`, aliases
 `openai` / `openai-compatible`), **OpenCode Zen** (`--provider opencode-zen`, free rotating

package/bin/triss.js

@@ -40,8 +40,19 @@ import {
   runEdit,
   runUnset,
 } from '../src/commands/config.js';
-import { runCoderInit, runCoderRun, runCoderClean } from '../src/commands/coder.js';
+import {
+  runCoderInit,
+  runCoderRun,
+  runCoderClean,
+  runCoderSessionList,
+  runCoderSessionClean,
+  runCoderStateAdopt,
+  runCoderStateReset,
+  runCoderResultList,
+  runCoderResultClean,
+} from '../src/commands/coder.js';
 import { runCoderModels, runCoderModelSet, runCoderModelRollback } from '../src/commands/coder-models.js';
+import { runCoderStateBackup, runCoderStateValidate } from '../src/commands/coder-state-backup.js';
 import { loadIntegrations } from '../src/integrations/_registry.js';
 import { withCall } from '../src/call-context.js';
 import { positiveIntegerOption, positiveNumberOption } from '../src/option-validation.js';
@@ -191,6 +202,7 @@ program
   .option('--small-model <p/m>', 'forward coder small model')
   .option('--isolate', 'forward coder isolation')
   .option('--no-isolate', 'disable coder isolation')
+  .option('--allow-best-effort-caller-worktree', 'forward coder isolation downgrade')
   .option('--restrict', 'forward coder restriction')
   .option('--no-restrict', 'disable coder restriction')
   .option('--cwd <path>', 'forward coder working directory')
@@ -214,6 +226,8 @@ program
   .option('-b, --base <branch>', 'compare against this branch (default: auto-detect origin/HEAD or main/master/develop)')
   .option('--skip-issue', "don't try to look up a Jira/Linear ticket from the branch/PR title")
   .option('--stdin', 'read an explicitly piped UTF-8 diff instead of Git or PR sources')
+  .option('--files <paths...>', 'literal path selectors: review ONLY these files (repeatable; renames select both sides)')
+  .option('--issue <key>', 'explicit linked-issue key (e.g. PROJ-123); PR prose never triggers tracker access')
   .option('-q, --question <text>', 'override the default review question')
   .option('--provider <name>', 'inference provider: worker (default), deepseek (alias), glm, or kimi (alias: moonshot)')
   .option('-m, --model <name>', 'model preset (flash | pro) or full model id (default: pro)')
@@ -221,6 +235,7 @@ program
   .option('--format <format>', 'response format: text (default) or evidence')
   .option('--stream', 'force streaming even when stdout is not a TTY')
   .option('--no-stream', 'disable streaming output (default streams when stdout is a TTY)')
+  .option('--payload-mode <mode>', 'review payload mode: single (default) or shard (sequential whole-file shards; no global verdict)')
   .action((pr, opts) => wrap(runReview)(pr, opts));
 
 program
@@ -276,7 +291,7 @@ config
   .option('-f, --force', 're-prompt for keys that are already set')
   .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-engine <name>', 'coder target only: coding engine to configure (opencode default, opencode2 beta, or crush). `coder init` uses --engine')
   .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));
 
@@ -324,14 +339,14 @@ config
 
 const coder = program
   .command('coder')
-  .description('Run a coding agent (OpenCode or Crush engine)');
+  .description('Run a coding agent (OpenCode V1, OpenCode 2 beta, or Crush engine)');
 
 coder
   .command('init')
-  .description('Install/configure a coding engine (opencode default, or crush), provider key, permission policy, and agent templates')
+  .description('Install/configure a coding engine (opencode default, opencode2 beta, or crush), provider key, permission policy, and agent templates')
   .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('--engine <name>', 'coding engine to configure: opencode (default), opencode2 (beta — shares the opencode.json config; see docs/opencode2.md), or crush')
   .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)')
@@ -339,11 +354,11 @@ coder
 
 coder
   .command('run [prompt]')
-  .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')
+  .description('Spawn a coding agent — GLM, the OpenAI-compatible Triss worker, Kimi, OpenCode Zen, or OpenCode Go (opencode default; opencode2 beta or --engine crush) — and print a JSON envelope to stdout')
+  .option('--engine <name>', 'coding engine: opencode (default), opencode2 (beta — see docs/opencode2.md), 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('--agent <name>', 'agent template to use (V1 default: coder; opencode2 beta uses its built-in primary agent unless set)')
   .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)')
@@ -353,6 +368,7 @@ coder
   .option('--no-restrict', 'crush only: disable restrict (crush auto-approves every tool — the default)')
   .option('--cwd <path>', 'working directory (ignored with --isolate)')
   .option('--timeout <sec>', 'kill the engine after this many seconds', parsePositiveNumber, 900)
+  .option('--allow-best-effort-caller-worktree', 'allow downgrade to caller worktree when isolated isolation cannot be enforced (default off — fails before spawn without it)')
   .option('--stdin', 'read the prompt from piped stdin instead of the [prompt] argument')
   .option('--json', 'no-op — the envelope is always JSON; kept for symmetry with other commands')
   .action((prompt, opts) => wrap(runCoderRun)(prompt, opts));
@@ -366,10 +382,10 @@ coder
 coder
   .command('models')
   .description('List current + live coder models, provider compatibility, and credential readiness (read-only)\n\n' +
-    'Configuration sources:\n' +
-    '  • opencode: project opencode.json (local) or ~/.config/opencode/opencode.json (global)\n' +
+    'Configuration sources (layered; later sources win):\n' +
+    '  • opencode & opencode2: JSONC-aware layered config — global ~/.config/opencode/opencode.json, then every opencode.json/.opencode/opencode.json up from the project root to the Git boundary (project-local wins)\n' +
     '  • crush: ./.crush/crush.json (local) or ~/.local/share/crush/crush.json (global)')
-  .option('--engine <name>', 'coding engine: opencode (default) or crush')
+  .option('--engine <name>', 'coding engine: opencode (default), opencode2 (beta — layered JSONC config), or crush')
   .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));
@@ -391,7 +407,7 @@ coderModel
       '  • crush: project .crush/crush.json (local) or ~/.local/share/crush/crush.json (global)'
   )
   .option('--small <model>', 'small/fast model id (omit to keep the current compatible value)')
-  .option('--engine <name>', 'coding engine: opencode (default) or crush')
+  .option('--engine <name>', 'coding engine: opencode (default), opencode2 (beta — layered JSONC config), or crush')
   .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)')
@@ -408,6 +424,72 @@ coderModel
   .option('-l, --local', 'restore to the project scope (./opencode.json or ./.crush/crush.json)')
   .action((opts) => wrap(runCoderModelRollback)(opts.from, opts));
 
+// `coder state` is a command GROUP whose leaves are `backup` and `validate`
+// (Section 15 rollback contract).
+const coderState = coder
+  .command('state')
+  .description('Back up or validate the v2 coder state of a project (rollback contract)');
+
+coderState
+  .command('backup')
+  .description('Create a bounded rollback backup of the v2 coder state (both engine session stores + coder-state-v2)')
+  .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
+  .option('--backup <path>', 'backup destination directory (default: <project>/.triss/backups/<timestamp>)')
+  .option('--json', 'print the stable machine-readable result (no secrets)')
+  .action((opts) => wrap(runCoderStateBackup)(opts));
+
+coderState
+  .command('validate')
+  .description('Validate a rollback backup: manifest schema, completion marker hash, per-entry verification')
+  .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
+  .requiredOption('--backup <basename>', 'backup directory to validate')
+  .option('--json', 'print the stable machine-readable result (no secrets)')
+  .action((opts) => wrap(runCoderStateValidate)(opts));
+
+coderState
+  .command('adopt')
+  .description('Adopt owned v2 state under a NEW project id: quarantine the old id, rewrite validated owner records')
+  .requiredOption('--from-project-id <32hex>', 'the old project id (32 lowercase hex) to quarantine')
+  .action((opts) => wrap(runCoderStateAdopt)(opts));
+
+coderState
+  .command('reset')
+  .description('Quarantine all validated local v2 state and create an empty identity (never deletes it)')
+  .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
+  .action((opts) => wrap(runCoderStateReset)(opts));
+
+// `coder session` group (v2 session CLI contract, Atomic 23).
+const coderSession = coder
+  .command('session')
+  .description('List or clean v2 isolated sessions (per-engine store; legacy .triss/sessions.json is never touched)');
+
+coderSession
+  .command('list')
+  .description('Serialize the bounded v2 session inventory projection to stdout')
+  .option('--engine <name>', 'coding engine: opencode (default) or crush')
+  .action((opts) => wrap(runCoderSessionList)(opts));
+
+coderSession
+  .command('clean <slug>')
+  .description('Remove a selected inactive v2 isolated session/workspace transaction')
+  .requiredOption('--engine <name>', 'coding engine: opencode or crush (MANDATORY)')
+  .action((slug, opts) => wrap(runCoderSessionClean)(slug, opts));
+
+// `coder result` group (retained-result CLI, Atomic 23).
+const coderResult = coder
+  .command('result')
+  .description('List or clean retained result artifacts (never persistent sessions)');
+
+coderResult
+  .command('list')
+  .description('Serialize the bounded retained-result projection to stdout')
+  .action((opts) => wrap(runCoderResultList)(opts));
+
+coderResult
+  .command('clean <run-id>')
+  .description('Remove only a validated retained result artifact (run-<32 lowercase hex>)')
+  .action((runId, opts) => wrap(runCoderResultClean)(runId, opts));
+
 function wrap(fn) {
   return async (...args) => {
     try {

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

@@ -124,3 +124,17 @@ RED tests must establish:
 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.
+
+## Current credential-proxy limitation (2026-08)
+
+The parent-owned credential proxy pins the upstream ORIGIN plus a path prefix
+per provider. For opencode built-in providers without a documented base-URL
+override (`moonshot`, `kimi-for-coding`), the engine cannot be verifiably
+pointed at the proxy, so `triss coder run` fails closed BEFORE spawn instead
+of handing the real upstream a one-run proxy token it would reject. `zai`
+(ZAI_BASE_URL/ZHIPU_BASEURL), `opencode-zen/go` (OPENCODE_BASE_URL), the
+managed `triss-worker` overlay, and every crush run keep working. Direct
+non-coder calls (`triss ask/review/chat --provider kimi|moonshot`) are
+unaffected — they never spawn an engine. Lifting the limitation requires an
+audited provider overlay (the same mechanism the worker block uses) for these
+providers.

package/docs/configuration.md

@@ -263,16 +263,30 @@ self-hosted endpoints).
 | Variable                        | Required | Default            | Notes                                     |
 | -------------------------------- | -------- | ------------------ | ------------------------------------------ |
 | `ZHIPU_API_KEY`                  | yes¹     | —                  | Z.AI API key for `ask`/`review --provider glm` and GLM coder models — <https://z.ai/manage-apikey/apikey-list> |
-| `OPENCODE_API_KEY`               | no¹      | —                  | Shared OpenCode credential for Zen `opencode/*` and paid Go `opencode-go/*` models (opencode engine only). A key alone does not prove Go subscription, quota, or regional readiness. See [opencode-zen.md](opencode-zen.md) and [opencode-go.md](opencode-go.md). |
+| `OPENCODE_API_KEY`               | no¹      | —                  | Shared OpenCode credential for Zen `opencode/*` and paid Go `opencode-go/*` models (opencode engines). A key alone does not prove Go subscription, quota, or regional readiness. See [opencode-zen.md](opencode-zen.md) and [opencode-go.md](opencode-go.md). |
 | `MOONSHOT_API_KEY`               | no¹      | —                  | Moonshot AI (Kimi) key for `ask`/`review --provider kimi` and `moonshotai/*` coder models — <https://platform.kimi.ai/console/api-keys> |
-| `KIMI_API_KEY`                   | no¹      | —                  | Kimi for Coding subscription key (opencode engine only) — unlocks `kimi-for-coding/*` models like `kimi-for-coding/k3` — <https://www.kimi.com/code/docs/en/> |
+| `KIMI_API_KEY`                   | no¹      | —                  | Kimi for Coding subscription key (opencode engines) — unlocks `kimi-for-coding/*` models like `kimi-for-coding/k3` — <https://www.kimi.com/code/docs/en/> |
 | `TRISS_KIMI_BASE_URL`            | no       | `https://api.moonshot.ai/v1` | Endpoint for `--provider kimi` ask/review calls — set `https://api.moonshot.cn/v1` for a China-mainland key. Trailing slashes are stripped; a blank/degenerate value falls back to the default |
 | `TRISS_CODER_MODEL`              | no       | `zai-coding-plan/glm-5.2`       | Resolved **main** model, passed to opencode via `--model`. Worker uses `triss-worker/<id>`, Go uses `opencode-go/<id>`, and Zen uses `opencode/<id>`. Main and small must stay within one provider prefix. |
 | `TRISS_CODER_SMALL_MODEL`        | no       | `zai-coding-plan/glm-5-turbo`   | Small/fast **management/init intent** — written to `opencode.json` `small_model` by `init`/`triss coder model set`. **Not** a runtime override of an already-pinned small role (see precedence) |
 | `TRISS_CODER_OPENCODE_VERSION`   | no       | `1.18.7`           | Pin override for the `opencode-ai` npm install |
-| `TRISS_CODER_ENGINE`             | no       | `opencode`          | Coding engine: `opencode` (default) or `crush` |
+| `TRISS_CODER_ENGINE`             | no       | `opencode`          | Coding engine: `opencode` (default), `opencode2` (beta — see [opencode2.md](./opencode2.md)), or `crush` |
+| `TRISS_CODER_OPENCODE2_VERSION`  | no       | `0.0.0-next-17430`  | Exact pin override for the `@opencode-ai/cli` npm install (opencode2 engine — exact match required) |
 | `TRISS_CODER_CRUSH_VERSION`      | no       | `0.1.6`             | Pin override for the `@phpcraftdream/crush` npm install (crush engine) |
-| `TRISS_CODER_CRUSH_RESTRICT`     | no       | unset (`0`)        | crush only — `1` opts INTO the CLI allowlist (`--restrict-run` + `--allow-bash`/`--allow-tool`, the only enforcement path that works today — crush 0.1.3 ignores the `permissions.run` config). Unset leaves crush unrestricted; crush then defaults to isolate-ON. CLI `--restrict`/`--no-restrict` overrides; crush.json `permissions.run.restrict` is the next fallback (forward-compat — currently inert) |
+| `TRISS_CODER_SESSION_CAP`        | no       | `4`                 | Persistent v2 session inventory cap per engine (fail closed) |
+
+### Review limits (Release B)
+
+All four limits are reloadable at runtime; values are independently clamped
+to their hard maxima, and any contradiction (e.g. `shard_max > single_max`)
+falls back to the complete default set — never a partial application.
+
+| Variable                        | Default            | Hard max        | Notes                                     |
+| ------------------------------- | ------------------ | --------------- | ----------------------------------------- |
+| `TRISS_REVIEW_SINGLE_MAX_BYTES` | `262144` (256 KiB) | `1048576` (1 MiB) | Single-request payload bound (metadata + question + diff) |
+| `TRISS_REVIEW_SHARD_MAX_BYTES`  | `98304` (96 KiB)   | `262144` (256 KiB) | Per-shard payload bound (sharding not yet available) |
+| `TRISS_REVIEW_TOTAL_MAX_BYTES`  | `4194304` (4 MiB)  | `16777216` (16 MiB) | Total corpus bound; also the stdin acquisition cap |
+| `TRISS_REVIEW_MAX_SHARDS`       | `64`               | `256`            | Shard-count bound (sharding not yet available) |
 
 `triss coder init` auto-detects which Z.AI endpoint `ZHIPU_API_KEY`
 actually authenticates against — the `zai-coding-plan` (subscription)