Add Junie as a built-in agent (junie --acp true)

[mashan555]

feat: add JetBrains Junie as a built-in agent

What Problem This Solves
Users who work with JetBrains Junie could not target it directly through acpx — there was no junie built-in agent, so acpx junie ... did not resolve to a known harness. This change adds Junie to the built-in agent registry so it is available as a first-class native agent alongside the other supported harnesses in the acpx CLI.

Why This Change Was Made
Junie already ships a compliant ACP stdio mode junie --acp true and its ACP adapter correctly advertises persistent-session capabilities loadSession + sessionCapabilities.resume, so it works over the standard native ACP path with no adapter package and no agent-specific glue in src/acp/client.ts. The change is intentionally minimal: register the launch command and update the documentation surfaces required by repo policy. Non-goal: no changes to docs/CLI.md main-landing docs stay impartial and only name pi, openclaw, codex, claude, and no adapter version specifiers in docs.

User Impact
Users can now run Junie directly through acpx, for example:

acpx junie exec 'echo hello'
acpx junie sessions new --name docs
acpx junie -s docs 'rewrite CLI docs'

Named sessions reopen across processes persistent mode because acpx detects Junie's capabilities automatically. Junie must be installed and authenticated locally — acpx never installs it. The one intentional limitation is that exec/prompt without a named session is one-shot by design.

Evidence
• test/agent-registry.test.ts: resolution junie, JUNIE, whitespace, "native, not via adapter", and presence in listBuiltInAgents.
• test/integration.test.ts: writeFakeJunieAgent helper + e2e test that acpx junie exec 'echo hello' resolves to junie --acp true and returns exit code 0 with hello output.
• pnpm run check format, typecheck, lint, build, viewer build, coverage tests passes; pnpm run check:docs passes.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 24, 2026, 7:17 AM ET / 11:17 UTC.

ClawSweeper review

What this changes

The PR registers JetBrains Junie as the junie built-in ACP agent using junie --acp true, with registry and integration coverage plus synchronized agent documentation.

Merge readiness

⛔ Blocked until real behavior proof from a real setup is added - 6 items remain

Keep this PR open for maintainer product-direction review and real Junie runtime proof: it adds a permanent built-in keyword that changes how an existing raw acpx junie invocation resolves, while the submitted test exercises only a fake executable.

Priority: P2
Reviewed head: facd630161e6b02994adf3d49b89dbf587c1716b
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The patch is focused and documented, but its compatibility contract is unresolved and the vendor-runtime claim has only mock coverage.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The PR body reports checks, and the test uses a fake junie shim, but there is no after-fix live Junie run showing the actual CLI accepts --acp true and completes the claimed ACP flow; post a redacted terminal transcript or recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The PR body reports checks, and the test uses a fake junie shim, but there is no after-fix live Junie run showing the actual CLI accepts --acp true and completes the claimed ACP flow; post a redacted terminal transcript or recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	4 items	Current registry fallback is raw-command compatible: On current main, resolveAgentCommand returns the supplied name when it is not in the built-in registry. Adding junie therefore changes an existing acpx junie invocation from a raw junie command to the fixed junie --acp true launch command. The PR changes that resolution path: The proposed registry entry adds the permanent junie keyword and fixed ACP arguments; its tests verify the new mapping but do not cover an existing custom/raw Junie launch or a configuration override. Runtime proof is mock-only: The integration test writes a fake junie executable that strips --acp true before passing control to the repository mock ACP agent. It proves acpx command construction, not the behavior of an installed and authenticated Junie CLI or its persistent-session capabilities.
Findings	1 actionable finding	[P1] Preserve raw-command compatibility for junie
Security	None	None.

How this fits together

The built-in agent registry converts a short CLI agent name into the command acpx starts as an ACP server. That launch command then feeds session creation, prompt execution, and persistent-session recovery, so each new name becomes part of the stable CLI command surface.

flowchart LR
  User[Agent or operator command] --> Name[Built-in agent name]
  Name --> Registry[Built-in registry]
  Registry --> Launch[ACP launch command]
  Launch --> Client[ACP client session]
  Client --> Runtime[Prompt and session runtime]
  Runtime --> Output[Structured CLI output]

Loading

Decision needed

Question	Recommendation
Should acpx reserve junie as a permanent built-in name even though that changes the existing raw-command fallback for acpx junie?	Adopt Junie with compatibility proof: Approve junie as a core built-in after documenting or testing the supported override/migration path and receiving real Junie ACP evidence.

Why: The implementation adds a durable user-facing naming convention and changes an existing invocation path; repository policy treats such conventions as compatibility-sensitive product surface, so code review cannot determine the intended contract alone.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The PR body reports checks, and the test uses a fake junie shim, but there is no after-fix live Junie run showing the actual CLI accepts --acp true and completes the claimed ACP flow; post a redacted terminal transcript or recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Preserve raw-command compatibility for `junie` (P1) - resolveAgentCommand currently returns an unknown name unchanged, so existing acpx junie workflows launch their local command exactly as configured. This registry entry silently changes them to junie --acp true; preserve or explicitly document and test the supported override/migration path before reserving the name.
• Resolve merge risk (P1) - Merging reserves junie as a built-in name and silently appends --acp true for existing raw-command users, potentially changing locally customized Junie launch behavior without an upgrade path.
• Resolve merge risk (P1) - The claimed native Junie ACP and persistent-session behavior has no after-fix evidence from a real installed, authenticated Junie setup; the fake executable cannot reveal vendor CLI argument, handshake, or resume incompatibilities.
• Complete next step (P2) - A maintainer must choose the permanent junie naming and compatibility contract, and the external contributor must supply real Junie runtime proof before normal merge review can complete.

Findings

• [P1] Preserve raw-command compatibility for junie — src/agent-registry.ts:51

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Review surface	9 files changed; 108 additions; 0 deletions	A one-line registry change is accompanied by tests and four documentation surfaces, so the main merge question is contract validation rather than code volume.
New public keyword	1 built-in name: junie	The keyword alters CLI resolution for a previously unknown agent name and therefore needs explicit compatibility intent.

Merge-risk options

Maintainer options:

1. Prove and document the compatibility path (recommended)
   Keep the built-in only after adding focused coverage or documentation for existing raw/custom junie users and posting redacted real-runtime proof.
2. Accept the reserved-name break
   Maintainers may intentionally reserve junie, but should record that existing raw acpx junie workflows must use the documented override path.
3. Pause the built-in addition
   Do not add the keyword if the team does not want to own the permanent naming and upgrade contract.

Technical review

Best possible solution:

Choose whether junie should be a permanent core keyword, preserve an explicit escape hatch for pre-existing raw/custom Junie commands, and then add redacted live evidence covering a real one-shot call and named-session reopen before merge.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug report. For the PR's runtime claim, no high-confidence real reproduction is provided: the included integration test uses a fake Junie executable rather than an installed and authenticated Junie CLI.

Is this the best way to solve the issue?

Unclear. Adding a native ACP command is mechanically narrow, but reserving a durable CLI name and changing its former raw-command behavior needs maintainer approval plus real Junie validation before this is the best supported path.

Full review comments:

• [P1] Preserve raw-command compatibility for junie — src/agent-registry.ts:51
resolveAgentCommand currently returns an unknown name unchanged, so existing acpx junie workflows launch their local command exactly as configured. This registry entry silently changes them to junie --acp true; preserve or explicitly document and test the supported override/migration path before reserving the name.
  Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 26b740e81038.

Labels

Label changes:

• add P2: This is a bounded compatibility and validation concern for a new built-in agent, without evidence of a current outage or data-loss path.
• add merge-risk: 🚨 compatibility: Registering junie changes the existing unknown-name fallback from a raw command to a fixed junie --acp true launch command.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports checks, and the test uses a fake junie shim, but there is no after-fix live Junie run showing the actual CLI accepts --acp true and completes the claimed ACP flow; post a redacted terminal transcript or recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a bounded compatibility and validation concern for a new built-in agent, without evidence of a current outage or data-loss path.
• merge-risk: 🚨 compatibility: Registering junie changes the existing unknown-name fallback from a raw command to a fixed junie --acp true launch command.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body reports checks, and the test uses a fake junie shim, but there is no after-fix live Junie run showing the actual CLI accepts --acp true and completes the claimed ACP flow; post a redacted terminal transcript or recording before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Current registry fallback is raw-command compatible: On current main, resolveAgentCommand returns the supplied name when it is not in the built-in registry. Adding junie therefore changes an existing acpx junie invocation from a raw junie command to the fixed junie --acp true launch command. (src/agent-registry.ts:48, 26b740e81038)
• The PR changes that resolution path: The proposed registry entry adds the permanent junie keyword and fixed ACP arguments; its tests verify the new mapping but do not cover an existing custom/raw Junie launch or a configuration override. (src/agent-registry.ts:51, facd630161e6)
• Runtime proof is mock-only: The integration test writes a fake junie executable that strips --acp true before passing control to the repository mock ACP agent. It proves acpx command construction, not the behavior of an installed and authenticated Junie CLI or its persistent-session capabilities. (test/integration.test.ts:929, facd630161e6)
• Repository policy requires deliberate user-visible conventions: The checked repository policy and VISION.md describe agent names and launch conventions as product surface, favoring fewer stable conventions; the PR correctly updates the required skill and agent documentation but still needs an explicit decision on reserving this name. (VISION.md:6, 26b740e81038)

Likely related people:

• mashan555: Authored the sole PR commit and supplied the claimed Junie ACP launch and session-capability rationale; no independent current-main ownership trail was available in the supplied review material. (role: proposed implementation author; confidence: medium; commits: facd630161e6; files: src/agent-registry.ts, test/integration.test.ts, agents/Junie.md)
• kelvinschen: Current Unreleased history credits this person for a recent built-in adapter-range refresh, an adjacent registry and compatibility surface; the provided material does not establish exclusive ownership. (role: recent adjacent contributor; confidence: low; commits: 26b740e81038; files: CHANGELOG.md, src/agent-registry.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Post redacted real Junie terminal evidence for a one-shot ACP request and a named session reopened in a second process.
• Add a focused compatibility or documentation path for existing raw/custom acpx junie use before reserving the keyword.
• Ask for a fresh ClawSweeper review after updating the PR body; if it does not trigger, ask a maintainer to comment @clawsweeper re-review.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.