triss-coworker 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.34.0] — 2026-08-13
+
+### Added
+
+- `triss exec` deterministically routes a task to `ask`, `review`, `coder run`,
+  or `chat`. Its JSON `--explain` mode validates the selected route without
+  model, Git, integration, update-check, stdin, network, or filesystem work.
+- `ask` and `review` support a shared `evidence` response contract across CLI
+  and MCP, with explicit Outcome, Evidence, Uncertainty, and Decision sections.
+- Help, completion, README, MCP documentation, and generated agent instructions
+  cover the new routing and evidence interfaces.
+
+### Changed
+
+- Core CLI and MCP token budgets, plus coder timeouts, use strict shared
+  positive-number validation. Malformed and partially numeric values now fail
+  before corpus, Git, model, or subprocess work.
+- Lexical `exec` routing is conservative: ambiguous or read-only status wording
+  remains chat, while only explicit review or implementation intent selects an
+  agentic route.
+
+### Fixed
+
+- Managed `AGENTS.md` and `CLAUDE.md` initialization now plans all destinations
+  before mutation, rejects aliases and malformed marker layouts, preserves
+  unrelated bytes and file modes, installs complete files atomically, and uses
+  identity-aware rollback without clobbering intervening user changes.
+- Clean text reviews retain their legacy message even when terminal colors are
+  enabled, and `exec --explain` remains side-effect free in interactive shells.
+
+## [0.33.0] — 2026-08-13
+
+### Added
+
+- Automatic, cached stable-release notices for interactive CLI and initialized
+  MCP sessions, with `TRISS_UPDATE_CHECK=0` as the passive-check opt-out.
+- `triss update` text/JSON status plus explicit receipt-backed standalone apply
+  and verified offline rollback. Package-manager, source, legacy, and unknown
+  installations remain read-only.
+- An npm-free standalone artifact/installer with per-version integrity
+  inventories, journaled activation/recovery, retained-size reporting, and
+  guarded public Release promotion.
+
+### Security
+
+- Update endpoints are fixed and strictly allowlisted, downloads/extraction are
+  bounded, and standalone writes require validated receipt ownership.
+
 ## [0.32.0] — 2026-08-12
 
 ### Added
@@ -1008,7 +1056,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of `triss-coworker`.
 
-[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.31.0...HEAD
+[Unreleased]: https://github.com/ayleen/triss-coworker/compare/v0.34.0...HEAD
+[0.34.0]: https://github.com/ayleen/triss-coworker/compare/v0.33.0...v0.34.0
+[0.33.0]: https://github.com/ayleen/triss-coworker/compare/v0.32.0...v0.33.0
+[0.32.0]: https://github.com/ayleen/triss-coworker/compare/v0.31.1...v0.32.0
+[0.31.1]: https://github.com/ayleen/triss-coworker/compare/v0.31.0...v0.31.1
 [0.31.0]: https://github.com/ayleen/triss-coworker/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/ayleen/triss-coworker/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/ayleen/triss-coworker/compare/v0.28.0...v0.29.0

package/README.md

@@ -50,8 +50,10 @@ tokens of tracker chatter into its own context. Adding a new provider
 
 - **Node.js ≥ 22** (LTS). Check with `node --version`.
   - Don't have it? Install via [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), Homebrew (`brew install node`), or [nodejs.org](https://nodejs.org/).
-- **npm** (ships with Node.js) — used for the `npm install -g` path. `pnpm` and `yarn` also work.
-- **git** — used by the bash one-liner installer to clone the repo.
+- **npm** (ships with Node.js) — used only for the package-manager install path.
+  `pnpm` and `yarn` also work.
+- The standalone bash installer and update discovery do not require npm, pnpm,
+  yarn, git, tar, unzip, or a checksum utility once a standalone Release exists.
 - A **DeepSeek API key** (free tier works) for the worker model: <https://platform.deepseek.com/>.
 
 Triss has no other runtime dependencies.
@@ -84,6 +86,14 @@ binary is `triss`.
 curl -fsSL https://raw.githubusercontent.com/ayleen/triss-coworker/main/install.sh | bash
 ```
 
+This installs a receipt-backed standalone copy under
+`~/.local/share/triss` and links `~/.local/bin/triss`. Override those paths for
+the install command with `TRISS_STANDALONE_HOME` and `TRISS_BIN_DIR`.
+`TRISS_HOME` remains reserved for the old git installer and is never interpreted
+as standalone write authority. During the first-release transition only, a
+verified missing standalone asset may use the previous git+npm path for a fresh
+empty legacy target; existing legacy checkouts are never pulled or modified.
+
 ### Option C — from source
 
 ```bash
@@ -101,6 +111,34 @@ triss --help
 triss status
 ```
 
+## Updates
+
+During successful interactive CLI use, Triss checks a fixed GitHub Release
+endpoint at most once per cache window and prints a throttled update notice to
+stderr. A due check is awaited and adds at most 1.1 seconds; a fresh cache adds
+no network wait. Long-running MCP servers begin the same check only after the
+MCP initialization handshake and use MCP logging plus stderr fallback.
+
+```bash
+triss update                  # fresh status and guidance; no file changes
+triss update --json           # one machine-readable object
+triss update --apply          # receipt-backed standalone installs only
+triss update --rollback       # offline rollback to a verified prior version
+```
+
+Apply and rollback require confirmation; add `--yes` for non-interactive
+operation confirmation. Breaking a proven-stale update lock is a separate
+authorization: add `--break-lock` (and also `--yes` when non-interactive).
+Package-manager, source, ephemeral, legacy-git, and unknown installations remain
+read-only and receive installation-specific guidance.
+
+A valid Release that requires a newer Node is reported as available but cannot
+be applied until Node is upgraded. Standalone status reports retained version
+count and receipt-recorded payload bytes; automatic pruning is not performed.
+Set `TRISS_UPDATE_CHECK=0` to disable passive checks and notices. Explicit
+`triss update` remains available. A running MCP host must be restarted after an
+update to load the new version.
+
 ## Configure
 
 ```bash
@@ -265,6 +303,7 @@ and writing**.
 | Command         | Does                                                  | Replaces                            |
 | --------------- | ----------------------------------------------------- | ----------------------------------- |
 | `triss ask`        | Reads files, URLs, and/or piped stdin — returns a summary | The agent reading the source itself |
+| `triss exec`       | Deterministically routes a task to `ask`, `review`, `coder run`, or `chat`; `--explain` prints the JSON decision without executing | Manually choosing the delegation command |
 | `triss chat`       | Bare prompt to the worker model — no corpus           | A separate `gpt`-style CLI          |
 | `triss write`      | Generates code/docs from a spec + reference file      | The agent typing out boilerplate    |
 | `triss extract`    | Pulls readable transcript from JSONL session logs     | Manually scraping `~/.claude/...`   |
@@ -278,6 +317,7 @@ and writing**.
 | `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 |
 | `triss status`     | Shows current model + key + .env sources              | —                                   |
+| `triss update`     | Checks for updates; explicitly applies/rolls back standalone installs | npm registry polling or silent self-update |
 | `triss config`     | Interactive credential management                     | Manual `.env` editing               |
 | `triss mcp`        | Register Triss as MCP server in Claude Code           | Editing `~/.claude.json` by hand    |
 | `triss completion` | Shell completion script (bash/zsh)                    | Hand-rolled completion              |
@@ -299,12 +339,54 @@ triss ask --paths "src/**/*.ts" \
 triss ask --paths "src/**/*.ts" \
           --question "Find SQL injection risks" \
           --provider kimi --model pro    # Kimi K3 via MOONSHOT_API_KEY
+
+# Optional evidence-oriented Markdown contract (text is the default)
+triss ask --paths "src/**/*.ts" --question "Find SQL injection risks" \
+          --format evidence
 ```
 
 Typical output is a focused answer with cited file paths, not a raw file dump.
 That is the whole trick: the primary agent gets the useful bits, not a
 firehose wearing a moustache.
 
+`--format evidence` appends a trusted instruction requiring the model-authored
+Markdown sections `Outcome`, `Evidence`, `Uncertainty`, and `Decision required`.
+It does not make Triss semantically validate the model's claims. The same
+optional contract is available to `triss review` and MCP `triss_ask` /
+`triss_review` as `response_format: "evidence"`; defaults remain unchanged.
+
+### `triss exec`
+
+```bash
+triss exec --explain --paths README.md "summarize this project"
+triss exec --explain --review "review the current branch"
+triss exec --code "add a bounded validation"
+```
+
+Repeat `--paths <path>` or `--urls <url>` when routing more than one source;
+the final positional argument remains the task:
+
+```bash
+triss exec --paths README.md --paths package.json "summarize this project"
+```
+
+Routing is deterministic: explicit review inputs (`--pr`, `--base`,
+`--review`) take precedence, then `--paths`/`--urls` for `ask`, `--code`, and
+`--chat`. Without an explicit route, review/audit language selects `review`,
+explicit implementation/change language selects `coder run`, and everything
+else selects `chat`. Read-only status phrases such as `show build status` stay
+on `chat`. Contradictory explicit signals and stdin-only routing fail
+closed. Options unsupported by the selected route also fail instead of being
+silently discarded. In `--explain`, such a failure is represented by
+`route: null` with its reason rather than thrown. `--explain` emits
+schema-versioned JSON and performs no model, Git, network, stdin, or filesystem
+mutation.
+
+`exec --max-tokens` is forwarded to ask, review, and chat. For coder routing it
+is supported with `--engine crush`; the OpenCode engine has no per-run token
+budget flag, so `exec --code --max-tokens ...` without Crush fails explicitly
+instead of silently ignoring the requested cap.
+
 ### `triss write`
 
 ```bash
@@ -923,6 +1005,11 @@ touch the variables directly. The full reference (worker model,
 integrations, tunables, security toggles) lives in
 [docs/configuration.md](docs/configuration.md#environment-reference).
 
+`TRISS_UPDATE_CHECK=0` disables passive update checks. Installer-only
+`TRISS_STANDALONE_HOME` and `TRISS_BIN_DIR` select standalone paths and are
+recorded in the ownership receipt; later environment changes do not grant write
+authority.
+
 `.env` files are loaded from `~/.config/triss/.env` (global) and
 `<project-root>/.triss.env` (project, overrides global). Real `process.env`
 always wins. See [docs/configuration.md](docs/configuration.md#recipes--common-setups-end-to-end)
@@ -1008,8 +1095,6 @@ test suite.
 
 **Planned**:
 
-- [ ] `triss exec <task>` — auto-route a freeform task to the right
-      sub-command
 - [ ] More provider recipe blocks in the docs (Kimi, Ollama,
       OpenRouter — examples already present, but with terse setup steps)
 

package/bin/triss.js

@@ -8,7 +8,7 @@ if (nodeMajor < 22) {
   process.exit(1);
 }
 
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { readFileSync } from 'node:fs';
 import pc from 'picocolors';
 import { runAsk } from '../src/commands/ask.js';
@@ -29,6 +29,8 @@ import { runInit } from '../src/commands/init.js';
 import { runAgentHelp } from '../src/commands/agent-help.js';
 import { runStatus } from '../src/commands/status.js';
 import { runCompletion } from '../src/commands/completion.js';
+import { runExec } from '../src/commands/exec.js';
+import { runUpdate } from '../src/commands/update.js';
 import {
   runWizard,
   runSet,
@@ -42,11 +44,38 @@ import { runCoderInit, runCoderRun, runCoderClean } from '../src/commands/coder.
 import { runCoderModels, runCoderModelSet, runCoderModelRollback } from '../src/commands/coder-models.js';
 import { loadIntegrations } from '../src/integrations/_registry.js';
 import { withCall } from '../src/call-context.js';
+import { positiveIntegerOption, positiveNumberOption } from '../src/option-validation.js';
+import { loadEnvFiles } from '../src/config.js';
+import {
+  runDefaultPassiveCliCheck,
+  shouldSuppressPassiveCheck,
+} from '../src/update/passive.js';
+import { isExecExplainInvocation } from '../src/cli-argv.js';
 
 const packageJson = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 );
 
+function collectOption(value, previous) {
+  return previous.concat(value);
+}
+
+function parsePositiveInteger(value) {
+  try {
+    return positiveIntegerOption(value);
+  } catch (error) {
+    throw new InvalidArgumentError(error.message);
+  }
+}
+
+function parsePositiveNumber(value) {
+  try {
+    return positiveNumberOption(value);
+  } catch (error) {
+    throw new InvalidArgumentError(error.message);
+  }
+}
+
 const program = new Command();
 program
   .name('triss')
@@ -56,6 +85,19 @@ program
   )
   .version(packageJson.version);
 
+program.hook('postAction', async () => {
+  loadEnvFiles();
+  const argv = process.argv.slice(2);
+  if (shouldSuppressPassiveCheck({
+    argv,
+    stderrIsTTY: Boolean(process.stderr.isTTY),
+    ci: /^(1|true|yes)$/i.test(process.env.CI || ''),
+    optOut: process.env.TRISS_UPDATE_CHECK === '0',
+    commandFailed: Boolean(process.exitCode),
+  })) return;
+  await runDefaultPassiveCliCheck({ currentVersion: packageJson.version });
+});
+
 program
   .command('init')
   .description('Add the triss delegation block to your project (or globally)')
@@ -74,8 +116,9 @@ program
   .requiredOption('-q, --question <text>', 'question to answer about the corpus')
   .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')
-  .option('--max-tokens <n>', 'token budget for reasoning + answer', (v) => parseInt(v, 10), 8192)
+  .option('--max-tokens <n>', 'token budget for reasoning + answer', parsePositiveInteger, 8192)
   .option('--system <text>', 'override the system prompt')
+  .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)")
   // Commander also supplies its Command instance to action handlers. Adapt
@@ -89,7 +132,7 @@ program
   .requiredOption('-t, --target <path>', 'output file path')
   .option('-c, --context <path>', 'reference file to mimic in style')
   .option('-m, --model <name>', 'model preset (flash | pro) or full model id')
-  .option('--max-tokens <n>', 'token budget for reasoning + output', (v) => parseInt(v, 10), 16384)
+  .option('--max-tokens <n>', 'token budget for reasoning + output', parsePositiveInteger, 16384)
   .action(wrap(runWrite));
 
 program
@@ -121,6 +164,39 @@ program
   .option('--no-stream', 'disable streaming output (default streams when stdout is a TTY)')
   .action((prompt, opts) => wrap(runChat)(prompt, opts));
 
+program
+  .command('exec [task]')
+  .description('Route a task deterministically to ask, review, coder run, or chat')
+  .option('--explain', 'print the JSON route decision without executing anything')
+  .option('--pr <number>', 'explicitly route to review a GitHub PR')
+  .option('--base <branch>', 'explicitly route to review against a base branch')
+  .option('--review', 'explicitly route to review')
+  .option('--skip-issue', 'forward review linked-ticket lookup suppression')
+  .option('--paths <path>', 'explicitly route to ask with a file path; repeat for multiple paths', collectOption, [])
+  .option('--urls <url>', 'explicitly route to ask with a URL; repeat for multiple URLs', collectOption, [])
+  .option('--code', 'explicitly route to coder run')
+  .option('--chat', 'explicitly route to chat')
+  .option('--stdin', 'let the selected downstream command read piped input')
+  .option('--provider <name>', 'forward the inference provider')
+  .option('-m, --model <name>', 'forward the model')
+  .option('--max-tokens <n>', 'forward the token budget')
+  .option('--format <format>', 'forward ask/review response format: text or evidence')
+  .option('--system <text>', 'forward the system prompt to ask/chat')
+  .option('--stream', 'forward streaming preference')
+  .option('--no-stream', 'disable forwarded streaming')
+  .option('--engine <name>', 'forward coder engine')
+  .option('--agent <name>', 'forward coder agent template')
+  .option('--session <id>', 'forward coder session')
+  .option('--continue', 'continue the most recent coder session')
+  .option('--small-model <p/m>', 'forward coder small model')
+  .option('--isolate', 'forward coder isolation')
+  .option('--no-isolate', 'disable coder isolation')
+  .option('--restrict', 'forward coder restriction')
+  .option('--no-restrict', 'disable coder restriction')
+  .option('--cwd <path>', 'forward coder working directory')
+  .option('--timeout <sec>', 'forward coder timeout')
+  .action((task, opts) => wrap(runExec)(task, opts));
+
 program
   .command('commit-msg')
   .description('Generate a Git commit message from staged changes (Conventional Commits by default).')
@@ -142,6 +218,7 @@ program
   .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)')
   .option('--max-tokens <n>', 'token budget for the review (default 8192)')
+  .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)')
   .action((pr, opts) => wrap(runReview)(pr, opts));
@@ -169,6 +246,19 @@ program
   .description('Show current configuration: API key, models, .env sources')
   .action(wrap(runStatus));
 
+program
+  .command('update')
+  .description('Check for a newer stable release; explicitly update standalone installs')
+  .option('--json', 'emit one machine-readable status object')
+  .option('--apply', 'apply the newer release to a validated standalone install')
+  .option('--rollback', 'switch to the previous verified standalone version')
+  .option('--yes', 'skip apply/rollback confirmation in non-interactive use')
+  .option('--break-lock', 'separately authorize breaking a proven-stale update lock')
+  // Commander passes its Command instance as a second action argument.  The
+  // update runner has a second parameter reserved for injected dependencies
+  // in tests, so keep the CLI boundary options-only.
+  .action((opts) => wrap(runUpdate)(opts));
+
 program
   .command('completion <shell>')
   .description('Print shell completion script (bash | zsh). eval `triss completion bash`')
@@ -262,7 +352,7 @@ coder
   .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('--timeout <sec>', 'kill the engine after this many seconds', parsePositiveNumber, 900)
   .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));
@@ -365,7 +455,14 @@ mcp
   .action(wrap(runMcpStatus));
 
 // Plugin-style integrations (jira, linear, ...). See docs/extending.md.
-const integrations = await loadIntegrations();
+// `exec --explain` is an inspection mode that performs no work at all, so it
+// must not trigger integration *startup* side effects: the github integration
+// bootstraps by spawning `gh auth token` (a credential child process) at load
+// time. Explain skips the load entirely — its route decision needs none of
+// the integration subcommands. Every other command still loads and registers
+// them normally.
+const isExplainOnly = isExecExplainInvocation(process.argv.slice(2));
+const integrations = isExplainOnly ? [] : await loadIntegrations();
 for (const manifest of integrations) {
   const sub = program.command(manifest.name).description(manifest.description || manifest.name);
   manifest.register(sub, { wrap });