dsh-scratch-vault

Codex-style scratch execution for DeepSeek Harness — operation scripts run outside the workspace, and get collected in the plugin.

English | 中文

A DSH plugin that keeps agent workspaces to deliverables. The throwaway probes, one-off converters and diagnostics an agent writes only to run once no longer land in your repository: they execute from a session scratch root outside the workspace, and every one of them is archived in a plugin-owned vault you can list, read, promote, or purge.

before                                    after
repo/                                     repo/
├── src/                                  ├── src/
├── _probe_models.py        ← noise       ├── package.json
├── _recon_api.py           ← noise       └── (deliverables only)
├── tmp_convert.mjs         ← noise
├── apply-paths.ps1         ← noise       vault/
└── package.json                          └── entries/20261012…-a1b2c3/script

---

Why

Long-running agent tasks accumulate intermediate files. The files themselves cost nothing on disk; the cost is that every later glob, grep and directory listing has to wade through them, which pushes irrelevant content into context and makes the agent re-derive what it already did.

DSH already has most of the machinery to prevent this. Its workspace-write sandbox grants writes under the workspace root or a platform temporary root (writableRoots returns the workspace root, /tmp and os.tmpdir()), and the workspace change summary already excludes temporary roots (isTemporaryPath — "scratch paths that never enter the change summary"). What is missing is the part that routes scratch work there, and the part that remembers it.

This plugin is those two parts.

Install

dsh plugin --profile desktop add github:TINGOD2006/dsh-scratch-vault

Then restart DSH. From a local checkout:

dsh plugin --profile desktop add link:C:/path/to/dsh-scratch-vault

On Windows use forward slashes in the path, or pnpm will splice the drive letter into the profile directory and the plugin will install without activating.

Requirements: Node ≥ 22 and a DSH build that mounts the tools service. The plugin declares no dependencies at all — not even @deepseek-ai/dsh-tools. A linked plugin's bare specifiers resolve against its real path, which never reaches the profile's node_modules, so one host import is enough to make the whole plugin fail to load with nothing but failed to import to show for it. Tool definitions are therefore assembled by hand in lib/tools.js, producing exactly the shapes defineTool produces. Nothing to install, nothing to keep in sync.

Editing any file under lib/ requires a full DSH restart. The loader builds its module graph at boot and caches each module by its resolved URL, so disabling and re-enabling the bundle re-runs the cached module's apply() — it does not re-import the file.

What it does

L2 — discipline, environment, inline execution

• A system-prompt section telling the model that operation scripts belong in the scratch root, not the workspace.
• $DSH_SCRATCH and $DSH_VAULT, injected into every shell call through ctx.shellEnv. The namespace is rebuilt per shell call, so the value is always the calling session's own directory.
• run_script({ language, code, description }) — the "run it without writing a file into the workspace" tool. The program is written to a scratch file outside the workspace and executed through ctx.shell, so it runs under the session's sandbox policy. This is the right answer to "I just need to run something".

L3 — interception

tools/execute is the only seam that runs around dispatch and can therefore change what a tool body receives: the registry passes the mutable execution into the waterfall, and dispatchToolBody reads exec.arguments afterwards. (tools/pre-execute cannot do this — its decision type is allow | deny | cancel | ask, with no place to put arguments.)

When a write or edit targets a scratch script inside the workspace, its file_path is rewritten to the session scratch root, and the tool result tells the model the real absolute path plus the vault entry id. Shell commands that reference the redirected script are rewritten too.

Two properties keep this safe:

• The mapping is a pure function of the path (scratchPathFor). DSH dispatches tool calls in parallel groups, so a write and the pwsh that runs it can be in flight simultaneously; anything order-dependent would race.
• A shell token is only rewritten when the workspace file does not exist. A legacy leftover that really is on disk keeps running from disk.

The shell rewriter is deliberately conservative, because a missed rewrite costs one uncollected file while a wrong rewrite breaks a command that used to work. A token is left alone when it sits next to a glob metacharacter, extends a longer filename (x.py.bak), is part of a shell variable reference ($env:X\a.py, $DSH_SCRATCH/a.py, %TEMP%\a.py), or is relative and its working directory cannot be determined — cd $env:WORK, cd %WORK%, a bare cd (which goes to the home directory), cd ~/proj.

A relative token after an earlier cd/Set-Location/pushd is resolved against the directory that change put the shell in, not blindly against the workspace root: cd <workspace> then python _probe.py is the everyday shape and still redirects to the scratch path the write produced, while cd …\lib then Get-ChildItem notes.js refers to a real file and is left alone. Absolute paths stay unambiguous and are always redirected, drive letter included.

L4 — the vault

Every intercepted script is archived under the vault directory with a JSONL ledger, plus scratch_list, scratch_show, scratch_promote (copy one back into the workspace as a real deliverable) and scratch_purge.

scratch_import retrofits residue that was already in the workspace before the plugin existed: it collects the paths you name, verifies the vault copy byte-for-byte, and only then removes the original (keepOriginal: true keeps it, dryRun: true reports without touching either side).

Every vault write happens inside the plugin's own process, and that is load bearing. <vaultDir> lives under DSH_HOME, outside the session workspace and therefore outside the sandbox's writable roots: a program the agent runs through the shell cannot write the vault, and neither can a sandboxed tool. Collection only works on the host side of that boundary — which is precisely where these tools run.

Configuration

There is no Cordis Config schema on purpose. A profile that cannot resolve a schema library's peer dependency would fail to mount the plugin entirely, and a workspace-hygiene plugin that refuses to load is worse than one with no settings form. Configuration is a plain JSON file instead:

<vaultDir>/scratch-vault.json          # default: ~/.dsh/scratch-vault/scratch-vault.json
$DSH_SCRATCH_VAULT_CONFIG              # or point at any JSON file

Every key is optional; missing keys fall back to the built-in defaults.

Key	Default	Meaning
enabled	true	Master switch.
interceptMode	"redirect"	"redirect" moves the write; "deny" refuses it and explains the alternative; "report" changes nothing but logs every file that would have been intercepted.
scratchRoot	"" → <os.tmpdir()>/dsh-scratch	Where scratch files live. Must be outside the workspace.
vaultDir	"" → <DSH_HOME>/scratch-vault	Where collected scripts are archived.
interceptWrites	true	Whether write/edit are inspected at all.
rewriteShell	true	Whether shell command references follow a redirected write.
injectPrompt	true	Whether the discipline section is added to the prompt.
exposeEnv	true	Whether DSH_SCRATCH/DSH_VAULT are injected into shell calls.
registerRunScript	true	Whether run_script is offered.
interpreters	{python,node,powershell,bash}	Executable per language.
extensions	{python:".py",node:".mjs",…}	Scratch file extension per language.
scriptExtensions	27 entries	Which extensions can be scratch scripts.
scriptNamePatterns	narrow set	Base-name regexes marking a scratch script.
scratchDirNames	_scratch, tmp, …	Directory names that mark everything beneath them.
protectDirs	src, lib, test, …	Never touched — a project's real source.
excludeGlobs	[]	Deliverable allowlist, workspace-relative.
treatBareRootScriptsAsScratch	true	A script at the root of a workspace with no project manifest is scratch.
retainDays	14	Purge cutoff.
maxVaultEntries	2000	Ledger cap; oldest are dropped.
maxEntryBytes	4194304	Above this the entry is recorded but its bytes are not stored.

Start with report mode

On an unfamiliar repository, set "interceptMode": "report" first. It records what the classifier would have done without moving a single file, which is the cheap way to find out whether scriptNamePatterns needs tuning for your layout.

How the classifier decides

A false positive silently diverts a real deliverable; a false negative merely leaves a helper script behind — the status quo. Every default therefore leans toward keeping the file, and the rules are ordered worst-case-first:

1. excludeGlobs matched → keep (the user named this file).
2. A directory segment is in protectDirs → keep (real source wins over any scratch heuristic).
3. A directory segment is in scratchDirNames → vault.
4. The base name matches scriptNamePatterns (_probe.py, .check.mjs, tmp_x.sh, recon_*.py) and its extension is in scriptExtensions → vault. The extension gate is what keeps .gitignore, .env and .editorconfig out of the vault — their names look like scratch files, but they are ordinary repository files.
5. A script-extension file sits directly at the root of a workspace with no project manifest → vault. This is the rule that separates "a scratch folder" from "a repository".
6. Otherwise → keep.

scratch_promote is the escape hatch for rule 4 or 5 guessing wrong.

The tools

Tool	Purpose
run_script	Run a program from a scratch file; no workspace write.
scratch_import	Collect scripts already in the workspace; verify, then remove.
scratch_list	Newest-first listing, optionally per session.
scratch_show	One entry plus its source.
scratch_promote	Copy a vaulted script back into the workspace.
scratch_purge	Delete entries past the retention window; dry run by default.
scratch_status	Effective configuration and vault counts.

Known limits

• The vault is not a security boundary. It records what the plugin moved; it does not stop an agent that decides to write a file into the workspace by some path the classifier calls a deliverable.
• Interception is per-write. A script produced by a shell redirect (python … > out.py) or by a program the agent runs is only caught if the shell token matched a rewritten reference; the file itself is not moved.
• The shell rewriter under-covers on purpose. Shell variables, globs, longer filenames and relative paths after a cd are all left untouched (see L3), so a scratch script referenced in one of those shapes is not redirected. Redirecting it would have broken a working command.
• The classifier is name- and location-based. It does not read the file.
• The vault grows until purged. scratch_purge exists; it is not scheduled.
• systemPrompt.section cannot name the per-session path (its text function receives only a scope key), which is why the path travels through $DSH_SCRATCH instead of the prompt.
• run_script requires ctx.shell. Without it the tool is not registered, and the other layers still work.
• The vault cannot be written from inside the sandbox. It sits under DSH_HOME, outside the workspace and therefore outside writableRoots; only plugin-side code can collect. A shell program the agent runs cannot.
• Collecting is not automatic. scratch_import is opt-in and explicit. The plugin never scans or sweeps the workspace on its own; it only diverts writes it intercepts and paths you hand it.
• Editing the plugin needs a restart. The loader caches the module by its resolved URL; disabling and re-enabling the bundle re-runs the cached module's apply(), it does not re-import the file.

Development

node test/classify.test.mjs
node test/intercept.test.mjs
node test/paths.test.mjs
node test/plugin.test.mjs
node test/shellroots.test.mjs
node test/shellscratch.test.mjs
node test/tools.test.mjs
node test/vault.test.mjs

The suite is offline and fully dependency-free: every module under lib/ is imported by the tests, lib/tools.js included — registerTools touches only ctx.tools.register, ctx.get and a vault, so a two-method stub context is a faithful harness for it.

Run the files directly rather than node --test. Under a confined DSH sandbox a child process with piped stdio fails with EPERM, which is what the test runner's file isolation uses.

License

MIT