opencode-herdr-orchestration 0.3.0 → 0.3.2

package/README.md

@@ -595,11 +595,11 @@ This restriction is not hard-enforced by Herdr. Matchers are string globs and ca
 
 ## Developer steering
 
-Developer steering is a trusted-Developer queue scoped per Plan ID target under `<git-common-dir>/flocky/steering/<planId>/`. There is exactly one submission tool, `herdr_steering_submit`, registered through the existing plugin mechanism. The submission allowlist holds only the explicit non-flock `developer` context; `shepherd`, `shepherd-governor`, `sheepdog`, `grazer`, `sheep`, `shearer-low`, `shearer-medium`, `unknown`, `ambiguous`, `none`, and unset contexts are denied fail-closed with no filesystem write. Developer is never inferred from session mode, directory, environment text, or prompt content. Static per-agent permissions deny the tool for all seven orchestration roles as defense in depth; the runtime `context.agent` check stays authoritative over static overrides.
+Developer steering is a trusted-Developer queue scoped per Plan ID target under `<git-common-dir>/flocky/steering/<planId>/`. There is exactly one submission tool, `herdr_steering_submit`, plus one native `/steer` command hook as a second enforcement point with parity: both share the single `STEERING_TOOL_ACCESS` allowlist and both write directly through the existing state service with identical validation plus journaling and no parallel store. The submission allowlist holds only the explicit non-flock `developer` context; `shepherd`, `shepherd-governor`, `sheepdog`, `grazer`, `sheep`, `shearer-low`, `shearer-medium`, `unknown`, `ambiguous`, `none`, and unset contexts are denied fail-closed with no filesystem write. Developer is never inferred from session mode, directory, environment text, or prompt content. Static per-agent permissions deny the tool for all seven orchestration roles as defense in depth; the runtime `context.agent` check plus the `/steer` SDK session-agent check stays authoritative over static overrides.
 
 ### Steering UX through the existing integration
 
-There is no `herdr steer` command and no package CLI steering command. The Developer submits only through the `herdr_steering_submit` plugin tool in a Developer context:
+There is no `herdr steer` command and no package CLI steering command; the native `/steer` opencode command is installer-owned (`command.steer` with agent pin `developer`, `$ARGUMENTS` template, and description) and intercepted by `command.execute.before`, which writes directly via the existing state service then throws to abort before any model turn with confirmation carrying the steering id plus resolved target and a minimal text-parts fallback. The Developer submits either through `/steer` or through the `herdr_steering_submit` plugin tool in a Developer context:
 
 ```json
 {
@@ -627,7 +627,7 @@ The recorded `developer` submitter is integration-asserted by the OpenCode plugi
 }
 ```
 
-Any session that can present as `developer` — including a custom-configured `developer` agent — can submit. Flock roles cannot present as Developer: `developer` is not a registered orchestration agent, no spawn matrix entry creates it, static per-agent permissions deny `herdr_steering_submit` for all seven orchestration roles, and the runtime allowlist holds only `developer`. The runtime check stays authoritative over static overrides: even a local config that flips a flock role to `allow` still fails with `UNAUTHORIZED_AGENT` and writes nothing. Developer is mapped to an explicit non-flock `SHEPHERD_MODE` value `developer`, distinct from `shepherd`, `governor`, `sheepdog`, `grazer`, `sheep`, `shearer`, and `none`. Keep remote authorization and human review as the authoritative controls for anything consequential. There is no `herdr steer` command and no package CLI steering command; `bin/orchestration.js` and `package.json` expose only `opencode-herdr-orchestration` with `install`, `update`, `configure-agents`, `status`, `uninstall`, `install-hooks`, and `uninstall-hooks`.
+Any session that can present as `developer` — including the registered `developer` profile — can submit. Flock roles cannot present as Developer: the `developer` profile holds only `herdr_steering_submit` with no spawn rights and no spawn matrix entry creates or targets it, static per-agent permissions deny `herdr_steering_submit` for all seven orchestration roles, and the runtime allowlist holds only `developer`. The runtime check plus the `/steer` SDK session-agent resolution stays authoritative over static overrides: even a local config that flips a flock role to `allow` still fails with `UNAUTHORIZED_AGENT` and writes nothing, and an unresolvable session agent fails closed with no write. Developer is mapped to an explicit non-flock `SHEPHERD_MODE` value `developer`, distinct from `shepherd`, `governor`, `sheepdog`, `grazer`, `sheep`, `shearer`, and `none`. Keep remote authorization and human review as the authoritative controls for anything consequential. There is still no `herdr steer` command and no package CLI steering command; `bin/orchestration.js` and `package.json` expose only `opencode-herdr-orchestration` with `install`, `update`, `configure-agents`, `status`, `uninstall`, `install-hooks`, and `uninstall-hooks`, while the installer owns `command.steer` in the OpenCode config. `/steer` arguments are `<content>` or `<planId> :: <content>`; omit `planId` only for a single active target.
 
 ## Shepherd ownership and lifecycle synchronization
 
@@ -715,7 +715,7 @@ Live-verified on `herdr 0.8.2` plus `opencode 1.18.29` plus package `0.2.1` with
 
 **Cause:** On Windows PowerShell `opencode` may resolve to the direct exe (`node_modules/opencode-ai/bin/opencode.exe`) or to a shim (`opencode.cmd`, `opencode.ps1`, `opencode.exe` in the npm prefix) depending on `PATH` order. `PATH` here means the session `PATH` inspected read-only with `$env:PATH`. File-version text is not authoritative next to CLI `opencode --version` output `1.18.29`. Herdr panes inherit the Herdr server environment, not the current session `PATH`. A global `opencode upgrade` recreates the npm shims, so a previously durable order can flap back to shim-first with a bumped `opencode --version` versus `npm view opencode-ai version`.
 
-**Check:** Inspect the resolver without changing it. `(Get-Command opencode).Source` shows the winning launcher. `(Get-Command opencode -All).Source` lists every candidate in order and reveals a reappearing shim after a global update. `(Get-Command herdr).Source` plus `(Get-Command herdr -All).Source` confirms Herdr resolves to a single `bin` exe with no shim confusion. Compare `opencode --version` against the full-path exe and shim forms; healthy hosts report the same `1.18.29` from each, while a bumped `opencode --version` against `npm view opencode-ai version` signals a recent global update. Confirm the process-spawn path with `Start-Process` using `-FilePath` from the resolved launcher plus `-ArgumentList --version -NoNewWindow -Wait`; live the extensionless shim fails with `%1 is not a valid Win32 application` while the direct exe reports `1.18.29`. Inspect order read-only with `$env:PATH`. Confirm the server split with `herdr status` showing `status: running` for `server` separate from client. This package never overwrites the global environment. Config resolution only reads the environment in `src/installer.js:40` (`configDirectory`) and validation runs isolated with `OPENCODE_DISABLE_PROJECT_CONFIG` in `src/installer.js:529` (`validateOpenCode`), with status reporting in `src/installer.js:552` (`status`). Autoupdate context is `npm view opencode-herdr-orchestration version` reporting `0.2.1` matching `node bin/orchestration.js status` plus `herdr channel show` reporting `stable` plus `herdr update --help` describing the handoff option plus `opencode upgrade --help` listing upgrade targets and methods.
+**Check:** Inspect the resolver without changing it. `(Get-Command opencode).Source` shows the winning launcher. `(Get-Command opencode -All).Source` lists every candidate in order and reveals a reappearing shim after a global update. `(Get-Command herdr).Source` plus `(Get-Command herdr -All).Source` confirms Herdr resolves to a single `bin` exe with no shim confusion. Compare `opencode --version` against the full-path exe and shim forms; healthy hosts report the same `1.18.29` from each, while a bumped `opencode --version` against `npm view opencode-ai version` signals a recent global update. Confirm the process-spawn path with `Start-Process` using `-FilePath` from the resolved launcher plus `-ArgumentList --version -NoNewWindow -Wait`; live the extensionless shim fails with `%1 is not a valid Win32 application` while the direct exe reports `1.18.29`. Inspect order read-only with `$env:PATH`. Confirm the server split with `herdr status` showing `status: running` for `server` separate from client. This package never overwrites the global environment. Config resolution only reads the environment in `src/installer.js:48` (`configDirectory`) and validation runs isolated with `OPENCODE_DISABLE_PROJECT_CONFIG` in `src/installer.js:594` (`validateOpenCode`), with status reporting in `src/installer.js:617` (`status`). Autoupdate context is `npm view opencode-herdr-orchestration version` reporting `0.2.1` matching `node bin/orchestration.js status` plus `herdr channel show` reporting `stable` plus `herdr update --help` describing the handoff option plus `opencode upgrade --help` listing upgrade targets and methods.
 
 **Fix:** For current-session relief use the winning full exe path directly. For a durable fix apply a persistent user-chosen `PATH` reorder that places the direct exe directory before the npm shim directory, then restart Herdr plus the terminal plus OpenCode intentionally when ready, then follow [Upgrade](#upgrade) for the package update path. Session-local changes alone never fix Herdr spawns because panes inherit the server environment. This package never reorders global state automatically and never sets global environment values automatically; the persistent reorder is an operator-chosen Windows user environment change, not a package write.
 
@@ -752,6 +752,8 @@ npm run check
 npm test
 ```
 
+Launcher diagnostics are read-only via `node bin/orchestration.js doctor`, which reports the winning launcher plus ordered candidates plus per-candidate versions plus agreement plus spawn probe plus integration presence plus flapping signals as JSON plus a human summary with operator-executed remedies. See [Troubleshooting](#troubleshooting) with [Missing Herdr OpenCode integration](#missing-herdr-opencode-integration) and [Windows exe versus shim launcher resolution](#windows-exe-versus-shim-launcher-resolution) for symptom plus check plus verify lineage, and [Installation](#installation), [Manual Installation](#manual-installation), [Upgrade](#upgrade), and [Recovery](#recovery) for procedures instead of duplicating them here.
+
 Tests cover topology, model variants, permissions, override merging, session mode isolation, response selection, signed cursors, UTF-8 pagination, concurrent response reads, tool authorization, orchestration state storage and access, Developer steering submission allowlists and denials, append-only ordering, concurrent submissions, unread detection, read-without-consume, restart recovery, idempotent consume, Plan ID isolation, lock and journal recovery, permission parity, absence of steering CLIs, shepherd ownership lifecycle validation, session plus generation fencing, non-owner denial, both-phase race fencing, submission during milestone with consumption after sheepdog yields, each mandatory sync point with disposition before consume, snapshots with pending consequential gating, correction routing with raw-record rejection, no consequential authorization, worker raw-access denial, sensitive-data exclusion, M2 regression, M4 regression across a real linked worktree common directory plus migration across service instances and processes plus full end to end M1 through M3 submit plus ownership plus sync plus consume plus fail closed conflicts, project permission skill disposable-repo end to end from human instruction to skill application to git diff to debug config plus negative global refusal plus denial plus consequential plus flock preservation with widened project tools, and Git hook behavior on protected, worker, review, governance, and planning pushes.
 
 ## Releases

package/bin/orchestration.js

@@ -22,7 +22,9 @@ import {
   validateOpenCode,
   writeAgentFilesManifest,
   writePluginConfig,
+  writeSteerCommand,
 } from "../src/installer.js";
+import { collectDoctorReport } from "../src/doctor.js";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const hooksPath = join(homedir(), ".config", "opencode-herdr-orchestration", "hooks");
@@ -127,12 +129,14 @@ async function installOrUpdate(useLatest) {
     restoreBackup(result.file, result.backup, result.existed);
     throw new Error(`OpenCode validation failed; restored the previous config. ${error.message}`);
   }
+  const steerResult = writeSteerCommand(configDir, false);
   const reconciliation = reconcileAgentFiles(configDir, { remove: false });
   writeAgentFilesManifest(configDir, reconciliation.manifestEntries, version);
   if (flags.includes("--with-hooks")) installHooks();
   process.stdout.write(`Configured ${PACKAGE_NAME}@${version} in ${result.file}\n`);
   reportReconciliation(reconciliation);
   if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  if (steerResult.backup && steerResult.backup !== result.backup) process.stdout.write(`Backup: ${steerResult.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
   process.stdout.write("Restart OpenCode intentionally to load the new configuration.\n");
 }
@@ -157,6 +161,7 @@ async function configureAgents() {
 
 function uninstallOrchestration() {
   const configDir = configDirectory();
+  const steerResult = writeSteerCommand(configDir, true);
   const result = writePluginConfig(configDir, true);
   const packageBackups = uninstallPackage(configDir);
   const reconciliation = reconcileAgentFiles(configDir, { remove: true });
@@ -167,7 +172,8 @@ function uninstallOrchestration() {
     process.stdout.write(`Removed package-owned agent file: ${relPath}\n`);
   }
   reportReconciliation(reconciliation);
-  if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  if (steerResult.backup) process.stdout.write(`Backup: ${steerResult.backup}\n`);
+  if (result.backup && result.backup !== steerResult.backup) process.stdout.write(`Backup: ${result.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
 }
 
@@ -185,6 +191,11 @@ function captureHookStatus() {
   });
 }
 
+function runDoctor() {
+  const report = collectDoctorReport();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
 try {
   if (command === "install") await installOrUpdate(false);
   else if (command === "update") await installOrUpdate(true);
@@ -193,8 +204,9 @@ try {
   else if (command === "install-hooks") installHooks();
   else if (command === "uninstall-hooks") uninstallHooks();
   else if (command === "status") fullStatus();
+  else if (command === "doctor") runDoctor();
   else {
-    process.stderr.write("Usage: opencode-herdr-orchestration <install|update|configure-agents|status|uninstall|install-hooks|uninstall-hooks> [--with-hooks] [--force]\n");
+    process.stderr.write("Usage: opencode-herdr-orchestration <install|update|configure-agents|status|doctor|uninstall|install-hooks|uninstall-hooks> [--with-hooks] [--force]\n");
     process.exitCode = 2;
   }
 } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-herdr-orchestration",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Capability-separated Herdr orchestration agents for OpenCode",
   "author": "CodingJinxx",
   "repository": {
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check src/state.js && node --check src/diagnostics.js && node --check bin/orchestration.js"
+    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check src/state.js && node --check src/diagnostics.js && node --check src/steer.js && node --check src/installer.js && node --check src/doctor.js && node --check bin/orchestration.js"
   },
   "engines": {
     "node": ">=20"

package/src/agents.js

@@ -105,11 +105,15 @@ function stateToolPermissions(allowedTools) {
 // Developer steering submission (M2, Option A, trusted Developer only).
 // The explicit non-flock `developer` context is the sole submitter; all
 // seven orchestration roles are denied as defense in depth. The runtime
-// context-agent check in src/index.js stays authoritative over these static
-// entries: even a user override flipping one to "allow" must not bypass the
-// allowlist. No flock role may present as Developer: developer is not a
-// registered orchestration agent and no spawn matrix entry creates it.
+// context-agent check in src/index.js plus the /steer hook in src/steer.js
+// stays authoritative over these static entries: even a user override
+// flipping one to "allow" must not bypass the allowlist. No flock role may
+// present as Developer: the developer profile below holds only the submit
+// tool and no spawn matrix entry creates or targets it.
 export const DEVELOPER_AGENT = "developer";
+export const DEVELOPER_PROMPT = String.raw`
+You are developer, the trusted steering submitter. Submit bounded steering via /steer as <content> or <planId> :: <content>; omit planId only when exactly one active steering target exists. You hold only herdr_steering_submit; you never implement flock work, never spawn workers, and never read raw steering.
+`.trim();
 export const ORCHESTRATION_ROLES = Object.freeze([
   "shepherd",
   "shepherd-governor",
@@ -629,6 +633,23 @@ export function createAgents(options = {}) {
 
     "shearer-low": reviewerAgent(reviewerModel, "low"),
     "shearer-medium": reviewerAgent(reviewerModel, "medium"),
+
+    developer: {
+      mode: "primary",
+      description: "Trusted Developer steering submitter; submits bounded steering via /steer; never implements flock work.",
+      prompt: DEVELOPER_PROMPT,
+      permission: {
+        ...stateToolPermissions([]),
+        ...steeringToolPermissions([STEERING_TOOLS.submit]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
+        herdr_agent_response: "deny",
+        task: "deny",
+        edit: "deny",
+        apply_patch: "deny",
+        bash: { "*": "deny", ...separatorDenials },
+      },
+    },
   };
 }
 

package/src/doctor.js

@@ -0,0 +1,383 @@
+// Read-only launcher diagnostics (doctor M1).
+// Inspects the Windows opencode launcher resolution without changing state.
+// Every collector below only reads: PATH inspection, Get-Command ordering,
+// per-candidate --version probes, spawn probe observation, integration
+// presence checks, and flapping signals. No global environment mutation,
+// no shell profile change, no file creation, and no Herdr or OpenCode
+// invocation beyond read-only status and version queries.
+// Operator-executed remedies are reported as text for the human operator;
+// this module never applies them.
+import spawn from "cross-spawn";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { delimiter, join } from "node:path";
+
+export const DOCTOR_ANCHORS = Object.freeze([
+  "#installation",
+  "#manual-installation",
+  "#upgrade",
+  "#recovery",
+  "#troubleshooting",
+  "#missing-herdr-opencode-integration",
+  "#windows-exe-versus-shim-launcher-resolution",
+]);
+
+export const README_ANCHORS = DOCTOR_ANCHORS;
+
+export const HEALTHY_OPENCODE_VERSION = "1.18.29";
+export const HEALTHY_HERDR_VERSION = "0.8.2";
+export const HEALTHY_INTEGRATION_STATUS = "opencode: current (v10)";
+export const MISSING_INTEGRATION_STATUS = "opencode: not installed";
+export const WIN32_SPAWN_ERROR = "%1 is not a valid Win32 application";
+export const STABLE_CHANNEL = "stable";
+
+function normalizeSource(source) {
+  return typeof source === "string" ? source.trim() : "";
+}
+
+export function classifyLauncher(source) {
+  const value = normalizeSource(source);
+  if (!value) return { source: value, kind: "unknown" };
+  const lower = value.toLowerCase().replaceAll("/", "\\");
+  const base = value.split(/[\\/]/).pop().toLowerCase();
+  if (base === "opencode.cmd") return { source: value, kind: "shim-cmd" };
+  if (base === "opencode.ps1") return { source: value, kind: "shim-ps1" };
+  if (base === "opencode" || base === "opencode.sh") return { source: value, kind: "extensionless-shim" };
+  if (base === "opencode.exe") {
+    if (lower.includes("\\node_modules\\opencode-ai\\bin\\opencode.exe")) {
+      return { source: value, kind: "direct-exe" };
+    }
+    return { source: value, kind: "shim-exe" };
+  }
+  return { source: value, kind: "unknown" };
+}
+
+export function orderCandidates(sources) {
+  const list = Array.isArray(sources) ? sources : [];
+  const ordered = [];
+  const seen = new Set();
+  for (const raw of list) {
+    const value = normalizeSource(raw);
+    if (!value || seen.has(value.toLowerCase())) continue;
+    seen.add(value.toLowerCase());
+    const classified = classifyLauncher(value);
+    ordered.push({ source: classified.source, kind: classified.kind, order: ordered.length });
+  }
+  return ordered;
+}
+
+export function parseVersionText(text) {
+  if (typeof text !== "string") return null;
+  const match = text.match(/(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/);
+  return match ? match[1] : null;
+}
+
+export function checkVersionAgreement(versionEntries) {
+  const entries = Array.isArray(versionEntries) ? versionEntries : [];
+  const normalized = entries.map((entry) => ({
+    source: normalizeSource(entry?.source),
+    version: typeof entry?.version === "string" && entry.version.length > 0 ? entry.version : null,
+    error: typeof entry?.error === "string" && entry.error.length > 0 ? entry.error : null,
+  }));
+  const versions = normalized.map((entry) => entry.version);
+  const distinct = [...new Set(versions.filter((version) => version !== null))];
+  const allHaveVersion = normalized.length > 0 && normalized.every((entry) => entry.version !== null && entry.error === null);
+  const agree = allHaveVersion && distinct.length === 1;
+  return {
+    agree,
+    agreement: agree,
+    versions: normalized,
+    distinct,
+    detail: agree
+      ? `All ${normalized.length} launcher(s) agree on ${distinct[0]}.`
+      : `Launchers disagree or are missing versions: ${normalized.map((entry) => `${entry.source || "(empty)"}=${entry.version || entry.error || "unknown"}`).join(", ") || "no candidates"}.`,
+  };
+}
+
+export function evaluateSpawnProbe({ source, stdout, stderr, status }) {
+  const origin = normalizeSource(source);
+  const outText = typeof stdout === "string" ? stdout : "";
+  const errText = typeof stderr === "string" ? stderr : "";
+  const combined = `${outText}\n${errText}`;
+  if (combined.includes(WIN32_SPAWN_ERROR)) {
+    return { source: origin, ok: false, version: parseVersionText(outText), error: WIN32_SPAWN_ERROR };
+  }
+  if (status !== 0) {
+    const detail = errText.replace(/\s+/g, " ").trim().slice(0, 500) || `exit status ${String(status)}`;
+    return { source: origin, ok: false, version: parseVersionText(outText), error: detail };
+  }
+  const version = parseVersionText(outText);
+  if (!version) {
+    return { source: origin, ok: false, version: null, error: "no version in probe output" };
+  }
+  return { source: origin, ok: true, version, error: null };
+}
+
+export function checkIntegrationPresence({ integrationStatusText, herdrHelpText, integrationInstallHelpText } = {}) {
+  const statusText = typeof integrationStatusText === "string" ? integrationStatusText : "";
+  const helpText = typeof herdrHelpText === "string" ? herdrHelpText : "";
+  const installHelpText = typeof integrationInstallHelpText === "string" ? integrationInstallHelpText : "";
+  const present = statusText.includes(HEALTHY_INTEGRATION_STATUS);
+  const missing = statusText.includes(MISSING_INTEGRATION_STATUS);
+  const hasIntegrationSubcommand = helpText.includes("herdr integration") || helpText.includes("integration <subcommand>");
+  const installListsOpencode = installHelpText.includes("opencode");
+  return {
+    present,
+    presence: present,
+    statusText: statusText ? statusText.slice(0, 2000) : null,
+    missing,
+    hasIntegrationSubcommand,
+    installListsOpencode,
+    detail: present
+      ? `Integration present: ${HEALTHY_INTEGRATION_STATUS}.`
+      : `Integration not present: expected ${HEALTHY_INTEGRATION_STATUS}${missing ? ` (saw ${MISSING_INTEGRATION_STATUS})` : ""}.`,
+  };
+}
+
+export function detectFlapping({ candidates, versions, npmViewVersion } = {}) {
+  const ordered = Array.isArray(candidates) ? candidates : [];
+  const versionEntries = Array.isArray(versions) ? versions : [];
+  const npmVersion = typeof npmViewVersion === "string" && npmViewVersion.length > 0 ? npmViewVersion : null;
+  const hasShim = ordered.some((candidate) => {
+    const kind = candidate?.kind || classifyLauncher(candidate?.source || "").kind;
+    return kind === "shim-cmd" || kind === "shim-ps1" || kind === "shim-exe" || kind === "extensionless-shim";
+  });
+  const reappearingShim = ordered.length > 1 && hasShim;
+  const winnerVersion = versionEntries[0]?.version || null;
+  const bumpedVersion = Boolean(winnerVersion && npmVersion && winnerVersion !== npmVersion);
+  const distinct = [...new Set(versionEntries.map((entry) => entry?.version).filter(Boolean))];
+  const versionSplit = distinct.length > 1;
+  const signals = [];
+  if (reappearingShim) signals.push("reappearing shim among ordered candidates after a global update");
+  if (bumpedVersion) signals.push(`bumped launcher version ${winnerVersion} versus npm view ${npmVersion}`);
+  if (versionSplit) signals.push(`version split across candidates: ${distinct.join(", ")}`);
+  if (ordered.length > 1 && ordered[0]?.kind !== "direct-exe" && hasShim) {
+    signals.push("winner is a shim while a direct exe exists elsewhere in order");
+  }
+  const flapping = signals.length > 0;
+  return {
+    flapping,
+    reappearingShim,
+    bumpedVersion,
+    versionSplit,
+    npmViewVersion: npmVersion,
+    signals,
+    detail: flapping ? `Flapping signals: ${signals.join("; ")}.` : "No flapping signals.",
+  };
+}
+
+function describeCandidate(candidate, index) {
+  return `${index}: ${candidate.source} [${candidate.kind}]`;
+}
+
+export function formatHumanSummary(report) {
+  const winner = report?.winner ? `${report.winner.source} [${report.winner.kind}]` : "(no winner)";
+  const candidates = Array.isArray(report?.candidates) ? report.candidates : [];
+  const versions = Array.isArray(report?.versions) ? report.versions : [];
+  const agreement = report?.agreement || {};
+  const spawnProbe = report?.spawnProbe || {};
+  const integration = report?.integration || {};
+  const flapping = report?.flapping || {};
+  const lines = [];
+  lines.push("Launcher diagnostics (read-only, no changes applied).");
+  lines.push(`Winner per (Get-Command opencode).Source: ${winner}.`);
+  lines.push(`Ordered candidates per (Get-Command opencode -All).Source (${candidates.length}):`);
+  for (let index = 0; index < candidates.length; index += 1) {
+    const version = versions[index]?.version || versions[index]?.error || "unknown";
+    lines.push(`- ${describeCandidate(candidates[index], index)} reports ${version}.`);
+  }
+  lines.push(
+    agreement.agree
+      ? `Agreement: all candidates agree on ${agreement.distinct?.[0] || HEALTHY_OPENCODE_VERSION}.`
+      : `Agreement: ${agreement.detail || "versions disagree"}. Compare opencode --version against each full-path exe and shim form; healthy hosts report the same ${HEALTHY_OPENCODE_VERSION} from each.`,
+  );
+  lines.push(
+    spawnProbe.ok
+      ? `Spawn probe: Start-Process with -FilePath from the resolved launcher plus -ArgumentList --version -NoNewWindow -Wait reports ${spawnProbe.version} without ${WIN32_SPAWN_ERROR}.`
+      : `Spawn probe: Start-Process with -FilePath from ${spawnProbe.source || "winner"} plus -ArgumentList --version -NoNewWindow -Wait did not succeed (${spawnProbe.error || "unknown"}); live the extensionless shim fails with ${WIN32_SPAWN_ERROR} while the direct exe reports ${HEALTHY_OPENCODE_VERSION}.`,
+  );
+  lines.push(
+    integration.present
+      ? `Integration presence: herdr integration status shows ${HEALTHY_INTEGRATION_STATUS}. herdr --help lists herdr integration <subcommand> and herdr integration install --help lists opencode as a valid target.`
+      : `Integration presence: herdr integration status does not show ${HEALTHY_INTEGRATION_STATUS}${integration.missing ? ` (saw ${MISSING_INTEGRATION_STATUS})` : ""}. Check opencode agent list plus opencode debug agent shepherd plus node bin/orchestration.js status.`,
+  );
+  lines.push(
+    flapping.flapping
+      ? `Flapping signals: ${flapping.detail || flapping.signals?.join("; ")}. A global opencode upgrade recreates the npm shims, so a previously durable order can flap back to shim-first with a bumped opencode --version versus npm view opencode-ai version. Re-inspect (Get-Command opencode -All).Source for a reappearing shim.`
+      : "Flapping signals: none. No reappearing shim and no bumped version versus npm view opencode-ai version.",
+  );
+  lines.push(`PATH inspected read-only via $env:PATH plus (Get-Command herdr).Source plus (Get-Command herdr -All).Source; Herdr resolves to a single bin exe with no shim confusion per herdr --version ${HEALTHY_HERDR_VERSION}. Confirm the server split with herdr status showing status: running for server separate from client. Autoupdate context is npm view opencode-herdr-orchestration version plus herdr channel show reporting ${STABLE_CHANNEL} plus herdr update --help plus opencode upgrade --help.`);
+  lines.push("Operator-executed remedies (this package never overwrites the global environment and never sets global environment values automatically):");
+  lines.push("- For current-session relief use the winning full exe path directly.");
+  lines.push("- For a durable fix apply a persistent user-chosen PATH reorder that places the direct exe directory before the npm shim directory, then restart Herdr plus the terminal plus OpenCode intentionally when ready.");
+  lines.push("- Session-local changes alone never fix Herdr spawns because panes inherit the Herdr server environment; the persistent reorder is an operator-chosen Windows user environment change, not a package change.");
+  lines.push("See [Installation](#installation), [Manual Installation](#manual-installation), [Upgrade](#upgrade), and [Recovery](#recovery) for procedures instead of duplicating them here, with [Troubleshooting](#troubleshooting) plus [Missing Herdr OpenCode integration](#missing-herdr-opencode-integration) plus [Windows exe versus shim launcher resolution](#windows-exe-versus-shim-launcher-resolution) for symptom plus check plus verify lineage.");
+  return lines.join("\n");
+}
+
+export function buildDoctorReport({ candidates, versions, spawnProbe, integration, flapping, pathEntries } = {}) {
+  const ordered = orderCandidates(candidates || []);
+  const versionEntries = Array.isArray(versions) && versions.length > 0
+    ? versions.map((entry, index) => ({
+      source: normalizeSource(entry?.source || ordered[index]?.source || ""),
+      version: typeof entry?.version === "string" && entry.version ? entry.version : null,
+      error: typeof entry?.error === "string" && entry.error ? entry.error : null,
+    }))
+    : ordered.map((candidate) => ({ source: candidate.source, version: null, error: "unknown" }));
+  const agreement = checkVersionAgreement(versionEntries);
+  const winner = ordered[0] || null;
+  const probe = spawnProbe && typeof spawnProbe === "object" && spawnProbe.source
+    ? spawnProbe
+    : { source: winner?.source || null, ok: false, version: versionEntries[0]?.version || null, error: versionEntries[0]?.error || "unknown" };
+  const integrationResult = integration && typeof integration === "object" ? integration : checkIntegrationPresence({});
+  const flappingResult = flapping && typeof flapping === "object" && Array.isArray(flapping.signals)
+    ? flapping
+    : { flapping: false, reappearingShim: false, bumpedVersion: false, versionSplit: false, npmViewVersion: null, signals: [], detail: "No flapping signals." };
+  const pathList = Array.isArray(pathEntries) ? pathEntries : [];
+  const base = {
+    tool: "doctor",
+    readOnly: true,
+    winner,
+    candidates: ordered,
+    orderedCandidates: ordered,
+    versions: versionEntries,
+    candidateVersions: versionEntries,
+    agreement,
+    spawnProbe: probe,
+    spawnProbes: versionEntries.map((entry) => ({
+      source: entry.source,
+      ok: entry.version !== null && entry.error === null,
+      version: entry.version,
+      error: entry.error,
+    })),
+    integration: integrationResult,
+    integrationPresence: integrationResult,
+    flapping: flappingResult,
+    flappingSignals: flappingResult.signals || [],
+    path: { entries: pathList, inspectedReadOnly: true },
+    remedies: [
+      "For current-session relief use the winning full exe path directly.",
+      "For a durable fix apply a persistent user-chosen PATH reorder that places the direct exe directory before the npm shim directory, then restart Herdr plus the terminal plus OpenCode intentionally when ready.",
+      "Session-local changes alone never fix Herdr spawns because panes inherit the Herdr server environment.",
+    ],
+    anchors: [...DOCTOR_ANCHORS],
+    readmeAnchors: [...DOCTOR_ANCHORS],
+  };
+  const summary = formatHumanSummary(base);
+  return {
+    ...base,
+    operatorRemedies: [...base.remedies],
+    summary,
+    humanSummary: summary,
+  };
+}
+
+function runCrossSpawnVersion(candidate) {
+  try {
+    const result = spawn.sync(candidate, ["--version"], { encoding: "utf8", windowsHide: true, timeout: 15000 });
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr : (result.error ? String(result.error.message || result.error) : "");
+    const version = parseVersionText(stdout);
+    if (result.error) {
+      return { source: candidate, version, error: String(result.error.message || result.error).slice(0, 500) };
+    }
+    if (result.status !== 0) {
+      return { source: candidate, version, error: (stderr || `exit status ${String(result.status)}`).replace(/\s+/g, " ").trim().slice(0, 500) };
+    }
+    if (!version) return { source: candidate, version: null, error: "no version in output" };
+    return { source: candidate, version, error: null };
+  } catch (error) {
+    return { source: candidate, version: null, error: String(error?.message || error).slice(0, 500) };
+  }
+}
+
+function runHelpCapture(command, args) {
+  try {
+    const result = spawn.sync(command, args, { encoding: "utf8", windowsHide: true, timeout: 15000 });
+    if (result.error) return "";
+    return typeof result.stdout === "string" ? result.stdout : "";
+  } catch {
+    return "";
+  }
+}
+
+function collectLiveCandidates(envPath) {
+  const currentPlatform = platform();
+  if (currentPlatform === "win32") {
+    try {
+      const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "(Get-Command opencode -All).Source"], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15000,
+      });
+      const stdout = typeof result.stdout === "string" ? result.stdout : "";
+      const lines = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+      if (lines.length > 0) return lines;
+    } catch {}
+  }
+  const raw = typeof envPath === "string" ? envPath : "";
+  const entries = raw.split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+  const found = [];
+  const names = currentPlatform === "win32" ? ["opencode.cmd", "opencode.ps1", "opencode.exe", "opencode"] : ["opencode"];
+  for (const dir of entries) {
+    for (const name of names) {
+      const candidate = join(dir.replace(/[\\/]+$/, ""), name);
+      try {
+        if (existsSync(candidate)) found.push(candidate);
+      } catch {}
+    }
+    if (found.length >= 8) break;
+  }
+  return found;
+}
+
+function collectLivePathEntries(envPath) {
+  const raw = typeof envPath === "string" ? envPath : "";
+  return raw.split(delimiter).map((entry) => entry.trim()).filter(Boolean);
+}
+
+export function collectDoctorReport(options = {}) {
+  const envPath = options.envPath !== undefined ? options.envPath : (process.env.PATH || process.env.Path || "");
+  const liveCandidates = options.candidates !== undefined ? options.candidates : collectLiveCandidates(envPath);
+  const ordered = orderCandidates(liveCandidates);
+  const liveVersions = options.versions !== undefined
+    ? options.versions
+    : ordered.map((candidate) => runCrossSpawnVersion(candidate.source));
+  const agreement = checkVersionAgreement(liveVersions);
+  const winnerProbeInput = options.spawnProbe !== undefined ? options.spawnProbe : (() => {
+    const winnerSource = ordered[0]?.source;
+    if (!winnerSource) return { source: null, ok: false, version: null, error: "no candidates" };
+    const match = liveVersions[0];
+    if (match && match.error && String(match.error).includes(WIN32_SPAWN_ERROR)) {
+      return evaluateSpawnProbe({ source: winnerSource, stdout: "", stderr: match.error, status: 1 });
+    }
+    if (match && match.version) {
+      return { source: winnerSource, ok: match.error === null, version: match.version, error: match.error };
+    }
+    return { source: winnerSource, ok: false, version: null, error: (match && match.error) || "unknown" };
+  })();
+  const integration = options.integration !== undefined ? options.integration : checkIntegrationPresence({
+    integrationStatusText: runHelpCapture("herdr", ["integration", "status"]),
+    herdrHelpText: runHelpCapture("herdr", ["--help"]),
+    integrationInstallHelpText: runHelpCapture("herdr", ["integration", "install", "--help"]),
+  });
+  let npmViewVersion = null;
+  if (options.npmViewVersion !== undefined) {
+    npmViewVersion = options.npmViewVersion;
+  } else {
+    const npmText = runHelpCapture("npm", ["view", "opencode-ai", "version"]);
+    npmViewVersion = parseVersionText(npmText);
+  }
+  const flapping = options.flapping !== undefined
+    ? options.flapping
+    : detectFlapping({ candidates: ordered, versions: liveVersions, npmViewVersion });
+  return buildDoctorReport({
+    candidates: ordered.map((candidate) => candidate.source),
+    versions: liveVersions,
+    spawnProbe: winnerProbeInput,
+    integration,
+    flapping,
+    pathEntries: collectLivePathEntries(envPath),
+  });
+}

package/src/index.js

@@ -16,6 +16,7 @@ import {
 } from "./agents.js";
 import { createResponseTool } from "./response.js";
 import { createStateService } from "./state.js";
+import { createSteerCommandHook } from "./steer.js";
 
 const SESSION_MODES = new Map();
 
@@ -344,39 +345,56 @@ export function createOwnershipTools(stateOptions = {}) {
   return tools;
 }
 
-export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
-  tool: {
-    herdr_agent_response: createResponseTool(options.response),
-    ...createStateTools(options.state),
-    ...createSteeringTools(options.state),
-    ...createRawSteeringTools(options.state),
-    ...createOwnershipTools(options.state),
-  },
-  config(config) {
-    config.agent ??= {};
-    const agents = createAgents(options);
-    for (const [name, defaults] of Object.entries(agents)) {
-      config.agent[name] = mergeAgent(defaults, config.agent[name]);
-    }
-  },
+export const HerdrOrchestrationPlugin = async (pluginInput = {}, options = {}) => {
+  const stateOptions = { ...(options.state ?? {}) };
+  if (stateOptions.cwd === undefined) {
+    const fallback = pluginInput?.directory ?? pluginInput?.worktree;
+    if (typeof fallback === "string" && fallback.length > 0) stateOptions.cwd = fallback;
+  }
+  const resolveAgent = options.steerResolveAgent ?? options.steer?.resolveAgent;
+  const steerBefore = createSteerCommandHook({
+    client: pluginInput?.client,
+    stateOptions,
+    ...(resolveAgent ? { resolveAgent } : {}),
+  });
+  return {
+    tool: {
+      herdr_agent_response: createResponseTool(options.response),
+      ...createStateTools(options.state),
+      ...createSteeringTools(options.state),
+      ...createRawSteeringTools(options.state),
+      ...createOwnershipTools(options.state),
+    },
+    config(config) {
+      config.agent ??= {};
+      const agents = createAgents(options);
+      for (const [name, defaults] of Object.entries(agents)) {
+        config.agent[name] = mergeAgent(defaults, config.agent[name]);
+      }
+    },
 
-  async "chat.message"(input) {
-    if (input.sessionID) SESSION_MODES.set(input.sessionID, modeForAgent(input.agent));
-  },
+    async "command.execute.before"(input, output) {
+      return steerBefore(input, output);
+    },
 
-  async "shell.env"(input, output) {
-    output.env.SHEPHERD_MODE = input.sessionID
-      ? (SESSION_MODES.get(input.sessionID) ?? "none")
-      : "none";
-  },
+    async "chat.message"(input) {
+      if (input.sessionID) SESSION_MODES.set(input.sessionID, modeForAgent(input.agent));
+    },
 
-  async event({ event }) {
-    if (event?.type === "session.deleted") {
-      const sessionID = event.properties?.info?.id ?? event.properties?.sessionID;
-      if (sessionID) SESSION_MODES.delete(sessionID);
-    }
-  },
-});
+    async "shell.env"(input, output) {
+      output.env.SHEPHERD_MODE = input.sessionID
+        ? (SESSION_MODES.get(input.sessionID) ?? "none")
+        : "none";
+    },
+
+    async event({ event }) {
+      if (event?.type === "session.deleted") {
+        const sessionID = event.properties?.info?.id ?? event.properties?.sessionID;
+        if (sessionID) SESSION_MODES.delete(sessionID);
+      }
+    },
+  };
+};
 
 export default HerdrOrchestrationPlugin;
 export {

package/src/installer.js

@@ -5,6 +5,13 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import spawn from "cross-spawn";
 import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+import {
+  STEER_COMMAND_AGENT as STEER_AGENT,
+  STEER_COMMAND_DESCRIPTION as STEER_DESCRIPTION,
+  STEER_COMMAND_NAME as STEER_NAME,
+  STEER_COMMAND_TEMPLATE as STEER_TEMPLATE,
+  steerCommandEntry as steerEntry,
+} from "./steer.js";
 
 export const PACKAGE_NAME = "opencode-herdr-orchestration";
 const NPM_COMMAND = "npm";
@@ -17,6 +24,7 @@ export const AGENT_NAMES = [
   "sheep",
   "shearer-low",
   "shearer-medium",
+  "developer",
 ];
 
 // Agents register dynamically through the plugin, so the package owns no agent
@@ -391,6 +399,64 @@ export function writePluginConfig(configDir, remove = false, models) {
   return { file, backup, changed: true, existed };
 }
 
+// Native /steer command owned by the installer. Single source for the shape
+// lives in src/steer.js; these helpers persist it with the same JSONC
+// preserve-comments plus backup discipline as the plugin config. The entry
+// pins agent developer, carries an $ARGUMENTS template, and describes the
+// Developer-only direct-write hook.
+export {
+  STEER_COMMAND_AGENT,
+  STEER_COMMAND_DESCRIPTION,
+  STEER_COMMAND_NAME,
+  STEER_COMMAND_TEMPLATE,
+  steerCommandEntry,
+} from "./steer.js";
+
+export function updateCommandConfig(text, commandName, entry, remove = false) {
+  const errors = [];
+  const parsed = parse(text || "{}", errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length) {
+    const first = errors[0];
+    throw new Error(`Invalid OpenCode JSONC at offset ${first.offset}: ${printParseErrorCode(first.error)}.`);
+  }
+  if (typeof commandName !== "string" || commandName.length === 0) {
+    throw new Error("Command name must be a non-empty string.");
+  }
+  const source = text || "{}";
+  if (remove && parsed?.command?.[commandName] === undefined) return source;
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: source.includes("\r\n") ? "\r\n" : "\n" };
+  const value = remove ? undefined : entry;
+  return applyEdits(source, modify(source, ["command", commandName], value, { formattingOptions }));
+}
+
+export function updateSteerCommand(text, entry = steerEntry(), remove = false) {
+  return updateCommandConfig(text, STEER_NAME, entry, remove);
+}
+
+export function isSteerCommandConfigured(text) {
+  const config = parse(text || "{}", [], { allowTrailingComma: true, disallowComments: false });
+  const entry = config?.command?.[STEER_NAME];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  return (
+    entry.agent === STEER_AGENT &&
+    typeof entry.template === "string" &&
+    entry.template.includes("$ARGUMENTS") &&
+    entry.description === STEER_DESCRIPTION
+  );
+}
+
+export function writeSteerCommand(configDir, remove = false) {
+  mkdirSync(configDir, { recursive: true });
+  const file = findConfigFile(configDir);
+  const existed = existsSync(file);
+  const previous = existed ? readFileSync(file, "utf8") : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  const next = updateSteerCommand(previous, steerEntry(), remove);
+  if (next === previous) return { file, backup: null, changed: false, existed };
+  const backup = backupFile(file);
+  writeFileSync(file, next, "utf8");
+  return { file, backup, changed: true, existed };
+}
+
 export function restoreBackup(file, backup, existed = true) {
   if (backup && existsSync(backup)) copyFileSync(backup, file);
   else if (!existed) rmSync(file, { force: true });
@@ -552,9 +618,16 @@ export function validateOpenCode(configDir) {
 export function status(configDir, packageRoot) {
   const file = findConfigFile(configDir);
   let configured = false;
+  let steerCommandConfigured = false;
   if (existsSync(file)) {
-    const config = parse(readFileSync(file, "utf8"), [], { allowTrailingComma: true, disallowComments: false });
+    const text = readFileSync(file, "utf8");
+    const config = parse(text, [], { allowTrailingComma: true, disallowComments: false });
     configured = Array.isArray(config?.plugin) && config.plugin.some(isOrchestrationPlugin);
+    try {
+      steerCommandConfigured = isSteerCommandConfigured(text);
+    } catch {
+      steerCommandConfigured = false;
+    }
   }
   const installed = installedVersion(configDir);
   let detectedAgents = [];
@@ -586,6 +659,7 @@ export function status(configDir, packageRoot) {
     updateAvailable: Boolean(installed && latest && installed !== latest),
     configFile: file,
     pluginConfigured: configured,
+    steerCommandConfigured,
     detectedAgents,
     agentsReady: detectedAgents.length === AGENT_NAMES.length,
     obsoleteAgentFiles,

package/src/steer.js

@@ -0,0 +1,124 @@
+import { DEVELOPER_AGENT, STEERING_TOOL_ACCESS, STEERING_TOOLS } from "./agents.js";
+import { createStateService } from "./state.js";
+
+// Native /steer command owned by the installer. The hook in this module is
+// the sole writer: it calls the existing state service directly so validation
+// plus journaling stay identical to the submit tool with no parallel store.
+export const STEER_COMMAND_NAME = "steer";
+export const STEER_COMMAND_AGENT = DEVELOPER_AGENT;
+export const STEER_COMMAND_DESCRIPTION =
+  "Submit bounded Developer steering for one Plan ID target (Developer only; flock roles denied).";
+export const STEER_COMMAND_TEMPLATE =
+  "Submit Developer steering with arguments: $ARGUMENTS\n\nFormat $ARGUMENTS as `<content>` or `<planId> :: <content>`; omit planId only when exactly one active steering target exists.";
+
+export function steerCommandEntry() {
+  return {
+    template: STEER_COMMAND_TEMPLATE,
+    description: STEER_COMMAND_DESCRIPTION,
+    agent: STEER_COMMAND_AGENT,
+  };
+}
+
+// Parse /steer arguments into the exact { content plus optional planId }
+// shape the state service validates. `::` separates an explicit planId
+// candidate from content when the left side is a single token (no whitespace);
+// the candidate is passed through so the state service reports
+// INVALID_PLAN_ID identically to the submit tool. A left side with whitespace
+// is prose, so the whole string stays content and `::` inside sentences never
+// misroutes.
+export function parseSteerArguments(rawArguments) {
+  const raw = typeof rawArguments === "string" ? rawArguments : "";
+  const separator = raw.indexOf("::");
+  if (separator !== -1) {
+    const left = raw.slice(0, separator).trim();
+    const right = raw.slice(separator + 2).trim();
+    if (left.length > 0 && !/\s/.test(left)) {
+      return { planId: left, content: right };
+    }
+  }
+  return { content: raw.trim() };
+}
+
+// Single shared allowlist with the submit tool: only the explicit developer
+// context passes. All seven orchestration roles plus unknown plus none plus
+// unset fail closed.
+export function isSteerAllowedAgent(agent) {
+  return STEERING_TOOL_ACCESS.get(STEERING_TOOLS.submit)?.has(agent) === true;
+}
+
+// Resolve the session agent via the SDK client, fail closed to undefined on
+// any unresolvable shape. Prefers session messages (UserMessage.agent) then
+// falls back to session get; any throw or missing agent is unresolvable.
+export async function resolveSessionAgentViaClient(client, sessionID) {
+  if (!client || typeof sessionID !== "string" || sessionID.length === 0) return undefined;
+  try {
+    const session = client?.session;
+    if (!session) return undefined;
+    if (typeof session.messages === "function") {
+      const result = await session.messages({ path: { id: sessionID } });
+      const data = result?.data ?? result;
+      if (Array.isArray(data)) {
+        for (let index = data.length - 1; index >= 0; index -= 1) {
+          const agent = data[index]?.info?.agent;
+          if (typeof agent === "string" && agent.length > 0) return agent;
+        }
+      }
+    }
+    if (typeof session.get === "function") {
+      const result = await session.get({ path: { id: sessionID } });
+      const data = result?.data ?? result;
+      const agent = data?.agent ?? data?.info?.agent;
+      if (typeof agent === "string" && agent.length > 0) return agent;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function pushPart(output, text) {
+  const part = { type: "text", text };
+  if (output && Array.isArray(output.parts)) {
+    output.parts.push(part);
+    return;
+  }
+  if (output && output.parts === undefined) {
+    output.parts = [part];
+  }
+}
+
+// command.execute.before intercept for /steer. Performs the write directly
+// through the existing state service, enforces the shared Developer-only
+// allowlist, then throws to abort before any model turn. The throw carries
+// the confirmation (steering id plus resolved target); output.parts carries
+// the same text as a minimal fallback if error styling is unacceptable.
+export function createSteerCommandHook({ client, stateOptions = {}, resolveAgent } = {}) {
+  const resolve = resolveAgent ?? ((sessionID) => resolveSessionAgentViaClient(client, sessionID));
+  return async function steerCommandBefore(input, output) {
+    if (!input || input.command !== STEER_COMMAND_NAME) return;
+    let agent;
+    try {
+      agent = await resolve(input.sessionID);
+    } catch {
+      agent = undefined;
+    }
+    if (typeof agent !== "string" || !isSteerAllowedAgent(agent)) {
+      const denial = `Steering denied: agent ${JSON.stringify(agent ?? "unknown")} may not use /${STEER_COMMAND_NAME}. Developer context only.`;
+      pushPart(output, denial);
+      throw new Error(denial);
+    }
+    const parsed = parseSteerArguments(input.arguments);
+    const state = createStateService(stateOptions);
+    const payload =
+      parsed.planId === undefined ? { content: parsed.content } : { planId: parsed.planId, content: parsed.content };
+    const result = await state.submitSteering(payload);
+    if (!result.ok) {
+      const failure = `Steering failed [${result.error.code}]: ${result.error.message}`;
+      pushPart(output, failure);
+      throw new Error(failure);
+    }
+    const confirmation = `Steering recorded: ${result.entry.id} for target ${result.entry.planId}#${result.entry.sequence}`;
+    pushPart(output, confirmation);
+    throw new Error(confirmation);
+  };
+}