triss-coworker 0.22.4 → 0.24.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] — 2026-07-10
+
+### Added
+
+- **OpenCode Zen provider for `triss coder`.** The default `opencode` engine
+  is no longer limited to Z.AI GLM — it can run any model served by
+  [OpenCode Zen](https://opencode.ai/docs/zen/) (`opencode/<id>`, e.g. the free
+  `opencode/hy3-free` / Tencent Hunyuan 3) by authenticating with a new
+  `OPENCODE_API_KEY`. Credentials are provider-scoped: a run forwards **only**
+  the key its model needs, so a Zen-only machine needs no `ZHIPU_API_KEY`. Z.AI
+  GLM stays the default provider; `crush` remains Z.AI-only. (#12)
+- `triss coder init --provider opencode-zen` — guided Zen setup: prompts for
+  `OPENCODE_API_KEY`, resolves the model against the **live Zen catalogue**
+  (`GET /zen/v1/models`, first-available from a free-model priority list), writes
+  `opencode.json` (deny-first bash policy + agent templates), and pins the chosen
+  model into `TRISS_CODER_MODEL` so a bare `triss coder run` works. Provider is
+  auto-inferred from a preset/single credential when the flag is omitted. (#12)
+- `OPENCODE_API_KEY` is a first-class, optional, masked secret on the coder
+  manifest — surfaced in `triss status`, the `config` wizard, and the MCP coder
+  tools (which now light up on `ZHIPU_API_KEY` **or** `OPENCODE_API_KEY`). (#12)
+- `--allow-unsafe-bash` on `triss coder init` — explicit opt-in to proceed when
+  an existing `opencode.json` has no deny-first bash policy. (#12)
+- New `docs/opencode-zen.md` deep-dive (auth, live catalogue, precedence, setup
+  gates, privacy, MCP, verification). (#12)
+
+### Changed
+
+- `triss coder init` / `config wizard coder` now **fail (non-zero)** instead of
+  reporting a misleading success on an unrunnable setup: a missing provider key,
+  a pin shadowed by a shell export or higher-precedence `.env`, or an
+  existing/cross-scope `opencode.json` that is unsafe (no deny-first policy) or
+  unusable (a `small_model` that is cross-provider, cross-plan, or no longer in
+  the live catalogue). Config and templates are still written, so fixing the
+  cause and re-running is a clean idempotent completion. (#12)
+
+### Security
+
+- Resolved 8 CodeQL code-scanning alerts (input validation and safe handling in
+  `completion.js`, `_contract.js`, `handlers.js`, `secrets.js`, and hardened the
+  `publish` / `test` GitHub workflows).
+- Rewrote `stripHtml` as a state machine and removed HTML-entity decoding to
+  eliminate a double-unescape flagged by CodeQL.
+
+## [0.23.0] — 2026-07-07
+
+### Added
+
+- **Second GLM coding engine: `crush`** (`@phpcraftdream/crush`, pinned
+  `0.1.3`), selectable per run with `triss coder run --engine crush` or
+  globally with `TRISS_CODER_ENGINE=crush`; set up via
+  `triss coder init --engine crush`. Compared to the default opencode
+  engine it emits one JSON envelope (no ndjson fold), uses native
+  get-or-create session ids (no `.triss/sessions.json` map), reports a real
+  per-call `delta_cost_usd`, and exposes `--role smart|fast`. Both engines
+  share the single `ZHIPU_API_KEY` (crush reads it natively on ≥0.1.1, with
+  a `ZAI_API_KEY` compatibility alias). (#10)
+- `--restrict` / `--no-restrict` on `triss coder run`, plus the
+  `TRISS_CODER_CRUSH_RESTRICT` env var, to opt into a crush command
+  allowlist. When on, triss emits the read-only allowlist as CLI flags
+  (`--allow-bash` / `--allow-tool`); it is **opt-in** (default off) because
+  a denied bash command currently deadlocks crush until the timeout. (#10)
+- `TRISS_CODER_CRUSH_VERSION` to pin a specific `@phpcraftdream/crush`
+  npm version. (#10)
+- New `docs/glm-clients.md` — a single reference for how Triss talks to
+  GLM (both engines, key/endpoint routing, model selection, usage modes,
+  and the safety model), and `docs/crush-issues.md` /
+  `docs/crush-restrict-issues.md` capturing the crush maintainer bug
+  reports. (#10)
+
+### Changed
+
+- `triss coder run --engine crush` isolates by default (a disposable
+  `.triss/wt/<slug>` worktree); pass `--no-isolate` to opt out. crush's
+  own `crush.json` `permissions.run` config is not yet honored upstream and
+  a denied command deadlocks, so the worktree is crush's reliable safety
+  layer. opencode is unchanged (isolate off; its `opencode.json` bash
+  allowlist is enforced). (#10)
+
 ## [0.22.4] — 2026-07-04
 
 ### Fixed

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 `ZHIPU_API_KEY` is set
-  (setup: `triss coder init`). `triss_coder_run`'s timeout defaults to
+  (setup: `triss coder init`). `triss_coder_run` takes an optional `engine`
+  (`opencode` default, or `crush`); its timeout defaults to
   1500s (25 min) over MCP, above the CLI's 900s, since GLM 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.
@@ -268,8 +269,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 GLM coding agent (opencode engine): key, `opencode.json`, agent templates | Manually installing/configuring opencode |
-| `triss coder run` | Spawns the GLM coding agent and prints one JSON envelope (`--isolate` for a disposable worktree). **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 (Z.AI GLM, or `--provider opencode-zen` for free OpenCode Zen models like `hy3`), `opencode.json` / crush models + `permissions.run` policy, 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 GLM coding agent 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 |
@@ -430,27 +431,80 @@ default timeout, configurable via `--timeout <ms>`.
 ### `triss coder`
 
 Delegates an implementation task to a GLM coding agent (the `opencode`
-engine) instead of the primary model writing the code itself.
+engine by default; `crush` is an alternative — see **Engines** below)
+instead of the primary model writing the code itself.
 
 ```bash
 triss coder init                                  # once: key, opencode.json, agent templates
 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 init` probes which Z.AI plan your key actually works with
-(subscription vs. pay-as-you-go) and writes the matching model prefix, and
-lets you pick the GLM model interactively instead of always defaulting to
-`glm-5.2`.
+`triss coder init` first asks which provider to configure — **Z.AI GLM**
+(default) or **OpenCode Zen** (`--provider opencode-zen`, free models incl.
+Hunyuan `hy3`). For Z.AI it probes which plan your key works with (subscription
+vs. pay-as-you-go) and writes the matching model prefix; for Zen it saves an
+`OPENCODE_API_KEY` and writes an `opencode/<id>` model. Either way it lets you
+pick the model interactively. See the **Providers** section below and
+[docs/opencode-zen.md](docs/opencode-zen.md) for the OpenCode Zen deep‑dive.
 
 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
 conversation across calls. **POSIX only** (macOS/Linux) for now. See
-`docs/configuration.md` for the coder env vars and `docs/mcp.md` for the
+`docs/glm-clients.md` for the full picture of how Triss talks to GLM
+(both engines, key/endpoint routing, models, and every usage mode),
+`docs/configuration.md` for the coder env vars, and `docs/mcp.md` for the
 MCP tool equivalents.
 
+**Engines** — `opencode` (default) enforces a deny-first bash allowlist
+(`opencode.json`) that actually works — prefer it when you want that safety
+layer baked in. `crush` (`--engine crush` / `TRISS_CODER_ENGINE=crush`, npm
+`@phpcraftdream/crush` ≥0.1.3) has a **weaker, interim** safety story: live
+testing proved crush 0.1.3 **ignores** its `permissions.run` config block and
+a denied bash command **deadlocks to the timeout**. So triss ships crush with
+isolate-**ON** by default (the disposable worktree is the reliable safety
+layer) and makes restrict **opt-in** (default OFF). `triss coder init` still
+seeds a `permissions.run` block into crush.json as forward-compat (harmless,
+correct once upstream honors it), but the working allowlist today is the CLI
+flags: when you pass `--restrict` (or `TRISS_CODER_CRUSH_RESTRICT=1`), `triss
+coder run` emits `--restrict-run` plus `--allow-bash`/`--allow-tool` flags for
+each entry. Override per-run with `--restrict` / `--no-restrict` (resolution:
+CLI flag > env > crush.json `permissions.run.restrict` > default OFF). For
+Z.AI GLM, both engines share the single `ZHIPU_API_KEY` (crush ≥0.1.1 reads it
+natively; triss also forwards it as `ZAI_API_KEY` for older binaries; see
+**Providers** below for the opencode-only OpenCode Zen alternative). 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
+`zai/*` (GLM) use `ZHIPU_API_KEY`, while `opencode/*` models — served free by
+[OpenCode Zen](https://opencode.ai/docs/zen/), e.g. **`opencode/hy3-free`**
+(Tencent Hunyuan 3) — use `OPENCODE_API_KEY`. To point coder at a Zen model:
+
+```bash
+triss coder init --provider opencode-zen         # guided: key + opencode.json
+# …or by hand:
+triss config set OPENCODE_API_KEY <key>          # or add it to .triss.env
+export TRISS_CODER_MODEL=opencode/hy3-free        # default it for every run
+export TRISS_CODER_SMALL_MODEL=opencode/hy3-free
+triss coder run "add input validation to /signup"
+# …or per-run, without changing the default:
+triss coder run "..." --model opencode/hy3-free
+```
+
+`triss coder run` passes the resolved model to opencode with `--model` and
+forwards only the key that model needs, so a Zen run works with
+`OPENCODE_API_KEY` alone — no Z.AI key required. The deny-first `opencode.json`
+bash policy applies to Zen runs too. Any Zen model id works via
+`TRISS_CODER_MODEL=opencode/<id>` / `--model`, not just the free ones the
+picker lists. (The `crush` engine speaks Z.AI only.) Full details, the model
+catalogue, and every configuration path are in
+[docs/opencode-zen.md](docs/opencode-zen.md).
+
 If your Z.AI plan hits its usage limit, `triss coder run` fails fast with
 the reset time converted to your local timezone (Z.AI reports it in
 Beijing time), instead of hanging until `--timeout`. Under the hood

package/bin/triss.js

@@ -223,23 +223,30 @@ config
 
 const coder = program
   .command('coder')
-  .description('Run a GLM coding agent (opencode engine)');
+  .description('Run a GLM coding agent (opencode or crush engine)');
 
 coder
   .command('init')
-  .description('Install/configure the opencode engine, Z.AI key, permission policy, and agent templates')
+  .description('Install/configure a coding engine (opencode default, 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('--provider <name>', 'opencode engine model provider: zai (Z.AI GLM, default) or opencode-zen (free models incl. hy3)')
+  .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 GLM coding agent (opencode engine) and print a JSON envelope to stdout')
+  .description('Spawn a GLM coding agent (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('--model <p/m>', 'override the model for this run only')
   .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)')
+  .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', (v) => parseInt(v, 10), 900)
   .option('--stdin', 'read the prompt from piped stdin instead of the [prompt] argument')

package/docs/coder-agent-plan.md

@@ -616,3 +616,314 @@ reuse, 2 safety-layer denial checks, 2 `--dir`/global-config checks, plus
 retries) against the `zai-coding-plan` endpoint, all subscription-covered.
 One `zai` (non-coding-plan) call was attempted and failed before any
 tokens were billed (`isRetryable` error prior to a completion).
+
+## Phase 6 recon (crush fork — 2026-07-05)
+
+The prereq is unblocked: the fork publishes **`@phpcraftdream/crush`** on
+npm (`0.1.0`, FSL-1.1-MIT, bin `crush`, node ≥18, Go-free prebuilt binary
+via per-platform optionalDependencies). Live recon of that binary
+(`v0.0.0-20260704…+dirty`) in a scratch dir against the existing
+`ZHIPU_API_KEY` — the fork's `crush run` **diverges substantially from
+this plan's Phase 6 assumptions**. Corrections, all verified live:
+
+- **Provider / key var mismatch.** crush ships Z.AI as a built-in Catwalk
+  provider `zai` (`type: openai-compat`, endpoint
+  `https://api.z.ai/api/coding/paas/v4` — same coding-plan endpoint as
+  opencode), models `glm-5.2 / glm-5.1 / glm-5-turbo / glm-4.7 / …`. But
+  it reads **`ZAI_API_KEY`**, NOT `ZHIPU_API_KEY`. Adapter must bridge
+  this: simplest is to map the value into `ZAI_API_KEY` inside crush's
+  spawn-env allowlist so triss keeps a single user-facing `ZHIPU_API_KEY`.
+  Confirmed working: `crush ping` → `zai / glm-5.2 … status: ok`; a
+  `crush run --role smart --json` returned a clean `end_turn` envelope.
+- **Single JSON envelope (no ndjson fold).** `crush run --json` prints ONE
+  object to stdout at end-of-run:
+  `{session_id, exit_reason, final_text, assistant_notes?, tool_calls,
+   usage:{delta_tokens, delta_cost_usd}, duration_ms, error}`. `exit_reason`
+  vocabulary: `end_turn | done | canceled | timeout | max_cost |
+  max_tokens | error`. Tool-call heartbeat still goes to stderr as
+  `▶ <toolName>`. So the crush adapter's `foldOutput` is a trivial
+  parse-last-line, not a streaming fold. **cost is real here**
+  (`delta_cost_usd: 0.000048` observed) — unlike opencode's coding-plan
+  cost:0. Usage is a combined `delta_tokens`, NOT split prompt/completion.
+- **Native sessions — no slug→id map needed.** `crush run --session <id>`
+  is genuine get-or-create with a **caller-supplied arbitrary id** (docs:
+  "an arbitrary new id to start a fresh session with that exact id — handy
+  for CI"). So for crush, pass triss's own slug straight through; the
+  `.triss/sessions.json` mapping (an opencode-only workaround) is
+  unnecessary. Adapter flag e.g. `needsSessionMap: false`.
+- **`--role` is REQUIRED.** Every `crush run` must declare `--role
+  smart|large` (big model) or `--role fast|small` (cheap). `--model
+  <provider/model[@level]>` overrides per invocation. Default large model
+  resolved from `crush models use <large> <small>` (atoms `glm5_2`,
+  `glm5_turbo`) written to `crush.json` (global
+  `~/.local/share/crush/crush.json`, local `./.crush/crush.json`).
+- **SAFETY MODEL IS WEAKER — the headline caveat.** This confirms Phase 6
+  note 3, but stronger: `crush run` is non-interactive and
+  **auto-approves EVERY permission request; the agent gets the full tool
+  set with no prompting** and there is **no bash command-pattern
+  allowlist** like opencode's deny-first `opencode.json`. crush's own
+  `run --help` warns runs are "fast but irreversible — only run in a
+  workspace you can afford to lose." Mitigations available, all must be
+  applied by triss for crush: (a) force/strongly-default `--isolate`
+  (disposable git worktree) for crush; (b) `CRUSH_FORBID_WRITES=<paths>`
+  env blocks write/edit tools from named paths; (c) `--agents single`
+  (default) disables sub-agent fan-out/recursion; (d) `--max-cost` /
+  `--max-tokens` runaway caps. There is NO way to reproduce opencode's
+  per-command bash allowlist — document this trade-off prominently
+  (agent can't be given a curated safe-command list; it's all-or-nothing
+  inside the sandbox).
+- **stdin IS accepted** (unlike opencode): prompt = `<stdin>\n\n<args>`.
+- **Extra levers worth surfacing in the adapter/docs:** `--timeout`
+  (accepts `900`/`900s`/`15m`; preserves partial answer in envelope),
+  `--on-finish "cmd"` (sets `CRUSH_SESSION_ID`/`CRUSH_EXIT_REASON`/…),
+  `crush sessions cancel <id>` for external cancellation, `--format json`
+  post-processing that strips code fences from `final_text`.
+
+Net: the crush adapter is in most respects SIMPLER than opencode
+(single-envelope parse, native sessions, no template-shape guessing) but
+its **safety story is the one place it is worse** and must not be papered
+over. The engine-abstraction shape in Phase 6 step 1 still holds; the
+`configTemplate` member becomes a `crush.json` + `crush models use`
+writer, and a new adapter member is needed for the spawn-env key bridge
+(`ZHIPU_API_KEY` → `ZAI_API_KEY`) and the crush-only safety env
+(`CRUSH_FORBID_WRITES`).
+
+## Phase 6 re-eval (crush 0.1.3 — 2026-07-06)
+
+The fork maintainer shipped three releases (0.1.1 → 0.1.3, all 2026-07-05)
+in direct response to `docs/crush-issues.md`. Re-verified every one of the
+seven reported issues live on `0.1.3` (real `ZHIPU_API_KEY`, live Z.AI
+coding-plan endpoint). Scorecard:
+
+| # | Sev | Issue | Status | Evidence (0.1.3) |
+|---|-----|-------|--------|------------------|
+| 1 | High | `--version` = `v0.0.0…+dirty` | ✅ fixed | reports clean `v0.1.3` |
+| 2 | High | `zai` reads only `ZAI_API_KEY` | ✅ fixed | with only `ZHIPU_API_KEY` set (`ZAI_API_KEY` unset), `zai` hit the network and returned 401 → key read natively |
+| 3 | Med | `--role fast` (glm-5-turbo) hung to timeout | ✅ fixed | original repro (`crush run --role fast --model zai/glm-5-turbo`) → `exit_reason:end_turn`, `final_text:"PONG"` in 47s |
+| 4 | Med | no allowlist, everything auto-approved | ✅ fixed | `--restrict-run` + `--allow-bash` (forms: prefix / `exact:` / `glob:` / `regex:`, chaining-guarded) + `--allow-tool` + config `permissions.run.{restrict,allow_bash,allow_tools}`; CLI merges with config |
+| 5 | Med | `models list` does network + disk writes | ✅ fixed | default reads cache/embedded, no network, no writes; `--refresh` is opt-in |
+| 6 | Low | `ping` rejects `--role` | ✅ fixed | `ping --role smart\|fast` + dedicated `ping-fast` |
+| 7 | Low | startup WARN noise on stderr | 🟡 mostly | old git-repo / Apple-Terminal warnings gone; stderr is clean once models are configured; one WARN remains only on misconfig (large-as-small fallback for `local-cli`) |
+
+**6/7 fully fixed, 1 (low) mostly. Every High and Medium is resolved.**
+Issue #4 was closed exactly as suggested (command-pattern allowlist honored
+by `crush run`), and better — CLI flags merge with `crush.json`.
+
+Bonus levers added (not requested), worth surfacing later: `--effort
+low|medium|high`, `--on-finish` hook (`CRUSH_SESSION_ID/EXIT_REASON/COST_USD/
+TOKENS/DURATION_SEC`), watchdog `--timeout-extends-on-progress` +
+`--timeout-hard-cap`, `--small-model`, `--format json-schema:<file>`,
+`--aggregation attach|concat` for sub-agent fan-out + reduction-loss
+warning, per-session budget persistence, default `--timeout` now 60m.
+
+The `exit_reason` vocabulary is unchanged (`done | canceled | timeout |
+max_cost | max_tokens | error`, plus `end_turn`) → `mapCrushExitReason`
+already covers all of them; **no mapper change needed.**
+
+### What to do now (adapter work — implement via GLM, Claude reviews)
+
+Assignee: GLM (`triss coder run --engine crush`). Reviewer: Claude.
+All changes are in `src/coder-engines/crush.js` + tests + docs. Ship on
+`feat/coder-crush-engine`.
+
+1. **Bump the pin + enforce the version.**
+   - `CRUSH_PIN_DEFAULT`: `0.1.0` → `0.1.3`.
+   - `detectCrush()` is presence-only today with a TODO "enforce pin once
+     crush --version reports clean semver." That precondition now holds
+     (`v0.1.3`). Parse the `vX.Y.Z` out of `crush --version` and return a
+     structured `{found, version, satisfiesPin}`; the caller warns (dim
+     stderr, non-fatal) on mismatch. Keep it non-fatal — a newer crush must
+     still run. Drop the two `TODO: enforce pin` comments.
+   - Test: feed a fake `sh` returning `crush version v0.1.3` and assert
+     parsed `version === '0.1.3'` / `satisfiesPin === true`; also a
+     `v0.2.0` (newer, still `found:true`) and a garbage string.
+
+2. **Retire / re-annotate the ZHIPU→ZAI env bridge.**
+   - crush now reads `ZHIPU_API_KEY` natively (issue #2), so the
+     `ZHIPU_API_KEY → ZAI_API_KEY` copy in `buildCrushSpawnEnv` is no longer
+     required. Decision: **keep it as belt-and-suspenders** (harmless, helps
+     anyone still on 0.1.0) BUT rewrite the "silently unconfigured zai
+     provider" comment — it is now false for 0.1.1+. New comment: crush
+     ≥0.1.1 reads `ZHIPU_API_KEY` directly; we still forward `ZAI_API_KEY`
+     as a compatibility alias for older binaries. Also forward
+     `ZHIPU_API_KEY` itself into the env allowlist so the native path works.
+   - Test: assert the spawn env contains BOTH `ZHIPU_API_KEY` and
+     `ZAI_API_KEY` when the base env has `ZHIPU_API_KEY`.
+
+3. **Adopt real restricted-run safety — DECISION: Variant A (parity with
+   opencode), restrict ON by default.** This closes the one gap we flagged.
+   The design mirrors opencode's deny-first `opencode.json`: persist the
+   policy in `crush.json`, do NOT inject the allowlist as per-run CLI flags.
+   Rationale: crush merges `permissions.run.allow_bash` from config with CLI
+   flags and honors `permissions.run.restrict:true` — so a config-seeded
+   policy travels into isolated worktrees and lets users add/remove/replace
+   commands by editing ONE file, exactly like `opencode.json`. Injecting via
+   CLI flags would let users only ADD, not remove our defaults.
+   - **Seed `permissions.run` into `crush.json` at init**
+     (`configureCrushModels` / the crush init path). `crush models use`
+     already writes `.crush/crush.json` (local) / `~/.local/share/crush/
+     crush.json` (global) with a `models` block and NO permissions — there
+     is no `crush config` CLI, so read-modify-write that JSON, merging the
+     `permissions.run` block into the existing object (never clobber the
+     `models` block). Write:
+     ```json
+     "permissions": { "run": {
+       "restrict": true,
+       "allow_bash": [ …shared read-only set… ],
+       "allow_tools": ["view"]
+     }}
+     ```
+   - **Shared allowlist constant.** Mirror the opencode adapter's trusted
+     set verbatim so both engines behave identically. opencode's is
+     `opencode.json` `permission.bash` (see coder.js ~L453): `git status`,
+     `git diff*`, `git log*`, `ls*`, `node --test*`, `npm test*`,
+     `npm run test*`, with `webfetch/websearch: deny`. Translate to crush
+     forms (`'git diff'` prefix, `'glob:ls *'`, `'glob:npm test *'`,
+     `'glob:node --test *'`, etc.) in ONE named constant so a bump is one
+     edit. crush's chaining-guard on prefix patterns is stricter than
+     opencode's glob — fine, keep it.
+   - **No-clobber, like opencode.** If the user already has a
+     `permissions.run` block in crush.json, do NOT overwrite it; if an
+     existing crush.json has no restrict policy, warn on stderr (dim), same
+     as the opencode "existing config lacks deny policy" warning path
+     (coder.js ~L503).
+   - **Flip crush's isolate default to OFF** to complete the parity. Today
+     `coder.js:1697` defaults crush isolate-ON because it had no allowlist;
+     under Variant A the config-seeded deny-first policy is the safety layer,
+     so crush should default isolate-OFF like opencode. Update that line AND
+     its comment. `--isolate` / `--no-isolate` tristate still wins.
+
+   **User override surface (precedence high → low) — document all four:**
+   1. Per-run CLI: add `--no-restrict` / `--restrict` tristate on `coder
+      run` in `bin/triss.js` (mirror the existing `--isolate` tristate — no
+      Commander default, undefined = "use env/config default"). `--no-restrict`
+      drops to auto-approve for one run; `--isolate` brings back the
+      disposable worktree for one run.
+   2. Env: `TRISS_CODER_CRUSH_RESTRICT=0` disables restrict by default
+      without touching config or flags. (Add to README + .env.example.)
+   3. Persistent: edit `crush.json` `permissions.run` — set
+      `restrict:false`, or add/remove/replace `allow_bash`/`allow_tools`.
+      This is the recommended, opencode-equivalent override.
+   4. Fallback default when none of the above is set: restrict ON.
+
+   Resolution order in code: CLI flag (if defined) > `TRISS_CODER_CRUSH_
+   RESTRICT` env (if set) > `crush.json` `permissions.run.restrict` (if the
+   user hand-set it) > built-in default `true`. When restrict resolves ON
+   and we control the config, `buildCrushRunArgv` passes `--restrict-run`
+   (belt-and-suspenders even though config also has `restrict:true`); when
+   it resolves OFF, pass nothing (crush's auto-approve default).
+   - Tests: (a) init seeds `permissions.run.restrict:true` + the shared
+     allow_bash into a fresh crush.json WITHOUT dropping the `models` block;
+     (b) init does NOT clobber a user's existing `permissions.run`;
+     (c) `buildCrushRunArgv` with restrict ON contains `--restrict-run`,
+     with restrict OFF contains neither `--restrict-run` nor allow flags;
+     (d) resolution order: CLI `--no-restrict` beats env=1 beats config.
+
+4. **Docs lockstep (per CLAUDE.md "user-visible change" rule).**
+   - `docs/crush-issues.md`: add a "Resolved in 0.1.3 (2026-07-06)" header
+     block at the top mapping each issue → fixed/mostly, so the report reads
+     as closed, not open. Do not delete the original findings (they are the
+     provenance).
+   - `README.md` + `.env.example`: document any new env var introduced in
+     step 3 (`TRISS_CODER_CRUSH_RESTRICT` / allowlist) and the
+     `TRISS_CODER_CRUSH_VERSION` pin now defaulting to `0.1.3`.
+   - `docs/mcp.md` only if a new gating env var is added.
+
+5. **Do NOT (out of scope for this pass, note for later):** wiring
+   `--effort`, `--on-finish`, or the progress-watchdog flags. They are real
+   upside but belong in a follow-up; keep this PR to "close the 7 issues +
+   safety parity."
+
+Review focus for Claude: (a) version parse handles `+dirty`/garbage/newer
+without throwing; (b) the env bridge keeps BOTH keys and the comment no
+longer claims the provider is "silently unconfigured"; (c) Variant A parity
+is correct — init seeds `permissions.run` WITHOUT clobbering the `models`
+block or an existing user policy, the shared allowlist actually matches the
+opencode set, crush isolate default is flipped to OFF, and the override
+resolution order (CLI > env > config > default-ON) is exactly as specified;
+(d) `spawnSync` stays argv-array (never `shell:true`); (e) all three doc
+files moved in lockstep, and the `--no-restrict` flag + `TRISS_CODER_CRUSH_
+RESTRICT` env are both documented in README + .env.example.
+
+## Phase 6 fix — restrict enforcement is CLI-only (2026-07-06, live-verified)
+
+Post-merge review (Fable + live crush runs) found that the committed Variant A
+(commit `2ad14dc`) **does not actually restrict crush**, and by flipping crush
+to isolate-OFF it shipped a net safety *regression*. All facts below were
+verified live against `@phpcraftdream/crush@0.1.3` with a real Z.AI key; see
+`docs/crush-restrict-issues.md` for the maintainer bug report.
+
+**What's broken (verified live):**
+- **Config `permissions.run` is inert.** `crush run --restrict-run` with an
+  `allow_bash` policy seeded into `crush.json` (tried `./crush.json`,
+  `./.crush/crush.json`, and both) still ran a non-allowlisted `echo` to
+  completion. Our `seedCrushPermissions` writes a policy crush ignores.
+- **`--restrict-run` with no CLI allow flags == unrestricted** (auto-approves
+  everything), not deny-all.
+- **CLI `--allow-bash` / `--allow-tool` DO enforce.** Only the command-line
+  flags take effect. Verified tool taxonomy: file tools are `view`, `edit`,
+  `write`, `ls` (accepts `name` or `tool:action`, e.g. `edit:write`); a coder
+  successfully created a file via `write` under `--restrict-run` + those
+  allow-tools with no deadlock.
+- **A denied *bash* command deadlocks to timeout** (`Context deadline
+  exceeded`, no envelope) instead of denying cleanly. File-tool denials were
+  not observed to deadlock; only bash.
+
+**Consequence for the default.** A coding agent routinely runs bash outside a
+read-only allowlist (`npm run build`, `tsc`, `npm run lint`, …). With the
+deadlock bug, every such call dead-ends the whole run at the timeout. So
+**Variant-A "restrict ON by default" is NOT viable for the coder use case
+until the maintainer fixes the deadlock** — it would make crush runs
+routinely dead-end. This supersedes the "restrict ON by default" decision
+above: that decision assumed clean deny (as the crush `--help` text promises),
+which live testing disproved.
+
+**Revised interim stance (until the two crush bugs are fixed upstream):**
+- **crush isolate default → back to ON** (revert the flip in `2ad14dc`). The
+  disposable worktree is the reliable, deadlock-free safety layer — the same
+  posture crush shipped with originally.
+- **crush restrict default → OFF**, but **opt-in restrict actually works**:
+  when the user passes `--restrict` / `TRISS_CODER_CRUSH_RESTRICT=1`,
+  `buildCrushRunArgv` emits the allowlist as **CLI flags** (not config).
+- Net interim posture: *worktree containment (default) + opt-in CLI allowlist
+  for defense-in-depth*. Once the maintainer fixes deadlock + config, revisit
+  flipping restrict back ON by default for true opencode parity.
+
+### Tasks (implement, then live-verify — enforcement can't be unit-tested)
+
+1. **`buildCrushRunArgv` — emit CLI allow flags when restrict is ON.**
+   For each pattern in `CRUSH_ALLOW_BASH_PATTERNS` push `--allow-bash <p>`,
+   and for each tool in a new `CRUSH_ALLOW_TOOLS = ['view','edit','write','ls']`
+   constant push `--allow-tool <t>`, alongside the existing `--restrict-run`.
+   When restrict is OFF, emit none of them (unchanged). Keep argv an array.
+2. **Revert the isolate default for crush to ON.** In `src/commands/coder.js`
+   change `opts.isolate === undefined ? false` back to `? engine === 'crush'`
+   (opencode stays OFF). Update the comment to cite the deadlock/inert-config
+   reason, not the old "policy is the safety layer" reason.
+3. **Change `CRUSH_RESTRICT_DEFAULT` to `false`.** `resolveCrushRestrict`
+   precedence is unchanged (CLI > env > crush.json > default); only the final
+   default flips. `--restrict` / `TRISS_CODER_CRUSH_RESTRICT=1` still turn it on.
+4. **Keep `seedCrushPermissions` but label it forward-compat.** The config is
+   inert today; keep seeding it (harmless, and correct once the maintainer
+   honors it) BUT update the comment + any user-facing message to say the
+   allowlist is currently enforced via CLI flags, not this config block.
+5. **Fable low fixes:**
+   - `seedCrushPermissions`: a valid-JSON-but-non-object crush.json (e.g. `[]`)
+     must route into the same warn-and-skip branch as a parse error — do NOT
+     silently overwrite it.
+   - `detectCrush`/pin: when the pin string itself doesn't parse to semver
+     (e.g. `TRISS_CODER_CRUSH_VERSION=latest`), skip the comparison (treat as
+     satisfied / emit a dim "pin unparseable" note) instead of a perpetual
+     `satisfiesPin:false` warning.
+6. **Docs lockstep + reconcile the now-false parity claims:** `glm-clients.md`
+   §2 table (Safety/Isolation rows) + §8, `crush-issues.md` row #4, README
+   Engines section, and `.env.example` currently say crush has working
+   `permissions.run` parity and isolate-OFF. Correct all to the interim stance:
+   config inert / CLI-flag enforcement / isolate-ON / restrict opt-in.
+
+**Live-verify after implementing (mandatory — this is the whole point):**
+`triss coder run --engine crush --restrict "<edit a file + run an allowed
+test>"` actually edits and runs; a run that tries a disallowed bash command
+fails safe (times out) rather than executing it; default (no `--restrict`)
+runs isolated. Passing unit tests are necessary but NOT sufficient — the
+`2ad14dc` regression passed 431 tests.

package/docs/configuration.md

@@ -122,7 +122,7 @@ Removes a variable.
 | `worker`   | `TRISS_WORKER_API_KEY`, `TRISS_WORKER_BASE_URL`, `TRISS_WORKER_FLASH_MODEL`, `TRISS_WORKER_PRO_MODEL` | only `TRISS_WORKER_API_KEY` is required |
 | `jira`     | `ATLASSIAN_BASE_URL`, `ATLASSIAN_EMAIL`, `ATLASSIAN_API_TOKEN`           | all three                                 |
 | `linear`   | `LINEAR_API_KEY`, `LINEAR_API_URL`                                       | only `LINEAR_API_KEY` is required         |
-| `coder`    | `ZHIPU_API_KEY` (setup: `triss coder init` — engine, `opencode.json`, agent templates) | `ZHIPU_API_KEY` is required |
+| `coder`    | `ZHIPU_API_KEY`, `OPENCODE_API_KEY` (setup: `triss coder init` — engine, `opencode.json`, agent templates) | `ZHIPU_API_KEY` (Z.AI GLM); `OPENCODE_API_KEY` optional (OpenCode Zen, e.g. `opencode/hy3-free`) |
 
 When you add a new integration (see [extending.md](extending.md)), its
 `envVars` declaration is automatically picked up — no wizard changes needed.
@@ -241,14 +241,18 @@ self-hosted endpoints).
 | `TRISS_WORKER_PRO_MODEL`    | no       | `deepseek-v4-pro`                | Override the `pro` preset             |
 | `TRISS_DEFAULT_MODEL`   | no       | `flash`                          | Which preset is used when no `--model`|
 
-### Coder (GLM coding agent, opencode engine)
+### Coder (GLM coding agent)
 
 | Variable                        | Required | Default            | Notes                                     |
 | -------------------------------- | -------- | ------------------ | ------------------------------------------ |
-| `ZHIPU_API_KEY`                  | yes      | —                  | Z.AI API key for GLM models — <https://z.ai/manage-apikey/apikey-list> |
-| `TRISS_CODER_MODEL`              | no       | `zai-coding-plan/glm-5.2`       | Model written to `opencode.json`           |
+| `ZHIPU_API_KEY`                  | yes¹     | —                  | Z.AI API key for GLM models — <https://z.ai/manage-apikey/apikey-list> |
+| `OPENCODE_API_KEY`               | no¹      | —                  | OpenCode Zen key (opencode engine only) — unlocks `opencode/*` models like `opencode/hy3-free` — <https://opencode.ai/docs/zen/> |
+| `TRISS_CODER_MODEL`              | no       | `zai-coding-plan/glm-5.2`       | Resolved model, passed to opencode via `--model` (and written to `opencode.json` by `init`). Use `opencode/hy3-free` for OpenCode Zen |
 | `TRISS_CODER_SMALL_MODEL`        | no       | `zai-coding-plan/glm-5-turbo`   | Small/fast model written to `opencode.json`|
 | `TRISS_CODER_OPENCODE_VERSION`   | no       | `1.17.13`           | Pin override for the `opencode-ai` npm install |
+| `TRISS_CODER_ENGINE`             | no       | `opencode`          | Coding engine: `opencode` (default) or `crush` |
+| `TRISS_CODER_CRUSH_VERSION`      | no       | `0.1.3`             | 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 init` auto-detects which Z.AI endpoint `ZHIPU_API_KEY`
 actually authenticates against — the `zai-coding-plan` (subscription)
@@ -261,6 +265,45 @@ file) when the existing `model` prefix doesn't match what the key
 verified against — that mismatch is what makes opencode retry a model
 call it can never complete.
 
+¹ **Credentials are provider-specific.** A run needs the one key its
+resolved model requires: `zai-coding-plan/*` and `zai/*` (GLM) need
+`ZHIPU_API_KEY`; `opencode/*` OpenCode Zen models (e.g. the free
+`opencode/hy3-free`) need `OPENCODE_API_KEY`. So `ZHIPU_API_KEY` is
+"required" only in the sense that it is the default provider's key — a
+zen-only setup runs on `OPENCODE_API_KEY` alone. `triss coder run` forwards
+whichever key the model needs to the engine subprocess and gates on it
+before spawning. The `crush` engine speaks Z.AI only and always needs
+`ZHIPU_API_KEY`. `triss status` / `triss_coder_status` show both keys, and
+the coder MCP tools surface once **either** is set. Run
+`triss coder init --provider opencode-zen` to set up a Zen model interactively
+(key + `opencode.json`); full details are in
+[opencode-zen.md](opencode-zen.md).
+
+**Engines.** `opencode` (default) enforces a deny-first per-command bash
+allowlist via `opencode.json` (curated safe commands only) that actually
+works. `crush` (`--engine crush` or `TRISS_CODER_ENGINE=crush`; npm
+`@phpcraftdream/crush` ≥0.1.3, bin `crush`) has a **weaker, interim** safety
+story: live testing proved crush 0.1.3 **ignores** its `permissions.run`
+config block and a denied bash command **deadlocks to timeout**, so triss
+ships crush isolate-**ON** by default (the disposable worktree is the reliable
+safety layer) and makes restrict **opt-in** (default OFF). `triss coder init`
+still seeds a `permissions.run` block into crush.json as forward-compat
+(harmless, correct once upstream honors it), but the working allowlist today
+is the CLI flags: `--restrict` (or `TRISS_CODER_CRUSH_RESTRICT=1`) makes
+`triss coder run` emit `--restrict-run` plus `--allow-bash`/`--allow-tool` for
+each entry. Override per-run with `--restrict` / `--no-restrict` (resolution:
+CLI flag > env > crush.json `permissions.run.restrict` > default OFF). Prefer
+opencode when you want the bash-policy safety layer baked into the project;
+crush is simpler (one JSON envelope, native session ids) but pair it with its
+default isolation, or opt into `--restrict` for a CLI allowlist on top — don't
+combine `--no-restrict` with `--no-isolate` in a workspace you can't afford to
+lose. For Z.AI GLM, both engines share the single `ZHIPU_API_KEY` — crush
+≥0.1.1 reads it natively; triss also forwards it as `ZAI_API_KEY` for older
+binaries. (opencode can alternatively run OpenCode Zen `opencode/*` models on
+`OPENCODE_API_KEY` — see the coder env-var table above.)
+See `docs/crush-restrict-issues.md` for the live-verified bug facts and
+`docs/crush-issues.md` for the fuller list of crush caveats.
+
 `triss coder run` is **POSIX only** (macOS/Linux) — its engine env
 allowlist and `--timeout` kill both rely on POSIX process-group
 semantics. It refuses to run on Windows with a clear error rather than