Introduction

In DSH environments, agents often need to operate on multiple Git repositories. If the current workspace does not match the expected branch, or has diverged from the remote, subsequent commits and pushes may lead to data loss or overwriting. dsh-checkout-guard is a DSH plugin for pre-checks before editing, committing, or pushing. It verifies that the current workspace is in the expected state and prevents writes when the state is incorrect.

Plugin Overview

Name: lesliewylie/dsh-checkout-guard

Maintainer: LeslieWylie

Category: admin-security

License: MIT

Core positioning: This is a read-only, offline-by-default DSH plugin. It reads the Git workspace and checks branch identity, divergence from the remote, the identity of the next commit, staged work in the index, and whether duplicate clones on the same machine may cause conflicts.

Installation and Enablement

Install the plugin via npm and enable it in the DSH configuration file.

  1. Install
    npm install dsh-checkout-guard
  1. Enable
    Add the following entry to cordis.yml:
    - id: checkout-guard
      name: 'dsh-checkout-guard'

Core Features

The plugin provides the following checks. It defaults to read-only mode:

  • Branch identity and remote divergence: Checks whether the current branch matches the expected branch and calculates the difference relative to the remote (ahead/behind).
  • Next commit identity: Validates the author information that will be used for the next commit (requires the expectIdentity parameter).
  • Workspace index check: Checks whether there is already staged work in the index.
  • Duplicate clone detection: Detects on the same machine whether other repository clones have the same remote and determines whether they are ahead of the current workspace.
  • Write protection: If the above checks fail, the plugin blocks write operations.

Tool Usage

The plugin provides two main tools for single-repository checks and batch scans.

checkout_guard: Check a single workspace

Used to check the status of a single repository path.

Parameters:
* path (required): The absolute path to the workspace.
* expectBranch: The expected branch. A mismatch triggers a block.
* fetch: Whether to run git fetch first to obtain the latest remote state (default false; this is the only feature that performs network operations).
* expectIdentity: The expected author email address used to validate commit identity.

Return value:
The result includes a safeToWrite field. Writes are allowed only when this field is true. Other fields, such as blockers, list reasons that prevent writing, while warnings provides non-blocking status information.

checkout_guard_scan: Batch scan root directories

Used to scan all workspaces under the specified root directories and return an overview.

Parameters:
* roots: The list of root directories to scan.
* maxDepth: The scan depth.

Output:
Returns information such as each workspace’s branch, upstream, ahead/behind status, number of uncommitted changes, and fetch time, and flags repositories with needsAttention (requires attention) and duplicateRemotes (duplicate remotes).

Security and Considerations

Understanding the plugin’s boundaries helps use it correctly.

  • No identity judgment: The plugin itself does not judge whether your identity is correct unless you explicitly specify expectIdentity. It only reports where the author information comes from.
  • No automatic fixes: The plugin does not automatically pull, rebase, or stage. It only reports errors and blocks operations. If an abnormal state is found, manual handling is required.
  • No write operations: The plugin does not write data to any repository. Even in fetch: true mode, it only runs git fetch --dry-run, and does not modify the index or lock files.
  • Avoid lock conflicts: The plugin runs with GIT_OPTIONAL_LOCKS=0 to avoid competing with other agents or processes for .git/index.lock.
  • No remote archive detection: The plugin cannot determine via API whether a remote repository has been archived.

Configuration

The plugin’s scope can be configured in cordis.yml.

- id: checkout-guard
  name: 'dsh-checkout-guard'
  config:
    roots:
      - /path/to/projects

The roots parameter limits the directory scope the plugin scans. If not set, it defaults to the user’s home directory.

Conclusion

As a pre-check tool, dsh-checkout-guard reduces data risk caused by agents misjudging state in multi-repository environments by blocking incorrect write operations. It does not promise to resolve conflicts, but it ensures operations stop when the state is unclear.