fix(kiro): self-healing MCP path resolution in dev checkouts, bump to 2.4.1

[jampetz]

What & why

When a developer clones the repo and opens it directly in AWS Kiro without running install-kiro.sh, the MCP server failed to start. .mcp.kiro.json's ${KIRO_PLUGIN_ROOT:-$PWD/.kiro/..} fallback resolved to the repo root (since .kiro/ lives there), not plugins/simulator/, so it tried to run the nonexistent /mcp-server/run.sh instead of /plugins/simulator/mcp-server/run.sh. The bug only surfaced in local dev — an installed plugin has KIRO_PLUGIN_ROOT set correctly by the host.

Fixes:

• .mcp.kiro.json — probes for mcp-server/run.sh at the resolved path and falls back to appending plugins/simulator/ when it's missing, so both the installed-plugin and dev-checkout layouts resolve correctly without any install step.
• install-kiro.sh — now sed-resolves the same KIRO_PLUGIN_ROOT fallback to the absolute plugin path when generating a workspace's mcp.json, instead of a plain copy. An externally-installed workspace's config is now self-contained and no longer depends on KIRO_PLUGIN_ROOT being set at runtime at all.
• README.md — Kiro install instructions updated: the install command now shows sh plugins/simulator/scripts/install-kiro.sh ., and the surrounding text documents both fixes.
• .gitignore — added .env and .kiro (workspace-local Kiro overlay, generated by install-kiro.sh, must not be committed).

Type of change

• Bug fix
• New MCP tool / capability
• Skill behaviour
• Docs
• Chore / refactor

Checklist

• make build && make vet pass locally
• If I added/renamed a tool — N/A, no tool changes
• If I changed skill frontmatter — N/A, no skill changes
• Reference docs that skills load at runtime stay under plugins/simulator/docs/ — N/A, untouched
• No tokens or .env committed; TLS verification left on by default
• Version bumped in all manifests (.claude-plugin/plugin.json, .kiro-plugin/plugin.json, .codex-plugin/plugin.json,CHANGELOG.md entry added — 2.4.0 → 2.4.1

Notes for reviewers

Manually verified all three scenarios: installed-plugin path (KIRO_PLUGIN_ROOT pre-set), dev-checkout path (unset, probequires .kiro/ to already exist as a directory, which it will since that's where mcp.json itself lives), andinstall-kiro.sh against an external workspace (generated mcp.json has a valid, hardcoded absolute path; resolved run.sh path is correct).

[gh-corezoid]

AI Review

Kiro path-resolution bug fix with version bump 2.4.0→2.4.1; two issues found: commit subject line 5 chars over limit and POWER.md version not updated.

Checklist

Check	Result
U1 Conventional commit format	⚠️ warning — subject is 75 chars (limit 70): fix(kiro): self-healing MCP path resolution in dev checkouts, bump to 2.4.1
U2 No leaked credentials	✅ pass
U3 No merge commits	✅ pass — 1 commit, 1 parent
U4 Correct base branch	✅ pass — targets develop
U5 Build & tests (Go)	⏭️ skip — no *.go files changed
U6 Architectural/design	⚠️ advisory — see notes below
S1 No manual edits to public/	✅ pass — public/ not touched
S2 API path parameter names	⏭️ skip — no internal/tools/ Go changes
S3 Eval scenarios for new tools	⏭️ skip — no new tools added
S4 Discovery artifacts committed	⏭️ skip — no internal/ changes
S5 Manifest files version-synced	❌ error — POWER.md still has version: 2.4.0; all other 5 manifests were bumped to 2.4.1
S6 README/ARCHITECTURE updated	✅ pass — no new tools; README updated for Kiro install instructions

Issues found

[error] S5 — POWER.md version not bumped
POWER.md frontmatter still reads version: 2.4.0. Five other manifest files were correctly bumped to 2.4.1, but POWER.md was missed. Per S5, all six manifest files must show the same version when any one of them changes.

Files updated correctly: .agents/plugins/marketplace.json, .claude-plugin/marketplace.json, plugins/simulator/.claude-plugin/plugin.json, plugins/simulator/.codex-plugin/plugin.json, plugins/simulator/.kiro-plugin/plugin.json.

Missing update: POWER.md → change version: 2.4.0 to version: 2.4.1.

---

[warning] U1 — Commit subject line exceeds 70 characters
Subject fix(kiro): self-healing MCP path resolution in dev checkouts, bump to 2.4.1 is 75 characters. Convention requires ≤ 70. Consider shortening, e.g. fix(kiro): self-healing MCP path, bump to 2.4.1 or similar.

---

[advisory] U6 — Architectural notes

1. install-kiro.sh sed delimiter fragility: The sed substitution uses # as a delimiter (sed 's#...#...#g'). If $PLUGIN_ROOT ever contains a literal # character (unusual but possible on some systems), the command will break with a cryptic error. A safer alternative is to escape the replacement string or use a Python/awk one-liner. Low risk for typical installs.

2. .mcp.kiro.json one-shot fallback: The probe-then-append logic (|| PLUGIN_ROOT="$PLUGIN_ROOT/plugins/simulator") is a correct fix for the two known layouts but silently produces a wrong path if neither layout matches, causing a confusing exec failure. Adding a final guard (e.g., [ -f "$PLUGIN_ROOT/mcp-server/run.sh" ] || { echo "ERROR: cannot locate mcp-server/run.sh" >&2; exit 1; }) would give a clearer diagnostic. Advisory only.

---

This review was generated automatically. A human maintainer should still make the merge decision.

[gh-corezoid]

AI Review

Re-review after synchronize: Kiro path-resolution bug fix with version bump 2.4.0→2.4.1; U6 advisory issues addressed by the new commit; S5 error (POWER.md not bumped) and U1 warning (subject line length) remain open.

Checklist

Check	Result
U1 Conventional commit format	⚠️ warning — commit 1 subject is 75 chars (limit 70): fix(kiro): self-healing MCP path resolution in dev checkouts, bump to 2.4.1; commit 2 subject is 48 chars ✅
U2 No leaked credentials	✅ pass
U3 No merge commits	✅ pass — 2 commits, neither is a merge commit
U4 Correct base branch	✅ pass — targets develop
U5 Build & tests (Go)	⏭️ skip — no *.go files changed
U6 Architectural/design	✅ pass — both advisory items from previous review resolved by new commit
S1 No manual edits to public/	✅ pass — public/ not touched
S2 API path parameter names	⏭️ skip — no internal/tools/ Go changes
S3 Eval scenarios for new tools	⏭️ skip — no new tools added
S4 Discovery artifacts committed	⏭️ skip — no internal/ changes
S5 Manifest files version-synced	❌ error — POWER.md still has version: 2.4.0; all other five manifests updated to 2.4.1
S6 README/ARCHITECTURE updated	✅ pass — no new tools; README updated for Kiro install instructions

Issues found

[error] S5 — POWER.md version not bumped (unresolved from previous review)
POWER.md frontmatter still reads version: 2.4.0. The five other manifest files were correctly bumped to 2.4.1 in the first commit, but POWER.md was not included and is absent from both commits in this PR. Per S5, all six manifest files must show the same version when any one of them changes.

Fix: add version: 2.4.1 in the frontmatter of POWER.md.

---

[warning] U1 — Commit 1 subject line exceeds 70 characters (unresolved from previous review)
fix(kiro): self-healing MCP path resolution in dev checkouts, bump to 2.4.1 is 75 characters. The convention requires ≤ 70. This commit predates the synchronize push and its subject is unchanged. Consider an interactive rebase to shorten it, e.g. fix(kiro): self-healing MCP path, bump to 2.4.1 (47 chars).

---

Fixed since last review ✅

• U6 advisory — sed escaping fragility: install-kiro.sh now escapes \, &, and # in PLUGIN_ROOT before splicing into the sed replacement (PLUGIN_ROOT_ESCAPED="$(printf '%s\n' "$PLUGIN_ROOT" | sed 's/[\&#]/\\&/g')"). Resolved by commit d40e4ace.
• U6 advisory — missing run.sh guard: .mcp.kiro.json now verifies mcp-server/run.sh exists at the resolved PLUGIN_ROOT after both the primary probe and the plugins/simulator/ fallback, and exits with a clear error message if neither candidate works. Resolved by commit d40e4ace.

---

This review was generated automatically. A human maintainer should still make the merge decision.