Introduction

When building agents with DeepSeek Harness (DSH), if the workspace changes while an agent is processing—for example, another agent, an IDE, or a CLI tool edits files—the agent may continue to rely on stale or outdated cached files, leading to inconsistencies.

Core Features

This plugin surfaces concurrent workspace changes before an agent continues working. It does so through the following mechanisms:

  1. Shared watcher: Live sessions using the same normalized workspace root share a single Chokidar watcher.
  2. Path verification: Watcher events only invalidate paths; before model requests, the plugin resolves and stats each path via ctx.fs.
  3. Version control: A session’s DSH fs/observed version is retained only when an authoritative external tool result succeeds, its tool/result is appended, and the closing step/end is committed. Nested code-mode effects remain “dirty” rather than self-acknowledged if their external call fails.
  4. Persistent logging: Successful, persistently logged DSH reads/writes/edits become the session’s acknowledged version, so the writer does not receive redundant notifications while other agents still do.
  5. User notification: A source user-role notification is inserted at agent/pre-step so that it is persisted before the model sees it.
  6. Final check: agent/turn-stopping performs a final check and prompts one step when new filesystem state or watcher boundary degradation arrives.
  7. State separation: Delivered state and DSH read/write baselines are tracked separately, preventing duplicate prompts while still reporting new versions.
  8. Precise receivers: Precise process-local watcher receivers only acknowledge path generations covered by persisted notifications. Unavailable paths remain pending until verification recovers.
  9. Bounded startup: Watcher startup is bounded and cancellable.

Installation and Activation

Requirements:
- Node.js: ^22.19.0 || >=24.0.0
- pnpm: 11.7.0

Build the project first, then run the profile installer from the checked-out relative package path to ensure relative paths are correctly anchored:

pnpm build
pnpm exec dsh plugin --profile <profile-name> add .

The package declares dsh.bundle.patch, so dsh plugin automatically activates cordis.patch.yml.

Configuration

The package works without configuration. A later profile patch can replace its line and set values, for example:

- id: workspace-change-awareness
  name: dsh-workspace-change-awareness
  config:
    debounceMs: 75
    maxWaitMs: 500
    maxNoticePaths: 50
    statConcurrency: 16
    usePolling: false
    pollIntervalMs: 100
    verifyAtTurnStop: true
    ignoredDirectories: [.git, node_modules]

Use Cases and Notes

This plugin runs with the current DSH process permissions. Review the source code and license before installation.

Be aware of the following edge cases:
- Watcher events only invalidate paths; they do not directly track file contents.
- Filesystem events cannot prove who made a change. The notification states that a path changed outside the session’s acknowledged filesystem observations, without claiming a human author.
- Host watching does not cover remote filesystem providers. Previously observed remote targets are revalidated at pre-step via ctx.fs.stat().
- New agents start from the current workspace state; initial files are not reported as changes.
- Restored or compacted sessions receive conservative reread reminders because process-local observations cannot cover edits made while DSH was stopped.
- Watcher startup is bounded and cancellable.
- File names are JSON escaped, and the visible list is bounded.
- Changes after the final pre-step stat are observed at the next boundary. DSH’s existing filesystem observation policy still provides atomic stale-version protection for first-party writes and edits; arbitrary shell writes bypass this policy.

Conclusion

This plugin resolves cache inconsistencies caused by concurrent edits by enforcing filesystem state verification before an agent continues.

GitHub repository