harness-everything 0.20.4 → 0.20.6

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.20.4",
+      "version": "0.20.6",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.20.6](https://github.com/dyphn1/Harness-everything/compare/v0.20.5...v0.20.6) (2026-09-22)
+
+### Bug Fixes
+
+* **distribution:** match resolve-on-path test extension casing to fixture files ([07f0e5a](https://github.com/dyphn1/Harness-everything/commit/07f0e5a815e779f5596d5c79d448b9ab383ee361))
+* **distribution:** resolve codex/claude on windows in path order, not exe preference ([048c5e4](https://github.com/dyphn1/Harness-everything/commit/048c5e40e0d4727700234c49e509fc6edfac4f01)), closes [#236](https://github.com/dyphn1/Harness-everything/issues/236)
+
+## [0.20.5](https://github.com/dyphn1/Harness-everything/compare/v0.20.4...v0.20.5) (2026-09-22)
+
+### Bug Fixes
+
+* **distribution:** support codex clis without --json or plugin install ([d6a48a6](https://github.com/dyphn1/Harness-everything/commit/d6a48a6763bb564eb7df14334579003823242af7)), closes [#221](https://github.com/dyphn1/Harness-everything/issues/221)
+
 ## [0.20.4](https://github.com/dyphn1/Harness-everything/compare/v0.20.3...v0.20.4) (2026-09-22)
 
 ### Bug Fixes

package/README.md

@@ -95,7 +95,7 @@ For `--global`, the installer uses each host's supported user-level skill locati
 
 The repository also ships a separate local OpenAI/Codex plugin package under `plugins/harness-everything/` with marketplace metadata in `.agents/plugins/marketplace.json`. That package is not the same thing as the `--codex` advisory installer path. The public OpenAI Skills-only upload is narrower again; see [docs/openai-plugin.md](docs/openai-plugin.md).
 
-The native `plugin-sync` command detects the installed host CLIs and applies the state-specific operation: an absent plugin is installed, while an already-installed plugin is explicitly updated (Claude Code) or its configured marketplace is upgraded (Codex). If a host cannot report plugin state, the command fails closed without installing or updating blindly.
+The native `plugin-sync` command detects the installed host CLIs and applies the state-specific operation: an absent plugin is installed, while an already-installed plugin is explicitly updated (Claude Code) or its configured marketplace is upgraded (Codex). Options the host CLI does not implement are dropped and retried, and a host build without plugin install commands is reported as an actionable skip. If a host cannot report plugin state, the command fails closed without installing or updating blindly.
 
 The installer records its state directories in `.git/info/exclude` — a local-only git ignore file — so Harness state never lands in a commit and your working tree (including `.gitignore`) is never modified. Everything owned by the general installer is removed with the built-in uninstaller:
 

package/ci/mechanism-2ao-plugin-sync.test.js

@@ -9,12 +9,13 @@ const {
   findMarketplace,
   findPlugin,
   parseJsonOutput,
+  resolveOnPath,
   sync
 } = require('../scripts/plugin-sync');
 
 const ROOT = path.resolve(__dirname, '..');
 
-function fakeHost({ claudeInstalled = false, codexInstalled = false, claudeMarketplace = true, codexMarketplace = true, unknownClaudePluginState = false, unknownClaudeYesFlag = false, unknownClaudeJsonFlag = false } = {}) {
+function fakeHost({ claudeInstalled = false, codexInstalled = false, claudeMarketplace = true, codexMarketplace = true, unknownClaudePluginState = false, unknownClaudeYesFlag = false, unknownClaudeJsonFlag = false, clapCodexJsonFlag = false, missingCodexPluginCommand = false } = {}) {
   const calls = [];
   const state = {
     claudeInstalled,
@@ -59,6 +60,27 @@ function fakeHost({ claudeInstalled = false, codexInstalled = false, claudeMarke
     }
 
     if (command === 'codex') {
+      // clap-based CLIs reject an option they do not implement as an
+      // unexpected argument, not as an unknown option. Read-only listings
+      // already have their own plain-text fallback, so this models a build
+      // whose mutating commands predate --json.
+      if (clapCodexJsonFlag && args.includes('--json') && /^plugin (marketplace (add|upgrade)|add)\b/.test(joined)) {
+        return {
+          status: 2,
+          stdout: '',
+          stderr: "error: unexpected argument '--json' found\n\n  tip: to pass '--json' as a value, use '-- --json'\n\nUsage: codex plugin marketplace add --ref <REF> <SOURCE>"
+        };
+      }
+      // Codex builds that ship only `codex plugin marketplace` have no plugin
+      // install/list surface at all.
+      if (missingCodexPluginCommand && /^plugin (list|add)\b/.test(joined)) {
+        const subcommand = joined.split(' ')[1];
+        return {
+          status: 2,
+          stdout: '',
+          stderr: `error: unrecognized subcommand '${subcommand}'\n\nUsage: codex plugin [OPTIONS] <COMMAND>`
+        };
+      }
       if (joined.includes('marketplace list --json')) {
         return { status: 0, stdout: JSON.stringify({ marketplaces: state.codexMarketplace ? [{ name: 'harness-everything' }] : [] }), stderr: '' };
       }
@@ -165,6 +187,41 @@ assert.strictEqual(findPlugin({ plugins: [{ id: 'harness-everything@harness-ever
   assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin add').length, 0, 'installed Codex plugin must not be re-added');
 }
 
+{
+  const fake = fakeHost({ codexInstalled: false, codexMarketplace: false, clapCodexJsonFlag: true });
+  const result = runHost('codex', fake);
+  const addCalls = callsFor(fake.calls, 'codex', 'plugin marketplace add');
+  const installCalls = callsFor(fake.calls, 'codex', 'plugin add');
+  assert.strictEqual(result.failed, 0, 'clap-style --json rejection must fall back to a compatible Codex command');
+  assert.strictEqual(result.results[0].action, 'install');
+  assert.strictEqual(addCalls.length, 2, 'unsupported Codex --json must cause one marketplace add retry');
+  assert.ok(addCalls[0].args.includes('--json'), 'first Codex marketplace add should use the current flags');
+  assert.ok(!addCalls[1].args.includes('--json'), 'Codex compatibility retry must omit unsupported --json');
+  assert.ok(installCalls.some(call => !call.args.includes('--json')), 'Codex plugin install must also retry without --json');
+}
+
+{
+  const fake = fakeHost({ codexInstalled: true, clapCodexJsonFlag: true });
+  const result = runHost('codex', fake);
+  const upgradeCalls = callsFor(fake.calls, 'codex', 'plugin marketplace upgrade');
+  assert.strictEqual(result.failed, 0, 'clap-style --json rejection must not fail the Codex upgrade path');
+  assert.strictEqual(result.results[0].action, 'update');
+  assert.strictEqual(upgradeCalls.length, 2, 'unsupported Codex --json must cause one upgrade retry');
+  assert.ok(!upgradeCalls[1].args.includes('--json'), 'Codex upgrade retry must omit unsupported --json');
+}
+
+{
+  const fake = fakeHost({ codexMarketplace: false, missingCodexPluginCommand: true, clapCodexJsonFlag: true });
+  const result = runHost('codex', fake);
+  assert.strictEqual(result.failed, 0, 'a Codex build without plugin subcommands is a capability boundary, not a failure');
+  assert.strictEqual(result.skipped, 1, 'the boundary must be reported as a distinct skipped outcome');
+  assert.strictEqual(result.results[0].reasonCode, 'host-capability-boundary', 'a capability boundary must not be reported as a missing CLI');
+  assert.match(result.results[0].reason, /codex plugin list/, 'the skip reason must name the missing host command');
+  assert.match(result.results[0].reason, /upgrade/i, 'the skip reason must stay actionable');
+  assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin marketplace add').length, 2, 'the supported marketplace registration must still run');
+  assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin add').length, 0, 'an unsupported host must not be blindly installed into');
+}
+
 {
   const fake = fakeHost({ unknownClaudePluginState: true });
   const result = runHost('claude', fake);
@@ -178,6 +235,38 @@ assert.strictEqual(findPlugin({ plugins: [{ id: 'harness-everything@harness-ever
   const result = sync({ host: 'all' }, { commandAvailable: () => false, log: () => {}, warn: () => {} });
   assert.strictEqual(result.skipped, 2);
   assert.strictEqual(result.failed, 0);
+  assert.ok(result.results.every(entry => entry.reasonCode === 'cli-not-found'), 'an absent CLI must stay distinguishable from a capability boundary');
+}
+
+// resolveOnPath() is pure filesystem logic (platform choice happens only at
+// the defaultRunner call site), so its directory-order-first contract runs
+// on every CI OS, not only Windows.
+{
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-plugin-sync-resolve-'));
+  const cmdDir = path.join(base, 'cmd-dir');
+  const exeDir = path.join(base, 'exe-dir');
+  fs.mkdirSync(cmdDir);
+  fs.mkdirSync(exeDir);
+  fs.writeFileSync(path.join(cmdDir, 'harness-fixture.cmd'), '');
+  fs.writeFileSync(path.join(exeDir, 'harness-fixture.exe'), '');
+  try {
+    // Real PATHEXT is upper-case, but NTFS matches it case-insensitively
+    // against lower-case fixture files; this test also runs on Linux/macOS
+    // CI, whose case-sensitive filesystems would not, so the fixture extension
+    // casing matches the file names exactly. The point under test is
+    // directory order versus extension order, not PATHEXT's own casing.
+    const pathExt = '.com;.exe;.bat;.cmd';
+    const cmdFirst = resolveOnPath('harness-fixture', { pathValue: [cmdDir, exeDir].join(path.delimiter), pathExt });
+    assert.strictEqual(String(cmdFirst).toLowerCase(), path.join(cmdDir, 'harness-fixture.cmd').toLowerCase(), 'an earlier PATH directory must win even when a later one has the extension PATHEXT prefers');
+
+    const exeFirst = resolveOnPath('harness-fixture', { pathValue: [exeDir, cmdDir].join(path.delimiter), pathExt });
+    assert.strictEqual(String(exeFirst).toLowerCase(), path.join(exeDir, 'harness-fixture.exe').toLowerCase(), 'PATH order, not extension preference, must decide the match');
+
+    const missing = resolveOnPath('harness-fixture-does-not-exist', { pathValue: [cmdDir, exeDir].join(path.delimiter), pathExt });
+    assert.strictEqual(missing, null, 'an unresolved command must return null, not throw');
+  } finally {
+    fs.rmSync(base, { recursive: true, force: true });
+  }
 }
 
 if (process.platform === 'win32') {
@@ -195,6 +284,33 @@ if (process.platform === 'win32') {
   }
 }
 
+// End-to-end: when a .cmd shim sits earlier on PATH than an unrelated real
+// .exe, the runner must actually execute the .cmd (not silently prefer
+// whichever candidate Node's non-shell spawn can launch directly).
+if (process.platform === 'win32') {
+  const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-plugin-sync-order-'));
+  const shadowDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-plugin-sync-shadow-'));
+  const originalPath = process.env.PATH;
+  try {
+    fs.writeFileSync(path.join(fixtureDir, 'harness-order-fixture.cmd'), '@echo off\r\necho current-cmd-shim\r\n');
+    // A real, directly-launchable PE binary standing in for an unrelated,
+    // stale standalone install later on PATH. cmd.exe itself is a stable,
+    // always-present .exe to copy for this purpose.
+    fs.copyFileSync(path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe'), path.join(shadowDir, 'harness-order-fixture.exe'));
+    process.env.PATH = [fixtureDir, shadowDir, originalPath || ''].join(path.delimiter);
+
+    const context = createContext();
+    const result = context.runner('harness-order-fixture', []);
+    assert.strictEqual(result.status, 0, 'the earlier PATH entry must run successfully');
+    assert.match(result.stdout, /current-cmd-shim/, 'an earlier .cmd must be executed even though a later, directly-launchable .exe also matches');
+  } finally {
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+    fs.rmSync(fixtureDir, { recursive: true, force: true });
+    fs.rmSync(shadowDir, { recursive: true, force: true });
+  }
+}
+
 for (const wrapper of ['scripts/plugin-sync.sh', 'scripts/plugin-sync.ps1']) {
   const text = fs.readFileSync(path.join(ROOT, wrapper), 'utf8');
   assert.match(text, /plugin-sync\.js/);

package/docs/architecture.md

@@ -102,13 +102,13 @@ Two kernel mechanisms annotate plans without creating hard workflow enforcement:
 
 ### PreToolUse guard trio and denied-mutation probes
 
-On the Claude hook path, three narrowly scoped `PreToolUse` guards sit alongside the workflow/action gates:
+On the Claude hook path, three narrowly scoped `PreToolUse` guards sit alongside the workflow/action gates. **All three are advisory and fail open — none of them can reject a tool call.** The mechanism that still performs real `exit(2)` hard blocking on this hook is `action-gate.js` (see "Claude Code" below), not this trio.
 
 - `boundary-guard.js` (Grep/Glob/Read): warns about very large reads and noisy search roots; it fails open.
 - `depth-guard.js` (Write): reminds when an existing file would be overwritten without prior inspection. The semantic obligation to establish current target state before destructive overwrite is a **MUST**; the hook itself stays fail-open. New files are unaffected.
 - `context-compact.js`: estimates working-tree context pressure from `git status`/`git diff --numstat` so later stages can compact or halt before lost-in-the-middle degradation.
 
-Shell mutation observation is best-effort evidence for reminders. The old mutation-probe reservation/lock subsystem was retired by #190.
+Shell mutation observation is best-effort evidence for reminders. The old mutation-probe reservation/lock subsystem, and the hard `exit(2)` blocking `boundary-guard.js`/`depth-guard.js` previously performed, were retired by [#190](https://github.com/dyphn1/Harness-everything/issues/190), which reclassified every Harness-owned *cognitive* workflow gate (this trio, plus `stop-gate.js`, `subagent-scope-guard.js`, `atomic-commit-check.js`, `workflow-gate.js`) as a non-blocking reminder. #190 explicitly kept user/host permission and explicit dangerous-action approval boundaries — i.e. `action-gate.js` — out of scope and still enforced.
 
 ## Integration Touchpoints
 
@@ -124,11 +124,11 @@ The installer configures native lifecycle hooks and project skills.
 
 - `SessionStart`: bootstrap/restoration.
 - `UserPromptSubmit`: kernel routing + semantic workflow contract.
-- `PreToolUse`: workflow/boundary/depth/scope reminders, plus separate action permission and Rule-of-3 boundaries.
+- `PreToolUse`: workflow/boundary/depth/scope reminders (all advisory, fail-open), plus the separate `action-gate.js` permission boundary and the Rule-of-3 same-signature-failure boundary.
 - `PostToolUse`: outcomes, state, repeated-failure evidence, stage checks.
 - `Stop`: action-gate audit plus non-blocking workflow/verification reminders.
 
-These hooks make semantic obligations observable; they do not promote cognitive workflow contracts into hard enforcement.
+Cognitive workflow contracts (boundary/depth/scope/commit/workflow guards) are made observable, not hard-enforced — [#190](https://github.com/dyphn1/Harness-everything/issues/190) downgraded their `exit(2)` blocking to reminders. `action-gate.js` and the Rule-of-3 zoom-out boundary are the two mechanisms that still hard-block on this hook path; #190 explicitly scoped both out of that downgrade as user/host permission and dangerous-action safety boundaries.
 
 ### OpenCode — plugin enforcement, scoped live verification
 

package/docs/platform-capabilities.md

@@ -80,11 +80,14 @@ The command detects Claude Code and Codex independently, ensures the Harness mar
 - absent plugin → install;
 - existing Claude Code plugin → `claude plugin update harness-everything@harness-everything`;
 - existing Codex plugin → `codex plugin marketplace upgrade harness-everything`;
+- host without the plugin subcommands at all (a Codex build shipping only `codex plugin marketplace`) → register the marketplace source, then skip with an actionable capability-boundary reason;
 - unknown plugin state → fail closed, with no blind install/re-add.
 
+Mutating commands are issued with the current option set and retried without any option the host rejects, covering both commander wording (`unknown option '--json'`) and clap wording (`unexpected argument '--json' found`), so older Claude and Codex builds stay supported.
+
 The installed branch is intentionally an update branch even when the current release is already the newest version; the host command may report “already latest.” Codex marketplace upgrade is the current native refresh operation; the command does not edit private cache paths or `config.toml`. These are deterministic command/state tests, not live-host evidence, so `liveHostVerification` remains `Unknown` in the matrix.
 
-On Windows, the synchronizer retries through `ComSpec` when Node cannot directly start a CLI shim, so npm-installed `codex.cmd` and `claude.cmd` commands remain discoverable when the wrapper is launched from Git Bash.
+On Windows, the synchronizer resolves `codex`/`claude` the same way an interactive shell does: it walks `PATH` directories in order and tries `PATHEXT` extensions within each directory before moving on, so directory order — not which candidate happens to be a directly launchable `.exe` — decides the match. This matters because Node's non-shell `spawnSync` cannot execute a `.cmd`/`.bat` shim directly and, left to its own resolution, can silently prefer an unrelated, older standalone `.exe` elsewhere on `PATH` over a newer npm-installed shim with no error to signal it. Only the one case Windows genuinely requires an interpreter for — a resolved `.cmd`/`.bat` target — is run through `ComSpec`, using the already-resolved absolute path rather than re-resolving the bare command name.
 
 ### Explicit Codex user-hook compatibility fallback
 

package/docs/platform-compatibility.json

@@ -114,7 +114,7 @@
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
         "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "General Harness installer ownership is mechanism-tested. The optional codex-hooks compatibility fallback separately has exact-entry update/uninstall ownership tests and preserves unrelated user hooks; live Codex trust/dispatch still requires host evidence."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
-        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; no live Codex host refresh is preserved."},
+        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; unsupported CLI options are dropped and retried, and a Codex build without codex plugin list/add is reported as an actionable capability-boundary skip. No live Codex host refresh is preserved."},
         "liveHostVerification": {"status": "Unknown", "notes": "No preserved Codex plugin/session artifact proves current bundled-hook entry. Native plugin mounting is preferred; the explicit user-hook fallback is mechanism-verified only and does not solve host carriers that bypass hook dispatch."}
       }
     },

package/docs/troubleshooting.md

@@ -197,6 +197,13 @@ npx github:dyphn1/Harness-everything plugin-sync --json
 
 The command installs only when the plugin is absent. An installed Claude plugin uses the explicit Claude update command; an installed Codex plugin uses marketplace upgrade. If plugin state cannot be read, synchronization stops without re-adding or overwriting the plugin.
 
+Host CLIs differ in which options and subcommands they implement, so the synchronizer degrades instead of failing:
+
+- An option the host rejects — `unknown option '--json'` (commander) or `unexpected argument '--json' found` (clap/Codex) — is dropped and the command is retried without it.
+- A Codex build that ships only `codex plugin marketplace` has no `codex plugin list`/`codex plugin add`. The marketplace source is still registered and the host is reported as `[skip] codex: …` with an actionable reason, not as a failure. Upgrade the Codex CLI, or enable the plugin from Codex, to complete installation.
+
+If several `codex`/`claude` binaries are on `PATH` (for example an npm shim plus a separately installed build), the synchronizer resolves the same one your interactive shell would: it walks `PATH` directories in order and, on Windows, tries `PATHEXT` extensions within each directory before moving to the next — matching `cmd.exe`/PowerShell/`which` resolution, so directory order decides the match, not which candidate happens to be a directly launchable `.exe`. If the reported capabilities still look stale, an orphaned install is genuinely earlier on `PATH` than the one you expect; check `where codex` (Windows) or `which -a codex` (POSIX) to see the full resolution order, and remove or reorder the stale entry.
+
 See [openai-plugin.md](openai-plugin.md) for installation and validation details.
 
 ### Public OpenAI Skills-only plugin behaves differently from local Codex plugin

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.20.4",
+  "version": "0.20.6",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/sbom.cdx.json

@@ -2,23 +2,23 @@
   "$schema": "https://cyclonedx.org/schema/bom-1.7.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.7",
-  "serialNumber": "urn:uuid:478ab7f0-6aaf-55ae-9e1a-9e950ea30f9d",
+  "serialNumber": "urn:uuid:dad0ee6f-3060-5d2e-a044-10420f0fa6e3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-22T02:13:44.851Z",
+    "timestamp": "2026-09-22T15:27:33.748Z",
     "tools": [
       {
         "vendor": "Harness Everything",
         "name": "generate-sbom.js",
-        "version": "0.20.4"
+        "version": "0.20.6"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/harness-everything@0.20.4",
+      "bom-ref": "pkg:npm/harness-everything@0.20.6",
       "name": "harness-everything",
-      "version": "0.20.4",
-      "purl": "pkg:npm/harness-everything@0.20.4"
+      "version": "0.20.6",
+      "purl": "pkg:npm/harness-everything@0.20.6"
     }
   },
   "components": [
@@ -1999,7 +1999,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/harness-everything@0.20.4",
+      "ref": "pkg:npm/harness-everything@0.20.6",
       "dependsOn": [
         "pkg:npm/%40commitlint/cli@19.8.1",
         "pkg:npm/%40commitlint/config-conventional@19.8.1",

package/scripts/plugin-sync.js

@@ -11,6 +11,8 @@
  */
 
 const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
 
 const DEFAULTS = Object.freeze({
   marketplace: 'harness-everything',
@@ -19,17 +21,83 @@ const DEFAULTS = Object.freeze({
   ref: process.env.HARNESS_PLUGIN_REF || 'main'
 });
 
+// Windows CLIs that ship as a .cmd/.bat shim are not executable via the same
+// direct CreateProcess call Node uses for a .exe, and — unlike a real shell —
+// Node's non-shell spawnSync does not search PATHEXT-suffixed candidates for
+// a bare command name at all. When more than one `codex`/`claude` is on
+// PATH (an npm shim plus a separately installed .exe is a common pairing),
+// the non-shell spawn silently resolves whichever entry happens to be a real
+// .exe, regardless of PATH order — so an unrelated, older standalone install
+// can shadow a newer npm-updated shim with no error to signal it.
+//
+// resolveOnPath() replicates what a real shell / `where.exe` does instead:
+// walk PATH directories in order, and within each directory try PATHEXT
+// extensions in order, returning the first match. Directory order wins over
+// extension preference, exactly like cmd.exe and PowerShell's own lookup, so
+// the result matches what typing the command in a terminal would run.
+function resolveOnPath(command, { pathValue = process.env.PATH || process.env.Path || '', pathExt = process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD' } = {}) {
+  if (path.isAbsolute(command)) return fs.existsSync(command) ? command : null;
+
+  const dirs = pathValue.split(path.delimiter).filter(Boolean);
+  const extensions = pathExt.split(';').map(ext => ext.trim()).filter(Boolean);
+  const hasKnownExtension = extensions.some(ext => command.toLowerCase().endsWith(ext.toLowerCase()));
+
+  for (const dir of dirs) {
+    if (hasKnownExtension) {
+      const candidate = path.join(dir, command);
+      if (fs.existsSync(candidate)) return candidate;
+      continue;
+    }
+    for (const ext of extensions) {
+      const candidate = path.join(dir, command + ext);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+// A .bat/.cmd target is not a Win32 executable image; Windows requires the
+// cmd.exe interpreter to run one at all, the same way a shebang-less script
+// needs an explicit interpreter on POSIX. This is the one case a shell is
+// unavoidable, and only that resolved file is passed to it — never the bare
+// command name or user-controlled arguments re-interpreted as a command line.
+const SHELL_REQUIRED_EXTENSIONS = new Set(['.bat', '.cmd']);
+
+function runResolved(resolved, args, options) {
+  const ext = path.extname(resolved).toLowerCase();
+  if (SHELL_REQUIRED_EXTENSIONS.has(ext)) {
+    const comspec = process.env.ComSpec || process.env.COMSPEC || 'cmd.exe';
+    return spawnSync(comspec, ['/d', '/c', resolved, ...args], options);
+  }
+  return spawnSync(resolved, args, options);
+}
+
 function defaultRunner(command, args) {
   const options = {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
     windowsHide: true
   };
+
+  if (process.platform === 'win32') {
+    const resolved = resolveOnPath(command);
+    if (resolved) {
+      const result = runResolved(resolved, args, options);
+      return {
+        status: result.status === null ? 1 : result.status,
+        stdout: result.stdout || '',
+        stderr: result.stderr || '',
+        error: result.error || null
+      };
+    }
+  }
+
   let result = spawnSync(command, args, options);
 
-  // npm-installed Windows CLIs are often .cmd shims. Node can report those
-  // shims as an executable-resolution error when this script is launched from
-  // Git Bash, even though the same command is available to the shell.
+  // Resolution above only checks the filesystem; if PATH itself could not be
+  // read, or the command is reachable through a mechanism resolveOnPath does
+  // not model (e.g. an App Execution Alias), fall back to letting the shell
+  // do its own resolution rather than failing outright.
   if (process.platform === 'win32' && result.error && ['EACCES', 'EINVAL', 'ENOENT'].includes(result.error.code)) {
     const comspec = process.env.ComSpec || process.env.COMSPEC || 'cmd.exe';
     result = spawnSync(comspec, ['/d', '/c', command, ...args], options);
@@ -189,41 +257,73 @@ function query(context, command, args) {
   return context.runner(command, args, { query: true }) || { status: 1, stdout: '', stderr: 'runner returned no result' };
 }
 
-function hasUnknownOption(result, option) {
-  const output = [result && result.stderr, result && result.stdout, result && result.error && result.error.message]
+function resultText(result) {
+  return [result && result.stderr, result && result.stdout, result && result.error && result.error.message]
     .map(value => String(value || ''))
     .join('\n');
-  return new RegExp(`unknown option\\s+['"]?${escapeRegExp(option)}['"]?`, 'i').test(output);
 }
 
-function runClaudePluginMutation(context, action, pluginId) {
-  const baseArgs = [
-    'plugin', action, pluginId,
-    '--scope', 'user'
-  ];
-  let args = [...baseArgs, '--yes', '--json'];
+// Host CLIs disagree on how they reject an option they never implemented:
+// commander-based CLIs (Claude) say "unknown option '--json'", while
+// clap-based CLIs (Codex) say "unexpected argument '--json' found". Both mean
+// the same thing, so compatibility retries must recognize either wording.
+function hasUnsupportedOption(result, option) {
+  const output = resultText(result);
+  const name = escapeRegExp(option);
+  return [
+    `unknown option\\s+['"]?${name}['"]?`,
+    `unrecognized option\\s+['"]?${name}['"]?`,
+    `unexpected argument\\s+['"]?${name}['"]?`,
+    `found argument\\s+['"]?${name}['"]?`
+  ].some(pattern => new RegExp(pattern, 'i').test(output));
+}
+
+// A host build that never shipped the subcommand is a capability boundary, not
+// a transient failure, so it must be reported differently from a broken call.
+function hasUnsupportedSubcommand(result, subcommand) {
+  const expression = new RegExp(
+    `(unrecognized|unknown|invalid)\\s+(sub)?command\\s+['"]?${escapeRegExp(subcommand)}['"]?`,
+    'i'
+  );
+  return expression.test(resultText(result));
+}
+
+// Optional arguments are dropped one at a time so a host that implements only
+// some of them still reaches a command it accepts.
+function runHostMutation(context, command, baseArgs, optionalArgs, label) {
+  let args = [...baseArgs, ...optionalArgs];
   let attempt = 0;
 
   while (true) {
-    const result = invoke(context, 'claude', args, {
+    const result = invoke(context, command, args, {
       mutate: true,
-      label: attempt === 0 ? `claude plugin ${action}` : `claude plugin ${action} compatibility retry`,
+      label: attempt === 0 ? label : `${label} compatibility retry`,
       warnOnFailure: false
     });
     if (result.status === 0) return result;
 
-    const unsupported = ['--yes', '--json'].find(option => args.includes(option) && hasUnknownOption(result, option));
+    const unsupported = optionalArgs.find(option => args.includes(option) && hasUnsupportedOption(result, option));
     if (!unsupported) {
-      context.warn(`[failed] ${commandLine('claude', args)}\n  ${resultError(result)}`);
+      context.warn(`[failed] ${commandLine(command, args)}\n  ${resultError(result)}`);
       return result;
     }
 
     args = args.filter(arg => arg !== unsupported);
     attempt += 1;
-    context.warn(`[notice] Claude CLI does not support ${unsupported}; retrying ${action} without that option.`);
+    context.warn(`[notice] ${command} CLI does not support ${unsupported}; retrying ${label} without that option.`);
   }
 }
 
+function runClaudePluginMutation(context, action, pluginId) {
+  return runHostMutation(
+    context,
+    'claude',
+    ['plugin', action, pluginId, '--scope', 'user'],
+    ['--yes', '--json'],
+    `claude plugin ${action}`
+  );
+}
+
 function listState(context, { command, jsonArgs, plainArgs, detectJson, detectText }) {
   const jsonResult = query(context, command, jsonArgs);
   if (jsonResult.status === 0) {
@@ -239,6 +339,7 @@ function listState(context, { command, jsonArgs, plainArgs, detectJson, detectTe
   return {
     known: false,
     value: false,
+    attempts: [jsonResult, plainResult],
     error: `${resultError(jsonResult)}; fallback: ${resultError(plainResult)}`
   };
 }
@@ -312,11 +413,13 @@ function ensureCodexMarketplace(context) {
   const state = queryCodexMarketplace(context);
   if (!state.known) context.warn(`[notice] Codex marketplace state is unavailable; ensuring ${context.marketplace} is configured.`);
   if (!state.known || !state.value) {
-    const added = invoke(context, 'codex', [
-      'plugin', 'marketplace', 'add', context.repositorySource,
-      '--ref', context.ref,
-      '--json'
-    ], { mutate: true, label: 'codex marketplace add' });
+    const added = runHostMutation(
+      context,
+      'codex',
+      ['plugin', 'marketplace', 'add', context.repositorySource, '--ref', context.ref],
+      ['--json'],
+      'codex marketplace add'
+    );
     if (added.status !== 0) return { ok: false, error: resultError(added) };
   }
   return { ok: true };
@@ -332,10 +435,13 @@ function refreshClaudeMarketplace(context) {
 }
 
 function refreshCodexMarketplace(context) {
-  const upgraded = invoke(context, 'codex', [
-    'plugin', 'marketplace', 'upgrade', context.marketplace,
-    '--json'
-  ], { mutate: true, label: 'codex marketplace upgrade' });
+  const upgraded = runHostMutation(
+    context,
+    'codex',
+    ['plugin', 'marketplace', 'upgrade', context.marketplace],
+    ['--json'],
+    'codex marketplace upgrade'
+  );
   return upgraded.status === 0
     ? { ok: true }
     : { ok: false, error: resultError(upgraded) };
@@ -350,7 +456,7 @@ function verifyPlugin(context, host, queryPlugin) {
 }
 
 function syncClaude(context) {
-  if (!context.commandAvailable('claude')) return { host: 'claude', status: 'skipped', reason: 'claude CLI not found' };
+  if (!context.commandAvailable('claude')) return { host: 'claude', status: 'skipped', reasonCode: 'cli-not-found', reason: 'claude CLI not found' };
   const marketplace = ensureClaudeMarketplace(context);
   if (!marketplace.ok) return { host: 'claude', status: 'failed', error: marketplace.error };
   const installed = queryClaudePlugin(context);
@@ -372,11 +478,25 @@ function syncClaude(context) {
 }
 
 function syncCodex(context) {
-  if (!context.commandAvailable('codex')) return { host: 'codex', status: 'skipped', reason: 'codex CLI not found' };
+  if (!context.commandAvailable('codex')) return { host: 'codex', status: 'skipped', reasonCode: 'cli-not-found', reason: 'codex CLI not found' };
   const marketplace = ensureCodexMarketplace(context);
   if (!marketplace.ok) return { host: 'codex', status: 'failed', error: marketplace.error };
   const installed = queryCodexPlugin(context);
-  if (!installed.known) return { host: 'codex', status: 'failed', error: `Codex plugin state could not be determined: ${installed.error}` };
+  if (!installed.known) {
+    // A Codex build that ships only `codex plugin marketplace` cannot report
+    // or change plugin state at all. The marketplace source is now registered,
+    // which is everything this build supports, so report the host boundary
+    // instead of a generic failure.
+    if ((installed.attempts || []).some(attempt => hasUnsupportedSubcommand(attempt, 'list'))) {
+      return {
+        host: 'codex',
+        status: 'skipped',
+        reasonCode: 'host-capability-boundary',
+        reason: `this Codex CLI has no \`codex plugin list\` command, so plugin state cannot be read; ${context.marketplace} is registered as a marketplace source — enable the plugin from Codex, or upgrade the Codex CLI to a build that ships \`codex plugin list\`/\`codex plugin add\``
+      };
+    }
+    return { host: 'codex', status: 'failed', error: `Codex plugin state could not be determined: ${installed.error}` };
+  }
 
   let action;
   let result;
@@ -392,9 +512,13 @@ function syncCodex(context) {
     action = 'install';
     result = refreshCodexMarketplace(context);
     if (result.ok) {
-      result = invoke(context, 'codex', [
-        'plugin', 'add', `${context.plugin}@${context.marketplace}`, '--json'
-      ], { mutate: true, label: 'codex plugin install' });
+      result = runHostMutation(
+        context,
+        'codex',
+        ['plugin', 'add', `${context.plugin}@${context.marketplace}`],
+        ['--json'],
+        'codex plugin install'
+      );
     } else {
       result = { status: 1, stdout: '', stderr: result.error };
     }
@@ -488,7 +612,9 @@ function main(argv = process.argv.slice(2)) {
       else console.error(`[fail] ${result.host}: ${result.error}`);
     }
     if (summary.synchronized === 0 && summary.failed === 0) {
-      console.error('No supported host CLI was found. Install Claude Code and/or Codex, then retry.');
+      console.error(summary.results.every(result => result.reasonCode === 'cli-not-found')
+        ? 'No supported host CLI was found. Install Claude Code and/or Codex, then retry.'
+        : 'No host plugin was synchronized. Review the skip reasons above.');
     }
   }
   return summary.failed > 0 || summary.synchronized === 0 ? 1 : 0;
@@ -505,6 +631,7 @@ module.exports = {
   main,
   parseArgs,
   parseJsonOutput,
+  resolveOnPath,
   sync,
   textHasMarketplace,
   textHasPlugin