orchestra

English | 中文

Keep one long task moving across many context-bounded AI sessions: pressure measurable, handoffs verifiable, sessions resumable, work parallelizable, goals auto-orchestrated, sessions coordinateable.

Motivation

1. Context windows are finite. By the second half of a long task the model forgets, slows down, gets compacted, and eventually cannot continue.
2. Manual copy-paste continuation is unreliable. Copying an old conversation into a new one loses information, cannot be verified, and does not guarantee "pick up exactly the next step".
3. Complex work needs collaboration. Parallel sessions each work on a piece while one coordinator keeps the whole picture; any session can rotate into a fresh one when its context fills up, without interrupting the task.

Approach

Everything is user-level assembly, zero intrusion into the shipped Harness, living under ~/.dsh:

Five capability domains: relay (cross-session continuation) · parallelism (worktree workers) · orchestration (mission) · coordination (multi-session hub) · pace.

Usage

Since v34: /sessions, /sessions_active and /workers annotate each row with the session workspace kind ([worktree of <repo>] = a git worktree sibling checkout, [plain] = a non-git directory), so you can see at a glance which repo each session works in.

Since v35: the role-discipline section gained a "capability self-check" line — every session first inspects the delegation tools it ACTUALLY has (use the plugin commands when available, otherwise the subagent family), and creates its own sibling workspaces with git worktree add for isolated scratch work, listing every created workspace path in the report; the worker prompt likewise gains a "self-organization permission" (6th discipline item), while "work only in this workspace" and "then stop" semantics are unchanged.

Since v36: message correlation — /relay, /steer and /coordinate-intake envelopes carry a short question id q-xxxxxx; the named session ECHOES that id at the start of its reply (e.g. [q-3f9a2c] answer…) so the coordinator knows at a glance which instruction a reply answers; auto-forwarded replies additionally carry a [reply to q-xxxxxx] tag as a best-effort fallback (omitted when no prior question is found).

Since v37: decision layer model — every coordinator knows its own decision layer (a derived property of the coordination tree: longest path to a leaf — L0 leaf / L1 first-level hub / L2+ nested hub; the tree grows, the layer grows) and its own mandate (decision-domain intent, declared and persisted via /coordinate-hub … --mandate <text>); the layer line and information contract are steered in when a link is established or restored after a restart (the layer controls information density, the mandate controls decision boundaries), and /coordinate status shows them anytime — still available after a restart.

Since v38/v9: rotate link-migration fix (production defect) — /rotate (or /worker-successor) migrates the coordination links with the rotation: the source hub's hub=… spokes=… record is rewritten to the successor and every spoke receives a fresh hub=<successor> record, so after a restart spokes forward to the new hub automatically. The migration record is read on the PLUGIN side and fed to the host driver (the driver ctx cannot resolve sessionQuery — the exact reason the old version silently skipped migration in production); migration failure is never silent — the completion message says coordination links NOT migrated: <reason> and the successor receives a "links not migrated" notice (re-link manually with /coordinate-hub or let restore recover after a restart). Also, when coordinateForwardMarker is configured, a reply that ECHOES a question id q-xxxxxx at its start is forwarded back to the coordinator even without the coordination marker, provided that id exists in this session's log as a recent coord/steer envelope (a direct answer to a pointed question must come back; bare "ack" messages stay filtered).

Since v39/v10: mixed-topology persistence + worker-successor input fed by the caller (production-fix round two) — durable link records now carry the FULL topology: a hub's own /coordinate peers are written into the hub record too (hub=<id> spokes=… [peers=…]), and a non-hub session's multi-peer record persists every peer (peers=a,b,c), so after a restart both hub→peer and peer→hub directions survive — previously the hub's peers never entered its record and the hub→peer direction was lost forever on restart (the peer-side record remained, leaving a one-way link). /worker-successor now also reads the worker log (header/checkpoint/link record) on the PLUGIN side and feeds { record, workerLog } to the driver (the host driver ctx cannot resolve sessionQuery — v9's self-read would fail in production the same way); when the log cannot be read and no sessionQuery exists, the rotation fails LOUDLY with an error; link-migration failure keeps the "NOT migrated + notice" pattern. The rotation rewrite touches only hub= — spokes=/peers= are preserved verbatim, so the successor carries the full mixed topology.

Since v41/v11/v9: rotation is fully automatic (the user asked, verbatim: "I don't want to do anything; what I want to drive is /rotate; no compromises") — zero manual steps after /rotate. Besides coordination links, /rotate now also migrates the hub's decision-domain mandate and the durable mission checkpoint onto the successor (the mission auto-resumes via the plugin's mount, so no manual /mission resume); worker completion notifications are retargeted to the live successor via the worker's newest durable link record; and oldSession defaults to 'auto' — the old session is archived only AFTER every relation migrated (a partial migration keeps it alive and says so LOUDLY). 'keep'/'archive' override the default.

Since v42: hub→spoke delivery-channel guard (production-defect fix) — the ONLY way to send a message to a spoke/peer is to run the /relay <session-id> <message> command (use /steer for IMPORTANT content); a header like "【协调中心 → X】"/"【协调者 → X】" (or [coordinator -> X]) written in your reply body is NOT delivered — a spoke receives only what you actually relay/steer. When the coordinator's own reply body carries that header, the plugin reminds it ONCE to use /relay (it never blocks or rewrites the reply).

Since v46: FULL STEER — every hub↔spoke message arrives at the NEXT STEP BOUNDARY — hub→spoke instructions (/relay, /steer, /coordinate-intake and the matching tools) and the spoke→hub auto-forward all emit through the harness step-boundary channel (agent.steer): a running target still receives them, consumed before its next model decision — corrections no longer wait for the target's turn to end, and a busy hub sees the new report DURING the turn in which it processes the previous one (no more stale-snapshot coordination). The v43 mid-turn refusal is gone (soft boundary → a running target is always deliverable); --force is kept for command compatibility; consecutive updates to the same target are processed in arrival order with the LATEST WINS.

Since v45: delivery-tool registration reliability + channel text naming the tools — after the v44 restart the coordinator still reported "no /relay in this session" (spoke instructions need user relay), for two reasons: ① the preset's standing mount is single-flight and cached per process generation, and a GUI cold-read can trigger it DURING BOOT before the host tools service is up — the old "service missing → give up" guard then silently dropped the tools for the whole generation (verified live: v44 mounted, v42/v37 steers flowed, yet a live agent's catalog had no relay/steer tools); v45 retries every 2s until the registry is reachable (idempotent). ② the v42 delivery-channel texts (onboard.deliveryChannel/roles.coordDelivery) said the ONLY way is the /relay COMMAND and never named the tools — v45 rewrites both (zh+en) to add "or call your agent tools relay_to_session/steer_to_session (tool-form twin of the commands, they ARE in your tool catalog)", so a hub never concludes it lacks a delivery surface.

Since v44: delivery-tool wire-schema fix (the root cause of the v43 global HTTP 400) — v43's tool definitions put required: true INSIDE parameters.properties.<name>, which is not valid JSON Schema (required must be an array of strings at the object level); the harness's local registration validates only output.schema and forwards parameters verbatim, and the DeepSeek endpoint's strict schema validation then rejected the WHOLE request with 400 Invalid schema for function 'relay_to_session': true is not of type "array" — because the preset is the deployment default, EVERY message of EVERY session failed. v44 drops the per-property required: true (the object-level required: ['target_id','message'] stays), with no behavior change — the wire shape now matches first-party tools compiled via parameterSchemaSpecToJsonSchema. Lesson: when toolifying a command, validate the wire shape the remote accepts, not just the local catalog.

Since v43: plugin-registered delivery tools — the agent tools relay_to_session(<target-session-id>, <message>) and steer_to_session(<target-session-id>, <message>) are the tool-form twin of the /relay and /steer commands (same delivery kernel, same continuity-coord/continuity-steer source tag, same v36 q-id envelope), registered in the preset's standing scope — every agent on this preset has them in its tool catalog and can deliver by calling the tool (byte-identical to the commands); steer_to_session has NO --force escape hatch (mid-turn targets are always refused). The command surface stays 26 (tools do not occupy command slots).

Since v40: approval-stuck detection + goal/conflict warning (ops blind-spot fix, pure-plugin) — the harness approval has NO timeout and NO query RPC, so a session stuck on the approval dialog looks exactly like a healthy working session (a coordinator's 15-minute check-in used to see nothing). The plugin detects the dangling approval/asked (no same-id approval/decided) pair in the session's OWN event log: the hub check-in appends an APPROVAL STUCK ALERT for each stuck spoke (⚠️ spoke {id} stuck on approval: {tool} (since {time}) — you may need to approve it), /workers appends ⏳ pending approval: <tool> to stuck worker rows, and /session-peek prepends a pending-approval note to its output. Also, the harness /goal is DRIVING-style (queues the next round as soon as the agent is idle, no backoff) while coordination is WAITING-style — when this session is a hub AND an active goal is detected, /coordinate status warns: run /goal pause (GUI or this session) while waiting for spoke replies or a user decision, and use /mission for automatic orchestration. Usage taboos: see §"六之二" in docs/COMMANDS.md.

Full command reference: docs/COMMANDS.md.

Quick start

Prerequisite: DeepSeek Harness installed (DSH_HOME, default ~/.dsh).

Run from any directory (the clone location does not matter: the installer copies the deploy/ mirror into ~/.dsh; the repo folder is just a staging area):

git clone https://github.com/yiqiaowang-arch/orchestra.git
cd orchestra
powershell -ExecutionPolicy Bypass -File scripts/install.ps1

Then create a session, pick Orchestra in the preset selector, and run /continuity — seeing tokens / capacity / ratio means it works.

Maintainer (repo publisher) flow: after changing the LIVE runtime files (~/.dsh/.agent-presets/…, ~/.dsh/continuity-host/…, profile patch layers) and BEFORE every commit, run scripts/sync-deploy.ps1 — it mirrors live into deploy/ (archives superseded generations, sanitizes the <USER> placeholders) — then run scripts/install.ps1 to validate the same file set installs end to end (install restores the placeholders to real paths and makes difference backups). Clone-and-install users neither need nor should run sync-deploy — it only mirrors live→deploy back into the repo; installation is exclusively install.ps1 (deploy→live).

Platform: currently Windows-first. On macOS / Linux you need PowerShell Core (brew install powershell → pwsh) to run the installer, and the preset's shell tooling currently enables only the Windows pwsh — macOS / Linux are not adapted yet.

Docs

License

This project is a personal capability extension for DeepSeek Harness (MIT), running entirely in the user-owned directory (~/.dsh), decoupled from any business repository; it never modifies the shipped installation. Licensed under the MIT License, same as DeepSeek Harness.

The repository contains no personal absolute paths: local paths appear as the C:\Users\<USER>\ placeholder, and the install script, tests, and doc checks resolve real locations dynamically from the $DSH_HOME / $DSH_HARNESS environment variables (defaulting to ~/.dsh / ~/Documents/GitHub/deepseek-harness).