dsh-workspace-hygiene

English | 中文

dsh-workspace-hygiene is a DeepSeek Harness plugin for managing the growing collection of intermediate artifacts produced during long-running agent tasks: logs, code and other files.

While using different agents, I noticed a recurring problem: long-running tasks produce large numbers of intermediate files, cluttering the workspace and placing a burden on disk space and model context. Files sitting on disk generally do not consume tokens directly. The problem emerges when an agent repeatedly runs glob and grep, lists directories, reads files and reconstructs the meaning of its earlier results. Redundant files can create a chain of effects: a larger search space → more tool calls → more irrelevant content in context → more reasoning noise → higher token costs and latency, and poorer reasoning performance.

How can agents automatically manage the intermediate artifacts that accumulate during long-running tasks, keeping the workspace informative, readable and free of unnecessary redundancy throughout the task lifecycle? This is a research question worth exploring.

DeepSeek Harness already emphasizes mechanisms such as workspace-context budgets. Its filesystem and workspace subsystems primarily address file access, workspace identity, and read/write safety. Three further questions remain: Which files are still worth keeping? How should existing files be named? What directory structure should organize them?

dsh-workspace-hygiene is my initial response to these three questions. Its approach treats the workspace as an organized information space that evolves with the task. The plugin continually asks: Does this file still have value? If so, where should it live and what should it be called? If the answer is not yet clear, how should it be preserved for later assessment?

First, the plugin assesses the value of workspace files. It distinguishes core task materials, final deliverables, reusable intermediate results, temporary debugging or process records, and redundant artifacts that no longer serve a purpose. The assessment considers the file's characteristics alongside its place, role and lifecycle within the task, and explains the reasoning to the user. This produces a judgment about file value that people can understand and correct, going beyond simply identifying files that look temporary.

Second, the plugin separates value assessment from action. It recommends keeping valuable files and potentially useful intermediate results, with suggestions for their names and directories. It recommends removal for files that clearly have no further value. When the evidence is insufficient, it leaves the action undecided for user review. Users can accept, revise or reject these suggestions. This lets the agent take an active role in workspace management while keeping a mistaken judgment from directly causing irreversible loss.

Next, the plugin helps establish a stable, clear and readable organization. Files at different lifecycle stages should occupy distinct directories, making final outputs, intermediate materials, items awaiting review and items marked for removal easy to distinguish. Names should convey useful information about a file's origin and purpose. Consistent naming and directory rules turn scattered files into a structure that both people and agents can quickly browse, search and understand.

Finally, organization should continue throughout the task lifecycle. As the agent creates new files, the workspace needs ongoing assessment, organization and updates: valuable material becomes clearly identified output, intermediate work is managed together, confirmed waste is removed, and uncertain material is preserved for review. The aim is to maintain a high density of useful information and reduce the irrelevant content encountered in subsequent searches and interpretation.

The goal of dsh-workspace-hygiene is a systematic approach to workspace management for long-running agents: make each file's value, location and name clear, reducing disk usage while helping people understand what agents have done and helping agents interpret work left by themselves and other agents more efficiently.

Workspace tab

dsh-workspace-hygiene adds a 工作区 (Workspace) tab immediately after 轨迹 (Trajectory) in dsh web, with a directory tree, file classifications and purpose summaries, a cleanliness score out of 100, and manual and automatic organization modes.

Long agent tasks accumulate logs, failed patches, scratch exports and intermediate results. Their presence on disk does not itself consume context tokens; repeatedly searching and interpreting them does. This plugin makes their lifecycle visible and keeps maintenance separate from the primary agent's conversation.

• Browse every directory and file in the current session's workspace, including hidden files and protected source/dependency directories. Directories load on expansion, with pagination for large folders. Symbolic links are listed but never traversed.
• Inspect each file's category: protected / valuable / intermediate / disposable / uncertain; see its purpose, assessment, original path, suggested path and size. Purpose text is a filename/path heuristic, not a claim that the plugin understands every file's contents.
• See the cleanliness score, scan time, candidate count, maintenance process PID, and verification/recovery status.
• Select Manual or Automatic mode. The saved choice applies to the workspace and survives a restart.

The browser sends a session ID, never an arbitrary workspace root. The host derives the root from that live session and uses DSH's Connection RPC transport and trust checks. An explicit workspaceRoot configuration additionally pins the deployment boundary. Resume a cold session before using the panel.

Real DSH Web integration, using an isolated fixture workspace:

Manual and automatic organization

Manual is the default. A separate maintenance process watches filesystem changes and periodically assesses the workspace. Monitoring does not move source files, inject messages into the primary agent, or reserve its idle phase. Click 整理工作区, review the plan, then click 确认并开始整理 to execute it.

Automatic means assessment and a consent request, not unattended mutation. After each completed primary-agent turn, the process refreshes its assessment. A complete scan below cleanlinessThreshold (default 80) with eligible candidates opens a confirmation prompt, even when the conversation tab is selected. The user can inspect the plan or decline. Unchanged, declined suggestions are suppressed until the candidates change. Switching to automatic does not immediately organize anything.

Both modes use the same confirmed workflow:

flowchart LR
  A[Independent monitoring] --> B[Tree and score]
  B --> C{Manual click or end-of-turn suggestion}
  C --> D[Plan and user confirmation]
  D --> E[Reserve idle workspace]
  E --> F[Baseline checks and reference inspection]
  F --> G[Recoverable organization]
  G --> H[Integrity and project checks]
  H --> I[Independent DSH review]
  I --> J[Primary Agent review]
  H -->|failure| K[Rollback]
  I -->|rejected| K
  J -->|rejected, after turn| K

Only confirmed organization temporarily reserves the idle phase of all live agents sharing that workspace in this DSH host. New input waits while the operation finishes. A busy workspace is refused; cancellation requests rollback after the transaction journal settles. This coordination does not lock unrelated editors or other DSH host processes.

Independent process and two reviews

Each observed workspace owns a Node child process (src/worker.js) with its own in-memory state and .dsh-hygiene/agent/context.json. The process watches and assesses files without borrowing the main agent's message history. Ordinary monitoring uses deterministic policy and consumes no model calls.

After an approved transaction passes its checks, that process starts a separate dsh --profile headless process and session for evidence review. It uses the configured headless model and credentials. Its context contains the change list, reference/integrity/check evidence and a bounded summary of prior maintenance runs; it does not inherit the primary conversation. All inherited tools are hidden and a dispatch guard permits only hygiene_verdict. The reviewer cannot edit the workspace or run shell commands. A failed, unavailable or negative independent review causes rollback.

Next, the host sends one follow-up to the primary agent with the changes and evidence. The primary agent inspects the outcome and submits workspace_hygiene_review with its verdict and concrete checks. Only the assigned agent can acknowledge that run. The UI remains awaiting primary review until this happens; delivery is not treated as successful verification. A negative primary review triggers rollback when the turn reaches idle. Users can also request rollback from the result panel.

Reference protection and verification

The existing hash-bound, expiring plans, path protections, file/byte budgets, quarantine and restore journal remain the mutation boundary. The Web workflow never permanently deletes files. Source files, tracked files, credentials and protected paths remain protected by policy.

Before planning and again after confirmation, the worker searches project text for candidate paths and filenames. Referenced artifacts are retained and listed in the plan. The inspection is deliberately conservative: a reference in documentation can keep an artifact. References synthesized at runtime or located outside this workspace cannot be proven absent.

Project checks run before and after organization. By default a declared npm test is used; other projects should configure verificationCommands. A failing baseline leaves artifacts in place. Post-check failure, unrelated file changes or independent-review rejection restores the transaction. Changed destination/source files are never overwritten to force a rollback; conflicts remain visible as recovery required.

The evidence pass is capped at 10,000 files / 128 MiB, excluding dependency/VCS directories and plugin state/catalog directories. Exceeding the limit refuses organization rather than claiming complete verification. Projects without configured checks receive static verification only, displayed as static-only. Successful checks and both reviews provide evidence within their coverage; they are not a mathematical guarantee of zero bugs.

valuePolicy.organization.moveFiles can additionally enable approved renaming/moving of eligible retain/review artifacts. Source and referenced files still stay put. The plugin avoids risky refactors rather than rewriting arbitrary imports. Suggested metadata catalog paths are never physical file destinations.

Cleanliness score

For the assessed, non-protected file population N:

score = round(100 − 70 × disposable/N − 20 × intermediate/N − 10 × uncertain/N)

The score is bounded to 0–100; an empty assessed population scores 100. The UI exposes counts, penalties and exclusions. It measures artifact lifecycle hygiene, not source-code quality. Protected/dependency/ignored trees are browseable but excluded from the score. An incomplete bounded scan is labeled provisional and cannot trigger automatic organization or an approved plan.

The independent review payload is capped at 20,000 characters. Oversized evidence is rejected in full and the transaction is rolled back; it is never silently truncated.

Install or update

Requires Node ^22.19.0 || >=24 and a DSH Web profile providing conversation.view, connection.rpc and Agent.runMaintenance. The Web integration has been exercised against installed DSH 0.1.1-rc.2; the current upstream extension contracts were also inspected. DSH previews change rapidly, so pin a version when reproducing an experiment.

dsh plugin --profile web add github:taoshi1999/dsh-workspace-hygiene#main
dsh web

For local development, install the checkout by its path and restart DSH Web:

npm ci
dsh plugin --profile web add .

Restart the host and refresh the browser after an update. The package exports ./client and ./package.json and declares dsh.client, so DSH discovers the tab through its native client module loader. No DSH core patch or DOM injection is needed. To remove it:

dsh plugin --profile web remove dsh-workspace-hygiene

Configuration

Override the existing row by ID in the profile's cordis.patch.yml:

- id: workspace-hygiene
  name: dsh-workspace-hygiene
  config:
    mode: manual                 # manual | automatic
    cleanlinessThreshold: 80
    monitorIntervalMs: 30000
    debounceMs: 1500
    managedRoots: [tmp, scratch, outputs]
    minAgeHours: 24
    maxScanFiles: 5000
    maxArchiveFiles: 20
    maxArchiveBytes: 104857600
    stateDir: .dsh-hygiene
    verificationCommands:
      - command: npm
        args: [test]
    verificationTimeoutMs: 120000
    reviewerTimeoutMs: 180000
    # Optional absolute path to the installed dsh/lib/bin.js:
    # reviewerCli: /path/to/node_modules/@deepseek-ai/dsh/lib/bin.js
    valuePolicy:
      discardPatterns: ['tmp/**', 'scratch/**']
      retainPatterns: ['outputs/release/**']
      organization:
        moveFiles: false

Commands are trusted deployment configuration, executed without a shell; clients cannot submit commands through the UI. On Windows the npm shorthand is launched through Node's npm CLI. Command timeouts stop the spawned process tree on Windows. autoScan: false disables periodic monitoring; a UI refresh still explicitly scans and automatic mode still evaluates completed turns. enabled: false disables the host integration. A workspace's saved mode takes precedence after its first mode change.

Legacy autoArchive, autonomousMode, notifyAgent and autoScanEveryTurns no longer authorize unattended Web changes or routine main-agent notifications. Migrate to mode: automatic for per-turn suggestions. The six legacy scan/plan/apply/restore/status/explain tool adapters are still available to explicit library consumers, but are no longer installed into the main agent by this bundle. The only registered main-agent tool is workspace_hygiene_review.

See example configuration and value policy configuration. .hygieneignore exclusions continue to govern mutation assessment; the directory browser can still display those paths.

CLI and metadata catalog

The standalone CLI remains available for explicit operator workflows:

node bin/dsh-workspace-hygiene.mjs scan ./project
node bin/dsh-workspace-hygiene.mjs plan ./project
node bin/dsh-workspace-hygiene.mjs --help

CLI apply/restore and low-level library consumers retain their existing confirmation and policy contracts; they do not run the Web orchestration or its two-agent review protocol. Prefer the Workspace tab for the complete workflow.

workspace-artifacts/ remains an optional metadata-only catalog for transaction/CLI consumers. It contains path, purpose, value assessment and lifecycle decisions, not source-file copies. The live UI reads current filesystem metadata and the latest independent scan; monitoring does not need to rewrite that catalog or feed it into the main agent's context.

Illustrative workspace lifecycle

These earlier static examples explain the file lifecycle; they are not screenshots of the new live tab.

Development

npm ci
npm run check
npm run pack-check
node scripts/dev-web.mjs

dev-web.mjs boots a real DSH Web instance with a temporary home, profile and fixture workspace; it never edits your normal DSH profile. It requires an installed DSH CLI, optionally selected with HYGIENE_DSH_CLI. No credentials are copied to the fixture home. Stop it with Ctrl+C.

Tests cover process isolation, manual/automatic consent, complete directory access, path traversal, reference changes, baseline and post-check failures, rollback, primary-review acknowledgement and the existing transaction/catalog protections. Windows directory-junction tests run without elevation; file-symlink tests explicitly skip if Windows denies creation.

The research motivation and possible experiments remain in research agenda and community research.

MIT License.