dsh-super-code 0.3.8 → 0.3.10

package/docs/en/EvaluationResults.md

@@ -0,0 +1,240 @@
+# Evaluation Results
+
+[中文](../EvaluationResults.md) · English
+
+## Pro100: continuous-environment comparison
+
+All runs use Harness `0.2.1-rc.2`, `deepseek-v4.1-flash-1017`, high reasoning effort, and legacy budgets. Each group reuses its environment continuously across tasks. These are full 100-task results, sorted by tasks passed.
+
+| Configuration | Passed/valid | Mean total tokens (M) | Mean time (min) | Mean model calls | Mean tool calls | Cache rate |
+|---|---:|---:|---:|---:|---:|---:|
+| Super Code 0.3.5 | **51/100** | 6.435 | 24.751 | 76.660 | 75.840 | 98.927% |
+| Official Standard | 50/100 | 8.030 | 17.198 | 91.990 | 113.880 | 99.167% |
+| Unmodified dsh-ops 0.4.4 · Standard | 49/100 | 7.099 | 23.132 | 82.500 | 102.360 | 99.062% |
+| Official Standard + billion-context 0.1.209 | 45/100 | 6.359 | 18.471 | 108.950 | 131.140 | 97.654% |
+| Unmodified dsh-ops 0.4.4 · PTC | 44/100 | 7.322 | 23.695 | 81.490 | 80.960 | 99.056% |
+
+M means one million tokens, including reasoning tokens. Time includes some in-run service waits. Super Code `0.3.5` is the continuous legacy-budget baseline for this batch.
+
+This batch uses different environment-reuse and time-accounting conventions from the historical budget experiments below. They remain separate; pass counts, times, and efficiency percentages are not mixed. The historical `49/100` and `46/100` results are from earlier runs, rather than the `51/100` and `50/100` in this table. Existing per-task files still describe their original runs.
+
+## Evaluation design
+
+### Task set
+
+SWE-bench Pro hard-100 (frozen ID `swebench-pro-hard-100-ddd22492f1c38839`), graded with the official grader.
+
+- "hard-100" is this project's selection of 100 tasks by an existing difficulty method, not an official hardest-100 list.
+- Tuning uses only 33 valid hard tasks selected from the SWE-bench dev split. hard-100 is used only to evaluate frozen candidates and investigate issues, **never for tuning**, to avoid overfitting to the evaluation tasks.
+- The historical scores below include later reviews (see [Grading corrections](#grading-corrections)); every run has 100 valid scores.
+
+### Baseline
+
+Baselines include the official Standard preset and third-party plugin configurations. The historical official-preset comparison uses Standard rather than Minimal: on the old host, Standard + high passed 51 tasks and Minimal + high passed 46, with Standard using 23.5% fewer tokens per task.
+
+### Controlled variables
+
+Comparisons on the same host keep model, reasoning effort, and budgets fixed while comparing preset and plugin combinations. Host or model changes are identified separately. The continuous-environment table above includes some in-run service waits; historical budget experiments use net time, excluding failed requests and retry waits.
+
+### Historical process
+
+1. **Old-host baseline**: official presets and plugin versions were evaluated on DSH `0.1.5-rc.2` with `deepseek-v4.1-flash`. The Super Code `0.3.0` candidate passed 56 tasks, above the best official result (Standard + high, 51).
+2. **Regression after the host upgrade**: on DSH `0.2.1-rc.2` with `deepseek-v4.1-flash-1017`, under default budgets Standard fell to 46 and Super Code `0.3.4` to 41, below Standard.
+3. **Root-cause analysis**: a host probe showed that the new host tightened context budgets (see [Contents of the legacy budgets](#contents-of-the-legacy-budgets)), identifying budgets as one cause of the regression.
+4. **Retest with legacy budgets**: both sides switched to legacy budgets. Standard stayed at 46; Super Code `0.3.5` rose to 49. Based on this, the plugin uses legacy budgets by default from `0.3.6`.
+5. **Cross-model check**: compared with native ZCode on `glm-5.3-flash` to test whether the approach depends on a specific model.
+
+## Historical summary
+
+| Comparison | Result |
+|---|---|
+| New host, both on legacy budgets: Super Code `0.3.5` vs Standard + high | 49 vs 46; net time -21.3%, tokens -34.6%, model calls -25.5% |
+| New host, default → legacy budgets | Super Code 41 → 49; Standard 46 → 46 |
+| Old host: Super Code `0.3.0` candidate vs best official (Standard + high) | 56 vs 51 |
+| Old host: Super Code `0.3.0` candidate vs Minimal + high | 56 vs 46; time -47.6%, tokens -44.9% |
+| GLM-5.3-flash: Super Code `0.3.4` vs native ZCode | 45 vs 29; time -37.1%, tokens +52.4% |
+
+## New DSH and budgets
+
+DSH `0.2.1-rc.2` · model `deepseek-v4.1-flash-1017` (API ID `deepseek/deepseek-flash`) · high.
+
+| Metric (per-task mean) | Standard · default | Super Code 0.3.4 · default | Standard · legacy | Super Code 0.3.5 · legacy |
+|---|---:|---:|---:|---:|
+| Passed | 46/100 | 41/100 | 46/100 | **49/100** |
+| Net minutes | 17.875 | 20.364 | 20.870 | 16.416 |
+| Model calls | 85.050 | 68.810 | 91.980 | 68.540 |
+| Total tokens | 6,832,805.820 | 5,088,673.550 | 7,806,295.960 | 5,108,386.410 |
+| Cached input tokens | 6,710,566.400 | 4,972,166.400 | 7,679,298.560 | 4,993,935.320 |
+| Uncached input tokens | 59,268.620 | 55,138.870 | 59,291.340 | 52,906.560 |
+| Output tokens | 62,970.800 | 61,368.280 | 67,706.060 | 61,544.530 |
+| Requests without usage | 0 | 0 | 0 | 1 |
+
+- **Standard**: legacy budgets left the pass count unchanged and used 14.2% more tokens. Per task: 7 gains, 7 regressions.
+- **Super Code**: legacy budgets passed 8 more tasks with only 0.4% more tokens and 19.4% less net time. Per task: 12 gains, 4 regressions.
+- The two plugin runs used different versions (0.3.4 → 0.3.5), so not all of the gain can be attributed to budgets.
+- The legacy-budget plugin run is `0.3.5` with explicit overrides. These budgets are the default from `0.3.6`, but there is **no** separate 100-task run of 0.3.6–0.3.8.
+- The Standard legacy-budget run only overrides host budgets; Super Code is not loaded.
+
+### Contents of the legacy budgets
+
+They restore the `0.1.5-rc.2` context policy: measure against the full window, compress at 80%, keep the latest 16% verbatim, cap summaries at 8,192 tokens, one extra compression attempt and one overflow retry. On newer hosts, the default and maximum PTC deadlines are 600 seconds. Several settings were restored together; this is not a single-parameter experiment. [How to configure](UsageGuide.md#runtime-budgets)
+
+A [host probe](../../eval/results/swebench-pro-final-100/HostBudgetDiagnostics.json) with a fixed 1,000,000-token window and 384,000 reserved output tokens measured:
+
+| | Old | New |
+|---|---:|---:|
+| Compression threshold | 800,000 | 550,464 |
+| Verbatim retention | 160,000 | 98,560 |
+| Summary request cap | 8,192 | 65,536 |
+
+Summary instructions are identical in both. The probe used deterministic summaries, so it does not measure summary quality or show that every task triggered these changes.
+
+### Regression of the newer combination
+
+Compared with the old host and model, Standard fell from 51 to 46 and Super Code from 56 (0.3.0 candidate) to 41 (0.3.4). Host, model, and plugin changed together. Budgets are one identified cause, but this does not prove they explain the whole regression.
+
+The same task has passed in one run and failed in another. Because configurations also changed between runs, these data cannot estimate random variation under a fixed setup.
+
+[Per-task data for all four runs](../../eval/results/swebench-pro-final-100/HarnessRc2Results.json)
+
+## Official presets
+
+DSH `0.1.5-rc.2` · `deepseek-v4.1-flash`.
+
+| Metric (per-task mean) | Minimal + high | Minimal + max | Standard + high | Standard + max | PTC + high | Create + high |
+|---|---:|---:|---:|---:|---:|---:|
+| Passed | 46/100 | 50/100 | **51/100** | 50/100 | 47/100 | 49/100 |
+| Raw minutes | 25.685 | 32.529 | 20.683 | 20.389 | 17.302 | 19.856 |
+| Net minutes | 25.122 | 32.009 | 18.826 | 19.507 | 15.122 | 18.714 |
+| Median net minutes | 25.598 | 32.167 | 16.639 | 16.878 | 13.455 | 16.452 |
+| P90 net minutes | 41.658 | 45.179 | 36.681 | 33.834 | 25.031 | 30.104 |
+| Model calls | 124.660 | 138.920 | 92.370 | 101.260 | 71.160 | 93.600 |
+| Top-level tool calls | 127.360 | 150.070 | 110.480 | 124.940 | 70.990 | 113.780 |
+| Total input tokens | 11,477,169.950 | 14,849,497.540 | 8,771,693.040 | 11,434,388.180 | 6,160,934.650 | 9,205,287.290 |
+| Total tokens | 11,578,046.900 | 14,966,097.260 | 8,854,513.910 | 11,543,772.990 | 6,238,434.510 | 9,292,949.400 |
+| Cached input tokens | 11,404,101.120 | 14,770,140.160 | 8,713,578.230 | 11,366,136.320 | 6,099,266.510 | 9,145,025.240 |
+| Uncached input tokens | 73,068.830 | 79,357.380 | 58,114.810 | 68,251.860 | 61,668.140 | 60,262.050 |
+| Output tokens | 100,876.950 | 116,599.720 | 82,820.870 | 109,384.810 | 77,499.860 | 87,662.110 |
+| Input cache hit rate | 99.363% | 99.466% | 99.337% | 99.403% | 98.999% | 99.345% |
+| Retry minutes excluded (total) | 56.323 | 51.936 | 185.717 | 88.220 | 217.996 | 114.226 |
+| Requests without usage | 3 | 11 | 4 | 0 | 5 | 2 |
+
+- Create keeps the official tools, but evaluation isolation blocks `cordis_run` from running dynamic code on the host; read-only inspection still works.
+- Minimal + high reuses a historical baseline on a different Harness revision, so differences cannot be attributed entirely to reasoning effort.
+
+[Per-task data](../../eval/results/swebench-pro-final-100/OfficialPresetResults.json)
+
+## Historical versions
+
+DSH `0.1.5-rc.2` · `deepseek-v4.1-flash` · high. Times use the historical raw convention (see [Methodology](#methodology)); don't compare them with the net times above.
+
+| Metric (per-task mean) | Minimal + high | 0.0.9 | 0.1.2 | 0.2.0 layered memory | 0.3.0 Batch.3 |
+|---|---:|---:|---:|---:|---:|
+| Passed | 46 | 50 | 53 | 54 | **56** |
+| Raw minutes | 25.685 | 16.458 | 16.011 | 15.148 | 13.461 |
+| Median minutes | 26.138 | 14.398 | 13.736 | 13.510 | 12.197 |
+| P90 minutes | 43.696 | 28.816 | 29.360 | 24.145 | 21.381 |
+| Model calls | 124.660 | 92.780 | 99.780 | 93.830 | 69.290 |
+| Top-level tool calls | 127.360 | 116.550 | 123.340 | 119.160 | 69.730 |
+| Total input tokens | 11,477,169.950 | 9,525,315.530 | 9,840,382.730 | 9,202,574.270 | 6,290,407.000 |
+| Cached input tokens | 11,404,101.120 | 9,461,981.440 | 9,775,799.040 | 9,142,005.760 | 6,231,823.360 |
+| Uncached input tokens | 73,068.830 | 63,334.090 | 64,583.690 | 60,568.510 | 58,583.640 |
+| Output tokens | 100,876.950 | 97,900.990 | 97,793.480 | 96,519.570 | 91,561.850 |
+| Total tokens | 11,578,046.900 | 9,623,216.520 | 9,938,176.210 | 9,299,093.840 | 6,381,968.850 |
+| Input cache hit rate | 99.363% | 99.335% | 99.344% | 99.342% | 99.069% |
+| Requests without usage | 3 | 8 | 1 | 1 | 0 |
+
+Relative to Minimal:
+
+| Version | Pass rate | Mean time | Total tokens | Gains | Regressions |
+|---|---:|---:|---:|---:|---:|
+| 0.0.9 | +4 pp | -35.9% | -16.9% | 7 | 3 |
+| 0.1.2 | +7 pp | -37.7% | -14.2% | 10 | 3 |
+| 0.2.0 | +8 pp | -41.0% | -19.7% | 11 | 3 (37, 396, 503) |
+| 0.3.0 Batch.3 | +10 pp | -47.6% | -44.9% | 13 | 3 |
+
+- 0.3.0 vs 0.2.0: time -11.1%, tokens -31.4%, model calls -26.2%, passes 54 → 56 (8 gains, 6 regressions). One run; a net gain of two is not a stable improvement.
+- 0.2.0 vs 0.1.2: time -5.4%, tokens -6.4%, passes 53 → 54 (7 gains, 6 regressions). Better overall does not mean every earlier pass held.
+- One PTC call can run several operations, so top-level tool calls don't measure how many files were read or commands run.
+
+Candidate identity:
+
+- **0.2.0** is the frozen layered-memory candidate. Its package still carried version 0.1.3, SHA-256 `164cc1b505c05288f01b6f12c0756af049dbde8f1a49bdb11f9a320a19c925f5`.
+- **0.3.0** is the installed candidate with internal version `0.3.0-batch.3`. The release package was checked file by file against the frozen runtime modules and passed unit tests and real-host regression; the 100 tasks were not rerun.
+- Both share Harness commit `649bfcddf0e3532510a38380b9620570d8b13818`, but prompt changes and tool presentation still can't be separated. Memory tools were triggered only occasionally, so differences can't be attributed to memory alone.
+
+[Four-version per-task data](../../eval/results/swebench-pro-final-100/CorrectedFourVersions.json) · [Batch.3 per-task data](../../eval/results/swebench-pro-final-100/Batch3Results.json)
+
+## Cross-model
+
+`glm-5.3-flash` · max. Super Code `0.3.4` on DSH `0.1.5-rc.2`, versus the complete native ZCode Desktop `3.14.4` / CLI `0.16.9` (not an extracted Agent).
+
+| Metric (per-task mean) | DSH + Super Code 0.3.4 | Native ZCode |
+|---|---:|---:|
+| Passed | **45/100** | 29/100 |
+| Net minutes | 32.896 | 52.320 |
+| Model calls | 66.890 | 64.310 |
+| Total tokens | 5,499,154.470 | 3,609,511.930 |
+| Cached input tokens | 5,302,796.160 | 3,356,862.720 |
+| Uncached input tokens | 126,050.640 | 144,405.020 |
+| Output tokens | 70,307.670 | 108,244.190 |
+| Requests without usage | 29 | 120 |
+
+This shows the approach also works on GLM. It compares two complete systems, so it doesn't isolate the plugin's contribution or generalize to all models.
+
+[Per-task data](../../eval/results/swebench-pro-final-100/GLMComparison.json) · [Execution scripts](../../eval/glm/README.md)
+
+## Grading corrections
+
+Every correction regrades an **original answer** or restores an omitted export row. No model was asked to answer again. Original verdicts, patch hashes, usage, and timing are kept.
+
+### 2026-10-21 to 23
+
+| Run | Before | After | Date |
+|---|---:|---:|---|
+| Super Code 0.3.4 · default | 40/99 | 41/100 | 10-21 |
+| Super Code 0.3.5 · legacy | 48/99 | 49/100 | 10-21 |
+| Standard high · default | 45/100 | 46/100 | 10-22 |
+| Standard high · legacy | 46/100 | 46/100 | 10-22 |
+| GLM Super Code 0.3.4 | 44/100 | 45/100 | 10-22 |
+| GLM native ZCode | 28/100 | 29/100 | 10-22 |
+| Standard max · DSH 0.1.5-rc.2 | 49/99 | 50/100 | 10-23 |
+
+- The first six are the same NodeBB task. After fixing offline dependency setup (base fails, reference passes), each run's original patch was graded twice; only complete, matching results count. Only four exact quote/space test-name differences are accepted; assertions, timeouts, and statuses are unchanged, and grading runs offline. Standard with legacy budgets still has a real failure, so it's unchanged.
+- Standard max restores Teleport task 610: its original grade was a pass but was missing from the export.
+
+[Correction evidence and original hashes](../../eval/results/swebench-pro-final-100/GradingReconciliation.json)
+
+### Earlier reviews
+
+| Version | Original passes | Corrected | Environment regrades |
+|---|---:|---:|---:|
+| Minimal | 41 | 46 | 4 |
+| 0.0.9 | 46 | 50 | 3 |
+| 0.1.2 | 49 | 53 | 4 |
+| 0.2.0 | 48 | 54 | 5 |
+
+- **Environment failures**: 16 records hit issues such as a ConfigFileTest 500 ms timeout or a SIGKILLed Jest worker. Each was regraded with its original patch and needed two matching, clean results — **not** retried until it passed. 12 recovered, 4 still failed.
+- **Dependency downloads**: 12 Node build-dependency download failures in the official-preset runs, same rule: 11 recovered, 1 still failed.
+- **Test-name mismatches**: 31 records differed only in test names (16 dynamic-year cases in OpenLibrary, 15 trailing quote/space cases in NodeBB). All raw tests passed and every missing required name mapped exactly. Only these two mappings are accepted; no fuzzy matching, no borrowing results from other versions.
+- **Older experiments**: 7 newly found environment failures were regraded: 3 recovered, 4 still failed. Three other old records (early Minimal task 4, old Graph task 623, and old Graph task 99, which had copied task 378's metadata) were found and reviewed. None are in the published scores, which are unchanged.
+
+### Review coverage
+
+- All 3,296 Pro / Dev primary records had their raw logs reparsed (this counts retained duplicates, not unique tasks). All 1,212 Dev verdicts agree. All 400 published four-version records bind exactly to their original summaries and grading logs.
+- For 3,224 records, request ledgers match summaries (calls, tokens, missing usage) with no duplicate request IDs; 72 have no saved ledger.
+- This is not a full audit of every raw session or provider bill.
+
+[Per-record review](../../eval/results/swebench-pro-final-100/GradingReviewResults.json)
+
+## Methodology
+
+- **Net time**: excludes failed requests and retry waits in the final valid answer; excludes grading.
+- **Raw time** (historical table): Web RPC time of the final valid answer, excluding grading, image downloads, and regrading, but without subtracting internal failed requests or retries. The median averages the 50th and 51st values; P90 is the 90th. An older 0.0.9 document said 16.27 minutes; the unified convention gives 16.458.
+- **Call counts**: exclude logged failed requests.
+- **Tokens**: total = cached input + uncached input + output (including reasoning). Cache hit rate = all cached input / all input, not a per-task average. Summed per task, then averaged over valid tasks.
+- **Missing usage is not estimated**, so tokens are not a full bill and exclude earlier abandoned attempts.
+- **Execution**: DSH via native Web RPC; ZCode via its complete native CLI.
+- **Privacy**: public data keeps only fields needed for auditing — no private provider addresses, credentials, environment configuration, local paths, or verbatim user messages. Per-task result files stay in the repository, not the npm package.
+
+[All result tables](../../eval/results/swebench-pro-final-100/ResultsTables.md) · [Result files](../../eval/results/swebench-pro-final-100/README.md)

package/docs/en/UsageGuide.md

@@ -0,0 +1,321 @@
+# Usage Guide
+
+[中文](../UsageGuide.md) · English
+
+New here? Read the Install and Use sections of the [README](../../README.en.md) first. This page covers the details.
+
+- [Model](#model)
+- [Can't find the preset](#cant-find-the-preset)
+- [Settings](#settings)
+- [Preset version and reinstall](#preset-version-and-reinstall)
+- [Sidebar](#sidebar)
+- [Batched tool calls](#batched-tool-calls)
+- [Runtime budgets](#runtime-budgets)
+- [Windows command environment](#windows-command-environment)
+- [Deletion protection](#deletion-protection)
+- [MCP connection](#mcp-connection)
+- [Frontend Skill](#frontend-skill)
+
+## Model
+
+The plugin has no model settings of its own. If you already have a working model, just use it. Otherwise add a provider under Harness **Settings → Models**, then pick a model and reasoning effort below the message input.
+
+Child Agents use the parent's model by default. Harness manages permissions and tools.
+
+## Can't find the preset
+
+First make sure the plugin is enabled, then check your host version against [Compatibility](Compatibility.md). Then:
+
+**Harness 0.1.7 and later (declarative presets)**: the plugin declares the preset and the host loads it. Go to **Settings → Super Code** and click **Install preset**. If the host doesn't expose management APIs, the page says so.
+
+**Harness 0.1.5 / 0.1.6 (directory presets)**: the plugin installs a user copy on first load. If it's missing, install it manually from **Settings → Super Code**.
+
+- If the default identifier `super-code` is taken, pick another one. Existing presets are never overwritten.
+- If you delete this copy yourself, a restart won't bring it back. Install it again manually.
+
+Before plugin 0.2.0, the settings page lives under **Plugins → Plugin configuration**.
+
+## Settings
+
+**Settings → Super Code** has five tabs:
+
+| Tab | Contents |
+|---|---|
+| Home | Preset status and versions, deletion-protection level, MCP switch, connected/past conversation counts |
+| Preset configuration | Install, reinstall, rename, Windows command environment |
+| Context settings | [Runtime budgets](#runtime-budgets) |
+| Deletion protection | [Deletion protection](#deletion-protection) |
+| Connection | [MCP connection](#mcp-connection) |
+
+Switching tabs keeps unsaved input.
+
+### Names and language
+
+- The identifier selects the preset; the display name can be changed separately. Chinese characters and spaces are fine, up to 120 characters.
+- Default names and descriptions follow Harness's Chinese/English setting. Fields you've edited are left alone.
+- Changing the language only updates display fields, not preset content or version.
+- Older Harness versions cache the preset list, so the page reloads once when the wording changes.
+- Preset files on one host share one language; different clients can't show different languages at the same time.
+- A read-only install directory or YAML the plugin can't safely parse may block syncing. Refresh and retry from Settings.
+
+## Preset version and reinstall
+
+Settings shows the **plugin version** and the **preset version** separately.
+
+- Same version: the preset matches the installed plugin. It doesn't mean there's no newer release on npm.
+- Old preset without a version: shows "Version not recorded" and isn't treated as current.
+- Updating the plugin doesn't update an installed preset. To get the new preset, reinstall.
+
+**Reinstall**: click **Reinstall preset** → the dialog lists the presets to be replaced plus the new name and identifier → check and confirm.
+
+- You can remove entries, but not confirm an empty list. Cancel or Esc changes nothing.
+- Reinstalling overwrites the old preset. Save your customizations first.
+- Existing sessions keep the old preset; new sessions use the new one.
+
+**Safety**:
+
+- Only presets verifiably installed by this plugin are replaced (directory: install record, UUID, path, directory identity; declarative: source marker or install record). Unmarked old copies and same-name declarations are left alone.
+- The old content is backed up in `.super-code-backup-*`: under the user preset root for directory hosts, under the current profile for declarative hosts (ownership records in `.super-code-presets.json`).
+- A failed install restores automatically. After an unexpected crash, restore manually from the backup.
+
+## Sidebar
+
+In the right sidebar choose **Super Code**. Three sections, at most one open at a time, Tasks by default. Click the open heading to collapse all sections. Switching keeps reading position, filters, and drafts. The UI follows Harness's Chinese/English setting.
+
+### Tasks
+
+Read-only. Shows what's already recorded in the session:
+
+- **Goal**: the recorded task goal, or the user's original message if there is none.
+- **Steps**: todos the model wrote down, shown as done/total. No steps means no invented plan or progress.
+- **Tool calls**: success, failure, and running counts grouped by tool.
+- **Files**: successful file changes that can be confirmed from tool arguments or diffs, including nested PTC calls.
+
+Notes:
+
+- A stopped run doesn't mean the task is done.
+- The file list isn't a full Git diff: indirect changes from the terminal or external scripts may be missing, and a past change doesn't mean the file still differs. Failed, pending, read-only, and inherited child-Agent operations don't count.
+- Everything is expanded in a virtual list, so long histories stay smooth. There is a display limit; you'll see a notice when it's hit, and full content is in the details.
+- It doesn't change prompts, model requests, or tool definitions, and writes nothing into model context.
+
+### Agent execution
+
+The Agent tree, with status, usage, and cache rate for each Agent.
+
+- Drag empty space to pan; zoom with the wheel or buttons.
+- Click a node to open its details in a new sidebar tab. The main conversation stays put.
+- Details are shown as a chat: user task, Agent replies, expandable tool calls and results. The header shows status, tokens, and cache; open **Details** for more usage, task records, and memory activity.
+- Running animations respect the system's reduced-motion setting.
+
+The [task](../images/task-status.png) and [tree screenshots](../images/agent-tree.png) render the current plugin with official frontend components and sample data. They illustrate the UI, not model quality.
+
+### Memory library
+
+Pick **This project** or **Global preferences**, then browse by topic or search (topic, summary, identifier). Click an entry for details and source. You can add, edit, and delete (with confirmation). Manually edited entries are marked as manual, with current content only and no version history.
+
+Memory has three layers:
+
+| Layer | What it keeps | Scope |
+|---|---|---|
+| Task state | Current goal, constraints, progress, checks | Current conversation |
+| Project memory | Sourced project facts, lessons, agreements | Same workspace path, by topic |
+| Global preferences | Preferences you explicitly want across projects | Same Harness storage root |
+
+- To keep an agreement long-term, just tell the Agent. It's saved when the tool reports success and it shows up in the library.
+- Project memory saved by an Agent must link to a real tool result; global preferences need your own words and a clear cross-project intent.
+- Projects at different paths, including Git worktrees, don't share project memory.
+- Memory lives in local host storage, not in project files, and the whole library is never sent to the model. At most 4 summaries from the current topic (≤2 KiB) and 4 from global preferences (≤1 KiB) are included automatically; details require an explicit read.
+- Memory can't override the current request, grant permissions, or prove code is unchanged since it was recorded.
+- You can browse memory from past sessions without resuming an Agent or calling the model.
+
+### Which memory each Agent used
+
+Click a node in the tree → open **Details** → expand **Memory activity**. It distinguishes context inclusion, summary reads, detail reads, saves, and deletions. Click a record to jump to that entry in the library.
+
+- These are actions recorded by the host, not proof that the model understood or followed them.
+- History a child Agent inherits from its parent doesn't count as its own read; failed calls don't count as reads.
+- Up to the latest 100 are shown; the full record is in the session log.
+- If an entry is later edited or deleted, the record stays, but the library only shows current content.
+
+## Batched tool calls
+
+Super Code uses Harness-native PTC: one model call can combine several tool operations, such as reading a few unrelated files at once, then decide what to do next. No separate mode needed.
+
+- Independent reads run in parallel; writes, tests, state changes, and dependent steps run in order.
+- On partial failure, successful results are kept and only failed or stale reads are retried.
+- The plugin declares which of its task and memory actions can run in parallel; unknown actions run alone. Other tools follow their own Harness declarations.
+- The host handles permissions, cancellation, and result storage.
+
+Batching cuts round trips between the model and tools. It doesn't make every operation faster.
+
+## Runtime budgets
+
+Under the **Context settings** tab. The plugin already uses the better-performing legacy budgets, so you usually don't need to touch this. Values in parentheses are the host's own defaults, for comparison.
+
+| Type | Includes | Applies to |
+|---|---|---|
+| Common budgets | Compression ratios, summary cap, PTC deadlines, retries | Super Code by default; also Standard, PTC, Minimal, and Create when "Also apply to official presets" is on |
+| Super Code only | Active task record limit, task-memory capacity | Super Code only |
+
+- "Also apply to official presets" is off by default. It only changes budgets, not official tools or prompts, and never touches custom presets.
+- Saved changes apply to new Agents. Running Agents keep their settings and aren't restarted.
+- Leave a field blank to use the plugin default; **Reset to defaults** clears UI overrides.
+- A failed save keeps your input. If it says budgets were changed elsewhere, reload first.
+- On older hosts without `ptcRuntime`, PTC deadline fields are disabled; other budgets still work.
+
+Plugin defaults (no need to add them to your config; only write the fields you want to change):
+
+```yaml
+budgets:
+  pressureBasis: window      # use the full context window; "host" follows the host policy
+  thresholdRatio: 0.8        # start compressing at 80%
+  retainRatio: 0.16          # keep the latest 16% verbatim; must be below thresholdRatio
+  summaryMaxTokens: 8192     # summary cap
+  compactionRetries: 1       # extra compression attempts
+  maxOverflowRetries: 1      # overflow retries
+  ptcTimeoutMs: 600000       # default PTC deadline (ms, including tool waits)
+  ptcMaxTimeoutMs: 600000    # PTC deadline cap, never above the host cap
+applyToOfficialPresets: false
+maxTasks: 32                 # Super Code: active task records
+maxContextBytes: 32768       # Super Code: task-memory context bytes
+```
+
+- A shorter deadline set explicitly on a call still applies.
+- Older hosts time PTC by busy CPU time; newer hosts by elapsed time. The two aren't comparable.
+- Raising `maxTasks` or `maxContextBytes` uses more context. The defaults are usually fine.
+
+## Windows command environment
+
+See [Compatibility](Compatibility.md) for the tested scope.
+
+On Windows, Super Code defaults to bundled GNU Bash, BusyBox and GNU grep. Common Bash commands work without installing Git for its shell. Developer tools such as Git, Node and Python still need separate installation. macOS and Linux keep the host's existing environment.
+
+Turn off **Preset configuration → Command environment → Use bundled Bash (Windows)** to use the host's PowerShell for new conversations. Changes save automatically; running Agents retain their environment, and child Agents inherit their conversation's shell and tool restrictions. Reinstall an older installed preset to pick up the new shell entry. Selection follows the DSH server's platform, independently of the browser's operating system. These switches are editable only on Windows hosts; other platforms show gray, disabled switches with an **Only available on Windows** hover tooltip.
+
+Enable **Also apply to official presets** in the same section to use bundled Bash in Standard, PTC and Create; it is off by default. This choice is independent of the budget and deletion-protection scopes. Turning off the main Bash switch also restores the original shell for new official Agents while retaining the saved scope choice. Minimal keeps its persistent terminal; custom presets are not changed automatically. Official presets can use this setting without an installed Super Code preset copy.
+
+The plugin carries its runtime and prepares it offline under `%LOCALAPPDATA%\dsh-super-code\shell` on first use. It does not change the system PATH. Settings shows readiness and preparation errors; turn the switch off to use the host environment after an error. Failed commands are never replayed through a different shell. DSH continues to own approvals, deletion protection and process management.
+
+The official Windows sandbox blocks the internal named pipes MSYS requires. Bash calls under `read-only` or `workspace-write` therefore fail explicitly before the command runs. If still needed, the Agent can request DSH approval for the **exact same command** with `sandbox_permissions="danger-full-access"` and a justification. Approval permits only that invocation; rejection, cancellation, or disabled approvals leave it unexecuted. The plugin never changes session permissions or switches shells automatically. If the outer PTC `run_code` program also needs wider access, it requires its own host approval; approving Bash does not authorize that outer program.
+
+Programs still run on Windows. BusyBox does not implement every GNU option; `.cmd` quoting and native `/` arguments differ from Linux. MSYS converts some paths automatically. Use `MSYS2_ARG_CONV_EXCL` for an individual invocation that needs literal arguments rather than disabling conversion globally. The bundle does not include `trash`, and permanent deletion is never presented as a recycle-bin operation. On ARM64 Windows, Bash, grep and the MSYS DLLs run through x64 emulation. See [Compatibility](Compatibility.md) for tested scope and the [runtime notes](../../runtime/windows/README.md) for sources and licenses.
+
+## Deletion protection
+
+Under the **Deletion protection** tab. Default is **Relaxed**.
+
+| Mode | Behavior |
+|---|---|
+| Off | No instructions, no blocking |
+| Relaxed (default) | Tells Agents to delete with recoverable `trash`, in scripts too. If you explicitly ask for `rm`, it's used without extra plugin confirmation |
+| Strict | No direct `rm`, even in scripts. Recognized permanent deletions need your approval each time, and only temp-file or build-artifact cleanup is allowed |
+
+The exact Relaxed instruction: **Delete files or directories with `trash <path>` (recoverable) by default; use `rm` only for temp files or build artifacts after I've confirmed.**
+
+- Only Super Code is protected by default. "Also apply to official presets" is off by default (independent of the budget switch with the same name).
+- Saved changes apply to later commands.
+- Legacy `true` means Strict, `false` means Off.
+
+Strict mode checks terminal commands before they run for `rm`, common wrappers, inline shell scripts, and PowerShell deletion commands such as `Remove-Item`, including terminal calls inside PTC.
+
+- Only a one-time host approval that you accept lets it through; rejection, cancellation, and errors all block. Each approval covers that one call.
+- If `trash` isn't available, the Agent should use another recoverable method or stop.
+- It isn't an OS sandbox: it doesn't inspect external script files, obfuscated programs, or every language's delete API. Use the host sandbox for process-level isolation.
+
+Relaxed mode relies on instructions only and blocks nothing. Host permission checks still apply.
+
+## MCP connection
+
+Lets external MCP clients (such as other AI coding tools) hand tasks to DSH. Off by default, listens on `127.0.0.1` only, uses Streamable HTTP with token auth.
+
+### Turn it on
+
+Under the **Connection** tab:
+
+1. Check the working directories to allow (subdirectories included).
+2. Adjust the port and maximum connections if needed.
+3. Turn the switch on. Changes save automatically.
+
+**Allow MCP to create conversations** is on by default. Turning it off requires explicit reuse. New conversations join the existing workspace; an unregistered directory gets a workspace with the same name and no suffix. New titles start with `[MCP]`.
+
+**Allow caller approval** is off by default. When enabled, an exact one-time tool approval for a delegated task can be sent to the caller through an interactive form or `dsh_approve`. Host policy remains authoritative, and directory consent always stays in DSH.
+
+Directories:
+
+- The DSH workspace list is reread every time you open the tab. On first setup, existing workspaces are preselected; workspaces added later are **not** granted access automatically.
+- Add directories with the directory picker. Uncheck to revoke; unchecking the last one also turns MCP off.
+
+Connections:
+
+- Maximum connections defaults to 3, up to 32, and is also the task concurrency limit.
+- Disconnect clients from the Connection tab; idle connections drop after 10 minutes. Disconnecting doesn't cancel accepted tasks.
+- "Connected conversations" on Home means the linked MCP connection is still online, regardless of whether the task finished. After disconnect they count as past conversations.
+
+Port conflicts are reported directly. Use the URL shown on the page.
+
+### Configure the client
+
+1. Copy **Connection Prompt** from the Connection tab and give it to a client that supports Streamable HTTP MCP. It includes the URL, auth method, and tool notes, but **not** the real token.
+2. Copy the token separately and configure it in the client as `Authorization: Bearer <token>`. Don't put the token in a repository or a shared prompt.
+3. Keep DSH running. Rotating the token invalidates the old one immediately; update the client.
+
+Whether a client can set up MCP from the prompt by itself depends on the client. You can also enter the URL and auth manually. The token is shown by default on the Connection tab and hidden when you leave.
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `dsh_status` | Inspect directories, policies, capacity, blocking tasks, and recovery guidance |
+| `dsh_models` | List exact model/effort IDs for `dsh_run` and `dsh_send`; omission retains the current/default selection |
+| `dsh_read` | Page through owned conversations and managed children, including public messages, tool results, and failure details; excludes reasoning and private configuration |
+| `dsh_approve` | Approve or reject one exact pending operation only when caller approval is enabled |
+| `dsh_sessions` | Call first after connecting: lists recent conversations per directory with status, whether they can be reused, connection capacity, and task concurrency |
+| `dsh_run` | Start a task. Pass `taskId` to reuse a specific conversation, or `newConversation: true` for a new one (passing neither also creates new). It **never** picks the latest conversation on its own. Same `requestId` + same input won't dispatch twice; different input is a conflict |
+| `dsh_wait` | Read task status, output, workspace changes, and new events, waiting up to 30 seconds. Without a task ID, lists all tasks page by page |
+| `dsh_send` | Add a follow-up or continue in the same conversation, with a new `requestId`. Never approves permissions for you |
+| `dsh_request_directory` | Ask for a new working directory; you approve it in DSH |
+| `dsh_cancel` | Request cancellation of the conversation and its child tasks. Keep checking status to confirm it actually stopped |
+
+### Requesting a new directory
+
+The client calls `dsh_request_directory` with a `requestId`, an existing absolute `path`, and a `reason`. DSH shows a global dialog (Settings doesn't need to be open) with the client name, directory, and reason.
+
+- Access is granted only when you click **Allow access**. A model's auto-approval can't do it for you.
+- Repeat the same call to check status: `pending` / `approved` / `rejected` / `expired`.
+- Tasks can't run in that directory until it's approved.
+- At most 8 pending requests, expiring after 5 minutes. Rejection, stopping the service, or restarting never grants access.
+- Client name and reason are filled in by the client; treat them as hints only.
+
+### Task status and recovery
+
+- Tasks use the conversation's current or explicitly selected model, the Super Code preset, and your permissions. Model/effort choices persist in that conversation. Permissions are never auto-approved.
+- The client's sandbox doesn't carry over to DSH. Allowed directories only control where tasks can start; they aren't a file sandbox.
+- Tasks in the same workspace don't run in parallel. For parallel work, prepare separate worktrees yourself; the plugin doesn't create, delete, or merge worktrees.
+- `waiting_confirmation`: the caller can decide only when caller approval is enabled and an exact pending request exists; otherwise the user handles it in DSH.
+- `finished`: execution ended, but `acceptance` is always `not-verified`. The caller must check the result.
+- Returned file info is an observation of the Git workspace, including changes that existed before the task, so it doesn't prove the task made them. Non-Git directories or exceeded limits are marked unavailable.
+- Wait timeouts and client disconnects don't cancel tasks. Turning off the connection just stops new requests.
+- After a restart, prompts are never resent automatically. Find the ID via `dsh_sessions` or the task list, check the state, then continue explicitly. If the state can't be confirmed, it shows `interrupted` or `unavailable`; tasks not confirmed as stopped keep their concurrency slot.
+
+On capacity refusal, retain the same `requestId` and input and wait through `dsh_status` and `dsh_wait`. Do not cancel other clients' tasks or reconfigure the serving app. Release SDK sessions with `transport.terminateSession()` before `client.close()`; closing alone does not release server capacity. The packaged `super-code-mcp` CLI accepts JSON on stdin and reads its token from the private `DSH_MCP_TOKEN` environment variable.
+
+### Storage and limits
+
+- Task records, settings, and the token are stored in the profile's `super-code-connection` directory (directory 0700, files 0600). One service instance per profile.
+- Limits: 200 task records, 128 follow-ups per task, the latest 200 events, the last 12,000 output characters. Directory-request history keeps up to 100 entries, in memory only.
+- When task records are full, new tasks are rejected explicitly; old records are never dropped silently.
+
+## Frontend Skill
+
+The plugin ships `super-code-frontend`, used for pages, components, visual tweaks, responsive layout, interaction states, and browser checks. It focuses on:
+
+- whether elements line up on the same edges
+- whether what you see matches what you can click
+- whether controls stay put, are easy to reach, and need little input
+
+It keeps the project's own visual style, needs no particular framework, and adds no tools. Normally only its name and short description go to the model; the body and relevant references load when a task matches. You can also ask for it directly: "use super-code-frontend".
+
+- Only presets installed or reinstalled from 0.3.3 onward include it. For existing presets, back up your customizations, then reinstall.
+- A project or user skill with the same name overrides the bundled one, following host precedence.
+- The browser-check part is guidance only: no enforced loop detection, no automatic long-term memory writes.
+- Whether it improves frontend quality needs a separate real-task evaluation; install tests and SWE scores can't show that.

package/lib/connection/approvals.d.ts

@@ -0,0 +1,21 @@
+import type { CallerApproval, CallerApprovalDecision } from './types.js';
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+export type ApprovalAnswer = ApprovalOutcome | 'host';
+export declare class CallerApprovals {
+    private readonly now;
+    private readonly requests;
+    private readonly settled;
+    private readonly presenting;
+    constructor(now?: () => number);
+    request(input: Omit<CallerApproval, 'id' | 'createdAt' | 'expiresAt'>, signal?: AbortSignal): Promise<ApprovalAnswer>;
+    private expire;
+    pending(taskId: string): CallerApproval[];
+    present(taskId: string, id: string): boolean;
+    defer(taskId: string, id: string): void;
+    decide(taskId: string, id: string, decision: CallerApprovalDecision): {
+        outcome: ApprovalOutcome;
+        repeated: boolean;
+    };
+    withdraw(taskId?: string, answer?: ApprovalAnswer): void;
+}
+//# sourceMappingURL=approvals.d.ts.map

package/lib/connection/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/connection/approvals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAExE,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;AACxF,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;AAEtD,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0E;IAClG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAClB,GAAG,GAAE,MAAM,MAAiB;IACnD,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IAkB3H,OAAO,CAAC,MAAM;IAGd,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE;IAIzC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAM5C,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAIvC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE;IAgBrH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,cAAuB,GAAG,IAAI;CAGjE"}