@oisincoveney/pipeline 2.8.3 → 2.9.0

package/.agents/skills/orchestrate/SKILL.md

@@ -1,23 +1,23 @@
 ---
-description: Local multi-agent orchestrator — decompose a task and fan it out to the MoKa specialist roster on the current machine instead of submitting to the remote Moka pipeline. The local twin of the MoKa Orchestrator. On Claude Code, dispatch each agent with `opencode run`; on OpenCode, spawn native Task subagents. Use when the user wants parallel specialist agents driven locally rather than as Argo/k8s jobs.
+description: Local multi-agent orchestration through the supervised MoKa runtime. Start canonical local work with `moka run "<task>"`; use OpenCode native Task subagents only when explicitly chosen; reserve emergency CLI fallback for titled, logged, session-captured recovery.
 name: orchestrate
 ---
 
 # Orchestrate
 
-The **local twin of the MoKa Orchestrator**. The MoKa Orchestrator decomposes a task and submits a schedule to Argo/k8s via `moka submit`, where the runtime executes it as DAG jobs on the cluster. Orchestrate runs the **same roster, same loop, on the current machine** — no schedule, no `moka submit`, no Argo. It is the hands-on, here-and-now path for getting work done through specialist agents.
+The **local supervised twin of the MoKa Orchestrator**. Start local orchestration with `moka run "<task>"` from the repository root. It uses the package-owned roster, config, run-control state, logs, and CLI contracts on the current machine — no raw host subprocess fan-out, no unmanaged local sessions.
 
-Use this skill when the user wants real work driven through **parallel specialist agents locally**: a task large enough to decompose into research / test / implement / verify lanes, where you stay the controller and the agents do the labor.
+Use this skill when the user wants real work driven through **parallel specialist agents locally**: a task large enough to decompose into research / test / implement / verify lanes, where you stay the controller and the agents do the labor through the supervised runtime.
 
 ## When NOT to use
 
-- **Durable, reproducible, or cluster-scale runs** → use [[quick]] or [[execute]] (these submit through `moka submit`). Orchestrate is ephemeral and local; it leaves no schedule artifact.
+- **Durable, reproducible, or cluster-scale runs** → use the remote path (for example `moka run --target remote ...` or the package compatibility commands). Orchestrate is local.
 - **Trivial single-threaded work** → just do it inline. Spawning agents for a one-line change is pure overhead.
-- **You need package gates enforced as part of a pipeline run** → that is the remote path's job. Orchestrate still *uses* the gate agents (Verifier, Acceptance Reviewer, Thermo Nuclear Reviewer) but does not replace pipeline-level gating.
+- **You need package gates enforced by a remote pipeline** → use the remote path. Local orchestration still uses the gate agents, but does not replace remote pipeline gating.
 
 ## The roster
 
-The same specialist agents the MoKa pipeline uses, mirrored locally. Each is `mode: all`, so it works both as an `opencode run --agent` subprocess and as a native Task subagent.
+The same specialist agents the MoKa pipeline uses, mirrored locally through package-owned config. When OpenCode native Task mode is explicitly chosen, select the same agent names.
 
 | Role        | Agent name              | Writes        | Job |
 |-------------|-------------------------|---------------|-----|
@@ -30,43 +30,55 @@ The same specialist agents the MoKa pipeline uses, mirrored locally. Each is `mo
 | Learn       | `MoKa Learner`          | memory only   | Store durable lessons from the completed run (qdrant memory). The pipeline's LEARN phase. |
 | Inspect     | `MoKa Inspector`        | nothing       | Read-only repository inspection / explanation. |
 
-Keep each agent inside its lane — never ask the Code Writer to touch tests, or a reviewer to write files. The lane boundaries are what make fan-out safe. (`MoKa Schedule Planner` is intentionally **not** in this roster: it plans the DAG for remote `moka submit`; locally *you* do that in the Plan step.)
+Keep each agent inside its lane — never ask the Code Writer to touch tests, or a reviewer to write files. The lane boundaries are what make fan-out safe. (`MoKa Schedule Planner` is intentionally **not** in this roster: it plans remote DAGs; locally *you* decompose before dispatch.)
 
-## Dispatch by host
+## Dispatch
 
-The orchestration **doctrine below is identical on every host**. Only the spawn mechanism differs — select the branch for the host you are actually running in.
+The orchestration doctrine is host-neutral: **canonical local orchestration starts with `moka run`**. Host-specific dispatch applies only when the user explicitly chooses OpenCode native Task use or when supervised CLI execution is unavailable and an emergency fallback is accepted.
 
-### On Claude Code → `opencode run`
-
-Spawn each roster member as a headless OpenCode subprocess and read its JSON back:
+### Canonical supervised local run — all hosts
 
 ```sh
-opencode run --agent "MoKa Code Writer" --format json \
-  "<scoped task + acceptance criteria + paths to read>"
+moka run "<scoped task + acceptance criteria + paths to read>"
 ```
 
-- Select the roster member with `--agent "<exact name>"` (names from the table above).
-- Use `--format json` so the agent's structured result comes back machine-readable; parse it, do not eyeball it.
-- **Parallelize independent lanes**: launch each `opencode run` as a background Bash process (one tool call per lane in the same turn), then collect. Run dependent lanes only after their inputs land.
-- Pass context by path, not by paste — agents read the worktree directly. Hand them the files/AC the Researcher produced.
-- `--model` / `--variant` only when a lane genuinely needs a different tier; otherwise inherit.
+- Start here on Claude Code, OpenCode, and plain terminals. Do not pair this with unmanaged local subprocess fan-out for the same work.
+- Use package flags instead of host-specific spawning: `--effort quick`, `--effort thorough`, `--read-only`, `--detach`, or `--target remote` when those modes are intended.
+- Capture the `Run id` and inspect with `moka status <run-id>` and `moka logs <run-id>` rather than relying on an agent transcript alone.
+- If you manually split lanes, keep each lane as its own supervised run with tight scope and explicit acceptance criteria.
 
-### On OpenCode → native Task subagents
+### Explicit OpenCode native Task mode
 
-You are already inside OpenCode — do not shell out to `opencode run`. Spawn the roster directly with the native **Task** tool, selecting the agent by the same name:
+Use this branch only when the user explicitly chooses native OpenCode Task subagents and you are already inside OpenCode.
 
-- `task` → `MoKa Researcher`, `MoKa Test Writer`, `MoKa Code Writer`, `MoKa Verifier`, `MoKa Acceptance Reviewer`, `MoKa Thermo Nuclear Reviewer`, `MoKa Learner`.
+- Spawn the roster directly with the native **Task** tool, selecting the agent by the exact name from the table.
 - Issue independent Task calls together so they run concurrently; sequence dependent ones.
-- Each subagent's structured output returns to you as the controller — gather, do not re-do their work.
+- Each subagent's structured output returns to you as the controller — gather it, do not re-do their work.
+- Do not shell out from OpenCode for local orchestration; if the supervised CLI is available, return to `moka run`.
+
+### Emergency fallback — raw `opencode run`
+
+Use raw `opencode run` only when `moka run` cannot execute, the user still wants local agent work, and you explicitly record that the run is outside MoKa supervision.
+
+```sh
+mkdir -p .pipeline/runs
+title="Emergency fallback: <lane>"
+log=".pipeline/runs/emergency-$(date +%Y%m%d%H%M%S).log"
+opencode run --agent "MoKa Code Writer" --format json \
+  "<scoped task + acceptance criteria + paths to read>" 2>&1 | tee "$log"
+```
+
+- Required capture: fallback title, exact command, cwd, log path, and session id from the output/event stream. If no session id is emitted, state that explicitly.
+- Keep the fallback lane scoped and one-shot; switch back to `moka run` as soon as the supervised runtime is available.
 
 ## The loop
 
-Whichever host you are on, run the same six steps:
+Whichever allowed dispatch path you use, run the same six steps:
 
 1. **Plan** — Decompose the task into a DAG of agent lanes. Model parallelism *structurally*: independent lanes fan out together, dependents wait on their inputs (research → tests → implementation → verify). Do not invent JSON-pointer fanout; nest the work as real lanes.
-2. **Dispatch** — Fan out per the host branch above. Scope each agent tightly: one job, its lane's write boundary, explicit acceptance criteria.
+2. **Dispatch** — Prefer `moka run`; use native Task only when explicitly chosen; use emergency fallback only with the required capture above. Scope each agent tightly: one job, its lane's write boundary, explicit acceptance criteria.
 3. **Gather** — Collect each agent's structured output (`research.json`, the Verifier's verdict JSON, etc.). Treat the returned artifact as the source of truth.
-4. **Gate** — Run `MoKa Verifier` (checks vs AC), `MoKa Acceptance Reviewer` (audits each acceptance criterion), and `MoKa Thermo Nuclear Reviewer` (final code-quality review). Do **not** accept work on a `FAIL` from any gate. Loop the relevant lane (re-dispatch Code Writer with the failure evidence) rather than papering over it.
+4. **Gate** — Run `MoKa Verifier` (checks vs AC), `MoKa Acceptance Reviewer` (audits each acceptance criterion), and `MoKa Thermo Nuclear Reviewer` (final code-quality review). Do **not** accept work on a `FAIL` from any gate. Loop the relevant lane with the failure evidence rather than papering over it.
 5. **Learn** — Once the gates pass, run `MoKa Learner` to store durable lessons from the run (qdrant memory) when there is something worth reusing. This mirrors the canonical pipeline's LEARN phase; skip it only when the run produced nothing reusable.
 6. **Synthesize** — Report only the evidence the agents actually returned: what passed, what the diff is, what the reviewers proved. Never fabricate or assume an outcome an agent did not report.
 
@@ -75,21 +87,22 @@ Whichever host you are on, run the same six steps:
 Token usage is the dominant cost and quality lever — it explains the bulk of agent performance variance, and context degrades well before a model's window fills. But the first job of sizing is **reliable completion**: a lane an agent can't finish is worthless however cheap. Size the work accordingly:
 
 - **Size for reliable completion first.** Each lane must be small enough that a single agent session finishes it cleanly. If an agent times out, stalls, or returns having only *planned* without producing its artifact, the lane was **too big** — split it into smaller lanes (one file, section, or concern each); do **not** just raise the timeout, that re-runs the same flake. **Slow is fine; flaky is not** — many small lanes that each reliably complete beat one big lane that gambles. Lanes that share a file run sequentially; only truly independent lanes fan out. Treat repeated stalls as a decomposition bug, not bad luck.
-- **Under-timeouts and permission walls are the real flake sources — not a step cap.** Per opencode's docs, an agent with no `steps`/`maxSteps` set "will continue to iterate until the model chooses to stop or the user interrupts the session" — i.e. **no hard step budget by default** (the MoKa agents set none). So a Code Writer that returns having only *planned* was not hitting a step limit; it was killed by too short a dispatch timeout or blocked on a denied read (e.g. `external_directory: deny`). Fixes: give long multi-file authoring runs **generous wall-clock** (do not kill them early — they are slow, not capped); scope lanes so they don't need denied/external reads; and only if you must *bound* a runaway agent, set `steps` in its config. Smaller lanes still help (less work = faster, fewer surprises), but "multi-file authoring can't be delegated" is a timeout/scoping issue, not an opencode limit.
-- **Scale fan-out to complexity, not ambition.** A trivial change is one agent (or just do it inline); a bounded change is 1–3 lanes; only go wide for genuinely independent breadth. Code parallelizes poorly — keep writer lanes narrow (the pipeline caps `green`/code fan-out at 2 for exactly this reason).
+- **Under-timeouts and permission walls are the real flake sources.** Give long multi-file authoring runs generous wall-clock, scope lanes so they don't need denied/external reads, and only bound runaway agents when you genuinely need a hard limit. Smaller lanes still help (less work = faster, fewer surprises), but "multi-file authoring can't be delegated" is usually a timeout/scoping issue.
+- **Scale fan-out to complexity, not ambition.** A trivial change is one agent (or just do it inline); a bounded change is 1–3 lanes; only go wide for genuinely independent breadth. Code parallelizes poorly — keep writer lanes narrow.
 - **Keep each agent's context small and high-signal.** Pass context by path and hand over the distilled `research.json`, never raw repo dumps. A lane that needs half the repo in its context is mis-scoped — split it.
 - **Distilled returns.** Expect each sub-agent to return a ~1–2k-token summary of its result, not its full transcript. Gather the summary; don't re-read the work.
-- **Re-dispatch once, with evidence.** On a gate `FAIL`, re-dispatch the failing lane a *single* time with concentrated failure evidence — do not thrash. Each fresh `opencode run` re-pays the full cold-start context tax (~35k tokens of standup before any work), so a retry loop is expensive; fix the input, not the dice.
+- **Re-dispatch once, with evidence.** On a gate `FAIL`, re-dispatch the failing lane a *single* time with concentrated failure evidence — do not thrash. Each fresh supervised lane pays the cold-start context cost; fix the input, not the dice.
 - **Smallest roster that covers the work.** Every extra lane is another cold standup. Default to the fewest specialists that close the task; add a lane only when it genuinely runs independently.
 
 ## Rules
 
-- **Doctrine is host-neutral; only the Dispatch section is host-specific.** Do not leak `opencode run` syntax into an OpenCode run or Task-tool talk into a Claude run.
+- **Canonical local orchestration starts with `moka run`.** Do not tell Claude Code to use `moka run` and also spawn unmanaged subprocesses.
+- **Host distinction is opt-in.** OpenCode native Task subagents are valid only when explicitly chosen; otherwise use the supervised CLI.
+- **Emergency fallback is not canonical.** Raw host CLI use requires the title/log/session capture above and must be reported as unsupervised.
 - **You are the controller, not a worker.** Decompose, dispatch, gate, synthesize. Let the specialists do the labor inside their lanes.
 - **Evidence only.** Report what agents returned. A green claim needs a Verifier `PASS` with evidence behind it — see [[verify]].
 - **Respect lane write boundaries.** Researcher/Verifier/both Reviewers write no repo files (Researcher emits only `research.json`; Learner writes only to memory); Test Writer touches only tests; Code Writer touches only `src/`. Mixed lanes corrupt parallel fan-out.
-- **Local, not durable.** If the user needs a reproducible cluster run or a schedule artifact, route to [[quick]] / [[execute]] instead.
 
 ## The short version
 
-Orchestrate is `moka submit` brought home: same roster, same decompose → dispatch → gather → gate → learn → synthesize loop, run on this machine. On Claude Code each agent is an `opencode run --agent` subprocess; on OpenCode each is a native Task subagent. You stay the orchestrator — fan out the lanes, gate on real verifier *and* reviewer evidence, capture lessons via the Learner, and report only what the agents proved.
+Start local orchestration with `moka run "<task>"`. Use OpenCode native Task subagents only when explicitly chosen, and use emergency raw CLI fallback only with title, log, and session capture. You stay the orchestrator — decompose the lanes, gate on real verifier *and* reviewer evidence, capture lessons via the Learner, and report only what the agents proved.

package/README.md

@@ -82,61 +82,71 @@ moka explain-plan
 
 ## Command Surface
 
-`moka submit "<task>"`
+`moka run "<task>"` is the primary command surface.
 
-Generates the full graph schedule for a task, builds the runner payload from the
-current git context, and submits an Argo Workflow to the configured Momokaya
-cluster.
-
-```shell
-moka submit "Implement PIPE-123 user-facing behavior"
-```
-
-`moka submit "<task>" --quick`
-
-Uses the compact graph for smaller work.
-
-```shell
-moka submit "Fix the login bug" --quick
-```
-
-`moka submit --schedule <schedule.yaml> "<task>"`
-
-Submits a previously approved schedule artifact.
-
-```shell
-moka submit --schedule .pipeline/runs/<runId>/schedule.yaml "Implement PIPE-123"
-```
-
-`moka submit --command -- <argv...>`
-
-Submits one explicit command as a one-task Argo Workflow.
-
-```shell
-moka submit --command -- opencode run "fix this bug"
-```
-
-`moka run "<task>"`
-
-Runs package-owned workflow config from the current worktree. Scheduled
+It runs package-owned workflow config from the current worktree. Scheduled
 entrypoints generate a schedule artifact under `.pipeline/runs/<runId>/` and run
 the compiled schedule through the runtime.
 
+Canonical commands:
+
+- `moka run "<task>"`: start the primary local or remote run flow.
+- `moka runs`: list known runs, newest first.
+- `moka status <run-id>`: show run and node status; add `--watch` to poll.
+- `moka logs <run-id> [node-id]`: print whole-run or node-specific artifacts.
+- `moka stop <run-id> [node-id]`: abort a run or one active node.
+- `moka export <run-id> --sanitize`: print a portable evidence bundle.
+- `moka doctor`: check local prerequisites and config health.
+- `moka init`: install package-owned host resources for a repository.
+
 ```shell
 moka run "Implement PIPE-123 user-facing behavior"
+moka run --target local --effort normal "Implement a standard local change"
 moka run --schedule .pipeline/runs/<runId>/schedule.yaml "Implement PIPE-123"
 moka run --workflow inspect "Report the app structure and available checks. Do not modify files."
-moka run --entrypoint quick "Implement a focused fix"
+moka run --effort quick "Implement a focused fix"
+moka run --effort normal "Implement a standard fix"
+moka run --target remote --effort thorough "Submit a full hosted graph run"
+moka run --read-only "Inspect the repository without edits"
+moka run --target remote --command -- opencode run "fix this bug"
 ```
 
-`moka inspect "<task>"`
+Flag defaults and choices:
 
-Runs the configured read-only inspection entrypoint.
+- `--target` selects `local` (default, current worktree) or `remote` (hosted
+  Momokaya submission). Use canonical `moka run --target remote "<task>"` for
+  hosted graph runs.
+- `--effort` selects `quick`, `normal`, or `thorough`; `normal` is the default.
+- `--read-only` switches mode to `read`; mode defaults to `write`.
 
-```shell
-moka inspect "Explain the app structure and available checks"
+Local run artifacts live under `.pipeline/runs/<runId>/`:
+
+```text
+.pipeline/runs/<runId>/
+  schedule.yaml
+  manifest.json
+  status.json
+  events.ndjson
+  nodes/<node-id>/
+  artifacts/
 ```
 
+Use `moka export <run-id> --sanitize` before sharing a run. The sanitized export
+keeps portable evidence and omits prompt text, session body content, secrets,
+tokens, and credentials.
+
+Compatibility aliases and presets remain available for existing scripts:
+
+- `moka quick "<task>"` is a compatibility preset for
+  `moka run --effort quick "<task>"`.
+- `moka execute "<task>"` is a compatibility preset for
+  `moka run --effort thorough "<task>"`.
+- `moka inspect "<task>"` is a compatibility preset for
+  `moka run --read-only "<task>"`.
+- `moka submit "<task>"` is a compatibility alias for
+  `moka run --target remote --effort thorough "<task>"`. Its existing `--quick`,
+  `--schedule`, and `--command` options remain supported for remote submissions.
+
 Use `PIPELINE_TARGET_PATH=/path/to/worktree` when invoking `moka` from outside
 the target repository.
 

package/defaults/pipeline.yaml

@@ -15,18 +15,10 @@ repo_map:
 # last passed node without re-running (or re-spending tokens on) finished work.
 durability:
   enabled: true
-# best_of_n / parallel_worktrees: the verifier-pattern dial. Schedule generation
-# + selection are validated/tested, BUT a live end-to-end run (2026-06-16) proved
-# the EXECUTION is not yet production-ready, so it stays OFF by default (on-by-
-# default made real runs hang). Two runtime gaps remain — see PIPE-83.14:
-#   1. The leased opencode server is rooted at the main worktree and throws
-#      "Unexpected server error" when a candidate session runs with directory set
-#      to its isolated worktree → candidates exit 70, retries exhaust, green loops.
-#      Fix: lease a per-worktree opencode server for each candidate.
-#   2. The winning candidate's file changes live in its worktree and are never
-#      merged back to the main tree, so downstream nodes wouldn't see them.
-# Enable explicitly (best_of_n.enabled + n:2 + categories:[green] + parallel_
-# worktrees.enabled) once those land; n=2 also ~doubles green-node spend.
+# parallel_worktrees: opt-in git-worktree isolation for parallel child nodes —
+# each parallel child runs on its own branch with its own per-worktree opencode
+# server so concurrent edits and sessions can't collide. OFF by default; enable
+# explicitly with parallel_worktrees.enabled.
 token_budget:
   default_context_window: 200000
   max_context_pct: 50
@@ -62,6 +54,15 @@ runner_command:
     setup:
       - command: bun
         args: [install, --frozen-lockfile]
+      # Set up package-owned pipeline support + the opencode model registration
+      # (.opencode/opencode.json, which declares the gpt-5.5-* reasoning selectors)
+      # on every run, so opencode-backed agents in the pod resolve their models
+      # instead of failing with "Model not found". Both commands are idempotent
+      # and write no repo-local pipeline config.
+      - command: moka
+        args: [init]
+      - command: moka
+        args: [install-commands]
 scheduler:
   commands:
     quick:

package/defaults/profiles.yaml

@@ -88,7 +88,7 @@ profiles:
   moka-orchestrator:
     runner: opencode
     description: Orchestrate the configured pipeline and enforce gates.
-    instructions: { inline: "Orchestrate the configured pipeline locally. Load the `orchestrate` skill and spawn the roster as native Task subagents on this machine. Do not submit to Argo or run `moka submit`. Enforce only package-configured gates." }
+    instructions: { inline: "Orchestrate through the canonical local `moka run` supervisor. For compatibility slash commands, run the `moka run` command and flags shown in the command body. Treat execution as CLI/supervised runtime, not OpenCode-native Task execution. Enforce only package-configured gates." }
     skills: [orchestrate, execute, quick, inspect]
     mcp_servers: [pipeline-gateway]
     tools: [read, list, grep, glob, bash]

package/dist/argo-submit.js

@@ -1,9 +1,9 @@
 import { ArgoGraphCompilerError, compileArgoExecutionGraph } from "./argo-graph.js";
+import { parseRunnerCommandPayload, runnerCommandPayloadSchema } from "./runner-command-contract.js";
 import { buildRunnerTaskDescriptor } from "./runner-command/task-descriptor.js";
 import { buildRunnerArgoWorkflowManifest, runnerArgoWorkflowManifestSchema } from "./argo-workflow.js";
 import { normalizeRunnerRepositoryForSubmit } from "./git-remote-url.js";
 import { compileScheduleArtifact, parseScheduleArtifact } from "./planning/generate.js";
-import { parseRunnerCommandPayload, runnerCommandPayloadSchema } from "./runner-command-contract.js";
 import { KubernetesArgoService, KubernetesArgoServiceLive } from "./runtime/services/kubernetes-argo-service.js";
 import { workflowSubmitResultSchema } from "./workflow-submit-contract.js";
 import { stringify } from "yaml";

package/dist/cli/doctor.d.ts

@@ -0,0 +1,21 @@
+//#region src/cli/doctor.d.ts
+interface DoctorCheck {
+  detail: string;
+  name: string;
+  passed: boolean;
+}
+interface DoctorResult {
+  blockers: DoctorCheck[];
+  checks: DoctorCheck[];
+  passed: boolean;
+  warnings: DoctorCheck[];
+}
+interface DoctorFlags {
+  cluster?: boolean | string;
+  json?: boolean;
+  kubeContext?: string;
+  kubeconfig?: string;
+}
+declare function runDoctor(cwd: string, options?: DoctorFlags): Promise<DoctorResult>;
+//#endregion
+export { runDoctor };

package/dist/cli/doctor.js

@@ -0,0 +1,268 @@
+import { PipelineConfigError } from "../config/schemas.js";
+import { loadPipelineConfig } from "../config/load.js";
+import "../config.js";
+import { opencodeAgentName } from "../runtime/opencode-agent-name.js";
+import { loadMokaGlobalConfig } from "../moka-global-config.js";
+import { defaultClusterDoctorNamespace, runClusterDoctor } from "../cluster-doctor.js";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { execa } from "execa";
+import { join } from "node:path";
+import matter from "gray-matter";
+//#region src/cli/doctor.ts
+const HEADLESS_AGENT_PERMISSION_VALUES = new Set(["ask"]);
+const RUN_READINESS_CATEGORIES = new Set([
+	"acceptance",
+	"green",
+	"intake",
+	"red",
+	"research",
+	"verification"
+]);
+const OPENCODE_AGENT_LIST_ARGS = [
+	"agent",
+	"list",
+	"--json"
+];
+const BULLET_PREFIX_RE = /^[-*]\s+/;
+const LINE_RE = /\r?\n/;
+async function runDoctor(cwd, options = {}) {
+	const commandChecks = await Promise.all([
+		checkCommand("npx", ["--version"], cwd),
+		checkCommand("opencode", ["--version"], cwd),
+		checkCommand("fallow", ["--version"], cwd)
+	]);
+	const configCheck = checkPipelineConfig(cwd);
+	const config = configCheck.passed ? loadPipelineConfig(cwd) : null;
+	const [sdkCheck, agentVisibility] = await Promise.all([checkOpenCodeSdk(), config ? checkMokaAgents(cwd, config) : Promise.resolve({ check: {
+		detail: "skipped because pipeline config is invalid",
+		name: "moka-agents",
+		passed: true
+	} })]);
+	const globalConfig = loadMokaGlobalConfig();
+	const clusterResult = options.cluster ? await runClusterDoctor({
+		kubeContext: options.kubeContext,
+		kubeconfigPath: options.kubeconfig ?? globalConfig?.momokaya.kubernetes.kubeconfig,
+		namespace: clusterNamespace(options.cluster, globalConfig?.momokaya.kubernetes.namespace)
+	}) : { checks: [] };
+	const checks = [
+		...commandChecks,
+		configCheck,
+		sdkCheck,
+		agentVisibility.check,
+		...clusterResult.checks
+	];
+	const warnings = [...agentVisibility.warning ? [agentVisibility.warning] : [], ...headlessPermissionWarnings(cwd)];
+	const blockers = checks.filter((check) => !check.passed);
+	return {
+		blockers,
+		checks,
+		passed: blockers.length === 0,
+		warnings
+	};
+}
+function clusterNamespace(value, configuredNamespace) {
+	return typeof value === "string" && value.length > 0 ? value : configuredNamespace ?? defaultClusterDoctorNamespace();
+}
+function checkCommand(name, args, cwd) {
+	return checkCommandWithRunner(name, name, args, cwd);
+}
+async function checkCommandWithRunner(name, command, args, cwd) {
+	try {
+		await execa(command, args, {
+			cwd,
+			stdin: "ignore"
+		});
+		return {
+			detail: "available",
+			name,
+			passed: true
+		};
+	} catch (err) {
+		return {
+			detail: commandErrorDetail(err),
+			name,
+			passed: false
+		};
+	}
+}
+function checkPipelineConfig(cwd) {
+	try {
+		loadPipelineConfig(cwd);
+		return {
+			detail: "valid",
+			name: "pipeline-config",
+			passed: true
+		};
+	} catch (err) {
+		let message = "invalid";
+		if (err instanceof PipelineConfigError) message = err.issues.map((issue) => issue.message).join("; ");
+		else if (err instanceof Error) message = err.message;
+		return {
+			detail: message || "missing or invalid",
+			name: "pipeline-config",
+			passed: false
+		};
+	}
+}
+async function checkOpenCodeSdk() {
+	try {
+		if (typeof (await import("@opencode-ai/sdk")).createOpencodeClient !== "function") return {
+			detail: "@opencode-ai/sdk does not export createOpencodeClient",
+			name: "opencode-sdk",
+			passed: false
+		};
+		return {
+			detail: "importable",
+			name: "opencode-sdk",
+			passed: true
+		};
+	} catch (err) {
+		return {
+			detail: commandErrorDetail(err),
+			name: "opencode-sdk",
+			passed: false
+		};
+	}
+}
+async function checkMokaAgents(cwd, config) {
+	const expected = expectedRunAgentNames(config);
+	if (expected.length === 0) return { check: {
+		detail: "no configured MoKa run agents",
+		name: "moka-agents",
+		passed: true
+	} };
+	try {
+		const visible = visibleAgentNames((await execa("opencode", OPENCODE_AGENT_LIST_ARGS, {
+			cwd,
+			stdin: "ignore"
+		})).stdout);
+		if (!visible.recognized) return skippedAgentVisibility("OpenCode agent listing output was not recognized");
+		if (visible.ambiguous && expected.every((name) => !visible.names.has(name))) return skippedAgentVisibility("OpenCode agent listing output did not include recognizable MoKa agent names");
+		const missing = expected.filter((name) => !visible.names.has(name));
+		return { check: missing.length ? {
+			detail: `missing configured MoKa agents: ${missing.join(", ")}`,
+			name: "moka-agents",
+			passed: false
+		} : {
+			detail: `visible: ${expected.join(", ")}`,
+			name: "moka-agents",
+			passed: true
+		} };
+	} catch (err) {
+		return skippedAgentVisibility(`Could not cheaply list OpenCode agents: ${commandErrorDetail(err)}`);
+	}
+}
+function skippedAgentVisibility(detail) {
+	return {
+		check: {
+			detail: "skipped because OpenCode agent listing is unavailable",
+			name: "moka-agents",
+			passed: true
+		},
+		warning: {
+			detail,
+			name: "moka-agents",
+			passed: true
+		}
+	};
+}
+function expectedRunAgentNames(config) {
+	const profiles = /* @__PURE__ */ new Set();
+	for (const catalog of Object.values(config.scheduler.node_catalogs)) for (const node of Object.values(catalog.nodes)) if (RUN_READINESS_CATEGORIES.has(node.category)) profiles.add(node.profile);
+	return [...profiles].filter((profileId) => config.profiles[profileId]?.runner === "opencode").map(opencodeAgentName).sort((a, b) => a.localeCompare(b));
+}
+function visibleAgentNames(stdout) {
+	const names = /* @__PURE__ */ new Set();
+	try {
+		const parsed = JSON.parse(stdout);
+		return {
+			ambiguous: false,
+			names,
+			recognized: collectAgentNames(parsed, names, Array.isArray(parsed))
+		};
+	} catch {
+		for (const line of stdout.split(LINE_RE)) {
+			const name = line.trim().replace(BULLET_PREFIX_RE, "");
+			if (name) names.add(name);
+		}
+	}
+	return {
+		ambiguous: true,
+		names,
+		recognized: names.size > 0
+	};
+}
+function collectAgentNames(value, names, inAgentList) {
+	if (typeof value === "string") {
+		if (inAgentList) names.add(value);
+		return inAgentList;
+	}
+	if (Array.isArray(value)) {
+		let recognized = inAgentList;
+		for (const item of value) recognized = collectAgentNames(item, names, inAgentList) || recognized;
+		return recognized;
+	}
+	if (!(value && typeof value === "object")) return false;
+	const record = value;
+	let recognized = false;
+	for (const key of [
+		"agent",
+		"id",
+		"name",
+		"subagent_type",
+		"title"
+	]) if (typeof record[key] === "string") {
+		names.add(record[key]);
+		recognized = true;
+	}
+	for (const key of [
+		"agents",
+		"data",
+		"items",
+		"result"
+	]) {
+		const item = record[key];
+		if (Array.isArray(item) || item && typeof item === "object") recognized = collectAgentNames(item, names, true) || recognized;
+	}
+	return recognized;
+}
+function headlessPermissionWarnings(cwd) {
+	if (!isHeadless()) return [];
+	const agentDir = join(cwd, ".opencode", "agents");
+	if (!existsSync(agentDir)) return [];
+	return readdirSync(agentDir).filter((entry) => entry.endsWith(".md")).flatMap((entry) => headlessPermissionWarning(join(agentDir, entry), entry));
+}
+function headlessPermissionWarning(path, entry) {
+	try {
+		if (!statSync(path).isFile()) return [];
+		const risky = interactivePermissionPaths(matter(readFileSync(path, "utf8")).data.permission);
+		if (risky.length === 0) return [];
+		return [{
+			detail: `${entry} requires interactive permission prompts at ${risky.join(", ")}; headless MoKa runs may block.`,
+			name: "headless-permissions",
+			passed: true
+		}];
+	} catch (err) {
+		return [{
+			detail: `Could not inspect ${entry} for headless permission risks: ${commandErrorDetail(err)}`,
+			name: "headless-permissions",
+			passed: true
+		}];
+	}
+}
+function interactivePermissionPaths(value, path = ["permission"]) {
+	if (typeof value === "string") return HEADLESS_AGENT_PERMISSION_VALUES.has(value.toLowerCase()) ? [path.join(".")] : [];
+	if (Array.isArray(value)) return value.flatMap((item, index) => interactivePermissionPaths(item, [...path, String(index)]));
+	if (!(value && typeof value === "object")) return [];
+	return Object.entries(value).flatMap(([key, item]) => interactivePermissionPaths(item, [...path, key]));
+}
+function isHeadless() {
+	const ci = process.env.CI?.toLowerCase();
+	return ci !== void 0 && ci !== "" && ci !== "0" && ci !== "false" || !process.stdin.isTTY;
+}
+function commandErrorDetail(err) {
+	const error = err;
+	return (error.shortMessage || error.stderr || error.message || String(err)).trim() || "not available";
+}
+//#endregion
+export { runDoctor };

package/dist/cli/format.js

@@ -3,7 +3,8 @@ const LINE_RE = /\r?\n/;
 function createTerminalRuntimeReporter(write = (message) => console.log(message)) {
 	const state = { attempts: /* @__PURE__ */ new Map() };
 	return (event) => {
-		write(formatRuntimeProgressMessage(event, state));
+		const message = formatRuntimeProgressMessage(event, state);
+		if (message !== null) write(message);
 	};
 }
 function formatRuntimeProgressMessage(event, state = { attempts: /* @__PURE__ */ new Map() }) {
@@ -72,7 +73,7 @@ function formatRuntimeEventOutput(output) {
 function formatRepairProgress(event) {
 	switch (event.type) {
 		case "output.repair": return `Output repair ${event.passed ? "passed" : "failed"}: ${event.nodeId} attempt=${event.attempt}${event.reason ? ` (${event.reason})` : ""}`;
-		default: throw new Error(`Unhandled runtime event: ${event.type}`);
+		default: return null;
 	}
 }
 function formatObservabilityProgress(event) {
@@ -117,7 +118,9 @@ function formatRuntimeFailure(result) {
 	return lines.join("\n");
 }
 function formatDoctorResult(result) {
-	return [`Doctor: ${result.passed ? "PASS" : "FAIL"}`, ...result.checks.map((check) => `- ${check.passed ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`)].join("\n");
+	const lines = [`Doctor: ${result.passed ? "PASS" : "FAIL"}`, ...result.checks.map((check) => `- ${check.passed ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`)];
+	if (result.warnings?.length) lines.push(...result.warnings.map((check) => `- WARN ${check.name}: ${check.detail}`));
+	return lines.join("\n");
 }
 function appendIndentedSection(lines, label, values) {
 	const text = values.filter(Boolean).join("\n").trim();