openclaw-code-agent 3.1.0 → 3.2.0

package/README.md

@@ -9,22 +9,61 @@
 - **Plan -> Review -> Execute**. `plan` is the default launch mode, with `ask`, `delegate`, and `approve` deciding how much plan approval autonomy the orchestrator gets.
 - **Optional worktree isolation**. New sessions default to `off`; opt into `ask`, `delegate`, `auto-merge`, or `auto-pr` when you want worktree-backed branch isolation and post-run branch handling.
 - **State-driven decision UX**. `ask` sends explicit action buttons for **Merge locally**, **Create PR**, **Decide later**, and **Dismiss**. The same action-token model now backs both Telegram and Discord interactive callbacks.
+- **Lifecycle-first cleanup**. Worktrees are treated as temporary task sandboxes. The plugin distinguishes `merged` from `released` so different-SHA branches whose content already landed on the base branch can still be cleaned safely.
 - **Full session lifecycle**. Suspend, resume, fork, interrupt, and recover sessions across restarts with persisted metadata and output.
+- **Explicit goal-task loops**. Opt into verifier-driven repair loops or Ralph-style completion loops when you need iterative autonomous execution toward a specific goal.
 - **Real operator visibility**. `agent_sessions`, `agent_output`, and `agent_stats` show status, buffered output, duration, and USD cost.
 - **Two harnesses, one control plane**. Claude Code and Codex share the same tools, routing, notification pipeline, and worktree strategy model while each backend uses its own native execution substrate.
 - **One continuation primitive**. `agent_respond` is the only way to continue, approve, revise, or redirect an existing session. Forks still go through `agent_launch(..., resume_session_id=..., fork_session=true)`.
 
 Need the version-pinned ACP breakdown? See [docs/ACP-COMPARISON.md](docs/ACP-COMPARISON.md).
 
+## New In 3.2.0
+
+`3.2.0` is the release that makes the newer worktree and plan-review model feel reliable enough for daily use.
+
+- **Deterministic completion and approval state**. Terminal notifications and wakes no longer depend on transcript-style summary heuristics, and plan-gated sessions now surface explicit approval/execution state for operators and orchestration logic.
+- **Real auto-merge conflict recovery**. `auto-merge` now gets one autonomous conflict-resolution attempt, then retries the merge automatically before escalating back to a preserved branch or PR path.
+- **Lifecycle-first worktree cleanup**. Worktree status and cleanup now treat `released` as a first-class resolved state, so rebased, squashed, and cherry-picked work can still be identified and cleaned safely.
+- **Safer repository follow-through**. Worktree disk-space validation now checks the correct filesystem on first run and for custom worktree directories, and cross-repo PR auto-targeting now works for upstream-only repos.
+- **Stronger release hygiene**. The repo now standardizes on `pnpm` validation, and release automation validates `package.json`, `openclaw.plugin.json`, and the release version together before publish.
+
 ## From Prompt To Merged Branch
 
 1. Launch a coding session from chat with `/agent ...` or `agent_launch(...)`.
 2. Review the plan in the same thread before anything touches the repo.
 3. Let the agent finish in an isolated worktree, then merge or publish the result from chat.
 
+### Explicit Goal Tasks
+
+Goal tasks are an explicit opt-in path for iterative autonomous work. They do not replace the default `agent_launch` flow.
+
+Use the dedicated goal entrypoints:
+
+- `/goal ...`
+- `goal_launch(...)`
+
+The plugin does not automatically switch into goal mode just because a freeform prompt contains the words `goal task`.
+
+Use them when you want the plugin to keep looping toward one concrete outcome:
+
+- **Verifier mode** reruns one or more shell checks after each coding turn and keeps iterating until they pass or the iteration budget is exhausted.
+- **Ralph mode** keeps resuming the same task until the agent emits an exact completion promise, with optional verifiers run after completion is claimed.
+
+Examples:
+
+```bash
+/goal --workdir /repo --verify "npm test" --verify "npm run lint" Fix the failing auth flow
+/goal --workdir /repo --mode ralph --completion-promise DONE Ship the draft blog post workflow end to end
+goal_launch(goal="Fix the failing auth flow", verifier_commands=["npm test", "npm run lint"], workdir="/repo")
+goal_launch(goal="Ship the draft blog post workflow end to end", goal_mode="ralph", completion_promise="DONE", workdir="/repo")
+```
+
+Once launched, use `goal_status` / `/goal_status` to inspect progress and `goal_stop` / `/goal_stop` to terminate the loop. Goal-task state is persisted so recoverable loops can resume after a gateway restart.
+
 ### Plan First
 
-The differentiator is the plan-review loop. Claude Code and Codex both feed the same review UX now: the plugin receives a structured plan artifact, keeps execution blocked until approval, and resumes the same session with `agent_respond(..., approve=true)`.
+The differentiator is the plan-review loop. Claude Code and Codex both feed the same review UX now: the plugin receives a structured plan artifact, keeps execution blocked until approval, and resumes the same session with `agent_respond(..., approve=true)`. If the user asks for revisions, the revised submission becomes the new actionable review version for that same session, and `approve=true` resolves against that latest version instead of any stale earlier change-request state.
 
 <img src="assets/ask-readme.gif" alt="Plan review in ask mode with inline approval controls">
 
@@ -38,6 +77,20 @@ When the task is done, the plugin can leave the branch for review, merge it auto
 
 *The main checkout stays clean. The branch lifecycle happens in the worktree, and the chat thread stays current on what was shipped.*
 
+### Worktree Lifecycle
+
+Worktree-backed sessions move through product-facing lifecycle states:
+
+- `active`: sandbox still in use
+- `pending decision`: waiting for merge / PR / dismiss follow-through
+- `pr_open`: PR exists and the sandbox is being preserved
+- `merged`: branch landed by normal git ancestry
+- `released`: content is already on the base branch even though branch SHAs differ after rebase, squash, or cherry-pick
+- `dismissed`: user intentionally discarded the sandbox
+- `no_change`: session finished without a committed delta
+
+For cleanup, use `agent_worktree_cleanup(mode="preview_safe")` to preview what **Clean all safe** would remove, `mode="clean_safe"` to perform that cleanup, and `mode="preview_all"` to review both safe sandboxes and the reasons other worktrees were retained.
+
 ## Supported Harnesses
 
 | Harness | Status | Notes |
@@ -57,6 +110,8 @@ openclaw plugins enable openclaw-code-agent
 openclaw gateway restart
 ```
 
+This release targets the OpenClaw `v2026.4.9` external plugin contract. `package.json` now carries the plugin API compatibility and build metadata used by modern OpenClaw / ClawHub installs, so keep those fields in sync when bumping the plugin release baseline.
+
 Add a minimal config block under `plugins.entries["openclaw-code-agent"]` in `~/.openclaw/openclaw.json`:
 
 ```json
@@ -110,14 +165,15 @@ For multi-workspace or multi-bot setups, configure `agentChannels`. The full rou
 
 Prefer fully routable channel strings such as `telegram|123456789` or `telegram|my-bot|123456789`. A bare provider like `telegram` is only a weak fallback; the plugin now repairs topic routing from `originSessionKey` when possible, but explicit channels are still the safer default.
 
-### Upgrade Note For 3.1.0
+### Upgrade Note For 3.2.0
 
-`3.1.0` is a maintenance release focused on reliability, explicit session state, and release-tooling hardening.
+If you are upgrading from `3.1.0`, the important behavioral changes are:
 
-- Upgrading archives old or invalid persisted session stores to a timestamped `.legacy-*.json` backup and starts with a fresh index.
-- Legacy Codex SDK session entries are archived and not loaded by the App Server backend.
-- App Server-backed Codex sessions are now the only supported Codex runtime path.
-- Contributors and release automation should use `pnpm verify` as the canonical validation gate.
+- `defaultWorktreeStrategy` is back to `off`, so worktree isolation remains opt-in unless you configure it explicitly.
+- `auto-merge` now attempts one autonomous conflict resolution before escalating.
+- Completion wakes and no-change outcomes are deterministic and carry explicit approval/execution state instead of relying on transcript inference.
+- Worktree cleanup is lifecycle-first and can now classify already-landed branches as `released`, which makes `preview_safe` and `clean_safe` more trustworthy after rebase, squash, or cherry-pick flows.
+- Release validation now checks package/plugin version parity in addition to the normal `pnpm verify` gate.
 
 ### Backend Capabilities
 
@@ -138,10 +194,13 @@ Prefer fully routable channel strings such as `telegram|123456789` or `telegram|
 | `agent_stats` | Show aggregate usage and cost |
 | `agent_merge` | Merge a worktree branch back to base |
 | `agent_pr` | Create or update a GitHub PR |
-| `agent_worktree_status` | Show branch, PR, and pending-decision state |
-| `agent_worktree_cleanup` | Clean up merged agent branches or dismiss a pending worktree decision |
+| `agent_worktree_status` | Show authoritative lifecycle state, derived repo evidence, cleanup safety, and retained reasons |
+| `agent_worktree_cleanup` | Clean all lifecycle-safe worktrees or dismiss one pending decision without touching live/unsafe worktrees |
+| `goal_launch` | Start an explicit verifier or Ralph-style goal loop |
+| `goal_status` | Show one goal task or list all goal tasks |
+| `goal_stop` | Stop a running goal task |
 
-The chat command surface mirrors the common workflows: `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, and `/agent_stats`.
+The chat command surface mirrors the common workflows: `/agent`, `/agent_sessions`, `/agent_output`, `/agent_respond`, `/agent_kill`, `/agent_stats`, `/goal`, `/goal_status`, and `/goal_stop`.
 
 ## Docs