triss-coworker 0.36.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/CHANGELOG.md +128 -0
  2. package/README.md +65 -0
  3. package/bin/triss.js +83 -1
  4. package/docs/coder-one-shot-provider-plan.md +14 -0
  5. package/docs/configuration.md +14 -1
  6. package/docs/mcp.md +19 -3
  7. package/docs/reliable-delegation-contract-plan.md +37 -8
  8. package/docs/reliable-delegation-release-a.md +263 -0
  9. package/package.json +2 -2
  10. package/src/coder-credential-proxy.js +443 -0
  11. package/src/coder-engines/crush.js +10 -1
  12. package/src/coder-git-mediator.js +226 -0
  13. package/src/coder-lease.js +240 -0
  14. package/src/coder-orchestration.js +211 -0
  15. package/src/coder-process-supervisor.js +159 -0
  16. package/src/coder-result-owner-adapter.js +108 -0
  17. package/src/coder-result-quarantine.js +358 -0
  18. package/src/coder-result-registry-codec.js +231 -0
  19. package/src/coder-result-transitions.js +297 -0
  20. package/src/coder-result.js +542 -0
  21. package/src/coder-run-state.js +98 -0
  22. package/src/coder-sandbox.js +270 -0
  23. package/src/coder-session-inventory-codec.js +275 -0
  24. package/src/coder-session-owner-adapter.js +177 -0
  25. package/src/coder-session-store.js +327 -0
  26. package/src/coder-session-transitions.js +296 -0
  27. package/src/coder-state-backup.js +384 -0
  28. package/src/coder-state.js +346 -0
  29. package/src/coder-write-quota.js +171 -0
  30. package/src/commands/ask.js +2 -10
  31. package/src/commands/coder-state-backup.js +80 -0
  32. package/src/commands/coder.js +956 -45
  33. package/src/commands/exec.js +8 -1
  34. package/src/commands/review.js +310 -54
  35. package/src/config.js +103 -1
  36. package/src/fixed-kernel-lock.js +243 -0
  37. package/src/integrations/_contract.js +55 -16
  38. package/src/managed-root.js +253 -0
  39. package/src/mcp/handlers.js +95 -3
  40. package/src/mcp/review-core.js +310 -36
  41. package/src/mcp/tools.js +75 -2
  42. package/src/owned-process-journal.js +310 -0
  43. package/src/owned-process-reconcile.js +298 -0
  44. package/src/provider-errors.js +300 -0
  45. package/src/release-a-acceptance.js +605 -0
  46. package/src/review-executor.js +218 -0
  47. package/src/review-git.js +320 -0
  48. package/src/review-input.js +142 -0
  49. package/src/review-live.js +75 -0
  50. package/src/review-payload.js +379 -0
  51. package/src/review-pr-fetch.js +158 -0
  52. package/src/review-pr-identity.js +154 -0
  53. package/src/review-pr-metadata.js +112 -0
  54. package/src/review-pr-registry.js +267 -0
  55. package/src/review-pr.js +161 -0
  56. package/src/review-scoped.js +265 -0
  57. package/src/update/install.js +1 -1
  58. package/src/worktree-fingerprint.js +302 -0
  59. package/templates/claude-full.md +12 -2
package/CHANGELOG.md CHANGED
@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.37.0] — 2026-08-18
11
+
12
+ ### Added
13
+
14
+ - **Reliable delegation (Release C)** — sequential sharding per
15
+ `docs/reliable-delegation-contract-plan.md`:
16
+ - `--payload-mode shard` CLI + MCP shard parity: source-ordered
17
+ whole-file shards (a file is never split across shards);
18
+ - sequential executor with first-failure stop, cancellation
19
+ between/in-flight shards, fresh limit re-checks, and per-shard
20
+ attempt/usage facts;
21
+ - **no global verdict**: completed sharded execution prints
22
+ `global verdict: unavailable_for_sharded`; no aggregation call, no
23
+ cross-shard analysis, no global approval;
24
+ - structured partial errors carry completed shard verdicts only —
25
+ never completed prose or raw diff content;
26
+ - `evidence + shard` and `shard + --stream` rejected before any model
27
+ call;
28
+ - Release C synthetic acceptance (`--synthetic --release C`) and live
29
+ acceptance (`--live --release C`; PASS / SKIPPED_NO_CREDENTIALS /
30
+ BLOCKED_ENVIRONMENT recorded separately, never upgraded to success).
31
+
32
+ - **Reliable delegation (Release B)** — bounded single review, exact PR
33
+ diff acquisition, and the issue trust boundary per
34
+ `docs/reliable-delegation-contract-plan.md`:
35
+ - reloadable review limits (`TRISS_REVIEW_SINGLE_MAX_BYTES`,
36
+ `TRISS_REVIEW_SHARD_MAX_BYTES`, `TRISS_REVIEW_TOTAL_MAX_BYTES`,
37
+ `TRISS_REVIEW_MAX_SHARDS`) with atomic validation and full-default
38
+ fallback on contradictions;
39
+ - pure diff parser with exact byte accounting and coverage model
40
+ (repository vs requested-scope axes);
41
+ - exact merge-base-to-head comparison identity with sanitized Git
42
+ execution (no external diff/textconv/config, grafts and nonempty
43
+ shallow repositories rejected) and sealed empty-attribute projection;
44
+ - inventory-first rename expansion (old-only/new-only selection keeps
45
+ both sides) and selected-content acquisition bounded by pathspec;
46
+ - bounded PR acquisition: canonical input, minimum-field `gh`
47
+ metadata, disposable bare repository under a registry lock (three
48
+ concurrent runs, 120 MiB pack / 128 MiB filesystem quotas), exact
49
+ OID re-verification, source-common-dir immutability;
50
+ - streaming bounded stdin with no partial buffering;
51
+ - issue trust boundary: PR prose never triggers tracker access;
52
+ explicit `--issue` uses minimum-field bounded queries; `--skip-issue`
53
+ deprecated;
54
+ - shared single-review executor with stable error codes
55
+ (`TRISS_REVIEW_LIMIT`, `TRISS_REVIEW_INVALID_INPUT`,
56
+ `TRISS_PROVIDER_EMPTY`, `TRISS_CANCELLED`) and scoped verdict
57
+ framing; MCP single-review parity with root enforcement and
58
+ structured coverage.
59
+
60
+ ### Fixed
61
+
62
+ - `triss coder run --isolate` / `triss_coder_run` isolation downgrade
63
+ (`--allow-best-effort-caller-worktree` /
64
+ `allowBestEffortCallerWorktree`): exact opt-in semantics, stable
65
+ public codes `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED` and
66
+ `TRISS_CODER_ISOLATION_DOWNGRADED` in message + `err.code` +
67
+ stderr + envelope warnings, and `effective_isolation:
68
+ best_effort_caller_worktree` (advisory-only); mechanism
69
+ unavailability downgrades while slug/branch conflicts
70
+ (`already exists`) fail closed even with the opt-in via stable
71
+ `err.code` dispatch (no message parsing).
72
+
73
+ ### Artifact integrity (0.37.0)
74
+
75
+ - `triss-dsh-provider-bundle-0.37.0.tgz` — sha256
76
+ `6fd343622443b8e2b15a0d0365fa6a893054d7eb51a26fc1bca5db3c0e068b2d`,
77
+ integrity `sha512-lBTCSU8kRHm5YN9twwnw1F5wH0OXuU8iwkKyQjXSZVaVCq5ga7z20BirXCJo65rMfcMLVBrbsl1GMXYXCqzpyw==`
78
+ (computed with the pinned release npm 11.6.2 via
79
+ `scripts/publish-gate.js pack-inspect`; `npm pack` output is
80
+ byte-deterministic — tar entries carry the fixed npm epoch mtime — so a
81
+ test pins this value against every future pack of the same content).
82
+ - Root `triss-coworker-0.37.0.tgz` sha256 is reproducible via
83
+ `npm pack` at tag `v0.37.0` (the root tarball ships `CHANGELOG.md`, so its
84
+ hash cannot be recorded inside this file); registry verification compares
85
+ the packed artifact against the published tarball byte-for-byte
86
+ (`scripts/publish-gate.js pack-inspect`).
87
+
10
88
  ## [0.36.0] — 2026-08-18
11
89
 
12
90
  ### Added
@@ -107,6 +185,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
107
185
 
108
186
  ### Added
109
187
 
188
+ - **Reliable delegation (Release A)** — coder envelope v2 orchestration per
189
+ `docs/reliable-delegation-contract-plan.md`:
190
+ - envelope fields `session_slug`, `result_retention`, `result_id`, and
191
+ `execution_capabilities` (eight honest `enforced|best_effort|unavailable`
192
+ values + `effective_isolation`) on every safe envelope
193
+ (`docs/reliable-delegation-release-a.md`);
194
+ - v2 session CLI: `triss coder session list`, `triss coder session clean
195
+ <slug> --engine <opencode|crush>` (per-engine store only, legacy
196
+ `.triss/sessions.json` never touched);
197
+ - retained-result registry: `triss coder result list`, `triss coder result
198
+ clean <run-id>`, and the exact result-registry codec/transitions
199
+ (1 GiB reservation / 3 GiB payload budget + 1 GiB headroom,
200
+ `TRISS_CODER_RESULT_CAP`, `TRISS_CODER_RESULT_QUOTA_REQUIRED`);
201
+ - rollback contract: `triss coder state backup|validate|adopt|reset` with
202
+ bounded no-follow backup, completion marker, and
203
+ `TRISS_CODER_ROLLBACK_RESULTS_PENDING` guard;
204
+ - quarantine transaction and quarantine clean (`quarantine-v1`,
205
+ phase-aware manifest machine, completion-marker hashing);
206
+ - credential proxy (loopback one-run token) on both engines — the real
207
+ provider key never reaches the engine environment; every run requires
208
+ the proxy (Release A rejects runs when it is unavailable);
209
+ - pure provider error classifier with stable public codes
210
+ (`TRISS_PROVIDER_AUTH/POLICY/RATE/TIMEOUT/NOT_FOUND/CONNECTION/UNKNOWN/
211
+ CONFLICT/EMPTY`);
212
+ - bounded blocker diagnostics (`environment_permission`,
213
+ `execution_policy`, `lock_or_process_state`, `unknown`; ≤16 entries,
214
+ duplicate categories collapsed);
215
+ - MCP: `allowBestEffortCallerWorktree` (default false),
216
+ `triss_coder_result_list`, `triss_coder_result_clean`.
110
217
  - `triss-dsh-provider-bundle`, a standalone npm package (workspace
111
218
  `packages/dsh-provider-bundle`) that activates the DeepSeek Harness
112
219
  `llm-pi-ai` adapter for `opencode`, `opencode-go`, and `zai` routes in a
@@ -176,6 +283,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
176
283
  the packed artifact against the published tarball byte-for-byte
177
284
  (`scripts/publish-gate.js pack-inspect`).
178
285
 
286
+ ### Changed
287
+
288
+ - Non-isolated `files_changed` is now `null` rather than `[]`;
289
+ `run_files_changed` is the only changes-expectation evidence. Consumers
290
+ must branch on `envelope_version` and `change_detection.status`.
291
+ - Bare `--continue` is rejected with migration guidance; v2 state is
292
+ selected only via `--session <slug>`.
293
+ - `ask`/`review`/MCP fail empty responses with the stable
294
+ `TRISS_PROVIDER_EMPTY` code instead of a direct `process.exit`.
295
+ - Capability-dependent Windows npm support wording: an unavailable OS
296
+ sandbox/cleanup/lock/quota never blocks a non-isolated/best-effort run but
297
+ provides none of those guarantees; unavailable credential isolation always
298
+ blocks before spawn.
299
+
300
+ ### Fixed
301
+
302
+ - `fd.readFile` position semantics in fixed-kernel-lock release (marker
303
+ clearing reads via path, keeping the fixed inode).
304
+ - Quarantine `readdir` import; result-state deletion moved to an immutable
305
+ tombstone sidecar.
306
+
179
307
  ## [0.34.0] — 2026-08-13
180
308
 
181
309
  ### Added
package/README.md CHANGED
@@ -533,8 +533,44 @@ git diff main...HEAD | triss review --stdin # review this branch's merge-base d
533
533
  triss review --skip-issue # don't try ticket lookup
534
534
  triss review --provider glm # same review flow, one-shot GLM inference
535
535
  triss review --provider kimi # …or Kimi (pro preset = kimi-k3)
536
+ triss review --files src/a.js test/b.test.js # literal file selection (after --)
537
+ triss review --issue ENG-42 # explicit tracker issue (never inferred from prose)
536
538
  ```
537
539
 
540
+ ### Reliable delegation — review safety (Release B)
541
+
542
+ Review runs are bounded and fail closed (see
543
+ [`docs/reliable-delegation-release-a.md`](docs/reliable-delegation-release-a.md)):
544
+
545
+ - **Limits**: single request (256 KiB default / 1 MiB hard max), shard
546
+ (96 KiB / 256 KiB), total corpus (4 MiB / 16 MiB), shard count (64 /
547
+ 256) — all reloadable via `TRISS_REVIEW_*_BYTES` / `TRISS_REVIEW_MAX_SHARDS`;
548
+ any contradiction falls back to the complete default set.
549
+ - **Git**: exact merge-base-to-head identity, one unique merge base, a
550
+ sanitized environment (no external diff/textconv/config injection,
551
+ grafts and nonempty shallow repositories rejected).
552
+ - **Selection**: literal `--files` selectors are expanded across renames
553
+ and only the selected content is acquired — a huge change with a small
554
+ selected file never buffers the full diff first.
555
+ - **PRs**: canonical input only, exact OID re-verification, disposable
556
+ bare repository under a registry lock (3 concurrent runs, 120 MiB pack /
557
+ 128 MiB filesystem quotas); the source directory is never mutated.
558
+ - **Issues**: PR or branch prose NEVER triggers tracker access. Only an
559
+ explicit `--issue KEY` performs a bounded minimum-field lookup;
560
+ `--skip-issue` is deprecated.
561
+ - **Empty responses** fail with `TRISS_PROVIDER_EMPTY` instead of
562
+ producing a clean verdict; usable non-empty text is never trimmed.
563
+
564
+ ### Sharding (Release C)
565
+
566
+ `triss review --payload-mode shard` runs source-ordered whole-file shards
567
+ sequentially. A file is never split across shards; the first failure or
568
+ cancellation stops the sequence. **Completed sharded execution is not a
569
+ global review**: there is no aggregation call, no cross-shard analysis, and
570
+ no global approval — the CLI prints `global verdict: unavailable_for_sharded`.
571
+ Partial errors carry completed shard verdicts only (never raw diff content).
572
+ `evidence + shard` and `shard + --stream` are rejected before any model call.
573
+
538
574
  The three diff sources are mutually exclusive: local Git (`triss review` or
539
575
  `--base`), a GitHub PR (`triss review <PR>`), or UTF-8 text piped to
540
576
  `triss review --stdin`. `--stdin` cannot be combined with a PR number or
@@ -599,8 +635,37 @@ triss coder run "add input validation to /signup" --isolate
599
635
  triss coder run "..." --engine crush # crush engine (isolates by default; restrict is opt-in)
600
636
  triss coder run "..." --engine crush --restrict # crush + CLI allowlist on top of the worktree
601
637
  triss coder clean # remove finished isolation worktrees
638
+ triss coder session list # list v2 sessions (per engine)
639
+ triss coder session clean <slug> --engine opencode # remove one inactive isolated session
640
+ triss coder result list # list retained result artifacts
641
+ triss coder state backup --project <path> # Section 15 rollback backup
642
+ triss coder state validate --project <path> --backup <dir>
602
643
  ```
603
644
 
645
+ Every `triss coder run` envelope (and the matching MCP tool) carries the
646
+ Release A contract fields: `session_slug` (explicit slug or an anonymous
647
+ generated one — never an implicit persistent conversation), `result_retention`
648
+ / `result_id` (`retained` only for isolated changed runs with enforced
649
+ result-store quota and a successful reservation), and `execution_capabilities`
650
+ (eight honest `enforced|best_effort|unavailable` values plus
651
+ `effective_isolation`). Non-isolated `files_changed` is `null`; the only
652
+ changes-expectation evidence is `run_files_changed`. Process completion is not
653
+ task satisfaction — use `--expect changes --isolate` and inspect `git status`
654
+ yourself. Unavailable OS sandbox/cleanup/lock/quota does not block a
655
+ non-isolated/best-effort run but provides none of those guarantees; explicit
656
+ or default isolation needs `--allow-best-effort-caller-worktree` (default
657
+ off) or fails before spawn with `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED`
658
+ (stable `err.code`; retry hint when the isolation mechanism is unavailable),
659
+ and unavailable credential isolation always blocks before spawn. With the
660
+ opt-in and only when the isolation mechanism itself is unavailable (no git
661
+ repository or worktree creation failure — slug/branch conflicts like
662
+ `already exists` still fail closed), the run downgrades to
663
+ `best_effort_caller_worktree`: stderr and envelope `warnings` carry
664
+ `TRISS_CODER_ISOLATION_DOWNGRADED` and `effective_isolation` becomes
665
+ `best_effort_caller_worktree` (advisory-only, `files_changed` is `null`,
666
+ edits may reach the caller worktree). Full details:
667
+ `docs/reliable-delegation-release-a.md`.
668
+
604
669
  `triss coder init` first asks which provider to configure — **Z.AI GLM**
605
670
  (default), the existing **Triss worker** (`--provider worker`, aliases
606
671
  `openai` / `openai-compatible`), **OpenCode Zen** (`--provider opencode-zen`, free rotating
package/bin/triss.js CHANGED
@@ -40,8 +40,19 @@ import {
40
40
  runEdit,
41
41
  runUnset,
42
42
  } from '../src/commands/config.js';
43
- import { runCoderInit, runCoderRun, runCoderClean } from '../src/commands/coder.js';
43
+ import {
44
+ runCoderInit,
45
+ runCoderRun,
46
+ runCoderClean,
47
+ runCoderSessionList,
48
+ runCoderSessionClean,
49
+ runCoderStateAdopt,
50
+ runCoderStateReset,
51
+ runCoderResultList,
52
+ runCoderResultClean,
53
+ } from '../src/commands/coder.js';
44
54
  import { runCoderModels, runCoderModelSet, runCoderModelRollback } from '../src/commands/coder-models.js';
55
+ import { runCoderStateBackup, runCoderStateValidate } from '../src/commands/coder-state-backup.js';
45
56
  import { loadIntegrations } from '../src/integrations/_registry.js';
46
57
  import { withCall } from '../src/call-context.js';
47
58
  import { positiveIntegerOption, positiveNumberOption } from '../src/option-validation.js';
@@ -191,6 +202,7 @@ program
191
202
  .option('--small-model <p/m>', 'forward coder small model')
192
203
  .option('--isolate', 'forward coder isolation')
193
204
  .option('--no-isolate', 'disable coder isolation')
205
+ .option('--allow-best-effort-caller-worktree', 'forward coder isolation downgrade')
194
206
  .option('--restrict', 'forward coder restriction')
195
207
  .option('--no-restrict', 'disable coder restriction')
196
208
  .option('--cwd <path>', 'forward coder working directory')
@@ -214,6 +226,8 @@ program
214
226
  .option('-b, --base <branch>', 'compare against this branch (default: auto-detect origin/HEAD or main/master/develop)')
215
227
  .option('--skip-issue', "don't try to look up a Jira/Linear ticket from the branch/PR title")
216
228
  .option('--stdin', 'read an explicitly piped UTF-8 diff instead of Git or PR sources')
229
+ .option('--files <paths...>', 'literal path selectors: review ONLY these files (repeatable; renames select both sides)')
230
+ .option('--issue <key>', 'explicit linked-issue key (e.g. PROJ-123); PR prose never triggers tracker access')
217
231
  .option('-q, --question <text>', 'override the default review question')
218
232
  .option('--provider <name>', 'inference provider: worker (default), deepseek (alias), glm, or kimi (alias: moonshot)')
219
233
  .option('-m, --model <name>', 'model preset (flash | pro) or full model id (default: pro)')
@@ -221,6 +235,7 @@ program
221
235
  .option('--format <format>', 'response format: text (default) or evidence')
222
236
  .option('--stream', 'force streaming even when stdout is not a TTY')
223
237
  .option('--no-stream', 'disable streaming output (default streams when stdout is a TTY)')
238
+ .option('--payload-mode <mode>', 'review payload mode: single (default) or shard (sequential whole-file shards; no global verdict)')
224
239
  .action((pr, opts) => wrap(runReview)(pr, opts));
225
240
 
226
241
  program
@@ -353,6 +368,7 @@ coder
353
368
  .option('--no-restrict', 'crush only: disable restrict (crush auto-approves every tool — the default)')
354
369
  .option('--cwd <path>', 'working directory (ignored with --isolate)')
355
370
  .option('--timeout <sec>', 'kill the engine after this many seconds', parsePositiveNumber, 900)
371
+ .option('--allow-best-effort-caller-worktree', 'allow downgrade to caller worktree when isolated isolation cannot be enforced (default off — fails before spawn without it)')
356
372
  .option('--stdin', 'read the prompt from piped stdin instead of the [prompt] argument')
357
373
  .option('--json', 'no-op — the envelope is always JSON; kept for symmetry with other commands')
358
374
  .action((prompt, opts) => wrap(runCoderRun)(prompt, opts));
@@ -408,6 +424,72 @@ coderModel
408
424
  .option('-l, --local', 'restore to the project scope (./opencode.json or ./.crush/crush.json)')
409
425
  .action((opts) => wrap(runCoderModelRollback)(opts.from, opts));
410
426
 
427
+ // `coder state` is a command GROUP whose leaves are `backup` and `validate`
428
+ // (Section 15 rollback contract).
429
+ const coderState = coder
430
+ .command('state')
431
+ .description('Back up or validate the v2 coder state of a project (rollback contract)');
432
+
433
+ coderState
434
+ .command('backup')
435
+ .description('Create a bounded rollback backup of the v2 coder state (both engine session stores + coder-state-v2)')
436
+ .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
437
+ .option('--backup <path>', 'backup destination directory (default: <project>/.triss/backups/<timestamp>)')
438
+ .option('--json', 'print the stable machine-readable result (no secrets)')
439
+ .action((opts) => wrap(runCoderStateBackup)(opts));
440
+
441
+ coderState
442
+ .command('validate')
443
+ .description('Validate a rollback backup: manifest schema, completion marker hash, per-entry verification')
444
+ .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
445
+ .requiredOption('--backup <basename>', 'backup directory to validate')
446
+ .option('--json', 'print the stable machine-readable result (no secrets)')
447
+ .action((opts) => wrap(runCoderStateValidate)(opts));
448
+
449
+ coderState
450
+ .command('adopt')
451
+ .description('Adopt owned v2 state under a NEW project id: quarantine the old id, rewrite validated owner records')
452
+ .requiredOption('--from-project-id <32hex>', 'the old project id (32 lowercase hex) to quarantine')
453
+ .action((opts) => wrap(runCoderStateAdopt)(opts));
454
+
455
+ coderState
456
+ .command('reset')
457
+ .description('Quarantine all validated local v2 state and create an empty identity (never deletes it)')
458
+ .requiredOption('--project <absolute-path>', 'absolute path of the validated project root')
459
+ .action((opts) => wrap(runCoderStateReset)(opts));
460
+
461
+ // `coder session` group (v2 session CLI contract, Atomic 23).
462
+ const coderSession = coder
463
+ .command('session')
464
+ .description('List or clean v2 isolated sessions (per-engine store; legacy .triss/sessions.json is never touched)');
465
+
466
+ coderSession
467
+ .command('list')
468
+ .description('Serialize the bounded v2 session inventory projection to stdout')
469
+ .option('--engine <name>', 'coding engine: opencode (default) or crush')
470
+ .action((opts) => wrap(runCoderSessionList)(opts));
471
+
472
+ coderSession
473
+ .command('clean <slug>')
474
+ .description('Remove a selected inactive v2 isolated session/workspace transaction')
475
+ .requiredOption('--engine <name>', 'coding engine: opencode or crush (MANDATORY)')
476
+ .action((slug, opts) => wrap(runCoderSessionClean)(slug, opts));
477
+
478
+ // `coder result` group (retained-result CLI, Atomic 23).
479
+ const coderResult = coder
480
+ .command('result')
481
+ .description('List or clean retained result artifacts (never persistent sessions)');
482
+
483
+ coderResult
484
+ .command('list')
485
+ .description('Serialize the bounded retained-result projection to stdout')
486
+ .action((opts) => wrap(runCoderResultList)(opts));
487
+
488
+ coderResult
489
+ .command('clean <run-id>')
490
+ .description('Remove only a validated retained result artifact (run-<32 lowercase hex>)')
491
+ .action((runId, opts) => wrap(runCoderResultClean)(runId, opts));
492
+
411
493
  function wrap(fn) {
412
494
  return async (...args) => {
413
495
  try {
@@ -124,3 +124,17 @@ RED tests must establish:
124
124
  Acceptance requires focused tests, the full Node test/lint suite, package
125
125
  smoke, a live synthetic worker run from a GLM-persisted temporary project, and
126
126
  sequential GLM 5.2 plus independent agent reviews.
127
+
128
+ ## Current credential-proxy limitation (2026-08)
129
+
130
+ The parent-owned credential proxy pins the upstream ORIGIN plus a path prefix
131
+ per provider. For opencode built-in providers without a documented base-URL
132
+ override (`moonshot`, `kimi-for-coding`), the engine cannot be verifiably
133
+ pointed at the proxy, so `triss coder run` fails closed BEFORE spawn instead
134
+ of handing the real upstream a one-run proxy token it would reject. `zai`
135
+ (ZAI_BASE_URL/ZHIPU_BASEURL), `opencode-zen/go` (OPENCODE_BASE_URL), the
136
+ managed `triss-worker` overlay, and every crush run keep working. Direct
137
+ non-coder calls (`triss ask/review/chat --provider kimi|moonshot`) are
138
+ unaffected — they never spawn an engine. Lifting the limitation requires an
139
+ audited provider overlay (the same mechanism the worker block uses) for these
140
+ providers.
@@ -273,7 +273,20 @@ self-hosted endpoints).
273
273
  | `TRISS_CODER_ENGINE` | no | `opencode` | Coding engine: `opencode` (default), `opencode2` (beta — see [opencode2.md](./opencode2.md)), or `crush` |
274
274
  | `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) |
275
275
  | `TRISS_CODER_CRUSH_VERSION` | no | `0.1.6` | Pin override for the `@phpcraftdream/crush` npm install (crush engine) |
276
- | `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) |
276
+ | `TRISS_CODER_SESSION_CAP` | no | `4` | Persistent v2 session inventory cap per engine (fail closed) |
277
+
278
+ ### Review limits (Release B)
279
+
280
+ All four limits are reloadable at runtime; values are independently clamped
281
+ to their hard maxima, and any contradiction (e.g. `shard_max > single_max`)
282
+ falls back to the complete default set — never a partial application.
283
+
284
+ | Variable | Default | Hard max | Notes |
285
+ | ------------------------------- | ------------------ | --------------- | ----------------------------------------- |
286
+ | `TRISS_REVIEW_SINGLE_MAX_BYTES` | `262144` (256 KiB) | `1048576` (1 MiB) | Single-request payload bound (metadata + question + diff) |
287
+ | `TRISS_REVIEW_SHARD_MAX_BYTES` | `98304` (96 KiB) | `262144` (256 KiB) | Per-shard payload bound (sharding not yet available) |
288
+ | `TRISS_REVIEW_TOTAL_MAX_BYTES` | `4194304` (4 MiB) | `16777216` (16 MiB) | Total corpus bound; also the stdin acquisition cap |
289
+ | `TRISS_REVIEW_MAX_SHARDS` | `64` | `256` | Shard-count bound (sharding not yet available) |
277
290
 
278
291
  `triss coder init` auto-detects which Z.AI endpoint `ZHIPU_API_KEY`
279
292
  actually authenticates against — the `zai-coding-plan` (subscription)
package/docs/mcp.md CHANGED
@@ -348,11 +348,21 @@ the default), `OPENCODE_API_KEY` (OpenCode Zen or paid OpenCode Go — see
348
348
  agent (default `opencode` engine; `engine: "crush"` selects the crush
349
349
  engine). Same options as `triss coder run` on the CLI (`engine`,
350
350
  `session`, `continue`, `agent`, `provider`, `model`, `small_model`,
351
- `isolate`, `cwd`, `timeout`)
351
+ `isolate`, `cwd`, `timeout`) plus `allowBestEffortCallerWorktree`
352
+ (boolean, default FALSE — the only MCP consent to an isolation
353
+ downgrade when isolation was requested/effective but the enforced
354
+ sandbox is unavailable; without it such a run fails before spawn with
355
+ `TRISS_CODER_ISOLATION_ENFORCEMENT_REQUIRED` — downgrade produces
356
+ `TRISS_CODER_ISOLATION_DOWNGRADED` in stderr and envelope `warnings`,
357
+ `effective_isolation: best_effort_caller_worktree`, advisory-only
358
+ `files_changed: null`/`worktree: null`, edits may reach the caller
359
+ worktree; user-remediable slug/branch conflicts containing
360
+ `already exists` still fail closed even with the opt-in)
352
361
  minus `--stdin`, which is meaningless over MCP (the prompt is a normal
353
362
  tool argument). Returns the JSON envelope — `engine`, `engine_version`,
354
- `session_id`, `exit_reason`, `final_text`, `files_changed`, `diff_stat`,
355
- `worktree`, `usage`, `warnings` — as the tool result. `engine` is the
363
+ `session_id`, `session_slug`, `result_retention`, `result_id`,
364
+ `execution_capabilities`, `exit_reason`, `final_text`, `files_changed`,
365
+ `diff_stat`, `worktree`, `usage`, `warnings` — as the tool result. `engine` is the
356
366
  `opencode`/`opencode2`/`crush` enum (default `opencode` V1, or
357
367
  `TRISS_CODER_ENGINE`; `opencode2` is the V2 beta — see
358
368
  [opencode2.md](opencode2.md));
@@ -383,6 +393,12 @@ the default), `OPENCODE_API_KEY` (OpenCode Zen or paid OpenCode Go — see
383
393
  (`TRISS_WORKER_API_KEY` / `ZHIPU_API_KEY` / `OPENCODE_API_KEY` / `MOONSHOT_API_KEY` /
384
394
  `KIMI_API_KEY` — never the value), and how many isolation
385
395
  worktrees are live.
396
+ - `triss_coder_result_list` — the bounded retained-result projection
397
+ (`run_id`, `engine`, `session_slug`, `published_at`, `state`). Never
398
+ lists persistent sessions.
399
+ - `triss_coder_result_clean` — remove ONLY a validated retained result
400
+ artifact by `run_id` (`run-<32 lowercase hex>`, enforced in the schema
401
+ and the handler). Never removes a persistent session selected by a slug.
386
402
 
387
403
  If an MCP client cancels or times out `triss_coder_run`, its cancellation signal
388
404
  is forwarded to the detached engine process group. Normal completion also
@@ -1628,7 +1628,19 @@ proxy alone receives the real provider credential through a non-inherited
1628
1628
  in-memory value. Because the pinned engines accept credentials only through
1629
1629
  their ordinary environment/config channels, the engine receives a random
1630
1630
  single-run proxy token in the expected API-key variable plus a loopback base URL
1631
- and provider/model routing facts. Tool subprocesses may observe this ephemeral
1631
+ and provider/model routing facts. The proxy's `endpoint` is always the upstream
1632
+ ORIGIN (`https://host[:port]`, no path); the engine's base URL is the loopback
1633
+ origin plus the pinned path prefix (`scopedBaseUrl`), and forwarding is a plain
1634
+ origin+path join, so the provider prefix can never be doubled. Anthropic-protocol
1635
+ upstreams (Kimi for Coding) authenticate with `x-api-key` plus
1636
+ `anthropic-version`, never a Bearer token, and their one-run token is likewise
1637
+ accepted from `x-api-key`. Every forwarded JSON body must name exactly the
1638
+ pinned model; the pinned prefix matches boundary-exactly (`/v1` never accepts
1639
+ `/v10`); upstream responses are relayed under a hard byte cap; revocation aborts
1640
+ every in-flight upstream fetch. Providers whose engine channel cannot be
1641
+ verifiably pinned to the proxy (no documented base-URL override) fail closed
1642
+ BEFORE spawn rather than handing the real upstream a one-run proxy token it
1643
+ would reject. Tool subprocesses may observe this ephemeral
1632
1644
  token; this is accepted in v1 because it cannot reveal the real provider key or
1633
1645
  reach any endpoint except the local run-scoped proxy. The token is accepted only
1634
1646
  for one run/model/provider, has request-count, byte, rate, and deadline caps no
@@ -1652,8 +1664,11 @@ memory/environment, and IPC to unrelated processes are absent or denied. This
1652
1664
  full filesystem/network/process denial is an enforced-sandbox claim only. In
1653
1665
  best-effort mode, the engine may access other same-user filesystem locations or
1654
1666
  network routes that the host cannot confine; the sole mandatory protection is
1655
- the separately enforced credential-isolation launcher, which must deny raw
1656
- provider stores and parent-process access before spawn.
1667
+ the separately required credential-isolation launcher (the loopback token
1668
+ proxy). Until an OS-enforced backend denies raw provider stores to the same-UID
1669
+ child, `execution_capabilities.credential_isolation` reports `best_effort` when
1670
+ the proxy is active and `unavailable` otherwise — never `enforced` — and the
1671
+ run-path preflight rejects any run without an active proxy.
1657
1672
 
1658
1673
  Compile an enforced-sandbox allowlist only from a host-owned toolchain manifest discovered and
1659
1674
  approved by Package 0, never by scanning `PATH` inside the sandbox. The
@@ -2270,10 +2285,15 @@ object, and `payload_mode`. Stdin rejects file selectors because the caller owns
2270
2285
  its acquisition boundary.
2271
2286
 
2272
2287
  Selectors are exact decoded repository-relative paths, never pathspecs or
2273
- globs. Reject empty values, NUL, invalid UTF-8, absolute paths, and `.` or `..`
2274
- components. Leading dashes, glob characters, and pathspec-magic-looking text
2275
- remain literal filename bytes. Pass selected paths only after `--` as argument
2276
- array entries `:(literal)<path>`; never interpolate them into a shell command.
2288
+ globs. Reject empty values, NUL, invalid UTF-8, absolute paths, `..`
2289
+ components, leading `:` pathspec magic, and glob/escape metacharacters
2290
+ (`*`, `?`, `[`, `\`) — a selector that Git could reinterpret as a pattern
2291
+ would silently change the reviewed scope. Pass selected paths only after `--`
2292
+ as argument array entries; never interpolate them into a shell command.
2293
+ A selector set that matches NOTHING fails closed with
2294
+ `TRISS_REVIEW_SCOPE_EMPTY` (exit 2) BEFORE any model call; a model verdict
2295
+ over an empty scope is never produced. Partial matches proceed with honest
2296
+ partial coverage surfaced to the caller.
2277
2297
 
2278
2298
  Selection is inventory-first:
2279
2299
 
@@ -2805,7 +2825,16 @@ completed calls, and `usage_status: missing` for failed calls.
2805
2825
  - Triss cannot override an upstream policy rejection;
2806
2826
  - generic lock files do not expose a universal health-check contract;
2807
2827
  - regex classification of `EPERM`, `EACCES`, or lock text is a diagnostic hint,
2808
- not proof of the root cause.
2828
+ not proof of the root cause;
2829
+ - a loopback token proxy alone is NOT OS-enforced credential isolation: the
2830
+ same-UID engine child can still read raw credential stores, so
2831
+ `credential_isolation` must never be reported as `enforced` until a reviewed
2832
+ platform backend actually denies those reads — and until then, a run is
2833
+ REFUSED before spawn whenever a raw store (project/global `.triss.env`) is
2834
+ readable, unless the operator explicitly acknowledges the best-effort scope
2835
+ with `TRISS_CODER_ALLOW_BEST_EFFORT_ISOLATION=1`;
2836
+ - a scoped review whose selectors matched nothing is NOT a clean verdict: it is
2837
+ `TRISS_REVIEW_SCOPE_EMPTY`, exit 2, before any provider call.
2809
2838
 
2810
2839
  Add only bounded categories to the envelope:
2811
2840