opencode-herdr-orchestration 0.3.1 → 0.3.3

package/bin/orchestration.js

@@ -24,6 +24,7 @@ import {
   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");
@@ -190,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);
@@ -198,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.1",
+  "version": "0.3.3",
   "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 src/steer.js && node --check src/installer.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

@@ -288,9 +288,9 @@ const GOVERNOR_SEND_KEYS_CTRL_C_ALLOWS = {
 // --clear`, close takes `<pane_id>`.
 // Agent rename evidenced as `herdr agent rename <TARGET> <NAME>|--clear`
 // (live `agent list` shows `name` such as `issue1418m1sheep` and `agent get`
-// shows `name` plus `pane_id`); pane rename plus tab rename helps evidenced
-// but only pane plus agent rename are enabled, tab rename stays denied to
-// keep the single-tab 4-pane cap.
+// shows `name` plus `pane_id`); pane rename plus agent rename plus tab create
+// helps evidenced and enabled for per-tab overflow, tab rename stays denied
+// to keep the per-tab 4-pane cap with new-tab overflow.
 // Count queries evidenced as `herdr tab list --workspace <ID>` returning
 // `{"id":"cli:tab:list","result":{"tabs":[{"pane_count":1,"tab_id":"w1K:t1",...}]},"type":"tab_list"}`,
 // `herdr pane list --workspace <ID>` returning
@@ -316,19 +316,21 @@ const GOVERNOR_SEND_KEYS_CTRL_C_ALLOWS = {
 // IDs are opaque stable handles (`w1K`, `w1K:t1`, `w1K:p1` from
 // `HERDR_WORKSPACE_ID` plus `HERDR_TAB_ID` plus `HERDR_PANE_ID`); closed IDs
 // are not reused; prefer `--current` and never rely on the UI-focused pane.
-// Fallback if any of tab list plus pane get plus rename plus close plus
-// split are missing: reuse the current pane via `--pane` plus `--current`,
-// report STOP naming the missing capability, never invent `herdr pane
-// create*` plus `herdr tab split*` plus `herdr agent events*` plus
-// `herdr pane move*` plus `herdr pane resize*` plus `herdr workspace
+// Fallback if any of tab list plus tab create plus pane get plus rename plus
+// close plus split are missing: reuse the current pane via `--pane` plus
+// `--current`, report STOP naming the missing capability, never invent
+// `herdr pane create*` plus `herdr tab split*` plus `herdr agent events*`
+// plus `herdr pane move*` plus `herdr pane resize*` plus `herdr workspace
 // create*` behavior.
 // Protected Dev Developer Terminal exclusion cannot be matcher-enforced:
 // pane IDs are opaque and labels are absent from scan plus split plus close
 // command strings, while a `*Dev*` glob would overmatch legitimate
-// `--cwd C:\Dev\...` values, so no such glob is added; the prompt plus
-// README Pane layout policy exclusion stays primary; see README residual.
+// `--cwd C:\Dev\...` values, so no such glob is added; the prompt plus docs
+// architecture tab section exclusion stays primary with per-tab cap plus
+// new-tab overflow plus never touch Dev in any tab; see docs residual.
 const SHEPHERD_PANE_ALLOWS = {
   "herdr tab list*": "allow",
+  "herdr tab create*": "allow",
   "herdr pane get*": "allow",
   "herdr pane rename*": "allow",
   "herdr agent rename*": "allow",
@@ -341,6 +343,7 @@ const GOVERNOR_PANE_ALLOWS = {
 };
 const SHEEPDOG_PANE_ALLOWS = {
   "herdr tab list*": "allow",
+  "herdr tab create*": "allow",
   "herdr pane get*": "allow",
   "herdr pane rename*": "allow",
   "herdr agent rename*": "allow",

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/prompts.js

@@ -1,6 +1,6 @@
-// 14-18-M2 prompt policy plus startup layout plus placement behavior.
-// Shared M1 normative pane policy sentences are cited with the same wording
-// as README Pane layout policy (14-18-M1) so prompts and runtime cannot drift.
+// Prompt policy plus startup layout plus placement behavior.
+// Shared normative pane policy sentences are cited with the same wording
+// as docs architecture tab section so prompts and runtime cannot drift.
 // Every spawning role carries the same shared sentences; role-specific
 // ownership plus startup destinations differ per role. Leaves stay unchanged.
 // Spawn plus response plus state matrices stay intact with no new spawn targets.
@@ -9,8 +9,9 @@ export const PANE_CAP = 4;
 export const DEV_PANE_LABELS = Object.freeze(["Dev", "Developer Terminal"]);
 export const PANE_POLICY_SHARED_SENTENCES = Object.freeze([
   "at most four panes per tab including the caller pane",
-  "Never split when the filtered count is already four; use indexed overflow instead.",
-  "Overflow by index within role grouping instead of creating a fifth pane.",
+  "Reuse first within the four-pane cap per tab",
+  "Never split when the filtered count is already four; overflow to a new tab instead.",
+  "Overflow to a new tab with indexed role labels when the cap binds.",
   "Grouped by role with indexed labels (Sheepdog, sheep-1, sheep-2, shearer-low-1, grazer-1)",
   "tabs keep their existing labels",
   "Reuse the matching pane when found; split only when no reusable pane exists and the cap permits.",
@@ -19,26 +20,27 @@ export const PANE_POLICY_SHARED_SENTENCES = Object.freeze([
   "excluded from every scan plus split plus placement plus rename plus close plus reuse",
   "Never count it toward the four-pane cap, never list it as a reuse candidate, never split from it or into it, never place a worker there, never rename it, never close it, and never reuse it for overflow.",
   "Filter it during scan by terminal_title plus terminal_title_stripped plus label before counting plus reusing",
-  "when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or report STOP with preserved state.",
-  "Never create a workspace or tab to evade the cap",
+  "when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or overflow to a new tab or report STOP with preserved state.",
+  "Never create a workspace to evade the cap",
+  "Never touch the Dev pane in any tab.",
   "Start in the calling pane and never rely on another client focused pane.",
   "If any primitive below is missing, reuse the current pane via --pane plus --current and report STOP naming the missing capability with preserved state.",
   "Pre-create default stays minimal",
   "On finish, reuse the pane for the next same-role assignment after confirming idle plus done.",
-  "Six-step placement is single-tab plus reuse-first plus evidence-only",
-  "Dynamic placement follows the same single normative pane policy with no separate rulebook.",
+  "Six-step placement is reuse-first plus evidence-only with new-tab overflow",
+  "Dynamic placement follows the same single normative pane policy with new-tab overflow and no separate rulebook.",
 ]);
 export const PANE_POLICY_SHARED_PARAGRAPH = String.raw`
-Pane layout policy (single normative policy, same wording as README): Four-pane cap: at most four panes per tab including the caller pane. Never split when the filtered count is already four; use indexed overflow instead. Overflow by index within role grouping instead of creating a fifth pane. Grouped by role with indexed labels (Sheepdog, sheep-1, sheep-2, shearer-low-1, grazer-1); tabs keep their existing labels. Reuse the matching pane when found; split only when no reusable pane exists and the cap permits. Reuse is preferred over clutter: reuse a capacity-available managed pane for the same role before splitting. Never derive IDs from sidebar order or examples; parse them from JSON responses. The pane labeled Dev (Developer Terminal) is excluded from every scan plus split plus placement plus rename plus close plus reuse. Never count it toward the four-pane cap, never list it as a reuse candidate, never split from it or into it, never place a worker there, never rename it, never close it, and never reuse it for overflow. Filter it during scan by terminal_title plus terminal_title_stripped plus label before counting plus reusing; when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or report STOP with preserved state. Never create a workspace or tab to evade the cap. Start in the calling pane and never rely on another client focused pane. If any primitive below is missing, reuse the current pane via --pane plus --current and report STOP naming the missing capability with preserved state. Pre-create default stays minimal: reuse the current pane via --pane plus --current when primitives are missing. On finish, reuse the pane for the next same-role assignment after confirming idle plus done. Six-step placement is single-tab plus reuse-first plus evidence-only. Dynamic placement follows the same single normative pane policy with no separate rulebook.
+Pane layout policy (single normative policy, same wording as docs architecture tab section): Four-pane cap: at most four panes per tab including the caller pane. Reuse first within the four-pane cap per tab. Never split when the filtered count is already four; overflow to a new tab instead. Overflow to a new tab with indexed role labels when the cap binds. Grouped by role with indexed labels (Sheepdog, sheep-1, sheep-2, shearer-low-1, grazer-1); tabs keep their existing labels. Reuse the matching pane when found; split only when no reusable pane exists and the cap permits. Reuse is preferred over clutter: reuse a capacity-available managed pane for the same role before splitting. Never derive IDs from sidebar order or examples; parse them from JSON responses. The pane labeled Dev (Developer Terminal) is excluded from every scan plus split plus placement plus rename plus close plus reuse. Never count it toward the four-pane cap, never list it as a reuse candidate, never split from it or into it, never place a worker there, never rename it, never close it, and never reuse it for overflow. Filter it during scan by terminal_title plus terminal_title_stripped plus label before counting plus reusing; when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or overflow to a new tab or report STOP with preserved state. Never create a workspace to evade the cap. Never touch the Dev pane in any tab. Start in the calling pane and never rely on another client focused pane. If any primitive below is missing, reuse the current pane via --pane plus --current and report STOP naming the missing capability with preserved state. Pre-create default stays minimal: reuse the current pane via --pane plus --current when primitives are missing. On finish, reuse the pane for the next same-role assignment after confirming idle plus done. Six-step placement is reuse-first plus evidence-only with new-tab overflow. Dynamic placement follows the same single normative pane policy with new-tab overflow and no separate rulebook.
 `.trim();
 export const SHEPHERD_PANE_OWNERSHIP_PARAGRAPH = String.raw`
-Shepherd pane ownership plus startup: shepherd manages its single Sheepdog pane scan plus placement plus rename only and never closes; starts its grazer in a sibling pane of the current tab; leaves gain no pane plus tab plus rename commands and stay unchanged.
+Shepherd pane ownership plus startup: shepherd manages its single Sheepdog pane scan plus placement plus rename plus tab create only and never closes; starts its grazer in a sibling pane of the current tab with overflow to a new tab with indexed role labels when the cap binds; leaves gain no pane plus tab plus rename commands and stay unchanged.
 `.trim();
 export const GOVERNOR_PANE_OWNERSHIP_PARAGRAPH = String.raw`
 Governor pane ownership plus startup: shepherd-governor manages its single Sheepdog pane scan plus placement plus rename only and never closes flock panes; starts its sheepdog in a dedicated sibling Sheepdog pane of the current tab; leaves gain no pane plus tab plus rename commands and stay unchanged.
 `.trim();
 export const SHEEPDOG_PANE_OWNERSHIP_PARAGRAPH = String.raw`
-Sheepdog pane ownership plus startup plus dynamic placement: sheepdog manages flock panes scan plus placement plus rename plus close up to the cap; only the creator may rename plus close its panes and only after commits are integrated or otherwise preserved and the worktree is clean; starts in its own Sheepdog pane and starts flock workers in sibling flock panes of the same tab grouped by role with indexed labels; startup destinations for grazer plus sheep plus shearer-low plus shearer-medium worker categories stay within the four-pane cap with Dev excluded and pre-create default minimal; six-step placement is single-tab plus reuse-first plus evidence-only with cap check plus reuse check plus split plus rename plus start; on cap go to indexed overflow reuse and never split; reuse capacity-available managed panes first and reuse the pane on finish after confirming idle plus done; never create a new tab or workspace to evade the cap.
+Sheepdog pane ownership plus startup plus dynamic placement: sheepdog manages flock panes scan plus placement plus rename plus close plus tab create up to the per-tab cap; only the creator may rename plus close its panes and only after commits are integrated or otherwise preserved and the worktree is clean; starts in its own Sheepdog pane and starts flock workers in sibling flock panes of the current tab with overflow to a new tab with indexed role labels when the cap binds grouped by role with indexed labels; startup destinations for grazer plus sheep plus shearer-low plus shearer-medium worker categories stay within the four-pane cap per tab with Dev excluded in any tab and pre-create default minimal; six-step placement is reuse-first plus evidence-only with new-tab overflow with cap check plus reuse check plus split plus rename plus tab create plus start; on cap go to a new tab with indexed role labels and never split a fifth pane; reuse capacity-available managed panes first within the cap and reuse the pane on finish after confirming idle plus done; never create a workspace to evade the cap and never touch the Dev pane in any tab.
 `.trim();
 export const SHEPHERD_PROMPT = String.raw`
 You are shepherd, the planning authority of the flock. You research the user's goal through grazer workers and present an implementation-ready plan. You never implement, integrate, or deliver; execution and final delivery belong to shepherd-governor after the user approves your plan by selecting it.
@@ -258,13 +260,14 @@ Keep summaries secondary to findings. Never implement fixes.
 Raw Developer steering is not yours: shepherd phases own raw check, read, consume, and lifecycle tools in code and you are denied them.
 `.trim();
 
-// 14-18-M2 placement helpers (pure, evidence-only, same policy, no separate rulebook).
+// Placement helpers (pure, evidence-only, same policy, no separate rulebook).
 // These helpers operate on abstract pane records without Herdr calls, so they
 // need no broader spawn authority and no missing CLI primitives. They mirror
-// the shared normative wording above: four-pane cap, Dev exclusion, reuse
-// before create, indexed overflow, startup destinations within cap, and
-// pre-create default minimal. Caller context stays via current pane ID and
-// never relies on another client focused pane.
+// the shared normative wording above: four-pane cap per tab, Dev exclusion
+// in any tab, reuse first within cap, new-tab overflow with indexed role
+// labels, startup destinations per tab, and pre-create default minimal.
+// Caller context stays via current pane ID and never relies on another
+// client focused pane.
 export function isDevPane(pane) {
   if (!pane || typeof pane !== "object") return false;
   for (const key of ["label", "terminal_title", "terminal_title_stripped"]) {
@@ -318,21 +321,13 @@ export function decidePanePlacement({ panes, tabId, reuseCandidateId, currentPan
       return {
         action: "overflow-reuse",
         paneId: reuseCandidateId,
-        reason: "Never split when the filtered count is already four; use indexed overflow instead.",
-      };
-    }
-    const firstManaged = managedInTab[0];
-    if (firstManaged && !candidateIsDev) {
-      return {
-        action: "overflow-reuse",
-        paneId: firstManaged.pane_id,
-        reason: "Overflow by index within role grouping instead of creating a fifth pane.",
+        reason: "Reuse first within the four-pane cap per tab",
       };
     }
     return {
-      action: "overflow-reuse",
-      paneId: preCreateDefaultPane(currentPaneId) ?? null,
-      reason: "when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or report STOP with preserved state.",
+      action: "new-tab",
+      paneId: null,
+      reason: "Overflow to a new tab with indexed role labels when the cap binds.",
     };
   }
 
@@ -348,7 +343,7 @@ export function decidePanePlacement({ panes, tabId, reuseCandidateId, currentPan
     return {
       action: "split",
       paneId: null,
-      reason: "when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or report STOP with preserved state.",
+      reason: "when only the Dev pane would satisfy reuse, treat reuse as absent and either split elsewhere within cap or overflow to a new tab or report STOP with preserved state.",
     };
   }