chore(release): 0.4.0 — integrate the full 16-step stack into main

.github/workflows/benchmark-gates.yml

@@ -0,0 +1,62 @@
+name: Opt-in OPS acceptance benchmarks
+on:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  benchmark-gates:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { runner: windows-latest, target: win32-x64, suffix: '.exe' }
+          - { runner: ubuntu-24.04, target: linux-x64, suffix: '' }
+          - { runner: macos-latest, target: darwin-arm64, suffix: '' }
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    env:
+      CARGO_BUILD_JOBS: '3'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+      - name: Set up pinned Rust
+        shell: bash
+        run: rustup toolchain install 1.97.1 --profile minimal && rustup default 1.97.1
+      - name: Install locked dependencies
+        run: npm ci --ignore-scripts
+      - name: Build candidate host
+        run: npm run build
+      - name: Acquire optional pinned Windows Bash fixture
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $env:DSH_HOME = Join-Path $env:RUNNER_TEMP 'ops-benchmark-bash'
+          node bin/dsh-ops.mjs bash-runtime install
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          $fixture = node --input-type=module -e "import {pinnedBashExecutable} from './lib/shells/pinned.js'; console.log(pinnedBashExecutable())"
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          "DSH_OPS_TEST_BASH=$fixture" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+      - name: Build candidate worker
+        run: npm run build:ptc
+      - name: Materialize exact 0.3.1 source blobs
+        run: node bench/gates/prepare-baseline.mjs baseline-031
+      - name: Build independent 0.3.1 worker
+        run: cargo build --release --locked --manifest-path baseline-031/native/Cargo.toml
+      - name: Verify benchmark harness integrity
+        run: node test/run.mjs bench-gates bench-integrity
+      - name: Run all five real-host acceptance gates
+        run: node bench/cli.mjs gates --baseline-source baseline-031 --baseline-worker baseline-031/native/target/release/dsh-ops-worker${{ matrix.suffix }} --output benchmark-gates.json
+      - name: Upload exact evidence even when a gate fails
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: benchmark-gates-${{ matrix.target }}
+          path: |
+            benchmark-gates.json
+            benchmark-gates.json.md
+          if-no-files-found: error
+          retention-days: 30

.github/workflows/ci.yml

@@ -2,15 +2,15 @@ name: Cross-platform validation
 on:
   # A merge must validate itself. Without this, a branch was only ever checked when someone
   # remembered to dispatch the workflow by hand — which is how a stale number shipped in #134.
-  # `0.3.2` is this cycle's release branch: what lands there is what ships, so it validates on
-  # push exactly like `main`.
+  # Release branches validate on push exactly like `main`; each 0.4.0 slice lands on its
+  # staging branch before the final release PR.
   push:
-    branches: [main, 0.3.2]
+    branches: [main, 0.3.2, release/0.4.0]
   # And a pull request has to show its result before it is merged, not after. GitHub reads this
   # file from the pull request's own head, so listing the release branch here is what makes a
-  # pull request against `0.3.2` run the gate at all.
+  # pull request against a release branch run the gate at all.
   pull_request:
-    branches: [main, 0.3.2]
+    branches: [main, 0.3.2, release/0.4.0]
   # A merge queue builds the queued commits before they reach `main`, and it only accepts a group
   # whose required checks passed there. Without this trigger the workflow simply never runs for a
   # queued group, so enabling a merge queue would silently un-gate every merge.
@@ -56,6 +56,9 @@ jobs:
       DSH_OPS_RETRY_TIMEOUTS: '1'
     steps:
       - uses: actions/checkout@v7
+        with:
+          # The provenance regression verifies exact blobs from the pinned 0.3.1 commit.
+          fetch-depth: 0
       - uses: actions/setup-node@v7
         with:
           node-version: '24'
@@ -79,18 +82,11 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y acl
       - name: Install locked dependencies
         run: npm ci --ignore-scripts --registry=https://registry.npmjs.org
-      - name: Build and test native worker
-        shell: bash
-        run: |
-          cargo test --locked --manifest-path native/Cargo.toml
-          npm run build:ptc
-      - name: Windows IPC build
-        if: runner.os == 'Windows'
-        run: npm run build:bash-ipc
       # The gate, not `npm run verify`: it runs the same suites with `DSH_OPS_REQUIRE_RUNTIME=1`
       # on POSIX (a runtime-absence skip is a failure, not a pass), refuses any skip outside this
       # platform's known set, fails when a suite file on disk was never collected, and checks the
-      # packed artifact. Build success is not behaviour.
+      # packed artifact. It builds the plugin before its CLI, then builds/tests the worker and
+      # Windows IPC proxies using an explicitly downloaded pinned Bash fixture (or DSH_OPS_TEST_BASH). Build success is not behaviour.
       - name: Functional gate (skips, suite inventory, packed artifact)
         shell: bash
         run: node scripts/verify-gate.mjs --skip-install
@@ -136,6 +132,8 @@ jobs:
           restore-keys: ops-031-${{ runner.os }}-${{ runner.arch }}-
       - name: Install locked dependencies
         run: npm ci --ignore-scripts --registry=https://registry.npmjs.org
+      - name: Build the plugin
+        run: npm run build
       - name: Build the native worker
         shell: bash
         run: npm run build:ptc
@@ -169,6 +167,9 @@ jobs:
       CARGO_BUILD_JOBS: '3'
     steps:
       - uses: actions/checkout@v7
+        with:
+          # Included benchmark tests verify the pinned historical baseline.
+          fetch-depth: 0
       - uses: actions/setup-node@v7
         with:
           node-version: '24'
@@ -186,6 +187,8 @@ jobs:
           restore-keys: ops-031-${{ runner.os }}-${{ runner.arch }}-
       - name: Install locked dependencies
         run: npm ci --ignore-scripts --registry=https://registry.npmjs.org
+      - name: Build the plugin
+        run: npm run build
       - name: Build the native worker
         shell: bash
         run: npm run build:ptc
@@ -268,6 +271,9 @@ jobs:
       DSH_OPS_RETRY_TIMEOUTS: '1'
     steps:
       - uses: actions/checkout@v7
+        with:
+          # The provenance regression verifies exact blobs from the pinned 0.3.1 commit.
+          fetch-depth: 0
       - uses: actions/setup-node@v7
         with:
           node-version: '22.19'
@@ -276,11 +282,6 @@ jobs:
         run: rustup toolchain install 1.97.1 --profile minimal && rustup default 1.97.1
       - name: Install locked dependencies
         run: npm ci --ignore-scripts --registry=https://registry.npmjs.org
-      - name: Build and test native worker
-        shell: bash
-        run: |
-          cargo test --locked --manifest-path native/Cargo.toml
-          npm run build:ptc
       - name: Functional gate (skips, suite inventory, packed artifact)
         shell: bash
         run: node scripts/verify-gate.mjs --skip-install

.github/workflows/release.yml

@@ -10,8 +10,8 @@ name: Release
 # not be read as evidence that a tag produces a release. Enabling it is an admin step,
 # and the first run must be a dispatch on `main` — see docs/release-process.md.
 #
-# WHAT IT PUBLISHES: the GitHub Release for the tag — title, generated notes, the three
-# installable tarballs and `SHA256SUMS`. npm is a separate channel and is deliberately
+# WHAT IT PUBLISHES: the GitHub Release for the tag — title, generated notes, the installable
+# tarballs and `SHA256SUMS`. npm is a separate channel and is deliberately
 # NOT published here: `npm publish` needs an `NPM_TOKEN` secret that this repository
 # does not grant to Actions, and docs/PROVENANCE.md records that GitHub publication
 # does not automatically publish npm. Adding npm publication later needs an admin to
@@ -82,13 +82,13 @@ jobs:
         run: rustup target add ${{ matrix.triple }}
 
       - name: Install locked dependencies
-        # Only the Windows job needs node_modules: the IPC proxies link against the
-        # pinned shell payload. The other two targets build from the committed Rust
-        # sources alone, so they skip the install. `--ignore-scripts` keeps an install
-        # hook out of the release path, matching ci.yml.
-        if: matrix.target == 'win32-x64'
+        # Every target builds the host JS consumed by the runtime staging CLI.
+        # Windows also needs the pinned shell payload for its IPC proxies.
         run: npm ci --ignore-scripts --registry=https://registry.npmjs.org
 
+      - name: Build the plugin
+        run: npm run build
+
       - name: Build the native worker
         shell: bash
         run: cargo build --release --locked --manifest-path native/Cargo.toml --target ${{ matrix.triple }}
@@ -99,6 +99,10 @@ jobs:
         shell: bash
         run: node bin/native-runtime.mjs stage --platform ${{ matrix.target }} --input native/target/${{ matrix.triple }}/release
 
+      - name: Acquire optional pinned Bash fixture
+        if: matrix.target == 'win32-x64'
+        run: node bin/dsh-ops.mjs bash-runtime install
+
       - name: Build the Windows Bash IPC proxies
         # Only the Windows target carries the IPC proxies; their receipt is verified
         # against the committed native/bash-ipc sources by the gate below. Fails when
@@ -117,15 +121,16 @@ jobs:
   gate:
     name: Verify the release closure and assemble the publish directory
     needs: native
-    # Assembly is Windows-only by design: the two platform payload packages this
-    # release publishes are Windows payloads. The gate reads every target's bytes and
-    # does not need to execute them.
+    # Windows validates the IPC payload while checking every target artifact.
     runs-on: windows-latest
     timeout-minutes: 45
     env:
       DIST: dist-release
     steps:
       - uses: actions/checkout@v7
+        with:
+          # Included benchmark tests verify the pinned historical baseline.
+          fetch-depth: 0
 
       - uses: actions/setup-node@v7
         with:
@@ -170,6 +175,11 @@ jobs:
           rustup default 1.97.1
           cargo build --release --locked --manifest-path native/Cargo.toml
 
+      - name: Build plugin and acquire optional pinned Bash fixture
+        run: |
+          npm run build
+          node bin/dsh-ops.mjs bash-runtime install
+
       - name: Release gate (manifest, suites, runtime closure)
         # Publishing must not start before this step is green — it is the only reason
         # the `publish` job sits behind `needs`. `verify:release` is
@@ -181,8 +191,8 @@ jobs:
         run: npm run verify:release
 
       - name: Assemble and pack the publish directory
-        # Materializes the two Windows platform packages from their pinned upstream
-        # assets, packs everything, and writes provenance.json + SHA256SUMS under
+        # Packs the main plugin without shell payload dependencies and writes
+        # provenance.json + SHA256SUMS under
         # $env:DIST. A non-zero exit fails the run; nothing is published from here.
         run: node scripts/build-platform-packages.mjs --dist "$env:DIST"
 

.gitignore

@@ -19,6 +19,9 @@ native/target/
 # Dependencies
 node_modules/
 
+# Compiled plugin source (edit src/ and run npm run build)
+/lib/
+
 # Scratch trees used by the suites and by hand
 .tmp-*
 *.scratch.*

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repository. Humans: see
+[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) (中文：[docs/贡献指南.md](docs/贡献指南.md)), which this file
+summarizes and never overrides.
+
+## What dsh-ops is
+
+A DSH tool-enhancement plugin. Its purpose is to save the model's tokens, contain context growth,
+shorten task time and make the model more capable — by giving it low-cognitive-load tools with small
+inputs/outputs, honest feedback that stops retry loops, and progressive disclosure of advanced
+capabilities.
+
+- **Minimal and low-intrusion.** It only adds `ops_*` tools (including `ops_bash` on Windows) and can
+  optionally replace some official tools. It does not change host logic, rewrite the shared tool
+  registry, or depend on other plugins; integration code with other plugins lives apart from the core.
+- **Native and PTC are separate projections of one kernel.** Native mode output is read by the model
+  (compact, line-numbered text); PTC output is read by sandboxed code (strict typed data). Do not
+  make one shape serve both. See issue #261 for the 0.4.0 design.
+
+## Hard rules
+
+1. **No code file over 1000 lines.** `node scripts/check-file-size.mjs` (`npm run check:size`) runs
+   in CI over every git-tracked `.js .mjs .cjs .ts .mts .cts .rs .ps1 .sh .py .cpp .h .hpp .cc` file
+   outside `node_modules/ native/target/ runtime/ licenses/ docs/ dist/`. When a file approaches the
+   limit, split it into modules and group them in a folder (see `src/shells/`,
+   `scripts/lib/build/`, `bench/lib/fixtures/`). Do not raise the limit or add exclusions.
+2. **A PR adds at most ~1000 implementation lines** (tests and byte-identical moves excluded) and
+   touches only the files its issue names. Large work is split into slices on a staging branch
+   (for 0.4.0: `release/0.4.0`).
+3. **No AI attribution** in commits, PRs, issues or comments: no `Co-authored-by:` lines naming an
+   agent/model/bot, no "Generated with/Made with" footers. Commits use the user's own identity.
+4. **Every new behaviour has an assertion** that fails when the change is reverted. No silent skips,
+   no retries to hide flaky concurrency — fix the cause.
+5. **Do not edit generated output.** `lib/` is built from `src/`; `runtime/` is staged worker output.
+
+## Layout
+
+| Path | Contents |
+| --- | --- |
+| `src/` | Plugin source (strict TypeScript and TSX). Compiled by `tsc` to `lib/` |
+| `lib/` | Build output that is shipped and imported by tests — gitignored, never edited by hand |
+| `src/components/<name>/` | One directory per DSH component row (`shell`, `file`, `ptc`, `panel`, `tui`, `hide-official`, …): entry, `package.json`, `locale/`, `icon.png` |
+| `native/` | Rust worker (`dsh-ops-worker`); one JSON request on stdin, one JSON result on stdout, spawned per call through the host subprocess/sandbox |
+| `test/` | One `*.test.mjs` file = one suite = one process; shared helpers in `test/lib/` (never named `*.test.mjs`) |
+| `bench/` | Repository-only benchmarks; never shipped, never part of the default gate |
+| `scripts/`, `bin/` | Gate, manifest validation, packaging, CLI |
+| `docs/` | Bilingual docs: every document exists in English and Chinese |
+
+## Commands
+
+```console
+npm ci --ignore-scripts                                  # install (locked)
+npm run build                                            # src/ -> lib/ (tsc + assets)
+cargo test --workspace --locked --manifest-path native/Cargo.toml    # Rust unit tests
+npm run build:ptc                                        # build + stage the native worker (needed by most suites)
+npm run build:bash-ipc                                   # Windows only
+npm run verify                                           # build + manifest check + all suites
+node test/run.mjs <filter>                               # only suites whose file name contains <filter>
+npm run check:size                                       # the 1000-line gate
+node scripts/verify-gate.mjs --skip-install              # the full release gate, exactly what CI runs
+```
+
+- Suites without a built worker **skip**; a skip is not a pass. On Linux/macOS the gate sets
+  `DSH_OPS_REQUIRE_RUNTIME=1`, which turns those skips into failures.
+- `DSH_HOME` must point into the system temp directory when running a suite directly; the harness
+  refuses anything else. `node test/run.mjs` creates one per suite.
+
+## Code conventions
+
+- English for code, comments, CLI output and commit messages; user-facing docs in both languages,
+  updated in the same PR.
+- Tool names always come from `publicToolName()` in `src/policy.ts`; never hand-write `ops_`.
+- Config is validated in `src/config.ts`; unknown keys are errors that name the key. Defaults in
+  `cordis.patch.yml` must equal the defaults in code.
+- The host half must not import `@deepseek-ai/*` values at load time; use `ctx.inject` / `ctx.get`.
+  Publish tools only through this plugin's own scoped `ctx.tools.register`.
+- Tool failures are returned values (`status`, `error.code`, `effectState`), never thrown. Never
+  report a partial or early-stopped result as complete.
+- Do not remove tool contracts (argument semantics, defaults, path base, paging completeness,
+  permission boundaries) to save schema bytes.
+- New dependencies need a reason in the PR, an exact version published at least 7 days earlier, and
+  no change to security settings.
+
+## Commits and PRs
+
+- Conventional, imperative English subjects, e.g. `fix(file): classify oversized grep files`.
+- A PR links a claimed issue, fills `.github/PULL_REQUEST_TEMPLATE.md`, and puts real command output
+  (pass/skip/fail counts) in its Validation section.
+- Add a `docs/CHANGELOG.md` `## [Unreleased]` entry when behaviour or shipped docs change.
+- Never force-push shared branches, rewrite pushed history, or merge PRs without the maintainers.
+
+## Windows notes
+
+- Run `npm`/`git` from PowerShell if the Git Bash environment resolves `npm` to WSL or lacks the git
+  identity/CA bundle.
+- A local `tar` may fail to unpack the packed tarball on non-ASCII doc filenames; CI is the reference
+  for that gate step.