harness-everything 0.20.3 → 0.20.5

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.3",
+      "version": "0.20.5",
       "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.3",
+  "version": "0.20.5",
   "author": {
     "name": "Miya Daniel"
   },

package/.github/workflows/release.yml

@@ -68,3 +68,11 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           NPM_CONFIG_PROVENANCE: "true"
         run: npx --no-install semantic-release
+
+      - name: Upload release SBOM artifact
+        if: ${{ hashFiles('sbom.cdx.json') != '' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-sbom
+          path: sbom.cdx.json
+          if-no-files-found: error

package/.releaserc.json

@@ -103,6 +103,12 @@
     [
       "@semantic-release/github",
       {
+        "assets": [
+          {
+            "path": "sbom.cdx.json",
+            "label": "CycloneDX SBOM"
+          }
+        ],
         "successComment": false,
         "failTitle": false,
         "labels": false,

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project are documented in this file.
 
+## [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
+
+* **release:** publish sbom release artifacts ([83eeb96](https://github.com/dyphn1/Harness-everything/commit/83eeb96c1746ccbffcdcba478ba6b54c522887a0)), closes [#222](https://github.com/dyphn1/Harness-everything/issues/222)
+
 ## [0.20.3](https://github.com/dyphn1/Harness-everything/compare/v0.20.2...v0.20.3) (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/RELEASING.md

@@ -40,9 +40,9 @@ A push to `main` runs the full reusable CI gate and then semantic-release. A man
 6. Run `scripts/sync-release-version.js` to synchronize package, Claude, OpenAI/Codex, OpenCode, lockfile, and changed canonical skill version fields.
 7. Regenerate and verify plugin packages, then generate and validate the release-only `sbom.cdx.json` CycloneDX 1.7 file.
 8. Update `CHANGELOG.md` and create `chore(release): X.Y.Z [skip ci]`.
-9. Create tag `vX.Y.Z`, publish npm with provenance (including the generated SBOM), and create the GitHub Release.
+9. Create tag `vX.Y.Z`, publish npm with provenance (including the generated SBOM), create the GitHub Release with the SBOM attached, and retain the same file as an Actions artifact.
 
-The SBOM is generated from the release `package.json`/`package-lock.json` as CycloneDX 1.7, the current 1.x format, to satisfy consumers and regulatory baselines requiring CycloneDX 1.6 or later. It is intentionally not committed to Git. npm packaging is tested to ensure `sbom.cdx.json` is included in the published tarball.
+The SBOM is generated from the release `package.json`/`package-lock.json` as CycloneDX 1.7, the current 1.x format, to satisfy consumers and regulatory baselines requiring CycloneDX 1.6 or later. It is intentionally not committed to Git. The release publishes `sbom.cdx.json` in the npm tarball and as a GitHub Release asset, while the workflow also retains it as an Actions artifact.
 
 Release concurrency is serialized so two updates to `main` cannot publish competing versions.
 
@@ -90,7 +90,8 @@ The release workflow runs the reusable CI gate before semantic-release. After pu
 ```text
 gh run list --workflow release.yml --limit 5
 gh run view <run-id> --json conclusion,headSha,jobs
-gh release view v<version> --json tagName,publishedAt,url
+gh release view v<version> --json tagName,publishedAt,url,assets
+gh run view <run-id> --json conclusion,headSha,jobs,artifacts
 npm view harness-everything version dist-tags --json
 ```
 

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

@@ -14,7 +14,7 @@ const {
 
 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 +59,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 +186,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 +234,7 @@ 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');
 }
 
 if (process.platform === 'win32') {

package/ci/mechanism-2ap-sbom.test.js

@@ -24,6 +24,22 @@ assert.ok(execPlugin, 'semantic-release exec plugin is required for SBOM generat
 assert.match(execPlugin[1].prepareCmd, /generate-sbom\.js --output sbom\.cdx\.json --version \$\{nextRelease\.version\}/);
 assert.match(execPlugin[1].prepareCmd, /generate-sbom\.js --validate sbom\.cdx\.json --version \$\{nextRelease\.version\}/);
 
+const githubPlugin = releaseConfig.plugins.find(plugin => Array.isArray(plugin) && plugin[0] === '@semantic-release/github');
+assert.ok(githubPlugin, 'semantic-release github plugin is required for release publication');
+assert.ok(Array.isArray(githubPlugin[1].assets), 'GitHub Release assets must be configured');
+assert.ok(
+  githubPlugin[1].assets.some(asset => asset && typeof asset === 'object' && asset.path === 'sbom.cdx.json'),
+  'GitHub Release must publish the generated SBOM as an asset'
+);
+
+const releaseWorkflow = fs.readFileSync(path.join(ROOT, '.github/workflows/release.yml'), 'utf8');
+assert.match(releaseWorkflow, /uses:\s+actions\/upload-artifact@v4/,
+  'release workflow must retain the generated SBOM as an Actions artifact');
+assert.match(releaseWorkflow, /if:\s+\$\{\{\s*hashFiles\('sbom\.cdx\.json'\)\s*!=\s*''\s*\}\}/,
+  'release workflow must skip artifact upload when semantic-release has no release');
+assert.match(releaseWorkflow, /path:\s+sbom\.cdx\.json/,
+  'release workflow artifact must point at the generated SBOM');
+
 const bom = buildBom(ROOT, {
   version: packageJson.version,
   timestamp: '2026-09-21T00:00:00.000Z',

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,8 +80,11 @@ 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.

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` binaries are on `PATH` (for example an npm shim plus an installer-managed build), the synchronizer runs whichever one Node resolves first, which may be older than the one your interactive shell picks up. Compare `codex --version` with `node -e "console.log(require('child_process').spawnSync('codex',['--version'],{encoding:'utf8'}).stdout)"` when the reported capabilities look wrong.
+
 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.3",
+  "version": "0.20.5",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "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.3",
+  "version": "0.20.5",
   "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.3",
+  "version": "0.20.5",
   "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:c82181bb-3272-5951-8990-f785d038f412",
+  "serialNumber": "urn:uuid:2fe1f791-72b1-528d-91ab-182e028b8f11",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-09-22T01:49:40.805Z",
+    "timestamp": "2026-09-22T14:48:08.473Z",
     "tools": [
       {
         "vendor": "Harness Everything",
         "name": "generate-sbom.js",
-        "version": "0.20.3"
+        "version": "0.20.5"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/harness-everything@0.20.3",
+      "bom-ref": "pkg:npm/harness-everything@0.20.5",
       "name": "harness-everything",
-      "version": "0.20.3",
-      "purl": "pkg:npm/harness-everything@0.20.3"
+      "version": "0.20.5",
+      "purl": "pkg:npm/harness-everything@0.20.5"
     }
   },
   "components": [
@@ -1999,7 +1999,7 @@
       ]
     },
     {
-      "ref": "pkg:npm/harness-everything@0.20.3",
+      "ref": "pkg:npm/harness-everything@0.20.5",
       "dependsOn": [
         "pkg:npm/%40commitlint/cli@19.8.1",
         "pkg:npm/%40commitlint/config-conventional@19.8.1",

package/scripts/plugin-sync.js

@@ -189,41 +189,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 +271,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 +345,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 +367,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 +388,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 +410,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 +444,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 +544,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;