@soleur/opencode 0.0.0-stage → 1.0.0

package/lib/harness.ts

@@ -0,0 +1,716 @@
+/**
+ * Harness adapter — maps Soleur workflow invocations to Claude Code, Grok Build, Codex, Devin CLI, or the Cursor CLI.
+ *
+ * Claude: Skill tool (`soleur:<skill>`), Task tool (agents), `/soleur:<command>` slash commands.
+ * Grok:   slash commands (`/<skill>`, `/go`), spawn_subagent (agents).
+ * Codex:  $soleur:<skill> skill mentions, spawn_agent (agents).
+ * Devin:  Skill tool (`soleur:<skill>`), run_subagent (agents), `/soleur:<command>` slash commands.
+ * Cursor: `/go` and `/sync` stay bare; every other skill and agent is `/soleur-<name>`. Slice 1 does not detect this harness.
+ * OpenCode: bare skill ids (the registration key), agents via the subagent tool keyed on the path id.
+ *
+ * Skills and go.md must call these helpers (or follow routingInstructions) — never improvise workflows.
+ */
+
+import { resolve } from "path";
+import {
+  agentIdToPath,
+  agentIdToGrokSubagentType,
+  discoverAgentEntries,
+  pathToAgentId,
+  PLUGIN_ROOT,
+} from "./agent-registry";
+import { cursorAgentSlash, cursorSkillSlash } from "../scripts/sync-cursor-name-map";
+import { behindSyncInstructions } from "./pr-merge-poll";
+import { pipelineInvocationSuffix, workflowFidelityInstructions } from "./workflow-fidelity";
+
+export type Harness = "claude" | "grok" | "codex" | "devin" | "cursor" | "opencode" | "antigravity" | "unknown";
+
+/** Env vars set by Antigravity CLI / Google Gemini CLI. */
+const ANTIGRAVITY_ENV_MARKERS = [
+  "ANTIGRAVITY_CLI",
+  "AGY_VERSION",
+  "GEMINI_CLI",
+] as const;
+
+/** Env vars set by Grok Build (see https://docs.x.ai/build/settings/reference). */
+const GROK_ENV_MARKERS = [
+  "GROK_HOME",
+  "GROK_AGENT",
+  "GROK_DEFAULT_MODEL",
+  "GROK_SUBAGENTS",
+] as const;
+
+/** Env vars set by Devin CLI. */
+const DEVIN_ENV_MARKERS = [
+  "DEVIN",
+  "DEVIN_HOME",
+] as const;
+
+export interface SkillInvocation {
+  harness: Harness;
+  tool: "Skill" | "slash_command" | "skill";
+  command: string;
+  args?: string;
+  instruction: string;
+}
+
+export interface AgentSpawn {
+  harness: Harness;
+  tool: "Task" | "spawn_subagent" | "spawn_agent" | "run_subagent" | "invoke_subagent" | "subagent";
+  agent: string;
+  prompt: string;
+  instruction: string;
+}
+
+/** Strip `soleur:` prefix; Grok exposes bare skill names as slash commands. */
+export function normalizeSkillName(skill: string): string {
+  return skill.replace(/^soleur:/, "");
+}
+
+/**
+ * Ensure agent ids are plugin-qualified when a bare or path-style name is passed.
+ * Path-style: `engineering/review/security-sentinel` → registry-qualified id.
+ */
+export function normalizeAgentName(agent: string): string {
+  if (agent.startsWith("soleur:")) {
+    return agent;
+  }
+  if (agent.includes("/")) {
+    return pathToAgentId(`agents/${agent.replace(/\.md$/, "")}.md`);
+  }
+  if (agent.includes(":")) {
+    return `soleur:${agent}`;
+  }
+  return agent;
+}
+
+/**
+ * Detect the active harness from environment markers and process metadata.
+ * Detection order: CLAUDECODE → OPENCODE → ANTIGRAVITY_* → GROK_* → CODEX_THREAD_ID → DEVIN_* → process title/argv heuristics.
+ *
+ * OPENCODE is checked second, and before the config-path markers, on purpose. OpenCode injects it
+ * into the environment of every process it spawns as a tool call — and into nothing else: a clean
+ * env, `opencode serve`, `opencode acp`, and the session runtime process itself all lack it
+ * (measurements.md §1.1). GROK_HOME / DEVIN_HOME are installation *paths* that a shell profile can
+ * export into any session, so they must not be able to shadow a marker OpenCode injects itself.
+ * CLAUDECODE keeps the first position the existing precedence tests pin.
+ *
+ * `AI_AGENT=opencode` is present in the same arm but is deliberately NOT the predicate: the name is
+ * generic (measurements.md §1.0 caveat).
+ */
+export function detectHarness(env: NodeJS.ProcessEnv = process.env): Harness {
+  if (env.CLAUDECODE) {
+    return "claude";
+  }
+
+  if (env.OPENCODE) {
+    return "opencode";
+  }
+
+  for (const key of ANTIGRAVITY_ENV_MARKERS) {
+    if (env[key]) {
+      return "antigravity";
+    }
+  }
+
+  for (const key of GROK_ENV_MARKERS) {
+    if (env[key]) {
+      return "grok";
+    }
+  }
+
+  if (env.CODEX_THREAD_ID) {
+    return "codex";
+  }
+
+  for (const key of DEVIN_ENV_MARKERS) {
+    if (env[key]) {
+      return "devin";
+    }
+  }
+
+  // Process heuristics apply only when inspecting the live runtime env — not
+  // injected test fixtures (Grok Build's argv/title would false-positive "grok").
+  if (env === process.env && typeof process !== "undefined") {
+    const title = (process.title ?? "").toLowerCase();
+    const argv = process.argv.join(" ").toLowerCase();
+    if (title.includes("antigravity") || /\b(antigravity|agy)\b/.test(argv)) {
+      return "antigravity";
+    }
+    if (title.includes("grok") || /\bgrok\b/.test(argv)) {
+      return "grok";
+    }
+    if (title.includes("devin") || /\bdevin\b/.test(argv)) {
+      return "devin";
+    }
+  }
+
+  return "unknown";
+}
+
+/**
+ * Return the harness-specific skill invocation string (display / logging).
+ */
+export function formatSkillInvocation(skill: string, args?: string): string {
+  const harness = detectHarness();
+  const name = normalizeSkillName(skill);
+  const trimmedArgs = args?.trim();
+
+  if (harness === "codex") {
+    return trimmedArgs ? `$soleur:${name} ${trimmedArgs}` : `$soleur:${name}`;
+  }
+
+  if (harness === "grok") {
+    return trimmedArgs ? `/${name} ${trimmedArgs}` : `/${name}`;
+  }
+
+  if (harness === "opencode") {
+    // OpenCode's skill id is the bare directory basename: the name must equal its directory
+    // (measurements §2.3), so `soleur:<name>` cannot be a registration key. This is the same
+    // bare-dispatch shape Grok already carries, not a new exception (ADR-291 D1).
+    return trimmedArgs ? `${name} ${trimmedArgs}` : name;
+  }
+
+  if (harness === "devin") {
+    const command = trimmedArgs ? `/soleur:${name} ${trimmedArgs}` : `/soleur:${name}`;
+    return command;
+  }
+
+  if (harness === "antigravity") {
+    const command = trimmedArgs ? `/soleur:${name} ${trimmedArgs}` : `/soleur:${name}`;
+    return command;
+  }
+
+  // Claude's operator-typed form is the slash command, exactly as the codex/grok/devin arms
+  // above give theirs. This used to return `soleur:<name> (args: <x>)` — a DISPLAY string no
+  // operator can type — while ADR-226 §4 and the `operator-typed-render` blocks in ten skills
+  // cite this function as the thing that produces a typeable form. The blocks were right about
+  // the contract and the claude arm was the outlier (#8299).
+  const command = `/soleur:${name}`;
+  return trimmedArgs ? `${command} ${trimmedArgs}` : command;
+}
+
+/**
+ * Structured skill invocation — use at routing sites instead of improvising steps.
+ */
+export function invokeSkill(skill: string, args?: string): SkillInvocation {
+  const harness = detectHarness();
+  const name = normalizeSkillName(skill);
+  const trimmedArgs = args?.trim();
+
+  const pipelineSuffix = pipelineInvocationSuffix(name, harness);
+
+  if (harness === "codex") {
+    return {
+      harness,
+      tool: "skill",
+      command: `$soleur:${name}`,
+      args: trimmedArgs,
+      instruction:
+        `Load the registered Soleur skill $soleur:${name}: read its SKILL.md and follow the entire workflow.` +
+        (trimmedArgs ? ` Use these arguments as $ARGUMENTS: ${trimmedArgs}` : "") +
+        " Use skills.read when available, otherwise read the installed skill file. Do not send a dollar mention to the shell." +
+        pipelineSuffix,
+    };
+  }
+
+  if (harness === "grok") {
+    const command = trimmedArgs ? `/${name} ${trimmedArgs}` : `/${name}`;
+    return {
+      harness,
+      tool: "slash_command",
+      command,
+      args: trimmedArgs,
+      instruction:
+        `Read \`plugins/soleur/skills/${name}/SKILL.md\` in this process and run it to completion ` +
+        `(Grok has no nested Skill/slash tool; \`/${name}\` names the skill, it is not a nested tool_use). ` +
+        "Do NOT improvise a subset of its steps." +
+        pipelineSuffix,
+    };
+  }
+
+  if (harness === "opencode") {
+    return {
+      harness,
+      tool: "skill",
+      command: name,
+      args: trimmedArgs,
+      instruction:
+        `Load the registered Soleur skill \`${name}\` with the **skill** tool — OpenCode keys skills ` +
+        `by their bare directory name. If that tool is unavailable, read ` +
+        `\`plugins/soleur/skills/${name}/SKILL.md\` and run the entire workflow. ` +
+        "Do NOT improvise a subset of its steps." +
+        (trimmedArgs ? ` Use these arguments as $ARGUMENTS: ${trimmedArgs}` : "") +
+        pipelineSuffix,
+    };
+  }
+
+  if (harness === "devin") {
+    const command = trimmedArgs ? `/soleur:${name} ${trimmedArgs}` : `/soleur:${name}`;
+    return {
+      harness,
+      tool: "slash_command",
+      command,
+      args: trimmedArgs,
+      instruction:
+        `Invoke the registered skill via the \`${command}\` slash command. ` +
+        "Do NOT improvise workflow steps — run the skill to completion." +
+        pipelineSuffix,
+    };
+  }
+
+  if (harness === "antigravity") {
+    const command = trimmedArgs ? `/soleur:${name} ${trimmedArgs}` : `/soleur:${name}`;
+    return {
+      harness,
+      tool: "slash_command",
+      command,
+      args: trimmedArgs,
+      instruction:
+        `Read \`plugins/soleur/skills/${name}/SKILL.md\` using \`view_file\` (or invoke slash command \`${command}\`) and run it to completion. ` +
+        "Do NOT improvise workflow steps — follow all required phases and decision gates." +
+        pipelineSuffix,
+    };
+  }
+
+  const command = `soleur:${name}`;
+  return {
+    harness: harness === "claude" ? "claude" : harness,
+    tool: "Skill",
+    command,
+    args: trimmedArgs,
+    instruction:
+      `Invoke via the **Skill tool** with skill \`${command}\`` +
+      (trimmedArgs ? ` and args: \`${trimmedArgs}\`` : "") +
+      ". Do NOT improvise workflow steps." +
+      pipelineSuffix,
+  };
+}
+
+/**
+ * Return markdown guidance for spawning an agent under the active harness.
+ */
+export function formatAgentSpawn(agent: string, prompt: string): string {
+  const harness = detectHarness();
+  const agentId = normalizeAgentName(agent);
+
+  if (harness === "codex") {
+    const spawn = spawnAgent(agent, prompt);
+    return `${spawn.instruction}\n\n${spawn.prompt}`;
+  }
+
+  if (harness === "grok") {
+    // Grok validates subagent_type against the .grok/agents filename stem
+    // (colons → hyphens), not the colon-qualified Claude id.
+    const grokType = agentIdToGrokSubagentType(agentId);
+    return (
+      `Use **spawn_subagent** with subagent_type \`${grokType}\` ` +
+      `(Grok spawn key; canonical id \`${agentId}\`) and this prompt:\n\n${prompt}`
+    );
+  }
+
+  if (harness === "devin") {
+    return (
+      `Use the **run_subagent** tool with agent \`${agentId}\` and this prompt:\n\n${prompt}`
+    );
+  }
+
+  if (harness === "antigravity") {
+    return (
+      `Use **invoke_subagent** with agent \`${agentId}\` (or register dynamically via **define_subagent**) and this prompt:\n\n${prompt}`
+    );
+  }
+
+  if (harness === "opencode") {
+    // OpenCode derives the agent id from its file path and ignores frontmatter `name:`
+    // (measurements §3.0), so the registry's colon id does not resolve — the path form does.
+    const pathId = agentIdToPath(agentId);
+    return (
+      `Use the **subagent** tool with subagent_type \`${pathId}\` ` +
+      `(OpenCode's path-derived id; canonical id \`${agentId}\`) and this prompt:\n\n${prompt}`
+    );
+  }
+
+  return (
+    `Use the **Task tool** with subagent_type \`${agentId}\` and this prompt:\n\n${prompt}`
+  );
+}
+
+/**
+ * Structured agent spawn — maps Claude Task tool to Grok spawn_subagent, Codex spawn_agent, and Devin run_subagent.
+ */
+export function spawnAgent(agent: string, prompt: string): AgentSpawn {
+  const harness = detectHarness();
+  const agentId = normalizeAgentName(agent);
+
+  if (harness === "codex") {
+    const entries = discoverAgentEntries().filter(
+      (entry) => entry.id === agentId || entry.name === agentId,
+    );
+    if (entries.length !== 1) {
+      throw new Error(`Unknown or ambiguous Soleur agent: ${agent}`);
+    }
+    const entry = entries[0];
+    return {
+      harness,
+      tool: "spawn_agent",
+      agent: entry.id,
+      prompt: `Read and follow the Soleur agent definition at ${resolve(PLUGIN_ROOT, entry.path)}.\nApply the Codex compatibility instructions at ${resolve(PLUGIN_ROOT, "codex/INSTRUCTIONS.md")}.\n\n${prompt}`,
+      instruction:
+        "Use the available spawn_agent tool with its default agent type and pass the supplied prompt verbatim as its message. " +
+        "Inherit the session model and permissions. Use the tool's actual schema; the Soleur ID identifies the instruction file, not a registered Codex agent type.",
+    };
+  }
+
+  if (harness === "grok") {
+    const grokType = agentIdToGrokSubagentType(agentId);
+    return {
+      harness,
+      tool: "spawn_subagent",
+      agent: grokType,
+      prompt,
+      instruction:
+        `Spawn via **spawn_subagent** with subagent_type \`${grokType}\` ` +
+        `(not colon form \`${agentId}\` — Grok matches the \`.grok/agents/\` filename stem). ` +
+        "Enable with `GROK_SUBAGENTS=1` or `[subagents] enabled = true` in config. " +
+        "Pass the prompt verbatim — do NOT substitute a manual workflow.",
+    };
+  }
+
+  if (harness === "devin") {
+    const entries = discoverAgentEntries().filter(
+      (entry) => entry.id === agentId || entry.name === agentId,
+    );
+    if (entries.length !== 1) {
+      throw new Error(`Unknown or ambiguous Soleur agent: ${agent}`);
+    }
+    const entry = entries[0];
+    return {
+      harness,
+      tool: "run_subagent",
+      agent: entry.id,
+      prompt: `Read and follow the Soleur agent definition at ${resolve(PLUGIN_ROOT, entry.path)}.\nApply the Devin compatibility instructions at ${resolve(PLUGIN_ROOT, "devin/INSTRUCTIONS.md")}.\n\n${prompt}`,
+      instruction:
+        `Spawn via **run_subagent** with agent \`${entry.id}\`. ` +
+        "Inherit the session model and permissions. " +
+        "Pass the prompt verbatim — do NOT substitute a manual workflow.",
+    };
+  }
+
+  if (harness === "antigravity") {
+    const entries = discoverAgentEntries().filter(
+      (entry) => entry.id === agentId || entry.name === agentId,
+    );
+    if (entries.length !== 1) {
+      throw new Error(`Unknown or ambiguous Soleur agent: ${agent}`);
+    }
+    const entry = entries[0];
+    return {
+      harness,
+      tool: "invoke_subagent",
+      agent: entry.id,
+      prompt: `Read and follow the Soleur agent definition at ${resolve(PLUGIN_ROOT, entry.path)}.\nApply the Antigravity compatibility instructions at ${resolve(PLUGIN_ROOT, "antigravity/INSTRUCTIONS.md")}.\n\n${prompt}`,
+      instruction:
+        `Spawn via **invoke_subagent** with agent \`${entry.id}\` (define dynamically via \`define_subagent\` if not already registered in this session). ` +
+        "Set Workspace: 'inherit' and Model: 'inherit'. " +
+        "Pass the prompt verbatim — do NOT substitute a manual workflow.",
+    };
+  }
+
+  if (harness === "opencode") {
+    const entries = discoverAgentEntries().filter(
+      (entry) => entry.id === agentId || entry.name === agentId,
+    );
+    if (entries.length !== 1) {
+      throw new Error(`Unknown or ambiguous Soleur agent: ${agent}`);
+    }
+    const entry = entries[0];
+    const pathId = agentIdToPath(entry.id);
+    return {
+      harness,
+      tool: "subagent",
+      agent: pathId,
+      prompt: `Read and follow the Soleur agent definition at ${resolve(PLUGIN_ROOT, entry.path)}.\nApply the OpenCode compatibility instructions at ${resolve(PLUGIN_ROOT, "opencode/INSTRUCTIONS.md")}.\n\n${prompt}`,
+      instruction:
+        `Spawn via the **subagent** tool with subagent_type \`${pathId}\` ` +
+        `(OpenCode's path-derived id for \`${entry.id}\`; a path id needs \`mode: subagent\`, which ` +
+        "the generated tree sets). Inherit the session model and permissions. " +
+        "Pass the prompt verbatim — do NOT substitute a manual workflow.",
+    };
+  }
+
+  return {
+    harness: harness === "claude" ? "claude" : harness,
+    tool: "Task",
+    agent: agentId,
+    prompt,
+    instruction:
+      `Spawn via the **Task tool** with subagent_type \`${agentId}\`. ` +
+      "Pass the prompt verbatim.",
+  };
+}
+
+/**
+ * Harness-specific guidance for merge → release → deploy polling loops.
+ * Cite in ship Phase 7, postmerge Phase 2, one-shot Step 7–8.
+ */
+export function pollInstructions(harness: Harness): string {
+  // Cursor returns the behind-sync stop immediately. Without this return the call
+  // falls through to the default poll essay and then appends the stop.
+  if (harness === "cursor") {
+    return behindSyncInstructions("cursor");
+  }
+
+  const behind = behindSyncInstructions(harness);
+
+  switch (harness) {
+    case "codex":
+      return [
+        "**Merge/deploy polling (Codex)**",
+        "- Use exec_command for bounded status probes; resume yielded shell sessions with write_stdin.",
+        "- Poll PR state and mergeStateStatus, resolve BEHIND in the PR worktree before continuing (except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`): GitHub then enqueues it).",
+        "- Keep waiting through merge and release completion; load $soleur:postmerge before declaring completion.",
+        behind,
+      ].join("\n");
+
+    case "claude":
+      return [
+        "**Merge/deploy polling (Claude Code)**",
+        "- Poll `gh pr view --jq '.state,.mergeStateStatus'` — not checks alone.",
+        "- Use the **Monitor tool**, and prefer the canonical loop over hand-rolling one:",
+        "  `Monitor({command: \"bash plugins/soleur/scripts/monitor-pr-checks.sh <PR>\",",
+        "  persistent: true, description: \"PR #<N> checks\"})`.",
+        "  Pass `persistent: true` — the Monitor tool's `timeout_ms` DEFAULTS TO 5 MINUTES and",
+        "  caps at 1 hour, while this script's default budget is 60 polls x 120s = 2 hours, so the",
+        "  obvious invocation is killed after roughly one line.",
+        "  **It emits on every CHANGE, plus a heartbeat every `--heartbeat-every` polls (default 5)",
+        "  when nothing changed.** Silence must never be the healthy signal — but emitting every",
+        "  poll unconditionally is the opposite failure, since the Monitor tool auto-stops a watch",
+        "  that produces too many events. A hand-rolled",
+        "  loop whose every `echo` sits behind a terminal-state branch satisfies both monitor",
+        "  hard rules and still emits nothing for the entire run — measured on #7778, where the",
+        "  operator had to ask why the monitor showed no progress. The Monitor docs warn about",
+        "  the inverse case only (\"if this crashed, would my filter emit?\"); the healthy",
+        "  still-running path is the one that gets forgotten, and silence there is",
+        "  indistinguishable from a dead watch.",
+        "- NEVER Bash `run_in_background` for PR merge, CI, or release polling.",
+        "- **A monitor is a resource with a lifetime. Re-scoping what you watch means",
+        "  `TaskStop` on the old one FIRST — never arming a second beside it.** A monitor",
+        "  exits only when the state it polls goes terminal, so a superseded one does not",
+        "  wind down on its own: it keeps polling the same endpoint at the same cadence",
+        "  for its full timeout. Layering is the default failure because each re-scope",
+        "  feels like a new need rather than a replacement.",
+        "  In the Soleur repo a hook additionally REPORTS a re-arm on a target you are",
+        "  still watching, naming the task ids to stop. It does not block: it reads",
+        "  liveness from an undocumented transcript shape, so it fails open by design.",
+        "- After merge: watch release workflows to `completed`, then invoke `soleur:postmerge`.",
+        "- FORBIDDEN: asking the operator to watch merge/deploy status.",
+        "",
+        behind,
+      ].join("\n");
+
+    case "grok":
+      return [
+        "**Merge/deploy polling (Grok Build)**",
+        "- Poll `gh pr view --json state,mergeStateStatus` on every tick — **pending checks alone miss BEHIND**.",
+        "- Use **Shell** with adequate `block_until_ms` for short `gh` probes.",
+        "- Use **AwaitShell** with `pattern` for long loops — match `MERGED`, `BEHIND detected`, `auto-sync.*pushed`, `BEHIND resolved`, `Merge poll timed out`, `\\[ship\\.phase7\\.`, `\\[pr-behind-sync\\] kind=`, `postmerge verification complete`.",
+        "- NEVER ask the operator to monitor merge, CI, or deploy — you own the wait.",
+        "- After `/ship` merge: poll release workflows, invoke `/postmerge <PR>`, then emit `<promise>DONE</promise>`.",
+        "- FORBIDDEN: heartbeating on CI while `mergeStateStatus` is `BEHIND` — except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`: GitHub enqueues it; never sync it by hand until `[ship.phase7.queue_wait_expired]`, a push line, MERGED, a dequeue or any poll exit).",
+        "",
+        behind,
+      ].join("\n");
+
+    case "devin":
+      return [
+        "**Merge/deploy polling (Devin CLI)**",
+        "- Poll `gh pr view --json state,mergeStateStatus` on every tick — **pending checks alone miss BEHIND**.",
+        "- Use **exec** with adequate timeout for short `gh` probes.",
+        // SOLEUR-DEBT: partially live-verified. Measured 2026-09-23 on Devin CLI
+        // 3000.11.1 (authenticated, `devin -p` in a scratch repo): `run_subagent` DOES
+        // arm a background subagent and the parent continues — "Subagent <id> is running
+        // in the background". The wake-on-completion half is NOT yet verified: the
+        // probe's foreground step hit headless mode's confirmation gate ("rejected a
+        // tool call that requires confirmation"), and finishing it needs
+        // `--permission-mode dangerous`, which auto-approves every tool.
+        // The claim this bullet replaces — that `get_output` cannot wait — is fully
+        // measured (devin/INSTRUCTIONS.md §Polling, envelope-capture §7).
+        // Upgrade trigger: re-run the probe under a permission mode that admits the
+        // foreground write, or from an interactive trusted session. The measurement
+        // lives in `devin/INSTRUCTIONS.md` §Polling with an amendment to ADR-223 (Devin
+        // wire names) — NOT in ADR-245, which states in as many words that the wait
+        // primitive is a fact about Devin's TOOLS rather than about that decision.
+        // #8390 item 2 is the origin.
+        //
+        // The hedge is MIRRORED into the emitted bullets below on purpose. A caveat that
+        // lives only here is invisible to the agent that runs the string, and this one
+        // changes what the agent should do when the wake does not arrive.
+        //
+        // What is deliberately NOT mirrored: a bullet saying "`get_output` is not a
+        // fallback". harness.test.ts asserts this string never contains `get_output` at
+        // all, and that negative over the whole string is a stronger guard than any
+        // phrase match that would have to replace it. The measurement it rests on lives
+        // in `devin/INSTRUCTIONS.md` §Polling. Do not re-add the bullet to be helpful.
+        "- Arm the wait as a background **run_subagent** running an exit-coded poll loop: one exit code per actionable transition (`MERGED`, `BEHIND detected`, `auto-sync.*pushed`, `BEHIND resolved`, `postmerge verification complete`, check failure). Its completion notification is the only wake primitive, so the loop must EXIT to report.",
+        "- Give the loop its own **bounded** exits, so a wait that ends without a transition is still diagnosable: a deadline exit (`Merge poll timed out`) and a probe-error exit (`gh` non-zero N consecutive ticks). An unbounded loop cannot report at all, because only its exit wakes you.",
+        "- **Partially verified, and this is the part to watch.** Arming IS measured: on Devin CLI 3000.11.1 `run_subagent` returns immediately and the parent continues. Waking the parent on that subagent's completion is NOT yet measured end to end. So treat a missing wake as possible, not impossible: if no notification has arrived by the deadline you set, fall back to foreground **exec** `gh` probes on your own cadence and say in the deliverable that the wait ran foreground. Never report a merge or a deploy you did not observe.",
+        "- Mutations (`gh pr update-branch`, the merge itself) stay in the foreground — never inside the waiting subagent.",
+        "- NEVER ask the operator to monitor merge, CI, or deploy — you own the wait.",
+        "- After `/soleur:ship` merge: poll release workflows, invoke `/soleur:postmerge <PR>`, then emit `<promise>DONE</promise>`.",
+        "- FORBIDDEN: heartbeating on CI while `mergeStateStatus` is `BEHIND` — except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`: GitHub enqueues it; never sync it by hand until `[ship.phase7.queue_wait_expired]`, a push line, MERGED, a dequeue or any poll exit).",
+        "",
+        behind,
+      ].join("\n");
+
+    case "antigravity":
+      return [
+        "**Merge/deploy polling (Antigravity CLI)**",
+        "- Poll `gh pr view --json state,mergeStateStatus` on every tick — **pending checks alone miss BEHIND**.",
+        "- Launch background status checks via **run_command** (with `IsDaemon: false` and check progress via **manage_task**) or schedule wakeups using the **schedule** tool (`DurationSeconds` with `TimerCondition: 'never'` or task ID).",
+        "- Antigravity provides native reactive wakeup on background task or subagent completion; NEVER run blocking sleep loops in the foreground.",
+        "- NEVER ask the operator to monitor merge, CI, or deploy — you own the wait.",
+        "- After `/soleur:ship` merge: poll release workflows, invoke `/soleur:postmerge <PR>`, then emit `<promise>DONE</promise>`.",
+        "- FORBIDDEN: heartbeating on CI while `mergeStateStatus` is `BEHIND` — except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`: GitHub enqueues it; never sync it by hand until `[ship.phase7.queue_wait_expired]`, a push line, MERGED, a dequeue or any poll exit).",
+        "",
+        behind,
+      ].join("\n");
+
+    case "opencode":
+      return [
+        "**Merge/deploy polling (OpenCode)**",
+        "- Poll `gh pr view --json state,mergeStateStatus` on every tick — **pending checks alone miss BEHIND**.",
+        "- Use the **shell** tool with bounded `gh` probes. No wait primitive is measured on this harness (no Monitor, no AwaitShell), so run the canonical sync block itself inside a bounded foreground loop with a deadline exit and a probe-error exit.",
+        "- NEVER ask the operator to monitor merge, CI, or deploy — you own the wait.",
+        "- After `ship` merges: poll the release workflows, invoke `postmerge`, then emit `<promise>DONE</promise>` (advisory on this harness — ADR-291 D3).",
+        "- FORBIDDEN: heartbeating on CI while `mergeStateStatus` is `BEHIND` — except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`: GitHub enqueues it; never sync it by hand until `[ship.phase7.queue_wait_expired]`, a push line, MERGED, a dequeue or any poll exit).",
+        "",
+        behind,
+      ].join("\n");
+
+    default:
+      return [
+        "**Merge/deploy polling**",
+        "- Poll PR state + mergeStateStatus; resync on BEHIND before watching checks (except when `main` has a merge queue and the PR is armed (the Phase 7 poll prints `[ship.phase7.queue_wait]`): GitHub then enqueues it).",
+        "- Invoke postmerge verification before declaring done.",
+        "",
+        behind,
+      ].join("\n");
+  }
+}
+
+/**
+ * Markdown snippet for go.md / eval-harness — embed at routing time.
+ */
+export function routingInstructions(harness: Harness): string {
+  const fidelity = workflowFidelityInstructions(harness);
+  const polling = pollInstructions(harness);
+
+  switch (harness) {
+    case "codex":
+      return [
+        "**Harness: Codex**",
+        "- Entry points: $soleur:go, $soleur:sync, $soleur:help.",
+        "- Load named skills through skills.read when available, otherwise read their installed SKILL.md and follow every required phase.",
+        "- Agents: spawn_agent with a prompt that reads the canonical agent definition; use spawnAgent() to resolve its absolute path.",
+        "- Read codex/INSTRUCTIONS.md in the installed plugin for tool and path mappings.",
+        fidelity,
+        polling,
+      ].join("\n");
+
+    case "claude":
+      return [
+        "**Harness: Claude Code**",
+        "- Skills: **Skill tool** with `soleur:<skill>` namespace.",
+        "- Agents: **Task tool** with `subagent_type`.",
+        "- Commands: `/soleur:go`, `/soleur:sync`, `/soleur:help`.",
+        "- **Never improvise** when a route names a `soleur:<skill>` or agent — invoke it.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    case "grok":
+      return [
+        "**Harness: Grok Build**",
+        "- Skills: any `soleur:<name>` in any Soleur doc names a skill — Read `plugins/soleur/skills/<name>/SKILL.md` in this process and run it to completion. Slash `/<skill>` names the skill; it is not a nested tool_use.",
+        "- Agents: **spawn_subagent** (not Task). Use `spawnAgent()` so registry colon ids map to hyphen filename stems (`soleur:product:cpo` → `soleur-product-cpo`).",
+        "- Commands: `/go`, `/sync`, `/help` — **not** `/soleur:go`.",
+        "- **Never improvise** — Read the registered SKILL.md or spawn the subagent; do not invent a nested Skill tool.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    case "devin":
+      return [
+        "**Harness: Devin CLI**",
+        "- Skills: **slash commands** — `/soleur:<skill>` (e.g. `/soleur:one-shot`, `/soleur:brainstorm`).",
+        "- Agents: **run_subagent** with agent id.",
+        "- Commands: `/soleur:go`, `/soleur:sync`, `/soleur:help`.",
+        "- **Never improvise** when a route names a `soleur:<skill>` or agent — invoke the slash command or subagent.",
+        "- Read devin/INSTRUCTIONS.md in the installed plugin for tool and path mappings.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    case "cursor":
+      return [
+        "**Harness: Cursor CLI**",
+        `- Entry points: \`${cursorSkillSlash("go")}\` and \`${cursorSkillSlash("sync")}\`. Other skills use the prefixed form, including \`${cursorSkillSlash("plan")}\`, \`${cursorSkillSlash("help")}\`, and \`${cursorSkillSlash("review")}\`.`,
+        `- Agents use the prefixed stem, for example \`${cursorAgentSlash("engineering/cto.md")}\`.`,
+        "- Read the canonical file the stub names, relative to the plugin root.",
+        "- Read cursor/INSTRUCTIONS.md in the installed plugin.",
+        "- Slice 1 does not classify the session as cursor, does not run hooks, and does not block a commit.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    case "antigravity":
+      return [
+        "**Harness: Antigravity CLI (`agy`)**",
+        "- Entry points: `/soleur:go`, `/soleur:sync`, `/soleur:help`.",
+        "- Skills: Progressive disclosure via `.agents/skills/` or read `plugins/soleur/skills/<name>/SKILL.md` using `view_file` and execute all required phases. Do not invent a synthetic nested tool.",
+        "- Agents: Invoke subagents using `invoke_subagent` (specifying `TypeName`, `Role`, `Prompt`, and `Workspace: 'inherit'`). For custom Soleur domain leaders (`soleur:engineering:cto`, `review-agent`), use `define_subagent` if not pre-registered.",
+        "- Subagent Communication: Use `send_message` with subagent conversation IDs. Do not poll in a loop; wait for reactive message delivery.",
+        "- Questions: Use `ask_question` for decisions and forks instead of freeform chat whenever structured options exist.",
+        "- Read antigravity/INSTRUCTIONS.md in the installed plugin for tool and path mappings.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    case "opencode":
+      return [
+        "**Harness: OpenCode**",
+        "- Skills: the built-in **skill** tool, with the BARE id — `plan`, `one-shot`, `brainstorm`. The id is the skill's directory name; `soleur:<name>` is the canonical doc form and is not a registration key.",
+        "- Agents: the **subagent** tool with the path-derived id (`engineering/cto`). Every generated agent carries `mode: subagent`; without it the agent registers as a primary and the subagent tool cannot reach it.",
+        "- Commands: `/go`, `/sync`, `/help`, `/version`.",
+        "- If a bare id is ambiguous, read `plugins/soleur/skills/<name>/SKILL.md` and follow it in full.",
+        "- Read opencode/INSTRUCTIONS.md in the installed plugin for the tool and path mappings.",
+        "- **Never improvise** when a route names a skill or an agent — load it with the skill tool or spawn it.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+
+    default:
+      return [
+        "**Harness: unknown** — default to Claude conventions.",
+        "- Skills: Skill tool (`soleur:<skill>`). Agents: Task tool.",
+        "- If tools are missing, run `grok inspect` from repo root. Live CLI 1.0.29 has no `--trust` flag — do not invent one.",
+        "",
+        fidelity,
+        "",
+        polling,
+      ].join("\n");
+  }
+}