Fix stalled workflows and integrate development on devel

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches: [release]
+    branches: [devel, release]
     types: [opened, synchronize, reopened, ready_for_review, edited]
 
 permissions:

.github/workflows/release.yml

@@ -18,7 +18,7 @@ concurrency:
 jobs:
   release:
     name: Publish from release and open promotion PR
-    if: github.event_name == 'push' || github.event.pull_request.merged == true
+    if: github.event_name == 'push' || (github.event.pull_request.merged == true && github.event.pull_request.head.ref == 'devel' && github.event.pull_request.head.repo.full_name == github.repository)
     runs-on: ubuntu-latest
     timeout-minutes: 25
     permissions:
@@ -37,7 +37,7 @@ jobs:
           cache: npm
       - name: Install pipeline dependencies
         run: npm ci --ignore-scripts
-      - name: Prepare version, publish package, and promote through a PR
+      - name: Publish, prepare main PR, and synchronize devel
         env:
           GH_TOKEN: ${{ github.token }}
         run: node scripts/release-pipeline.mjs

AGENTS.md

@@ -4,7 +4,10 @@ Use English for all user-facing prompts, UI labels, errors, generated bot messag
 
 Never push commits directly to `main` or modify its files through GitHub APIs.
 All changes reach `main` by merging a PR from `release`. Feature PRs target
-`release`; version and post-publication README commits belong on `release`.
+`devel`. Only a reviewed `devel` → `release` PR starts automatic publication.
+Version and post-publication README commits belong on `release`; after a stable
+publication, automation merges that published head back into `devel` without a
+PR or force push. Never reset development work to match release.
 
 ## Project context
 
@@ -28,7 +31,7 @@ steps, project setup, headless operation, and removal.
 | [docs/runtime.md](docs/runtime.md) | User-visible behavior while the bot runs: GitHub questions and permission replies, branch selection, media inputs, prompt loading, follow-up comments, session tabs, and routine management commands. | Use when changing issue conversations, session continuation, runtime tools, or TUI behavior. |
 | [docs/advanced.md](docs/advanced.md) | Separate scheduler/dispatcher setup, multiple repositories, custom RPC jobs, full options, timeouts, management and retry commands, persistence, reconciliation, locks, and known limits. | Use for low-level configuration, operational troubleshooting, recovery, or ownership/concurrency changes. |
 | [docs/installation.md](docs/installation.md) | Loader registration, config-directory precedence, prerequisites, source installation, project-local installation, upgrade conflicts, testing on another machine, and migration limits. | Use when working on packaging, installers, registration, upgrades, or deployment troubleshooting. |
-| [docs/releases.md](docs/releases.md) | Feature-to-release PR checks, automatic patch versions, manual npm version/tag releases, exact changelog notes, publication recovery, README commits on release, and promotion PRs into protected main. | Use for CI triggers, versioning, packaging, GitHub Release publication, branch permissions, or recovery after a failed release. |
+| [docs/releases.md](docs/releases.md) | Feature-to-devel and devel-to-release PR checks, automatic patch versions, manual npm version/tag releases, exact changelog notes, publication recovery, README commits on release, automatic release-to-devel synchronization, and promotion PRs into protected main. | Use for CI triggers, versioning, packaging, GitHub Release publication, branch permissions, or recovery after a failed release. |
 
 For common investigations:
 
@@ -71,17 +74,42 @@ the installation block without making remote writes. Keep its markers intact.
   installation. `examples/` contains configuration examples; `test/` contains
   automated tests. `package.json` defines build and validation commands.
 
-## Keeping documentation accurate
+## Keeping documentation accurate — required for every change
 
-Treat the implementation as the source of truth for current behavior. If code
-and documentation disagree, inspect the relevant code and tests and make the
-discrepancy explicit rather than assuming the documented behavior is implemented.
-When changing behavior, update the relevant reference page and any affected
-workflow diagrams. Keep the architecture page concise; put detailed execution
-paths in `docs/bot-workflow.md` and user-facing runtime guidance in `docs/runtime.md`.
+Documentation is part of the implementation, not a later cleanup task. **If a code
+change affects anything already described, update that description and every
+affected diagram in the same change and PR.** A change is not complete while its
+code and documentation disagree. Do not defer documentation to a later release,
+follow-up issue, or another agent.
 
-Validate changed Mermaid diagrams with a Mermaid parser when available; checking
-Markdown fences alone does not validate diagram syntax. Avoid literal semicolons
-in sequence-diagram message labels because they can be parsed as statement
-separators. For documentation-only changes, check links and formatting; application
-tests are not needed unless executable behavior also changes.
+For every code, configuration, CLI/RPC, prompt, or workflow change:
+
+1. Read the affected reference pages and compare their claims with the source and
+   relevant tests. Use the documentation map above to find all entry points.
+2. Update affected behavior, defaults, commands, examples, prerequisites, limits,
+   failure/retry paths, and recovery instructions. Check README and cross-linked
+   pages as well as the primary reference; fixing only one mention is insufficient.
+3. For automation changes, review all eight sections of `docs/bot-workflow.md`
+   for impact and update every affected Mermaid diagram and its surrounding text.
+   Show actual ordering, phase/status transitions, durable checkpoints, questions,
+   verification/publication gates, and restart paths. Do not draw desired behavior
+   as if it were implemented. Keep architecture concise and detailed paths in the
+   workflow/runtime references.
+4. Validate modified Mermaid with a parser, and check local links, headings,
+   examples and Markdown formatting. Fences alone do not prove valid diagrams.
+   Avoid literal semicolons in sequence-diagram messages. Report any validation
+   that could not be run; do not claim it passed.
+5. Before finishing, review the complete diff for code/documentation agreement.
+   In the PR description, identify the documentation updated, or state why the
+   change has no documented or user-visible behavior impact. Add accurate
+   `Unreleased` notes for changes that enter the next release.
+
+Treat implementation and verified tests as evidence of current behavior. If an
+existing discrepancy is discovered, correct the affected documentation within the
+authorized scope and make any remaining mismatch explicit. Distinguish model
+instructions from enforced runtime behavior, and branch/unreleased features from
+features already present in a published package. Do not change an unrelated
+runtime behavior merely to make an old description true.
+
+For documentation-only changes, check links, formatting and diagram syntax;
+application tests are not needed unless executable behavior also changes.

CHANGELOG.md

@@ -1,13 +1,42 @@
 # Changelog
 
 Release descriptions come from the exact version section committed with the tag.
-Add feature changes under `Unreleased`; after a PR merges into `release`, automation
+Add feature changes under `Unreleased`; after a `devel` PR merges into `release`, automation
 moves them into the new patch version's section. For a manual release, prepare
 and commit the exact version section before creating its tag. Prerelease headings
 include the full version, for example `## 0.7.0-beta.1`.
 
 ## Unreleased
 
+### Documentation
+
+- Align all eight bot workflow diagrams and runtime/recovery references with the
+  implementation, including owner lifecycle, feedback queuing, session recovery,
+  verification gates, merge polling and TUI commands.
+- Require documentation and affected diagrams to be updated with each relevant
+  implementation change in repository and bundled bot instructions.
+
+### Fixed
+
+- Reconcile timed-out or interrupted sessions completed manually after a blocked
+  task or service restart. Verify and publish through the dispatcher, then process
+  queued issue feedback on the same branch and PR, including legacy checkpoints.
+
+### Added
+
+- `/restartworkflow` and the matching CLI/RPC command resume a stopped task from
+  its saved stage, preserving worktrees, sessions, PRs, and feedback. Checkpoint
+  continuation requests across restarts without bypassing checks or permissions.
+
+### Changed
+
+- Collect feature PRs on `devel` without publishing a release. Run CI on PRs to
+  `devel` and `release`, and publish automatic patches only after a same-repository
+  `devel` to `release` PR is merged.
+- After stable publication and README update, automatically merge the published
+  release head into `devel` without a synchronization PR. Preserve new development
+  commits, retry concurrent updates, and fail safely on conflicts or denied pushes.
+
 ## 0.6.5
 
 ### Fixed
@@ -44,7 +73,7 @@ include the full version, for example `## 0.7.0-beta.1`.
 
 - Run full CI when feature PRs target `release`, including new commits to open PRs.
   Ordinary feature pushes no longer run CI or build packages.
-- Publish an automatic patch after a PR merges into `release`, and support manual
+- Publish an automatic patch after a `devel` PR merges into `release`, and support manual
   version tags on that branch without a second version bump.
 - Recover interrupted publication without moving tags or republishing completed
   packages. Commit README on `release` before opening or updating its PR to `main`.

README.md

@@ -252,7 +252,14 @@ installations are not removed by `npm uninstall --global`.
 - **Progress:** use `/bot` in the TUI, or the CLI's `status`, `scan`, `pause`, and
   `resume` commands from the target repository. Closing a PR closes its bot tabs
   while retaining session history. Authorized issue comments can continue work
-  on an open PR without another mention.
+  on an open PR without another mention, after the current round publishes.
+- **Recovery:** completing a stopped bot session manually is detected by the
+  dispatcher, which verifies and publishes before processing queued comments.
+  Use `/restartworkflow` in the owner project's TUI or
+  `opencode2-automation restartworkflow 'owner/repository#123'` from its primary
+  checkout to recover an eligible stopped task without discarding work. Pending
+  questions and failing checks still block progress. See
+  [workflow recovery](docs/runtime.md#interrupted-sessions-and-workflow-recovery).
 
 Keep machine-specific `.opencode/automation.json` files out of Git: global `init`
 does not add an ignore rule. See [configuration and Git branches](docs/configuration.md#configuration-files-and-git-branches)
@@ -291,21 +298,27 @@ copy it to another machine and follow the `.tgz` instructions above.
 
 ## GitHub Actions and releases
 
-1. Work on a feature branch and add release notes under `Unreleased` in
-   [CHANGELOG.md](CHANGELOG.md). Ordinary branch pushes do not run CI or publish packages.
-2. Open a PR into the long-lived `release` branch. CI runs lint, type checking,
-   tests, a build, and an installation check on Node 22 and 24. New commits to
-   the open PR rerun these checks. Review and merge after they pass.
-3. The merge starts **Release**. It increments the patch version on `release`,
-   moves the unreleased notes into that version's changelog section, and pushes
-   the version commit and tag atomically. It builds and verifies the tagged
-   package, then publishes the GitHub Release with `.tgz`, SHA-256, and exact
-   version notes. No package is published to npm.
-4. Only after publication succeeds, automation commits the versioned README link
-   on `release` and opens or updates a PR from `release` into `main`.
-5. Review and merge that PR with a **merge commit**. All code, version metadata,
-   release notes, and README changes reach protected `main` through this PR.
-   The automation never pushes to `main` or writes its files through the API.
+1. Create a feature branch from `devel` and add release notes under `Unreleased`
+   in [CHANGELOG.md](CHANGELOG.md). Pushes without an open PR do not run CI.
+2. Open a PR into `devel`. CI runs lint, type checking, tests, a build, and an
+   installation check on Node 22 and 24. New commits to the open PR rerun checks.
+   Review and merge after they pass. Merging into `devel` does not publish a package.
+3. When ready to publish the accumulated changes, open a `devel` → `release` PR.
+   After its checks pass, review and merge it with a **merge commit**.
+4. The merge starts **Release**: an automatic patch version, exact changelog notes,
+   atomic version/tag push, and publication of the verified `.tgz` and SHA-256.
+   No package is published to npm.
+5. After publication, automation commits the new README download link on `release`
+   and opens or updates the `release` → `main` promotion PR. It also automatically
+   merges that published head into `devel`, including version metadata and README,
+   preserving newer development work. No synchronization PR is created.
+6. Review and merge the promotion PR with a **merge commit**. Protected `main`
+   receives all released code, metadata and README through that PR only.
+
+A synchronization conflict or rejected push fails the Release job without
+resetting `devel` or undoing publication. Resolve the conflict or permissions and
+rerun the job; it reuses the published version. Synchronization does not wait for
+the main PR to merge and does not trigger another release.
 
 To choose a version manually, prepare and commit its exact changelog section on
 `release`, then use `npm version`, for example:
@@ -321,7 +334,8 @@ git push --atomic origin release v1.0.0
 The pushed tag publishes exactly `1.0.0`, without another version bump. Both
 `v1.0.0` and `1.0.0` tag names are accepted. The next automatic patch is `1.0.1`.
 Version tags must point to code on `release`; ordinary pushes to that branch
-never start publication. Finish the active release before merging another feature.
+never start publication. Finish the active release before merging another `devel` → `release` PR.
+Feature PRs may continue to accumulate on `devel`.
 
 The README on `release` is updated after publication; the README on `main` changes
 when the promotion PR is merged. The tag and packaged README remain snapshots

docs/advanced.md

@@ -71,28 +71,46 @@ node dist/manage.js run /absolute/path/to/owner-project github-issues
 node dist/manage.js pause /absolute/path/to/owner-project github-issues
 node dist/manage.js resume /absolute/path/to/owner-project github-issues
 node dist/manage.js retry /absolute/path/to/owner-project 'owner/repository#123'
+node dist/manage.js restartworkflow /absolute/path/to/owner-project 'owner/repository#123'
 ```
 
 `pause` stops scheduled scans and manual scheduler runs. It does not cancel queued
 work or active sessions; direct dispatcher `scan` still works.
 
-`retry` resumes blocked or failed tasks. If a session failed or prompt delivery is
-uncertain, inspect the session and worktree before explicitly starting a new one:
+`retry` clears blocked or failed status at the saved phase and requires an idle
+worker and maintenance loop. It does not append a continuation to an interrupted
+session. Prefer `restartworkflow` to continue that same session. If prompt delivery
+is uncertain, inspect the session and worktree before explicitly starting a new one:
 
 ```bash
 node dist/manage.js retry /absolute/path/to/owner-project 'owner/repository#123' --restart-session
 ```
 
 This interrupts the previous session and reuses the worktree. It preserves code
 and already-published acknowledgement comments. An issue edited after analysis
-remains blocked for review. A new authorized comment after completion starts a
+still faces the phase-specific issue/route guards on its next execution. A new authorized comment after completion starts a
 follow-up round and updates the same open PR.
 
+`restartworkflow` (also available as `/restartworkflow` in the owner TUI) queues
+recovery at the saved phase, without interrupting active execution or clearing
+the session. An interrupted session receives one checkpointed continuation
+request after it becomes idle; a completed session proceeds to verification.
+The request survives owner restarts. Uncertain delivery blocks inspection rather
+than replaying the continuation. Repeated requests while ready/running are no-ops.
+The RPC method `automation.github.restartworkflow` accepts `{ key }` and returns
+`{ accepted }`. A true result acknowledges queuing, not completed publication.
+Known tasks not blocked/failed return false after the pending-question and closed-PR
+guards. Missing tasks, unresolved questions, closed/merged PRs, absent routes,
+and unrecognized running-session errors produce errors. Recovery does not run a
+scan, resume a paused scheduler, or restart the service.
+Unlike `retry`, recovery can be queued while a different task is working.
+
 ## Persistence and reconciliation
 
 The queue stores analysis decisions and clarification dialogue, comment ID, session ID, phase, pinned base branch,
 worktree, base commit, pending questions, replies, permission decisions, helper
-IDs, check results, PR title, publication time, PR, and merge status. Writes are
+IDs, session-stop classification, recovery request and admission checkpoint, check
+results, PR title, publication time, PR, and merge status. Writes are
 atomic; heartbeat locks prevent multiple owners of the same state directory.
 
 After a crash, allow 30 seconds for an abandoned lock to expire. Do not remove
@@ -110,7 +128,7 @@ location are checked before renaming, and no model is prompted. Requests have a
 servers without a matching service registration skip this mechanism; use the
 shared service for unattended automation.
 
-SDK adapters may ignore AbortSignal. The plugin therefore bounds its own SDK waits,
+SDK adapters may ignore AbortSignal. The executor therefore bounds its local SDK waits,
 preserves healthy worker execution on owner disposal, and settles local state writes
 before releasing ownership. A replacement waits up to 15 seconds for the retiring
 owner's locks. RPC disposal has a five-second deadline per component; cleanup still
@@ -119,6 +137,14 @@ error should be investigated via plugin details and server logs. Back up the que
 worktree, and session database before recovery. Reconcile an already-published PR
 and saved session instead of restarting implementation or deleting the worktree.
 
+A blocked session stop is rechecked on worker passes (no more than once every
+30 seconds after an unsuccessful probe, and only when a new worker pass can start). A matching saved session with a successful
+final assistant response re-enters normal execution validation, checks, and
+publication automatically, including legacy timeout/interruption checkpoints.
+Failed checks, pending questions, and uncertain prompt delivery are not cleared.
+Queued feedback is retained until publication completes. The stop itself never
+automatically prompts the model; continue it manually or request workflow recovery.
+
 Only one issue executes at a time. Checks must succeed before publication. Push
 uses the exact verified commit without force. Worktrees remain available for
 inspection; automatic cleanup is not implemented.