dsh-reins

Reins

面向 DeepSeek Harness 的持久化目标编排：任务 DAG、持久化审批与等待、崩溃恢复，以及自行运行测试的验收。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:dreamfarer-space/dsh-reins#366926cf11ff4995b80c3981be41108fcd12f6d9

兼容性与来源证明

Reins 以 dsh-reins 发布，当前版本为 0.4.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/10/3

版本

0.4.0stable

2026/10/3

DeepSeek Harness Plugin Hub

← Plugins

dsh-reins

Reins

面向 DeepSeek Harness 的持久化目标编排：任务 DAG、持久化审批与等待、崩溃恢复，以及自行运行测试的验收。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:dreamfarer-space/dsh-reins#366926cf11ff4995b80c3981be41108fcd12f6d9

README

Reins — durable Objectives for DeepSeek Harness

English · 简体中文

Harness executes. Reins holds the reins.
Tell Reins what you want in one sentence. It plans it with you, keeps it moving across Tasks, sessions,
approvals, CI, failures and restarts, and calls it done only when the check it runs itself passes.

Install · Quick start · Commands · Configuration · Architecture · Security model · Tests · Development

Why Reins

An Agent conversation is good at "do this now". Real engineering goals take longer: change the code, run the tests, wait for someone to approve a push, wait for CI, fix what CI found, wait for review… and somewhere in between the process crashes or the machine restarts.

Keeping an Agent loop spinning while it waits wastes resources, and it makes it easy to mistake "the model said it is done" for "it is done". Reins moves all of that into a durable orchestration layer:

Describe the goal in plain words; your conversation's model plans it with you and asks when there is a real choice to make.
Waiting is durable state, not an idle Agent loop; when the event arrives, a new Attempt continues.
A sensitive call is denied when no one approves it; an approval authorizes exactly that one call.
A Task is complete only when it passes the acceptance gate. A finished Goal or a successful Attempt is not enough, and tests are run by Reins itself, never taken from the Agent's word.
Everything lives in SQLite. After a crash, Reins reconciles conservatively: nothing uncertain is ever treated as success.

How it works

From one sentence to an accepted result

/reins add a delete command to my notes tool

The model of the conversation you typed this in looks at the project first.
When the request leaves a real choice open, it asks you (DSH's question card with options). Things it can find out itself, it does not ask.
If no existing test covers the change, it writes the check first and confirms that the check fails today.
It calls reins_create_objective with the Tasks, their order and a check command per Task. Reins pins the check files by hash, so the Agent doing a Task cannot rewrite its own exam.
Reins' own Agents do the work in the background, in their own sessions. When one needs approval, /reins-todo lists it, and /reins-approve <id> lets the Task continue where it stopped.
Reins runs the check itself. Exit code 0 is the only way to "done".

This was verified with a real DeepSeek model in DSH Web. Asked for "a delete function for the notes tool", the model asked whether to delete by index or by text, wrote check-delete.mjs and saw it fail, and created the Objective. A Reins Agent implemented delete-by-index, and Reins ran the pinned check: exit 0, accepted.

Features

	Capability	What it means
💬	Plain-words planning	`/reins <what you want>`: the conversation's model plans with you, asks about real choices, writes the check first, then creates the Objective
🧭	Task DAG	An Objective holds several Tasks with dependencies; a downstream Task becomes ready only when its upstream Tasks are accepted
🔁	Attempt boundary	Every run is an immutable Attempt; a finished Attempt never comes back to life, every resume is a new Attempt
✋	Durable approvals	Sensitive tools are denied and parked when no one approves; an approval becomes a one-shot grant bound to Task / Attempt / session / Goal / tool / arguments / policy version / expiry and is consumed atomically, once
⏳	Durable waits and events	`awaiting_approval` / `awaiting_ci` / `awaiting_timer` / `awaiting_external_event`; immutable events, idempotent consumption, duplicate suppression
📡	Polling watchers	GitHub Checks, PR reviews, local/remote processes; backoff, timeouts, rate limits, offline handling, stale results refused; credentials never stored or logged
🧩	Safe replanning	Graph revisions; the DAG changes only at safe points, and an Attempt from an old revision cannot be accepted (enforced in the database)
🌿	Parallel worktrees	Parallel Tasks each get their own git worktree; orphan reconciliation, branch conflict avoidance, merging, acceptance bound to artifact hashes
🤖	Subagents / session fork	Route a Task to a normal session, a read-only subagent or a session fork; seeing a tool is not permission to use it
🧪	Acceptance gate	Frozen criteria and deterministic validators (file checks, durable `reins.` facts, and `reins.command_succeeds`, where Reins runs the test command itself*); only a pass receipt completes a Task
📉	No-progress detection	Deterministic failure fingerprints; repeated identical failures, a stalled acceptance, repeated denials or tool errors put the Task on hold for you

Install

Requirements

Node.js ≥ 22.13 (for the built-in node:sqlite)
DeepSeek Harness @deepseek-ai/dsh@0.2.0-rc.1 (Reins pins its peer dependencies to this version)

npm install -g @deepseek-ai/dsh@0.2.0-rc.1

Below, <DSH_HOME> is the Harness data directory (the DSH_HOME environment variable, ~/.dsh when unset) and web is the profile to install into.

1. Get a fixed copy

Install from a fixed snapshot directory, so that later changes to a working copy do not change what is installed:

git clone --branch v0.4.0 https://github.com/dreamfarer-space/dsh-reins.git reins-0.4.0

2. Install the plugin

Reins is a DSH plugin bundle. Either:

In DSH Web: sidebar Plugins → Add plugin, enter the absolute path of the snapshot directory (for example D:/plugins/reins-0.4.0), then Enable now.

From the command line:

dsh plugin --profile web add file:/absolute/path/to/reins-0.4.0

Reins then appears under Plugins → Installed with its icon and description; the switch on the right starts and stops it. You do not need to edit cordis.patch.yml.

3. Settings on the Plugins page

Open Reins on the Plugins page. Settings are edited right there and apply as soon as you save, without a restart:

Setting	What it does
Approval policy	Strict: every tool needs approval. Recommended (default): reading and editing files is trusted; commands, network, subagents and unknown tools need approval. Custom: the recommended set plus tools you tick (`pwsh`, `bash`, `web_fetch`, …), and a list of tools that always need approval. Trust all: everything except the always-ask list (only for directories you can roll back)
Continue automatically	Continue after events, retries or a finished Task without waiting for `/reins-tick` (the Objective must allow it too: ask for it in `/reins`, or `/reins-goal --auto`)
Approval wait in the page	How long an approval may wait in the conversation before the Agent is released and it moves to `/reins-todo`
Default workspace	Where Objectives without their own `workspace` work
Desktop notification / reminder in conversation	How Reins tells you that it needs you or that something finished

These settings are stored in the profile's cordis.patch.yml (config: under - id: reins) and can be edited by hand as well; the rest of the options are under Configuration.

4. Check

Type /reins in a conversation: the usage text lists all commands. Typing /reins also shows them in DSH's command menu. Reins only governs the Attempts it starts; your own conversations with an Agent are not affected.

Update, roll back, uninstall

Update: prepare a new snapshot directory and run dsh plugin --profile web add file:<new directory> again, or add it again on the Plugins page.
Roll back: before installing, back up package.json, pnpm-lock.yaml and cordis.patch.yml under <DSH_HOME>/profiles/web; to roll back, copy them back and run dsh plugin --profile web install.
Stop / uninstall: switch it off on the Plugins page to stop Reins (database and settings are kept); Uninstall removes the bundle.
From before 0.3.0: older versions needed a hand-written - insert: - id: reins ... in cordis.patch.yml. The bundle now declares that entry itself; change the old insert block into a settings override (- id: reins with config:), or reins is loaded twice.
From 0.3.x: every /reins <subcommand> is now its own command (/reins todo → /reins-todo, /reins dag <id> → /reins-status <id>, …). The old forms still work and print the new name; /reins followed by anything else is now a plain-words request.

Quick start

Say what you want

/reins the login endpoint crashes with a null pointer, fix it
/reins add CSV export to the report page, keep the current JSON export

The conversation's model plans it with you as described in How it works. It works in any conversation, including as the first message of a new one. If the project is not the conversation's directory, name the directory in the request.

One sentence, your own check

When you already know the command that proves the work is done, skip the planning:

/reins-goal fix the clamp edge cases
/reins-goal make lint pass --test "npm run lint" --workspace D:/work/app
/reins-goal fix clamp --dry-run          # preview only
/reins-goal fix clamp --auto             # continue on its own after events / retries (also needs unattendedEnabled)

Without --test, Reins detects the test command (package.json test script, Node test files, Cargo, Go, pytest) and tells you to pass --test if it finds none.

Then two commands are enough

/reins-todo                 # everything waiting for you: approvals, held Tasks (with the last error), Tasks waiting for a tick
/reins-approve 3f9c1a2b     # approve with the short id shown by /reins-todo

After an approval, the Task continues in its previous session (the Agent remembers where it was). You do not need /reins-tick. Reading and editing files is trusted by default; running commands (pwsh / bash), network access and subagents still need approval (see trustPreset under Configuration).

In DSH Web

Reins sessions are in the sidebar: the Agent conversation of each Task appears under "未分组" (Ungrouped), named after the Task. Open it to see what the Agent did.
Approve either way: a session that needs approval is marked "待审批" (awaiting approval), and you can click "允许一次 / 拒绝" (allow once / deny) there. If you do not, after interactiveApprovalTimeoutMs (5 minutes by default) the Agent is released and the request moves to /reins-todo with a short id. DSH's own approvals (for example pwsh asking to widen the sandbox) follow the same rule.
Reins tells you: when something needs you (an approval, a held Task, a finished or failed Objective), Windows shows a notification, and the next time you talk to any DSH conversation the Agent mentions it briefly, with the command to run.
After DSH was force-stopped: if nothing was running, Reins takes over on restart by itself. If an Objective had an Attempt running, Reins cannot prove it stopped, so it holds only that Objective (no takeover, no changes) and runs everything else. /reins-todo, the reminder and the notification all point to it. Once you are sure the old DSH is gone, run /reins-recover <id> --confirm: the unfinished Attempt is recorded as interrupted, side effects with an unknown result wait for you, and the Objective continues.

Several Tasks by hand: get a PR mergeable

For full control over Tasks, dependencies and criteria, write the Task graph yourself with /reins-objective: implement, test, then wait for CI.

/reins-objective {"id":"pr-7","summary":"Get PR #7 mergeable","workspace":"D:/work/app","tasks":[
  {"id":"fix","title":"Implement the fix","criteria":[{"kind":"file_contains","spec":{"path":"src/fix.js","substring":"FIXED"}}]},
  {"id":"tests","title":"Run the tests","dependsOn":["fix"],"criteria":[{"kind":"reins.command_succeeds","spec":{"argv":["node","--test"],"timeoutMs":300000}}]},
  {"id":"ci","title":"Wait for CI","dependsOn":["tests"],"criteria":[{"kind":"reins.wait_satisfied","spec":{"waitKind":"ci","eventType":"ci.passed"}}]}
]}

What happens next:

Reins starts an Attempt for fix. The Agent gets a structured handoff (goal, current Task, criteria, last failure, budget, …) and calls task_complete when done.
The acceptance gate checks the criteria; only a pass completes fix, which makes tests ready. For tests, Reins runs node --test itself and looks only at the exit code; no test report written by the Agent counts.
In ci, the Agent pushes and calls reins_wait (kind: "ci"). The Attempt ends, the Agent stops, and a watcher starts polling.
Pushing is sensitive: with no one there it is denied and parked. /reins-todo shows the request, /reins-approve <short id> approves it, and the Task continues in its previous session.
If CI fails, a new Attempt continues with a compact failure context (failed checks, failure fingerprint); once CI passes, the Task is accepted.

See everything at any time:

/reins-status pr-7

[!IMPORTANT] Unattended runs are off by default. Attempts started by an event, a timer, an automatic retry or "the previous Task was accepted" are unattended; they do not start on their own, /reins-todo lists them and /reins-tick <objectiveId> runs them. Approvals you gave are not in that group: an approval authorizes the call and the Task continues by itself. To let Reins continue on its own all the way, set both the configuration unattendedEnabled: true and the Objective field "unattendedOptIn": true (--auto for /reins-goal; say so in a /reins request).

Commands

Every action is its own top-level command, so DSH's command menu lists and completes it. approve, deny and resolve accept the short id shown by /reins-todo (a unique prefix of at least 4 characters; an ambiguous prefix is refused).

Command	What it does
`/reins <what you want>`	Plain-words request: this conversation's model plans it with you and creates the Objective. Without text: usage
`/reins-goal <sentence> [--test "<cmd>"] [--workspace <dir>] [--id <id>] [--auto] [--dry-run]`	One-Task Objective that is done when the test command exits 0
`/reins-todo`	Everything waiting for you: approvals (with short ids), approvals waiting in a DSH conversation, side effects with an unknown result, held Tasks and their last error, Tasks waiting for a tick, Objectives held after a forced stop
`/reins-status [objectiveId]`	Without an id: all Objectives, unfinished first. With an id: Objective, Task DAG, current Attempts, acceptance, waits, approvals, watchers, budget, lease, recent events
`/reins-approve <id> [reason]`	Approve a durable approval request
`/reins-deny <id> [reason]`	Deny it; the Agent is told why
`/reins-pause <objectiveId>`	Pause; running Attempts stop, state is kept
`/reins-resume <objectiveId>`	Resume a paused Objective; also lifts held Tasks inside an active one (no progress, approval loop, wait timeout) and restarts no-progress counting
`/reins-cancel <objectiveId>`	Cancel; unused grants are revoked first
`/reins-tick [objectiveId]`	Run scheduling now (counts as attended)
`/reins-recover [objectiveId] [--confirm]`	After a forced stop of DSH: list Objectives held by the old process; `--confirm` releases them once the old process is gone (also works when Reins could not start)
`/reins-objective <json>`	Create an Objective from a hand-written Task graph (fields below)
`/reins-replan <objectiveId> <json>`	Replan at a safe point: `{"add":[…],"remove":[…],"modify":[…],"reopen":[…],"reason":"…"}`
`/reins-event <json>`	Deliver an external durable event
`/reins-resolve <id> done\|not_done`	Say whether a side effect with an unknown result happened
`/reins-merge <objectiveId> <taskId>`

Objective and Task fields

Field	Meaning
`id`	Objective id (optional, random by default)
`summary`	What the Objective is about
`workspace`	The Objective's directory (absolute, must exist). Agents work there, and file criteria and acceptance commands run there. Default: `evidenceRoot` / `repoRoot`
`tasks[]`	Tasks, at least one
`tasks[].id` / `title` / `description`	Task id, title and instructions
`tasks[].dependsOn`	Ids of Tasks that must be accepted first (no cycles)
`tasks[].required`	Whether the Objective needs this Task, default `true`
`tasks[].criteria[]`	Acceptance criteria: `{"kind","spec","required"}`
`tasks[].capability`	Routing, see below
`tasks[].maxAttempts` / `maxWallTime`	Task budget
`maxAttempts` / `maxWallTime`	Objective budget; `maxWallTime` defaults to 7 days and includes waiting
`maxActiveMs`	Limit on actual running time, excluding waiting
`maxParallel`	Parallel Attempts of one Objective (above 1 needs worktree isolation)
`noProgressLimit`	No-progress threshold (default: `noProgressAttemptLimit`)
`unattendedOptIn`	Whether it may continue unattended

Routing: capability

Field	Meaning
`route`	`session` (default, normal Agent + Goal), `subagent` (in-process child Agent), `fork` (forked from the previous Attempt's session)
`readOnly`	Default `true` for `subagent` / `fork`: sensitive tools are always denied
`isolation`	`none` or `worktree`; a subagent that writes code must use `worktree`
`provider`	Subagent provider (default `spawn`, `fork` for forks)
`model` / `modelProvider`	Model and model provider
`tools.allow` / `tools.deny`	Limit visible tools. Visible is not allowed: sensitive calls still need approval
`maxGoalRounds`	Goal rounds per Attempt, default 3

Acceptance criteria

kind	spec	Passes when
`file_exists` / `file_absent`	`{"path"}`	the file exists / does not exist
`file_contains`	`{"path","substring"}`	the file contains the text
`file_sha256_equals`	`{"path","sha256"}`	the file has this hash
`json_field_equals`	`{"path","pointer","expected"}`	the JSON field equals the value; `pointer` is a dotted path (`a.b`)
`marker_count_equals`	`{"path","marker","count"}`	the marker occurs that many times
`reins.wait_satisfied`	`{"waitKind","eventType"}`	the Task's last wait was satisfied by a durable event of that type, and the current Attempt is newer than the event
`reins.output_contains`	`{"substring"}`	the subagent's output contains the text
`reins.no_ambiguous_side_effects`	`{}`	the Task has no side effect with an unknown result
`reins.command_succeeds`	`{"argv","cwd","timeoutMs","expectExitCode","pins","env"}`	Reins runs the command itself at acceptance and the exit code equals `expectExitCode` (default 0)

File paths are relative to the Attempt's directory (the Objective's workspace, evidenceRoot or the worktree); absolute paths and .. are refused.

[!WARNING] File criteria check files in the working directory, and the Agent can write those files too. In a real-model test, after a failing test run the model rewrote test-report.json to {"passed":true}, and json_field_equals passed. For "tests pass" or "the build succeeds", use reins.command_succeeds, never a report file.

Rules of reins.command_succeeds:

Agent tools

Tool	Used by	What it does
`reins_create_objective`	the conversation where you typed `/reins`	Creates the planned Objective. Works once per `/reins` in that conversation, never in Reins' own sessions; validates Tasks, order, check commands, and pins `checkFiles`. `dryRun` shows the plan without creating it
`task_complete`	Reins Agents	Claims the Task is done; Reins pre-checks, the acceptance gate decides
`reins_wait`	Reins Agents	Ends the current Attempt and waits durably; a new Attempt continues when the event arrives

reins_wait kinds:

kind	Arguments	Resumes on
`ci`	`repo` (`owner/name`), `sha`, optional `requiredChecks`	`ci.passed` / `ci.failed`
`pr_review`	`repo`, `number`	`review.approved` / `review.changes_requested` / `review.commented` / `pr.merged` / `pr.closed`
`process`	`exitFile` or `pid`, optional `name`	`process.succeeded` / `process.failed` / `process.lost`
`remote`	`url`, optional `name` (host must be in `remoteWatcherHosts`)	`remote.succeeded` / `remote.failed` / `remote.cancelled`
`timer`	`delayMs`	`timer.fired`
`external_event`	`subject`, `eventTypes`	events delivered with `/reins-event`

Every wait takes a timeoutMs (default 24 hours); after it, the Task is held for you instead of being retried blindly.

External event example (subject carries the ext: prefix and matches the subject of reins_wait):

/reins-event {"source":"deployer","sourceEventId":"deploy-42","type":"deploy.done","subject":"ext:deploy-42","objective":"pr-7","payload":{"env":"staging"}}

source + sourceEventId is the event's identity: a repeated delivery is suppressed, and the same identity with different content is flagged as a conflict instead of overwriting the original.

Single-Task commands (Phase 2/3, for scripts)

These are reachable as /reins <subcommand> only: create <summary> | <task title>, criteria-add <objectiveId> <taskId> <kind> <json-spec>, criteria-list <objectiveId> <taskId> [revision], criteria-revise <objectiveId> <taskId>, accept <objectiveId> <taskId> [attemptId], receipts <objectiveId> <taskId>. /reins-status, -pause, -resume and -cancel work for these Objectives too. For new work use /reins or /reins-goal.

Configuration

Configuration is validated strictly: unknown keys, invalid numbers, cloud URLs and UNC network paths are refused.

Key	Default	Meaning
`databasePath`	`~/.dsh/dsh-reins/reins.sqlite`	Local SQLite path (the directory is created if missing). One live Reins process per database
`evidenceRoot`	`null`	Default directory for Objectives without a `workspace`; with neither this nor `repoRoot`, orchestrated Objectives must bring their own `workspace`
`approvalRequiredTools`	`[]`	Tools that always need approval
`trustPreset`	`workspace`	Built-in trusted set. `workspace`: `read`, `glob`, `grep`, `write`, `edit`, `str_replace_editor`, `todo_write`, `get_goal`, `update_goal` and Reins' `task_complete`, `reins_wait`; commands, network, subagents and unknown tools still need approval. `none`: only `trustedTools`
`trustedTools`	`[]`	Tools trusted in addition to the preset (for example `["pwsh"]`)
`trustUnlistedTools`	`false`	Whether unlisted tools are trusted. Not by default: an unknown side effect needs approval
`unattendedEnabled`	`false`	Allow unattended runs (the Objective must also have `unattendedOptIn`)
`defaultMaxAttempts`	`5`	Default maximum Attempts per Task
`defaultMaxWallTimeMs`	`300000`	Default wall-clock budget of a single-Task Objective
`orchestratedDefaultWallTimeMs`	7 days	Default wall-clock budget of an orchestrated Objective (including waits)
`noProgressAttemptLimit`	`3`	No-progress threshold
`maxConcurrentAttempts`

Budgets: maxWallTime is wall-clock time, including waits for CI and approvals; maxActiveMs counts only the time Attempts actually run; maxGoalRounds bounds each Attempt. There is no reliable token telemetry, so there is no token or cost budget.

Architecture

Reins architecture

Reins is a Cordis plugin that uses only the public DeepSeek Harness API and never changes the Harness core:

Commands and planning (src/commands/): the /reins and /reins-* commands; /reins <request> hands the request to the conversation's model with agent.followup, and reins_create_objective turns its plan into an Objective.
Orchestrator (src/orchestrator/): schedules ready Tasks, keeps the DAG and graph revisions, durable waits and events, watchers, approvals, worktrees, routing, failure fingerprints and handoffs.
Runtime (src/orchestration/runtime.js): atomic admission, lease fencing, outer settle (disarm → cancel → idle → flush → final receipt), tool and step guards. Inside an Attempt, only the Harness goal-round driver continues the work.
Acceptance gate (src/acceptance/): the only path to completed; database triggers make completion without a pass receipt impossible.
Storage (src/store/ + migrations/): SQLite (node:sqlite), migrations 001–015, append-only audit, key invariants enforced by triggers.

How a resume happens

An approval, from park to acceptance

CI, timers, PR reviews and external events all take the same path: wait → durable event → idempotent consume → new Attempt.

Security model

Every capability of Reins obeys these invariants; the tests and the real-Harness verification are built around them:

Harness executes, Reins orchestrates. Public API only, no private imports, no changes to the Harness core.
Only the goal-round driver continues work inside an Attempt; one Objective has exactly one valid writer (lease + epoch fencing).
A finished Attempt never comes back to life; a parked Attempt always resumes as a new Attempt.
A sensitive call without approval is denied, and the denial must still be followed by park / cancel and a proof of quiescence.
Approval is not acceptance, and a finished Goal is not a finished Task. Approval cannot bypass the sandbox, guards, leases, budgets or the acceptance gate.
A wait keeps no Agent loop.
A side effect with an unknown result is never replayed automatically; a consumed grant is never restored, even if the tool failed or the process crashed.
SQLite and the Harness session log are separate consistency domains: quiet only with a flush proof; after a restart nothing uncertain is treated as success.
Taking over after a crash needs an exit proof bound to owner / Objective / epoch / execution; without it, that Objective is held (LEASE_BUSY) and never touched.
One live Reins process per database: another live owner makes startup fail with DATABASE_IN_USE; a process whose database was taken over stops scheduling and polling at once.
"Tests pass" is verified by Reins itself: reins.command_succeeds runs the frozen command at acceptance; if a pinned file changed, it does not run at all.
A planned Objective comes only from you: reins_create_objective works only after you typed /reins in that conversation, once, never in Reins' own sessions, and check files the planner wrote are pinned before any Agent starts.
Conservative takeover after a forced stop: a lease is taken over automatically only when the old process is recorded on this host, is confirmed gone, and had nothing running; otherwise you confirm with /reins-recover --confirm, and that confirmation is append-only.
After an approval, the same session continues: the next Attempt reopens the parked Harness session (still a new Attempt with a new Goal; the grant still allows exactly that one call). After a failure, crash or replan, a new session is used. A Task parked for approval 10 times in a row is held for you to decide.
URLs chosen by an Agent only reach allowed hosts: waits check when registered and before every poll, refuse redirects and never carry credentials.

Tests and verification

npm ci                    # dependencies
npm run typecheck         # type check against the public Harness API
npm test                  # main regression suite (about 70 seconds)
npm run test:runner       # scenario driver and verifier regression (including verifier negatives)
npm run test:live         # real DeepSeek Harness scenarios (about 4 minutes)
npm run test:live:phase3  # Phase 3 single-Task real Harness scenarios (about 2 minutes)
node scripts/build-diagrams.mjs   # rebuild the bilingual README diagrams

Current results:

Suite	Result
`npm test`	499 / 499
`npm run test:runner`	48 / 48 (including 28 Phase 4 verifier negatives)
`npm run test:live`	7 / 7
`npm run test:live:phase3`	11 / 11 gates
`npm run typecheck`	passes

Real Harness scenarios (`npm run test:live`)

Each case starts a real dsh --profile process in an isolated DSH_HOME: real Cordis, Agent, agent loop, goal-round driver, session persistence, tool pipeline and headless approval; only the model is a deterministic fixture. User actions go through the really registered /reins-* commands; GitHub is a local stand-in that keeps its state across process restarts.

Case	What it proves
`e2e`	"Get a PR mergeable" with five Tasks: no approver → park → approve → a new Attempt pushes exactly once; CI fails → fix → approved push again → CI passes; review handled; Objective completes after every acceptance
`crash-running`	Attempt killed with `SIGKILL` while running, restarted with an exit proof: reconciled as interrupted, retried, completed
`crash-consumed`	Killed after the grant was consumed and the push happened but before the result was recorded: the side effect is marked ambiguous, not replayed, completed after you confirm
`crash-awaiting-ci`	Killed while waiting for CI: the watcher resumes polling and drives the next Attempts to completion
`no-proof`	Killed without an exit proof: that Objective is held (`LEASE_BUSY`), untouched, while Reins runs
`second-process`	A second process on the same database while the first runs `e2e`: it refuses to start with `DATABASE_IN_USE` and runs nothing; the first completes normally
`subagent`	Real subagent and session fork: sensitive calls from a read-only child are recognized and denied with zero physical side effects; the child session's `parentSession` is the Reins anchor session; a fork retry really derives from the previous session

The independent verifier scripts/phase4-harness-verify.mjs reads only SQLite (opened read-only), the physical side-effect log, the supervisor records and the real session logs, with 6–59 checks per case, and does not trust the scenario plugin's own conclusions. tests/runner/phase4-verifier-negative.test.js tampers with a real run snapshot one fact at a time to prove the verifier fails.

[!NOTE] The scenarios above use a deterministic model and a local GitHub stand-in. With a real model (DeepSeek), these were verified separately in DSH Web: /reins planning (look first, ask about a real choice, write and pin the check, create; then the Reins Agent did the work and the pinned check passed); /reins-goal; normal fixes, correcting after a denial, approvals, an impossible task, the default tool policy, a forged test report, and reins.command_succeeds acceptance (with a forged report present, Reins ran the tests itself, got exit 1, and the Task did not complete).

Project layout

reins/
├── src/
│   ├── plugin.js              # plugin entry (Cordis apply)
│   ├── config.js              # configuration schema and strict validation
│   ├── live-config.js         # settings saved on the Plugins page apply without a reload
│   ├── commands/              # /reins and /reins-* commands, /reins planning (plan.js)
│   ├── orchestrator/          # DAG, waits/events, watchers, approvals, worktrees, routing, fingerprints, handoffs
│   ├── orchestration/         # runtime: admission, budgets, no-progress, outer settle
│   ├── acceptance/            # acceptance gate, frozen criteria, validators, receipt integrity
│   ├── approval/              # relational approvals (Phase 2)
│   ├── store/                 # SQLite store, transactions, migrations, instance lock
│   ├── reconcile/             # startup reconciliation
│   ├── harness/               # public Harness API adapter
│   └── tools/                 # task_complete tool
├── client/client.js           # settings page on DSH Web's Plugins page
├── migrations/                # 001–015, only ever added to
├── scripts/                   # real Harness scenario drivers, independent verifiers, diagram builder
├── tests/                     # regression tests grouped by feature (see tests/README.md)
├── docs/assets/               # README images (English and Chinese)
└── smoke/public-api.ts        # public API type-check sample

Development

Rules

For a feature or a fix, first write a test that reproduces the problem, then change the code.
Never delete or loosen a safety assertion to make a test pass. Identity binding, lease fencing, and default-deny for approvals and acceptance stay.
Task and Objective completion goes through the acceptance gate, never through a model's "done" or a direct database edit.
Never commit API keys, real user configuration, real databases, logs or run evidence.
After every change run typecheck, test and test:runner; for framework lifecycle, recovery or tool calls also test:live.

Conventions

Schema changes only add migrations; 001–015 are never rewritten.
A new user action is a new top-level /reins-<action> command (a row in COMMANDS in src/commands/register.js); the real-Cordis unload test pins the exact command set. listValidatorKinds() stays at the 6 file validators; new acceptance kinds go into the separate reins.* registry.
Temporary test files go through tests/fixtures/scratch.js; never hard-code local paths.
Text files use LF (enforced by .gitattributes).
The English and Chinese diagrams are built from one description by scripts/build-diagrams.mjs.

What gets published

package.json files contains the plugin only (src, migrations, client, locale, the bundle patch, icon, license and README); tests, scripts and dev dependencies are not published.

Known limitations

File criteria trust files in the working directory, which the Agent can write; for "tests / build pass" use reins.command_succeeds.
reins.command_succeeds runs code from the working directory; any file not pinned may have been changed by the Agent. It does not run in a sandbox.
/reins planning depends on the judgement of the conversation's model: it may decide something you would have liked to be asked about, or pick a check that is weaker than you want. Read its summary; /reins-status <id> shows the exact check of every Task. /reins-goal does not pin test files; for a stronger guarantee use /reins (which pins checks it wrote) or /reins-objective with pins.
With a real model, /reins planning, /reins-goal and single-Task scenarios are verified; CI / PR watchers, crash recovery, parallel worktrees, subagent / fork and replanning were verified in the real Harness with a deterministic model only.
Tested on Windows only; Linux and macOS are unverified.
Desktop notifications are built in on Windows only; elsewhere configure notifyCommand.
DSH's sandbox blocks commands that start child processes, such as node --test, so an Agent may ask to widen the sandbox; acceptance is not affected, because Reins runs the tests itself outside the sandbox.
Single-Task Objectives (/reins create) run one at a time and, without evidenceRoot, work in the DSH process's start directory; orchestrated Objectives run in parallel execution slots.

License

MIT.

兼容性与来源证明

Reins 以 dsh-reins 发布，当前版本为 0.4.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/10/3

版本

0.4.0stable

2026/10/3

README

Reins — durable Objectives for DeepSeek Harness

English · 简体中文

Install · Quick start · Commands · Configuration · Architecture · Security model · Tests · Development

Why Reins

Describe the goal in plain words; your conversation's model plans it with you and asks when there is a real choice to make.
Waiting is durable state, not an idle Agent loop; when the event arrives, a new Attempt continues.
A sensitive call is denied when no one approves it; an approval authorizes exactly that one call.
A Task is complete only when it passes the acceptance gate. A finished Goal or a successful Attempt is not enough, and tests are run by Reins itself, never taken from the Agent's word.
Everything lives in SQLite. After a crash, Reins reconciles conservatively: nothing uncertain is ever treated as success.

How it works

From one sentence to an accepted result

/reins add a delete command to my notes tool

The model of the conversation you typed this in looks at the project first.
When the request leaves a real choice open, it asks you (DSH's question card with options). Things it can find out itself, it does not ask.
If no existing test covers the change, it writes the check first and confirms that the check fails today.
It calls reins_create_objective with the Tasks, their order and a check command per Task. Reins pins the check files by hash, so the Agent doing a Task cannot rewrite its own exam.
Reins' own Agents do the work in the background, in their own sessions. When one needs approval, /reins-todo lists it, and /reins-approve <id> lets the Task continue where it stopped.
Reins runs the check itself. Exit code 0 is the only way to "done".

Features

	Capability	What it means
💬	Plain-words planning	`/reins <what you want>`: the conversation's model plans with you, asks about real choices, writes the check first, then creates the Objective
🧭	Task DAG	An Objective holds several Tasks with dependencies; a downstream Task becomes ready only when its upstream Tasks are accepted
🔁	Attempt boundary	Every run is an immutable Attempt; a finished Attempt never comes back to life, every resume is a new Attempt
✋	Durable approvals	Sensitive tools are denied and parked when no one approves; an approval becomes a one-shot grant bound to Task / Attempt / session / Goal / tool / arguments / policy version / expiry and is consumed atomically, once
⏳	Durable waits and events	`awaiting_approval` / `awaiting_ci` / `awaiting_timer` / `awaiting_external_event`; immutable events, idempotent consumption, duplicate suppression
📡	Polling watchers	GitHub Checks, PR reviews, local/remote processes; backoff, timeouts, rate limits, offline handling, stale results refused; credentials never stored or logged
🧩	Safe replanning	Graph revisions; the DAG changes only at safe points, and an Attempt from an old revision cannot be accepted (enforced in the database)
🌿	Parallel worktrees	Parallel Tasks each get their own git worktree; orphan reconciliation, branch conflict avoidance, merging, acceptance bound to artifact hashes
🤖	Subagents / session fork	Route a Task to a normal session, a read-only subagent or a session fork; seeing a tool is not permission to use it
🧪	Acceptance gate	Frozen criteria and deterministic validators (file checks, durable `reins.` facts, and `reins.command_succeeds`, where Reins runs the test command itself*); only a pass receipt completes a Task
📉	No-progress detection	Deterministic failure fingerprints; repeated identical failures, a stalled acceptance, repeated denials or tool errors put the Task on hold for you

Install

Requirements

Node.js ≥ 22.13 (for the built-in node:sqlite)
DeepSeek Harness @deepseek-ai/dsh@0.2.0-rc.1 (Reins pins its peer dependencies to this version)

npm install -g @deepseek-ai/dsh@0.2.0-rc.1

Below, <DSH_HOME> is the Harness data directory (the DSH_HOME environment variable, ~/.dsh when unset) and web is the profile to install into.

1. Get a fixed copy

Install from a fixed snapshot directory, so that later changes to a working copy do not change what is installed:

git clone --branch v0.4.0 https://github.com/dreamfarer-space/dsh-reins.git reins-0.4.0

2. Install the plugin

Reins is a DSH plugin bundle. Either:

In DSH Web: sidebar Plugins → Add plugin, enter the absolute path of the snapshot directory (for example D:/plugins/reins-0.4.0), then Enable now.

From the command line:

dsh plugin --profile web add file:/absolute/path/to/reins-0.4.0

Reins then appears under Plugins → Installed with its icon and description; the switch on the right starts and stops it. You do not need to edit cordis.patch.yml.

3. Settings on the Plugins page

Open Reins on the Plugins page. Settings are edited right there and apply as soon as you save, without a restart:

Setting	What it does
Approval policy	Strict: every tool needs approval. Recommended (default): reading and editing files is trusted; commands, network, subagents and unknown tools need approval. Custom: the recommended set plus tools you tick (`pwsh`, `bash`, `web_fetch`, …), and a list of tools that always need approval. Trust all: everything except the always-ask list (only for directories you can roll back)
Continue automatically	Continue after events, retries or a finished Task without waiting for `/reins-tick` (the Objective must allow it too: ask for it in `/reins`, or `/reins-goal --auto`)
Approval wait in the page	How long an approval may wait in the conversation before the Agent is released and it moves to `/reins-todo`
Default workspace	Where Objectives without their own `workspace` work
Desktop notification / reminder in conversation	How Reins tells you that it needs you or that something finished

These settings are stored in the profile's cordis.patch.yml (config: under - id: reins) and can be edited by hand as well; the rest of the options are under Configuration.

4. Check

Update, roll back, uninstall

Update: prepare a new snapshot directory and run dsh plugin --profile web add file:<new directory> again, or add it again on the Plugins page.
Roll back: before installing, back up package.json, pnpm-lock.yaml and cordis.patch.yml under <DSH_HOME>/profiles/web; to roll back, copy them back and run dsh plugin --profile web install.
Stop / uninstall: switch it off on the Plugins page to stop Reins (database and settings are kept); Uninstall removes the bundle.
From before 0.3.0: older versions needed a hand-written - insert: - id: reins ... in cordis.patch.yml. The bundle now declares that entry itself; change the old insert block into a settings override (- id: reins with config:), or reins is loaded twice.
From 0.3.x: every /reins <subcommand> is now its own command (/reins todo → /reins-todo, /reins dag <id> → /reins-status <id>, …). The old forms still work and print the new name; /reins followed by anything else is now a plain-words request.

Quick start

Say what you want

/reins the login endpoint crashes with a null pointer, fix it
/reins add CSV export to the report page, keep the current JSON export

One sentence, your own check

When you already know the command that proves the work is done, skip the planning:

/reins-goal fix the clamp edge cases
/reins-goal make lint pass --test "npm run lint" --workspace D:/work/app
/reins-goal fix clamp --dry-run          # preview only
/reins-goal fix clamp --auto             # continue on its own after events / retries (also needs unattendedEnabled)

Without --test, Reins detects the test command (package.json test script, Node test files, Cargo, Go, pytest) and tells you to pass --test if it finds none.

Then two commands are enough

/reins-todo                 # everything waiting for you: approvals, held Tasks (with the last error), Tasks waiting for a tick
/reins-approve 3f9c1a2b     # approve with the short id shown by /reins-todo

In DSH Web

Reins sessions are in the sidebar: the Agent conversation of each Task appears under "未分组" (Ungrouped), named after the Task. Open it to see what the Agent did.
Approve either way: a session that needs approval is marked "待审批" (awaiting approval), and you can click "允许一次 / 拒绝" (allow once / deny) there. If you do not, after interactiveApprovalTimeoutMs (5 minutes by default) the Agent is released and the request moves to /reins-todo with a short id. DSH's own approvals (for example pwsh asking to widen the sandbox) follow the same rule.
Reins tells you: when something needs you (an approval, a held Task, a finished or failed Objective), Windows shows a notification, and the next time you talk to any DSH conversation the Agent mentions it briefly, with the command to run.
After DSH was force-stopped: if nothing was running, Reins takes over on restart by itself. If an Objective had an Attempt running, Reins cannot prove it stopped, so it holds only that Objective (no takeover, no changes) and runs everything else. /reins-todo, the reminder and the notification all point to it. Once you are sure the old DSH is gone, run /reins-recover <id> --confirm: the unfinished Attempt is recorded as interrupted, side effects with an unknown result wait for you, and the Objective continues.

Several Tasks by hand: get a PR mergeable

For full control over Tasks, dependencies and criteria, write the Task graph yourself with /reins-objective: implement, test, then wait for CI.

/reins-objective {"id":"pr-7","summary":"Get PR #7 mergeable","workspace":"D:/work/app","tasks":[
  {"id":"fix","title":"Implement the fix","criteria":[{"kind":"file_contains","spec":{"path":"src/fix.js","substring":"FIXED"}}]},
  {"id":"tests","title":"Run the tests","dependsOn":["fix"],"criteria":[{"kind":"reins.command_succeeds","spec":{"argv":["node","--test"],"timeoutMs":300000}}]},
  {"id":"ci","title":"Wait for CI","dependsOn":["tests"],"criteria":[{"kind":"reins.wait_satisfied","spec":{"waitKind":"ci","eventType":"ci.passed"}}]}
]}

What happens next:

Reins starts an Attempt for fix. The Agent gets a structured handoff (goal, current Task, criteria, last failure, budget, …) and calls task_complete when done.
The acceptance gate checks the criteria; only a pass completes fix, which makes tests ready. For tests, Reins runs node --test itself and looks only at the exit code; no test report written by the Agent counts.
In ci, the Agent pushes and calls reins_wait (kind: "ci"). The Attempt ends, the Agent stops, and a watcher starts polling.
Pushing is sensitive: with no one there it is denied and parked. /reins-todo shows the request, /reins-approve <short id> approves it, and the Task continues in its previous session.
If CI fails, a new Attempt continues with a compact failure context (failed checks, failure fingerprint); once CI passes, the Task is accepted.

See everything at any time:

/reins-status pr-7

[!IMPORTANT] Unattended runs are off by default. Attempts started by an event, a timer, an automatic retry or "the previous Task was accepted" are unattended; they do not start on their own, /reins-todo lists them and /reins-tick <objectiveId> runs them. Approvals you gave are not in that group: an approval authorizes the call and the Task continues by itself. To let Reins continue on its own all the way, set both the configuration unattendedEnabled: true and the Objective field "unattendedOptIn": true (--auto for /reins-goal; say so in a /reins request).

Commands

Command	What it does
`/reins <what you want>`	Plain-words request: this conversation's model plans it with you and creates the Objective. Without text: usage
`/reins-goal <sentence> [--test "<cmd>"] [--workspace <dir>] [--id <id>] [--auto] [--dry-run]`	One-Task Objective that is done when the test command exits 0
`/reins-todo`	Everything waiting for you: approvals (with short ids), approvals waiting in a DSH conversation, side effects with an unknown result, held Tasks and their last error, Tasks waiting for a tick, Objectives held after a forced stop
`/reins-status [objectiveId]`	Without an id: all Objectives, unfinished first. With an id: Objective, Task DAG, current Attempts, acceptance, waits, approvals, watchers, budget, lease, recent events
`/reins-approve <id> [reason]`	Approve a durable approval request
`/reins-deny <id> [reason]`	Deny it; the Agent is told why
`/reins-pause <objectiveId>`	Pause; running Attempts stop, state is kept
`/reins-resume <objectiveId>`	Resume a paused Objective; also lifts held Tasks inside an active one (no progress, approval loop, wait timeout) and restarts no-progress counting
`/reins-cancel <objectiveId>`	Cancel; unused grants are revoked first
`/reins-tick [objectiveId]`	Run scheduling now (counts as attended)
`/reins-recover [objectiveId] [--confirm]`	After a forced stop of DSH: list Objectives held by the old process; `--confirm` releases them once the old process is gone (also works when Reins could not start)
`/reins-objective <json>`	Create an Objective from a hand-written Task graph (fields below)
`/reins-replan <objectiveId> <json>`	Replan at a safe point: `{"add":[…],"remove":[…],"modify":[…],"reopen":[…],"reason":"…"}`
`/reins-event <json>`	Deliver an external durable event
`/reins-resolve <id> done\|not_done`	Say whether a side effect with an unknown result happened
`/reins-merge <objectiveId> <taskId>`

Objective and Task fields

Field	Meaning
`id`	Objective id (optional, random by default)
`summary`	What the Objective is about
`workspace`	The Objective's directory (absolute, must exist). Agents work there, and file criteria and acceptance commands run there. Default: `evidenceRoot` / `repoRoot`
`tasks[]`	Tasks, at least one
`tasks[].id` / `title` / `description`	Task id, title and instructions
`tasks[].dependsOn`	Ids of Tasks that must be accepted first (no cycles)
`tasks[].required`	Whether the Objective needs this Task, default `true`
`tasks[].criteria[]`	Acceptance criteria: `{"kind","spec","required"}`
`tasks[].capability`	Routing, see below
`tasks[].maxAttempts` / `maxWallTime`	Task budget
`maxAttempts` / `maxWallTime`	Objective budget; `maxWallTime` defaults to 7 days and includes waiting
`maxActiveMs`	Limit on actual running time, excluding waiting
`maxParallel`	Parallel Attempts of one Objective (above 1 needs worktree isolation)
`noProgressLimit`	No-progress threshold (default: `noProgressAttemptLimit`)
`unattendedOptIn`	Whether it may continue unattended

Routing: capability

Field	Meaning
`route`	`session` (default, normal Agent + Goal), `subagent` (in-process child Agent), `fork` (forked from the previous Attempt's session)
`readOnly`	Default `true` for `subagent` / `fork`: sensitive tools are always denied
`isolation`	`none` or `worktree`; a subagent that writes code must use `worktree`
`provider`	Subagent provider (default `spawn`, `fork` for forks)
`model` / `modelProvider`	Model and model provider
`tools.allow` / `tools.deny`	Limit visible tools. Visible is not allowed: sensitive calls still need approval
`maxGoalRounds`	Goal rounds per Attempt, default 3

Acceptance criteria

kind	spec	Passes when
`file_exists` / `file_absent`	`{"path"}`	the file exists / does not exist
`file_contains`	`{"path","substring"}`	the file contains the text
`file_sha256_equals`	`{"path","sha256"}`	the file has this hash
`json_field_equals`	`{"path","pointer","expected"}`	the JSON field equals the value; `pointer` is a dotted path (`a.b`)
`marker_count_equals`	`{"path","marker","count"}`	the marker occurs that many times
`reins.wait_satisfied`	`{"waitKind","eventType"}`	the Task's last wait was satisfied by a durable event of that type, and the current Attempt is newer than the event
`reins.output_contains`	`{"substring"}`	the subagent's output contains the text
`reins.no_ambiguous_side_effects`	`{}`	the Task has no side effect with an unknown result
`reins.command_succeeds`	`{"argv","cwd","timeoutMs","expectExitCode","pins","env"}`	Reins runs the command itself at acceptance and the exit code equals `expectExitCode` (default 0)

File paths are relative to the Attempt's directory (the Objective's workspace, evidenceRoot or the worktree); absolute paths and .. are refused.

[!WARNING] File criteria check files in the working directory, and the Agent can write those files too. In a real-model test, after a failing test run the model rewrote test-report.json to {"passed":true}, and json_field_equals passed. For "tests pass" or "the build succeeds", use reins.command_succeeds, never a report file.

Rules of reins.command_succeeds:

Agent tools

Tool	Used by	What it does
`reins_create_objective`	the conversation where you typed `/reins`	Creates the planned Objective. Works once per `/reins` in that conversation, never in Reins' own sessions; validates Tasks, order, check commands, and pins `checkFiles`. `dryRun` shows the plan without creating it
`task_complete`	Reins Agents	Claims the Task is done; Reins pre-checks, the acceptance gate decides
`reins_wait`	Reins Agents	Ends the current Attempt and waits durably; a new Attempt continues when the event arrives

reins_wait kinds:

kind	Arguments	Resumes on
`ci`	`repo` (`owner/name`), `sha`, optional `requiredChecks`	`ci.passed` / `ci.failed`
`pr_review`	`repo`, `number`	`review.approved` / `review.changes_requested` / `review.commented` / `pr.merged` / `pr.closed`
`process`	`exitFile` or `pid`, optional `name`	`process.succeeded` / `process.failed` / `process.lost`
`remote`	`url`, optional `name` (host must be in `remoteWatcherHosts`)	`remote.succeeded` / `remote.failed` / `remote.cancelled`
`timer`	`delayMs`	`timer.fired`
`external_event`	`subject`, `eventTypes`	events delivered with `/reins-event`

Every wait takes a timeoutMs (default 24 hours); after it, the Task is held for you instead of being retried blindly.

External event example (subject carries the ext: prefix and matches the subject of reins_wait):

/reins-event {"source":"deployer","sourceEventId":"deploy-42","type":"deploy.done","subject":"ext:deploy-42","objective":"pr-7","payload":{"env":"staging"}}

source + sourceEventId is the event's identity: a repeated delivery is suppressed, and the same identity with different content is flagged as a conflict instead of overwriting the original.

Single-Task commands (Phase 2/3, for scripts)

Configuration

Configuration is validated strictly: unknown keys, invalid numbers, cloud URLs and UNC network paths are refused.

Key	Default	Meaning
`databasePath`	`~/.dsh/dsh-reins/reins.sqlite`	Local SQLite path (the directory is created if missing). One live Reins process per database
`evidenceRoot`	`null`	Default directory for Objectives without a `workspace`; with neither this nor `repoRoot`, orchestrated Objectives must bring their own `workspace`
`approvalRequiredTools`	`[]`	Tools that always need approval
`trustPreset`	`workspace`	Built-in trusted set. `workspace`: `read`, `glob`, `grep`, `write`, `edit`, `str_replace_editor`, `todo_write`, `get_goal`, `update_goal` and Reins' `task_complete`, `reins_wait`; commands, network, subagents and unknown tools still need approval. `none`: only `trustedTools`
`trustedTools`	`[]`	Tools trusted in addition to the preset (for example `["pwsh"]`)
`trustUnlistedTools`	`false`	Whether unlisted tools are trusted. Not by default: an unknown side effect needs approval
`unattendedEnabled`	`false`	Allow unattended runs (the Objective must also have `unattendedOptIn`)
`defaultMaxAttempts`	`5`	Default maximum Attempts per Task
`defaultMaxWallTimeMs`	`300000`	Default wall-clock budget of a single-Task Objective
`orchestratedDefaultWallTimeMs`	7 days	Default wall-clock budget of an orchestrated Objective (including waits)
`noProgressAttemptLimit`	`3`	No-progress threshold
`maxConcurrentAttempts`

Architecture

Reins architecture

Reins is a Cordis plugin that uses only the public DeepSeek Harness API and never changes the Harness core:

Commands and planning (src/commands/): the /reins and /reins-* commands; /reins <request> hands the request to the conversation's model with agent.followup, and reins_create_objective turns its plan into an Objective.
Orchestrator (src/orchestrator/): schedules ready Tasks, keeps the DAG and graph revisions, durable waits and events, watchers, approvals, worktrees, routing, failure fingerprints and handoffs.
Runtime (src/orchestration/runtime.js): atomic admission, lease fencing, outer settle (disarm → cancel → idle → flush → final receipt), tool and step guards. Inside an Attempt, only the Harness goal-round driver continues the work.
Acceptance gate (src/acceptance/): the only path to completed; database triggers make completion without a pass receipt impossible.
Storage (src/store/ + migrations/): SQLite (node:sqlite), migrations 001–015, append-only audit, key invariants enforced by triggers.

How a resume happens

An approval, from park to acceptance

CI, timers, PR reviews and external events all take the same path: wait → durable event → idempotent consume → new Attempt.

Security model

Every capability of Reins obeys these invariants; the tests and the real-Harness verification are built around them:

Harness executes, Reins orchestrates. Public API only, no private imports, no changes to the Harness core.
Only the goal-round driver continues work inside an Attempt; one Objective has exactly one valid writer (lease + epoch fencing).
A finished Attempt never comes back to life; a parked Attempt always resumes as a new Attempt.
A sensitive call without approval is denied, and the denial must still be followed by park / cancel and a proof of quiescence.
Approval is not acceptance, and a finished Goal is not a finished Task. Approval cannot bypass the sandbox, guards, leases, budgets or the acceptance gate.
A wait keeps no Agent loop.
A side effect with an unknown result is never replayed automatically; a consumed grant is never restored, even if the tool failed or the process crashed.
SQLite and the Harness session log are separate consistency domains: quiet only with a flush proof; after a restart nothing uncertain is treated as success.
Taking over after a crash needs an exit proof bound to owner / Objective / epoch / execution; without it, that Objective is held (LEASE_BUSY) and never touched.
One live Reins process per database: another live owner makes startup fail with DATABASE_IN_USE; a process whose database was taken over stops scheduling and polling at once.
"Tests pass" is verified by Reins itself: reins.command_succeeds runs the frozen command at acceptance; if a pinned file changed, it does not run at all.
A planned Objective comes only from you: reins_create_objective works only after you typed /reins in that conversation, once, never in Reins' own sessions, and check files the planner wrote are pinned before any Agent starts.
Conservative takeover after a forced stop: a lease is taken over automatically only when the old process is recorded on this host, is confirmed gone, and had nothing running; otherwise you confirm with /reins-recover --confirm, and that confirmation is append-only.
After an approval, the same session continues: the next Attempt reopens the parked Harness session (still a new Attempt with a new Goal; the grant still allows exactly that one call). After a failure, crash or replan, a new session is used. A Task parked for approval 10 times in a row is held for you to decide.
URLs chosen by an Agent only reach allowed hosts: waits check when registered and before every poll, refuse redirects and never carry credentials.

Tests and verification

npm ci                    # dependencies
npm run typecheck         # type check against the public Harness API
npm test                  # main regression suite (about 70 seconds)
npm run test:runner       # scenario driver and verifier regression (including verifier negatives)
npm run test:live         # real DeepSeek Harness scenarios (about 4 minutes)
npm run test:live:phase3  # Phase 3 single-Task real Harness scenarios (about 2 minutes)
node scripts/build-diagrams.mjs   # rebuild the bilingual README diagrams

Current results:

Suite	Result
`npm test`	499 / 499
`npm run test:runner`	48 / 48 (including 28 Phase 4 verifier negatives)
`npm run test:live`	7 / 7
`npm run test:live:phase3`	11 / 11 gates
`npm run typecheck`	passes

Real Harness scenarios (`npm run test:live`)

Case	What it proves
`e2e`	"Get a PR mergeable" with five Tasks: no approver → park → approve → a new Attempt pushes exactly once; CI fails → fix → approved push again → CI passes; review handled; Objective completes after every acceptance
`crash-running`	Attempt killed with `SIGKILL` while running, restarted with an exit proof: reconciled as interrupted, retried, completed
`crash-consumed`	Killed after the grant was consumed and the push happened but before the result was recorded: the side effect is marked ambiguous, not replayed, completed after you confirm
`crash-awaiting-ci`	Killed while waiting for CI: the watcher resumes polling and drives the next Attempts to completion
`no-proof`	Killed without an exit proof: that Objective is held (`LEASE_BUSY`), untouched, while Reins runs
`second-process`	A second process on the same database while the first runs `e2e`: it refuses to start with `DATABASE_IN_USE` and runs nothing; the first completes normally
`subagent`	Real subagent and session fork: sensitive calls from a read-only child are recognized and denied with zero physical side effects; the child session's `parentSession` is the Reins anchor session; a fork retry really derives from the previous session

[!NOTE] The scenarios above use a deterministic model and a local GitHub stand-in. With a real model (DeepSeek), these were verified separately in DSH Web: /reins planning (look first, ask about a real choice, write and pin the check, create; then the Reins Agent did the work and the pinned check passed); /reins-goal; normal fixes, correcting after a denial, approvals, an impossible task, the default tool policy, a forged test report, and reins.command_succeeds acceptance (with a forged report present, Reins ran the tests itself, got exit 1, and the Task did not complete).

Project layout

reins/
├── src/
│   ├── plugin.js              # plugin entry (Cordis apply)
│   ├── config.js              # configuration schema and strict validation
│   ├── live-config.js         # settings saved on the Plugins page apply without a reload
│   ├── commands/              # /reins and /reins-* commands, /reins planning (plan.js)
│   ├── orchestrator/          # DAG, waits/events, watchers, approvals, worktrees, routing, fingerprints, handoffs
│   ├── orchestration/         # runtime: admission, budgets, no-progress, outer settle
│   ├── acceptance/            # acceptance gate, frozen criteria, validators, receipt integrity
│   ├── approval/              # relational approvals (Phase 2)
│   ├── store/                 # SQLite store, transactions, migrations, instance lock
│   ├── reconcile/             # startup reconciliation
│   ├── harness/               # public Harness API adapter
│   └── tools/                 # task_complete tool
├── client/client.js           # settings page on DSH Web's Plugins page
├── migrations/                # 001–015, only ever added to
├── scripts/                   # real Harness scenario drivers, independent verifiers, diagram builder
├── tests/                     # regression tests grouped by feature (see tests/README.md)
├── docs/assets/               # README images (English and Chinese)
└── smoke/public-api.ts        # public API type-check sample

Development

Rules

For a feature or a fix, first write a test that reproduces the problem, then change the code.
Never delete or loosen a safety assertion to make a test pass. Identity binding, lease fencing, and default-deny for approvals and acceptance stay.
Task and Objective completion goes through the acceptance gate, never through a model's "done" or a direct database edit.
Never commit API keys, real user configuration, real databases, logs or run evidence.
After every change run typecheck, test and test:runner; for framework lifecycle, recovery or tool calls also test:live.

Conventions

Schema changes only add migrations; 001–015 are never rewritten.
A new user action is a new top-level /reins-<action> command (a row in COMMANDS in src/commands/register.js); the real-Cordis unload test pins the exact command set. listValidatorKinds() stays at the 6 file validators; new acceptance kinds go into the separate reins.* registry.
Temporary test files go through tests/fixtures/scratch.js; never hard-code local paths.
Text files use LF (enforced by .gitattributes).
The English and Chinese diagrams are built from one description by scripts/build-diagrams.mjs.

What gets published

package.json files contains the plugin only (src, migrations, client, locale, the bundle patch, icon, license and README); tests, scripts and dev dependencies are not published.

Known limitations

File criteria trust files in the working directory, which the Agent can write; for "tests / build pass" use reins.command_succeeds.
reins.command_succeeds runs code from the working directory; any file not pinned may have been changed by the Agent. It does not run in a sandbox.
/reins planning depends on the judgement of the conversation's model: it may decide something you would have liked to be asked about, or pick a check that is weaker than you want. Read its summary; /reins-status <id> shows the exact check of every Task. /reins-goal does not pin test files; for a stronger guarantee use /reins (which pins checks it wrote) or /reins-objective with pins.
With a real model, /reins planning, /reins-goal and single-Task scenarios are verified; CI / PR watchers, crash recovery, parallel worktrees, subagent / fork and replanning were verified in the real Harness with a deterministic model only.
Tested on Windows only; Linux and macOS are unverified.
Desktop notifications are built in on Windows only; elsewhere configure notifyCommand.
DSH's sandbox blocks commands that start child processes, such as node --test, so an Agent may ask to widen the sandbox; acceptance is not affected, because Reins runs the tests itself outside the sandbox.
Single-Task Objectives (/reins create) run one at a time and, without evidenceRoot, work in the DSH process's start directory; orchestrated Objectives run in parallel execution slots.

License

MIT.

remote

remoteWatcherHosts

Reins

兼容性与来源证明

版本

相关插件

Reins

README

Why Reins

How it works

Features

Install

Requirements

1. Get a fixed copy

2. Install the plugin

3. Settings on the Plugins page

4. Check

Update, roll back, uninstall

Quick start

Say what you want

One sentence, your own check

Then two commands are enough

In DSH Web

Several Tasks by hand: get a PR mergeable

Commands

Agent tools

Configuration

Architecture

How a resume happens

Security model

Tests and verification

Real Harness scenarios (npm run test:live)

Project layout

Development

Rules

Conventions

What gets published

Known limitations

License

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

Why Reins

How it works

Features

Install

Requirements

1. Get a fixed copy

2. Install the plugin

3. Settings on the Plugins page

4. Check

Update, roll back, uninstall

Quick start

Say what you want

One sentence, your own check

Then two commands are enough

In DSH Web

Several Tasks by hand: get a PR mergeable

Commands

Agent tools

Configuration

Architecture

How a resume happens

Security model

Tests and verification

Real Harness scenarios (npm run test:live)

Project layout

Development

Rules

Conventions

What gets published

Known limitations

License

Real Harness scenarios (`npm run test:live`)

Real Harness scenarios (`npm run test:live`)