@devorch/cli-linux-x64 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "devorch-cli",
3
+ "owner": { "name": "Dev Orchestrator" },
4
+ "description": "The Claude Code companion mod shipped with the devorch CLI. Added by 'devorch companion install' from the folder beside the CLI binary.",
5
+ "plugins": [
6
+ {
7
+ "name": "devorch-companion",
8
+ "source": "./devorch-companion",
9
+ "description": "The DevOrch skills (/devorch-companion:sdlc-drive, /devorch-companion:devorch-step), the devorch-step-worker agent and a DevOrch MCP server, plus a mod that wakes an idle step session when a watched run can move, shows run position and open blockers, and answers blockers from a slash command."
10
+ }
11
+ ]
12
+ }
@@ -0,0 +1,24 @@
1
+ {
2
+ "name": "devorch-companion",
3
+ "version": "0.20.0",
4
+ "description": "DevOrch companion: the sdlc-drive and devorch-step skills, the devorch-step-worker agent and a DevOrch MCP server (the devorch CLI's `companion mcp`), plus a mod that watches DevOrch runs and wakes an idle /devorch-companion:devorch-step session on platform events instead of ScheduleWakeup polling. Status line, /devorch-watch, /devorch-unwatch, /devorch-answer, the devorch_companion tool and a $.devorch event hook for other plugins.",
5
+ "author": { "name": "Dev Orchestrator" },
6
+ "license": "UNLICENSED",
7
+ "types": "./types/index.d.ts",
8
+ "userConfig": {
9
+ "devorchExe": {
10
+ "type": "string",
11
+ "title": "devorch executable",
12
+ "description": "Full path of the devorch executable the mod runs for watches and answers. Leave empty to use the path `devorch companion install` recorded (the DEVORCH_EXE environment variable wins over both). The MCP server always runs the recorded path: rerun `devorch companion install` to change it.",
13
+ "required": false,
14
+ "default": ""
15
+ },
16
+ "apiBase": {
17
+ "type": "string",
18
+ "title": "DevOrch API base URL",
19
+ "description": "The DevOrch server the MCP server and run watches use. Default: the hosted API, https://api.devorchestrator.com (an empty value means the same). Set http://localhost:8700 to dogfood against a local backend. DEVORCH_API_BASE in the environment wins over this; a single watch can also name its own base URL.",
20
+ "required": false,
21
+ "default": "https://api.devorchestrator.com"
22
+ }
23
+ }
24
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "mcpServers": {
3
+ "devorch": {
4
+ "type": "stdio",
5
+ "command": "devorch",
6
+ "args": ["companion", "mcp", "--api-base", "${user_config.apiBase}"]
7
+ }
8
+ }
9
+ }
@@ -1,25 +1,105 @@
1
- # DevOrch companion mod (DEV-47 C6, DEV-56)
1
+ # DevOrch companion plugin (DEV-47 C6, DEV-56)
2
2
 
3
- A shareable Claude Code mod that turns DevOrch platform events into actions in the session: it watches a run with
4
- `devorch run watch <runId>`, shows the run's position and open blockers in a status line, and wakes an idle session
5
- with `/devorch-step <runId>` the moment the run can move (a blocker answered, a step's result applied), so an
6
- interactive run no longer polls. It is separate from this workspace's own `devorch-guard` mod.
3
+ A self-contained Claude Code plugin for driving DevOrch runs from any repository:
7
4
 
8
- ## Install
5
+ | Piece | Path | What it is |
6
+ |---|---|---|
7
+ | `/devorch-companion:sdlc-drive` | `skills/sdlc-drive/` | Claim an assigned tracker issue, start an SDLC run, drive it (Interactive or `--headless`). |
8
+ | `/devorch-companion:devorch-step` | `skills/devorch-step/` | Process one instruction of a run; `/loop` it to drive the run. |
9
+ | `devorch-companion:devorch-step-worker` | `agents/` | The subagent that does one instruction's work in a fresh context. |
10
+ | MCP server `devorch` | `.mcp.json` | `devorch companion mcp`: the CLI's stdio MCP server (full profile, no admin band). Tools read `mcp__plugin_devorch-companion_devorch__<tool>`. |
11
+ | The mod | `hooks/` | Watches a run with `devorch run watch <runId>`, shows its position and open blockers in a status line, and wakes an idle session with `/devorch-companion:devorch-step <runId>` the moment the run can move, so an interactive run no longer polls. |
9
12
 
10
- The mod ships beside the `devorch` binary (npm platform package `bin/claude-mod/`, NuGet tool
11
- `tools/net10.0/any/claude-mod/`):
13
+ Everything targets **one backend**: the plugin's `apiBase` setting, default the hosted API
14
+ `https://api.devorchestrator.com` (empty means the same). `DEVORCH_API_BASE` in the environment wins over the setting,
15
+ and a single watch can name its own base URL. The CLI's own default (`http://localhost:8700`) is untouched: the plugin
16
+ always passes its URL explicitly. It is separate from the DevOrch workspace's own `devorch-guard` mod.
12
17
 
13
- ```bash
14
- devorch companion install # records this devorch in the mod, prints the two commands
15
- claude plugin marketplace add "<path printed above>"
16
- claude plugin install devorch-companion@devorch-cli
17
- ```
18
+ ## First run (new user)
19
+
20
+ 1. **Install the CLI** (either channel):
21
+
22
+ ```bash
23
+ npm i -g dev-orchestrator-cli # or: dotnet tool install -g dev-orchestrator-cli
24
+ ```
25
+
26
+ 2. **Sign in to the hosted API.** `devorch login` honours `--base-url` and `DEVORCH_API_BASE` but defaults to
27
+ `http://localhost:8700`, so name the server; tokens are cached per base URL in `~/.devorch/token.json`, and the
28
+ plugin's MCP server reuses that session:
29
+
30
+ ```bash
31
+ devorch login --oauth --base-url https://api.devorchestrator.com
32
+ ```
33
+
34
+ 3. **Prepare and install the plugin.** `companion install` records this `devorch` in the plugin (`cli.json` for the
35
+ mod, and the `command` of `.mcp.json` for the MCP server) and prints the two `claude plugin` commands:
36
+
37
+ ```bash
38
+ devorch companion install
39
+ claude plugin marketplace add "<path printed above>"
40
+ claude plugin install devorch-companion@devorch-cli
41
+ ```
42
+
43
+ 4. **Start Claude Code** in your repository, check `/mcp` lists `plugin:devorch-companion:devorch` as connected, then
44
+ run `/devorch-companion:sdlc-drive <integrationExternalId>`.
18
45
 
19
46
  After upgrading the CLI, run `devorch companion install` again, then
20
47
  `claude plugin marketplace update devorch-cli && claude plugin update devorch-companion@devorch-cli`.
21
- `DEVORCH_EXE` (or the plugin's `devorchExe` setting) overrides the recorded executable; `apiBase` (or a watch's own
22
- base URL) points it at a worktree slot.
48
+ `DEVORCH_EXE` (or the plugin's `devorchExe` setting) overrides the executable the mod runs; the MCP server always runs
49
+ the one `companion install` recorded.
50
+
51
+ ## Design notes
52
+
53
+ - **Which `devorch` runs.** `devorch companion install` writes the executable it is running as into the plugin folder
54
+ before `claude plugin install` copies it into Claude Code's cache: `cli.json` (read by the mod) and the
55
+ `mcpServers.devorch.command` of `.mcp.json`. That path is the npm platform package's `bin/devorch(.exe)` (beside
56
+ `claude-mod/`) or, for the NuGet tool, the stable shim `~/.dotnet/tools/devorch(.exe)`, never the versioned
57
+ `.store/` folder that `dotnet tool update` deletes. No PATH lookup, no Node, no shell shim (`devorch.cmd` would need
58
+ `cmd /c` on Windows). The shipped `.mcp.json` says `devorch` so an unprepared copy (a `--plugin-dir` load of the
59
+ source) still starts from PATH.
60
+ - **Why `devorch companion mcp` rather than `devorch mcp serve`.** It is `mcp serve` over stdio with the plugin's base
61
+ URL rule built in: `DEVORCH_API_BASE`, then `--api-base ${user_config.apiBase}`, then the hosted API. A value that is
62
+ not an http(s) URL (empty, or an unsubstituted placeholder) is skipped, so "empty means prod" holds even though
63
+ `${user_config.*}` cannot express a fallback. The mod applies the same rule (`resolveBaseUrl` in
64
+ `hooks/supervision.ts`), so watches and the skills' tools hit one server.
65
+ - **Wake command.** Claude Code names plugin skills `/<plugin>:<skill>`. Before each wake the mod lists the session's
66
+ commands and submits `devorch-companion:devorch-step` whenever it is listed, even beside a project-level
67
+ `devorch-step` (this plugin's copy ships with the mod and the CLI, so they stay in step). It falls back to a listed
68
+ bare `devorch-step` only when the plugin's skill is missing. A rejected wake reads as `healthy: false`, and the skill
69
+ keeps its own `ScheduleWakeup`.
70
+ - **Tool names.** The skills name `mcp__plugin_devorch-companion_devorch__*` in `allowed-tools` and refer to verbs by
71
+ their bare name in the body ("the DevOrch MCP server's `get_next_instruction`"), so any DevOrch MCP server with the
72
+ same tools also works. Keep the server key `devorch`: renaming it renames every tool.
73
+ - **Stage work outside the workspace.** The worker follows `execute-instruction` / `evaluate-gate` and the stage skills
74
+ when the session has them (the DevOrch workspace does); elsewhere it runs the server-assembled step prompt
75
+ (`get_step_prompt`). Workspace-only steps (worktrees via `scripts/worktree_manage.py`, `app_run.py`, slot rules) are
76
+ guarded behind "in the DevOrch workspace".
77
+ - The worker's result-schema block is a copy of the workspace-rendered rule (`openapi/result-schema-rule.json`);
78
+ refresh it when that rule changes.
79
+
80
+ ## Dogfooding locally (the DevOrch workspace)
81
+
82
+ Point the plugin at the local backend so the bundled MCP server and the watches both hit it. Either set the plugin's
83
+ option at project scope, in the workspace's `.claude/settings.local.json`:
84
+
85
+ ```json
86
+ { "pluginConfigs": { "devorch-companion@devorch-cli": { "options": { "apiBase": "http://localhost:8700" } } } }
87
+ ```
88
+
89
+ or user-wide with `echo '{"apiBase":"http://localhost:8700"}' | claude plugin configure devorch-companion@devorch-cli --values-stdin`,
90
+ or set `DEVORCH_API_BASE=http://localhost:8700` in the environment Claude Code starts with (it wins over the option).
91
+ Sign in once for that URL: `devorch login --base-url http://localhost:8700` (password or `--oauth`).
92
+
93
+ - **Worktree slots.** A slot's backend is on `http://localhost:87NN`. Start Claude Code for that slot with
94
+ `DEVORCH_API_BASE=http://localhost:87NN` so the bundled server targets it, or pass `baseUrl` on a single watch
95
+ (`/devorch-watch <runId> http://localhost:87NN`).
96
+ - **The workspace's own MCP servers** (`devorch-local`, `devorch-local-mcp` in `.mcp.json`) stay for ad-hoc and admin
97
+ use: `devorch-local` runs `mcp serve --allow-control` (the admin band the plugin's server never exposes). The
98
+ shipped skills use the plugin's server; the workspace's project copies of `devorch-step`, `sdlc-drive` and
99
+ `devorch-step-worker` can be deleted once this plugin version is installed (the wake already prefers the plugin's
100
+ skill).
101
+ - To run the plugin straight from source: `devorch companion install` from a build output
102
+ (`src/DevOrchestrator.Cli/bin/Debug/net10.0/`), then the two `claude plugin` commands against the printed path.
23
103
 
24
104
  ## Status
25
105
 
@@ -30,11 +110,12 @@ base URL) points it at a worktree slot.
30
110
  | CLI option contract (R12): `test/cli-options.json`, checked by the mod tests and by `CompanionArgvContractTests` (C#) | `test/` | built, tested |
31
111
  | `register.ts`: the adapter over `$` (process spawn, turn tracking, `$.command.run`, status line, `/devorch-watch`, `/devorch-unwatch`, `/devorch-answer`, tool `devorch_companion`, `$.devorch.on` for other plugins) | `hooks/register.ts` | built; **behaviour unverified until the Windows spike** (`sdlc/devorch-companion-mod-platform-events/implement/spike-tq27.md`) and QA |
32
112
  | `.claude-plugin/plugin.json`, `hooks/hooks.json`, marketplace manifest | `.claude-plugin/`, `../.claude-plugin/` | built |
33
- | Shipping in the npm and NuGet packages; `CLI_PATHS` and `on.push.paths`; `devorch companion install` | CLI | built |
113
+ | Shipping in the npm and NuGet packages; `CLI_PATHS` and `on.push.paths`; `devorch companion install` (records the exe in `cli.json` and `.mcp.json`); `devorch companion mcp` | CLI | built |
114
+ | Skills `sdlc-drive`, `devorch-step`, agent `devorch-step-worker`, MCP server `devorch` | `skills/`, `agents/`, `.mcp.json` | built; live OAuth against the hosted API unverified |
34
115
 
35
116
  The spike still decides three things the adapter assumes: that `$.process.spawn` of the native `devorch.exe` shows no
36
117
  console window on Windows, which event marks the end of a main-loop turn, and that
37
- `$.command.run({command: "devorch-step"})` queues until idle and rejects an unknown command. Every host failure
118
+ `$.command.run({command: "devorch-companion:devorch-step"})` queues until idle and rejects an unknown command. Every host failure
38
119
  reads as `healthy: false`, so the skills fall back to `ScheduleWakeup` rather than stalling.
39
120
 
40
121
  ## Tests
@@ -0,0 +1,135 @@
1
+ ---
2
+ name: devorch-step-worker
3
+ description: Performs the work of exactly one DevOrch run instruction in a fresh context, writing that step's stage documents and code changes to disk, and returns one result JSON object. Launched by the devorch-step skill with a runId, an instructionId and an optional worktree path. Use only for dispatching a DevOrch instruction.
4
+ ---
5
+
6
+ # DevOrch Step Worker
7
+
8
+ You do the work of **one** DevOrch instruction. The orchestrator that launched you only fetches instructions,
9
+ applies results and prints status, so everything else happens here: reading context, stage docs and source,
10
+ making edits, running tests.
11
+
12
+ **Tools.** The DevOrch verbs below (`get_instruction`, `get_context_for_instruction`, `get_step_prompt`,
13
+ `put_step_output`, `record_decision`, `raise_blocker`, `submit_verdict`) are tools of the DevOrch MCP server. The
14
+ companion plugin bundles one, so they read `mcp__plugin_devorch-companion_devorch__<verb>`; if that server is absent,
15
+ use the same verb from the DevOrch MCP server this session has (for example `mcp__devorch-local-mcp__<verb>`).
16
+
17
+ **Writing files is the work, not a report.** Each stage produces documents under `sdlc/{slug}/`, such as
18
+ `problem.md`, `synthesis.md` and the stage `INDEX.md`. Those are the step's deliverables, and later steps read them
19
+ from disk. Write them with the Write and Edit tools as the stage guidance directs. Never put a document's body into
20
+ the result JSON instead of the file: the result only references files through `artifacts[].ref`. Your findings for
21
+ the orchestrator are the result JSON's `outputs.summary`, not a separate file.
22
+
23
+ Your prompt gives you `runId`, `instructionId`, `worktree` (an absolute path, or `none`) and `driverId`.
24
+
25
+ ## Procedure
26
+
27
+ 1. **Read the envelope.** Call `get_instruction(runId)`. If its `instructionId` differs from the one you were
28
+ given, stop and return a `blocked` result with a blocker of type `error` that names both ids.
29
+ 2. **Gather.** Call `get_context_for_instruction(runId)`. Always do this, before any other work. It carries the work
30
+ intent, upstream outputs, prior decisions, open questions, blockers and open steering `directives[]` (honor any
31
+ that apply). Its `workItem` section lists every BQ/TQ, AC, G and TC key the work item already has: reuse a key
32
+ when you write about the same item, number a new one from `nextKeys`, and never renumber.
33
+ 3. **Dispatch on `kind`**, matching case and separators loosely:
34
+ - `execute_step`: if an `execute-instruction` skill is available in this session, follow it. Otherwise call
35
+ `get_step_prompt(runId, instructionId)`: the server assembles the full step prompt (stage and step guidance,
36
+ inputs, each output slot's contract, the postconditions it will check, and the result instructions). Do what it
37
+ says, using the stage skill named by `spec.skill` (`research-build`, `plan-build`, `implement-build`,
38
+ `review-build`, `qa-build`) when this session has it, and the prompt's own guidance when it doesn't.
39
+ - `evaluate`: if an `evaluate-gate` skill is available, follow it. Otherwise judge the gate `spec.check` against
40
+ the context bundle and the subjects `inputs` reference, and return one `evaluate.result.v1` with
41
+ `outputs.verdict` (`approved`, `rejected` or `approvedWithGaps`), `outputs.rationale` and
42
+ `outputs.confidence`. Don't echo or name the boundary: the server resolves it.
43
+ - `record_backedge`: do what `spec` asks and report it as a `record_backedge.result.v1`.
44
+ - anything else: return a `blocked` result naming the kind.
45
+ 4. **Signal as needed** while you work: `record_decision` for settled calls later steps should see, `raise_blocker`
46
+ for a hard stop.
47
+ 5. **Report.** Your final message is one result JSON object and nothing else: no prose, no code fences.
48
+
49
+ ## Where work happens
50
+
51
+ - Stage documents go under `sdlc/{slug}/` at the project root (the main checkout, not a worktree).
52
+ - Never name a `.md` file starting with `analysis`, `report`, `summary` or `findings`. Claude Code refuses
53
+ a subagent's Write of those ("Subagents should return findings as text, not write report files"). Use
54
+ names like `cross-cutting.md` or `verdict.md` instead.
55
+ - When `worktree` is a path, all code changes, builds, tests and running services happen inside it. In the DevOrch
56
+ workspace that means `<worktree>/app/backend` and `<worktree>/app/frontend` on that worktree's slot ports, never
57
+ slot 0 (`app/` at the workspace root, ports 8700 and 8800).
58
+ - When `worktree` is `none`, code changes happen in the current checkout. Never commit to, merge to or push the
59
+ default branch; leave changes for the person to review.
60
+ - Rendered and behavioural checks belong to QA. The implement step stops at build and lint.
61
+ - In the DevOrch workspace, for browser work run `uv run scripts/app_run.py e2e-token [email]` from the worktree root
62
+ immediately beforehand, because the token expires within minutes.
63
+ - Never read secret files (`.env*`, credential stores). Learn whether something is configured from how the app
64
+ behaves.
65
+
66
+ ## Result rules
67
+
68
+ - Report in the schema your envelope's `outputContract.schema` names (or another of its
69
+ `outputContract.acceptedSchemas`). The rule, rendered from the backend's published artifact:
70
+
71
+ <!-- result-schema-rule:begin (generated by scripts/result_schema_rule_check.py --write from app/backend/openapi/result-schema-rule.json; do not edit by hand) -->
72
+ **Accepted result schemas.** The server judges the body's `schema` against the instruction's kind. Omitting `schema` means the preferred one; any other schema is rejected with 422 `result_schema_mismatch` naming the expected schemas. The envelope's `outputContract.acceptedSchemas` carries the same list.
73
+
74
+ | Instruction kind | Preferred (`outputContract.schema`) | Also accepted |
75
+ |---|---|---|
76
+ | `execute_step` | `execute_step.result.v1` | `execute_step.result.v2` |
77
+ | `evaluate` | `evaluate.result.v1` | none |
78
+ | `record_backedge` | `record_backedge.result.v1` | none |
79
+
80
+ > In execute_step.result.v2, outputs holds only slot names (each a receipt or an inline value); summary is a top-level member, and v1 report members (passes, gaps) do not belong in it.
81
+
82
+ Example bodies (each is accepted for its kind; pinned by the backend's golden contract test):
83
+
84
+ - `execute_step` / `execute_step.result.v1`: `{"schema":"execute_step.result.v1","status":"succeeded","outputs":{"summary":"One paragraph of what the step did.","passes":1,"gaps":[]},"evidence":{"harness":"claude"}}`
85
+ - `execute_step` / `execute_step.result.v2`: `{"schema":"execute_step.result.v2","status":"succeeded","summary":"One paragraph of what the step did.","outputs":{"synthesis":{"receipt":{"kind":"artifact-revision","ref":"<receipt ref from put_step_output>","version":"1"}}},"evidence":{"harness":"claude"}}`
86
+ - `evaluate` / `evaluate.result.v1`: `{"schema":"evaluate.result.v1","status":"succeeded","outputs":{"verdict":"approved","rationale":"Why the gate passes or fails.","confidence":0.8},"evidence":{"harness":"claude"}}`
87
+ - `record_backedge` / `record_backedge.result.v1`: `{"schema":"record_backedge.result.v1","status":"succeeded","outputs":{"summary":"What was recorded."},"evidence":{"harness":"claude"}}`
88
+ <!-- result-schema-rule:end -->
89
+
90
+ - `status` is exactly one of `succeeded`, `failed`, `blocked` or `skipped`. Never `completed`, `done` or `ok`.
91
+ - Set `evidence.harness` to `"claude"`, and `evidence.sessionId` to the value of `$CLAUDE_CODE_SESSION_ID`.
92
+ - `deliverables` is a **top-level** field, next to `status` and `outputs`. Never put it under `outputs`.
93
+ - Never ask the user anything. If only a human can answer, return `status: "blocked"` with a `blocker`.
94
+ - To re-ask a question the work item already has (`workItem.questions` in the context), set the `BQ`/`TQ` blocker's
95
+ `ref` to its key (`"ref": "BQ-2"`, on the result blocker or `raise_blocker`) so the blocker links to it instead of
96
+ creating a duplicate. The prefix must match the type; a mismatch is rejected. Omit `ref` for a new question.
97
+ - If only a person can **do** something (a spike on real hardware, an interactive session, a third-party console),
98
+ return `blocked` with a `human_task` blocker and a `runbook`: `prerequisites`, ordered `steps` with exact
99
+ `command`s, `doneWhen` and `reportFormat` (what to paste back). Keep `question` to the one-sentence ask. A
100
+ `human_task` without steps is rejected. Commands never contain secret values; name the env var or file instead.
101
+
102
+ ## Storing slot outputs
103
+
104
+ - **Parse slot JSON locally before `put_step_output`** (or any tool that takes a JSON `body`). A stray brace is the
105
+ most common failure, and it is cheaper to catch before the call.
106
+ - **When a store call fails, report its exact text**, in `outputs.gaps` or the blocker. Don't paraphrase it.
107
+ - **An opaque failure is not a `driverId` problem.** Don't change or drop `driverId` to work around an error you
108
+ can't read; a lease problem comes back as a typed problem that says so.
109
+ - **Use the `driverId` your prompt gives you, as given (the bare session id).** Never copy the envelope's
110
+ `lease.holder` (`driver:<id>`): the server adds the `driver:` prefix itself, so the prefixed form is a lease
111
+ conflict (409 `instruction_lease_conflict`) on every store call.
112
+ - A `malformed_request` result names the parser `detail`, `line` and `byte_position`. **Positions are 0-based**
113
+ (`position_base: 0`), as in the detail text: line 0 is the first line. Fix the body and retry.
114
+ - An `internal_error` result is a server fault, not your mistake. Retry once; if it persists, put its `trace_id`
115
+ in the blocker.
116
+
117
+ ## When a tool call is refused
118
+
119
+ A refusal is something to understand, not to route around. Don't retry the same call, don't reach the same result
120
+ another way (a shell write instead of Write, a different path, a document's text pasted into the result), and don't
121
+ ask the orchestrator to do it for you. Instead:
122
+
123
+ 1. Copy the refusal text exactly, character for character, including any bracketed rule name and any mention of
124
+ auto mode, a hook, a permission rule or a classifier.
125
+ 2. Note what was refused: the tool, the path or command, and what you were trying to produce.
126
+ 3. Work out which mechanism refused it, with your evidence. An auto-mode classifier block names a rule in brackets,
127
+ such as `[Data Exfiltration]`; a permission rule names the rule; a hook says it is a hook. If you can't tell, say so.
128
+ 4. Return `status: "blocked"` with a `blocker` of type `env` whose `question` holds all of the above. Keep the
129
+ work you completed, and list in `outputs.gaps` what the refusal left undone.
130
+
131
+ ## Do not
132
+
133
+ - Call `get_next_instruction` or `apply_instruction_result`. Those belong to the orchestrator.
134
+ - Call `answer_blocker` (or `devorch blocker answer`). A blocker is answered by a human; raise it and return `blocked`.
135
+ - Merge to `main` or push to `main`.
@@ -297,8 +297,28 @@ export function parseAnswerArgs(args: string): { slug: string; blockerRef: strin
297
297
  return answer.length > 0 ? { slug, blockerRef, answer } : null
298
298
  }
299
299
 
300
- /** The only command the mod ever submits: `/devorch-step <runId>` with the id it holds (CC-4, AC-906). */
301
- export function wakeCommand(runId: string): { command: string; args: string } {
300
+ /** The step skill this plugin ships, as Claude Code names a plugin skill: `/<plugin>:<skill>`. */
301
+ export const PLUGIN_STEP_COMMAND = 'devorch-companion:devorch-step'
302
+ /** A project- or user-level `devorch-step` skill (this workspace's own copy, before it is deleted). */
303
+ export const BARE_STEP_COMMAND = 'devorch-step'
304
+
305
+ /**
306
+ * Which step command the wake submits, from the session's command names (`$.command.list()`). The plugin's own skill
307
+ * wins whenever it is listed, even beside a project-level `devorch-step`: it is the copy that ships with this mod and
308
+ * its CLI, so the two stay in step. The bare name is used only when the plugin's skill is not listed (a host that
309
+ * does not namespace plugin skills, or the mod loaded without its skills folder). With no list (the call failed),
310
+ * the plugin's name.
311
+ */
312
+ export function stepCommandName(available: readonly string[] | null): string {
313
+ if (!available || available.includes(PLUGIN_STEP_COMMAND)) return PLUGIN_STEP_COMMAND
314
+ return available.includes(BARE_STEP_COMMAND) ? BARE_STEP_COMMAND : PLUGIN_STEP_COMMAND
315
+ }
316
+
317
+ /**
318
+ * The only command the mod ever submits: the step skill (see `stepCommandName`) with the run id it holds and nothing
319
+ * else (CC-4, AC-906).
320
+ */
321
+ export function wakeCommand(runId: string, available: readonly string[] | null = null): { command: string; args: string } {
302
322
  if (!/^[0-9a-fA-F-]{36}$/.test(runId)) throw new Error('not a run id')
303
- return { command: 'devorch-step', args: runId }
323
+ return { command: stepCommandName(available), args: runId }
304
324
  }
@@ -23,7 +23,8 @@ import {
23
23
  * Long-lived loops (one per watched run) keep running after that hook returns, as the host's spawn example shows.
24
24
  *
25
25
  * Invariants (design-L0 Domain Integrity Constraints):
26
- * - only `wakeCommand(runId)` reaches `$.command.run`, with a run id the mod validated (CC-4);
26
+ * - only `wakeCommand(runId, names)` reaches `$.command.run`: the step skill (the plugin's own
27
+ * `devorch-companion:devorch-step`, else a listed bare `devorch-step`) with a run id the mod validated (CC-4);
27
28
  * - no blocker or question text in the status line, toasts, tool results, command replies or the log (CC-4, D19);
28
29
  * - no wake inside a main-loop turn or within SETTLE_MS of its end (CC-5), none while the Stop-hook host is armed (CC-6);
29
30
  * - one long-lived `devorch run watch` child per watched run on rungs 1-2, zero processes per event (AC-4);
@@ -31,7 +32,7 @@ import {
31
32
  *
32
33
  * Spike-conditional branches (design-L0): this file implements the DEFAULT branch of each row (no console flash on
33
34
  * spawn/run, main-loop `turn.complete` with `agentId` undefined, `$.command.run` queues until idle and accepts the
34
- * `devorch-step` skill, a `clock.after` scheduled in `turn.complete` runs outside the turn). The Windows spike
35
+ * step skill, a `clock.after` scheduled in `turn.complete` runs outside the turn). The Windows spike
35
36
  * (`spike-tq27.md`) confirms or changes them; a rejected wake already degrades to `healthy: false`.
36
37
  */
37
38
 
@@ -238,8 +239,10 @@ export const register: Register = (on, options) => {
238
239
  wakeInFlight = runId
239
240
  log(runId, why === 'wake' ? 'wake-submitted' : 'hand-back-submitted', { token: run.lastToken })
240
241
  try {
242
+ // The plugin's step skill (/devorch-companion:devorch-step) unless only a bare devorch-step is listed.
243
+ const names = await $.command.list().then((list) => list.map((c) => c.name)).catch(() => null)
241
244
  diag.submit = { at: now(), stage: 'command.run called' }
242
- await $.command.run(wakeCommand(runId))
245
+ await $.command.run(wakeCommand(runId, names))
243
246
  diag.submit = { at: now(), stage: 'command.run resolved' }
244
247
  } catch (err) {
245
248
  diag.submit = { at: now(), stage: `command.run rejected: ${String(err).slice(0, 200)}` }
@@ -248,7 +251,7 @@ export const register: Register = (on, options) => {
248
251
  run.pendingWake = false
249
252
  run.expiry?.cancel()
250
253
  wakeHealth = { ...wakeHealth, wakeBroken: true }
251
- $.ui.toast('DevOrch: could not wake the session; /devorch-step keeps its own wakeup')
254
+ $.ui.toast('DevOrch: could not wake the session; the step skill keeps its own wakeup')
252
255
  log(runId, 'wake-rejected')
253
256
  redraw()
254
257
  for (const r of runs.values()) checkHandBack(r)
@@ -26,6 +26,8 @@ export const CLI_OPTIONS = {
26
26
  'run wait': ['--since', '--seconds', '--base-url'],
27
27
  'blocker answer': ['--stdin', '--json', '--base-url'],
28
28
  version: ['--json'],
29
+ // Not built by the mod: the plugin's .mcp.json runs it (checked by a test against that file).
30
+ 'companion mcp': ['--api-base'],
29
31
  } as const satisfies Record<string, readonly string[]>
30
32
 
31
33
  export type CliCommand = keyof typeof CLI_OPTIONS
@@ -68,7 +70,7 @@ export function versionArgv(exe: string): string[] {
68
70
  /** The command (`run watch`, `version`, ...) and the options an argv uses, for the contract test. */
69
71
  export function optionsOf(argv: readonly string[]): { command: string; options: string[] } {
70
72
  const words = argv.slice(1)
71
- const command = words[0] === 'run' || words[0] === 'blocker' ? `${words[0]} ${words[1]}` : (words[0] ?? '')
73
+ const command = words[0] === 'run' || words[0] === 'blocker' || words[0] === 'companion' ? `${words[0]} ${words[1]}` : (words[0] ?? '')
72
74
  return { command, options: words.filter((w) => w.startsWith('--')) }
73
75
  }
74
76
 
@@ -258,10 +260,20 @@ export function resolveExe(s: ExeSources): { exe: string; source: 'env' | 'userC
258
260
 
259
261
  // ---- base URL (D14) -------------------------------------------------------------------------------------------
260
262
 
261
- /** Explicit argument -> `userConfig.apiBase` -> `DEVORCH_API_BASE` -> the CLI default. Trailing slashes trimmed. */
263
+ /**
264
+ * The hosted DevOrch API: the plugin's default when nothing names another server. Keep equal to
265
+ * `CompanionCli.ProdApiBase` (C#, used by `devorch companion mcp`) and the `apiBase` default in plugin.json.
266
+ */
267
+ export const PROD_API_BASE = 'https://api.devorchestrator.com'
268
+
269
+ /**
270
+ * Explicit argument (a watch's own base URL) -> `DEVORCH_API_BASE` -> `userConfig.apiBase` -> the hosted API, the same
271
+ * rule `devorch companion mcp` applies to the bundled MCP server, so the watches and the skills' tools hit one server.
272
+ * A value that is not an http(s) URL (empty included) is skipped. Trailing slashes trimmed.
273
+ */
262
274
  export function resolveBaseUrl(explicit: unknown, userConfig: unknown, env: string | undefined): string {
263
- const pick = [explicit, userConfig, env].find(nonEmpty)
264
- return (pick ?? 'http://localhost:8700').trim().replace(/\/+$/, '')
275
+ const pick = [explicit, env, userConfig].map((v) => (typeof v === 'string' ? v.trim() : v)).find(isBaseUrl)
276
+ return (pick ?? PROD_API_BASE).replace(/\/+$/, '')
265
277
  }
266
278
 
267
279
  /** Only an absolute http(s) URL may reach argv as `--base-url`. */
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: devorch-step
3
+ argument-hint: "<runId>"
4
+ description: Processes exactly one instruction of a DevOrch run by dispatching its work to a devorch-step-worker subagent, keeping the main thread as a thin orchestrator. TRIGGERS - devorch step, next devorch step, step this run, loop devorch run. USE WHEN - driving a DevOrch SDLC run one instruction at a time, by hand with /devorch-companion:devorch-step <runId> or repeatedly with /loop /devorch-companion:devorch-step <runId>.
5
+ allowed-tools: mcp__plugin_devorch-companion_devorch__get_next_instruction, mcp__plugin_devorch-companion_devorch__apply_instruction_result, mcp__plugin_devorch-companion_devorch__get_run_position, mcp__plugin_devorch-companion_devorch__raise_blocker, mcp__devorch-companion__devorch_companion, Bash(uv run scripts/worktree_manage.py *), Bash(uv run scripts/app_run.py *)
6
+ ---
7
+
8
+ # DevOrch Step
9
+
10
+ Process **one** instruction of a run, then stop. `/devorch-companion:devorch-step <runId>` is manual "next" mode.
11
+ `/loop /devorch-companion:devorch-step <runId>` repeats it until the run ends.
12
+
13
+ **The main thread only orchestrates.** Never read stage docs, source files or the context bundle here, and never
14
+ call `get_context_for_instruction`. The worker does all of that. The only output per instruction is one status line.
15
+
16
+ **Tools.** Every DevOrch verb below (`get_next_instruction`, `apply_instruction_result`, `get_run_position`,
17
+ `raise_blocker`) is a tool of the DevOrch MCP server. This plugin bundles one, so the tools read
18
+ `mcp__plugin_devorch-companion_devorch__<verb>`. If that server is absent, use the same verb from whichever DevOrch MCP
19
+ server this session has (for example `mcp__devorch-local-mcp__<verb>`); never mix two servers within one run, because
20
+ they may point at different backends.
21
+
22
+ ## A firing has two halves
23
+
24
+ Subagents run asynchronously, so one instruction spans two turns: **launch** ends the turn, and the worker's
25
+ hand-back starts **finish**.
26
+
27
+ ### Launch
28
+
29
+ 1. **Don't double-dispatch.** If a worker launched in this session for this run hasn't handed back, launch nothing.
30
+ Under `/loop`, schedule another fallback wakeup and end the turn.
31
+ 2. Call `get_next_instruction(runId, driverId)` and branch on `control`. `driverId` is this session's id
32
+ (`$CLAUDE_CODE_SESSION_ID`); use the same value on `apply_instruction_result`, because the instruction is leased
33
+ to it. Pass the **bare** id: the envelope's `lease.holder` reads `driver:<id>` because the server adds that prefix
34
+ itself, so sending the prefixed form back becomes `driver:driver:<id>` and every lease-checked call is a 409. If
35
+ the tool doesn't offer `driverId`, omit it on both calls:
36
+
37
+ | `control` | Action |
38
+ |---|---|
39
+ | `DONE` / `ESCALATE` / `ABORT` | PushNotification with the outcome and `reason`. Under `/loop`, `ScheduleWakeup(stop: true)`. Never self-heal. |
40
+ | `WAIT` | Print the `reason` and open blockers from `get_run_position`. Under `/loop`, follow **Wake owner** below (the companion mod if healthy, else wake after `retryAfterSeconds`). |
41
+ | `CONTINUE` | Go to 3. |
42
+
43
+ **Wake owner (DEV-47, DEV-56).** Exactly one thing wakes this session for a run. If the companion mod's tool
44
+ `mcp__devorch-companion__devorch_companion` exists, then **only under `/loop`** (a one-off step arms nothing) call
45
+ it with `{action: "watch", runId}` once before the first wait, and then `{action: "status", runId}`. The mod
46
+ watches the server set by the plugin's `apiBase` setting (or `DEVORCH_API_BASE`), the same one the bundled MCP
47
+ server uses; add `baseUrl` only when this run lives somewhere else (a worktree slot such as
48
+ `http://localhost:8704` while the plugin points at another server). When the status reports the run
49
+ `healthy: true`, the companion mod owns the wake: schedule **no** wakeup and end the turn; the mod submits
50
+ `/devorch-companion:devorch-step <runId>` within seconds of the run becoming actionable (a blocker answered, a lease
51
+ freed). When the tool is absent or reports `healthy: false` (watch child down, CLI too old), schedule the wakeup
52
+ yourself. The answer to a blocker can be given from here with `/devorch-answer <slug> <ref> <answer>` (mod) or
53
+ `devorch blocker answer <slug> <ref> --text ...` (CLI); never answer it yourself.
54
+
55
+ Re-fetching an instruction that was dispatched but never applied returns the same `instructionId`, so resuming
56
+ after a crash is safe.
57
+ 3. **Worktree, when `node.stage` is `implement`, `review` or `qa`.**
58
+ - **In the DevOrch workspace** (the project root has `scripts/worktree_manage.py` and `scripts/app_run.py`): the
59
+ worktree is named after `inputs.workItemSlug`. Check `uv run scripts/worktree_manage.py list`; if it's absent,
60
+ run `uv run scripts/worktree_manage.py create <slug>` (or `create <slug> --start` to create and start it in one
61
+ command). Then run `uv run scripts/app_run.py up --wait` from the worktree root (exit 4 = started but not healthy
62
+ in time; 5 = its port is held by another checkout's process). Pass its absolute path to the worker.
63
+ - **Anywhere else**, pass `none`: the worker works in the current checkout.
64
+
65
+ For earlier stages, pass `none`.
66
+ 4. Launch one `devorch-step-worker` subagent (this plugin's is `devorch-companion:devorch-step-worker`; a project-level
67
+ `devorch-step-worker` does the same job) with this prompt, then end the turn:
68
+
69
+ ```
70
+ runId: <runId>
71
+ instructionId: <instructionId>
72
+ worktree: <absolute path | none>
73
+ driverId: <this session's bare id, never the "driver:"-prefixed lease holder>
74
+ Do this step's work, including writing its stage documents under sdlc/<slug>/ and any code changes, then
75
+ return the result JSON. Parse slot JSON locally before put_step_output; if a store call fails, report its
76
+ exact text, and don't blame driverId for an opaque failure.
77
+ ```
78
+
79
+ Under `/loop`, first schedule a 1800-second fallback wakeup in case the worker never hands back, unless the
80
+ **Wake owner** check above says the companion mod is healthy for this run (it wakes the session if the worker's
81
+ instruction lease lapses without a result).
82
+
83
+ ### Finish (on the worker's hand-back)
84
+
85
+ 5. Parse the hand-back as one JSON object. If it doesn't parse, or step 6 rejects it, relaunch the worker once with
86
+ the error appended. On a second failure, call `raise_blocker` with type `error` and treat the run as `WAIT`.
87
+ 6. Call `apply_instruction_result(runId, instructionId, <result JSON>, driverId)`.
88
+ 7. Print one line and nothing else about the work, such as `qa/execute DONE (pass 1) - 12/12 passed`.
89
+ 8. Under `/loop`, **don't wait for a wakeup: go straight back to Launch step 2 in this same turn** and fetch the
90
+ next instruction. A `CONTINUE` launches the next worker now (with its 1800-second fallback wakeup); a `WAIT` or
91
+ terminal `control` is handled by the step 2 table as usual. Only the fallback and `WAIT` paths schedule a wakeup.
92
+
93
+ ## Anti-patterns
94
+
95
+ - Doing a step's work in the main thread.
96
+ - Echoing the worker's result, or a summary longer than the status line.
97
+ - Merging to `main` during a run. That's a human confirmation after `DONE`.
@@ -0,0 +1,173 @@
1
+ ---
2
+ name: sdlc-drive
3
+ argument-hint: "<integrationExternalId | issueKey | --run <runId>> [--headless | --interactive] [--integration <id>]"
4
+ description: The Claude-side in-session entry + demo wedge for the Sequential Autopilot - discover an assigned issue, claim it, verify the subscription, start an SDLC run, then drive it to DONE either Interactive (default, live in-session turns) or Headless (--headless, devorch run supervise, backgrounded). TRIGGERS - sdlc drive, claim and run my issue, claim my assigned issue, drive my ticket, autopilot my issue, run my assigned issue. USE WHEN - the user wants to claim an assigned tracker issue from Claude Code and have the autopilot take it research->qa to DONE, watched live; or to launch/host a Sequential Autopilot run.
5
+ allowed-tools: mcp__plugin_devorch-companion_devorch__list_assigned_issues, mcp__plugin_devorch-companion_devorch__next_assigned_issue, mcp__plugin_devorch-companion_devorch__claim_issue, mcp__plugin_devorch-companion_devorch__start_sdlc_for_issue, mcp__plugin_devorch-companion_devorch__whoami, mcp__plugin_devorch-companion_devorch__get_next_instruction, mcp__plugin_devorch-companion_devorch__apply_instruction_result, mcp__plugin_devorch-companion_devorch__get_run_position, mcp__devorch-companion__devorch_companion, Bash(devorch run *), Bash(*devorch.exe run *), Bash(*/devorch run *)
6
+ ---
7
+
8
+ # SDLC Drive
9
+
10
+ The **in-session entry point + demo wedge** for the Sequential Autopilot: from inside Claude Code the
11
+ user says *"claim and run my assigned issue"* and this skill discovers an assigned tracker issue,
12
+ claims it race-safely, verifies the subscription, opens an SDLC run, and then **drives that run to a
13
+ terminal state** in one of two run modes.
14
+
15
+ This skill **does NOT implement the loop.** Both run modes wrap the **same `step_once` primitive**:
16
+
17
+ - **Interactive** (default, the headline demo) — `/loop /devorch-companion:devorch-step` runs **inside this
18
+ session**; each step's work happens in a subagent, and you steer between steps.
19
+ - **Headless** (opt-in with `--headless`, the proven spine) — the loop runs **detached** in
20
+ `devorch run supervise` (fresh `claude -p` per step, `ANTHROPIC_API_KEY`-strip → guaranteed
21
+ subscription billing); you watch via the **portal**.
22
+
23
+ On a terminal `control` the skill **NOTIFIES** (PushNotification) — it does **not** self-heal. That is
24
+ the explicit design boundary: the backend program counter owns advancement; this skill claims, starts,
25
+ launches/hosts, and reports.
26
+
27
+ ## Tools and server
28
+
29
+ Every verb below (`list_assigned_issues`, `next_assigned_issue`, `claim_issue`, `whoami`, `start_sdlc_for_issue`,
30
+ `get_next_instruction`, `apply_instruction_result`, `get_run_position`) is a tool of the **DevOrch MCP server**. This
31
+ plugin bundles one (`devorch companion mcp`), so the tools read `mcp__plugin_devorch-companion_devorch__<verb>`. If that
32
+ server is missing, use the same verb from whichever DevOrch MCP server this session has, and keep to one server for
33
+ the whole run.
34
+
35
+ The bundled server, the companion mod's watches and the commands below all target one backend: the plugin's
36
+ `apiBase` setting (default `https://api.devorchestrator.com`), overridden by `DEVORCH_API_BASE`. Call that URL
37
+ `<apiBase>` below.
38
+
39
+ **If a tool call fails with 401 / "Run `devorch login` first"**, the CLI has no session for `<apiBase>`. Tell the user
40
+ to run `devorch login --oauth --base-url <apiBase>` in a terminal (it opens a browser) and then reconnect the server
41
+ with `/mcp`; don't try to log in for them.
42
+
43
+ ## Protocol
44
+
45
+ **Resuming an existing run:** if the argument is a run id (a GUID passed as `--run <runId>`), skip steps 1-4 and
46
+ go straight to RUN with it.
47
+
48
+ ### 1. DISCOVER — find an assigned issue (Read band, always available)
49
+
50
+ You need the **integration's externalId** (`{id}` below) — the issue-tracking integration whose agent
51
+ account holds the assigned issues. Take it from the user/args, or list the user's integrations first.
52
+
53
+ - **`list_assigned_issues(id)`** → `[{issue_key, title, status, claim_state, dispatch_external_id?}]`
54
+ (`claim_state` ∈ `unclaimed | queued | leased | running | completed | failed | cancelled`).
55
+ - **`next_assigned_issue(id)`** → the first still-`unclaimed` issue, or `null` when nothing is claimable.
56
+
57
+ Pick the target issue (prefer `next_assigned_issue` for the simple "do my next ticket" flow).
58
+
59
+ ### 2. CLAIM — atomically claim it (`pipeline.control`)
60
+
61
+ **`claim_issue`** with body `{"integration_id": "<integration externalId>", "issue_key": "DEV-103"}` →
62
+ `{dispatch_external_id, leased, issue_key}`. The wire is **snake_case**: a camelCase body
63
+ (`integrationId`/`issueKey`) is rejected with 400 `issue_key is required`. An issue key does not have to appear in
64
+ `list_assigned_issues` to be claimed.
65
+
66
+ - `leased: true` → **you won the claim**; carry `dispatch_external_id` to START.
67
+ - `leased: false` → **someone already claimed it** (race lost — a 200 VALUE, never an error). **Move to
68
+ the next issue** (`next_assigned_issue` again, or the next `unclaimed` row) and re-claim. This is a
69
+ clean loop, not a failure.
70
+
71
+ ### 3. VERIFY SUBSCRIPTION — check the gate, warn (don't block) in v1
72
+
73
+ Call **`whoami`** and inspect the active org + plan/entitlement. The hard binary **402
74
+ `upgrade_required`** gate ships later on the claim/start verbs; **in v1 this skill only
75
+ checks and WARNS** — if there is no active subscription/plan, surface a clear warning that the run may
76
+ be blocked once that gate lands, then proceed. (SuperAdmin/system bypass; don't hard-stop here.)
77
+
78
+ ### 4. START — open the run (`pipeline.control`)
79
+
80
+ **`start_sdlc_for_issue({id: dispatch_external_id})`** →
81
+ `{workItemSlug, runNumber, runExternalId, issueLink, instruction}`.
82
+
83
+ - `instruction` is the **inline informational envelope**: prompt-shaped first task with
84
+ **`instructionId: null`** — **informational only**, it does NOT advance the program counter. Use it to
85
+ preview the first step; the driver/host fetches the real instruction via `get_next_instruction`.
86
+ - Keep `runExternalId` (the run id every `devorch run` / `get_next_instruction` call needs) and
87
+ `workItemSlug`.
88
+
89
+ ### 5. RUN — branch on mode
90
+
91
+ **Default = Interactive** unless the user asked for `--headless`.
92
+
93
+ #### Interactive (default — the headline demo)
94
+
95
+ Run **`/loop /devorch-companion:devorch-step <runExternalId>`** (a project-level `/devorch-step` is the same skill
96
+ where one exists). The main thread only orchestrates: each instruction's work runs in a `devorch-step-worker`
97
+ subagent, and the session is idle between firings so the user can steer. `devorch-step` handles the terminal
98
+ `control` notifications (step 6).
99
+
100
+ **Wake without polling (DEV-47, DEV-56).** If the companion mod is running (the `mcp__devorch-companion__devorch_companion`
101
+ tool exists), call it with `{action: "watch", runId: <runExternalId>}` right after starting the run; add `baseUrl` only
102
+ when the run lives on a different server from `<apiBase>` (for example a worktree slot). The mod then wakes the idle
103
+ session with `/devorch-companion:devorch-step <runId>` within seconds of the run becoming actionable, and `devorch-step`
104
+ schedules no wakeup of its own while the mod reports the run healthy (its "Wake owner" rule). Without the mod, or when
105
+ it reports unhealthy, `devorch-step` keeps its timed wakeups. Blockers can be answered from the session with
106
+ `/devorch-answer <slug> <ref> <answer>` (mod) or `devorch blocker answer <slug> <ref> --text ...`; headless
107
+ `devorch run supervise` parks a WAIT on the server and resumes on its own.
108
+
109
+ > **Billing:** Interactive runs on your already-logged-in subscription — **no key-strip** (you launched
110
+ > Claude logged in). **Claude-only** for now.
111
+
112
+ #### Headless (`--headless` — the proven spine)
113
+
114
+ Launch the restart-safe supervisor **backgrounded** so this session stays responsive:
115
+
116
+ ```
117
+ <devorch> run supervise <runExternalId> --base-url <apiBase>
118
+ ```
119
+
120
+ `<devorch>` is the CLI the companion recorded, in this order:
121
+
122
+ 1. the `cli.path` the companion tool reports (`{action: "status"}`), which `devorch companion install` recorded;
123
+ 2. in the DevOrch workspace, `${CLAUDE_PROJECT_DIR}/tools/devorch/devorch.exe` when it exists (a local build of
124
+ `main`; rebuild it from `app/backend/src/DevOrchestrator.Cli` if it is stale);
125
+ 3. `devorch` on PATH.
126
+
127
+ If the chosen binary answers `Error: 'run' is not a command.`, it predates the `run` commands: say so and ask the user
128
+ to update the CLI (`npm i -g dev-orchestrator-cli@latest` or `dotnet tool update -g dev-orchestrator-cli`), then
129
+ `devorch companion install` again. Don't fall back to another binary silently.
130
+
131
+ Run it with the **Bash tool's `run_in_background: true`**. Then surface the **portal URL** so the user can watch the
132
+ run live (stages / gates / linked sessions): `/app/work-items/{workItemSlug}` on the web app that pairs with
133
+ `<apiBase>` (hosted: `https://app.devorchestrator.com/app/work-items/{workItemSlug}`; a local backend on port 87NN
134
+ pairs with `http://localhost:88NN`). A specific run is `/app/work-items/{workItemSlug}/runs/{runNumber}`. Poll status
135
+ with `get_run_position` or the portal; do not block this session on it.
136
+
137
+ > **Permission gate:** the Headless child spawns `claude -p`, so the actual launch is gated on the
138
+ > `Bash(claude *)` permission (and the `devorch run *` permission). If those aren't granted,
139
+ > report the exact command for the user to run and stop — do not attempt to bypass the gate.
140
+
141
+ ### 6. NOTIFY on terminal `control` (NOT self-heal)
142
+
143
+ When the run reaches a terminal `control`, branch and **notify** with a PushNotification — never
144
+ auto-fix:
145
+
146
+ | Terminal `control` | Action |
147
+ |---|---|
148
+ | `DONE` | PushNotification: run complete; link the card/portal. |
149
+ | `ESCALATE` | PushNotification: surfaced blockers/defects + the run digest; a human takes it. |
150
+ | `ABORT` | PushNotification: the run was aborted (operator/quota/guard). |
151
+
152
+ ## Operator stop / abort (stop a runaway run)
153
+
154
+ A back-edge loop or quota-burning run must be stoppable from the operator side:
155
+
156
+ - **Headless:** `<devorch> run abort <runExternalId>` (the same binary as the supervisor, chosen as above) — reaps
157
+ the tracked headless `claude -p` children for the driver process (best-effort operator stop). Also stop the
158
+ backgrounded `supervise` task.
159
+ - **Interactive (in-session control):** tell the session to stop the loop; it calls
160
+ `ScheduleWakeup(stop: true)` and no further firing happens. Unwatch the run with `/devorch-unwatch <runId>`.
161
+
162
+ ## Anti-patterns
163
+
164
+ - **Self-healing on a terminal control** — DONE/ESCALATE/ABORT → **notify**, never auto-retry/auto-fix.
165
+ The backend PC owns advancement and back-edges.
166
+ - **Advancing the PC by hand in Headless** — the `devorch run` driver owns `get_next_instruction` /
167
+ `apply_instruction_result` there; don't call them yourself for a Headless run.
168
+ - **Treating `leased:false` as an error** — it's the race-lost VALUE; move to the next issue.
169
+ - **Trusting the START `instruction` as binding** — its `instructionId` is null (informational only);
170
+ the real first instruction comes from `get_next_instruction`.
171
+ - **Hard-blocking on the subscription in v1** — check + warn; the binary 402 gate comes later.
172
+ - **Doing a step's work in this session** — Interactive routes every step through `devorch-step`'s worker.
173
+ - **Mixing backends** — the MCP server, the watch and `devorch run` must all point at `<apiBase>`.
package/bin/devorch CHANGED
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/bin/devorch
3
- size: 107100913 bytes
4
- sha256: 597a5255e8e6b1cdad08e0d9ba439766d9c08c0e604761debe40af0df259f5c6
3
+ size: 107103985 bytes
4
+ sha256: da445319a1fda8bade4b0031a7e5398f446c247d80b5ca9ee39c86bad889479c
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devorch/cli-linux-x64",
3
- "version": "0.19.0",
3
+ "version": "0.20.0",
4
4
  "description": "Dev Orchestrator CLI (devorch) prebuilt binary for linux-x64 (.NET RID linux-x64). Installed automatically by dev-orchestrator-cli; not meant to be installed directly.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {