@devorch/cli-linux-x64 0.20.0 → 0.21.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.
@@ -1,8 +1,10 @@
1
1
  {
2
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" },
3
+ "version": "0.21.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 (wakeMode: auto, push or poll). Status line, /devorch-watch, /devorch-unwatch, /devorch-answer, the devorch_companion tool and a $.devorch event hook for other plugins.",
5
+ "author": {
6
+ "name": "Dev Orchestrator"
7
+ },
6
8
  "license": "UNLICENSED",
7
9
  "types": "./types/index.d.ts",
8
10
  "userConfig": {
@@ -19,6 +21,32 @@
19
21
  "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
22
  "required": false,
21
23
  "default": "https://api.devorchestrator.com"
24
+ },
25
+ "wakeMode": {
26
+ "type": "string",
27
+ "title": "Wake mode",
28
+ "description": "Who wakes an interactive run between steps. auto (default): the companion mod wakes the session the moment the run can move while it is healthy, else the step skill polls with /loop + ScheduleWakeup. push: the companion only; if it is unhealthy the skill reports that and stops instead of polling. poll: always /loop + ScheduleWakeup (the mod still shows the status line but never wakes). DEVORCH_WAKE_MODE in the environment wins over this.",
29
+ "required": false,
30
+ "default": "auto",
31
+ "options": [
32
+ "auto",
33
+ "push",
34
+ "poll"
35
+ ]
36
+ },
37
+ "fallbackWakeupSeconds": {
38
+ "type": "number",
39
+ "title": "Fallback wakeup (seconds)",
40
+ "description": "Under poll, the safety-net ScheduleWakeup the step skill sets while a worker runs, in case it never hands back. 60 to 3600, default 1800. DEVORCH_FALLBACK_WAKEUP_SECONDS in the environment wins over this.",
41
+ "required": false,
42
+ "default": 1800
43
+ },
44
+ "longPollSeconds": {
45
+ "type": "number",
46
+ "title": "Long-poll seconds",
47
+ "description": "When the mod's live watch keeps failing it falls back to one-shot long-polls (devorch run wait --seconds N). 5 to 25 (the server's limit), default 25. DEVORCH_LONG_POLL_SECONDS in the environment wins over this.",
48
+ "required": false,
49
+ "default": 25
22
50
  }
23
51
  }
24
52
  }
@@ -5,7 +5,7 @@ A self-contained Claude Code plugin for driving DevOrch runs from any repository
5
5
  | Piece | Path | What it is |
6
6
  |---|---|---|
7
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. |
8
+ | `/devorch-companion:devorch-step` | `skills/devorch-step/` | Process a run's next instruction and keep going; the mod wakes it between instructions (push), or `/loop` does (poll). |
9
9
  | `devorch-companion:devorch-step-worker` | `agents/` | The subagent that does one instruction's work in a fresh context. |
10
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
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. |
@@ -48,6 +48,47 @@ After upgrading the CLI, run `devorch companion install` again, then
48
48
  `DEVORCH_EXE` (or the plugin's `devorchExe` setting) overrides the executable the mod runs; the MCP server always runs
49
49
  the one `companion install` recorded.
50
50
 
51
+ ## Wake modes
52
+
53
+ Between instructions an interactive run needs something to wake the session: a worker is running, or the run is
54
+ waiting on a human. Two mechanisms, and exactly one owns the wake at a time:
55
+
56
+ - **push** (realtime): the mod watches the run and submits `/devorch-companion:devorch-step <runId>` within seconds of
57
+ it becoming actionable. `sdlc-drive` runs the step skill **once, with no `/loop`**, and the step skill schedules no
58
+ wakeups. After a worker hands back, the step skill goes straight on to the next instruction in the same turn.
59
+ - **poll** (timed): `sdlc-drive` runs `/loop /devorch-companion:devorch-step <runId>` and the step skill keeps its own
60
+ `ScheduleWakeup`s: `retryAfterSeconds` on a `WAIT`, and a safety-net wakeup while a worker runs.
61
+
62
+ The `devorch_companion` tool's `status` and `watch` answers carry the resolved policy, which is the one field the skills
63
+ branch on:
64
+
65
+ ```json
66
+ "wake": { "mode": "auto", "effective": "push", "owner": "companion", "fallbackWakeupSeconds": 1800, "reason": "..." }
67
+ ```
68
+
69
+ `effective` is `push`, `poll`, or `unavailable` (`wakeMode` is `push` but the companion is unhealthy: the skill reports
70
+ `reason` and stops). `status` also returns `config`: each setting's value, its source (`env`, `option` or `default`)
71
+ and any warnings.
72
+
73
+ | Setting (plugin option) | Environment override | Default | Values |
74
+ |---|---|---|---|
75
+ | `wakeMode` | `DEVORCH_WAKE_MODE` | `auto` | `auto`: push while the companion is healthy, else poll. `push`: the companion only; unhealthy means report and stop, never poll. `poll`: always `/loop` + `ScheduleWakeup`; the mod still shows the status line (with `wake: poll`) but submits no wakes and reports `healthy: false`. An unknown value is `auto`, with a warning in `status`. |
76
+ | `fallbackWakeupSeconds` | `DEVORCH_FALLBACK_WAKEUP_SECONDS` | `1800` | The safety-net `ScheduleWakeup` under poll while a worker runs, and after a `WAIT` with no `retryAfterSeconds`. Clamped to 60..3600. |
77
+ | `longPollSeconds` | `DEVORCH_LONG_POLL_SECONDS` | `25` | The mod's rung-3 fallback (`devorch run wait --seconds N`, used only when the live watch keeps failing). Clamped to 5..25, the server's limit. |
78
+
79
+ Each setting resolves **environment variable, then plugin option, then default**; the first one that is set (not
80
+ empty) decides. Set the options with `/plugin configure devorch-companion@devorch-cli` (or the `/config` menu), or with
81
+ `claude plugin configure devorch-companion@devorch-cli --values-stdin`. The environment variables win because a
82
+ project-scope plugin option may not apply while a project's `env` does, so to pin a mode for one repository put it in
83
+ that project's `.claude/settings.json`:
84
+
85
+ ```json
86
+ { "env": { "DEVORCH_WAKE_MODE": "poll" } }
87
+ ```
88
+
89
+ A new setting takes effect when the mod reloads (a changed option reloads it; an environment change needs a new
90
+ session).
91
+
51
92
  ## Design notes
52
93
 
53
94
  - **Which `devorch` runs.** `devorch companion install` writes the executable it is running as into the plugin folder
@@ -65,8 +106,9 @@ the one `companion install` recorded.
65
106
  - **Wake command.** Claude Code names plugin skills `/<plugin>:<skill>`. Before each wake the mod lists the session's
66
107
  commands and submits `devorch-companion:devorch-step` whenever it is listed, even beside a project-level
67
108
  `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`.
109
+ bare `devorch-step` only when the plugin's skill is missing. A rejected wake reads as `healthy: false`, so under
110
+ `auto` the next firing sees `wake.effective: poll` and the skill keeps its own `ScheduleWakeup` (it starts `/loop`
111
+ when it wasn't under one).
70
112
  - **Tool names.** The skills name `mcp__plugin_devorch-companion_devorch__*` in `allowed-tools` and refer to verbs by
71
113
  their bare name in the body ("the DevOrch MCP server's `get_next_instruction`"), so any DevOrch MCP server with the
72
114
  same tools also works. Keep the server key `devorch`: renaming it renames every tool.
@@ -106,7 +148,7 @@ Sign in once for that URL: `devorch login --base-url http://localhost:8700` (pas
106
148
  | Piece | File | Status |
107
149
  |---|---|---|
108
150
  | Envelope parsing, NDJSON framing, generic event hook, wake decision, source ladder, CLI handshake, band text | `hooks/core.ts` | built, tested |
109
- | Supervision decisions: exit-code mapping (unknown -> rung 4), rung-3 backoff, heal/retry timers, pending-wake expiry, position dedupe, hand-back wake, terminal rule, watch cap, exe and base-URL resolution, multi-run status, `healthy` | `hooks/supervision.ts` | built, tested |
151
+ | Supervision decisions: exit-code mapping (unknown -> rung 4), rung-3 backoff, heal/retry timers, pending-wake expiry, position dedupe, hand-back wake, terminal rule, watch cap, exe and base-URL resolution, multi-run status, `healthy`, wake settings (env > option > default) and the wake policy | `hooks/supervision.ts` | built, tested |
110
152
  | CLI option contract (R12): `test/cli-options.json`, checked by the mod tests and by `CompanionArgvContractTests` (C#) | `test/` | built, tested |
111
153
  | `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 |
112
154
  | `.claude-plugin/plugin.json`, `hooks/hooks.json`, marketplace manifest | `.claude-plugin/`, `../.claude-plugin/` | built |
@@ -116,7 +158,7 @@ Sign in once for that URL: `devorch login --base-url http://localhost:8700` (pas
116
158
  The spike still decides three things the adapter assumes: that `$.process.spawn` of the native `devorch.exe` shows no
117
159
  console window on Windows, which event marks the end of a main-loop turn, and that
118
160
  `$.command.run({command: "devorch-companion:devorch-step"})` queues until idle and rejects an unknown command. Every host failure
119
- reads as `healthy: false`, so the skills fall back to `ScheduleWakeup` rather than stalling.
161
+ reads as `healthy: false`, so under `wakeMode: auto` the skills fall back to `ScheduleWakeup` rather than stalling.
120
162
 
121
163
  ## Tests
122
164
 
@@ -215,6 +215,8 @@ export interface WakeInputs {
215
215
  wakePending: boolean
216
216
  /** The latest run.position envelope for the watched run. */
217
217
  latest: PlatformEventEnvelope | null
218
+ /** False under `wakeMode: poll`: the skill owns the wake, so the mod submits none (default true). */
219
+ modWakes?: boolean
218
220
  }
219
221
 
220
222
  export type WakeDecision =
@@ -246,6 +248,7 @@ export function decideWake(i: WakeInputs): WakeDecision {
246
248
  * or null when the session may be woken and `watchedRunId` and `latest` are set. */
247
249
  function sessionHold(i: WakeInputs): WakeDecision | null {
248
250
  if (!i.watchedRunId) return { wake: false, reason: 'no run watched' }
251
+ if (i.modWakes === false) return { wake: false, reason: 'wakeMode poll: the skill owns the wake' }
249
252
  if (i.stopHookArmed) return { wake: false, reason: 'Stop-hook host armed' }
250
253
  if (i.turnRunning) return { wake: false, reason: 'turn running; re-evaluate when idle' }
251
254
  if (i.idleForMs !== null && i.idleForMs < SETTLE_MS)
@@ -6,9 +6,10 @@ import {
6
6
  } from './core.ts'
7
7
  import {
8
8
  HEAL_MS, LOG_MAX_BYTES, WAKE_EXPIRY_MS, afterPoll, afterWakeClaimed, afterWakeExpired, afterWatchExit,
9
- answerStdinArgv, canWatch, dedupe, handBackWake, health, isBaseUrl, logLine, parseUnwatchArgs, parseWatchArgs,
10
- resolveBaseUrl, resolveExe, respawnDelayMs, restoreWatched, runStatus, statusLine, terminalAction, tokenOf,
11
- updateHint, versionArgv, waitArgv, watchArgv, type WakeHealth, type WatchEntry,
9
+ answerStdinArgv, canWatch, dedupe, handBackWake, health, isBaseUrl, logLine, modWakes, parseUnwatchArgs,
10
+ parseWatchArgs, pollTimeoutMs, resolveBaseUrl, resolveExe, resolveSettings, respawnDelayMs, restoreWatched, runStatus,
11
+ statusLine, terminalAction, tokenOf, updateHint, versionArgv, waitArgv, wakePolicy, watchArgv, type Settings,
12
+ type WakeHealth, type WatchEntry,
12
13
  } from './supervision.ts'
13
14
 
14
15
  /**
@@ -40,8 +41,6 @@ const TOOL = 'mcp__devorch-companion__devorch_companion'
40
41
  const STOP_HOOK_MARKER = '.claude/hooks/interactive-loop/state/armed.json'
41
42
  /** How long tool `watch` waits for the first envelope or child exit before it answers (D16). */
42
43
  const FIRST_SIGNAL_MS = 5_000
43
- /** A rung-3 `run wait` parks 25 s on the server; the process gets 10 s more. */
44
- const POLL_TIMEOUT_MS = 35_000
45
44
 
46
45
  type Run = {
47
46
  entry: WatchEntry
@@ -82,6 +81,8 @@ export const register: Register = (on, options) => {
82
81
  let wakeHealth: WakeHealth = { misses: 0, wakeBroken: false }
83
82
  let turnRunning = false
84
83
  let lastTurnEnd: number | null = null
84
+ /** Wake mode and timing knobs: the plugin options now, refined with the DEVORCH_* environment at session start. */
85
+ let settings: Settings = resolveSettings({}, options)
85
86
  /** Diagnostics for the status action: the last wake decision and how far the last submit got. */
86
87
  const diag: { decision?: { at: number; wake: boolean; reason?: string }; submit?: { at: number; stage: string } } = {}
87
88
 
@@ -91,13 +92,29 @@ export const register: Register = (on, options) => {
91
92
  // ---- pure views over the state (no host calls) ----------------------------------------------------------------
92
93
 
93
94
  function healthOf(run: Run | null): { healthy: boolean; reason?: string } {
94
- return health({ cliOk: cli.ok, cliReason: cli.reason, stopHookArmed, wakeBroken: wakeHealth.wakeBroken, rung: run ? run.ladder.rung : null })
95
+ return health({
96
+ pollMode: settings.wakeMode === 'poll', cliOk: cli.ok, cliReason: cli.reason, stopHookArmed,
97
+ wakeBroken: wakeHealth.wakeBroken, rung: run ? run.ladder.rung : null,
98
+ })
99
+ }
100
+
101
+ /** The effective wake policy the skills branch on (`wake.effective`). */
102
+ function wakeOf(run: Run | null): ReturnType<typeof wakePolicy> {
103
+ return wakePolicy(settings.wakeMode, healthOf(run), settings.fallbackWakeupSeconds)
95
104
  }
96
105
 
97
106
  function statusObject(runId?: string): Record<string, unknown> {
98
107
  const asked = runId ? runs.get(runId) ?? null : null
99
108
  return {
100
109
  ...healthOf(asked),
110
+ wake: wakeOf(asked),
111
+ config: {
112
+ wakeMode: settings.wakeMode,
113
+ fallbackWakeupSeconds: settings.fallbackWakeupSeconds,
114
+ longPollSeconds: settings.longPollSeconds,
115
+ sources: settings.sources,
116
+ warnings: settings.warnings,
117
+ },
101
118
  cli: { ok: cli.ok, version: cli.version, path: cli.exe },
102
119
  stopHookArmed,
103
120
  wakeBroken: wakeHealth.wakeBroken,
@@ -161,7 +178,8 @@ export const register: Register = (on, options) => {
161
178
 
162
179
  function redraw(): void {
163
180
  const views = [...runs.values()].map((r) => ({ runId: r.entry.runId, latest: r.latest, ladder: r.ladder }))
164
- const hint = cli.ok && cli.version ? updateHint(modVersion, cli.version) : null
181
+ const hints = [cli.ok && cli.version ? updateHint(modVersion, cli.version) : null, settings.wakeMode === 'poll' ? 'wake: poll' : null]
182
+ const hint = hints.filter((h) => h !== null).join(' | ') || null
165
183
  $.ui.status(cli.ok ? statusLine(views, stopHookArmed, hint) : `DevOrch: offline (${cli.reason})`)
166
184
  }
167
185
 
@@ -171,7 +189,7 @@ export const register: Register = (on, options) => {
171
189
  run.handedBack = false
172
190
  return
173
191
  }
174
- if (handBackWake({ reportedHealthy: run.reportedHealthy, nowHealthy, stopHookArmed, handedBack: run.handedBack })) {
192
+ if (modWakes(settings.wakeMode) && handBackWake({ reportedHealthy: run.reportedHealthy, nowHealthy, stopHookArmed, handedBack: run.handedBack })) {
175
193
  run.handedBack = true
176
194
  run.reportedHealthy = false
177
195
  $.clock.after(0, () => void submit(run.entry.runId, 'hand-back'))
@@ -204,6 +222,7 @@ export const register: Register = (on, options) => {
204
222
  stopHookArmed,
205
223
  wakePending: run.pendingWake,
206
224
  latest: run.latest,
225
+ modWakes: modWakes(settings.wakeMode),
207
226
  })
208
227
  diag.decision = { at: now(), wake: decision.wake, ...(decision.wake ? {} : { reason: decision.reason }) }
209
228
  if (decision.wake) {
@@ -382,7 +401,8 @@ export const register: Register = (on, options) => {
382
401
  let exitCode = 75
383
402
  let stdout = ''
384
403
  try {
385
- const r = await $.process.run(waitArgv(exe, run.entry.runId, run.entry.baseUrl, run.lastToken), { timeoutMs: POLL_TIMEOUT_MS })
404
+ const argv = waitArgv(exe, run.entry.runId, run.entry.baseUrl, run.lastToken, settings.longPollSeconds)
405
+ const r = await $.process.run(argv, { timeoutMs: pollTimeoutMs(settings.longPollSeconds) })
386
406
  exitCode = r.exitCode
387
407
  stdout = r.stdout
388
408
  } catch {
@@ -555,6 +575,18 @@ export const register: Register = (on, options) => {
555
575
  ops = { watch, unwatch, firstSignal, evaluateAll, answer, shutdown }
556
576
 
557
577
  void (async () => {
578
+ try {
579
+ // The DEVORCH_* variables win over the plugin options (project-scope options may not apply; project `env` does).
580
+ // Literal names: the host lists the variables a module reads. Keep them equal to supervision's SETTING_ENV.
581
+ settings = resolveSettings({
582
+ wakeMode: (await $.env.get('DEVORCH_WAKE_MODE')) ?? undefined,
583
+ fallbackWakeupSeconds: (await $.env.get('DEVORCH_FALLBACK_WAKEUP_SECONDS')) ?? undefined,
584
+ longPollSeconds: (await $.env.get('DEVORCH_LONG_POLL_SECONDS')) ?? undefined,
585
+ }, options)
586
+ for (const w of settings.warnings) $.ui.toast(`DevOrch: ${w}`)
587
+ } catch {
588
+ // keep the option-only settings
589
+ }
558
590
  try {
559
591
  const env = await $.process.hookEnv()
560
592
  pluginRoot = env.CLAUDE_PLUGIN_ROOT ?? ''
@@ -568,10 +600,12 @@ export const register: Register = (on, options) => {
568
600
  await $.tool.register({
569
601
  name: 'devorch_companion',
570
602
  description:
571
- 'The DevOrch companion mod. status {runId?}: whether this session wakes itself for the run (healthy) or the ' +
572
- 'skill must keep its own ScheduleWakeup (healthy:false), plus each watched run\'s rung, control, lease and ' +
573
- 'open blocker refs. watch {runId, baseUrl?}: arm the wake for a run this session drives in a loop (answers ' +
574
- 'after the first event, at most 5 s). unwatch {runId}: stop.',
603
+ 'The DevOrch companion mod. status {runId?}: the wake policy for the run in `wake` (effective "push": the ' +
604
+ 'companion wakes this session, run the step once and schedule nothing; "poll": the skill drives /loop + ' +
605
+ 'ScheduleWakeup with wake.fallbackWakeupSeconds; "unavailable": wakeMode push but the companion is ' +
606
+ 'unhealthy, report and stop), plus healthy, config and each watched run\'s rung, control, lease and open ' +
607
+ 'blocker refs. watch {runId, baseUrl?}: arm the watch for a run this session drives (answers after the ' +
608
+ 'first event, at most 5 s, with the same wake field). unwatch {runId}: stop.',
575
609
  inputSchema: {
576
610
  type: 'object',
577
611
  properties: {
@@ -657,7 +691,7 @@ export const register: Register = (on, options) => {
657
691
  await ops.firstSignal(run)
658
692
  const h = healthOf(run)
659
693
  run.reportedHealthy = h.healthy
660
- return reply({ watching: runs.has(runId), ...h })
694
+ return reply({ watching: runs.has(runId), ...h, wake: wakePolicy(settings.wakeMode, h, settings.fallbackWakeupSeconds) })
661
695
  }
662
696
  if (input.action === 'unwatch') {
663
697
  await ops.unwatch(String(input.runId ?? ''))
@@ -32,7 +32,7 @@ export const CLI_OPTIONS = {
32
32
 
33
33
  export type CliCommand = keyof typeof CLI_OPTIONS
34
34
 
35
- /** Rung-3 long-poll length in seconds (the server's park limit). */
35
+ /** Rung-3 long-poll length in seconds by default: the server's park limit (the CLI accepts 0-25). */
36
36
  export const WAIT_SECONDS = 25
37
37
 
38
38
  /** `devorch run watch <runId> --base-url <url> [--since <token>]`: the long-lived child (rungs 1-2, D15). */
@@ -41,10 +41,17 @@ export function watchArgv(exe: string, runId: string, baseUrl: string, since: st
41
41
  return [exe, 'run', 'watch', runId, '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
42
42
  }
43
43
 
44
- /** `devorch run wait <runId> --seconds 25 --base-url <url> [--since <token>]`: one rung-3 long-poll (D5). */
45
- export function waitArgv(exe: string, runId: string, baseUrl: string, since: string | null): string[] {
44
+ /** `devorch run wait <runId> --seconds <n> --base-url <url> [--since <token>]`: one rung-3 long-poll (D5). `seconds`
45
+ * is the `longPollSeconds` setting, clamped again here so a bad value can never reach argv. */
46
+ export function waitArgv(exe: string, runId: string, baseUrl: string, since: string | null, seconds: number = WAIT_SECONDS): string[] {
46
47
  assertRunId(runId)
47
- return [exe, 'run', 'wait', runId, '--seconds', String(WAIT_SECONDS), '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
48
+ const s = clampInt(seconds, LONG_POLL_RANGE[0], LONG_POLL_RANGE[1], WAIT_SECONDS)
49
+ return [exe, 'run', 'wait', runId, '--seconds', String(s), '--base-url', baseUrl, ...(since ? ['--since', since] : [])]
50
+ }
51
+
52
+ /** How long the mod lets one `run wait` process live: its park time plus 10 s. */
53
+ export function pollTimeoutMs(longPollSeconds: number): number {
54
+ return (clampInt(longPollSeconds, LONG_POLL_RANGE[0], LONG_POLL_RANGE[1], WAIT_SECONDS) + 10) * 1_000
48
55
  }
49
56
 
50
57
  /** Append the run's base URL (D14). */
@@ -302,6 +309,9 @@ export function updateHint(modVersion: string, cliVersion: string): string | nul
302
309
  // ---- health (D6) ----------------------------------------------------------------------------------------------
303
310
 
304
311
  export interface HealthInputs {
312
+ /** `wakeMode` is `poll`: the skill owns the wake, so the mod never reports itself healthy (an older skill copy that
313
+ * branches on `healthy` then keeps its own wakeup). */
314
+ pollMode?: boolean
305
315
  cliOk: boolean
306
316
  cliReason: string
307
317
  stopHookArmed: boolean
@@ -317,9 +327,129 @@ export function health(i: HealthInputs): { healthy: boolean; reason?: string } {
317
327
  if (i.stopHookArmed) return { healthy: false, reason: 'Stop-hook host armed' }
318
328
  if (i.wakeBroken) return { healthy: false, reason: 'wake mechanism broken' }
319
329
  if (i.rung === 4) return { healthy: false, reason: 'run offline (rung 4)' }
330
+ if (i.pollMode) return { healthy: false, reason: 'wakeMode poll: the skill owns the wake' }
320
331
  return { healthy: true }
321
332
  }
322
333
 
334
+ // ---- wake modes: who wakes an interactive run, and the settings behind it --------------------------------------
335
+
336
+ /**
337
+ * `auto` (default): the companion wakes the session while it is healthy, else the skill polls with `/loop` and
338
+ * `ScheduleWakeup`. `push`: the companion only; when it is unhealthy the skill reports that and stops instead of
339
+ * polling. `poll`: never rely on the companion's wake (the mod submits none; it still shows the status line).
340
+ */
341
+ export const WAKE_MODES = ['auto', 'push', 'poll'] as const
342
+ export type WakeMode = (typeof WAKE_MODES)[number]
343
+
344
+ export const FALLBACK_WAKEUP_DEFAULT = 1800
345
+ export const FALLBACK_WAKEUP_RANGE = [60, 3600] as const
346
+ export const LONG_POLL_RANGE = [5, WAIT_SECONDS] as const
347
+
348
+ export type SettingSource = 'env' | 'option' | 'default'
349
+
350
+ /** The environment variable that overrides each plugin option. It wins, because project-scope plugin options may not
351
+ * apply while a project's settings `env` does. */
352
+ export const SETTING_ENV = {
353
+ wakeMode: 'DEVORCH_WAKE_MODE',
354
+ fallbackWakeupSeconds: 'DEVORCH_FALLBACK_WAKEUP_SECONDS',
355
+ longPollSeconds: 'DEVORCH_LONG_POLL_SECONDS',
356
+ } as const
357
+
358
+ export type SettingName = keyof typeof SETTING_ENV
359
+
360
+ export interface Settings {
361
+ wakeMode: WakeMode
362
+ /** The skill's safety-net `ScheduleWakeup` under poll, in seconds. */
363
+ fallbackWakeupSeconds: number
364
+ /** Rung-3 `devorch run wait --seconds`. */
365
+ longPollSeconds: number
366
+ /** Where each value came from. */
367
+ sources: Record<SettingName, SettingSource>
368
+ /** Invalid or clamped values, reported in the tool's `status` (never fatal). */
369
+ warnings: string[]
370
+ }
371
+
372
+ /**
373
+ * Resolve the wake settings. Per setting, the first non-empty of the `DEVORCH_*` environment variable, the plugin
374
+ * option, then the default. An unknown mode falls back to `auto` and a non-number to its default, each with a
375
+ * warning; a number outside its range is clamped, with a warning.
376
+ */
377
+ export function resolveSettings(env: Partial<Record<SettingName, string | undefined>>, options: Partial<Record<SettingName, unknown>> | undefined): Settings {
378
+ const warnings: string[] = []
379
+ const pick = (name: SettingName): { value: unknown; source: SettingSource } => {
380
+ if (present(env[name])) return { value: env[name], source: 'env' }
381
+ if (present(options?.[name])) return { value: options?.[name], source: 'option' }
382
+ return { value: undefined, source: 'default' }
383
+ }
384
+ const label = (name: SettingName, source: SettingSource): string => (source === 'env' ? SETTING_ENV[name] : `option ${name}`)
385
+
386
+ const mode = pick('wakeMode')
387
+ let wakeMode: WakeMode = 'auto'
388
+ if (mode.source !== 'default') {
389
+ const v = String(mode.value).trim().toLowerCase()
390
+ if ((WAKE_MODES as readonly string[]).includes(v)) wakeMode = v as WakeMode
391
+ else warnings.push(`${label('wakeMode', mode.source)}: unknown wake mode "${String(mode.value).trim().slice(0, 20)}"; using auto`)
392
+ }
393
+
394
+ const number = (name: SettingName, range: readonly [number, number], fallback: number): { value: number; source: SettingSource } => {
395
+ const p = pick(name)
396
+ if (p.source === 'default') return { value: fallback, source: 'default' }
397
+ const n = typeof p.value === 'number' ? p.value : Number(String(p.value).trim())
398
+ if (!Number.isFinite(n)) {
399
+ warnings.push(`${label(name, p.source)}: not a number; using ${fallback}`)
400
+ return { value: fallback, source: p.source }
401
+ }
402
+ const clamped = clampInt(n, range[0], range[1], fallback)
403
+ if (clamped !== n) warnings.push(`${label(name, p.source)}: ${n} is outside ${range[0]}..${range[1]}; using ${clamped}`)
404
+ return { value: clamped, source: p.source }
405
+ }
406
+ const fallback = number('fallbackWakeupSeconds', FALLBACK_WAKEUP_RANGE, FALLBACK_WAKEUP_DEFAULT)
407
+ const longPoll = number('longPollSeconds', LONG_POLL_RANGE, WAIT_SECONDS)
408
+
409
+ return {
410
+ wakeMode,
411
+ fallbackWakeupSeconds: fallback.value,
412
+ longPollSeconds: longPoll.value,
413
+ sources: { wakeMode: mode.source, fallbackWakeupSeconds: fallback.source, longPollSeconds: longPoll.source },
414
+ warnings,
415
+ }
416
+ }
417
+
418
+ export interface WakePolicy {
419
+ mode: WakeMode
420
+ /** `push`: the companion wakes the session (run the step once, no /loop, schedule nothing). `poll`: the skill wakes
421
+ * itself (/loop + ScheduleWakeup). `unavailable`: `push` was asked for but the companion is unhealthy; the skill
422
+ * reports it and stops. */
423
+ effective: 'push' | 'poll' | 'unavailable'
424
+ owner: 'companion' | 'skill' | 'none'
425
+ fallbackWakeupSeconds: number
426
+ reason: string
427
+ }
428
+
429
+ /** The one field the skills branch on: the configured mode resolved against the companion's health right now. */
430
+ export function wakePolicy(mode: WakeMode, h: { healthy: boolean; reason?: string }, fallbackWakeupSeconds: number): WakePolicy {
431
+ const base = { mode, fallbackWakeupSeconds }
432
+ if (mode === 'poll') return { ...base, effective: 'poll', owner: 'skill', reason: 'wakeMode poll: /loop + ScheduleWakeup' }
433
+ if (h.healthy) return { ...base, effective: 'push', owner: 'companion', reason: 'the companion is healthy and wakes the session' }
434
+ const why = h.reason ?? 'companion unhealthy'
435
+ if (mode === 'push') return { ...base, effective: 'unavailable', owner: 'none', reason: `wakeMode push, but ${why}` }
436
+ return { ...base, effective: 'poll', owner: 'skill', reason: `companion unhealthy (${why}); the skill polls` }
437
+ }
438
+
439
+ /** Whether the mod itself submits wakes (position-change and hand-back): every mode but `poll`. */
440
+ export function modWakes(mode: WakeMode): boolean {
441
+ return mode !== 'poll'
442
+ }
443
+
444
+ function present(v: unknown): boolean {
445
+ return (typeof v === 'string' && v.trim().length > 0) || (typeof v === 'number' && !Number.isNaN(v))
446
+ }
447
+
448
+ function clampInt(n: number, min: number, max: number, fallback: number): number {
449
+ if (!Number.isFinite(n)) return fallback
450
+ return Math.min(max, Math.max(min, Math.round(n)))
451
+ }
452
+
323
453
  // ---- the status line (D7) -------------------------------------------------------------------------------------
324
454
 
325
455
  export interface RunView {
@@ -1,14 +1,16 @@
1
1
  ---
2
2
  name: devorch-step
3
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>.
4
+ description: Processes the next instruction of a DevOrch run by dispatching its work to a devorch-step-worker subagent, keeping the main thread as a thin orchestrator; the companion mod wakes it for the next one (push) or /loop does (poll). TRIGGERS - devorch step, next devorch step, step this run, loop devorch run. USE WHEN - driving a DevOrch SDLC run one instruction at a time with /devorch-companion:devorch-step <runId>, woken by the companion mod or repeated with /loop /devorch-companion:devorch-step <runId>.
5
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
6
  ---
7
7
 
8
8
  # DevOrch Step
9
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.
10
+ `/devorch-companion:devorch-step <runId>` processes the run's next instruction and, after the worker hands back, goes
11
+ straight on to the one after. Between instructions that can't start yet (a worker running, a `WAIT`), something
12
+ must wake the session again: the companion mod (**push**, realtime) or `/loop` with `ScheduleWakeup` (**poll**, timed).
13
+ The **Wake** check below decides which, on every firing.
12
14
 
13
15
  **The main thread only orchestrates.** Never read stage docs, source files or the context bundle here, and never
14
16
  call `get_context_for_instruction`. The worker does all of that. The only output per instruction is one status line.
@@ -19,6 +21,27 @@ call `get_context_for_instruction`. The worker does all of that. The only output
19
21
  server this session has (for example `mcp__devorch-local-mcp__<verb>`); never mix two servers within one run, because
20
22
  they may point at different backends.
21
23
 
24
+ ## Wake: check it at the start of every firing
25
+
26
+ Exactly one thing wakes this session for a run. Before anything else in a firing (a launch, a wake from the mod, a
27
+ `/loop` tick or a worker's hand-back):
28
+
29
+ 1. If the companion tool `mcp__devorch-companion__devorch_companion` exists, call it with `{action: "watch", runId}`.
30
+ Re-watching a watched run is cheap and answers at once. Add `baseUrl` only when this run lives on a different
31
+ server from the plugin's `apiBase` setting (or `DEVORCH_API_BASE`), such as a worktree slot
32
+ `http://localhost:8704`. Read **`wake.effective`** and `wake.fallbackWakeupSeconds` from the answer. Don't
33
+ re-derive the policy from `healthy`.
34
+ 2. No companion tool: treat it as `poll` with a 1800-second fallback.
35
+ 3. Hold that value for the rest of the firing:
36
+
37
+ | `wake.effective` | Who wakes the session | What this firing does about it |
38
+ |---|---|---|
39
+ | `push` | The companion mod: it submits `/devorch-companion:devorch-step <runId>` within seconds of the run becoming actionable (a blocker answered, a lease freed or lapsed, the run finished), and hands the wake back once if it turns unhealthy. | **Schedule no wakeup, anywhere.** If this firing runs under `/loop`, stop the loop once (`ScheduleWakeup(stop: true)`) and say in one line that the companion owns the wake now; then carry on. |
40
+ | `poll` | You: `ScheduleWakeup` under `/loop`. | Schedule the wakeups named below. If this firing is not under `/loop` (no `ScheduleWakeup` to call), start `/loop /devorch-companion:devorch-step <runId>` at the point where a wakeup is due instead, and end the turn; its first firing picks up from there. |
41
+ | `unavailable` | Nobody: `wakeMode` is `push` but the companion is unhealthy. | Finish a worker's hand-back if this firing is one (steps 5 to 7, so no work is lost), then launch nothing: print `wake.reason`, say `/devorch-companion:devorch-step <runId>` resumes the run once the companion is fixed (or `wakeMode` is set to `auto`/`poll`), stop any `/loop` with `ScheduleWakeup(stop: true)`, and end the turn. |
42
+
43
+ "Schedule a wakeup" below always means: under `poll` only, as this table says.
44
+
22
45
  ## A firing has two halves
23
46
 
24
47
  Subagents run asynchronously, so one instruction spans two turns: **launch** ends the turn, and the worker's
@@ -27,7 +50,8 @@ hand-back starts **finish**.
27
50
  ### Launch
28
51
 
29
52
  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.
53
+ Under `poll`, schedule another fallback wakeup (`wake.fallbackWakeupSeconds`); under `push`, schedule nothing.
54
+ End the turn.
31
55
  2. Call `get_next_instruction(runId, driverId)` and branch on `control`. `driverId` is this session's id
32
56
  (`$CLAUDE_CODE_SESSION_ID`); use the same value on `apply_instruction_result`, because the instruction is leased
33
57
  to it. Pass the **bare** id: the envelope's `lease.holder` reads `driver:<id>` because the server adds that prefix
@@ -37,19 +61,10 @@ hand-back starts **finish**.
37
61
  | `control` | Action |
38
62
  |---|---|
39
63
  | `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`). |
64
+ | `WAIT` | Print the `reason` and open blockers from `get_run_position`. Under `push`, end the turn: the mod wakes the session when the run can move. Under `poll`, schedule a wakeup after `retryAfterSeconds` (else `wake.fallbackWakeupSeconds`). |
41
65
  | `CONTINUE` | Go to 3. |
42
66
 
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
67
+ The answer to a blocker can be given from here with `/devorch-answer <slug> <ref> <answer>` (mod) or
53
68
  `devorch blocker answer <slug> <ref> --text ...` (CLI); never answer it yourself.
54
69
 
55
70
  Re-fetching an instruction that was dispatched but never applied returns the same `instructionId`, so resuming
@@ -76,9 +91,9 @@ hand-back starts **finish**.
76
91
  exact text, and don't blame driverId for an opaque failure.
77
92
  ```
78
93
 
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).
94
+ Under `poll`, first schedule a fallback wakeup of `wake.fallbackWakeupSeconds` (1800 by default) in case the
95
+ worker never hands back. Under `push`, schedule nothing: the mod wakes the session if the worker's instruction
96
+ lease lapses without a result.
82
97
 
83
98
  ### Finish (on the worker's hand-back)
84
99
 
@@ -86,12 +101,15 @@ hand-back starts **finish**.
86
101
  the error appended. On a second failure, call `raise_blocker` with type `error` and treat the run as `WAIT`.
87
102
  6. Call `apply_instruction_result(runId, instructionId, <result JSON>, driverId)`.
88
103
  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.
104
+ 8. **Don't wait for a wakeup, with or without `/loop`: go straight back to Launch step 2 in this same turn** and fetch
105
+ the next instruction (after the Wake check, unless it said `unavailable`). A `CONTINUE` launches the next worker
106
+ now; a `WAIT` or terminal `control` is handled by the step 2 table. This is what keeps a push-driven run snappy:
107
+ the mod only has to wake the session when the run was waiting on something outside it.
92
108
 
93
109
  ## Anti-patterns
94
110
 
95
111
  - Doing a step's work in the main thread.
96
112
  - Echoing the worker's result, or a summary longer than the status line.
113
+ - Scheduling a wakeup, or starting `/loop`, while `wake.effective` is `push`: two wake owners fire twice.
114
+ - Polling when `wake.effective` is `unavailable`: the user chose push only.
97
115
  - Merging to `main` during a run. That's a human confirmation after `DONE`.
@@ -14,8 +14,9 @@ terminal state** in one of two run modes.
14
14
 
15
15
  This skill **does NOT implement the loop.** Both run modes wrap the **same `step_once` primitive**:
16
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.
17
+ - **Interactive** (default, the headline demo) — `/devorch-companion:devorch-step` runs **inside this
18
+ session**, woken by the companion mod the moment the run can move (push), or under `/loop` when the mod can't
19
+ (poll); each step's work happens in a subagent, and you steer between steps.
19
20
  - **Headless** (opt-in with `--headless`, the proven spine) — the loop runs **detached** in
20
21
  `devorch run supervise` (fresh `claude -p` per step, `ANTHROPIC_API_KEY`-strip → guaranteed
21
22
  subscription billing); you watch via the **portal**.
@@ -92,19 +93,32 @@ be blocked once that gate lands, then proceed. (SuperAdmin/system bypass; don't
92
93
 
93
94
  #### Interactive (default — the headline demo)
94
95
 
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).
96
+ The main thread only orchestrates: each instruction's work runs in a `devorch-step-worker` subagent, and the session
97
+ is idle between firings so the user can steer. `devorch-step` handles the terminal `control` notifications (step 6).
98
+ A project-level `/devorch-step` is the same skill where one exists.
99
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.
100
+ **Pick the wake from the companion (DEV-47, DEV-56).** Exactly one thing wakes the session between firings: the
101
+ companion mod (push, realtime) or `/loop` with `ScheduleWakeup` (poll, timed). Decide once, from the mod:
102
+
103
+ 1. If the companion tool `mcp__devorch-companion__devorch_companion` exists, call it with
104
+ `{action: "watch", runId: <runExternalId>}`; add `baseUrl` only when the run lives on a different server from
105
+ `<apiBase>` (for example a worktree slot). Read **`wake.effective`** from the answer and don't re-derive it from
106
+ `healthy`.
107
+ 2. Branch on it:
108
+
109
+ | `wake.effective` | Start the run with |
110
+ |---|---|
111
+ | `push` | **`/devorch-companion:devorch-step <runExternalId>` once, with no `/loop`.** The mod submits the next firing itself whenever the run can move (a blocker answered, a lease freed, the run finished) and hands the wake back if it turns unhealthy. |
112
+ | `poll` | **`/loop /devorch-companion:devorch-step <runExternalId>`**, as before: the step skill schedules its own wakeups (`wake.fallbackWakeupSeconds` as the safety net). |
113
+ | `unavailable` | Nothing. `wakeMode` is `push` but the companion is unhealthy: tell the user `wake.reason`, and that `/devorch-companion:devorch-step <runExternalId>` resumes the run once it's fixed (or set `wakeMode` to `auto`/`poll`). Stop. |
114
+
115
+ **No companion tool:** use `poll`. The one exception is a user who set `wakeMode: push` (or `DEVORCH_WAKE_MODE=push`)
116
+ and said so: report that the companion is missing and stop.
117
+
118
+ The mode comes from the plugin's `wakeMode` setting (`auto` by default: push while the companion is healthy, else
119
+ poll), overridden by `DEVORCH_WAKE_MODE`; see the plugin README's "Wake modes". Blockers can be answered from the
120
+ session with `/devorch-answer <slug> <ref> <answer>` (mod) or `devorch blocker answer <slug> <ref> --text ...`;
121
+ headless `devorch run supervise` parks a WAIT on the server and resumes on its own.
108
122
 
109
123
  > **Billing:** Interactive runs on your already-logged-in subscription — **no key-strip** (you launched
110
124
  > Claude logged in). **Claude-only** for now.
@@ -156,8 +170,9 @@ A back-edge loop or quota-burning run must be stoppable from the operator side:
156
170
  - **Headless:** `<devorch> run abort <runExternalId>` (the same binary as the supervisor, chosen as above) — reaps
157
171
  the tracked headless `claude -p` children for the driver process (best-effort operator stop). Also stop the
158
172
  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>`.
173
+ - **Interactive (in-session control):** unwatch the run with `/devorch-unwatch <runId>` so the companion submits no
174
+ further firing (push), and under `/loop` (poll) tell the session to stop the loop; it calls
175
+ `ScheduleWakeup(stop: true)`.
161
176
 
162
177
  ## Anti-patterns
163
178
 
@@ -31,9 +31,27 @@ export type DevorchRunStatus = {
31
31
  pendingWake: boolean
32
32
  }
33
33
 
34
+ /** Who wakes an interactive run: `push` the companion, `poll` the skill's /loop + ScheduleWakeup, `unavailable`
35
+ * wakeMode push with an unhealthy companion. */
36
+ export type DevorchWakePolicy = {
37
+ mode: 'auto' | 'push' | 'poll'
38
+ effective: 'push' | 'poll' | 'unavailable'
39
+ owner: 'companion' | 'skill' | 'none'
40
+ fallbackWakeupSeconds: number
41
+ reason: string
42
+ }
43
+
34
44
  export type DevorchStatus = {
35
45
  healthy: boolean
36
46
  reason?: string
47
+ wake: DevorchWakePolicy
48
+ config: {
49
+ wakeMode: 'auto' | 'push' | 'poll'
50
+ fallbackWakeupSeconds: number
51
+ longPollSeconds: number
52
+ sources: Record<'wakeMode' | 'fallbackWakeupSeconds' | 'longPollSeconds', 'env' | 'option' | 'default'>
53
+ warnings: string[]
54
+ }
37
55
  cli: { ok: boolean; version: string | null; path: string | null }
38
56
  stopHookArmed: boolean
39
57
  wakeBroken: boolean
package/bin/devorch CHANGED
@@ -1,4 +1,4 @@
1
1
  [diffend] Oversized file quarantined before diffing.
2
2
  name: package/bin/devorch
3
3
  size: 107103985 bytes
4
- sha256: da445319a1fda8bade4b0031a7e5398f446c247d80b5ca9ee39c86bad889479c
4
+ sha256: daf94f1065c07146affea737d5519d29ce8d2c4df85bb0cd2a5486ec9fb59a77
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devorch/cli-linux-x64",
3
- "version": "0.20.0",
3
+ "version": "0.21.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": {