dsh-double

dsh manages dsh — and twin dsh talks to twin dsh. A self-management, self-evolution & twin-communication plugin for DeepSeek Harness: blue-green self upgrades, health probing, last-known-good snapshots, plus an isolated testbed twin — a full second dsh instance the main can operate freely, that talks back agent-to-agent and evolves the main after proving changes in its sandbox.

What it does

A typical agent that modifies itself dies on restart, then needs an outside agent to come rescue it. dsh-double closes that loop so the agent can evolve itself safely:

1. Self-evolution (blue-green) — a change set is applied to a standby copy first, statically pre-checked (dump-config, YAML/JSON syntax, bundle resolvability, NO_ADAPTER guard, duplicate loader-entry detection) and trial-booted. Only when both pass is the change applied to the main dsh, which then restarts and must confirm healthy before the standby is stopped. If the main fails to boot, it auto-rolls back to the pre-evolution snapshot.
2. Health probing — main instance health is verified by TCP + HTTP + process checks (dsh writes no pid file), with the evidence chain shown in status.
3. Snapshots / last-known-good — a baseline snapshot is taken before any evolution and restorable on demand.
4. Wake-on-demand standby — when the main is stuck and mechanical recovery failed, the dormant standby (a disk-only copy, zero processes, zero ports) is woken as a temporary dsh instance on a separate port as a "spare brain" to diagnose and repair the main. It is never left running in normal operation.
5. Twin dsh (peer brains) — ~/.dsh/double/testbed/ is a real, fully isolated second dsh (own DSH_HOME, port 3081, fresh sessions; config cloned from main; node_modules / attachment objects shared read-only). Disk-dormant by default, woken on demand. Each side gets twin_* tools with full mutual operational control over the other (exec, fs read/write, lifecycle, evolve).
6. Agent-to-agent communication — twin_message sends text to the twin's own agent over the official /api gateway (session.create → session.prompt → poll session.history to turn/end) and returns its reply: the two LLM brains genuinely converse and collaborate. When the testbed has proven an evolution in its sandbox, the main can tell it "now evolve me" and the twin agent runs twin_evolve itself — blue-green, restart and all.
7. Anti-black-box by design — every twin_message lands as a real, replayable session in the receiving instance's UI; every interaction is appended to a shared, auditable transcript (~/.dsh/double/comm/transcript.jsonl, surfaced by twin_log, the dsh-double.py comm CLI and the dashboard card).

The heavy lifting lives in the battle-tested, zero-dependency CLI bin/dsh-double.py and a small out-of-process bin/dshd-supervisor — boot-time failures happen before any plugin runs, so life-support must stay outside the dsh process. This plugin exposes that machinery to the ecosystem.

Features

• In-harness tools (double_*) — the agent inside dsh can run its own evolution cycle end-to-end: double_status, double_check, double_snapshot, double_evolve, double_rollback, double_wake, double_stop.
• Twin tools (twin_*, role-relative — each side operates its peer): twin_status, twin_message (agent-to-agent request/response), twin_exec, twin_fs_read, twin_fs_write (full operational control), twin_evolve (blue-green the twin: testbed→main or main→testbed), twin_restart, twin_log; main side additionally: twin_up / twin_down / twin_init / twin_sync / twin_reset / twin_diff / twin_baseline.
• HTTP API — GET /double/status, GET /double/check, POST /double/snapshot, POST /double/evolve, POST /double/rollback, POST /double/wake, POST /double/stop, plus the /double/twin/* surface mirroring the twin tools (status/log/message/exec/fs/evolve/up/ down/restart/init/sync/reset/diff).
• Settings dashboard — two cards in dsh 设置: the self-management panel (main health, last-known-good, snapshots, standby, one-click actions) and the twin communication panel (peer status, lifecycle buttons, a message box that talks to the twin's agent, and a live feed of the shared comm transcript).
• Testbed-first workflow guidance — a global ~/.dsh/AGENTS.md iron rule plus the dsh-twin-workflow skill (skill/) steer agents to experiment in the twin (3081) and only then twin_diff + twin_evolve the proven delta back; testbed clone/reset carries the rule and skills into the twin.
• Twin session visibility — GET /double/twin/threads replays both twin threads (text + tool calls/results) in the main dashboard card, so watching only the main page is enough to follow everything the twins said.
• Transparent main restarts — testbed→main evolves announce themselves in the transcript and wait evolveNoticeSec (8s default) before dropping the page; after dsh's auto-reconnect the card banners the outcome. Opt-in requireEvolveApproval queues twin evolves for main-UI approve/reject; the approved engine runs in a double-forked detached wrapper that survives the restart and records the final result.

Install

Requires the dsh-double CLI + supervisor on the host (shipped in this repo under bin/): install bin/dsh-double.py and bin/dshd-supervisor to ~/.local/bin/ (make them executable).

dsh plugin add dsh-double

Or link it from source:

git clone https://github.com/Junkrat9527/dsh-double.git ~/dsh-double
cd ~/dsh-double && npm install && npm link
dsh plugin add dsh-double

Then restart dsh and check 设置 → 自我管理（dsh-double） or call GET /double/status.

Usage

Ask the agent, or call the API/tools directly:

"先跑 double_check 预检我的配置，然后 double_evolve 应用我准备好的变更目录，
成功后 double_status 确认主实例健康、备用身已休眠。"

Or via HTTP:

curl http://127.0.0.1:3080/double/status
curl -X POST http://127.0.0.1:3080/double/evolve -H 'content-type: application/json' \
  -d '{"change_dir": "/path/to/change-set"}'

Twin workflow (experiment in the sandbox, then let the twin evolve the main):

dsh-double.py testbed init && dsh-double.py testbed up   # wake the twin @3081
# ...experiment in the twin (its UI at http://127.0.0.1:3081 is fully isolated)...
dsh-double.py testbed diff                                # delta vs baseline
curl -X POST http://127.0.0.1:3080/double/twin/message -H 'content-type: application/json' \
  -d '{"text": "验证通过后，请调用 twin_evolve 把你的增量应用到主 dsh"}'
dsh-double.py comm 20                                     # audit the whole exchange

Architecture

~/.dsh/double/
├── snapshots/        # baseline snapshots (health-baseline copies)
├── standby/          # dormant standby copy (blue-green precheck target)
├── evolutions/       # evolution event log (pass/fail, rollback?)
├── comm/transcript.jsonl  # shared twin-communication audit log
├── supervisor.log    # life-support events
├── last-known-good   # pointer to the last healthy snapshot
└── testbed/          # the twin: a full, isolated second dsh (DSH_HOME, port 3081)
    ├── ...           # config cloned from main; node_modules & attachment
    │                 #   objects symlinked read-only; FRESH sessions/storages
    └── baseline/     # main-config reference for twin diff

Ports: main 3080 (no --port arg), testbed 3081, blue-green trial boot 3082 — process probes anchor on these so the twins never confuse each other's health.

• L0 life-support shell (dshd-supervisor, out-of-process): probes main health, auto-restarts, rolls back to last-known-good, wakes the standby — works even when dsh itself cannot boot.
• L1 self-management (dsh-double.py + this plugin): snapshot / check / evolve / rollback / wake / stop; the in-harness agent drives it via tools.

License

MIT — Copyright (c) 2026 Junkrat9527