NightShift: Audit Gating for Unattended Execution

Preamble¶

Existing tools in the DSH ecosystem (such as ctx-budget, blastradius, and rewind) usually target a single moment or a specific state. When an agent runs unattended for hours, goals may drift, budgets may be exhausted, or steps may fail silently. nightshift acts as a layer that enforces these contracts during execution.

Introduction¶

Run an agent unattended for hours and get an audit report in the morning, not a summary.

Core Features¶

1. Manifest Signing: Define the objective, deliverable, acceptance criteria, forbidden patterns, and command before starting.
2. Checkpoints and Rollback: Automatically roll back when validation fails.
3. Audit Report Generation: Render the report from runtime logs, not from a summary.
4. Gate Control: Intercept forbidden patterns, irreversibility classes, and curfews before execution.
5. Exit Code Translation: Communicate with sibling plugins (such as ctx-budget and blastradius).

Installation and Enabling¶

Use the official install command to add the plugin to the current configuration:

dsh plugin --profile web add github:liyixuan201211/nightshift

Typical Usage¶

Run the following steps in the project directory:

1. Initialization: Sign the Manifest and define the work objective and constraints.

   nightshift init --root ~/work --objective "finish the auth refactor and get the suite green" --deliverable "npm test passes" --accept "tests=npm test" --forbid "git push" --command "npm run build"

2. Preflight: Check whether the environment meets the required conditions before starting and whether startup is allowed.

   nightshift preflight --root ~/work

3. Execution: Run the specified command and automatically roll back if it fails.

   nightshift step --root ~/work --verify "npm test" -- npm run build

4. Acceptance: Perform an acceptance check on the current state.

   nightshift acceptance --root ~/work

5. Brief Generation: Generate an audit report, not a summary.

   nightshift brief --root ~/work

Key Behaviors and Limitations¶

• Positioning: It does not decide what to do; it only upholds what has already been decided. It is not a scheduler and does not provide sandbox isolation.
• Resource Fetching: It does not actively fetch content unless explicitly allowed via --allow-npx.
• Report Quality: The quality of the audit report depends on the completeness of the acceptance checks.
• Dependencies: Requires Node.js version >= 20.
• Log Storage: Logs are stored in the rewind directory, and rewind invocations must include --exclude .nightshift to avoid polluting snapshots.

Exit Code Reference¶

The plugin interacts with external systems through translated exit codes: