harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- harness
- description
- The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
02 资源文件 72
- 其他dispatch.cs2.3 KB
- 其他examples/config.jsonc1.0 KB
- 其他examples/policy.jsonc1.8 KB
- 参考文档global.json111 B
- 参考文档references/backends.md28.9 KB
- 参考文档references/cli.md53.0 KB
- 参考文档references/config.md23.6 KB
- 参考文档references/cookbook.md5.7 KB
- 参考文档references/guide.md11.7 KB
- 参考文档references/ledger.md50.0 KB
- 参考文档references/task-file.md35.3 KB
- 其他src/Backends/Codex/CodexBackend.cs49.4 KB
- 其他src/Backends/Codex/CodexHome.cs19.1 KB
- 其他src/Backends/Codex/CodexProcess.cs47.7 KB
- 其他src/Backends/Codex/CodexProtocol.cs11.5 KB
- 其他src/Backends/Codex/CodexRpc.cs14.3 KB
- 其他src/Backends/IWorkerBackend.cs1.6 KB
- 其他src/Backends/OpenCode/OpenCodeBackend.cs29.8 KB
- 其他src/Backends/OpenCode/OpenCodeCatalog.cs6.1 KB
- 其他src/Backends/OpenCode/OpenCodeCollect.cs4.6 KB
- 其他src/Backends/OpenCode/OpenCodeHost.cs20.5 KB
- 其他src/Backends/OpenCode/OpenCodeProfile.cs3.2 KB
- 其他src/Backends/OpenCode/OpenCodeRules.cs3.4 KB
- 其他src/Backends/OpenCode/OpenCodeSignals.cs17.7 KB
- 其他src/Backends/Types.cs17.4 KB
- 其他src/Cli/Args.cs3.3 KB
- 其他src/Cli/BackendScope.cs4.5 KB
- 其他src/Cli/Cli.cs7.7 KB
- 其他src/Cli/Commands.Control.cs20.9 KB
- 其他src/Cli/Commands.cs28.2 KB
- 其他src/Cli/Commands.SelfCheck.cs20.7 KB
- 其他src/Cli/Commands.Usage.cs10.7 KB
- 其他src/Config/AllowList.cs3.8 KB
- 其他src/Config/ConfigLayers.cs7.4 KB
- 其他src/Config/ConfigResolver.cs21.7 KB
- 其他src/Config/Locations.cs8.9 KB
- 其他src/Config/Policy.cs2.6 KB
- 其他src/Config/Wildcard.cs1.1 KB
- 其他src/Contracts/AskFiles.cs1.8 KB
- 其他src/Contracts/ConfigFiles.cs1.6 KB
- 其他src/Contracts/Constants.cs938 B
- 其他src/Contracts/Errors.cs225 B
- 其他src/Contracts/Json.cs6.6 KB
- 其他src/Contracts/LedgerShapes.cs10.5 KB
- 其他src/Contracts/TaskFile.cs3.1 KB
- 其他src/Escalation/AskQueue.cs3.1 KB
- 其他src/Escalation/Escalation.cs9.1 KB
- 其他src/Ledger/Ledger.cs10.9 KB
- 其他src/Ledger/SupervisorLock.cs1.9 KB
- 其他src/Scheduler/Plan.cs1.3 KB
- 其他src/Scheduler/Planner.cs27.1 KB
- 其他src/Scheduler/Prompt.cs11.4 KB
- 其他src/Scheduler/Scheduler.cs31.5 KB
- 其他src/Scheduler/Settlement.cs12.6 KB
- 其他src/Scheduler/Supervisor.cs1002 B
- 其他src/Scheduler/TaskRun.cs4.6 KB
- 其他src/Scheduler/TaskStarter.cs13.8 KB
- 其他src/Usings.cs382 B
- 其他src/Verify/Deliverable.cs18.4 KB
- 其他src/Verify/StructuredOutput.cs4.1 KB
- 其他src/Verify/Verifier.cs5.8 KB
- 其他src/Workspace/Commit.cs5.7 KB
- 其他src/Workspace/Executables.cs2.9 KB
- 其他src/Workspace/Git.cs7.7 KB
- 其他src/Workspace/GitConfigGate.cs5.3 KB
- 其他src/Workspace/Proc.cs4.4 KB
- 其他src/Workspace/Scope.cs9.8 KB
- 其他src/Workspace/Scratch.cs5.4 KB
- 其他src/Workspace/Snapshot.cs1.1 KB
- 其他src/Workspace/UserPathGuard.cs2.3 KB
- 其他src/Workspace/WorkerEnvironment.cs4.2 KB
- 其他src/Workspace/Worktree.cs25.5 KB
03 SKILL.md 正文
Dispatch harness
The harness runs tasks on worker models out of process, through two equal backends, opencode and Codex. Per task it prepares a workspace, starts the worker behind a write fence where the platform has one, answers or escalates its asks, settles the result from git, runs the verify commands on that result, and records every step in a ledger. This skill is the harness's contract.
Boundary
- This skill says how to run a task. What to hand out and how to judge the result belong to the caller.
- The caller selects the contract file paths (
contracts,--contract); the harness prepends only those files, whole, and depends on no other skill. - A calling skill that sends
structuredtasks owns their prompt and result schema. - Use
preparefor dependency steps outside the sandbox: Dependencies and the sandbox. When a build, test or tool fails under the fence or sandbox, readreferences/cookbook.md.
Invocation
From this skill's folder (its global.json selects the SDK), build, then run the command:
dotnet build dispatch.cs
dotnet dispatch.cs -- <command> [arguments]
- Build before every command. A non-zero build exit means nothing started; fix the error or retry
when two builds collided. The
--keepsdotnetfrom taking flags such as--force. - Paths on the command line are absolute (task file,
--repo,--contract,--ledger); paths in a task file are relative to that file, exceptdir(relative to the repository root). Contract semantics:references/task-file.md#contracts. In PowerShell use$PWD.ProviderPath. - Run
selfcheck [--repo <path>]on a new machine, after an update, and in a new repository. It checks each backend the configuration selects, or every installed one when none is selected (version, sign-in, catalog, a clean profile), Windows readiness and every resolved folder, and sends no prompt. Discovery and exit behavior:references/cli.md. - Commands:
selfcheck,routes,plan,run,status,usage,wait,asks,reply,cancel,collect,resume,clean. Arguments, output and exit codes of each:references/cli.md.
Backend and modes
Codex provides an OS sandbox; opencode's Linux/macOS fence is an accident guard, not a security boundary; Windows runs unfenced. Both support structured output. Modes and defaults:
| Setting | Values | Code, mechanical | Review, research | Structured |
|---|---|---|---|---|
profile |
clean (minimal profile), full (installed profile) |
clean |
clean |
clean |
project |
on (repository context loads), off |
on |
on |
off |
access |
read-only, workspace, full |
workspace |
read-only |
read-only |
workspace |
worktree (own branch from base), in-place (dir) |
worktree |
worktree |
scratch folder |
- Every task kind defaults to
profile: clean; explicit profiles at any layer win. A task that needs the installed profile's tools (MCP servers, plugins, skills) setsprofile: full. Codexaccess: fullremoves its sandbox. opencoderead-onlydenies edit and keeps the shell inside the fence; on Windows it also declines every shell call by default. workspace: in-placeruns indir, main checkout included.commit: none(default) records the diff without committing;commit: harnessrequires a clean tree and commits on the current branch.- Read-only writes are declined. For escalated shell asks,
readOnlyShell: decline(default) rejects;escalatelets a matching rule reach the operator. Replyoncepermits one command, outside the sandbox on Codex. - Denies beat escalation. Both backends decline unmatched asks in read-only tasks, MCP tools included.
Otherwise opencode answers
once; Codex declines with feedback. Codex denies apply only at approval: withworkspaceand network on, agit pushdeny cannot stop a push. - An unfenced opencode shell can write the harness's control folder and run ledger. Build caches a
fenced or sandboxed task must write go in
writableRoots(references/config.md). Verify commands run the worker's code as your user, outside sandboxing, on every backend. - Preferences layer user config < repository
.dispatch/< task file < command line. Restrictions (denies, scope, maximum access, network) only add up, and the route allow-list is the intersection of the layers that have one. Details:references/config.md.
Task file
{
"schemaVersion": 2,
"contracts": ["contracts/common.md", "contracts/model.md"],
"tasks": [
{ "id": "fix-guide-typo", "kind": "code", "backend": "codex", "route": "<model>#<effort>",
"base": "<branch>", "promptFile": "fix-guide-typo.md", "scope": ["docs/guide/"],
"verify": ["<build command>", "<test command>"], "timeoutMinutes": 60 }
]
}
kind:code,review,research,mechanicalorstructured. Each task names arouteor anagent; the harness never uses a backend's default model. Routes: opencode<provider>/<model>[#<variant>], Codex<model>[#<effort>].scopeis required forcodeandmechanical; two such tasks of one run never share a path (sharedPathsexempts a path from that overlap check only). A change outsidescopefails the task.structuredcarriesinput(items, id field) andresult(a JSON Schema in the harness's keyword subset, identity, immutable fields); it never commits or verifies.- Write the task file with an editor tool, not a shell heredoc. Every field:
references/task-file.md.
Run lifecycle
- Plan.
plan <tasks.jsonc>validates the file, contracts, allow-list and live catalog. - Run.
run <tasks.jsonc> [--run <name>]is the supervisor: it blocks until every task is final. To keep working meanwhile, start it from a background shell and watch from another one. A background run wakes you only through a waiter you arm in the same step: your tool's completion notice for that shell, orwait <run> --timeout <minutes>from another shell after startingrun(the waiter allows two minutes for its ledger to appear). Keep this timeout below your waiting shell or tool's timeout, and callwaitagain after exit 3. When you come back to a run without one, start withstatus <run>;(no supervisor: …)means nothing is driving it. - Watch.
status <run>shows each task's state, tool count and last tool call. States:queued,dispatching,running,waiting(escalated ask),settling,interrupted, and the finaldone,failed,cancelled. Usewait <run> --timeout <minutes>after startingrunto wait for those final states and print the status summary; choose a timeout below your shell or tool's timeout and call it again after exit 3. It exits at once if a recorded unfinished run has no supervisor. Startup grace and waiter exits:references/cli.md. - Answer.
asks [<run>]lists escalated asks;reply <run> <askId> once|reject [--message <text>]answers one. Answers are one-shot; the harness never grants a standing approval. - Stop.
cancel <run> <task>. Never kill the supervisor. - Read. Each task has
result.jsonandfinal.md; a code task addsdiff.patchandverify.log, a structured taskdeliverable.jsoninstead. These are the evidence; the worker's final text is not. Layout:references/ledger.md. - Clean. After the work is merged,
clean <run>removes worktrees, branches, temporary folders and backend sessions; unmerged or dirty work stays unless--force.
Exit codes
| Code | run |
|---|---|
| 0 | Every task done: verify green, changes in scope, structured deliverable valid |
| 1 | A task failed, was cancelled, is out of scope, or is not final; or the run aborted after it started |
| 2 | Nothing started: missing tool, signed-out backend, invalid task file, existing run id, usage error |
Recover, never rerun
A recorded run is never run again and its ledger is never edited by hand.
status <run>tells a stalled run from a working one:(supervised now)while a supervisor drives it,(no supervisor: resume <run> settles it)once none does. Check it whenever a run's completion notice is late or the host killed the shell that waited for it.- The supervisor stopped (restart, killed process): run
resume <run>once. It settles what ended and settles every started Codex task that is not final aslost; fenced opencode tasks whose server is gone are also lost, never reconstructed.resume <run> --continuere-prompts interrupted unfenced opencode tasks and starts the tasks that never started. - A task without a result while no supervisor holds the run:
collect <run> <task>. - A new attempt can retain eligible failed work without reusing the recorded run: set task-field
continueOfand make its prompt the amendment. - Work that needs a fresh attempt goes into a new task file, under a new run id; use
basefor a deliberate fresh start rather than retaining collected work.
Traps
- Host kills. A background shell's timeout must exceed the run's longest
timeoutMinutes, and the host's memory must holdmaxParallelmeasured task peaks (config). Otherwise the host kills the supervisor:resumesettles what it left, and Codex tasks that were running settlelost. - Codex plugin cache. Codex keeps one cached plugin version and may replace it during a run,
removing the supervisor's own files. Start the harness from a stable copy outside that cache;
selfcheck,planandrunwarn when started there (CLI). - Machine-wide state. Environment isolation does not cover the Windows registry, scheduled
tasks or the credential store. SDK first-use behaviour, including user PATH appends and HTTPS
development certificates, belongs in your
environmentconfiguration; the harness supplies no ecosystem switches. See the cookbook.selfcheckwarns on a long user PATH andrunrefuses a very long one. Do not pointDOTNET_CLI_HOME,CODEX_HOMEorXDG_DATA_HOMEat new folders yourself: the backends' sign-in lives in their homes. - Inherited Codex rules. Codex's app-server loads exec-policy rules it cannot be told to
ignore: an
allowrule can run a matching command outside the sandbox without asking.profile: cleandrops your own rules; system-level rules always load.planandresult.json(capabilityNotes) state what still applies to each read-only Codex task. - Approval gates in the repository. A worker that meets a rule asking for approval before any
change returns
donewith an empty diff. The fix belongs in that repository: scope its approval rules to the session that talks to the user; a dispatched worker runs the task it was given. - Read-only planning. A read-only task cannot write a plan file: return the plan in the final
text, or run it as a
codetask withaccess: workspaceandscopeset to the plan path (any change by arevieworresearchtask fails scope). - Long single-line inputs. Worker read tools truncate them; give Markdown or pretty-printed JSON.
- Windows paths. Deep repositories pass the path limit in worktrees: see
references/config.md. - Shell deny rules match command text only. Treat them as a guard against mistakes.
References
Read on demand: references/guide.md (which setting to choose for a task, why, and what a result
proves), references/task-file.md (every field, default, validation error), references/cli.md
(arguments, output and exit codes), references/ledger.md (run folder, events, fields),
references/config.md (layers, rules, allow-list, locations), references/backends.md (each mode,
rule and limit on opencode and Codex), references/cookbook.md (configuration recipes per ecosystem,
each labelled with where it was tried).
04 同仓库更多 Skills
writing-tunit-tests
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.
dotnet-walls
Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.
csharp-15
Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.
verified-waves
Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.
harness
The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.
delegating-to-worker-models
Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.