release: prepare 1.0.9 preview and clarify agent readiness

Bundle knowledge-base logos and report unverified or failed native authentication accurately. Update release metadata and document the six-agent discussion validation and known configuration limits.

Checks: frontend tests (379), desktop tests (1700), landing tests (13), frontend builds, desktop pack and dist, DMG and ZIP integrity.

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v7
         with:
-          node-version: "20.19"
+          node-version: "22.12"
           cache: npm
           cache-dependency-path: frontend/package-lock.json
 
@@ -31,6 +31,9 @@ jobs:
       - name: Run unit tests
         run: npm test
 
+      - name: Check website and release licensing consistency
+        run: node --test ../meldwork-landing/test/landing.test.cjs
+
       - name: Build web application
         run: npm run build
 
@@ -47,7 +50,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v7
         with:
-          node-version: "20.19"
+          node-version: "22.12"
           cache: npm
           cache-dependency-path: |
             frontend/package-lock.json

AGENTS.md

@@ -1,4 +1,4 @@
-# RoundRelay Development Rules
+# Meldwork Development Rules
 
 ## Working Style
 
@@ -9,9 +9,10 @@
 
 ## Product Boundaries
 
-- RoundRelay is a local-first desktop application. Do not introduce a required server, container, or cluster dependency unless the task explicitly calls for it.
+- Meldwork is a local-first desktop application. Do not introduce a required server, container, or cluster dependency unless the task explicitly calls for it.
 - Keep Agent execution in the Electron main process. Renderer access must go through narrow, validated preload APIs.
-- Never expose executable paths, tokens, provider credentials, or unrestricted shell execution to renderer code.
+- Respect native Agent configuration and keep CLI integration provider-agnostic. Do not add gateway-specific adapters, provider overrides, or bundled patches for external tools such as Magpie.
+- Never expose executable paths, tokens, credentials, or unrestricted shell execution to renderer code.
 - Store secrets only through operating-system-backed secure storage. Do not add plaintext fallbacks.
 - Keep workspace write access opt-in. Conversations and groups stay local; do not add remote participants, cloud channels, or remote conversation storage.
 

CHANGELOG.md

@@ -1,29 +1,184 @@
 # Changelog
 
-## Unreleased public MVP release candidate
+## 1.0.7 - 2026-10-27 (Meldwork-V1.0.7 prerelease)
 
-### Highlights
+- Preserve streamed discussion replies across cancellation and reload; scope ACP notifications to the active session.
+- Support Hermes native stream JSON and avoid MiMo interactive plan prompts in headless runs.
+- Add Zcode with its official logo before Pi Agent, native default configuration, and explicit missing-key errors.
+- Let WorkBuddy use an explicitly selected model from its desktop configuration, without exposing credentials to the renderer.
+- Keep Chinese slash-separated text intact while retaining credential and local-path redaction.
+- Unify application, artifact, README, and website versions at 1.0.7.
+- License Meldwork's original source, documentation, and website under Apache-2.0: commercial use is permitted without separate authorization or license fees. Third-party notices remain applicable. Older entries below describe their historical release terms.
+- Native acceptance includes a real WorkBuddy response; six-Agent unlimited discussion cancellation and reload were checked with simulated adapters. Zcode's default provider still needs a valid API key; the observed OpenCode router's invalid `tool_calls` finish reason remains an upstream issue.
+- Apple silicon DMG and ZIP remain ad-hoc signed and unnotarized.
 
-- Hardened durable group orchestration, crash recovery, Human Gates, Agent controls, and bounded run traces.
-- Added validated image, media, document, code, Office, and archive attachments through picker, paste, and drag-and-drop flows.
-- Added read-only staging when an Agent lacks native support for a selected attachment type.
-- Removed the superseded Role Review module and kept review as a bounded two-Agent group workflow.
-- Completed Agent, Knowledge, mock Cloud, and Channel framework contracts while keeping production Cloud and Channel connectors disabled by default.
-- Changed the repository license to the Meldwork Non-Commercial Source License, with commercial use requiring separate written permission.
-- Set the permanent macOS Bundle ID to `com.rydersun.meldwork` before the first public release.
-- Upgraded Electron from 39.8.5 to 39.8.10 and refreshed vulnerable development-only transitive dependencies; complete frontend and desktop dependency audits now report zero known vulnerabilities.
+## 0.1.6 - 2026-10-17 (Meldwork-V1.0.6 prerelease)
+
+### Agent Reliability
+
+- Tier authentication failures instead of treating any authentication-looking diagnostic as a sign-in problem, and retry transient provider errors.
+- Keep long-lived ACP Agents (Hermes, Kimi, MiMo, OpenCode) usable across stops, restarts, and hangs, including when a group alternates between read-only and write turns.
+- Stop the watchdog from killing Agents that are still thinking or building, and keep an ACP turn alive through traffic this client does not recognise.
+- Keep an Agent available through an inconclusive readiness probe and preserve its shell environment.
+- Let MiMo and OpenCode turns that call tools finish instead of returning a partial answer, and report a CLI's own error instead of EPIPE.
+- Launch WorkBuddy's app-bundled CLI again (it now ships only the lite bundle) and stop skipping every WorkBuddy permission check in write mode.
+- Refuse unsafe ACP permission requests during read-only turns.
+- Give direct chats the current request and the delivery contract again after a native session is rebuilt.
+- Compare installed Agent CLI versions as releases, so a newer installed CLI is not offered a downgrade.
+- Write workspace state compactly and durably, and record unhandled main-process faults in the diagnostics log.
+- Internal: split the auto-runner and the Agent invocation into modules grouped by purpose.
+
+### Group Conversations
+
+- Show group replies in the order Agents were dispatched.
+- Keep natural discussions going instead of ending on one slip, ask Agents to engage with each other, and let peers see workspace file paths.
+- Keep group members after an Agent failure, so one proxy 403 or an expired sign-in no longer removes an Agent from later turns, and recover groups that were emptied.
+- A member that is not ready no longer blocks a message to the whole group; skipped members are named.
+- Deliver attachments and knowledge bases to group Agents, and send Hermes image attachments over ACP.
+- Conversations no longer wait for each other, even in the same folder; writers inside one conversation still take turns.
+- Import only files an Agent wrote, including paths with spaces.
+- Explain run failures in Chinese and English instead of showing raw codes.
+
+### Interface
+
+- Start without waiting for Agent detection: the sidebar, home page, and composer show that detection is running.
+- Mark conversations that wait for your decision in the sidebar and list them on the home page; mark group runs that finished while you were in another conversation.
+- Add a General settings tab with language and a System, Light, or Dark appearance; System follows the operating system until you choose.
+- Explain on each Agent card why an installed Agent is unavailable: its installed version, the verified range, and the failed check.
+- Use a shared type scale and semantic status colors, keep secondary text within contrast guidelines, and keep long notices on screen long enough to read.
+- Keep unsent text per conversation, add Skip and arrow-key navigation to first-run onboarding, ask before deleting a cloud server connection, and show Gemini CLI's own logo.
+
+### Verification And Distribution
+
+- Frontend 357/357, desktop 1603/1603, and deterministic evaluation 6 cases / 18 results passed on a clean checkout.
+- DMG and ZIP are ad-hoc signed, without Apple Developer ID signing or notarization. No installed user application is replaced automatically.
+- Live coverage is limited to observed CLI versions and configurations; this release did not repeat the live Agent acceptance run.
+
+## 0.1.5 - 2026-09-09 (Meldwork-V1.0.5 prerelease)
+
+### Local Agent Reliability
+
+- Accept validated OpenClaw gateway configuration migrations without disabling path, permission, or credential isolation checks.
+- Keep installed Agents visible when credential or capability checks fail; isolate failed probes and refresh the catalog after current readiness settles.
+- Refresh native shell settings before manual detection and preserve supported proxy, CA, cloud Provider, and model-region settings without silently replacing a selected Provider.
+
+### Group Conversations
+
+- Route peer requests through explicit Agent decisions instead of interpreting prose mentions or media keywords as commands.
+- Persist AI task completion separately from individual invocation success and human adoption; support single-Agent automatic work and exact visible answers.
+- Resume human clarification gates after restart, reject conflicting responses, and prevent repeated responses from replaying calls.
+- Serialize workspace writers, recover interrupted writes through bound approvals, retain partial results, and send acknowledged session context incrementally.
+- Preserve completed and stopped task states after restart and show healthy contributions alongside failed participants.
+
+### Verification And Distribution
+
+- Frontend 343/343, desktop 1562/1562, and deterministic evaluation 6 cases / 18 results passed.
+- Web and desktop builds, packaging, real packaged Codex/OpenClaw group execution, cancellation, and restart acceptance passed on Apple silicon macOS.
+- DMG and ZIP are ad-hoc signed, without Apple Developer ID signing or notarization. No installed user application is replaced automatically.
+- Live coverage is limited to observed CLI versions and configurations; cloud credential forwarding is not cloud-account certification. Full evidence: `docs/releases/Meldwork-V1.0.5.md`.
+
+## 0.1.4 - 2026-09-01 (Meldwork-V1.0.4 prerelease)
+
+### Natural Group Discussions
+
+- Sequential discussion mode now runs one Agent at a time in the configured CLI order and records every round visibly.
+- Auto Discussion starts with concurrent proposals, then lets Agent responses route the next turn through exact final-line `@Agent` mentions. One mention runs one Agent; multiple mentions run concurrently.
+- Natural discussion prompts allow Agents to exchange views before work and review instead of forcing every turn into a review-only role.
+
+### Session And Recovery
+
+- Reuses one native Agent session per Agent task across discussion rounds and restarts.
+- Persists round messages and checkpoints before and after Agent execution so completed turns are recovered without duplicate reruns.
+- Rejects stale operation and snapshot bindings before late results can be committed.
+
+### Verification And Distribution
+
+- Focused natural discussion coverage: 17/17 tests passed.
+- Desktop syntax checks and `git diff --check` passed.
+- The Apple silicon DMG and ZIP are ad-hoc signed and not notarized. Live CLI behavior still depends on each installed Agent's version, authentication, Provider, and capabilities.
+
+## 0.1.3 - 2026-08-18 (Meldwork-V1.0.3 prerelease)
+
+### Concurrent Conversations
+
+- Concurrent Responses now treats an empty explicit selection as the whole group, so users can send one message to every group Agent without adding `@` mentions first.
+- Keeps every group member in the frozen batch. Agents beyond the available Scheduler capacity remain visibly queued instead of being removed from the request.
+- Preserves valid visible proposals when a CLI omits or malforms its proposal receipt, while later Auto Discussion phases retain their strict structured-receipt boundary.
+
+### Conversation Experience
+
+- Refines user-message metadata, Agent logos, inline Agent/Skill/knowledge mentions, Markdown rendering, mention-menu tracking, and narrow-layout wrapping.
+- Returns newly sent conversations to the active Agent loading state and keeps the animated return-to-bottom control for readers who have scrolled up.
+- Removes the special No round limit composer background, border, shadow, and container breathing effect. The infinity status cue and real collaboration phase feedback remain available.
+
+### Stop Durability
+
+- Persists completed and streamed concurrent Agent replies when the user stops a batch instead of removing already visible work.
+- Records stopped Agent attempts as interrupted, rejects late post-stop results, and resumes the stable batch commit idempotently after restart.
+
+### Packaging And Verification
+
+- Sets the frontend and desktop package version to `0.1.3` and publishes Apple silicon DMG and ZIP prerelease artifacts with a matching SHA-256 manifest.
+- Frontend tests: 306/306 passed. Desktop tests: 1338/1338 passed.
+- Web and Electron renderer builds, Electron `pack`, packaged acceptance, and `git diff --check` passed before release packaging.
+- The prerelease remains ad-hoc signed, without Apple Developer ID signing or notarization, and may require Open Anyway on first launch.
+
+## 0.1.2 - 2026-08-18 (Meldwork-V1.0.2 prerelease)
+
+### Collaboration Harness V4
+
+- Replaced the legacy group reply label with Concurrent Responses while preserving the existing `manual` persistence and IPC value.
+- Freezes one shared task snapshot before Scheduler leases, keeps every selected Agent in the batch, isolates same-batch replies, and commits completed replies in stable member order.
+- Starts Auto Discussion with independent parallel proposals instead of assigning the first Agent as the primary author and every later Agent as a review-only participant.
+- Lets the selected Agents challenge proposals and negotiate one responsibility graph. Harness validates unanimous agreement on the normalized plan, dependencies, permissions, and participant coverage instead of privately assigning the work.
+- Runs distinct agreed work packages, selects one synthesis writer, and binds independent verification to the current candidate Artifact. Contradictions remain tracked issues until resolved.
+- Adds strict structured collaboration receipts, bounded Artifact/Evidence references, compact delivery watermarks, phase-and-slot operation IDs, serialized Human Gates, and idempotent crash recovery.
+- Preserves V1 manual, V2 Auto Discussion, and V3 Task Graph records on their legacy parsers and executors.
+
+### Agent Runtime
+
+- Normalizes supported CLI output into streaming answer deltas, plans, status, tool lifecycle events, warnings, and terminal results without exposing raw commands, local paths, secrets, or chain-of-thought.
+- Improves Hermes streaming and tool-event capture while preserving its read-only SQLite final-result watermark and sanitized stdout fallback.
+- Improves OpenClaw stream and tool-event normalization in the Connector protocol, keeps its managed runtime state, Provider secret handling, and permission policy isolated, and closes disposable ACP sessions plus the authenticated loopback Gateway and in-flight health probes during shutdown.
+- Strips collaboration control blocks from user-visible messages, live deltas, durable traces, and later Agent context; invalid or missing required receipts fail the current phase.
+
+### Interface
+
+- Shows real collaboration phases for parallel divergence, cross-Agent challenge and negotiation, responsibility-based work, convergence, and independent verification.
+- Adds group-scoped unlimited-mode confirmation and state-driven motion with keyboard, Escape, `aria-live`, narrow-layout, and reduced-motion support.
+- Adds an animated return-to-bottom control to group and direct conversation timelines.
+- Keeps Agent message copy actions in the metadata row, aligns version switching, regenerate, and delete controls in the compact footer row, and hardens long-name, timestamp, and narrow-screen layout behavior.
+- Keeps legacy round-zero trace labels neutral instead of relabeling historical responses as concurrent work.
+
+### Durability And Safety
+
+- Records V4 phases, batches, slots, attempts, frozen snapshots, dynamic roles, result references, delivery watermarks, commit state, and typed Gate state in the Run Ledger.
+- Binds pending V4 Human Gates and continuations to the exact leased Agent attempt, allows safe read-only recovery, requires a Human Gate before retrying an ambiguous writable slot, rejects late results after stop, and resumes batch commits idempotently.
+- Rejects terminal Agent results and V4 phase advancement while an exact permission Gate is unresolved, rejects duplicate active ACP permission request IDs, and distinguishes known checkpoint failure from unknown post-write outcomes so live recovery state cannot regress behind the durable Ledger.
+- Keeps workspace writes opt-in. Concurrent replies, proposals, challenges, negotiated work, and verification remain read-only; only the synthesis writer receives write authority when enabled.
+- Restricts renderer snapshots to validated phase, participant, role, progress, and Gate fields. Prompts, executable paths, native Session references, internal snapshot IDs, and unrestricted tool payloads remain main-process only.
+
+### Packaging And Distribution
+
+- Sets the desktop package version to `0.1.2` with permanent Bundle ID `com.rydersun.meldwork`.
+- Produces Apple silicon DMG and ZIP prerelease artifacts using ad-hoc signing. This is not Apple Developer ID signing or notarization and may require Open Anyway on first launch.
+- Keeps `dist:public` as the fail-closed future formal-distribution path requiring a Developer ID identity, Hardened Runtime, complete Apple notarization credentials, and post-sign validation.
+- This historical release used the Meldwork Non-Commercial Source License and required prior written permission for commercial use. Current releases use Apache-2.0 as stated above.
 
 ### Verification
 
-- Frontend tests: 237 passed.
-- Desktop tests: 842 passed.
-- Web and Electron renderer builds passed without the previous 500 kB chunk warning.
-- Apple silicon package validation and exact packaged direct/group attachment acceptance passed.
-- Public distribution still requires Developer ID signing and Apple notarization.
+- Frontend tests: 302/302 passed. Desktop tests: 1335/1335 passed.
+- Deterministic Eval Harness: 6 cases and 18 results passed.
+- Web and Electron renderer builds, Electron `pack`, and `git diff --check` passed on the final source tree.
+- Packaged Manual V4 completed with Codex, Claude, and Hermes evidence; packaged Auto Discussion V4 completed with Codex and Claude evidence; stopped runs remained stopped.
+- Hermes live streaming and tool lifecycle acceptance passed. The latest OpenClaw live run failed closed with `LOCAL_AGENT_PROCESS_FAILED`; protocol fixtures and managed-runtime tests pass, but OpenClaw live streaming/tool acceptance is not claimed.
+- The final 360 x 800 packaged UI acceptance passed for group and direct return-to-latest behavior, Trace layout, message actions, and stop durability. A separate Codex direct run exceeded the 300-second observation window before completing late, so it is retained as a live timing limitation rather than counted as a UI failure.
+- Release DMG and ZIP digests are published in `SHA256SUMS.txt` and verified against the uploaded assets.
+- The prerelease remains ad-hoc signed, without Apple Developer ID signing or notarization; `spctl` rejection remains expected.
 
 ## 0.1.0 Private Preview 1 - 2026-08-03
 
-This private preview packages the current Meldwork MVP for internal evaluation on Apple silicon Macs.
+This private preview packages the initial Meldwork MVP for internal evaluation on Apple silicon Macs.
 
 ### Highlights
 
@@ -37,12 +192,12 @@ This private preview packages the current Meldwork MVP for internal evaluation o
 ### Distribution
 
 - macOS Apple silicon: DMG and ZIP artifacts.
-- Private preview only. The application is ad-hoc signed and not notarized with an Apple Developer ID.
-- Windows and Intel Mac release artifacts are not included in this preview.
+- Private preview only. The application was ad-hoc signed and not notarized with an Apple Developer ID.
+- Windows and Intel Mac release artifacts were not included.
 
 ### License
 
-Meldwork is source-available under PolyForm Noncommercial 1.0.0. Commercial use requires a separate written agreement.
+Meldwork was source-available under PolyForm Noncommercial 1.0.0 for this historical preview. Commercial use required a separate written agreement.
 
 ### Verification
 

CODE_OF_CONDUCT.md

@@ -0,0 +1,51 @@
+# Code of Conduct
+
+Meldwork is a workspace for people and Agents to build together. We want issues,
+pull requests, discussions, and community spaces to stay useful, direct, and
+respectful.
+
+## Expected Behavior
+
+- Be clear, constructive, and respectful when giving feedback.
+- Assume good intent while keeping discussions focused on facts, tradeoffs, and outcomes.
+- Respect different experience levels, backgrounds, languages, and working styles.
+- Keep disagreements technical, specific, and connected to the project.
+- Help maintainers keep issues and pull requests focused.
+- Protect private prompts, credentials, customer information, and other sensitive data.
+
+## Unacceptable Behavior
+
+The following behavior is not acceptable in Meldwork project spaces:
+
+- Personal attacks, insults, harassment, or sustained disruption.
+- Demeaning comments about identity, background, language, ability, or experience.
+- Threats, intimidation, stalking, or unwanted contact.
+- Publishing another person's private information without consent.
+- Spam, trolling, discrimination, or repeated off-topic posting.
+- Submitting malicious code, secrets, private data, or intentionally misleading reports.
+- Any behavior maintainers reasonably judge to make the project unsafe or unproductive.
+
+## Maintainer Responsibilities
+
+Maintainers may edit or remove comments, close issues, limit participation, or
+block participants when needed to protect the project community. Enforcement
+should be proportional, documented when practical, and focused on keeping
+collaboration healthy.
+
+## Reporting
+
+Report conduct concerns privately through the repository's GitHub contact or
+security reporting channel. Do not open a public issue for sensitive reports.
+
+Please include:
+
+- a short description of what happened;
+- links, screenshots, or message references when available;
+- whether you want follow-up, confidentiality, or no direct reply.
+
+Reports will be reviewed by project maintainers. We will handle reports with
+care and limit access to people who need the information to respond.
+
+This Code of Conduct applies wherever the project or its maintainers represent
+the Meldwork community. It is adapted from the Contributor Covenant and the
+community standards used by comparable open-source projects.

COMMERCIAL_USE.md

@@ -1,17 +1,23 @@
-# Commercial Use And Licensing
+# Commercial use / 商业使用
 
-Meldwork is source-available under the [Meldwork Non-Commercial Source License](LICENSE). The public repository can be inspected, evaluated, run, and modified for non-commercial purposes, but it is not licensed for commercial use.
+Meldwork's original source code, documentation, README files, and official website
+are licensed under [Apache License 2.0](LICENSE). Commercial use, private use,
+modification, redistribution, and inclusion in paid products or services are
+permitted under its terms. No separate commercial authorization or license fee
+is required.
 
-Any commercial use requires prior written permission from the copyright holder. This includes monetizing Meldwork, reselling or hosting it, embedding it in a proprietary product, using it to provide paid services, or using it as part of a for-profit organization's business operations.
+When redistributing, preserve the license, applicable copyright and attribution
+notices, and NOTICE information, and identify modified files as required by the
+license. Apache-2.0 does not grant trademark rights (Section 6).
 
-The copyright holder may offer a separate commercial license for organizations that need permission for:
+Third-party dependencies, fonts, Agent names, and logos retain their own licenses
+and terms; their inclusion does not imply endorsement. In particular, the
+website's bundled Fusion Pixel font retains its OFL license and notices.
 
-- proprietary redistribution or resale of Meldwork or a modified version;
-- embedding Meldwork code in a closed-source product;
-- offering a hosted, managed, or network-accessible version;
-- internal business operations at a for-profit organization;
-- separately licensed commercial features, enterprise integrations, support, or managed deployment.
+Meldwork 原创源代码、文档、README 和官网均采用 Apache-2.0。依照许可证条款，
+允许商业使用、私人使用、修改、再分发，以及用于收费产品或服务；无需另行取得商业
+授权或支付许可费。再分发时应保留许可证、适用的版权与归属声明及 NOTICE 信息，并
+按许可证要求标明修改。Apache-2.0 第 6 条不授予商标权。第三方依赖、字体、Agent
+名称和标志仍遵循各自条款；官网附带的 Fusion Pixel 字体保留 OFL 许可证与声明。
 
-A commercial license does not change the licenses of third-party dependencies, Agent products, names, models, or logos. The repository license also does not grant trademark rights to the Meldwork name, logo, screenshots, or other brand assets.
-
-This page is a practical summary and does not replace the license text or legal advice. When a planned use may be commercial, contact the repository owner through GitHub before using, distributing, hosting, reselling, or integrating the product.
+This summary does not replace LICENSE. 本说明不替代 LICENSE 正文。

CONTRIBUTING.md

@@ -1,18 +1,19 @@
 # Contributing
 
-Meldwork is source-available under the [Meldwork Non-Commercial Source License](LICENSE). Contributions are welcome when they improve the local-first desktop product, documentation, tests, or security posture.
+Meldwork is licensed under the [Apache License 2.0](LICENSE). Contributions are welcome when they improve the local-first desktop product, documentation, tests, or security posture.
 
-Unless a separate written agreement applies, a contribution accepted into this repository is available under the repository license. The project may also offer separately licensed commercial editions. Before external code is incorporated into a separately licensed commercial build, the maintainer may require a reviewed contributor-license agreement that grants the necessary relicensing rights. Opening a pull request by itself does not transfer copyright or silently grant those additional rights.
+Unless a separate written agreement applies, a contribution accepted into this repository is available under the repository license. Opening a pull request does not transfer copyright beyond the rights granted by the Apache License 2.0.
 
 ## Ground Rules
 
 - Keep changes small and tied to a clear product or engineering need.
 - Do not submit secrets, tokens, private logs, private prompts, or user data.
 - Do not add remote services, telemetry, credential collection, or server dependencies without explicit project approval.
-- Preserve the local-first boundary: renderer code must not gain unrestricted filesystem, shell, Provider credential, or executable-path access.
+- Preserve the local-first boundary: renderer code must not gain unrestricted filesystem, shell, credential, or executable-path access.
 - Include focused tests for behavior, security boundary, storage, or IPC changes.
-- Confirm that all submitted code and assets are yours to license and do not introduce incompatible license obligations.
+- Confirm that all submitted code and assets are yours to contribute and do not introduce incompatible license obligations.
 
-## Commercial Editions
+## Community Standards
 
-Commercial use of Meldwork requires prior written permission. Commercial editions, proprietary integrations, support, and other paid offerings may use separate terms; see [COMMERCIAL_USE.md](COMMERCIAL_USE.md).
+Please follow the [Code of Conduct](CODE_OF_CONDUCT.md) in issues, pull
+requests, discussions, and other project spaces.

LICENSE

@@ -1,82 +1,201 @@
-Meldwork Non-Commercial Source License 1.0
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2026 Ryder-MHumble.
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-This license applies to Meldwork and the source code, documentation, assets, and
-other materials in this repository, except where a file or third-party notice
-states a different license.
+   1. Definitions.
 
-Meldwork is source-available, not open source in the OSI sense. Commercial use is
-not permitted without prior written permission from the copyright holder.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-1. Allowed non-commercial use
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
-You may download, inspect, run, copy, and modify Meldwork for personal learning,
-research, evaluation, security review, and other non-commercial purposes.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
 
-You may share unmodified or modified copies for non-commercial purposes if you:
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
 
-- keep this license and all copyright, attribution, and trademark notices;
-- clearly mark your changes when you distribute a modified copy;
-- do not remove or obscure third-party notices; and
-- do not imply that the copyright holder endorses your copy or service.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
 
-2. Commercial use requires permission
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
 
-You may not use Meldwork for a commercial purpose without a separate written
-license or other written permission from the copyright holder.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
-Commercial purpose includes, without limitation:
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
 
-- selling, renting, sublicensing, or otherwise monetizing Meldwork or a modified
-  version;
-- offering Meldwork or a modified version as a hosted, managed, consulting,
-  outsourcing, integration, or support service;
-- embedding Meldwork code, UI, workflow, or packaged binaries in a proprietary,
-  paid, or revenue-generating product;
-- using Meldwork to provide paid deliverables, paid automation, paid Agent
-  operations, or other business services to a customer; and
-- use by or for a for-profit company, commercial product team, or revenue-driven
-  organization as part of its business operations.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
-If you want to use Meldwork commercially, contact the repository owner and obtain
-written permission before using, distributing, hosting, reselling, or integrating
-the product.
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
-3. No trademark license
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
 
-This license does not grant rights to use the Meldwork name, logo, product
-identity, screenshots, or other brand assets except as needed to describe an
-unaltered copy of the software in a truthful, non-confusing way.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
-4. Third-party materials
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
 
-Third-party software, Agent products, models, names, logos, dependencies, and
-other materials remain subject to their own licenses and terms. This license does
-not give you rights that the copyright holder does not own.
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
 
-5. Contributions
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
 
-Unless a separate written agreement says otherwise, contributions submitted to
-this repository may be used under this license. The copyright holder may require
-a separate contributor agreement before accepting contributions intended for a
-commercially licensed edition.
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
 
-6. Termination
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
 
-If you violate this license, your rights under it terminate automatically. The
-copyright holder may reinstate rights in writing after the violation is cured.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
-7. No warranty
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
-Meldwork is provided "as is", without warranties or conditions of any kind,
-including implied warranties of merchantability, fitness for a particular
-purpose, title, and non-infringement. You are responsible for evaluating whether
-the software is suitable and lawful for your use.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
 
-8. Limitation of liability
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
 
-To the maximum extent permitted by law, the copyright holder and contributors
-will not be liable for any damages arising from or related to the software or
-this license, including direct, indirect, incidental, consequential, special,
-exemplary, punitive, or business-interruption damages.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -1,9 +1,7 @@
 Meldwork
 Copyright 2026 Ryder-MHumble and Meldwork contributors.
 
-Meldwork is licensed under the Meldwork Non-Commercial Source License. See
-LICENSE. Commercial use requires separate written permission from the copyright
-holder.
+Meldwork is licensed under the Apache License 2.0. See LICENSE.
 
 Third-party Agent names, product names, and logos remain the property of their
 respective owners. They are used only to identify compatible integrations and
@@ -12,3 +10,7 @@ do not imply sponsorship or endorsement.
 The OpenCodeReview logo is sourced from Alibaba's OpenCodeReview project:
 https://github.com/alibaba/open-code-review/blob/main/imgs/logo-core.svg
 The upstream project is licensed under Apache License 2.0.
+
+The Zcode logo is sourced unchanged from the official Zcode website:
+https://zcode.z.ai/favicon-192x192.png?v=20260707-transparent
+The logo identifies the integration; its trademark rights remain with its owner.

README.md

@@ -1,117 +1,100 @@
 <p align="center">
-  <img src="frontend/public/logos/meldwork-readme-banner-en.png" alt="Meldwork - Agents change. Work continues." width="100%">
+  <img src="frontend/public/logos/meldwork-readme-banner-en.png" alt="Meldwork README banner" width="100%">
 </p>
 
 <p align="center">
   <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
 </p>
 
-# AI agents are interchangeable. Your work should not be.
+# Meldwork — Let Agents collaborate to move tasks forward
 
-**Meldwork is a local-first desktop workspace for persistent direct Agent conversations and bounded multi-Agent review. Each conversation keeps its own context, permissions, attachments, compatible native sessions, and sanitized execution history on your computer.**
+**Set the goal. Let Agents work together. Meldwork brings your existing Agents into one working group to share context, discuss approaches, carry out work, and check each other's results — with less relaying, prompting, and stitching outputs together.**
 
-Most Agent tools are already good at completing one step. The fragile part starts when work crosses tools: context gets copied by hand, files are attached again, permission boundaries drift, and the final answer can look complete without showing how it was formed. Meldwork keeps the task stable while Agents change. Start with one Agent, add another only when the work needs a different capability or an independent challenge, then inspect the result before deciding what to keep.
+Meldwork is a local-first multi-Agent collaboration workspace for the Agent tools you already use on your Mac. Once you choose the participants, goal, context, and permissions, Agents in Auto Discussion can build on each other's work, request contributions or reviews, and advance the task within the authorized scope. Direct conversations and independent concurrent responses also support research, analysis, writing, planning, review, and implementation.
 
-Meldwork is not about opening more AI windows. It is about letting complex work move between Agents without losing the thread: one Agent's conclusions and evidence can support the next step, every answer returns to the same task context, and you decide which results are worth accepting.
+You do not need to direct every round, but you still set the goal, grant permissions, and make key decisions. Missing information, permission requests, or tradeoffs may require your input. Workspace writes are opt-in; collaboration history, run state, and deliverables stay local so you can revisit the work and continue it.
 
 <p align="center">
-  <a href="https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.1/Meldwork-0.1.1-arm64.dmg"><strong>Download the macOS DMG</strong></a>
-  · <a href="LICENSE">Non-commercial source license</a>
-  · <a href="COMMERCIAL_USE.md">Commercial permission</a>
+  <a href="https://github.com/Ryder-Sun/Meldwork/releases/download/Meldwork-V1.0.9/Meldwork-1.0.9-arm64.dmg"><strong>Download Meldwork V1.0.9 for Apple silicon macOS</strong></a>
+  · <a href="architecture.md">Architecture</a>
+  · <a href="LICENSE">License</a>
 </p>
 
-## Install the desktop client
+## What Meldwork is for
 
-The current desktop build is for Apple silicon Macs.
+Meldwork is useful when several Agents need to advance the same task and you want to spend less time passing context and coordinating next steps. Typical work includes:
 
-1. Open the [latest GitHub Release](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.1).
-2. Download `Meldwork-0.1.1-arm64.dmg`.
-3. Drag Meldwork into Applications, then try to open it once.
-4. If macOS blocks the current preview because it is not yet Apple-notarized, open **System Settings → Privacy & Security**, scroll to **Security**, click **Open Anyway** beside Meldwork, then confirm **Open**. The button appears only after the first blocked launch attempt. Use only a DMG downloaded from the official Release above.
-5. Connect the supported Agent CLIs already installed on your computer, or configure an independent Provider profile for an Agent.
+- research and information synthesis across local Agent tools and selected knowledge sources;
+- product, market, operational, and technical analysis;
+- writing, planning, review, and structured document work;
+- multimodal work with local documents, images, audio, video, PDFs, and code or configuration files;
+- implementation in an authorized workspace, with other Agents checking the deliverables and requesting revisions.
 
-If the latest Release includes a DMG, it can be downloaded and installed locally. Developers can also run Meldwork from source with the commands below.
+## How a task moves through Meldwork
 
-## What is improved in V1.0.1
+1. **Select** the Agents that will work on the task together.
+2. **Scope** the goal, working directory, context, attachments, Skills, knowledge sources, and permissions.
+3. **Collaborate** in Auto Discussion: let Agents discuss approaches, carry out authorized work, and check results. Direct conversations and Concurrent Responses are also available.
+4. **Decide** when the work needs information, permission, or a tradeoff resolved.
+5. **Check the result** and request changes when more work is needed.
 
-- **Long-running work is more reliable:** an Agent is no longer treated as failed just because a task takes time. As long as it is still producing useful progress, the conversation can continue.
-- **Unlimited discussions are more rigorous:** when you choose unlimited rounds, Agents are asked to challenge unsupported claims and review each other's work carefully before accepting a conclusion.
-- **Cleaner conversation controls:** loading states, sidebar actions, and execution details are easier to scan, so you can tell what is active and what needs your attention.
-- **More dependable recovery:** interrupted or stalled work keeps its useful progress and exposes a clearer recovery path instead of leaving the conversation in an ambiguous state.
+## Collaboration modes
 
-## See the core workflow
-
-| Local Agent discovery | Direct multimodal work | Targeted multi-Agent review |
+| Mode | What happens | Best for |
 | --- | --- | --- |
-| [![Meldwork detecting local Agent CLIs](assets/meldwork-agent-discovery.png)](assets/meldwork-agent-discovery.png) | [![A direct Agent conversation returning image, audio, and document outputs](assets/meldwork-direct-multimodal.png)](assets/meldwork-direct-multimodal.png) | [![A group conversation with targeted Agent replies](assets/meldwork-multi-agent-review.png)](assets/meldwork-multi-agent-review.png) |
-| Detect supported Agent CLIs without presenting startup as an error state. | Keep prompts, generated media, files, permissions, and compatible native sessions in one direct conversation. | Ask only the selected Agents to respond, then inspect or collapse each reply independently. |
+| **Direct** | One selected Agent keeps its conversation and native session when supported. | Focused research, writing, analysis, or execution. |
+| **Concurrent Responses** | Selected Agents receive the same frozen task snapshot and return independent responses in stable order. | Comparing perspectives before choosing a path. |
+| **Auto Discussion V4** | Agents propose independently, discuss, request peer contributions, carry out authorized work, and check deliverables. A delivery owner judges progress and requests user decisions when needed. Native sessions continue when supported. | Multi-step collaboration with less manual coordination. |
 
-Click any screenshot to view it at full resolution.
+Participants are selected by the user. Automatic selection from a larger roster is outside the current preview.
 
-## What Meldwork does today
+## Revisit the process and continue the work
 
-- **Organizes local Agents:** detects supported CLI installations, keeps readiness visible, and lets users add approved CLI-based Custom Agents without turning the renderer into an unrestricted shell.
-- **Keeps direct work continuous:** each direct conversation retains its local history, attachments, permission mode, compatible native Session, and sanitized execution details.
-- **Moves multimodal files both ways:** users can paste or attach validated images, documents, code, archives, audio, and video; supported Agents and Providers can return locally previewable media and generated files to the same conversation.
-- **Targets group work explicitly:** mention the exact Agents needed for a task, run a single response or bounded automatic discussion, stop individual Agents, collapse replies, and review regenerated response versions.
-- **Makes execution inspectable and recoverable:** bounded run events, compact evidence capsules, checkpoints, completion states, and recovery actions remain available without exposing raw credentials, executable paths, or private reasoning.
-- **Keeps control local:** conversations and orchestration state stay on the computer, credentials use operating-system-backed secure storage where supported, and workspace write access remains opt-in.
+Meldwork keeps task context, Agent replies, run state, and deliverables locally so you can see how work progressed, where it stalled, and what needs attention next. The Run Ledger preserves phase, participant, attempt, artifact, recovery, and Human Gate state. Diagnostic tool output and sensitive runtime details stay behind the Electron main-process boundary.
 
-Capability still depends on the selected Agent, its installed version, authentication state, Provider, and declared attachment or tool support.
+These records help you inspect collaboration; they do not establish that every claim has been fact-checked. Peer review does not guarantee correctness, and important deliverables still need acceptance checks appropriate to their use.
 
-## A practical review loop
+## General Agent catalog
 
-1. Start a direct conversation with the Agent best suited to produce the first deliverable.
-2. Attach only the required context and enable workspace writes only when the task must modify files.
-3. Move the task into a group when it needs another capability or an independent challenge; select only the Agents that should participate.
-4. Compare final replies, generated artifacts, response versions, and sanitized run details before deciding what to accept.
+Meldwork detects and invokes compatible locally installed Agent commands. The catalog currently includes:
 
-Meldwork does not silently merge unrelated conversation histories. The user chooses which files, conclusions, Skills, and approved knowledge sources should cross into the next task.
+<table>
+  <tr>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/codex.svg" alt="Codex logo" width="32" height="32"><br><strong>Codex</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/hermes.png" alt="Hermes logo" width="32" height="32"><br><strong>Hermes</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/openclaw-transparent.png" alt="OpenClaw logo" width="32" height="32"><br><strong>OpenClaw</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/workbuddy.png" alt="WorkBuddy logo" width="32" height="32"><br><strong>WorkBuddy</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/zcode.png" alt="Zcode logo" width="32" height="32"><br><strong>Zcode</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/pi.svg" alt="Pi Agent logo" width="32" height="32"><br><strong>Pi Agent</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/kimi.png" alt="Kimi Code logo" width="32" height="32"><br><strong>Kimi Code</strong></td>
+  </tr>
+  <tr>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/mimo.svg" alt="MiMo Code logo" width="32" height="32"><br><strong>MiMo Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/claude.png" alt="Claude Code logo" width="32" height="32"><br><strong>Claude Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/gemini.svg" alt="Gemini CLI logo" width="32" height="32"><br><strong>Gemini CLI</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/opencode.svg" alt="OpenCode logo" width="32" height="32"><br><strong>OpenCode</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/qwen.svg" alt="Qwen Code logo" width="32" height="32"><br><strong>Qwen Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/opencodereview.svg" alt="OpenCodeReview logo" width="32" height="32"><br><strong>OpenCodeReview</strong></td>
+  </tr>
+</table>
 
-## The Harness behind the workspace
+Approved Agent Connectors and custom executable Agents use the desktop connector paths. The [desktop guide](desktop/README.md) contains the current adapter, installation, provider, and capability matrix.
 
-![Meldwork Harness Engine](frontend/public/logos/Harness-readme.png)
+## Context and local boundaries
 
-The Harness is the layer that keeps Agent collaboration from turning into copied prompts and disconnected transcripts. It normalizes Agent events, builds bounded context for each target, keeps compatible native sessions separate, checkpoints local run state, and exposes recovery states when authentication or compatibility needs user action.
+Meldwork runs as a local Electron application. Conversations, group configuration, run records, and app-owned attachments stay in the local user data directory. The renderer receives only validated snapshots through a narrow preload API; executable paths, credentials, native session references, Skill paths, and unrestricted shell access remain in the main process.
 
-- **Run control:** explicit targets, manual handoffs, bounded automatic rounds, stop, and per-Agent controls.
-- **Context control:** stable constraints, selected files, target-scoped Skills and knowledge sources, recent conclusions, and compact evidence capsules.
-- **Inspectable execution:** conclusions, source context, warnings, terminal status, and, when exposed by the selected Agent or transport, plans and tool lifecycle summaries.
-- **Durable local state:** conversations and bounded run records remain inspectable; context stays durable and traceable after completion or interruption.
+Selected Agents may send prompts, attachments, or Skills to the model provider configured in their own CLI. Knowledge access is explicit and bounded: the current implementation supports local Obsidian retrieval and CLI-owned Feishu or DingTalk access modes. Local-first describes where Meldwork stores and coordinates work; it does not promise that an Agent's model provider is offline.
 
-## Where the workflow fits
+## Download V1.0.9
 
-| Work | First Agent | Independent check |
-| --- | --- | --- |
-| Research and intelligence | Build the evidence base | Challenge unsupported claims and missing sources |
-| Product and strategy | Draft the proposal and decision model | Test user value, feasibility, and expensive failure modes |
-| Software delivery | Implement and verify the change | Review the diff, tests, security boundaries, and regressions |
-| Writing and operations | Produce the deliverable | Check structure, accuracy, tone, and execution risk |
+For Apple silicon macOS, download the [Meldwork V1.0.9 prerelease](https://github.com/Ryder-Sun/Meldwork/releases/tag/Meldwork-V1.0.9) and choose [`Meldwork-1.0.9-arm64.dmg`](https://github.com/Ryder-Sun/Meldwork/releases/download/Meldwork-V1.0.9/Meldwork-1.0.9-arm64.dmg). The release also includes a ZIP archive and SHA-256 manifest. Install at least one supported local Agent CLI before opening the app.
 
-The goal is not to maximize Agent count. Use one Agent when one is enough, and add another only when a different capability or independent review materially improves the result. Model requests still follow the Agent and Provider you choose; local-first describes Meldwork's workspace and orchestration state, not third-party model hosting.
+The preview artifacts are ad-hoc signed and not notarized with an Apple Developer ID. macOS may require **Open Anyway** under **System Settings → Privacy & Security** on first launch.
 
-## Connected Agents
+## Run from source
 
-Meldwork currently integrates with:
-
-**Codex · Hermes · OpenClaw · WorkBuddy · Kimi Code · MiMo Code · Claude Code · Gemini CLI · OpenCode · Qwen Code**
-
-Specialized review:
-
-**OpenCodeReview**
-
-Availability depends on the installed Agent, supported version, authentication state, and declared capabilities. OpenCodeReview is a specialized review target rather than a general conversation Agent.
-
-Each Agent keeps its own capabilities, provider configuration, permission model, and session behavior. Availability depends on the installed Agent, its version, and its authentication state.
-
-## Current release scope
-
-The first release-validated target is Apple silicon macOS. Windows has implementation-level support, but broad real-device validation is still incomplete. Broad third-party Agent certification is not yet claimed.
-
-<details>
-<summary><strong>Build from source for development</strong></summary>
-
-Requires Node.js 20.19 or newer and npm.
+Prerequisites: Node.js `22.12+` and npm.
 
 ```bash
 npm --prefix frontend ci
@@ -119,7 +102,7 @@ npm --prefix desktop ci
 npm --prefix desktop run dev
 ```
 
-Use the repository test scripts before distributing a build:
+Before distributing a build:
 
 ```bash
 npm --prefix frontend test
@@ -128,10 +111,27 @@ npm --prefix frontend run build:desktop
 npm --prefix desktop test
 ```
 
-</details>
+## V1.0.9
+
+Auto Discussion can complete native Agent turns on explicit completion and requires each participant to approve the same delivery version. A real six-Agent unlimited discussion completed in nine rounds with matching delivery hashes. This preview also improves Agent authentication status, handles CLI authentication errors reported on stderr, and bundles knowledge-base logos.
+
+Agent installation does not guarantee a working model connection: OpenClaw's isolated runtime may not support the native environment configuration, WorkBuddy's CLI may require its own login, and Zcode needs valid native provider credentials. Desktop and frontend regression checks passed 1,700 and 379 tests respectively.
+
+## V1.0.8
+
+V1.0.8 keeps Kimi read-only queries in manual approval mode instead of forcing a planning cycle, preserves MiMo's final text chunks, forwards supported native CLI configuration, and retains the selected Auto Discussion mode after sending. Repetitive native output is cancelled with partial replies preserved. Zcode remains before Pi Agent with its official logo and native default configuration; WorkBuddy can reuse a configured desktop model selected in Meldwork.
+
+Real CLI acceptance covered all 13 installed Agents. A five-Agent unlimited discussion completed all 14 native calls through an isolated Magpie hotfix. The installed Magpie version can rewrite `stop` into `tool_calls` when `tool_calls` is null, causing OpenCode, MiMo, and Hermes to continue indefinitely; this Meldwork release does not install or restart Magpie. OpenClaw, Zcode, Gemini, Qwen, and OpenCodeReview also had native configuration or authentication failures in this audit. Detecting an installed CLI does not certify a working model connection. Regression validation includes 1,655 desktop tests, 370 frontend tests, web and desktop builds, and package validation. Unlimited discussion retains stalled-process detection and write permissions remain opt-in.
+
+Electron acceptance with the same isolated gateway also completed a separate five-Agent unlimited discussion: 19 native calls, no failed attempts or retries, about 12 minutes. Auto Discussion and No round limit remained selected after sending, completion, and leaving and reopening the group. This verifies the workflow, not a response-time guarantee or a repair to the user's installed gateway.
+
+## Documentation
+
+- [Architecture and product boundary](architecture.md)
+- [Desktop setup and Agent matrix](desktop/README.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
 
 ## License
 
-Meldwork is source-available under the [Meldwork Non-Commercial Source License](LICENSE). You may inspect, run, modify, and share the software for non-commercial purposes, but commercial use is not permitted without prior written permission from the copyright holder.
-
-Commercial use includes resale, paid hosting, managed services, consulting or outsourcing use, closed-source embedding, and business operations by or for a for-profit organization. To request permission or a separate commercial license, see [COMMERCIAL_USE.md](COMMERCIAL_USE.md). Third-party attribution is recorded in [NOTICE](NOTICE).
+Meldwork is open source under the [Apache License 2.0](LICENSE). Commercial use, private use, modification, and redistribution are permitted under the license terms. No separate commercial authorization or license fee is required. Apache-2.0 does not grant trademark rights; see [COMMERCIAL_USE.md](COMMERCIAL_USE.md).

README.zh-CN.md

@@ -1,116 +1,100 @@
 <p align="center">
-  <img src="frontend/public/logos/meldwork-readme-banner-zh-CN.png" alt="Meldwork：Agent 随时切换，工作始终连续" width="100%">
+  <img src="frontend/public/logos/meldwork-readme-banner-cn.png" alt="Meldwork README banner" width="100%">
 </p>
 
 <p align="center">
   <a href="README.md">English</a> · <strong>简体中文</strong>
 </p>
 
-# Agent 可以换，工作不该断
+# Meldwork：让 Agent 自主协作推进任务
 
-**Meldwork 是一个本地优先的 Agent 桌面工作台，用于持续单聊和有边界的多 Agent 复核。每个会话的上下文、权限、附件、兼容的原生 Session 与脱敏运行记录都保存在你的电脑上。**
+**提出目标，让 Agent 们协作完成。Meldwork 把你已有的 Agent 组织成一个工作小组，共享上下文、讨论方案、协作执行并相互检查，减少你在它们之间转述、催办和整合结果的工作。**
 
-多数 Agent 已经能够完成一段工作。真正脆弱的是切换工具之后：上下文需要手工复制，文件要重新附加，权限边界容易丢失，最终答案看起来完整，却很难说明它是如何形成的。Meldwork 让任务保持稳定，让 Agent 按需变化。先从一个 Agent 开始；只有当任务需要另一种能力或独立质疑时，再加入第二个 Agent；最后由你检查结果并决定保留什么。
+Meldwork 是一个本地优先的多 Agent 协作工作空间，用来连接你已经在电脑上使用的 Agent 工具。你选定参与者、目标、上下文和权限后，自动讨论中的 Agent 可以接续彼此的工作，请求同伴补充或检查，并在授权范围内推进任务。它也支持单个 Agent 的直接会话和多个 Agent 的独立并发回复，覆盖研究、分析、写作、规划、评审和实施。
 
-它解决的不是“同时打开更多 AI”，而是让一项复杂工作能够在不同 Agent 之间真正接力：前一个 Agent 留下的结论和证据，后一个可以继续使用；所有人的回答仍然回到同一条任务脉络里，由你决定哪些结果值得接受。
+你无需安排每一轮发言，但仍负责目标、权限和关键决策。遇到信息缺失、权限请求或需要取舍的问题时，任务可能等待你处理。工作区写入需要明确授权；协作过程、运行状态和产物保存在本地，方便回看和继续工作。
 
 <p align="center">
-  <a href="https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.1/Meldwork-0.1.1-arm64.dmg"><strong>下载 macOS DMG 安装包</strong></a>
-  · <a href="LICENSE">非商用源码许可</a>
-  · <a href="COMMERCIAL_USE.md">商业授权说明</a>
+  <a href="https://github.com/Ryder-Sun/Meldwork/releases/download/Meldwork-V1.0.9/Meldwork-1.0.9-arm64.dmg"><strong>下载 Meldwork V1.0.9 Apple 芯片 macOS 版</strong></a>
+  · <a href="architecture.md">架构</a>
+  · <a href="LICENSE">许可证</a>
 </p>
 
-## 先装客户端，再开始工作
+## Meldwork 适合什么工作
 
-当前桌面客户端面向 Apple 芯片 Mac：
+当一个任务需要多个 Agent 共同推进，而你不想反复传递上下文、协调下一步时，Meldwork 更适合：
 
-1. 打开 [最新 GitHub Release](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.1)。
-2. 下载 `Meldwork-0.1.1-arm64.dmg`。
-3. 将 Meldwork 拖入“应用程序”，然后先尝试打开一次。
-4. 当前预览版尚未经过 Apple 公证。如果 macOS 阻止启动，请打开“系统设置 → 隐私与安全性”，向下滚动到“安全性”，在 Meldwork 提示旁点击“仍要打开”，再确认“打开”。“仍要打开”只会在首次启动被拦截后出现。请只使用从上方官方 Release 下载的 DMG。
-5. 连接电脑上已经安装的 Agent CLI，或为某个 Agent 单独配置 Provider。
+- 研究与信息综合：结合本地 Agent 工具和明确选择的知识源；
+- 产品、市场、运营和技术分析；
+- 写作、规划、评审和结构化文档工作；
+- 处理本地文档、图片、音频、视频、PDF、代码和配置文件的多模态工作；
+- 在授权工作目录内执行、由其他 Agent 检查成果并继续修改的实施工作。
 
-如果最新 Release 中包含 DMG 文件，就可以直接下载到本地安装。开发者也可以使用下方命令从源码运行。
+## 一个任务如何在 Meldwork 中推进
 
-## V1.0.1 这次改进了什么
+1. **选择**一起处理任务的 Agent。
+2. **限定**目标、工作目录、上下文、附件、Skill、知识源和权限。
+3. **协作**：启动 Auto Discussion，让 Agent 讨论方案、接续执行并检查成果；也可选择直接会话或并发回复。
+4. **决策**：在需要补充信息、授权或取舍时介入。
+5. **查看结果**：检查交付物，必要时提出修改，让工作继续推进。
 
-- **长时间任务更可靠：** Agent 只要还在持续产生有效进展，就不会因为任务耗时较长而被误判为失败。
-- **无限轮次更严格：** 选择 unlimited 模式后，Agent 会更认真地质疑缺少依据的结论，并在验收前严格复核自己和其他 Agent 的工作。
-- **会话控制更清晰：** 加载状态、侧边栏操作和执行详情更容易扫描，你可以快速判断当前正在运行什么、下一步需要处理什么。
-- **中断后更容易恢复：** 被打断或暂时停滞的任务会保留已有进展，并提供更明确的恢复路径，避免会话停在不确定状态。
+## 协作模式
 
-## 三个核心工作现场
-
-| 本地 Agent 检测 | 单聊中的多模态产物 | 指定 Agent 的群聊复核 |
+| 模式 | 运行方式 | 适合场景 |
 | --- | --- | --- |
-| [![Meldwork 正在检测本地 Agent CLI](assets/meldwork-agent-discovery.png)](assets/meldwork-agent-discovery.png) | [![Agent 在单聊中返回图片、音频和文档产物](assets/meldwork-direct-multimodal.png)](assets/meldwork-direct-multimodal.png) | [![多个指定 Agent 在群聊中分别回复](assets/meldwork-multi-agent-review.png)](assets/meldwork-multi-agent-review.png) |
-| 检测受支持的 Agent CLI，用明确的启动动画表达“正在准备”，而不是制造报错感。 | Prompt、生成媒体、文件、权限和兼容的原生 Session 都留在同一条单聊中。 | 只让用户点名的 Agent 参与，并可单独查看或收起每个 Agent 的回复。 |
+| **直接会话** | 一个已选 Agent 在适配器支持时保持对话和原生会话。 | 聚焦研究、写作、分析或执行。 |
+| **并发回复** | 已选 Agent 收到同一份冻结任务快照，并按稳定顺序返回独立回复。 | 在选择方案前比较不同视角。 |
+| **Auto Discussion V4** | Agent 独立提出方案后，接续讨论、请求同伴贡献、在授权范围内执行并检查成果。交付负责人判断任务进度，必要时请求用户决策；支持时保持原生会话。 | 希望减少人工协调的多步骤协作任务。 |
 
-单击任意截图可以查看完整尺寸。
+参与者始终由用户选择。从更大候选池自动选人组队不属于当前预览版。
 
-## Meldwork 当前已经具备的能力
+## 过程可回看，工作可继续
 
-- **统一管理本地 Agent：** 检测受支持的 CLI 安装和就绪状态，也允许用户引入经过批准、支持 CLI 控制的 Custom Agent，同时不向渲染层开放任意 Shell。
-- **让单聊持续存在：** 每条单聊保留本地历史、附件、权限模式、兼容的原生 Session 和经过脱敏的执行详情。
-- **让多模态文件双向流动：** 用户可以粘贴或附加经过验证的图片、文档、代码、压缩包、音频和视频；受支持的 Agent 与 Provider 也可以把可本地预览的媒体和生成文件返回到同一条会话。
-- **明确控制群聊参与者：** 点名真正需要的 Agent，运行单轮回复或有边界的自动讨论，停止指定 Agent，单独收起回复，并查看重新生成后的回答版本。
-- **让执行过程可检查、可恢复：** 有界运行事件、精简证据摘要、检查点、完成状态和恢复操作会被保留下来，同时避免暴露凭据、可执行路径或私有推理。
-- **把控制权留在本机：** 会话和编排状态保存在电脑上；兼容环境使用操作系统安全存储保存凭据；工作目录写入必须由用户主动开启。
+Meldwork 在本地保留任务上下文、Agent 回复、运行状态和产物，方便了解任务如何推进、哪里遇到阻塞，以及接下来需要处理什么。Run Ledger 保留阶段、参与者、尝试、产物、恢复状态和人工审批门；诊断工具输出与敏感运行信息留在 Electron 主进程边界内。
 
-具体能力仍取决于所选 Agent、本机版本、认证状态、Provider，以及该 Agent 声明的附件和工具支持。
+过程记录帮助检查协作情况，不代表每条结论都经过事实核验。Agent 的相互检查也不能保证结果正确，重要交付物仍需按实际用途验收。
 
-## 一条实际可用的复核流程
+## General Agent 目录
 
-1. 先用最适合产出初稿的 Agent 发起单聊。
-2. 只附加任务真正需要的上下文；只有任务必须修改文件时才开启工作目录写入。
-3. 当任务需要另一种能力或独立质疑时，再转入群聊，并且只选择真正需要参与的 Agent。
-4. 对照最终回答、生成产物、回答版本和脱敏运行详情，再决定采用什么。
+当适配器和 CLI 版本兼容时，Meldwork 会检测并调用已安装的 Agent 命令。当前目录包括：
 
-Meldwork 不会在用户不知情的情况下合并无关会话。哪些文件、结论、Skill 和授权知识源可以进入下一项任务，始终由用户决定。
+<table>
+  <tr>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/codex.svg" alt="Codex logo" width="32" height="32"><br><strong>Codex</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/hermes.png" alt="Hermes logo" width="32" height="32"><br><strong>Hermes</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/openclaw-transparent.png" alt="OpenClaw logo" width="32" height="32"><br><strong>OpenClaw</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/workbuddy.png" alt="WorkBuddy logo" width="32" height="32"><br><strong>WorkBuddy</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/zcode.png" alt="Zcode logo" width="32" height="32"><br><strong>Zcode</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/pi.svg" alt="Pi Agent logo" width="32" height="32"><br><strong>Pi Agent</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/kimi.png" alt="Kimi Code logo" width="32" height="32"><br><strong>Kimi Code</strong></td>
+  </tr>
+  <tr>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/mimo.svg" alt="MiMo Code logo" width="32" height="32"><br><strong>MiMo Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/claude.png" alt="Claude Code logo" width="32" height="32"><br><strong>Claude Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/gemini.svg" alt="Gemini CLI logo" width="32" height="32"><br><strong>Gemini CLI</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/opencode.svg" alt="OpenCode logo" width="32" height="32"><br><strong>OpenCode</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/qwen.svg" alt="Qwen Code logo" width="32" height="32"><br><strong>Qwen Code</strong></td>
+    <td align="center" valign="top"><img src="frontend/public/agent-logos/opencodereview.svg" alt="OpenCodeReview logo" width="32" height="32"><br><strong>OpenCodeReview</strong></td>
+  </tr>
+</table>
 
-## 工作空间背后的 Harness
+已批准的 Agent Connector 和自定义可执行 Agent 使用桌面端的连接器入口。完整的适配器、安装、Provider 和能力矩阵见[桌面端指南](desktop/README.md)。
 
-![Meldwork Harness Engine](frontend/public/logos/Harness-readme.png)
+## 上下文与本地边界
 
-Harness 是让 Agent 协作不退化成复制 Prompt 和散落会话的关键层。它统一 Agent 事件，为每个目标构建有边界的上下文，隔离兼容的原生 Session，保存本地 Run 状态，并在认证或兼容性需要用户处理时暴露明确的恢复状态。
+Meldwork 作为本地 Electron 应用运行。对话、群组配置、运行记录和应用管理的附件保存在本地用户数据目录。渲染进程只通过受约束的 preload API 获取校验后的状态；可执行路径、凭据、原生会话引用、Skill 路径和任意 Shell 权限都留在主进程中。
 
-- **运行控制：** 明确点名、手动接力、有边界的自动轮次、停止与单 Agent 控制。
-- **上下文控制：** 稳定约束、选定文件、按目标分配的 Skill 与知识来源、近期结论和精简证据摘要。
-- **可检查的执行过程：** 结论、上下文来源、警告、终态，以及所选 Agent 或传输方式能够提供的计划和工具生命周期摘要。
-- **持久本地状态：** 会话与有界 Run 记录在完成或中断后仍可查看；上下文保持持久并可追溯。
+选定的 Agent 仍可能把 Prompt、附件或 Skill 发送到其自身 CLI 凭据对应的模型服务商。知识访问必须明确选择并受边界约束：当前实现支持本地 Obsidian 检索，以及由本地 CLI 管理的飞书或钉钉访问模式。Local-first 描述的是 Meldwork 的数据和协作位置，不代表 Agent 使用的模型服务商一定离线。
 
-## 适合放进哪些工作流
+## 下载 V1.0.9
 
-| 工作类型 | 第一个 Agent | 独立复核 |
-| --- | --- | --- |
-| 研究与情报 | 建立证据基础 | 检查无证据结论和缺失来源 |
-| 产品与战略 | 形成方案与决策模型 | 压测用户价值、可行性和高成本失败点 |
-| 软件开发 | 实现并验证改动 | 审查 Diff、测试、安全边界和回归风险 |
-| 写作与运营 | 形成交付物 | 检查结构、准确性、语气和执行风险 |
+Apple 芯片 macOS 用户请前往 [Meldwork V1.0.9 预发布页](https://github.com/Ryder-Sun/Meldwork/releases/tag/Meldwork-V1.0.9)，下载 [`Meldwork-1.0.9-arm64.dmg`](https://github.com/Ryder-Sun/Meldwork/releases/download/Meldwork-V1.0.9/Meldwork-1.0.9-arm64.dmg)。发布页同时提供 ZIP 压缩包和 SHA-256 校验文件。启动应用前，请至少安装一个受支持的本地 Agent CLI。
 
-目标不是堆叠尽可能多的 Agent。一个 Agent 足够时就直接完成；只有当另一种能力或独立复核能明显提高结果质量时，再加入第二个 Agent。模型请求仍然会按照你选择的 Agent 和 Provider 发出；“本地优先”描述的是 Meldwork 的工作空间和编排状态，而不是第三方模型的部署方式。
+该预览版安装包使用 ad-hoc 临时签名，未使用 Apple Developer ID 签名，也未进行公证。macOS 首次启动时可能需要在“系统设置 → 隐私与安全性”中选择“仍要打开 / Open Anyway”。
 
-## 当前可以连接的 Agent
+## 从源码运行
 
-Meldwork 当前已支持：
-
-**Codex · Hermes · OpenClaw · WorkBuddy · Kimi Code · MiMo Code · Claude Code · Gemini CLI · OpenCode · Qwen Code**
-
-专项审查：
-**OpenCodeReview**
-
-能否实际使用取决于本机安装情况、受支持版本、认证状态和 Agent 声明的能力。OpenCodeReview 是专项审查目标，不作为通用对话 Agent 使用。
-
-每个 Agent 保留自己的能力、Provider、权限模型和 Session 行为。能否使用取决于本机是否安装、版本是否兼容，以及对应认证是否就绪。
-
-## 当前发布范围
-
-首个经过发布验证的目标是 Apple 芯片 Mac。Windows 已具备实现层支持，但广泛的真实设备验证仍未完成；所有第三方 Agent 的广泛兼容性还不属于当前承诺。
-
-<details>
-<summary><strong>开发者从源码运行</strong></summary>
-
-源码开发需要 Node.js 20.19 或更高版本以及 npm：
+前置条件：Node.js `22.12+` 和 npm。
 
 ```bash
 npm --prefix frontend ci
@@ -118,7 +102,7 @@ npm --prefix desktop ci
 npm --prefix desktop run dev
 ```
 
-分发前请运行仓库测试脚本：
+分发构建前运行：
 
 ```bash
 npm --prefix frontend test
@@ -127,10 +111,27 @@ npm --prefix frontend run build:desktop
 npm --prefix desktop test
 ```
 
-</details>
+## V1.0.9
+
+自动讨论可根据原生 Agent 的明确完成信号结束发言，并要求所有参与者认可同一版交付物。一轮真实六 Agent 无限轮讨论在九轮后完成，交付物哈希一致。此预览版还改进了 Agent 认证状态、识别 CLI 在标准错误中报告的认证失败，并将知识库图标打包进应用。
+
+已安装 Agent 不代表模型连接可用：OpenClaw 的隔离环境可能无法使用现有原生配置，WorkBuddy CLI 可能需要单独登录，Zcode 需要有效的原生提供方凭据。桌面端和前端回归测试分别通过 1,700 项和 379 项。
+
+## V1.0.8
+
+V1.0.8 将 Kimi 只读问答改为手动权限模式，避免强制进入计划流程；修复 MiMo 末尾文本丢失、原生 CLI 配置变量遗漏，以及发送后 Auto Discussion 模式重置。原生输出持续重复时会取消调用并保留已输出内容。Zcode 保持官方标志和 Pi Agent 前的位置，沿用原生默认配置；WorkBuddy 可以复用在 Meldwork 中选定的桌面已配置模型。
+
+本轮对全部 13 个已安装 CLI 进行了真实调用。使用独立 Magpie 热修网关的五 Agent 无限轮讨论中，14 次原生调用全部完成。当前安装的 Magpie 可能把 `tool_calls:null` 误判为真实工具调用，将 `stop` 改写为 `tool_calls`，导致 OpenCode、MiMo 和 Hermes 持续续写；本次 Meldwork 发布不会安装或重启 Magpie。OpenClaw、Zcode、Gemini、Qwen 和 OpenCodeReview 在本机另有原生配置或认证故障，检测到安装不代表模型连接已可用。回归验证包括桌面测试 1,655 项、前端测试 370 项、Web 与桌面构建及打包验证。无限轮讨论保留进程停滞检测，工作区写入仍需明确授权。
+
+Electron 实机界面另完成一轮五 Agent 无限轮讨论：19 次原生调用全部成功，无失败或自动重试，用时约 12 分钟。发送、完成、切回首页再返回群聊后，自动讨论与不限轮数均保持选中。该验收同样使用独立热修网关，证明流程可完成，不构成响应时长保证，也不代表用户现有网关已修复。
+
+## 文档
+
+- [架构与产品边界](architecture.md)
+- [桌面端设置与 Agent 矩阵](desktop/README.md)
+- [贡献指南](CONTRIBUTING.md)
+- [安全策略](SECURITY.md)
 
 ## 许可证
 
-Meldwork 采用 [Meldwork 非商用源码许可](LICENSE)。你可以为个人学习、研究、评估、安全审查等非商用目的查看、运行、修改和分享本项目，但未经版权所有者事先书面许可，不得用于商业目的。
-
-商业使用包括转售、付费托管、托管服务、咨询或外包交付、闭源嵌入，以及由营利组织或为营利组织开展的业务使用。需要商用、集成、分发或单独商业许可，请先查看 [COMMERCIAL_USE.md](COMMERCIAL_USE.md) 并取得授权。第三方标识归属见 [NOTICE](NOTICE)。
+Meldwork 以 [Apache License 2.0](LICENSE) 开源。在许可证条款范围内，可以商用、私用、修改和再分发。商用无需另行授权或支付许可费。Apache-2.0 不授予商标权；详见 [COMMERCIAL_USE.md](COMMERCIAL_USE.md)。

SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-Meldwork is a local-first desktop application that invokes local Agent CLIs, stores local conversations, imports validated image, media, document, code, and archive attachments, and manages Provider credentials through the Electron main process.
+Meldwork is a local-first desktop application that invokes local Agent CLIs, stores local conversations, imports validated image, media, document, code, and archive attachments, and runs each Agent with its own native CLI credentials through the Electron main process.
 
 ## Reporting
 
@@ -11,10 +11,10 @@ Do not open a public issue with exploit details, secrets, local file paths, or p
 ## In Scope
 
 - Renderer-to-main IPC authorization bypasses.
-- Exposure of executable paths, attachment paths, native session references, Provider API keys, or Skill file paths to renderer code.
+- Exposure of executable paths, attachment paths, native session references, CLI API keys, or Skill file paths to renderer code.
 - Arbitrary shell execution, arbitrary file read/write, unsafe navigation, or unsafe installer behavior.
 - Attachment validation, private storage, checksum, or preview isolation failures.
-- Credential storage or Provider configuration failures that expose secrets.
+- Credential storage failures that expose secrets.
 
 ## Out of Scope
 

architecture.md

@@ -2,7 +2,7 @@
 
 ## Product Boundary
 
-Meldwork is a local Electron desktop product for direct and multi-Agent work with explicitly selected Skill, image, and knowledge-source context. It has no account system, tenant model, required application server, remote conversation store, email delivery, scheduled jobs, or public SEO surface. Optional Agent, Cloud, and Channel Connectors run behind the Electron main-process trust boundary and are disabled until explicitly configured.
+Meldwork is a local Electron desktop product for multi-agent orchestration and review with explicitly selected Skill, image, and knowledge-source context. It has no account system, tenant model, required application server, remote conversation store, email delivery, scheduled jobs, or hosted web surface. Optional Agent, Cloud, and Channel Connectors run behind the Electron main-process trust boundary and are disabled until explicitly configured. The landing page at https://ryder-mhumble.github.io/Meldwork/ is the public marketing surface for search engine and AI assistant discoverability.
 
 The supported product surface is the packaged Electron application. The frontend is a renderer bundle; without the local preload bridge it shows a desktop-required state and cannot operate the workspace.
 
@@ -11,47 +11,101 @@ The supported product surface is the packaged Electron application. The frontend
 | Component | Responsibility | Primary evidence |
 | --- | --- | --- |
 | Vue renderer | Agent-first multi-session UI, direct-session rename/delete, live direct-chat conclusions and inline execution summaries, group-chat result streaming with an expandable per-Agent/right-side trace panel, per-round navigation, background completion markers, first-run carousel, conversation/Skill/image/knowledge composer UI, bounded attachment-preview cache, theme/i18n, user confirmation and input collection | `frontend/src/App.vue`, `frontend/src/components/RunTracePanel.vue`, `frontend/src/composables/useAttachmentPreviews.js`, `frontend/src/desktop.js`, `frontend/src/knowledgeBaseCatalog.js` |
-| Electron preload | Exposes narrow workspace, Human Gate, Cloud control, installer/Skill, attachment, Provider, and knowledge-source methods through `window.roundrelayDesktop` only to a local `file:` document; Channel ingress has no renderer API | `desktop/src/preload.cjs` |
-| Electron main | Trust boundary for IPC authorization and shutdown gating, persistence, attachment import/preview, Connector registration, Skill and knowledge-source validation, local/Cloud execution, Channel receivers, navigation, sanitized run events, operating-system notifications, Provider storage, and installer control | `desktop/src/main.cjs` |
-| Local workspace | Persists Meldwork conversations, final replies, compact evidence capsules, safe message metadata, task-scoped group Sessions, conversation-scoped direct Sessions, legacy Session migration, Agent-specific transcript deltas, Agent preferences/runtime evidence, and active run coordination | `desktop/src/local-workspace.cjs` |
-| Run Ledger | Atomically checkpoints bounded, sanitized per-run and per-Agent state for stop/crash recovery, marks nonterminal runs and Agent attempts interrupted after restart, supports idempotent reconciliation of missing terminal Agent messages, and purges records with their conversation | `desktop/src/run-ledger.cjs` |
-| Context Pack and delivery stores | Capture immutable, content-addressed Task inputs, attempt-specific approved prompts, exact outbound fingerprints, source hashes, target scope, and native Session provenance | `desktop/src/context-pack-store.cjs`, `desktop/src/local-workspace-context-packs.cjs` |
-| Outcome store | Persists typed Artifacts, Evidence, Findings, and Adoption records separately from diagnostic reasoning and tool summaries | `desktop/src/outcome-store.cjs`, `desktop/src/outcome-records.cjs` |
-| Human Gate store | Persists permission, budget, and decision requests and their terminal user/system decisions without exposing raw request payloads to the renderer | `desktop/src/human-gate-store.cjs`, `desktop/src/human-gate-coordinator.cjs` |
-| Scheduling and failure policy | Enforces run budgets, retry policy, per-Agent controls, and global/workspace scheduling | `desktop/src/run-scheduler.cjs`, `desktop/src/failure-policy.cjs` |
-| Agent Connector registry/runtime | Validates approved manifests and instances, separates CredentialRefs, records Connector/upstream versions, and reduces versioned idempotent Run Events | `desktop/src/agent-connector-manifest.cjs`, `desktop/src/agent-connector-registry.cjs`, `desktop/src/agent-connector-runtime.cjs` |
-| Attachment store | Imports validated local images, media, documents, code/configuration files, Office files, and archives into private app-owned storage, verifies metadata/checksums on read, and removes unreferenced entries | `desktop/src/attachment-store.cjs`, `desktop/src/image-dimensions.cjs` |
-| Local Skill catalog | Scans bounded known roots per Agent and returns sanitized Skill coordinates without exposing paths or contents | `desktop/src/local-skill-catalog.cjs` |
-| Local knowledge-source catalog | Detects and probes code-defined Feishu, DingTalk, and Obsidian access modes, returns sanitized readiness, validates task selections, and exposes reference-only future sources | `desktop/src/local-knowledge-base.cjs` |
-| Knowledge Connector runtime | Executes main-owned bounded search/fetch/snapshot/citation operations for explicit source selections; the renderer receives only sanitized discovery and selection records | `desktop/src/local-knowledge-connectors.cjs`, `desktop/src/knowledge-connector-filesystem.cjs` |
-| Cloud Agent runtime | Persists remote job/cursor state and idempotent input, permission, cancel, callback, polling, reconciliation, and Artifact operations without requiring a server | `desktop/src/cloud-agent-runtime.cjs`, `desktop/src/cloud-agent-operation-store.cjs` |
-| Channel ingress runtime | Verifies main-owned Connector events, rejects replay/expired delivery, maps external actors and subscriptions to local Tasks, queues a durable Inbox, and audits outbound replies | `desktop/src/channel-ingress-runtime.cjs`, `desktop/src/channel-inbox-store.cjs` |
-| Knowledge-source store | Persists only the user-selected Obsidian Vault path; Feishu and DingTalk credentials remain owned by their local CLIs | `desktop/src/knowledge-base-store.cjs` |
-| CLI adapters | Detect and invoke supported local Agent executables with per-Agent arguments and constrained child environments | `desktop/src/cli-adapters.cjs` |
-| Agent installer | Detects Agents and runs allowlisted npm packages or official installer scripts after user confirmation | `desktop/src/agent-installer.cjs` |
-| Provider store | Validates Provider metadata and encrypts the API key with Electron `safeStorage` | `desktop/src/provider-store.cjs` |
-| Managed OpenClaw runtime | Creates isolated local configuration and a restricted tool policy for OpenClaw | `desktop/src/openclaw-runtime.cjs` |
+| Electron preload | Exposes narrow workspace, Human Gate, Cloud control, installer/Skill, attachment, and knowledge-source methods through `window.meldworkDesktop` only to a local `file:` document; Channel ingress has no renderer API | `desktop/src/preload.cjs` |
+| Electron main | Trust boundary for IPC authorization and shutdown gating, persistence, attachment import/preview, Connector registration, Skill and knowledge-source validation, local/Cloud execution, Channel receivers, navigation, sanitized run events, operating-system notifications, and installer control | `desktop/src/main.cjs` |
+| Local workspace | Persists Meldwork conversations, final replies, compact evidence capsules, safe message metadata, task-scoped group Sessions, conversation-scoped direct Sessions, legacy Session migration, Agent-specific transcript deltas, Agent preferences/runtime evidence, and active run coordination | `desktop/src/workspace/local-workspace.cjs` |
+| V4 orchestration | Validates frozen snapshots, phase-aware slots, typed collaboration receipts, negotiated responsibility graphs, work receipts, synthesis recovery, verification, and idempotent commits | `desktop/src/collaboration/orchestration-v4-records.cjs`, `desktop/src/workspace/local-workspace-message-submission.cjs`, `desktop/src/workspace/local-workspace-auto-runner.cjs` and its `local-workspace-auto-runner-*.cjs` parts (see Code Map) |
+| Run Ledger | Atomically checkpoints bounded, sanitized per-run and per-Agent state for stop/crash recovery, marks nonterminal runs and Agent attempts interrupted after restart, supports idempotent reconciliation of missing terminal Agent messages, and purges records with their conversation | `desktop/src/runs/run-ledger.cjs` |
+| Context Pack and delivery stores | Capture immutable, content-addressed Task inputs, attempt-specific approved prompts, exact outbound fingerprints, source hashes, target scope, and native Session provenance | `desktop/src/collaboration/context-pack-store.cjs`, `desktop/src/workspace/local-workspace-context-packs.cjs` |
+| Outcome store | Persists typed Artifacts, Evidence, Findings, and Adoption records separately from diagnostic reasoning and tool summaries | `desktop/src/collaboration/outcome-store.cjs`, `desktop/src/collaboration/outcome-records.cjs` |
+| Human Gate store | Persists permission, budget, and decision requests and their terminal user/system decisions without exposing raw request payloads to the renderer | `desktop/src/gates/human-gate-store.cjs`, `desktop/src/gates/human-gate-coordinator.cjs` |
+| Scheduling and failure policy | Enforces run budgets, per-Agent controls, and one writer at a time within a conversation (conversations never wait for each other); classifies failures (sign-in, rate limit, network, provider, context overflow) and decides retries with `Retry-After`; stops a silent Agent through the invocation watchdog | `desktop/src/runs/run-scheduler.cjs`, `desktop/src/runs/failure-policy.cjs`, `desktop/src/runs/failure-signals.cjs`, `desktop/src/runs/invocation-watchdog.cjs` |
+| Agent Connector registry/runtime | Validates approved manifests and instances, separates CredentialRefs, records Connector/upstream versions, and reduces versioned idempotent Run Events | `desktop/src/agents/connectors/agent-connector-manifest.cjs`, `desktop/src/agents/connectors/agent-connector-registry.cjs`, `desktop/src/agents/connectors/agent-connector-runtime.cjs` |
+| Attachment store | Imports validated local images, media, documents, code/configuration files, Office files, and archives into private app-owned storage, verifies metadata/checksums on read, and removes unreferenced entries | `desktop/src/attachments/attachment-store.cjs`, `desktop/src/attachments/image-dimensions.cjs` |
+| Local Skill catalog | Scans bounded known roots per Agent and returns sanitized Skill coordinates without exposing paths or contents | `desktop/src/skills/local-skill-catalog.cjs` |
+| Local knowledge-source catalog | Detects and probes code-defined Feishu, DingTalk, and Obsidian access modes, returns sanitized readiness, validates task selections, and exposes reference-only future sources | `desktop/src/knowledge/local-knowledge-base.cjs` |
+| Knowledge Connector runtime | Executes main-owned bounded search/fetch/snapshot/citation operations for explicit source selections; the renderer receives only sanitized discovery and selection records | `desktop/src/knowledge/local-knowledge-connectors.cjs`, `desktop/src/knowledge/knowledge-connector-filesystem.cjs` |
+| Cloud Agent runtime | Persists remote job/cursor state and idempotent input, permission, cancel, callback, polling, reconciliation, and Artifact operations without requiring a server | `desktop/src/agents/cloud/cloud-agent-runtime.cjs`, `desktop/src/agents/cloud/cloud-agent-operation-store.cjs` |
+| Channel ingress runtime | Verifies main-owned Connector events, rejects replay/expired delivery, maps external actors and subscriptions to local Tasks, queues a durable Inbox, and audits outbound replies | `desktop/src/channels/channel-ingress-runtime.cjs`, `desktop/src/channels/channel-inbox-store.cjs` |
+| Knowledge-source store | Persists only the user-selected Obsidian Vault path; Feishu and DingTalk credentials remain owned by their local CLIs | `desktop/src/knowledge/knowledge-base-store.cjs` |
+| CLI adapters | Detect and invoke supported local Agent executables with per-Agent arguments and constrained child environments | `desktop/src/agents/cli/cli-adapters.cjs` |
+| Agent installer | Detects Agents and runs allowlisted npm packages or official installer scripts after user confirmation | `desktop/src/agents/installer/agent-installer.cjs` |
+| Managed OpenClaw runtime | Creates isolated local configuration and a restricted tool policy for OpenClaw | `desktop/src/agents/cli/openclaw-runtime.cjs` |
+
+## Code Map
+
+The workspace is composed of small modules around a thin coordinator. A module either owns one piece of state or is a pure function of its inputs; each has a test file with the same name under `desktop/test/`.
+
+**One Agent invocation** (`desktop/src/workspace/local-workspace-agent-invocation.cjs`) is the run lifecycle: lease, run, race against stop and timeout, record the result. It delegates to:
+
+| Module | Owns |
+| --- | --- |
+| `invocation-session.cjs` | The native Agent session of one invocation: resume, adopt a new id, discard and rebuild, record the turn |
+| `invocation-outputs.cjs` | Workspace snapshot before a writable turn, media import and artifact descriptors after it |
+| `invocation-prompt.cjs` | The prompt one Agent receives (frozen, direct chat, group) |
+| `invocation-budget.cjs` | Usage recorded against the run budget |
+| `invocation-failure.cjs` | Why an invocation ended (stopped, timed out, interrupted, cancelled, failed) and the hidden error metadata |
+| `desktop/src/runs/invocation-watchdog.cjs` | Startup, inactivity and stall windows; liveness versus substantive progress |
+| `desktop/src/agents/agent-permission-policy.cjs` | Automatic answers to permission requests; a read-only turn only approves side-effect-free tools |
+| `desktop/src/collaboration/collaboration-receipt.cjs` | Parsing and normalising the control receipt at the end of a turn (lenient for natural discussion, strict for phased V4) |
+| `desktop/src/collaboration/answer-marker-filter.cjs` | Hides control markers while an answer streams |
+
+**Prompts** live in `desktop/src/workspace/prompts/`: `natural-discussion-prompt.cjs` (named sections: brief, writer, owner, routing, receipt), `manual-reply-prompt.cjs` (concurrent replies in a group), and `prompt-contracts.cjs` (the language and deliverable contracts shared by all of them). Direct chats are built by `directPromptFor` in `local-workspace-context.cjs`.
+
+**The automatic run** is `LocalWorkspaceAutoRunner`; its methods are grouped into files by what they do and assembled with `Object.assign` onto the class prototype:
+
+| File | Responsibility |
+| --- | --- |
+| `local-workspace-auto-runner.cjs` | Constructor, `start` and `resume`, run-level helpers |
+| `…-natural-discussion.cjs`, `…-natural-decisions.cjs` | The production path: transcript, prompts, the sequential and agent-led loops, and what happens after each round (owner takeover, ignored routes, peer blockers, missing decisions) |
+| `…-v4-discussion.cjs`, `…-v4-phase.cjs`, `…-v4-results.cjs` | The phased V4 run, one phase, and turning results into receipts and commits |
+| `…-v4-context.cjs`, `…-v4-delivery.cjs`, `…-v4-synthesis.cjs`, `…-v4-outcomes.cjs` | What a run freezes and shares, how context reaches each Agent, synthesis recovery, and the receipts, review issues, convergence and acceptance checks |
+| `…-recovery.cjs` | Retries, pausing a failed Agent for the run, unauthorized-session recovery |
+| `…-collaboration.cjs` | Collaboration records written as a run progresses |
+| `…-task-graph.cjs`, `…-rounds.cjs` | V3 task-graph and V2 round runs, kept only to resume older runs |
+
+Splitting by file did not change any method; the class still shares one `this`. New behaviour should go into a small module with its own tests and be called from the group that owns the topic, not appended to a large method.
+
+## Reliability Rules
+
+- Conversations are independent. A running chat, direct or group, never makes an Agent in another conversation wait, even when both use the same folder and the same Agent. The writer lease is scoped to the conversation; inside one conversation writers still take turns.
+- A failure pauses an Agent for the current run only. Group membership is never rewritten because an Agent failed; a group whose members were all removed by an older build is rebuilt from the Agents that replied in it.
+- Only a definitive sign-in failure marks credentials missing. A refusal that could be a proxy or a tool's own output is retried once and reported as a provider failure.
+- An Agent that was available stays available through an inconclusive readiness probe for ten minutes. A definitive answer applies immediately.
+- A stopped or failed turn keeps a healthy long-lived ACP process and its native session. The process is replaced only when it ignores cancellation or the protocol breaks.
+- Unknown ACP traffic (banners, new update kinds, unknown notifications) is ignored; unknown requests are answered with "method not found". Malformed JSON, invalid responses and invalid permission requests still fail closed.
+- Messages in a group topic carry a dispatch number (`turnSeq`) assigned before the Agent starts, so live and saved replies share one order. Failure and stop notices take the turn's number.
+- A discussion does not end on a malformed receipt, an absent recipient, a peer reporting a blocker or an owner who forgot the decision: those are discarded, handed to the owner, or asked for once.
+
+## Concurrent Collaboration V4
+
+- A group with multiple selected Agents in `manual` mode runs as one concurrent batch. Harness freezes every selected Agent's task snapshot and delivery plan before any Scheduler lease, preserves all selected members, and publishes the batch in stable member order after the barrier. Direct conversations, one-Agent targets, and regeneration keep their existing execution paths.
+- Auto Discussion begins with independent parallel proposals. The selected Agents then challenge the proposal set and negotiate one responsibility graph; every participant must agree to the same normalized plan before work begins. Harness validates and schedules that graph but does not privately assign the responsibilities.
+- The agreed work packages run according to their declared dependencies and produce typed Artifact/Evidence references. Proposal, challenge, work, and verification remain read-only; when workspace writes are enabled, the agreed finalizer is the only synthesis writer. Different Agents independently verify the current candidate.
+- V4 checkpoints phase, slots, attempts, receipts, delivery watermarks, negotiated roles, candidate state, and commit progress. Read-only work can recover automatically at supported boundaries; an unknown writable outcome requires a Human Gate before retry. Stop and cancellation reject late results.
+- V1 manual, V2 Auto Discussion, and V3 Task Graph records remain on their legacy parsers and executors. Renderer snapshots expose only validated public phase, participant, role, progress, and Gate state, never prompts, executable paths, native Session references, or internal snapshot contents.
+
+Automatic participant selection from a larger roster, production remote Agents, enterprise governance, and an Outcome Network are outside the V1.0.2 release boundary.
 
 ## Trust Boundaries
 
-1. The renderer is not trusted with Node.js, Agent executable paths, native Agent session IDs or storage paths, attachment paths, Skill paths/contents, raw Provider credentials after saving, arbitrary filesystem reads, or arbitrary process execution. User-selected conversation workdirs and the user-selected Obsidian Vault path are intentional UI-visible paths; pasted image bytes use one exact import payload.
+1. The renderer is not trusted with Node.js, Agent executable paths, native Agent session IDs or storage paths, attachment paths, Skill paths/contents, raw CLI credentials, arbitrary filesystem reads, or arbitrary process execution. User-selected conversation workdirs and the user-selected Obsidian Vault path are intentional UI-visible paths; pasted image bytes use one exact import payload.
 2. Preload exposes only named IPC methods. Main validates that every request comes from the current main frame and exact bundled frontend file.
 3. Main owns local files, OS dialogs, attachment validation/storage, Skill and knowledge-source discovery/revalidation, Connector approval/registration, Agent discovery, child processes, Cloud observation, Channel authentication, installer downloads, and credential encryption.
 4. Agent CLIs are external processes. They receive a selected working directory, a constrained environment, permission flags, main-resolved image paths, target-scoped immutable Skill snapshots, and validated knowledge snapshots or read-only hints after capability checks.
-5. Provider, Agent Connector, Cloud Connector, Channel Connector, and installer destinations are external trust boundaries. Provider URLs are user supplied and validated; manifests and Connector instances fail closed unless explicitly approved; Channel signatures and Workspace scope are verified before Task delivery.
+5. Agent Connector, Cloud Connector, Channel Connector, and installer destinations are external trust boundaries. Manifests and Connector instances fail closed unless explicitly approved; Channel signatures and Workspace scope are verified before Task delivery.
 6. Harness events expose only allowlisted status, conclusion deltas, reasoning summaries, plans, tool lifecycle summaries, bounded result metadata, and source message IDs. Raw chain-of-thought, commands, executable paths, native session references, credentials, unrestricted stdout/stderr, and arbitrary tool payloads remain outside the renderer and shared Agent context.
 
 ## Local Data
 
 | Data | Location | Protection |
 | --- | --- | --- |
-| Meldwork conversations, messages, native session-reference mappings, Agent preferences/runtime evidence | Electron user data: `roundrelay-workspace.json` | Local JSON written through main; group native references are keyed by Task and Agent, direct references by conversation and Agent, all remain main-only, and snapshots remove executable paths |
-| Bounded run checkpoints | Electron user data: `roundrelay-run-ledger.json` | Atomic private writes; `0600` file, with new parent directories created as `0700`; at most 64 sanitized runs with bounded Agent output/events/source IDs; no raw commands, paths, credentials, or native session references |
-| Immutable Context Packs, delivery records, content blobs, typed outcomes, and Human Gates | Electron user data under `roundrelay-private/` | Content-addressed or atomically written main-only records; renderer snapshots expose only bounded IDs, provenance summaries, budgets, and pending Gate choices |
-| Cloud operations and Channel Inbox | Electron user data under `roundrelay-private/` | Private `0600` stores keep opaque remote references, idempotency state, signed-event-derived Task data, delivery cursors, Task mappings, and outbound audit records; raw signatures, headers, credentials, and complete IM history are not exposed to the renderer |
+| Meldwork conversations, messages, native session-reference mappings, Agent preferences/runtime evidence | Electron user data: `meldwork-workspace.json` | Local JSON written through main; group native references are keyed by Task and Agent, direct references by conversation and Agent, all remain main-only, and snapshots remove executable paths |
+| Bounded run checkpoints | Electron user data: `meldwork-run-ledger.json` | Atomic private writes; `0600` file, with new parent directories created as `0700`; at most 64 sanitized runs with bounded Agent output/events/source IDs; no raw commands, paths, credentials, or native session references |
+| Immutable Context Packs, delivery records, content blobs, typed outcomes, and Human Gates | Electron user data under `meldwork-private/` | Content-addressed or atomically written main-only records; renderer snapshots expose only bounded IDs, provenance summaries, budgets, and pending Gate choices |
+| Cloud operations and Channel Inbox | Electron user data under `meldwork-private/` | Private `0600` stores keep opaque remote references, idempotency state, signed-event-derived Task data, delivery cursors, Task mappings, and outbound audit records; raw signatures, headers, credentials, and complete IM history are not exposed to the renderer |
 | Imported attachments | Electron user data under `attachments/` | App-owned copy; `0700` directories, `0600` files, type/MIME/size validation, image-dimension checks where applicable, metadata checksum, ID-only renderer access |
-| Provider metadata and encrypted key | Electron user data: `roundrelay-provider.json` | API key encrypted with `safeStorage`; file written atomically with mode `0600` |
-| Knowledge-source preference | Electron user data: `roundrelay-knowledge-base.json` | Stores the selected absolute Obsidian Vault path only; written atomically as a private file |
+| Knowledge-source preference | Electron user data: `meldwork-knowledge-base.json` | Stores the selected absolute Obsidian Vault path only; written atomically as a private file |
 | Managed OpenClaw state/config | Electron user data under `openclaw-managed/` | Per-scope directories, mode `0700`; config mode `0600`; API key passed by child environment |
 | Theme, locale, and onboarding completion | Renderer `localStorage` | Non-secret UI preferences |
 
@@ -63,7 +117,6 @@ There is no Meldwork-hosted remote data store or application account namespace.
 
 - Agent CLIs may call their own configured model providers.
 - Selected attachments and Skill-influenced prompts may be sent by an Agent CLI to its configured model provider after local validation and capability checks.
-- Compatible Agents may receive the user-configured Provider URL/model/key from main.
 - Feishu and DingTalk readiness probes may invoke their configured local CLIs; a selected Agent may then use those CLI connections with read-only instructions.
 - An explicit Obsidian selection is searched and fetched through the main-owned read-only filesystem Connector, then captured as an immutable snapshot or explicit live reference before Agent invocation.
 - Approved Agent Connectors may contact only their declared outbound destinations and receive main-owned CredentialRefs rather than renderer-provided secrets.
@@ -75,16 +128,17 @@ There is no Meldwork-hosted remote data store or application account namespace.
 
 ## Known Risks And Assumptions
 
-- Installer recipes use mutable upstream packages or scripts and currently do not verify a pinned digest or signature (`desktop/src/agent-installer.cjs`).
-- Conversation history is local but not application-encrypted (`desktop/src/local-workspace.cjs`).
-- Sanitized Run Ledger checkpoints are local and private but not application-encrypted. The store assumes one Electron main-process writer and recovers only the last persisted bounded checkpoint, not every in-memory event (`desktop/src/run-ledger.cjs`).
+- Writable conversations that share a folder are not coordinated. Two Agents in different conversations can edit the same files at the same time, as two terminals in one directory can. Output capture compares `.meldwork-output/` before and after a run, so when two conversations produce deliverables in the same folder at the same time, one may attach or record a file the other wrote.
+- Installer recipes use mutable upstream packages or scripts and currently do not verify a pinned digest or signature (`desktop/src/agents/installer/agent-installer.cjs`).
+- Conversation history is local but not application-encrypted (`desktop/src/workspace/local-workspace.cjs`).
+- Sanitized Run Ledger checkpoints are local and private but not application-encrypted. The store assumes one Electron main-process writer and recovers only the last persisted bounded checkpoint, not every in-memory event (`desktop/src/runs/run-ledger.cjs`).
 - Conversation deletion is privacy-first across two local JSON stores rather than transactional: Ledger records are removed first; if the workspace write then fails, in-memory conversation state is rolled back and remains retryable, but the deleted trace checkpoints are not recreated.
-- Imported attachment copies are private and integrity-checked but not application-encrypted (`desktop/src/attachment-store.cjs`).
-- Local Skill files are untrusted prompt input. Main prevents renderer-supplied paths and cross-Agent selection, but a selected Skill can still influence Agent behavior (`desktop/src/local-skill-catalog.cjs`, `desktop/src/local-workspace.cjs`).
+- Imported attachment copies are private and integrity-checked but not application-encrypted (`desktop/src/attachments/attachment-store.cjs`).
+- Local Skill files are untrusted prompt input. Main prevents renderer-supplied paths and cross-Agent selection, but a selected Skill can still influence Agent behavior (`desktop/src/skills/local-skill-catalog.cjs`, `desktop/src/workspace/local-workspace.cjs`).
 - Obsidian selections use a main-owned read-only Connector with bounded retrieval, immutable snapshots, and citation hash verification. Generic Feishu and DingTalk access remains CLI-owned and prompt-mediated; their authentication and document permissions are not controlled by Meldwork. Notion, Confluence, Google Drive, and SharePoint are reference-only planned sources and are not active Connectors.
-- Native image support is currently limited to Codex, Hermes, and OpenCode, with different per-run limits; mixed groups fail before execution when they cannot receive equal image context (`desktop/src/cli-adapters.cjs`).
-- Read-only enforcement is owned by the Obsidian Connector for captured selections. Agent workspace and CLI-mediated remote access still depends partly on each upstream CLI honoring its permission flags; Meldwork adds per-CLI hardening where available (`desktop/src/cli-adapters.cjs`).
-- Provider requests and native Agent authentication are external dependencies; Meldwork cannot guarantee their availability or data handling.
+- Native image support is currently limited to Codex, Hermes, and OpenCode, with different per-run limits; mixed groups fail before execution when they cannot receive equal image context (`desktop/src/agents/cli/cli-adapters.cjs`).
+- Read-only enforcement is owned by the Obsidian Connector for captured selections. Agent workspace and CLI-mediated remote access still depends partly on each upstream CLI honoring its permission flags; Meldwork adds per-CLI hardening where available (`desktop/src/agents/cli/cli-adapters.cjs`).
+- Native Agent authentication and model requests are external dependencies; Meldwork cannot guarantee their availability or data handling.
 - Agent/Cloud/Channel Connector contracts validate provenance, scope, and idempotency, but the external implementation must honor its CredentialRef, outbound destination, cancellation, and signature-verification obligations. The production build registers no Cloud or Channel Connector by default.
 - macOS packaging uses ad-hoc signing for local validation, not a notarized public release (`desktop/scripts/after-pack.cjs`).
 
@@ -92,14 +146,11 @@ There is no Meldwork-hosted remote data store or application account namespace.
 
 - No email sending, so there is no `emails.md`.
 - No cron or scheduled background work, so there is no `cron.md`.
-- No supported public or indexable routes, so there is no `seo.md`.
+- No supported public or indexable routes in the app itself, so there is no `seo.md`. The landing page at https://ryder-mhumble.github.io/Meldwork/ serves as the public discoverability surface for search engines and AI assistants.
 
 ## Related Documents
 
-- [Flows](flows.md)
-- [Permissions](permissions.md)
-- [Variables And Secrets](variables.md)
-- [Test Coverage](tests.md)
-- [Automation](automation.md)
-- [Public MVP Release Checklist](public-mvp-release.md)
-- [macOS Signing And Notarization](macos-signing.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security Policy](SECURITY.md)
+- [Repository Guidelines For Agents](AGENTS.md)
+- [Changelog](CHANGELOG.md)

desktop/README.md

@@ -4,7 +4,7 @@ Meldwork 是完全本地运行的 Electron 客户端。它直接加载仓库中
 主进程中检测和调用本机 Agent CLI，不需要登录、JWT、远端平台、Docker 或云端服务。
 
 本地群聊、消息、群组配置和 CLI 会话引用保存在 Electron 用户数据目录。渲染进程只通过
-`window.roundrelayDesktop` 调用经过约束的 preload API，不会获得可执行文件路径、Provider
+`window.meldworkDesktop` 调用经过约束的 preload API，不会获得可执行文件路径、Provider
 API Key 或任意 Shell 执行能力。
 
 支持检测和调用以下本机 Agent CLI：
@@ -13,22 +13,26 @@ API Key 或任意 Shell 执行能力。
 - Hermes
 - OpenClaw
 - WorkBuddy
+- Zcode
+- Pi Agent
 - Kimi Code
 - MiMo Code
 - Claude Code
 - Gemini CLI
 - OpenCode
 - Qwen Code
+- OpenCodeReview
 
 Agent 管理面板提供经过白名单约束的安装入口。安装命令和下载地址由主进程固定，不会根据页面
-输入执行任意命令。对支持强制权限模式的 Agent，群聊级工作目录写入默认关闭，只有用户明确
-授权后才会切换为写入模式；Hermes 和 OpenClaw 没有等价的强制只读参数，界面会明确标为
-“由 Agent 自身权限控制”。Kimi 在只读对话中通过 Agent Client Protocol 的 `plan` 模式运行；
-用户明确开启写入权限后，才切换到 Kimi 原生的 `stream-json --prompt` 模式。
+输入执行任意命令。内置 Agent 通过各自支持的原生权限模式或 Meldwork 托管工具策略执行；无法
+满足当前权限契约的 Agent 会安全失败。群聊级工作目录写入默认关闭，只有用户明确授权后才会
+切换为写入模式。Kimi 在只读对话中通过 Agent Client Protocol 的 `plan` 模式运行；用户明确
+开启写入权限后，才切换到 Kimi 原生的 `stream-json --prompt` 模式。
 
 ## 首次启动与本地 Agent 检测
 
-当前预览版未使用 Apple Developer ID 签名和公证。如果 macOS 首次启动时拦截应用，请打开
+V1.0.7 GitHub 预发布使用 ad-hoc 临时签名，不使用 Apple Developer ID，也不提交 Apple 公证。
+如果 macOS 首次启动时拦截候选应用，请打开
 “系统设置 → 隐私与安全性”，找到 Meldwork 的拦截提示，点击“仍要打开 / Open Anyway”，
 再确认启动。
 
@@ -37,6 +41,12 @@ Agent 管理面板提供经过白名单约束的安装入口。安装命令和
 用固定计时器伪装完成。检测成功或失败后才释放按钮。完成或关闭引导后会在渲染层本地记录状态，
 后续启动直接进入工作台；Agent 仍可在管理面板中重新检测。
 
+## 并发协作 Harness V4
+
+群聊中选择多个 Agent 后，“并发回复”会在任何 Agent 获取调度资源前冻结同一份任务快照，让全部已选 Agent 独立生成，并在批次屏障后按稳定顺序提交。
+
+Auto Discussion 会依次进入独立提案、交叉质询与职责协商、分工执行、单写者整合和独立复核。职责图由 Agent 协商产生，Harness 只负责验证全员同意的同一份计划、依赖、权限、回执、恢复和提交边界，不在模型之外私下分配工作。参与者仍由用户选定；从更大候选池自动选人组队不属于当前版本。
+
 ## `@` Skill 引用
 
 在消息输入框输入 `@` 或点击 `@` 按钮，可以选择当前目标 Agent 本机已发现的 Skill。列表只
@@ -59,34 +69,29 @@ Agent 原生支持的图片会按其数量限制直接传递。其他文件，
 
 ## Provider 配置
 
-用户可以在客户端内填写一个 OpenAI-compatible Provider：
-
-```text
-provider: Provider 显示名称
-baseUrl: HTTPS 地址，或本机 loopback HTTP 地址
-model: 模型名称
-apiKey: API Key
-```
-
-API Key 仅通过 Electron `safeStorage` 加密保存到本机；操作系统安全存储不可用时拒绝落盘。
-Provider 不设品牌、服务地址或模型默认值，也不会从远端自动获取配置。配置后可供 Hermes、
-OpenClaw、WorkBuddy、Qwen 和 OpenCodeReview 使用；其他 Agent 沿用各自的本机鉴权和 Provider 配置。
+Agent 使用各自本机的原生鉴权、Provider 和默认模型配置。Meldwork 不要求统一 Provider，
+也不会将一个 Agent 的密钥注入其他 Agent。WorkBuddy 桌面账号的加密登录不能直接供独立
+CLI 解锁；可在 Meldwork 中选择桌面配置里已有且已配置鉴权的模型。
+Meldwork 仅保存模型标识，运行时由主进程读取原生配置，不向渲染层返回密钥。
+Zcode 沿用默认配置；若其默认 Provider 缺少 API Key，需要先修复本机原生配置。
 
 ## 本地 CLI 支持矩阵
 
 | Agent | 检测命令 | macOS 安装 | Windows 安装 | 用户 Provider |
 | --- | --- | --- | --- | --- |
 | Codex | `codex` | npm：`@openai/codex@latest` | npm：`@openai/codex@latest` | 不注入；沿用 Codex 本机配置 |
-| Hermes | `hermes` | 官方 `install.sh` | 官方 `install.ps1` | 支持 |
-| OpenClaw | `openclaw` | npm：`openclaw@latest` | npm：`openclaw@latest` | 支持，使用客户端隔离的托管配置 |
-| WorkBuddy | `codebuddy` | npm：`@tencent-ai/[email protected]` | npm：`@tencent-ai/[email protected]` | 实验性支持 |
+| Hermes | `hermes` | 官方 `install.sh` | 官方 `install.ps1` | 沿用本机配置 |
+| OpenClaw | `openclaw` | npm：`openclaw@latest` | npm：`openclaw@latest` | 沿用本机配置 |
+| WorkBuddy | `codebuddy` | npm：`@tencent-ai/[email protected]` | npm：`@tencent-ai/[email protected]` | 可选择桌面已配置模型 |
+| Zcode | `zcode` | 官方 CLI 安装 | 官方 CLI 安装 | 沿用默认配置 |
+| Pi Agent | `pi` | npm：`@mariozechner/pi-coding-agent` | npm：`@mariozechner/pi-coding-agent` | 沿用本机配置 |
 | Kimi Code | `kimi` | 官方 `install.sh` | 官方 `install.ps1` | 不注入；沿用 Kimi 本机配置 |
-| MiMo Code | `mimo` | npm：`@mimo-ai/cli@latest` | npm：`@mimo-ai/cli@latest` | 不注入；沿用 MiMo 本机配置，Meldwork 固定使用只读 `plan` Agent |
+| MiMo Code | `mimo` | npm：`@mimo-ai/cli@latest` | npm：`@mimo-ai/cli@latest` | 不注入；沿用 MiMo 本机配置，按授权使用 `plan` / `build` 模式 |
 | Claude Code | `claude` | npm：`@anthropic-ai/claude-code@latest` | npm：`@anthropic-ai/claude-code@latest` | 不注入；沿用 Claude 本机配置 |
 | Gemini CLI | `gemini` | npm：`@google/gemini-cli@latest` | npm：`@google/gemini-cli@latest` | 不注入；沿用 Gemini 本机配置 |
 | OpenCode | `opencode` | npm：`opencode-ai@latest` | npm：`opencode-ai@latest` | 不注入；沿用 OpenCode 本机配置 |
-| Qwen Code | `qwen` | npm：`@qwen-code/qwen-code@latest` | npm：`@qwen-code/qwen-code@latest` | 支持 |
-| OpenCodeReview | `ocr` | npm：`@alibaba-group/open-code-review@latest` | npm：`@alibaba-group/open-code-review@latest` | 支持 |
+| Qwen Code | `qwen` | npm：`@qwen-code/qwen-code@latest` | npm：`@qwen-code/qwen-code@latest` | 沿用本机配置 |
+| OpenCodeReview | `ocr` | npm：`@alibaba-group/open-code-review@latest` | npm：`@alibaba-group/open-code-review@latest` | 沿用本机配置 |
 
 macOS 会在当前 `PATH` 之外搜索 Volta、pnpm、fnm、asdf、mise、bun、
 `~/.local/bin`、`~/.kimi-code/bin`、`~/.mimocode/bin`、Homebrew 等常见目录。Windows 会额外搜索用户 npm、
@@ -101,12 +106,12 @@ Hermes 和 Kimi 的安装脚本来自固定 HTTPS 白名单地址；客户端不
 - `src/agents/`：Agent 兼容层、路由、运行时、CLI、安装器、连接器
 - `src/attachments/`：附件、内容存储、图片尺寸校验
 - `src/collaboration/`：对话、上下文包、产物、任务图
-- `src/workspace/`：本地工作区与自动调度
+- `src/workspace/`：本地工作区与自动调度；自动运行器的通用失败、重试和等待语义位于 `local-workspace-auto-runner-support.cjs`
 - `src/runs/`：运行、预算、事件、调度、日志
 - `src/knowledge/`：知识库与知识连接器
 - `src/skills/`：Skill 目录、快照、信任
 - `src/security/`：私有文件与敏感信息脱敏
-- `test/`：按同名领域镜像组织测试，`support/` 放测试辅助代码
+- `test/`：按同名领域镜像组织测试，`support/` 放测试辅助代码；测试发现与 suite 选择位于 `scripts/test-discovery.cjs`
 
 ## 本地开发
 
@@ -118,7 +123,7 @@ npm run dev
 
 可选环境变量：
 
-- `ROUNDRELAY_CODEX_SANDBOX`：Codex 默认沙箱模式，支持 `read-only` 和
+- `MELDWORK_CODEX_SANDBOX`：Codex 默认沙箱模式，支持 `read-only` 和
   `workspace-write`；未设置或值不受支持时使用 `read-only`。
 
 ## 测试与打包
@@ -130,7 +135,9 @@ npm run dist
 npm run dist:public
 ```
 
-`pack` 和 `dist` 用于本地验证，会先构建桌面前端。`dist:public` 是公开发布专用命令：它要求
+`pack` 用于生成未打包应用并验证 Electron 产物；`dist` 生成 V1.0.7 GitHub 预发布候选使用的 ad-hoc 签名 DMG 和 ZIP。这些产物不具备 Developer ID 信任链且未公证，不能声称通过 Gatekeeper。
+
+`dist:public` 是未来正式签名公开发行的专用命令：它要求
 Developer ID 证书和完整公证凭据，强制代码签名，在签名后校验永久 Bundle ID、Team ID 与
 hardened runtime，并调用 Apple 公证；任一条件不满足都会失败。产物输出到 `desktop/dist/`，
 其中包含本地前端，不依赖服务器或容器。

desktop/package-lock.json

@@ -1,13 +1,13 @@
 {
   "name": "meldwork-desktop",
-  "version": "0.1.1",
+  "version": "1.0.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "meldwork-desktop",
-      "version": "0.1.1",
-      "license": "SEE LICENSE IN LICENSE",
+      "version": "1.0.9",
+      "license": "Apache-2.0",
       "dependencies": {
         "@agentclientprotocol/sdk": "0.23.0",
         "@streamparser/json": "0.0.22",
@@ -16,6 +16,9 @@
       "devDependencies": {
         "electron": "39.8.10",
         "electron-builder": "26.15.3"
+      },
+      "engines": {
+        "node": ">=22.12.0"
       }
     },
     "node_modules/@agentclientprotocol/sdk": {
@@ -2620,9 +2623,9 @@
       }
     },
     "node_modules/js-yaml": {
-      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
-      "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
+      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
       "dev": true,
       "funding": [
         {

desktop/package.json

@@ -1,10 +1,13 @@
 {
   "name": "meldwork-desktop",
-  "version": "0.1.1",
+  "version": "1.0.9",
   "private": true,
   "description": "A local-first desktop workspace for multi-Agent collaboration",
   "author": "Ryder-MHumble",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "main": "src/main.cjs",
   "scripts": {
     "build:frontend": "npm --prefix ../frontend run build:desktop",
@@ -12,7 +15,11 @@
     "connector:conformance": "node --test test/agents/connectors/agent-connector-manifest.test.cjs test/agents/connectors/agent-connector-registry.test.cjs test/agents/connectors/agent-connector-runtime.test.cjs test/agents/connectors/agent-connector-instance-store.test.cjs test/agents/connectors/agent-connector-package-store.test.cjs test/agents/connectors/agent-connector-sdk.test.cjs",
     "eval:deterministic": "node scripts/run-evals.cjs --suite deterministic",
     "eval:provider": "node scripts/run-evals.cjs --suite provider",
-    "test": "node --test \"test/**/*.test.cjs\"",
+    "test": "node scripts/run-tests.cjs",
+    "test:agents": "node scripts/run-tests.cjs --suite agents",
+    "test:runs": "node scripts/run-tests.cjs --suite runs",
+    "test:workspace": "node scripts/run-tests.cjs --suite workspace",
+    "test:security": "node scripts/run-tests.cjs --suite security",
     "pack": "npm run build:frontend && electron-builder --dir",
     "dist": "npm run build:frontend && electron-builder --mac dmg zip",
     "dist:public": "node scripts/public-release-preflight.cjs && npm run build:frontend && electron-builder --config electron-builder.public.cjs --mac dmg zip"
@@ -31,6 +38,7 @@
     "productName": "Meldwork",
     "artifactName": "Meldwork-${version}-${arch}.${ext}",
     "afterPack": "scripts/after-pack.cjs",
+    "afterAllArtifactBuild": "scripts/after-all-artifact-build.cjs",
     "files": [
       "src/**/*",
       "samples/**/*",
@@ -52,6 +60,10 @@
       {
         "from": "../COMMERCIAL_USE.md",
         "to": "COMMERCIAL_USE.md"
+      },
+      {
+        "from": "build/dmg-background-ai-v4.tiff",
+        "to": "dmg-background.tiff"
       }
     ],
     "mac": {
@@ -63,21 +75,23 @@
       ]
     },
     "dmg": {
-      "background": "build/dmg-background-ai-v2.png",
+      "background": "build/dmg-background-ai-v4.png",
+      "icon": null,
+      "writeUpdateInfo": false,
       "window": {
-        "width": 540,
-        "height": 380
+        "width": 640,
+        "height": 420
       },
-      "iconSize": 128,
+      "iconSize": 112,
       "contents": [
         {
-          "x": 145,
-          "y": 210,
+          "x": 110,
+          "y": 205,
           "type": "file"
         },
         {
-          "x": 395,
-          "y": 210,
+          "x": 520,
+          "y": 205,
           "type": "link",
           "path": "/Applications"
         }

desktop/samples/local-echo.connector.json

@@ -1 +1 @@
-{"manifest":{"connectorId":"external.local-echo-sample","connectorVersion":"1.0.0","credentials":{"mode":"none","slots":[]},"description":"Local SDK sample that returns text without delegating to a built-in Agent.","domains":["general"],"eventProtocolVersion":1,"eventTypes":["Completed","Failed","Cancelled"],"inputTypes":["text"],"invocation":{"recipeId":"sdk.local-echo.v1"},"kind":"agent","label":"Local Echo Connector Sample","license":"LicenseRef-Meldwork-NC","manifestId":"connector-manifest-6ce79bf9cbe282e9f537a1b45d742cc507e21ade5ea2859dff9e007bd4f850db","outboundDestinations":[],"permissionModes":["read-only"],"recordType":"agent-connector-manifest","schemaVersion":1,"session":{"cancel":true,"checkpoint":false,"resume":true,"supported":true},"transport":{"protocol":"json","type":"cli"},"upstream":{"id":"meldwork-sdk","maxVersion":"1.0.0","minVersion":"1.0.0"},"usage":{"costMicros":false,"elapsedMs":false,"inputTokens":false,"outboundBytes":false,"outputTokens":false,"toolCalls":false}},"packageId":"connector-package-f4908cee8fa7acf5d17a403b39bd58cb8d4a1dfec3fbfb43c62c5727ee793cd4","provider":{"config":{},"id":"sdk.local-echo.v1"},"publisher":{"id":"meldwork","name":"Meldwork"},"recordType":"agent-connector-package","schemaVersion":1}
+{"manifest":{"connectorId":"external.local-echo-sample","connectorVersion":"1.0.0","credentials":{"mode":"none","slots":[]},"description":"Local SDK sample that returns text without delegating to a built-in Agent.","domains":["general"],"eventProtocolVersion":1,"eventTypes":["Completed","Failed","Cancelled"],"inputTypes":["text"],"invocation":{"recipeId":"sdk.local-echo.v1"},"kind":"agent","label":"Local Echo Connector Sample","license":"Apache-2.0","manifestId":"connector-manifest-6ce79bf9cbe282e9f537a1b45d742cc507e21ade5ea2859dff9e007bd4f850db","outboundDestinations":[],"permissionModes":["read-only"],"recordType":"agent-connector-manifest","schemaVersion":1,"session":{"cancel":true,"checkpoint":false,"resume":true,"supported":true},"transport":{"protocol":"json","type":"cli"},"upstream":{"id":"meldwork-sdk","maxVersion":"1.0.0","minVersion":"1.0.0"},"usage":{"costMicros":false,"elapsedMs":false,"inputTokens":false,"outboundBytes":false,"outputTokens":false,"toolCalls":false}},"packageId":"connector-package-f4908cee8fa7acf5d17a403b39bd58cb8d4a1dfec3fbfb43c62c5727ee793cd4","provider":{"config":{},"id":"sdk.local-echo.v1"},"publisher":{"id":"meldwork","name":"Meldwork"},"recordType":"agent-connector-package","schemaVersion":1}

desktop/scripts/after-all-artifact-build.cjs

@@ -0,0 +1,126 @@
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { execFileSync } = require('node:child_process')
+
+const ROOT_HIDDEN_RESOURCES = ['.background.tiff', '.VolumeIcon.icns']
+
+function selectDmgArtifacts(artifactPaths) {
+  return artifactPaths.filter(artifactPath => artifactPath.endsWith('.dmg'))
+}
+
+function findBundledPython(cacheRoot = process.env.ELECTRON_BUILDER_CACHE) {
+  const root = cacheRoot || path.join(os.homedir(), 'Library', 'Caches', 'electron-builder')
+  const pending = [root]
+
+  while (pending.length > 0) {
+    const current = pending.pop()
+    let entries
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const entry of entries) {
+      const candidate = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        pending.push(candidate)
+      } else if (
+        entry.isFile()
+        && /^python3(?:\.\d+)?$/.test(entry.name)
+        && path.basename(current) === 'bin'
+        && candidate.includes(`${path.sep}dmg-builder@`)
+      ) {
+        return candidate
+      }
+    }
+  }
+
+  throw new Error(`Unable to locate dmg-builder's bundled Python under ${root}`)
+}
+
+function parseAttachedVolume(plist, workDir, run = execFileSync) {
+  const plistPath = path.join(workDir, 'attach.plist')
+  fs.writeFileSync(plistPath, plist)
+  const parsed = JSON.parse(run('plutil', ['-convert', 'json', '-o', '-', plistPath], {
+    encoding: 'utf8',
+  }))
+  const mounted = parsed['system-entities'].find(entity => entity['mount-point'])
+  if (!mounted) {
+    throw new Error('hdiutil did not return a mounted DMG volume')
+  }
+  return { device: mounted['dev-entry'], mountPath: mounted['mount-point'] }
+}
+
+function repointDmgBackground(dmgPath, options = {}) {
+  const run = options.execFile || execFileSync
+  const pythonPath = options.pythonPath || findBundledPython(options.cacheRoot)
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'meldwork-dmg-'))
+  const readWriteDmg = path.join(workDir, 'writable.dmg')
+  const repackedDmg = `${dmgPath}.repacked-${process.pid}.dmg`
+  let device
+
+  try {
+    run('hdiutil', ['convert', dmgPath, '-format', 'UDRW', '-o', readWriteDmg], {
+      stdio: 'pipe',
+    })
+    const attached = parseAttachedVolume(run('hdiutil', [
+      'attach', readWriteDmg, '-nobrowse', '-readwrite', '-plist',
+    ], { encoding: 'utf8' }), workDir, run)
+    device = attached.device
+
+    const backgroundPath = path.join(
+      attached.mountPath,
+      'Meldwork.app',
+      'Contents',
+      'Resources',
+      'dmg-background.tiff',
+    )
+    if (!fs.existsSync(backgroundPath)) {
+      throw new Error(`Packaged DMG background is missing: ${backgroundPath}`)
+    }
+
+    run(pythonPath, [
+      path.join(__dirname, 'repoint-dmg-background.py'),
+      path.join(attached.mountPath, '.DS_Store'),
+      backgroundPath,
+    ], { stdio: 'pipe' })
+
+    for (const resource of ROOT_HIDDEN_RESOURCES) {
+      fs.rmSync(path.join(attached.mountPath, resource), { force: true })
+    }
+    run('/usr/bin/SetFile', ['-a', 'c', attached.mountPath], { stdio: 'pipe' })
+    run('/bin/sync', [], { stdio: 'pipe' })
+    run('hdiutil', ['detach', device], { stdio: 'pipe' })
+    device = null
+
+    run('hdiutil', [
+      'convert', readWriteDmg, '-format', 'UDZO', '-imagekey', 'zlib-level=9', '-o', repackedDmg,
+    ], { stdio: 'pipe' })
+    fs.renameSync(repackedDmg, dmgPath)
+  } finally {
+    if (device) {
+      try {
+        run('hdiutil', ['detach', '-force', device], { stdio: 'pipe' })
+      } catch {}
+    }
+    fs.rmSync(repackedDmg, { force: true })
+    fs.rmSync(workDir, { recursive: true, force: true })
+  }
+}
+
+async function afterAllArtifactBuild(buildResult) {
+  for (const dmgPath of selectDmgArtifacts(buildResult.artifactPaths)) {
+    repointDmgBackground(dmgPath)
+  }
+  return []
+}
+
+afterAllArtifactBuild.ROOT_HIDDEN_RESOURCES = ROOT_HIDDEN_RESOURCES
+afterAllArtifactBuild.selectDmgArtifacts = selectDmgArtifacts
+afterAllArtifactBuild.findBundledPython = findBundledPython
+afterAllArtifactBuild.parseAttachedVolume = parseAttachedVolume
+afterAllArtifactBuild.repointDmgBackground = repointDmgBackground
+
+module.exports = afterAllArtifactBuild

desktop/scripts/render-dmg-background.swift

@@ -0,0 +1,72 @@
+#!/usr/bin/env swift
+import AppKit
+import Foundation
+
+let arguments = CommandLine.arguments
+guard arguments.count == 3 else {
+    fputs("Usage: render-dmg-background.swift <source.png> <output.png>\n", stderr)
+    exit(1)
+}
+
+let sourceURL = URL(fileURLWithPath: arguments[1])
+let outputURL = URL(fileURLWithPath: arguments[2])
+guard let source = NSImage(contentsOf: sourceURL) else {
+    fputs("Unable to read source image\n", stderr)
+    exit(1)
+}
+guard let bitmap = NSBitmapImageRep(
+    bitmapDataPlanes: nil,
+    pixelsWide: 1280,
+    pixelsHigh: 840,
+    bitsPerSample: 8,
+    samplesPerPixel: 4,
+    hasAlpha: true,
+    isPlanar: false,
+    colorSpaceName: .deviceRGB,
+    bytesPerRow: 0,
+    bitsPerPixel: 0
+) else {
+    fputs("Unable to create output bitmap\n", stderr)
+    exit(1)
+}
+
+NSGraphicsContext.saveGraphicsState()
+NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: bitmap)
+source.draw(
+    in: NSRect(x: 0, y: 0, width: 1280, height: 840),
+    from: NSRect(x: 0, y: 4, width: 1280, height: 840),
+    operation: .copy,
+    fraction: 1
+)
+
+let centered = NSMutableParagraphStyle()
+centered.alignment = .center
+
+let title = "INSTALL MELDWORK" as NSString
+title.draw(
+    in: NSRect(x: 0, y: 712, width: 1280, height: 52),
+    withAttributes: [
+        .font: NSFont(name: "DIN Alternate Bold", size: 38) ?? NSFont.boldSystemFont(ofSize: 38),
+        .foregroundColor: NSColor(white: 0.96, alpha: 0.94),
+        .kern: 4.5,
+        .paragraphStyle: centered,
+    ]
+)
+
+let explanation = "DRAG MELDWORK INTO APPLICATIONS  /  YOUR WORKSPACE STAYS LOCAL" as NSString
+explanation.draw(
+    in: NSRect(x: 0, y: 675, width: 1280, height: 30),
+    withAttributes: [
+        .font: NSFont(name: "Menlo-Regular", size: 14) ?? NSFont.monospacedSystemFont(ofSize: 14, weight: .regular),
+        .foregroundColor: NSColor(white: 0.82, alpha: 0.74),
+        .kern: 1.5,
+        .paragraphStyle: centered,
+    ]
+)
+NSGraphicsContext.restoreGraphicsState()
+
+guard let png = bitmap.representation(using: .png, properties: [:]) else {
+    fputs("Unable to encode PNG\n", stderr)
+    exit(1)
+}
+try png.write(to: outputURL)

desktop/scripts/repoint-dmg-background.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+import sys
+
+from ds_store import DSStore
+from mac_alias import Alias
+
+
+def main():
+    ds_store_path, background_path = sys.argv[1:3]
+    with DSStore.open(ds_store_path, "r+") as store:
+        icon_view = store["."]["icvp"]
+        icon_view["backgroundImageAlias"] = Alias.for_file(background_path).to_bytes()
+        store["."]["icvp"] = icon_view
+
+
+if __name__ == "__main__":
+    main()

desktop/scripts/run-tests.cjs

@@ -0,0 +1,19 @@
+const { spawnSync } = require('node:child_process')
+const { discoverTestFiles } = require('./test-discovery.cjs')
+
+function option(name, fallback) {
+  const index = process.argv.indexOf(name)
+  return index === -1 ? fallback : process.argv[index + 1] || fallback
+}
+
+const suite = option('--suite', 'all')
+const result = spawnSync(process.execPath, [
+  '--test',
+  '--test-concurrency=2',
+  ...discoverTestFiles({ suite }),
+], {
+  stdio: 'inherit',
+})
+
+if (result.error) throw result.error
+process.exitCode = result.status ?? 1

desktop/scripts/test-discovery.cjs

@@ -0,0 +1,43 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const TEST_SUITES = Object.freeze({
+  agents: ['agents'],
+  attachments: ['attachments'],
+  collaboration: ['collaboration'],
+  core: ['channels', 'knowledge', 'media', 'skills'],
+  runs: ['runs'],
+  security: ['security', 'shell'],
+  workspace: ['workspace', 'gates'],
+})
+
+function collectTestFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const filename = path.join(directory, entry.name)
+    if (entry.isDirectory()) return collectTestFiles(filename)
+    return entry.isFile() && entry.name.endsWith('.test.cjs') ? [filename] : []
+  })
+}
+
+function normalizeSuite(suite) {
+  const value = String(suite || 'all').trim().toLowerCase()
+  if (value === 'all') return null
+  if (!Object.hasOwn(TEST_SUITES, value)) {
+    throw new Error(`Unknown desktop test suite: ${value}`)
+  }
+  return new Set(TEST_SUITES[value])
+}
+
+function testSuiteForFile(filename, directory = 'test') {
+  const relative = path.relative(path.resolve(directory), filename)
+  return relative.split(path.sep)[0] || 'core'
+}
+
+function discoverTestFiles({ directory = 'test', suite = 'all' } = {}) {
+  const selectedRoots = normalizeSuite(suite)
+  return collectTestFiles(path.resolve(directory))
+    .filter((filename) => !selectedRoots || selectedRoots.has(testSuiteForFile(filename, directory)))
+    .sort()
+}
+
+module.exports = { TEST_SUITES, discoverTestFiles, normalizeSuite, testSuiteForFile }

desktop/src/agents/agent-compatibility.cjs

@@ -5,6 +5,8 @@ const AGENT_VERSION_IDENTITIES = Object.freeze({
   hermes: [/\bhermes(?:\s+agent)?\b/i],
   openclaw: [/\bopenclaw\b/i],
   workbuddy: [/\b(?:workbuddy|codebuddy)\b/i],
+  zcode: [/\bzcode\b/i],
+  pi: [/\bpi(?:\s+agent)?\b/i],
   kimi: [/\bkimi(?:\s+code)?\b/i],
   mimo: [/\bmimo(?:\s+code)?\b/i, /\bmimocode\b/i],
   claude: [/\bclaude(?:\s+code)?\b/i],
@@ -18,6 +20,8 @@ const AGENT_EXECUTABLE_NAMES = Object.freeze({
   hermes: ['hermes'],
   openclaw: ['openclaw'],
   workbuddy: ['codebuddy'],
+  zcode: ['zcode'],
+  pi: ['pi', 'pi-agent', 'piagent'],
   kimi: ['kimi'],
   mimo: ['mimo'],
   claude: ['claude'],
@@ -54,6 +58,14 @@ const AGENT_COMPATIBILITY = Object.freeze({
       'json', 'plan', 'acceptEdits',
     ]),
   ]),
+  zcode: exactProfile('0.16.1', [
+    probe('zcode-prompt', ['--help'], ['--prompt', '--json', '--mode', '--resume', 'plan', 'edit']),
+  ]),
+  pi: exactProfile('0.84.2', [
+    probe('pi-cli', ['--help'], [
+      '--mode', '--print', '--session', '--tools', '--approve', '--no-approve', 'json',
+    ]),
+  ]),
   kimi: profile('0.19.2', '0.32.0', [
     probe('kimi-stream', ['--help'], [
       '--output-format', '--auto', '--session', '--prompt', 'stream-json',
@@ -94,11 +106,13 @@ const AGENT_COMPATIBILITY = Object.freeze({
   ]),
 })
 
-function probe(id, args, requiredText) {
+function probe(id, args, requiredText, validateOutput = null, timeout = null) {
   return Object.freeze({
     id,
     args: Object.freeze([...args]),
     requiredText: Object.freeze([...requiredText]),
+    validateOutput,
+    timeout,
   })
 }
 
@@ -256,6 +270,7 @@ module.exports = {
   AGENT_COMPATIBILITY,
   assessAgentVersion,
   capabilityProbes,
+  compareReleaseVersions,
   extractAgentVersion,
   identifyAgentVersion,
 }

desktop/src/agents/agent-output-importer.cjs

@@ -426,7 +426,7 @@ function importAgentOutputs(input, attachmentStore) {
     && !Array.isArray(input.baseline.files)
     ? input.baseline.files
     : {}
-  const candidates = outputFiles(safeOutputDirectory(workdirRealPath))
+  const controlledCandidates = outputFiles(safeOutputDirectory(workdirRealPath))
     .filter(file => !sameFileState(baselineFiles[file.name], file))
     .filter(file => Math.max(file.mtimeMs, file.ctimeMs) >= startedAt - 2000)
     .sort((left, right) => (
@@ -434,6 +434,30 @@ function importAgentOutputs(input, attachmentStore) {
       || left.name.localeCompare(right.name)
     ))
 
+  const reportedCandidates = []
+  const reportedPaths = Array.isArray(input.reportedPaths) ? input.reportedPaths : []
+  for (const reportedPath of reportedPaths.slice(0, MAX_SCANNED_ENTRIES)) {
+    if (typeof reportedPath !== 'string' || !path.isAbsolute(reportedPath)) continue
+    try {
+      const realPath = fs.realpathSync(reportedPath)
+      const stat = fs.statSync(realPath)
+      const extension = path.extname(realPath).toLowerCase()
+      // A path the Agent merely mentioned (a file it read, the user's input,
+      // a staged attachment) is not an output. Only files written during this
+      // run outside the input staging folder are imported.
+      if (!stat.isFile() || !SUPPORTED_EXTENSIONS.has(extension)
+          || stat.size > 64 * 1024 * 1024 || !isInside(workdirRealPath, realPath)
+          || realPath.split(path.sep).includes('.meldwork-input')
+          || stat.mtimeMs < startedAt - 2000) continue
+      reportedCandidates.push({
+        name: path.basename(realPath), path: realPath, size: stat.size,
+        mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs,
+      })
+    } catch { /* reported paths are best effort */ }
+  }
+  const candidates = [...controlledCandidates, ...reportedCandidates]
+    .filter((file, index, all) => all.findIndex(candidate => candidate.path === file.path) === index)
+
   const imported = []
   if (input.signal?.aborted) return imported
   for (const file of candidates) {

desktop/src/agents/agent-permission-policy.cjs

@@ -0,0 +1,85 @@
+const { createHash } = require('node:crypto')
+const { canonicalJson } = require('../collaboration/context-pack-records.cjs')
+
+function sha256(value) {
+  return createHash('sha256').update(String(value || '')).digest('hex')
+}
+
+// Tool kinds an Agent may use without approval during a read-only turn.
+const READ_ONLY_SAFE_TOOL_KINDS = new Set(['read', 'search', 'fetch', 'think'])
+
+function terminalPlanRejection(options = []) {
+  // Kimi's first reject option is "Revise", which loops without feedback.
+  return options.find(option => option?.optionId === 'plan_reject_and_exit'
+    && ['reject_once', 'reject_always'].includes(option.kind))
+}
+
+// Automatic answer to an Agent's permission request when the run is not
+// waiting for a person. Returns the response to send, `null` when the request
+// is refused but the Agent offered nothing to refuse with, or `undefined`
+// when no automatic answer exists and the caller must ask the user.
+//
+// A read-only turn stays read-only even when the Agent asks: only
+// side-effect-free tools are approved, while edits, deletes, moves, commands
+// and mode switches are refused.
+function automaticPermissionResponse(request, { allowWrite }) {
+  const options = Array.isArray(request?.options) ? request.options : []
+  if (!allowWrite && !READ_ONLY_SAFE_TOOL_KINDS.has(request?.toolCall?.kind)) {
+    const rejection = terminalPlanRejection(options)
+      || options.find(candidate => candidate?.kind === 'reject_once')
+      || options.find(candidate => candidate?.kind === 'reject_always')
+    return rejection?.optionId ? { status: 'rejected', optionId: rejection.optionId } : null
+  }
+  const option = options.find(candidate => candidate?.kind === 'allow_once')
+    || options.find(candidate => candidate?.kind === 'allow_always')
+    || options[0]
+  return option?.optionId ? { status: 'approved', optionId: option.optionId } : undefined
+}
+
+// A person's decision applies only to the exact request it was made for.
+function matchesResumedPermission(request, resumedGate) {
+  if (!request || !resumedGate?.request) return false
+  try {
+    if (canonicalJson(request) !== canonicalJson(resumedGate.request)) return false
+  } catch {
+    return false
+  }
+  const selected = request.options?.find(option => option.optionId === resumedGate.optionId)
+  if (!selected) return false
+  return resumedGate.status === 'approved'
+    ? selected.kind.startsWith('allow_')
+    : selected.kind.startsWith('reject_')
+}
+
+function permissionContinuationRequestId(requestHash, binding) {
+  return sha256(canonicalJson({
+    requestHash,
+    sessionRefHash: binding.sessionRefHash,
+    sessionProvenanceHash: binding.sessionProvenanceHash,
+  }))
+}
+
+// A resumed permission decision must belong to the native session the
+// request came from; anything else is refused before the Agent runs.
+function assertResumedPermissionBinding(resumed, currentBinding, sessionRef) {
+  const requestHash = sha256(canonicalJson(resumed.request))
+  const persistedBinding = {
+    sessionRefHash: resumed.sessionRefHash,
+    sessionProvenanceHash: resumed.sessionProvenanceHash,
+  }
+  if (resumed.requestId !== permissionContinuationRequestId(requestHash, persistedBinding)
+      || resumed.requestHash !== requestHash
+      || resumed.sessionProvenanceHash !== currentBinding.sessionProvenanceHash
+      || (sessionRef && resumed.sessionRefHash !== currentBinding.sessionRefHash)) {
+    throw new Error('LOCAL_RUN_PERMISSION_REQUEST_MISMATCH')
+  }
+}
+
+module.exports = {
+  terminalPlanRejection,
+  READ_ONLY_SAFE_TOOL_KINDS,
+  assertResumedPermissionBinding,
+  automaticPermissionResponse,
+  matchesResumedPermission,
+  permissionContinuationRequestId,
+}

desktop/src/agents/agent-routing.cjs

@@ -7,6 +7,7 @@ const {
   AGENT_PERMISSION_MODES,
   AGENT_TOOL_CLASSES,
   agentRuntimeCapabilities,
+  isCodeReviewAgentKind,
 } = require('./agent-runtime-contract.cjs')
 const { parseFitMatrix } = require('../evaluations/eval-records.cjs')
 const { cleanInline, isSupportedAgentKind } = require('../workspace/local-workspace-contracts.cjs')
@@ -331,23 +332,39 @@ class AgentRouter {
     )) {
       throw routingError('LOCAL_AGENT_ROUTING_CONTEXT_CONFLICT')
     }
-    const requirements = normalizeRoutingRequirements(input.routingRequirements, {
-      domains: effectiveMode === 'automatic' ? ['general'] : [],
-      inputTypes,
-      outputTypes: ['text'],
-      permissionMode: group.allowWrite === true ? 'workspace-write' : 'read-only',
-      minContextChars,
-      collaboration: mode === 'auto' ? 'required' : 'none',
-    })
     const approvedKinds = targetList(group.agentKinds)
     const explicitTargets = effectiveMode === 'explicit' && !requestedTargets.length
       ? approvedKinds
       : requestedTargets
+    const explicitReadOnlyTargets = effectiveMode === 'explicit'
+      && explicitTargets.length > 0
+      && explicitTargets.every(kind => isCodeReviewAgentKind(kind))
+    const detected = new Map((Array.isArray(agents) ? agents : []).map(agent => [agent.kind, agent]))
+    const permissionTargets = effectiveMode === 'explicit' ? explicitTargets : approvedKinds
+    const targetWriteSupport = permissionTargets.map((kind) => (
+      agentRuntimeCapabilities(kind, {
+        agent: detected.get(kind),
+        attachmentSupport: this.attachmentSupport(kind),
+      }).permissionModes.includes('workspace-write')
+    ))
+    const writePermissionCompatible = effectiveMode === 'explicit'
+      ? targetWriteSupport.every(Boolean)
+      : targetWriteSupport.some(Boolean)
+    const permissionMode = explicitReadOnlyTargets || !writePermissionCompatible
+      ? 'read-only'
+      : group.allowWrite === true ? 'workspace-write' : 'read-only'
+    const requirements = normalizeRoutingRequirements(input.routingRequirements, {
+      domains: effectiveMode === 'automatic' ? ['general'] : [],
+      inputTypes,
+      outputTypes: ['text'],
+      permissionMode,
+      minContextChars,
+      collaboration: mode === 'auto' ? 'required' : 'none',
+    })
     if (explicitTargets.some(kind => !approvedKinds.includes(kind))) {
       const kind = explicitTargets.find(target => !approvedKinds.includes(target))
       throw routingError('LOCAL_MESSAGE_TARGET_OUT_OF_GROUP', { kind })
     }
-    const detected = new Map((Array.isArray(agents) ? agents : []).map(agent => [agent.kind, agent]))
     const candidates = approvedKinds.map((kind) => evaluateCandidate(
       detected.get(kind) || { kind, available: false },
       requirements,

desktop/src/agents/agent-runtime-contract.cjs

@@ -1,3 +1,4 @@
+const { authFailureCertainty } = require('../runs/failure-signals.cjs')
 const AGENT_OUTCOMES = Object.freeze([
   'accepted',
   'running',
@@ -79,6 +80,14 @@ const AGENT_RUNTIME_CAPABILITIES = Object.freeze({
     domains: ['general', 'software-development', 'document-production'],
     toolClasses: ['filesystem', 'shell'],
   }),
+  zcode: generalProfile({
+    domains: ['general', 'software-development', 'research'],
+    toolClasses: ['filesystem', 'shell'],
+  }),
+  pi: generalProfile({
+    domains: ['general', 'software-development'],
+    toolClasses: ['filesystem', 'shell'],
+  }),
   kimi: generalProfile({
     domains: ['general', 'software-development', 'research', 'document-production'],
     toolClasses: ['filesystem', 'shell'],
@@ -119,6 +128,7 @@ const AGENT_RUNTIME_CAPABILITIES = Object.freeze({
 })
 
 const DEFAULT_RUNTIME_CAPABILITIES = generalProfile({ resumable: false })
+const REVIEW_ONLY_AGENT_KINDS = Object.freeze(new Set())
 
 function boundedValues(value, allowed, fallback) {
   if (!Array.isArray(value) || !value.length) return [...fallback]
@@ -205,10 +215,34 @@ function normalizeExternalRunRef(value) {
   return EXTERNAL_RUN_REF.test(ref) ? ref : ''
 }
 
+function terminalAuthenticationDiagnostic(value) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim()
+  if (!text || text.length > 2000) return ''
+  return /^HTTP\s+(?:401|403)\s*:\s*(?:unauthorized|forbidden|(?:invalid|expired|missing)\s+(?:access\s+token|token|credentials?|api[ _-]?key|authentication))(?:\s*\(request[ _-]?id:\s*[^()]{1,160}\))?\.?$/i
+    .test(text)
+    ? text
+    : ''
+}
+
+// True only for explicit sign-in or API-key statements. Ambiguous refusals
+// (HTTP 403, proxy or region blocks, "provider rejected") are classified as
+// LOCAL_AGENT_ACCESS_DENIED so they are retried instead of signing the Agent out.
+function authConfigurationFailure(detail) {
+  return authFailureCertainty(detail) === 'definitive'
+}
+
+function authFailureCode(detail) {
+  const certainty = authFailureCertainty(detail)
+  if (certainty === 'definitive') return 'LOCAL_AGENT_AUTH_REQUIRED'
+  if (certainty === 'ambiguous') return 'LOCAL_AGENT_ACCESS_DENIED'
+  return ''
+}
+
 function failureCategory(code) {
   const value = String(code || '')
   if (value === 'LOCAL_AGENT_SESSION_INVALID') return 'session'
-  if (value === 'LOCAL_AGENT_AUTH_REQUIRED') return 'authentication'
+  if (value === 'LOCAL_AGENT_AUTH_REQUIRED' || value === 'LOCAL_WORKBUDDY_PROVIDER_AUTH') return 'authentication'
+  if (value === 'LOCAL_AGENT_ACCESS_DENIED') return 'provider'
   if (value === 'LOCAL_AGENT_TIMEOUT') return 'timeout'
   if (value === 'LOCAL_AGENT_EXECUTION_STOPPED') return 'cancellation'
   if (value === 'LOCAL_AGENT_REFUSED') return 'refusal'
@@ -285,19 +319,40 @@ function requireTerminalAgentResult(result) {
     throw agentRuntimeError('LOCAL_AGENT_EXECUTION_STOPPED')
   }
   if (normalized.outcome === 'failed') {
-    const failure = normalized.failure?.code
+    let failure = normalized.failure?.code
       ? normalized.failure
       : agentRuntimeFailure('LOCAL_AGENT_PROCESS_FAILED')
+    const diagnostic = String(normalized.diagnostic || normalized.text || '')
+    // A structured failure whose diagnostic names an authentication problem is
+    // an authentication failure even when the CLI reported a generic process
+    // error, so the catalog can mark the Agent as needing a fresh login.
+    if (failure.category !== 'authentication' && authConfigurationFailure(diagnostic)) {
+      failure = agentRuntimeFailure('LOCAL_AGENT_AUTH_REQUIRED')
+    } else if (failure.code === 'LOCAL_AGENT_PROCESS_FAILED'
+        && authFailureCertainty(normalized.diagnostic) === 'ambiguous') {
+      failure = agentRuntimeFailure('LOCAL_AGENT_ACCESS_DENIED')
+    }
     throw agentRuntimeError(
       failure.code,
       normalized.diagnostic || normalized.text,
       failure,
     )
   }
+  const authenticationDiagnostic = terminalAuthenticationDiagnostic(normalized.text)
+  if (authenticationDiagnostic) {
+    throw agentRuntimeError(
+      authFailureCode(authenticationDiagnostic) || 'LOCAL_AGENT_ACCESS_DENIED',
+      authenticationDiagnostic,
+    )
+  }
   return normalized
 }
 
 function isReviewOnlyAgentKind(kind) {
+  return REVIEW_ONLY_AGENT_KINDS.has(kind)
+}
+
+function isCodeReviewAgentKind(kind) {
   return agentRuntimeCapabilities(kind).task === 'code_review'
 }
 
@@ -316,10 +371,14 @@ module.exports = {
   agentRuntimeCapabilities,
   agentRuntimeError,
   agentRuntimeFailure,
+  authConfigurationFailure,
+  authFailureCode,
+  isCodeReviewAgentKind,
   isReviewOnlyAgentKind,
   normalizeAgentResult,
   normalizeExternalRunRef,
   normalizeOutcome,
   outcomeForAcpStopReason,
   requireTerminalAgentResult,
+  terminalAuthenticationDiagnostic,
 }

desktop/src/agents/cli/cli-adapters.cjs

@@ -7,35 +7,35 @@ const {
   searchPath,
 } = require('./cli-discovery.cjs')
 const {
-  classifyCliOutcome,
-  claudeQwenRuntimeEvents,
-  codexProgressEvent,
-  codexRuntimeEvents,
-  createClaudeQwenRuntimeState,
-  createJsonLineParser,
   createRuntimeEventEmitter,
-  createStructuredOutputAccumulator,
-  hermesSessionRef,
-  jsonCliRuntimeEvents,
-  normalizeOpenClawOutput,
   parseClaudeQwenOutput,
   parseCodexOutput,
   parseGeminiOutput,
-  parseJsonOutputEvents,
   parseKimiOutput,
   parseMimoOutput,
   parseOpenCodeOutput,
   parseOpenCodeReviewOutput,
+  parsePiOutput,
   parseWorkBuddyOutput,
   readHermesFinalResponse,
   readHermesMessageWatermark,
   redactChildSecrets,
   runtimeCommandSummary,
-  stripAnsi,
+  stripExactMeldworkPromptEcho,
   structuredCliError,
 } = require('./cli-runtime-events.cjs')
-const { runAcpAgent } = require('./cli-acp-runner.cjs')
+const {
+  registerAcpShutdownBarrier,
+  runAcpAgent,
+  shutdownAcpSessionRuntime,
+} = require('./cli-acp-runner.cjs')
+const { withOpenClawGateway } = require('./cli-openclaw-gateway.cjs')
+const { createOutputRepetitionGuard } = require('./cli-output-repetition.cjs')
 const { imageAttachmentLimit, invocation } = require('./cli-invocations.cjs')
+const {
+  connectorLimitedRuntimeEvent,
+  resolveConnectorEventProfile,
+} = require('./cli-event-profiles.cjs')
 const {
   normalizeExternalRunRef,
   requireTerminalAgentResult,
@@ -48,13 +48,24 @@ const {
   failedAgentProcessError,
 } = require('./cli-process-support.cjs')
 const { createLegacyOutboundPayload } = require('../../collaboration/outbound-payload.cjs')
+const { authFailureCertainty } = require('../../runs/failure-signals.cjs')
 
 const MAX_PROGRESS_STEPS = 8
-const MAX_HERMES_PROGRESS_PENDING_CHARS = 64 * 1024
 const MAX_STDOUT_CAPTURE_BYTES = 10 * 1024 * 1024
 const MAX_STDERR_CAPTURE_BYTES = 1024 * 1024
 const OUTPUT_TRUNCATION_MARKER = Buffer.from('\n[output truncated]\n')
 
+const BROKEN_INPUT_GRACE_MS = 5000
+
+// A step that ends because the model asked for tools is followed by more
+// steps (the tools run, then the model continues); only the last step's finish
+// ends the run. Ending the process after the first one cut every tool-using
+// MiMo or OpenCode turn short.
+function stepFinishContinues(event) {
+  const reason = String(event?.part?.reason || event?.reason || '').toLowerCase()
+  return /^tool[-_ ]?(calls?|use)$/.test(reason)
+}
+
 function createBoundedOutputCapture(maxBytes) {
   const headLimit = Math.floor(maxBytes / 2)
   const tailLimit = maxBytes - headLimit
@@ -112,77 +123,6 @@ function createBoundedOutputCapture(maxBytes) {
 }
 
 
-function normalizeOutput(kind, stdout, sessionRef = '') {
-  if (kind === 'codex') {
-    const parsed = parseCodexOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'openclaw') {
-    return {
-      text: normalizeOpenClawOutput(stdout),
-      sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'hermes') {
-    return {
-      text: stripAnsi(stdout).trim(),
-      sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'workbuddy') {
-    const parsed = parseWorkBuddyOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'kimi') {
-    const parsed = parseKimiOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'mimo') {
-    return { ...parseMimoOutput(stdout), ...classifyCliOutcome(kind, stdout) }
-  }
-  if (kind === 'gemini') {
-    const parsed = parseGeminiOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'opencode') {
-    const parsed = parseOpenCodeOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (['claude', 'qwen'].includes(kind)) {
-    const parsed = parseClaudeQwenOutput(stdout)
-    return {
-      text: parsed.text,
-      sessionRef: parsed.sessionRef || sessionRef,
-      ...classifyCliOutcome(kind, stdout),
-    }
-  }
-  if (kind === 'opencodereview') return parseOpenCodeReviewOutput(stdout)
-  return { text: String(stdout || '').trim(), sessionRef, outcome: 'partial' }
-}
-
-
 async function runAgent(agent, prompt, workdir, options = {}) {
   if (options.signal?.aborted) throw agentExecutionError('LOCAL_AGENT_EXECUTION_STOPPED')
   const noteActivity = () => {
@@ -191,27 +131,59 @@ async function runAgent(agent, prompt, workdir, options = {}) {
   const platform = options.platform || process.platform
   const spawnFn = options.spawnFn || spawn
   let sessionRef = String(options.sessionRef || '')
+  const failureSessionRef = String(options.failureSessionRef || sessionRef)
   const hermesAcpAvailable = typeof options.hermesAcpAvailable === 'boolean'
     ? options.hermesAcpAvailable
     : agent.acpAvailable
   const spec = invocation(agent.kind, agent.executable, workdir, sessionRef, {
+    platform,
     sandbox: options.sandbox,
-    provider: options.provider,
     attachments: options.attachments,
     hermesAcpAvailable,
+    hermesStreamJsonAvailable: agent.streamJsonAvailable,
+    invocationTransport: options.invocationTransport,
     sessionTransport: options.sessionTransport,
+    maxTurns: options.maxTurns,
+    model: agent.kind === 'workbuddy' ? options.env?.CODEBUDDY_MODEL : undefined,
   })
+  const profile = resolveConnectorEventProfile(agent.kind, {
+    transport: spec.eventTransport,
+  })
+  if (!profile) throw agentExecutionError('LOCAL_AGENT_PROTOCOL_UNSUPPORTED')
   if (agent.kind === 'hermes' && !spec.acpMode && options.sessionTransport === 'acp') {
     sessionRef = ''
   }
-  if (spec.acpMode) {
+  if (spec.eventTransport === 'acp') {
     try {
-      return await runAcpAgent(agent, prompt, workdir, options, spec)
+      const executeAcp = runtimeOptions => runAcpAgent(
+        agent, prompt, workdir, runtimeOptions, spec, profile,
+      )
+      if (!spec.openClawGateway) return await executeAcp(options)
+      const shutdownBarrier = registerAcpShutdownBarrier(options.signal)
+      try {
+        if (!shutdownBarrier.isCurrent()) {
+          throw agentExecutionError('LOCAL_AGENT_EXECUTION_STOPPED')
+        }
+        return await withOpenClawGateway({
+          ...options,
+          executable: agent.executable,
+          signal: shutdownBarrier.signal,
+          workdir,
+        }, gatewayOptions => executeAcp({
+          ...options,
+          ...gatewayOptions,
+          acpShutdownGeneration: shutdownBarrier.shutdownGeneration,
+          signal: shutdownBarrier.signal,
+        }))
+      } finally {
+        shutdownBarrier.complete()
+      }
     } catch (error) {
-      if (agent.kind !== 'hermes' || error?.acpFallbackAllowed !== true
+      if (!spec.fallbackTransport || error?.acpFallbackAllowed !== true
           || options.signal?.aborted) throw error
       let fallbackPrompt = prompt
-      if (sessionRef && typeof options.onSessionInvalidated === 'function') {
+      if (spec.fallbackSessionPolicy === 'invalidate' && sessionRef
+          && typeof options.onSessionInvalidated === 'function') {
         const recovery = await options.onSessionInvalidated({
           kind: agent.kind,
           sessionRef,
@@ -221,18 +193,21 @@ async function runAgent(agent, prompt, workdir, options = {}) {
         else if (typeof recovery?.prompt === 'string') fallbackPrompt = recovery.prompt
       }
       try {
-        options.onEvent?.({
-          id: 'hermes-acp-fallback',
+        const pending = options.onEvent?.({
+          id: `${agent.kind}-acp-fallback`,
           type: 'warning',
           status: 'waiting',
           title: 'connector_fallback',
         })
+        if (pending && typeof pending.catch === 'function') pending.catch(() => {})
       } catch { /* runtime events are best-effort */ }
+      const fallbackRuntimeOptions = error?.openClawRuntimeOptions || {}
       return runAgent(agent, fallbackPrompt, workdir, {
         ...options,
-        sessionRef: '',
-        sessionTransport: 'legacy',
-        hermesAcpAvailable: false,
+        ...fallbackRuntimeOptions,
+        sessionRef: spec.fallbackSessionPolicy === 'preserve' ? sessionRef : '',
+        failureSessionRef,
+        invocationTransport: spec.fallbackTransport,
         onSessionInvalidated: undefined,
       })
     }
@@ -253,30 +228,17 @@ async function runAgent(agent, prompt, workdir, options = {}) {
     }))
   }
   const childEnv = childEnvironment(agent, workdir, options, platform)
+  const repetitionGuard = ['opencode', 'mimo', 'hermes'].includes(agent.kind)
+    ? createOutputRepetitionGuard() : null
   const runtimeEvents = createRuntimeEventEmitter({ ...options, onActivity: noteActivity }, childEnv)
-  if (['hermes', 'openclaw', 'workbuddy', 'opencodereview'].includes(agent.kind)) {
-    runtimeEvents.emit({
-      id: `${agent.kind}-connector`,
-      type: 'warning',
-      status: 'waiting',
-      title: 'connector_limited',
-    })
-  }
-  let hermesMessageWatermark = null
-  if (agent.kind === 'hermes') {
-    const watermarkFn = options.hermesMessageWatermarkFn || readHermesMessageWatermark
-    try {
-      const watermark = watermarkFn({
-        home: options.home,
-        existsFn: options.hermesStateExistsFn,
-        queryFn: options.hermesStateQueryFn,
-      })
-      if (Number.isSafeInteger(watermark) && watermark >= 0) {
-        hermesMessageWatermark = watermark
-      }
-    } catch { /* a missing pre-run watermark makes final lookup ineligible */ }
-  }
+  const capabilityWarning = connectorLimitedRuntimeEvent(agent.kind, profile)
+  if (capabilityWarning) runtimeEvents.emit(capabilityWarning)
+  const profileRunContext = profile.createRunContext(options)
   return await new Promise((resolve, reject) => {
+    const rejectTerminal = (error, status = 'failed') => {
+      runtimeEvents.finalize({ status })
+      reject(error)
+    }
     let child
     try {
       child = spawnFn(prepared.command, prepared.args, {
@@ -287,7 +249,7 @@ async function runAgent(agent, prompt, workdir, options = {}) {
         windowsHide: true,
       })
     } catch (error) {
-      reject(agentExecutionError(
+      rejectTerminal(agentExecutionError(
         'LOCAL_AGENT_SPAWN_FAILED',
         redactChildSecrets(error?.message || error, childEnv),
       ))
@@ -295,12 +257,17 @@ async function runAgent(agent, prompt, workdir, options = {}) {
     }
     const stdout = createBoundedOutputCapture(MAX_STDOUT_CAPTURE_BYTES)
     const stderr = createBoundedOutputCapture(MAX_STDERR_CAPTURE_BYTES)
-    const structuredOutput = createStructuredOutputAccumulator(agent.kind, sessionRef)
+    const structuredOutput = profile.createFinalOutputAccumulator(sessionRef)
     let settled = false
     let stopRequested = false
+    let timeoutRequested = false
+    let inputError = null
+    let brokenInputTimer = null
     let timeout
     let forceKillTimeout
     let forceSettleTimeout
+    let terminalKillTimer
+    let terminalForceKillTimer
     const progress = []
     const progressIndexes = new Map()
     let anonymousProgressId = 0
@@ -323,36 +290,24 @@ async function runAgent(agent, prompt, workdir, options = {}) {
       }
       try { options.onProgress?.(event) } catch { /* progress is best-effort */ }
     }
-    const hermesProgressBuffers = { stdout: '', stderr: '' }
-    const hermesProgressDecoders = { stdout: new TextDecoder(), stderr: new TextDecoder() }
-    const emitHermesProgress = (source, chunk, flush = false) => {
-      if (agent.kind !== 'hermes') return
-      const decoder = hermesProgressDecoders[source]
-      hermesProgressBuffers[source] += decoder.decode(chunk || undefined, { stream: !flush })
-      const lines = hermesProgressBuffers[source].split(/\r?\n/)
-      hermesProgressBuffers[source] = flush ? '' : (lines.pop() || '')
-      if (hermesProgressBuffers[source].length > MAX_HERMES_PROGRESS_PENDING_CHARS) {
-        hermesProgressBuffers[source] = ''
-      }
-      for (const line of lines) {
-        if (!/^┊\s*review diff$/i.test(stripAnsi(line).trim())) continue
-        emitProgress({ title: 'write_file', status: 'completed' })
-      }
-    }
-    const claudeQwenRuntimeState = createClaudeQwenRuntimeState()
-    const runtimeStreamParser = structuredOutput?.format === 'jsonl'
-      ? createJsonLineParser((event) => {
-          structuredOutput.ingest(event)
-          if (agent.kind === 'codex') {
-            const progressEvent = codexProgressEvent(event)
-            if (progressEvent) emitProgress(progressEvent)
+    const runtimeState = profile.createState()
+    const runtimeStreamParser = profile.source === 'stdout'
+      && ['jsonl', 'jsonrpc-jsonl'].includes(profile.framing)
+      && typeof profile.createDecoder === 'function'
+      ? profile.createDecoder((event) => {
+          structuredOutput.ingest?.(event)
+          observeTerminalEvent(event)
+          const progressEvent = profile.mapProgress(event)
+          if (progressEvent) emitProgress(progressEvent)
+          for (const runtimeEvent of profile.mapEvent(event, runtimeState)) {
+            if (stopRequested || settled) return
+            if (repetitionGuard?.(runtimeEvent)) {
+              inputError = agentExecutionError('LOCAL_AGENT_REPEATED_OUTPUT')
+              abort()
+              return
+            }
+            runtimeEvents.emit(runtimeEvent)
           }
-          const events = agent.kind === 'codex'
-            ? codexRuntimeEvents(event)
-            : ['claude', 'qwen'].includes(agent.kind)
-                ? claudeQwenRuntimeEvents(event, claudeQwenRuntimeState)
-                : jsonCliRuntimeEvents(agent.kind, event)
-          for (const runtimeEvent of events) runtimeEvents.emit(runtimeEvent)
         })
       : null
     const finish = (callback) => {
@@ -361,6 +316,9 @@ async function runAgent(agent, prompt, workdir, options = {}) {
       clearTimeout(timeout)
       clearTimeout(forceKillTimeout)
       clearTimeout(forceSettleTimeout)
+      clearTimeout(terminalKillTimer)
+      clearTimeout(terminalForceKillTimer)
+      clearTimeout(brokenInputTimer)
       options.signal?.removeEventListener('abort', abort)
       callback()
     }
@@ -375,9 +333,35 @@ async function runAgent(agent, prompt, workdir, options = {}) {
         child.kill(signal)
       } catch { /* the process has already exited */ }
     }
+    let terminalObserved = false
+    const observeTerminalEvent = (event) => {
+      if (terminalObserved || !event || typeof event !== 'object') return
+      const terminal = (
+        (['workbuddy', 'claude', 'qwen'].includes(agent.kind) && event.type === 'result')
+        || (agent.kind === 'hermes' && spec.eventTransport === 'stream-json' && event.type === 'result')
+        || (agent.kind === 'pi' && (event.type === 'agent_settled'
+          || (event.type === 'agent_end'
+            && !Object.hasOwn(event, 'willRetry') && !Object.hasOwn(event, 'willContinue'))))
+        || (agent.kind === 'codex' && event.type === 'turn.completed')
+        || (['mimo', 'opencode'].includes(agent.kind) && event.type === 'step_finish'
+          && !stepFinishContinues(event))
+        || (agent.kind === 'gemini' && event.type === 'result')
+        || (agent.kind === 'kimi' && event.type === 'session.resume_hint')
+      )
+      if (!terminal) return
+      terminalObserved = true
+      terminalKillTimer = setTimeout(() => {
+        if (settled) return
+        signalProcessTree('SIGTERM')
+        terminalForceKillTimer = setTimeout(() => {
+          if (!settled) signalProcessTree('SIGKILL')
+        }, 1500)
+      }, 250)
+    }
     const abort = () => {
       if (settled || stopRequested) return
       stopRequested = true
+      const terminalError = inputError || new Error('LOCAL_AGENT_EXECUTION_STOPPED')
       if (platform === 'win32' && child.pid) {
         const killer = spawnFn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], {
           stdio: 'ignore', windowsHide: true,
@@ -388,7 +372,10 @@ async function runAgent(agent, prompt, workdir, options = {}) {
           child.stdin.destroy()
           child.stdout.destroy()
           child.stderr.destroy()
-          reject(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+          rejectTerminal(
+            terminalError,
+            inputError ? 'failed' : (timeoutRequested ? 'timeout' : 'stopped'),
+          )
         }), KILL_SETTLE_MS)
         return
       }
@@ -400,65 +387,107 @@ async function runAgent(agent, prompt, workdir, options = {}) {
           child.stdin.destroy()
           child.stdout.destroy()
           child.stderr.destroy()
-          reject(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+          rejectTerminal(
+            terminalError,
+            inputError ? 'failed' : (timeoutRequested ? 'timeout' : 'stopped'),
+          )
         }), KILL_SETTLE_MS)
       }, TERMINATE_GRACE_MS)
     }
-    timeout = setTimeout(abort, 2 * 60 * 60 * 1000)
+    timeout = setTimeout(() => {
+      timeoutRequested = true
+      abort()
+    }, 2 * 60 * 60 * 1000)
     if (options.signal?.aborted) abort()
     else options.signal?.addEventListener('abort', abort, { once: true })
     child.stdout.on('data', (chunk) => {
       stdout.push(chunk)
       noteActivity()
-      if (structuredOutput?.format === 'document') structuredOutput.write(chunk)
+      structuredOutput.capture?.(chunk)
+      if (['document', 'text'].includes(structuredOutput?.format)) structuredOutput.write?.(chunk)
       runtimeStreamParser?.write(chunk)
-      emitHermesProgress('stdout', chunk)
     })
     child.stderr.on('data', (chunk) => {
       stderr.push(chunk)
       noteActivity()
-      emitHermesProgress('stderr', chunk)
     })
-    child.on('error', error => finish(() => reject(
-      stopRequested
+    child.stdin.on('error', (error) => {
+      if (settled || inputError) return
+      const sendFailure = () => agentExecutionError(
+        'LOCAL_AGENT_SEND_FAILED',
+        redactChildSecrets(error?.message || error, childEnv),
+      )
+      // A closed pipe usually means the CLI exited before it read the whole
+      // prompt (expired sign-in, rejected flag). Its own output says why, so
+      // let the process finish and report that. Only a process that stays
+      // alive without reading its input is a send failure.
+      if (['EPIPE', 'ERR_STREAM_DESTROYED', 'ECONNRESET'].includes(error?.code)) {
+        brokenInputTimer ||= setTimeout(() => {
+          if (settled || inputError) return
+          inputError = sendFailure()
+          abort()
+        }, BROKEN_INPUT_GRACE_MS)
+        return
+      }
+      inputError = sendFailure()
+      abort()
+    })
+    child.on('error', error => finish(() => rejectTerminal(
+      inputError || (stopRequested
         ? agentExecutionError('LOCAL_AGENT_EXECUTION_STOPPED')
         : agentExecutionError(
             'LOCAL_AGENT_SPAWN_FAILED',
             redactChildSecrets(error?.message || error, childEnv),
-          ),
+          )),
+      stopRequested ? (inputError ? 'failed' : (timeoutRequested ? 'timeout' : 'stopped')) : 'failed',
     )))
     child.on('close', (code, signal) => finish(() => {
       void (async () => {
-        emitHermesProgress('stdout', null, true)
-        emitHermesProgress('stderr', null, true)
         runtimeStreamParser?.end()
-        const structuredResult = structuredOutput?.end()
         if (stopRequested || options.signal?.aborted) {
-          reject(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
-          return
-        }
-        if (code !== 0) {
-          const rawStdout = stdout.text()
-          const rawStderr = stderr.text().trim()
-          const structuredDetail = structuredCliError(rawStdout)
-          const detail = redactChildSecrets(
-            [rawStderr, structuredDetail].filter(Boolean).join('\n'),
-            childEnv,
+          rejectTerminal(
+            inputError || new Error('LOCAL_AGENT_EXECUTION_STOPPED'),
+            inputError ? 'failed' : (timeoutRequested ? 'timeout' : 'stopped'),
           )
-          reject(failedAgentProcessError(detail, { sessionRef }))
           return
         }
         const rawStderr = stderr.text()
-        const nextSessionRef = agent.kind === 'hermes'
-          ? hermesSessionRef(rawStderr) || sessionRef
-          : sessionRef
-        const result = structuredResult || normalizeOutput(
-          agent.kind, stdout.text(), nextSessionRef,
-        )
+        const nextSessionRef = profile.resolveSessionRef({
+          stderr: rawStderr,
+          sessionRef,
+          runContext: profileRunContext,
+        })
+        let result = structuredOutput.end({
+          sessionRef: nextSessionRef,
+          prompt,
+        })
+        const rawStdout = stdout.text()
+        const structuredDetail = structuredCliError(rawStdout)
+        if (!String(result?.text || '').trim() && authFailureCertainty(rawStderr) === 'definitive') {
+          rejectTerminal(failedAgentProcessError(redactChildSecrets(rawStderr, childEnv), {
+            sessionRef: failureSessionRef, kind: agent.kind, model: options.env?.CODEBUDDY_MODEL,
+          }))
+          return
+        }
+        const usableNonZeroResult = code !== 0
+          && result
+          && typeof result.text === 'string'
+          && result.text.trim()
+          && ['completed', 'partial'].includes(result.outcome)
+        if (code !== 0 && !usableNonZeroResult) {
+          const detail = redactChildSecrets(
+            [result?.error, rawStderr, structuredDetail].filter(Boolean).join('\n'),
+            childEnv,
+          )
+          rejectTerminal(failedAgentProcessError(detail, {
+            sessionRef: failureSessionRef, kind: agent.kind, model: options.env?.CODEBUDDY_MODEL,
+          }))
+          return
+        }
         if (result.error) {
-          reject(failedAgentProcessError(
+          rejectTerminal(failedAgentProcessError(
             redactChildSecrets(result.error, childEnv),
-            { sessionRef },
+            { sessionRef: failureSessionRef, kind: agent.kind, model: options.env?.CODEBUDDY_MODEL },
           ))
           return
         }
@@ -466,24 +495,15 @@ async function runAgent(agent, prompt, workdir, options = {}) {
         const publicSessionRef = redactedSessionRef.includes('[redacted]')
           ? ''
           : redactedSessionRef
-        if (agent.kind === 'hermes') {
-          if (publicSessionRef && typeof options.onSessionRef === 'function') {
-            await options.onSessionRef(publicSessionRef, { transport: 'legacy' })
-          }
-          const finalResponseFn = options.hermesFinalResponseFn || readHermesFinalResponse
-          let finalResponse = ''
-          if (publicSessionRef && Number.isSafeInteger(hermesMessageWatermark)) {
-            try {
-              finalResponse = finalResponseFn(publicSessionRef, {
-                home: options.home,
-                afterMessageId: hermesMessageWatermark,
-                existsFn: options.hermesStateExistsFn,
-                queryFn: options.hermesStateQueryFn,
-              })
-            } catch { /* fall back to the official --quiet stdout */ }
-          }
-          const storedResponse = typeof finalResponse === 'string' ? finalResponse.trim() : ''
-          if (storedResponse) result.text = storedResponse
+        result = await profile.finalizeResult({
+          result: { ...result, sessionRef: publicSessionRef },
+          sessionRef: publicSessionRef,
+          runContext: profileRunContext,
+          options,
+        })
+        result = {
+          ...result,
+          text: stripExactMeldworkPromptEcho(result.text, prompt),
         }
         if (progress.length) result.progress = progress
         const redactedText = redactChildSecrets(result.text, childEnv)
@@ -499,11 +519,11 @@ async function runAgent(agent, prompt, workdir, options = {}) {
               : {}),
           })
         } catch (error) {
-          reject(error)
+          rejectTerminal(error)
           return
         }
         if (!output.text) {
-          reject(agentExecutionError('LOCAL_AGENT_EMPTY_RESPONSE'))
+          rejectTerminal(agentExecutionError('LOCAL_AGENT_EMPTY_RESPONSE'))
           return
         }
         const externalRunRef = normalizeExternalRunRef(
@@ -511,9 +531,9 @@ async function runAgent(agent, prompt, workdir, options = {}) {
         )
         if (externalRunRef) output.externalRunRef = externalRunRef
         if (result.progress?.length) output.progress = result.progress
-        runtimeEvents.emitFinalAnswer(redactedText)
+        runtimeEvents.finalize({ text: redactedText, status: output.outcome })
         resolve(output)
-      })().catch(error => reject(error))
+      })().catch(error => rejectTerminal(error))
     }))
     if (spec.stdin) child.stdin.end(stdin)
     else child.stdin.end()
@@ -525,13 +545,13 @@ module.exports = {
   detectAgents,
   imageAttachmentLimit,
   invocation,
-  normalizeOutput,
   parseCodexOutput,
   parseGeminiOutput,
   parseKimiOutput,
   parseMimoOutput,
   parseOpenCodeOutput,
   parseOpenCodeReviewOutput,
+  parsePiOutput,
   parseWorkBuddyOutput,
   prepareCommand,
   readHermesFinalResponse,
@@ -540,4 +560,5 @@ module.exports = {
   runAgent,
   runtimeCommandSummary,
   searchPath,
+  shutdownAcpSessionRuntime,
 }

desktop/src/agents/cli/cli-discovery.cjs

@@ -3,6 +3,7 @@ const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
 const { promisify } = require('node:util')
+const { networkEnvironment } = require('./cli-network-environment.cjs')
 const {
   assessAgentVersion,
   capabilityProbes,
@@ -15,6 +16,8 @@ const AGENT_PROFILES = {
   hermes: { label: 'Hermes', commands: ['hermes'] },
   openclaw: { label: 'OpenClaw', commands: ['openclaw'] },
   workbuddy: { label: 'WorkBuddy', commands: ['codebuddy'] },
+  zcode: { label: 'Zcode', commands: ['zcode'] },
+  pi: { label: 'Pi Agent', commands: ['pi', 'pi-agent', 'piagent'] },
   kimi: { label: 'Kimi', commands: ['kimi'] },
   mimo: { label: 'MiMo', commands: ['mimo'] },
   claude: { label: 'Claude', commands: ['claude'] },
@@ -25,6 +28,8 @@ const AGENT_PROFILES = {
 }
 const ALLOWED_KINDS = Object.keys(AGENT_PROFILES)
 const DEFAULT_WINDOWS_PATHEXT = ['.COM', '.EXE', '.BAT', '.CMD']
+const CAPABILITY_CACHE_TTL_MS = 5 * 60 * 1000
+const capabilityCache = new Map()
 const SYSTEM_CHILD_ENV_KEYS = Object.freeze([
   'HOME', 'USER', 'LOGNAME', 'SHELL',
   'TMPDIR', 'TMP', 'TEMP',
@@ -37,7 +42,7 @@ const SYSTEM_CHILD_ENV_KEYS = Object.freeze([
   'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA',
   'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432',
   'OS', 'PROCESSOR_ARCHITECTURE', 'PROCESSOR_IDENTIFIER', 'NUMBER_OF_PROCESSORS',
-  'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+  'CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'PI_CODING_AGENT_DIR',
 ])
 
 function envValue(env, name) {
@@ -46,7 +51,7 @@ function envValue(env, name) {
 }
 
 function systemChildEnvironment(sourceEnv = process.env, platform = process.platform) {
-  const env = {}
+  const env = networkEnvironment(sourceEnv, platform)
   for (const name of SYSTEM_CHILD_ENV_KEYS) {
     const value = envValue(sourceEnv, name)
     if (typeof value === 'string' && value) env[name] = value
@@ -205,6 +210,23 @@ function agentCommands(kind, options = {}) {
   return commands
 }
 
+// The WorkBuddy app ships its CLI with only the lite bundle, which the
+// launcher loads solely when this variable is set. Without it every headless
+// call, `--help` included, exits with MODULE_NOT_FOUND. Installs that carry a
+// regular bundle launch exactly as before.
+function launchEnvironment(kind, executable, options = {}) {
+  if (kind !== 'workbuddy' || !executable) return {}
+  const { pathApi } = runtimeOptions(options)
+  try {
+    const dist = pathApi.join(pathApi.dirname(fs.realpathSync(executable)), '..', 'dist')
+    const shipped = name => fs.existsSync(pathApi.join(dist, name))
+    if (shipped('codebuddy-lite-wb.mjs') && !shipped('codebuddy-headless.js') && !shipped('codebuddy.js')) {
+      return { CODEBUDDY_FORCE_LITE_WB_BUNDLE: '1' }
+    }
+  } catch { /* an unreadable layout keeps the default launch */ }
+  return {}
+}
+
 function executableExtensions(options = {}) {
   const { platform, env } = runtimeOptions(options)
   if (platform !== 'win32') return ['']
@@ -329,31 +351,57 @@ async function probeAgentCapabilities(kind, executable, options = {}) {
   const runtime = runtimeOptions(options)
   const { env, execFileFn, platform } = runtime
   const prepareCommandFn = options.prepareCommandFn || prepareCommand
-  const childEnv = options.childEnv || {
-    ...systemChildEnvironment(env, platform),
-    PATH: searchPath(options),
+  const childEnv = {
+    ...(options.childEnv || {
+      ...systemChildEnvironment(env, platform),
+      PATH: searchPath(options),
+    }),
+    ...launchEnvironment(kind, executable, options),
   }
+  let identity = ''
+  try {
+    const stat = (options.statFn || fs.statSync)(executable)
+    identity = JSON.stringify([
+      kind, executable, options.version || '', stat.dev, stat.ino,
+      stat.size, stat.mtimeMs, stat.ctimeMs,
+    ])
+  } catch { /* caching requires a verifiable executable identity */ }
+  const cacheKey = `${kind}:${executable}`
+  const prior = capabilityCache.get(cacheKey)
+  const recentCompatible = identity && prior?.identity === identity
+    && Date.now() - prior.checkedAt < CAPABILITY_CACHE_TTL_MS
   const results = await Promise.all(capabilityProbes(kind).map(async (probe) => {
-    try {
-      const command = prepareCommandFn(executable, probe.args, options)
-      const result = await execFileFn(command.command, command.args, {
-        timeout: 8000,
-        windowsHide: true,
-        env: childEnv,
-      })
-      return {
-        probe,
-        output: `${result.stdout || ''}\n${result.stderr || ''}`,
-      }
-    } catch {
-      return {
-        probe,
-        error: true,
+    for (const timeout of probe.timeout ? [probe.timeout] : [8000, 16000]) {
+      try {
+        const command = prepareCommandFn(executable, probe.args, options)
+        const result = await execFileFn(command.command, command.args, {
+          timeout,
+          windowsHide: true,
+          env: childEnv,
+        })
+        return { probe, output: `${result.stdout || ''}\n${result.stderr || ''}` }
+      } catch (error) {
+        const timedOut = error?.killed === true || error?.code === 'ETIMEDOUT'
+        if (timedOut && timeout === 8000) continue
+        return { probe, error: true, timedOut }
       }
     }
   }))
+  const failed = results.find(result => !result.timedOut && (result.error
+    || result.probe.requiredText.some(value => !result.output.includes(value))
+    || (result.probe.validateOutput && !result.probe.validateOutput(result.output))))
+  if (failed) capabilityCache.delete(cacheKey)
   for (const result of results) {
     const { probe } = result
+    if (result.timedOut && !failed) {
+      if (recentCompatible) continue
+      return {
+        compatibilityState: 'unknown',
+        incompatibilityReason: 'LOCAL_AGENT_CAPABILITY_PROBE_TIMEOUT',
+        incompatibilityProbe: probe.id,
+      }
+    }
+    if (result.timedOut) continue
     if (result.error) {
       return {
         compatibilityState: 'incompatible',
@@ -371,10 +419,15 @@ async function probeAgentCapabilities(kind, executable, options = {}) {
       }
     }
   }
+  if (identity && !results.some(result => result.timedOut)) {
+    capabilityCache.set(cacheKey, { identity, checkedAt: Date.now() })
+  }
   return {
     compatibilityState: 'compatible',
     incompatibilityReason: '',
     incompatibilityProbe: '',
+    ...(kind === 'hermes' && results.some(result => result.output?.includes('--format')
+      && result.output.includes('stream-json')) ? { streamJsonAvailable: true } : {}),
   }
 }
 
@@ -401,18 +454,17 @@ async function inspectAgentCandidate(kind, executable, options, childEnv) {
         version: identified?.line || '',
         versionIdentified: Boolean(identified),
       }
-    } catch { /* a broken shim is not a usable CLI */ }
+    } catch { /* capability probes can still establish whether this installation works */ }
     return { succeeded: false, version: '', versionIdentified: false }
   })()
 
-  const { succeeded: versionCommandSucceeded, version } = await versionTask
-  if (!versionCommandSucceeded) return null
+  const { version } = await versionTask
   const versionCompatibility = assessAgentVersion(kind, version)
   const capabilityTask = Promise.resolve().then(async () => {
     const result = await (options.probeAgentCapabilitiesFn || probeAgentCapabilities)(
       kind,
       executable,
-      { ...options, childEnv },
+      { ...options, childEnv, version },
     )
     return result && typeof result === 'object' ? result : incompatibleCapabilities
   }).catch(() => incompatibleCapabilities)
@@ -432,7 +484,7 @@ async function inspectAgentCandidate(kind, executable, options, childEnv) {
       })()
     : Promise.resolve(undefined)
   const [capabilityCompatibility, acpAvailable] = await Promise.all([capabilityTask, acpTask])
-  const compatibility = capabilityCompatibility.compatibilityState === 'incompatible'
+  const compatibility = capabilityCompatibility.compatibilityState !== 'compatible'
     ? { ...versionCompatibility, ...capabilityCompatibility }
     : {
         ...versionCompatibility,
@@ -446,7 +498,10 @@ async function inspectAgentCandidate(kind, executable, options, childEnv) {
     executable,
     version,
     ...compatibility,
-    ...(kind === 'hermes' ? { acpAvailable } : {}),
+    ...(kind === 'hermes' ? {
+      acpAvailable,
+      ...(capabilityCompatibility.streamJsonAvailable ? { streamJsonAvailable: true } : {}),
+    } : {}),
   }
 }
 
@@ -484,6 +539,7 @@ module.exports = {
   AGENT_PROFILES,
   ALLOWED_KINDS,
   detectAgents,
+  launchEnvironment,
   prepareCommand,
   probeAgentCapabilities,
   resolveExecutable,

desktop/src/agents/cli/cli-event-profiles.cjs

@@ -0,0 +1,590 @@
+const { StringDecoder } = require('node:string_decoder')
+const { createHash } = require('node:crypto')
+const {
+  classifyCliOutcome,
+  codexProgressEvent,
+  createJsonLineParser,
+  createStructuredOutputAccumulator,
+  hermesSessionRef,
+  normalizeOpenClawOutput,
+  parseClaudeQwenOutput,
+  parseCodexOutput,
+  parseGeminiOutput,
+  parseKimiOutput,
+  parseMimoOutput,
+  parseOpenCodeOutput,
+  parseOpenCodeReviewOutput,
+  parsePiOutput,
+  parseWorkBuddyOutput,
+  readHermesFinalResponse,
+  readHermesMessageWatermark,
+  stripAnsi,
+} = require('./cli-output-parsers.cjs')
+const {
+  acpRuntimeEvents,
+  claudeQwenRuntimeEvents,
+  codexRuntimeEvents,
+  createAcpRuntimeState,
+  createClaudeQwenRuntimeState,
+  createGeminiRuntimeState,
+  createPiRuntimeState,
+  finalOnlyRuntimeEvents,
+  geminiStreamJsonRuntimeEvents,
+  kimiStreamJsonRuntimeEvents,
+  mimoJsonRuntimeEvents,
+  openCodeJsonRuntimeEvents,
+  piJsonRuntimeEvents,
+} = require('./cli-runtime-event-mappers.cjs')
+
+function createStatelessRuntimeState() {
+  return {}
+}
+
+function publicLifecycleId(state, value) {
+  const raw = String(value || '')
+  if (!raw) return ''
+  if (/^[A-Za-z0-9._:-]{1,100}$/.test(raw)) return raw
+  const ids = state?.publicLifecycleIds
+  if (ids?.has(raw)) return ids.get(raw)
+  const publicId = `lifecycle:${createHash('sha256').update(raw).digest('hex')}`
+  ids?.set(raw, publicId)
+  return publicId
+}
+
+function noProgressEvent() {
+  return null
+}
+
+function createDefaultRunContext() {
+  return null
+}
+
+function resolveDefaultSessionRef(input = {}) {
+  return String(input.sessionRef || '')
+}
+
+async function finalizeDefaultResult(input = {}) {
+  return input.result
+}
+
+const MAX_FINAL_TEXT_CHARS = 1024 * 1024
+
+function appendFinalText(state, value) {
+  const remaining = MAX_FINAL_TEXT_CHARS - state.text.length
+  if (remaining > 0) state.text += String(value || '').slice(0, remaining)
+}
+
+const FINAL_OUTPUT_PARSERS = Object.freeze({
+  codex: parseCodexOutput,
+  openclaw: stdout => ({ text: normalizeOpenClawOutput(stdout), sessionRef: '' }),
+  workbuddy: parseWorkBuddyOutput,
+  pi: parsePiOutput,
+  kimi: parseKimiOutput,
+  mimo: parseMimoOutput,
+  claude: parseClaudeQwenOutput,
+  gemini: parseGeminiOutput,
+  opencode: parseOpenCodeOutput,
+  qwen: parseClaudeQwenOutput,
+  opencodereview: parseOpenCodeReviewOutput,
+})
+
+function createFinalOutputAccumulator(kind) {
+  return (sessionRef = '') => {
+    const structured = createStructuredOutputAccumulator(kind, sessionRef)
+    const decoder = new StringDecoder('utf8')
+    const raw = { text: '' }
+    return {
+      ...structured,
+      capture(chunk) {
+        appendFinalText(raw, decoder.write(chunk))
+      },
+      end(context = {}) {
+        appendFinalText(raw, decoder.end())
+        const classification = classifyCliOutcome(kind, raw.text)
+        const result = structured.end(context)
+        if (result) return result
+        const parsed = FINAL_OUTPUT_PARSERS[kind](raw.text)
+        const text = String(parsed?.text || '').trim()
+        return {
+          ...parsed,
+          text,
+          sessionRef: String(parsed?.sessionRef || context.sessionRef || sessionRef || ''),
+          outcome: parsed?.outcome || context.outcome || classification.outcome
+            || (text ? 'partial' : 'failed'),
+          ...((context.failure || classification.failure) && !parsed?.failure
+            ? { failure: context.failure || classification.failure }
+            : {}),
+          ...((context.diagnostic || classification.diagnostic) && !parsed?.diagnostic
+            ? { diagnostic: context.diagnostic || classification.diagnostic }
+            : {}),
+        }
+      },
+    }
+  }
+}
+
+function protocolStopOutcome(stopReason, fallback, text) {
+  if (['accepted', 'running', 'waiting_input', 'waiting_permission', 'partial', 'completed', 'failed', 'cancelled']
+    .includes(fallback)) return fallback
+  if (['end_turn', 'stop', 'success'].includes(String(stopReason || '').toLowerCase())) {
+    return 'completed'
+  }
+  if (['error', 'failed', 'refusal'].includes(String(stopReason || '').toLowerCase())) return 'failed'
+  if (['cancelled', 'canceled', 'aborted'].includes(String(stopReason || '').toLowerCase())) {
+    return 'cancelled'
+  }
+  return text ? 'partial' : 'failed'
+}
+
+function createAcpFinalOutputAccumulator(sessionRef = '') {
+  const state = { sessionRef: String(sessionRef || ''), stopReason: '', text: '' }
+  return {
+    format: 'protocol-record',
+    ingest(record) {
+      const update = record?.params?.update || record?.update || record
+      const nextSessionRef = record?.params?.sessionId || record?.sessionId || update?.sessionId
+      if (typeof nextSessionRef === 'string' && nextSessionRef) state.sessionRef = nextSessionRef
+      if (typeof update?.stopReason === 'string') state.stopReason = update.stopReason
+      if (update?.sessionUpdate === 'agent_message_chunk' && update.content?.type === 'text') {
+        appendFinalText(state, update.content.text)
+      }
+    },
+    end(context = {}) {
+      const text = stripAnsi(state.text).trim()
+      return {
+        text,
+        sessionRef: String(context.sessionRef || state.sessionRef || ''),
+        outcome: protocolStopOutcome(context.stopReason || state.stopReason, context.outcome, text),
+      }
+    },
+  }
+}
+
+function createHermesLegacyFinalOutputAccumulator(sessionRef = '') {
+  const decoder = new StringDecoder('utf8')
+  const state = { text: '' }
+  return {
+    format: 'text',
+    write(chunk) {
+      appendFinalText(state, decoder.write(chunk))
+    },
+    end(context = {}) {
+      appendFinalText(state, decoder.end())
+      const text = stripAnsi(state.text).trim()
+      return {
+        text,
+        sessionRef: String(context.sessionRef || sessionRef || ''),
+        outcome: protocolStopOutcome(context.stopReason, context.outcome || 'completed', text),
+      }
+    },
+  }
+}
+
+function createHermesLegacyRunContext(options = {}) {
+  const watermarkFn = options.hermesMessageWatermarkFn || readHermesMessageWatermark
+  try {
+    const messageWatermark = watermarkFn({
+      home: options.home,
+      existsFn: options.hermesStateExistsFn,
+      queryFn: options.hermesStateQueryFn,
+    })
+    return {
+      messageWatermark: Number.isSafeInteger(messageWatermark) && messageWatermark >= 0
+        ? messageWatermark
+        : null,
+    }
+  } catch {
+    return { messageWatermark: null }
+  }
+}
+
+function resolveHermesLegacySessionRef(input = {}) {
+  return hermesSessionRef(input.stderr) || String(input.sessionRef || '')
+}
+
+async function finalizeHermesLegacyResult(input = {}) {
+  const { options = {}, result, runContext, sessionRef } = input
+  if (sessionRef && typeof options.onSessionRef === 'function') {
+    await options.onSessionRef(sessionRef, { transport: 'legacy' })
+  }
+  if (!sessionRef || !Number.isSafeInteger(runContext?.messageWatermark)) return result
+  const finalResponseFn = options.hermesFinalResponseFn || readHermesFinalResponse
+  let finalResponse = ''
+  try {
+    finalResponse = finalResponseFn(sessionRef, {
+      home: options.home,
+      afterMessageId: runContext.messageWatermark,
+      existsFn: options.hermesStateExistsFn,
+      queryFn: options.hermesStateQueryFn,
+    })
+  } catch { /* fall back to the official --quiet stdout */ }
+  const text = typeof finalResponse === 'string'
+    ? finalResponse.trim().slice(0, MAX_FINAL_TEXT_CHARS)
+    : ''
+  return text ? { ...result, text } : result
+}
+
+function profile(input) {
+  const createState = () => {
+    const state = input.createState()
+    const runtimeState = state && typeof state === 'object' ? state : {}
+    runtimeState.publicLifecycleIds ||= new Map()
+    return runtimeState
+  }
+  return Object.freeze({
+    profileId: input.profileId,
+    protocol: input.protocol,
+    framing: input.framing,
+    source: input.source,
+    capabilities: Object.freeze({
+      answerMode: input.capabilities.answerMode,
+      tools: Object.freeze({ ...input.capabilities.tools }),
+      plan: input.capabilities.plan,
+      reasoning: input.capabilities.reasoning,
+      session: input.capabilities.session,
+      terminal: input.capabilities.terminal,
+    }),
+    createDecoder: input.createDecoder,
+    createState,
+    mapEvent(event, state) {
+      return input.mapEvent(event, state).map(runtimeEvent => (
+        runtimeEvent?.id
+          ? { ...runtimeEvent, id: publicLifecycleId(state, runtimeEvent.id) }
+          : runtimeEvent
+      ))
+    },
+    mapProgress: input.mapProgress || noProgressEvent,
+    createRunContext: input.createRunContext || createDefaultRunContext,
+    resolveSessionRef: input.resolveSessionRef || resolveDefaultSessionRef,
+    finalizeResult: input.finalizeResult || finalizeDefaultResult,
+    createFinalOutputAccumulator: input.createFinalOutputAccumulator,
+  })
+}
+
+const FULL_TOOL_LIFECYCLE = Object.freeze({ start: true, update: true, result: true })
+const START_RESULT_TOOL_LIFECYCLE = Object.freeze({ start: true, update: false, result: true })
+const START_ONLY_TOOL_LIFECYCLE = Object.freeze({ start: true, update: false, result: false })
+const NO_TOOL_LIFECYCLE = Object.freeze({ start: false, update: false, result: false })
+
+const CODEX_APP_SERVER_PROFILE = profile({
+  profileId: 'codex-app-server-jsonl-v1',
+  protocol: 'codex-app-server',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: START_RESULT_TOOL_LIFECYCLE,
+    plan: true, reasoning: true, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createStatelessRuntimeState,
+  mapEvent: codexRuntimeEvents,
+  mapProgress: codexProgressEvent,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('codex'),
+})
+
+const ANTHROPIC_STREAM_JSON_PROFILE = profile({
+  profileId: 'anthropic-stream-json-v1',
+  protocol: 'anthropic-stream-json',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: FULL_TOOL_LIFECYCLE,
+    plan: true, reasoning: true, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createClaudeQwenRuntimeState,
+  mapEvent: claudeQwenRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('claude'),
+})
+
+const ACP_JSONRPC_PROFILE = profile({
+  profileId: 'acp-jsonrpc-v1',
+  protocol: 'acp',
+  framing: 'jsonrpc-jsonl',
+  source: 'acp',
+  capabilities: {
+    answerMode: 'delta', tools: FULL_TOOL_LIFECYCLE,
+    plan: true, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createAcpRuntimeState,
+  mapEvent: acpRuntimeEvents,
+  createFinalOutputAccumulator: createAcpFinalOutputAccumulator,
+})
+
+const MIMO_JSON_EVENTS_PROFILE = profile({
+  profileId: 'mimo-json-events-v1',
+  protocol: 'mimo-json-events',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createStatelessRuntimeState,
+  mapEvent: mimoJsonRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('mimo'),
+})
+
+const GEMINI_STREAM_JSON_PROFILE = profile({
+  profileId: 'gemini-stream-json-v1',
+  protocol: 'gemini-stream-json',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: START_RESULT_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createGeminiRuntimeState,
+  mapEvent: geminiStreamJsonRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('gemini'),
+})
+
+const OPENCODE_JSON_EVENTS_PROFILE = profile({
+  profileId: 'opencode-json-events-v1',
+  protocol: 'opencode-json-events',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createStatelessRuntimeState,
+  mapEvent: openCodeJsonRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('opencode'),
+})
+
+const PI_JSON_EVENTS_PROFILE = profile({
+  profileId: 'pi-json-events-v2',
+  protocol: 'pi-json',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: FULL_TOOL_LIFECYCLE,
+    plan: false, reasoning: true, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createPiRuntimeState,
+  mapEvent: piJsonRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('pi'),
+})
+
+const OPENCLAW_TERMINAL_DOCUMENT_PROFILE = profile({
+  profileId: 'openclaw-terminal-document-v1',
+  protocol: 'openclaw-terminal-document',
+  framing: 'document',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'final', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: false, terminal: true,
+  },
+  createDecoder: null,
+  createState: createStatelessRuntimeState,
+  mapEvent: finalOnlyRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('openclaw'),
+})
+
+const OPENCODE_REVIEW_TERMINAL_DOCUMENT_PROFILE = profile({
+  profileId: 'opencodereview-terminal-document-v1',
+  protocol: 'opencodereview-terminal-document',
+  framing: 'document',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'final', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: false, terminal: true,
+  },
+  createDecoder: null,
+  createState: createStatelessRuntimeState,
+  mapEvent: finalOnlyRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('opencodereview'),
+})
+
+const WORKBUDDY_TERMINAL_RESULT_PROFILE = profile({
+  profileId: 'workbuddy-terminal-result-json-v1',
+  protocol: 'workbuddy-terminal-result-json',
+  framing: 'document',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'final', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: null,
+  createState: createStatelessRuntimeState,
+  mapEvent: finalOnlyRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('workbuddy'),
+})
+
+const KIMI_STREAM_JSON_PROFILE = profile({
+  profileId: 'assistant-jsonl-v1',
+  protocol: 'assistant-jsonl',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createStatelessRuntimeState,
+  mapEvent: kimiStreamJsonRuntimeEvents,
+  createFinalOutputAccumulator: createFinalOutputAccumulator('kimi'),
+})
+
+const HERMES_FINAL_TEXT_PROFILE = profile({
+  profileId: 'terminal-text-v1',
+  protocol: 'terminal-text',
+  framing: 'document',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'final', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: null,
+  createState: createStatelessRuntimeState,
+  mapEvent: finalOnlyRuntimeEvents,
+  createRunContext: createHermesLegacyRunContext,
+  resolveSessionRef: resolveHermesLegacySessionRef,
+  finalizeResult: finalizeHermesLegacyResult,
+  createFinalOutputAccumulator: createHermesLegacyFinalOutputAccumulator,
+})
+
+const HERMES_STREAM_JSON_PROFILE = profile({
+  profileId: 'hermes-stream-json-v1',
+  protocol: 'hermes-stream-json',
+  framing: 'jsonl',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'delta', tools: START_RESULT_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createDecoder: createJsonLineParser,
+  createState: createStatelessRuntimeState,
+  mapEvent(event) {
+    if (event.type === 'text' && typeof event.text === 'string') {
+      return [{ type: 'answer_delta', status: 'running', delta: event.text }]
+    }
+    if (['tool_use', 'tool_result'].includes(event.type)) {
+      return [{
+        id: event.tool_call_id || event.name,
+        type: event.type === 'tool_use' ? 'tool_start' : 'tool_result_summary',
+        title: event.name || 'tool',
+        status: event.type === 'tool_use' ? 'running' : event.is_error ? 'failed' : 'completed',
+      }]
+    }
+    return []
+  },
+  async finalizeResult({ result, options }) {
+    // Both native chat formats use the same resumable conversation IDs.
+    if (result.sessionRef) await options.onSessionRef?.(result.sessionRef, { transport: 'legacy' })
+    return result
+  },
+  createFinalOutputAccumulator(sessionRef = '') {
+    const state = { text: '', sessionRef, outcome: 'partial' }
+    const ingest = event => {
+      if (typeof event.session_id === 'string' && event.session_id) state.sessionRef = event.session_id
+      if (event.type === 'text' && typeof event.text === 'string') appendFinalText(state, event.text)
+      if (event.type === 'result') {
+        if (typeof event.text === 'string') state.text = event.text.slice(0, MAX_FINAL_TEXT_CHARS)
+        state.outcome = event.exit_code === 0 && !event.error ? 'completed' : 'failed'
+        if (event.error) state.error = String(event.error)
+      }
+    }
+    const parser = createJsonLineParser(ingest)
+    return {
+      ingest,
+      write: chunk => parser.write(chunk),
+      end() {
+        parser.end()
+        return { ...state }
+      },
+    }
+  },
+})
+
+const ZCODE_JSON_PROFILE = profile({
+  profileId: 'zcode-prompt-json-v1',
+  protocol: 'zcode-prompt-json',
+  framing: 'document',
+  source: 'stdout',
+  capabilities: {
+    answerMode: 'final', tools: NO_TOOL_LIFECYCLE,
+    plan: false, reasoning: false, session: true, terminal: true,
+  },
+  createState: createStatelessRuntimeState,
+  createDecoder: null,
+  mapEvent: finalOnlyRuntimeEvents,
+  createFinalOutputAccumulator() {
+    const decoder = new StringDecoder('utf8')
+    const raw = { text: '' }
+    return {
+      capture(chunk) { appendFinalText(raw, decoder.write(chunk)) },
+      end() {
+        appendFinalText(raw, decoder.end())
+        let value
+        try { value = JSON.parse(raw.text) } catch { return { text: '', outcome: 'failed' } }
+        if (typeof value.response !== 'string' || typeof value.sessionId !== 'string') {
+          return { text: '', outcome: 'failed' }
+        }
+        return {
+          text: value.response,
+          sessionRef: value.sessionId,
+          outcome: ['idle', 'completed'].includes(value.projection?.status) ? 'completed' : 'partial',
+        }
+      },
+    }
+  },
+})
+
+const CONNECTOR_EVENT_PROFILES = Object.freeze({
+  codex: CODEX_APP_SERVER_PROFILE,
+  hermes: ACP_JSONRPC_PROFILE,
+  openclaw: ACP_JSONRPC_PROFILE,
+  workbuddy: WORKBUDDY_TERMINAL_RESULT_PROFILE,
+  zcode: ZCODE_JSON_PROFILE,
+  pi: PI_JSON_EVENTS_PROFILE,
+  kimi: ACP_JSONRPC_PROFILE,
+  mimo: MIMO_JSON_EVENTS_PROFILE,
+  claude: ANTHROPIC_STREAM_JSON_PROFILE,
+  gemini: GEMINI_STREAM_JSON_PROFILE,
+  opencode: OPENCODE_JSON_EVENTS_PROFILE,
+  qwen: ANTHROPIC_STREAM_JSON_PROFILE,
+  opencodereview: OPENCODE_REVIEW_TERMINAL_DOCUMENT_PROFILE,
+})
+
+const TRANSPORT_EVENT_PROFILES = Object.freeze({
+  hermes: Object.freeze({ legacy: HERMES_FINAL_TEXT_PROFILE, 'stream-json': HERMES_STREAM_JSON_PROFILE }),
+  openclaw: Object.freeze({ legacy: OPENCLAW_TERMINAL_DOCUMENT_PROFILE }),
+  kimi: Object.freeze({ 'stream-json': KIMI_STREAM_JSON_PROFILE }),
+  mimo: Object.freeze({ acp: ACP_JSONRPC_PROFILE }),
+  pi: Object.freeze({ json: PI_JSON_EVENTS_PROFILE }),
+  opencode: Object.freeze({ acp: ACP_JSONRPC_PROFILE }),
+  workbuddy: Object.freeze({ 'stream-json': ANTHROPIC_STREAM_JSON_PROFILE }),
+})
+
+function resolveConnectorEventProfile(kind, options = {}) {
+  const base = CONNECTOR_EVENT_PROFILES[kind]
+  if (!base) return null
+  const transport = typeof options.transport === 'string' ? options.transport : ''
+  if (!transport || transport === base.protocol) return base
+  return TRANSPORT_EVENT_PROFILES[kind]?.[transport] || null
+}
+
+function connectorLimitedRuntimeEvent(kind, profile) {
+  const tools = profile?.capabilities?.tools
+  const limited = profile?.capabilities?.answerMode === 'final' || !tools?.start || !tools?.result
+  if (!profile || !limited || !/^[A-Za-z0-9._:-]{1,80}$/.test(String(kind || ''))) return null
+  return {
+    id: `${kind}-connector`,
+    type: 'warning',
+    status: 'waiting',
+    title: 'connector_limited',
+  }
+}
+
+module.exports = {
+  CONNECTOR_EVENT_PROFILES,
+  connectorLimitedRuntimeEvent,
+  resolveConnectorEventProfile,
+}

desktop/src/agents/cli/cli-invocations.cjs

@@ -6,13 +6,25 @@ const IMAGE_ATTACHMENT_LIMITS = Object.freeze({
   hermes: 1,
   opencode: 4,
 })
+const DEFAULT_INTERNAL_TURN_LIMITS = Object.freeze({
+  // Preserve the default for independent replies. Automatic discussions pass
+  // an explicit zero to let the native tool loop finish its work.
+  workbuddy: 8,
+})
+
+function internalTurnLimit(kind, requested) {
+  if (requested === 0) return 0
+  const value = Number(requested)
+  if (Number.isInteger(value) && value >= 1 && value <= 50) return value
+  return DEFAULT_INTERNAL_TURN_LIMITS[kind]
+}
 
 function codexSandbox(requested) {
   if (requested != null) {
     if (!CODEX_SANDBOXES.has(requested)) throw new Error('CODEX_SANDBOX_UNSUPPORTED')
     return requested
   }
-  const configured = process.env.ROUNDRELAY_CODEX_SANDBOX || 'read-only'
+  const configured = process.env.MELDWORK_CODEX_SANDBOX || 'read-only'
   return CODEX_SANDBOXES.has(configured) ? configured : 'read-only'
 }
 
@@ -62,8 +74,24 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
     }
   }
   if (kind === 'hermes') {
-    const legacySessionRef = options.sessionTransport === 'acp' ? '' : sessionRef
-    const useAcp = !attachments.length
+    if (options.hermesStreamJsonAvailable === true
+        && (options.hermesAcpAvailable === false || options.invocationTransport === 'stream-json'
+          || (sessionRef && options.sessionTransport !== 'acp'))
+        && (!sessionRef || options.sessionTransport !== 'acp')) {
+      return {
+        command: executable,
+        args: ['chat', '--format', 'stream-json',
+          ...(options.sandbox === 'workspace-write' ? ['--yolo'] : []),
+          ...(sessionRef ? ['--resume', sessionRef] : []),
+          ...(attachments[0] ? ['--image', attachments[0]] : []), '--query'],
+        promptArg: true,
+        eventTransport: 'stream-json',
+      }
+    }
+    // Hermes uses the same native conversation identifier across its ACP and
+    // legacy transports. Keep it when an attachment requires the legacy path.
+    const legacySessionRef = sessionRef
+    const useAcp = options.invocationTransport !== 'legacy'
       && options.hermesAcpAvailable !== false
       && (!sessionRef || options.sessionTransport === 'acp')
     if (useAcp) {
@@ -71,6 +99,12 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
         command: executable,
         args: ['acp'],
         acpMode: options.sandbox === 'workspace-write' ? 'accept_edits' : 'default',
+        eventTransport: 'acp',
+        fallbackTransport: 'legacy',
+        fallbackSessionPolicy: 'invalidate',
+        // Hermes ACP advertises image prompts; send images as content blocks
+        // instead of silently dropping them from a text-only prompt.
+        ...(attachments.length ? { imageAttachments: attachments } : {}),
       }
     }
     return {
@@ -79,16 +113,33 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
         'chat',
         '--quiet',
         ...(options.sandbox === 'workspace-write' ? ['--yolo'] : []),
-        ...(options.provider?.id ? ['--provider', options.provider.id] : []),
-        ...(options.provider?.model ? ['--model', options.provider.model] : []),
         ...(legacySessionRef ? ['--resume', legacySessionRef] : []),
         ...(attachments[0] ? ['--image', attachments[0]] : []),
         '--query',
       ],
       promptArg: true,
+      eventTransport: 'legacy',
     }
   }
   if (kind === 'openclaw') {
+    if (options.invocationTransport !== 'legacy') {
+      return {
+        command: executable,
+        args: [
+          '--no-color', '--log-level', 'info',
+          'acp',
+          ...(sessionRef ? ['--session', sessionRef] : []),
+          '--no-prefix-cwd',
+          '--verbose',
+        ],
+        eventTransport: 'acp',
+        acpSessionStrategy: 'new',
+        publicSessionRef: sessionRef,
+        openClawGateway: true,
+        fallbackTransport: 'legacy',
+        fallbackSessionPolicy: 'preserve',
+      }
+    }
     return {
       command: executable,
       args: [
@@ -98,45 +149,77 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
       ],
       suffixArgs: ['--json'],
       promptArg: true,
+      eventTransport: 'legacy',
     }
   }
   if (kind === 'workbuddy') {
+    const maxTurns = internalTurnLimit(kind, options.maxTurns)
     return {
       command: executable,
       args: [
         '--print',
-        '--output-format', 'json',
+        '--output-format', 'stream-json',
+        '--include-partial-messages',
+        // Workspace write access means accepting file edits in the working
+        // directory. Skipping every permission check would also let the CLI
+        // run any command anywhere on the machine without confirmation.
         '--permission-mode', options.sandbox === 'workspace-write' ? 'acceptEdits' : 'plan',
-        '--max-turns', '20',
+        ...(maxTurns ? ['--max-turns', String(maxTurns)] : []),
+        ...(options.model ? ['--model', options.model] : []),
         ...(sessionRef ? ['--resume', sessionRef] : []),
       ],
       promptArg: true,
+      eventTransport: 'stream-json',
+    }
+  }
+  if (kind === 'zcode') {
+    return {
+      command: executable,
+      args: ['--json', '--no-color', '--verbose', '--cwd', workdir,
+        '--mode', options.sandbox === 'workspace-write' ? 'edit' : 'plan',
+        ...(sessionRef ? ['--resume', sessionRef] : []), '--prompt'],
+      promptArg: true,
+    }
+  }
+  if (kind === 'pi') {
+    return {
+      command: executable,
+      args: [
+        '--mode', 'json', '--print',
+        ...(options.sandbox === 'workspace-write'
+          ? ['--approve']
+          : ['--no-approve', '--tools', 'read,grep,find,ls']),
+        ...(sessionRef ? ['--session', sessionRef] : []),
+      ],
+      promptArg: true,
+      eventTransport: 'json',
     }
   }
   if (kind === 'kimi') {
-    if (options.sandbox !== 'workspace-write') {
+    // Kimi rejects --auto together with --prompt. Use the permission-aware
+    // ACP transport for both modes instead of bypassing approval with --yolo.
+    return {
+      command: executable,
+      args: ['acp'],
+      acpMode: 'default',
+      eventTransport: 'acp',
+    }
+  }
+  if (kind === 'mimo') {
+    if (!attachments.length && options.invocationTransport !== 'json') {
       return {
         command: executable,
-        args: ['acp'],
-        acpMode: 'plan',
+        args: ['acp', '--cwd', workdir],
+        acpMode: options.sandbox === 'workspace-write' ? 'build' : 'plan',
+        eventTransport: 'acp',
+        fallbackTransport: 'json',
+        fallbackSessionPolicy: 'preserve',
       }
     }
     return {
       command: executable,
       args: [
-        '--output-format', 'stream-json',
-        '--auto',
-        ...(sessionRef ? ['--session', sessionRef] : []),
-        '--prompt',
-      ],
-      promptArg: true,
-    }
-  }
-  if (kind === 'mimo') {
-    return {
-      command: executable,
-      args: [
-        'run', '--pure', '--agent', options.sandbox === 'workspace-write' ? 'build' : 'plan',
+        'run', '--agent', options.sandbox === 'workspace-write' ? 'build' : 'plan',
         '--format', 'json', '--dir', workdir,
         ...(sessionRef ? ['--session', sessionRef] : []),
       ],
@@ -164,8 +247,6 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
         '--output-format', 'stream-json',
         '--include-partial-messages',
         '--approval-mode', options.sandbox === 'workspace-write' ? 'auto-edit' : 'plan',
-        ...(options.provider?.id === 'openai' ? ['--auth-type', 'openai'] : []),
-        ...(options.provider?.model ? ['--model', options.provider.model] : []),
         ...(sessionRef ? ['--resume', sessionRef] : []),
       ],
       promptArg: true,
@@ -184,6 +265,16 @@ function invocation(kind, executable, workdir, sessionRef = '', options = {}) {
     }
   }
   if (kind === 'opencode') {
+    if (!attachments.length && options.invocationTransport !== 'json') {
+      return {
+        command: executable,
+        args: ['acp', '--cwd', workdir],
+        acpMode: options.sandbox === 'workspace-write' ? 'build' : 'plan',
+        eventTransport: 'acp',
+        fallbackTransport: 'json',
+        fallbackSessionPolicy: 'preserve',
+      }
+    }
     return {
       command: executable,
       args: [

desktop/src/agents/cli/cli-network-environment.cjs

@@ -0,0 +1,19 @@
+const NETWORK_ENV_KEYS = Object.freeze([
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+  'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy',
+  'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+  'REQUESTS_CA_BUNDLE', 'CURL_CA_BUNDLE', 'NODE_USE_ENV_PROXY',
+])
+
+function networkEnvironment(source = {}, platform = process.platform) {
+  const result = {}
+  for (const [key, value] of Object.entries(source)) {
+    const allowed = platform === 'win32'
+      ? NETWORK_ENV_KEYS.find(name => name.toLowerCase() === key.toLowerCase())
+      : NETWORK_ENV_KEYS.find(name => name === key)
+    if (allowed && typeof value === 'string') result[allowed] = value
+  }
+  return result
+}
+
+module.exports = { NETWORK_ENV_KEYS, networkEnvironment }

desktop/src/agents/cli/cli-openclaw-gateway.cjs

@@ -0,0 +1,317 @@
+const { spawn } = require('node:child_process')
+const net = require('node:net')
+const path = require('node:path')
+
+const {
+  KILL_SETTLE_MS,
+  TERMINATE_GRACE_MS,
+  childEnvironment,
+} = require('./cli-process-support.cjs')
+const {
+  configureOpenClawGatewayRuntime,
+  refreshOpenClawRuntimeAfterStartup,
+} = require('./openclaw-runtime.cjs')
+
+const GATEWAY_READY_MARKER = '[gateway] ready'
+const GATEWAY_READY_TIMEOUT_MS = 15_000
+const GATEWAY_HEALTH_TIMEOUT_MS = 7_500
+const GATEWAY_HEALTH_OUTPUT_BYTES = 64 * 1024
+const GATEWAY_SETUP_ATTEMPTS = 3
+const OPENCLAW_GLOBAL_ARGS = Object.freeze(['--no-color', '--log-level', 'info'])
+
+function gatewayStartError(retryable = false) {
+  const error = new Error('OPENCLAW_GATEWAY_START_FAILED')
+  error.retryable = retryable
+  Object.defineProperty(error, 'acpFallbackAllowed', { value: true })
+  return error
+}
+
+function isPortConflict(value) {
+  return /EADDRINUSE|address already in use|port[^\n]{0,80}(?:busy|in use)/i
+    .test(String(value || ''))
+}
+
+function attachRuntimeOptions(error, runtimeOptions) {
+  if (error && (typeof error === 'object' || typeof error === 'function')) {
+    Object.defineProperty(error, 'openClawRuntimeOptions', {
+      value: {
+        env: runtimeOptions.env,
+        openClawRuntimeGuard: runtimeOptions.openClawRuntimeGuard,
+      },
+    })
+  }
+  return error
+}
+
+async function availableLoopbackPort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+    const finish = (error, port) => {
+      server.removeAllListeners()
+      if (error) reject(error)
+      else resolve(port)
+    }
+    server.once('error', error => finish(error))
+    server.listen({ host: '127.0.0.1', port: 0, exclusive: true }, () => {
+      const address = server.address()
+      const port = address && typeof address === 'object' ? address.port : 0
+      server.close(error => finish(error, port))
+    })
+    server.unref()
+  })
+}
+
+async function terminateGateway(child, platform = process.platform) {
+  if (!child || child.exitCode != null || child.signalCode != null) return
+  await new Promise((resolve) => {
+    let settled = false
+    let forceKillTimeout
+    let forceSettleTimeout
+    const finish = () => {
+      if (settled) return
+      settled = true
+      clearTimeout(forceKillTimeout)
+      clearTimeout(forceSettleTimeout)
+      child.removeListener('close', finish)
+      child.removeListener('error', finish)
+      resolve()
+    }
+    child.once('close', finish)
+    child.once('error', finish)
+    if (platform === 'win32' && child.pid) {
+      const killer = spawn('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore', windowsHide: true,
+      })
+      killer.on('error', () => {})
+      killer.unref()
+      forceSettleTimeout = setTimeout(finish, TERMINATE_GRACE_MS + KILL_SETTLE_MS)
+      return
+    }
+    const signalTree = (signal) => {
+      if (child.pid) {
+        try {
+          process.kill(-child.pid, signal)
+          return
+        } catch { /* fall back to the direct child */ }
+      }
+      try { child.kill(signal) } catch { /* the process has already exited */ }
+    }
+    signalTree('SIGTERM')
+    forceKillTimeout = setTimeout(() => signalTree('SIGKILL'), TERMINATE_GRACE_MS)
+    forceSettleTimeout = setTimeout(finish, TERMINATE_GRACE_MS + KILL_SETTLE_MS)
+  })
+  for (const stream of [child.stdin, child.stdout, child.stderr]) {
+    if (stream && !stream.destroyed) stream.destroy()
+  }
+}
+
+async function waitForGatewayReady(child, signal) {
+  return new Promise((resolve, reject) => {
+    let settled = false
+    let output = ''
+    const timeout = setTimeout(
+      () => finish(gatewayStartError()),
+      GATEWAY_READY_TIMEOUT_MS,
+    )
+    const cleanup = () => {
+      clearTimeout(timeout)
+      signal?.removeEventListener('abort', abort)
+      child.stdout?.removeListener('data', onData)
+      child.stderr?.removeListener('data', onData)
+      child.removeListener('error', onError)
+      child.removeListener('close', onClose)
+    }
+    const finish = (error) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      if (error) reject(error)
+      else {
+        child.on('error', () => {})
+        child.stdout?.resume()
+        child.stderr?.resume()
+        resolve()
+      }
+    }
+    const onData = (chunk) => {
+      output = `${output}${chunk.toString('utf8')}`.slice(-8192)
+      if (output.includes(GATEWAY_READY_MARKER)) finish()
+    }
+    const onError = error => finish(gatewayStartError(
+      error?.code === 'EADDRINUSE' || isPortConflict(error?.message),
+    ))
+    const onClose = () => finish(gatewayStartError(isPortConflict(output)))
+    const abort = () => finish(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.once('error', onError)
+    child.once('close', onClose)
+    if (signal?.aborted) abort()
+    else signal?.addEventListener('abort', abort, { once: true })
+  })
+}
+
+function gatewayChildAlive(child) {
+  return Boolean(child && !child.killed && child.exitCode == null && child.signalCode == null)
+}
+
+async function verifyGatewayHealth({
+  child: gatewayChild,
+  env,
+  executable,
+  gatewayPort,
+  signal,
+  workdir,
+}) {
+  if (!gatewayChildAlive(gatewayChild)) throw gatewayStartError()
+  const args = [
+    ...OPENCLAW_GLOBAL_ARGS, 'gateway', 'health',
+    '--port', String(gatewayPort),
+    '--timeout', '5000',
+    '--json',
+  ]
+  let healthChild
+  try {
+    healthChild = spawn(executable, args, {
+      cwd: path.resolve(workdir),
+      detached: process.platform !== 'win32',
+      env,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    })
+  } catch {
+    throw gatewayStartError()
+  }
+
+  await new Promise((resolve, reject) => {
+    let settled = false
+    let stdout = ''
+    let stdoutBytes = 0
+    const timeout = setTimeout(
+      () => finish(gatewayStartError()),
+      GATEWAY_HEALTH_TIMEOUT_MS,
+    )
+    const cleanup = () => {
+      clearTimeout(timeout)
+      signal?.removeEventListener('abort', abort)
+      gatewayChild.removeListener('error', onGatewayExit)
+      gatewayChild.removeListener('close', onGatewayExit)
+      healthChild.stdout?.removeListener('data', onData)
+      healthChild.removeListener('error', onHealthError)
+      healthChild.removeListener('close', onHealthClose)
+    }
+    const finish = (error) => {
+      if (settled) return
+      settled = true
+      cleanup()
+      const stopHealth = error && gatewayChildAlive(healthChild)
+        ? terminateGateway(healthChild)
+        : Promise.resolve()
+      stopHealth.catch(() => {}).then(() => {
+        if (error) reject(error)
+        else resolve()
+      })
+    }
+    const onData = (chunk) => {
+      stdoutBytes += chunk.length
+      if (stdoutBytes > GATEWAY_HEALTH_OUTPUT_BYTES) {
+        finish(gatewayStartError())
+        return
+      }
+      stdout += chunk.toString('utf8')
+    }
+    const onGatewayExit = () => finish(gatewayStartError())
+    const onHealthError = () => finish(gatewayStartError())
+    const onHealthClose = (code) => {
+      if (code !== 0 || !gatewayChildAlive(gatewayChild)) {
+        finish(gatewayStartError())
+        return
+      }
+      let result
+      try { result = JSON.parse(stdout.trim()) } catch { /* handled below */ }
+      finish(result?.ok === true ? null : gatewayStartError())
+    }
+    const abort = () => finish(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+
+    healthChild.stdout?.on('data', onData)
+    healthChild.once('error', onHealthError)
+    healthChild.once('close', onHealthClose)
+    gatewayChild.once('error', onGatewayExit)
+    gatewayChild.once('close', onGatewayExit)
+    if (signal?.aborted) abort()
+    else signal?.addEventListener('abort', abort, { once: true })
+  })
+}
+
+async function withOpenClawGateway(options, callback) {
+  if (typeof callback !== 'function') throw new TypeError('OPENCLAW_GATEWAY_CALLBACK_REQUIRED')
+  if (typeof options?.executable !== 'string' || !options.executable
+      || typeof options?.workdir !== 'string' || !path.isAbsolute(options.workdir)) {
+    throw new Error('OPENCLAW_GATEWAY_SCOPE_INVALID')
+  }
+
+  let runtimeOptions = options
+  for (let attempt = 0; attempt < GATEWAY_SETUP_ATTEMPTS; attempt += 1) {
+    if (options.signal?.aborted) throw new Error('LOCAL_AGENT_EXECUTION_STOPPED')
+    const gatewayPort = await availableLoopbackPort()
+    runtimeOptions = configureOpenClawGatewayRuntime(runtimeOptions, gatewayPort)
+    const gatewayUrl = `ws://127.0.0.1:${gatewayPort}`
+    const args = [
+      ...OPENCLAW_GLOBAL_ARGS, 'gateway', 'run',
+      '--bind', 'loopback',
+      '--port', String(gatewayPort),
+      '--auth', 'token',
+      '--tailscale', 'off',
+      '--ws-log', 'compact',
+    ]
+    const gatewayEnv = childEnvironment(
+      { kind: 'openclaw' },
+      options.workdir,
+      runtimeOptions,
+      process.platform,
+    )
+    const child = spawn(options.executable, args, {
+      cwd: path.resolve(options.workdir),
+      detached: process.platform !== 'win32',
+      env: gatewayEnv,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    })
+
+    try {
+      await waitForGatewayReady(child, options.signal)
+      await verifyGatewayHealth({
+        child,
+        env: gatewayEnv,
+        executable: options.executable,
+        gatewayPort,
+        signal: options.signal,
+        workdir: options.workdir,
+      })
+      runtimeOptions = refreshOpenClawRuntimeAfterStartup(runtimeOptions)
+    } catch (error) {
+      await terminateGateway(child)
+      // Startup can migrate the config before a port conflict or health failure.
+      runtimeOptions = refreshOpenClawRuntimeAfterStartup(runtimeOptions)
+      if (error?.retryable && attempt + 1 < GATEWAY_SETUP_ATTEMPTS) continue
+      throw attachRuntimeOptions(error, runtimeOptions)
+    }
+
+    try {
+      return await callback({
+        env: runtimeOptions.env,
+        gatewayPort,
+        gatewayUrl,
+        openClawRuntimeGuard: runtimeOptions.openClawRuntimeGuard,
+      })
+    } catch (error) {
+      throw attachRuntimeOptions(error, runtimeOptions)
+    } finally {
+      await terminateGateway(child)
+    }
+  }
+  throw gatewayStartError()
+}
+
+module.exports = { withOpenClawGateway }

desktop/src/agents/cli/cli-output-parsers.cjs

@@ -10,7 +10,7 @@ const MAX_RUNTIME_JSON_PENDING_CHARS = 1024 * 1024
 const MAX_STRUCTURED_JSON_BYTES = 64 * 1024 * 1024
 const MAX_STRUCTURED_TEXT_CHARS = 1024 * 1024
 const STRUCTURED_JSONL_KINDS = new Set([
-  'codex', 'workbuddy', 'kimi', 'mimo', 'claude', 'gemini', 'opencode', 'qwen',
+  'codex', 'workbuddy', 'pi', 'kimi', 'mimo', 'claude', 'gemini', 'opencode', 'qwen',
 ])
 const STRUCTURED_DOCUMENT_KINDS = new Set(['openclaw', 'opencodereview'])
 function parseCodexOutput(stdout) {
@@ -90,6 +90,65 @@ function appendStructuredText(state, value, separator = '\n') {
   state.text += `${prefix}${text}`.slice(0, remaining)
 }
 
+function stripPiInternalPromptEcho(value) {
+  let text = String(value || '').trim()
+  if (!text) return ''
+  const preamble = /^You are participating in a local multi-agent discussion\.[\s\S]*?^Answer the user naturally(?: in Markdown)?\.?\s*/im
+  text = text.replace(preamble, '').trim()
+  // Pi may resume from a compact continuation prompt and echo only the
+  // protocol instructions or the selected Harness records. Remove those
+  // internal lines while preserving any user-facing text on the same line.
+  text = text.replace(/^Do not output JSON, XML, receipt markers, protocol labels, hidden orchestration instructions, or a fixed response template\.\s*/im, '')
+  text = text.replace(/^Do not claim another Agent performed work, and do not modify shared workspace state unless this turn explicitly grants that permission\.\s*/im, '')
+  const lines = text.split(/\r?\n/)
+  const cleaned = []
+  let inRecords = false
+  for (const line of lines) {
+    const valueLine = line.trim()
+    if (/^Selected records from completed phases:\s*$/i.test(valueLine)) {
+      inRecords = true
+      continue
+    }
+    if (inRecords) {
+      if (/^MELDWORK_V4_COLLABORATION_PACKAGE_V1$/i.test(valueLine)
+          || /^\[index\]\s+\S+/i.test(valueLine)
+          || /^Artifact:\s+\S+/i.test(valueLine)
+          || /^Evidence:\s+\S+/i.test(valueLine)) continue
+      const phasePrefix = /^(?:\[(?:challenge|proposal)\]\s+agent=\S+\s+Completed the (?:challenge|proposal) phase\.\s*)/i
+      const remainder = line.replace(phasePrefix, '')
+      if (remainder !== line) {
+        if (remainder.trim()) cleaned.push(remainder)
+        continue
+      }
+      inRecords = false
+    }
+    cleaned.push(line)
+  }
+  return cleaned.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
+function stripPiPromptEcho(value, prompt) {
+  const text = String(value || '').trim()
+  const expected = String(prompt || '').trim()
+  if (expected && text.startsWith(expected)) {
+    return text.slice(expected.length).trim()
+  }
+  return stripPiInternalPromptEcho(text)
+}
+
+function stripExactMeldworkPromptEcho(value, prompt) {
+  const text = String(value || '')
+  const expected = String(prompt || '').trim()
+  if (!expected.includes('Current user task (authoritative):')
+      || !expected.startsWith('You are participating in the local ')) {
+    return text.trim()
+  }
+  const candidate = text.trimStart()
+  return candidate.startsWith(expected)
+    ? candidate.slice(expected.length).trimStart()
+    : text.trim()
+}
+
 function markStructuredFailure(state, code = 'LOCAL_AGENT_PROCESS_FAILED', diagnostic = '') {
   state.outcome = 'failed'
   state.failure = agentRuntimeFailure(code)
@@ -113,9 +172,40 @@ function stepFinishOutcome(reason) {
   return 'partial'
 }
 
+function structuredResultDiagnostic(event) {
+  const parts = []
+  if (typeof event?.error === 'string' && event.error.trim()) parts.push(event.error.trim())
+  else if (event?.error?.message) parts.push(String(event.error.message))
+  if (typeof event?.result === 'string' && event.result.trim()) parts.push(event.result.trim())
+  if (Array.isArray(event?.errors)) {
+    parts.push(...event.errors.map(value => String(value || '').trim()).filter(Boolean))
+  }
+  return parts.join('\n')
+}
+
 function ingestStructuredEvent(state, event) {
   if (!event || typeof event !== 'object' || Array.isArray(event)) return
   state.seen = true
+  if (['workbuddy', 'claude', 'qwen'].includes(state.kind)
+      && event.type === 'result') {
+    if (typeof event.session_id === 'string') state.sessionRef = event.session_id
+    if (typeof event.result === 'string') {
+      state.failure = null
+      state.diagnostic = ''
+      state.text = ''
+      appendStructuredText(state, event.result, '')
+      state.outcome = event.is_error === true ? 'partial' : 'completed'
+      return
+    }
+    // An error result without a usable result string still carries the CLI's
+    // error list; keep it as the failure diagnostic so authentication and
+    // session problems are classified instead of surfacing as a bare
+    // LOCAL_AGENT_PROCESS_FAILED.
+    if (event.is_error === true || String(event.subtype || '').startsWith('error')) {
+      markStructuredFailure(state, 'LOCAL_AGENT_PROCESS_FAILED', structuredResultDiagnostic(event))
+    }
+    return
+  }
   if (structuredEventFailed(event)) {
     markStructuredFailure(state)
     return
@@ -133,15 +223,7 @@ function ingestStructuredEvent(state, event) {
     return
   }
 
-  if (['workbuddy', 'claude', 'qwen'].includes(state.kind)) {
-    if (typeof event.session_id === 'string') state.sessionRef = event.session_id
-    if (event.type === 'result' && typeof event.result === 'string') {
-      state.text = ''
-      appendStructuredText(state, event.result, '')
-      state.outcome = 'completed'
-    }
-    return
-  }
+  if (['workbuddy', 'claude', 'qwen'].includes(state.kind)) return
 
   if (state.kind === 'kimi') {
     if (event.role === 'assistant' && typeof event.content === 'string') {
@@ -154,6 +236,41 @@ function ingestStructuredEvent(state, event) {
     return
   }
 
+  if (state.kind === 'pi') {
+    if (event.type === 'session' && typeof event.id === 'string') state.sessionRef = event.id
+    const update = event.assistantMessageEvent
+    if (event.type === 'message_update' && update?.type === 'text_delta'
+        && typeof update.delta === 'string') {
+      appendStructuredText(state, update.delta, '')
+    }
+    if (event.type === 'message_end' && event.message?.role === 'assistant'
+        && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block?.type === 'text' && typeof block.text === 'string') {
+          if (!state.text) appendStructuredText(state, block.text, '')
+        }
+      }
+      const stopReason = event.message.stopReason
+      if (stopReason) state.outcome = stepFinishOutcome(stopReason)
+    }
+    if (event.type === 'turn_end') {
+      state.outcome = stepFinishOutcome(event.message?.stopReason || event.stopReason || 'stop')
+    }
+    if (event.type === 'agent_end') {
+      state.piContinuing = event.willRetry === true || event.willContinue === true
+      const lastAssistant = event.messages?.findLast(message => message?.role === 'assistant')
+      if (lastAssistant?.stopReason) state.outcome = stepFinishOutcome(lastAssistant.stopReason)
+      else if (!state.outcome) state.outcome = 'completed'
+      if (state.outcome === 'completed' && !state.piContinuing) {
+        state.failure = null
+        state.diagnostic = ''
+      }
+    }
+    if (event.type === 'agent_settled') state.piContinuing = false
+    if (state.outcome === 'failed') markStructuredFailure(state)
+    return
+  }
+
   if (['mimo', 'opencode'].includes(state.kind)) {
     if (typeof event.sessionID === 'string') state.sessionRef = event.sessionID
     if (event.type === 'text' && event.part?.type === 'text'
@@ -273,7 +390,7 @@ function openCodeReviewTerminal(status, manifest, manifestPresent = manifest !=
   }
 }
 
-function finalizeStructuredState(state) {
+function finalizeStructuredState(state, context = {}) {
   if (state.parseError) {
     return {
       text: '',
@@ -313,9 +430,12 @@ function finalizeStructuredState(state) {
   }
 
   if (!state.seen && !state.text && !state.outcome) return null
-  const outcome = state.outcome || (state.text ? 'partial' : 'failed')
+  const outcome = state.kind === 'pi' && state.piContinuing && state.outcome === 'completed'
+    ? 'partial' : state.outcome || (state.text ? 'partial' : 'failed')
   const result = {
-    text: state.text.trim(),
+    text: state.kind === 'pi'
+      ? stripPiPromptEcho(state.text, context.prompt)
+      : state.text.trim(),
     sessionRef: state.sessionRef,
     outcome,
   }
@@ -348,7 +468,7 @@ function createStructuredOutputAccumulator(kind, sessionRef = '') {
     return {
       format: 'jsonl',
       ingest: event => ingestStructuredEvent(state, event),
-      end: () => finalizeStructuredState(state),
+      end: context => finalizeStructuredState(state, context),
     }
   }
 
@@ -611,6 +731,30 @@ function parseOpenCodeOutput(stdout) {
   }
 }
 
+function parsePiOutput(stdout) {
+  const events = parseJsonOutputEvents(stdout)
+  let sessionRef = ''
+  let text = ''
+  for (const event of events) {
+    if (typeof event.id === 'string' && event.type === 'session') sessionRef = event.id
+    if (event.type === 'message_update'
+        && event.assistantMessageEvent?.type === 'text_delta'
+        && typeof event.assistantMessageEvent.delta === 'string') {
+      text += event.assistantMessageEvent.delta
+    }
+    if (!text && event.type === 'message_end' && event.message?.role === 'assistant'
+        && Array.isArray(event.message?.content)) {
+      text = event.message.content
+        .filter(block => block?.type === 'text' && typeof block.text === 'string')
+        .map(block => block.text)
+        .join('')
+    }
+  }
+  const parsedText = text.trim()
+  const answer = stripPiInternalPromptEcho(parsedText)
+  return { text: parsedText ? answer : events.length ? '' : String(stdout || '').trim(), sessionRef }
+}
+
 function openCodeReviewText(output) {
   const sections = []
   if (typeof output.message === 'string' && output.message.trim()) {
@@ -686,6 +830,14 @@ function classifyCliOutcome(kind, stdout) {
   }
 
   const events = parseJsonOutputEvents(stdout)
+  if (['workbuddy', 'claude', 'qwen'].includes(kind)) {
+    const result = events.findLast(event => event?.type === 'result' && typeof event.result === 'string')
+    if (result) {
+      return {
+        outcome: result.is_error === true ? 'partial' : 'completed',
+      }
+    }
+  }
   const failed = events.findLast(event => (
     event?.type === 'error'
       || event?.status === 'failed'
@@ -706,11 +858,6 @@ function classifyCliOutcome(kind, stdout) {
         : 'partial',
     }
   }
-  if (['workbuddy', 'claude', 'qwen'].includes(kind)) {
-    return {
-      outcome: events.some(event => event?.type === 'result') ? 'completed' : 'partial',
-    }
-  }
   if (kind === 'kimi') {
     return {
       outcome: events.some(event => event?.type === 'session.resume_hint')
@@ -718,6 +865,16 @@ function classifyCliOutcome(kind, stdout) {
         : 'partial',
     }
   }
+  if (kind === 'pi') {
+    const terminal = events.findLast(event => event?.type === 'turn_end' || event?.type === 'agent_end')
+    if ((terminal?.willRetry === true || terminal?.willContinue === true)
+        && events.at(-1)?.type !== 'agent_settled') return { outcome: 'partial' }
+    const lastAssistant = terminal?.messages?.findLast(message => message?.role === 'assistant')
+    const previousTurn = events.findLast(event => event?.type === 'turn_end')
+    const reason = terminal?.message?.stopReason || terminal?.stopReason || lastAssistant?.stopReason
+      || previousTurn?.message?.stopReason || previousTurn?.stopReason
+    return { outcome: reason ? stepFinishOutcome(reason) : terminal ? 'completed' : 'partial' }
+  }
   if (['mimo', 'opencode'].includes(kind)) {
     const finish = events.findLast(event => (
       event?.type === 'step_finish' || event?.part?.type === 'step-finish'
@@ -754,7 +911,8 @@ function classifyCliOutcome(kind, stdout) {
 function structuredCliError(stdout) {
   const failed = parseJsonOutputEvents(stdout)
     .findLast(event => event?.is_error || event?.subtype?.startsWith('error'))
-  return String(failed?.error?.message || failed?.result || '').trim()
+  if (!failed) return ''
+  return structuredResultDiagnostic(failed)
 }
 
 function hermesSessionRef(stderr) {
@@ -833,11 +991,13 @@ module.exports = {
   parseKimiOutput,
   parseMimoOutput,
   parseOpenCodeOutput,
+  parsePiOutput,
   parseOpenCodeReviewOutput,
   parseWorkBuddyOutput,
   readHermesFinalResponse,
   readHermesMessageWatermark,
   stripAnsi,
+  stripExactMeldworkPromptEcho,
   structuredCliError,
   classifyCliOutcome,
 }

desktop/src/agents/cli/cli-output-repetition.cjs

@@ -0,0 +1,43 @@
+// Detect a runaway native turn, rather than deduplicating its visible answer.
+// Exact repetitions and sustained paraphrased closing acknowledgements count;
+// real tool activity resets the window.
+const CLOSING_ACKNOWLEDGEMENT = /^(?:(?:确认(?:收到)?|收到|本轮).{0,100}(?:收尾|结束|完成|定稿|后续轮次|按.{0,16}分工).{0,30}|确认|收到|确认收到|(?:confirmed|acknowledged|done)(?:[,:;].{0,100})?)$/iu
+
+function createOutputRepetitionGuard() {
+  let text = ''
+  let unchecked = 0
+  return update => {
+    const type = update?.sessionUpdate || update?.type
+    if (['tool_call', 'tool_call_update', 'tool_start', 'tool_result_summary'].includes(type)) {
+      text = ''
+      unchecked = 0
+      return false
+    }
+    const value = type === 'answer_delta' ? update.delta
+      : type === 'agent_message_chunk' && update.content?.type === 'text' ? update.content.text : ''
+    const chunk = String(value || '').replace(/\s/g, '')
+    if (!chunk) return false
+    text = (text + chunk).slice(-8192)
+    unchecked += chunk.length
+    if (unchecked < 32 || text.length < 64) return false
+    unchecked = 0
+    const clauses = text.split(/[。！？.!?]+/u).filter(Boolean).slice(-12)
+    if (clauses.filter(clause => CLOSING_ACKNOWLEDGEMENT.test(clause)).length >= 8) return true
+    if (new Set(text).size < 6) return false
+    const anchor = text.slice(-8)
+    let previous = text.lastIndexOf(anchor, text.length - 16)
+    while (previous >= 0) {
+      const period = text.length - 8 - previous
+      if (period > 2048) break
+      const copies = period < 80 ? 8 : 4
+      if (period * copies <= text.length) {
+        const block = text.slice(-period)
+        if (new Set(block).size >= 6 && text.endsWith(block.repeat(copies))) return true
+      }
+      previous = previous > 0 ? text.lastIndexOf(anchor, previous - 1) : -1
+    }
+    return false
+  }
+}
+
+module.exports = { createOutputRepetitionGuard }

desktop/src/agents/cli/cli-process-support.cjs

@@ -1,7 +1,12 @@
 const path = require('node:path')
-const { searchPath, systemChildEnvironment } = require('./cli-discovery.cjs')
+const { launchEnvironment, searchPath, systemChildEnvironment } = require('./cli-discovery.cjs')
+const { NETWORK_ENV_KEYS, networkEnvironment } = require('./cli-network-environment.cjs')
 const { redactChildSecrets } = require('./cli-runtime-events.cjs')
-const { agentRuntimeError } = require('../agent-runtime-contract.cjs')
+const {
+  agentRuntimeError,
+  authFailureCode,
+} = require('../agent-runtime-contract.cjs')
+const { authFailureCertainty, isContextOverflow } = require('../../runs/failure-signals.cjs')
 const { validateOpenClawRuntimeGuard } = require('./openclaw-runtime.cjs')
 
 const TERMINATE_GRACE_MS = 500
@@ -21,32 +26,44 @@ const OPENCLAW_RUNTIME_PATH_KEYS = Object.freeze([
   'OPENCLAW_CONFIG_PATH',
   'OPENCLAW_WORKSPACE_DIR',
 ])
+const CONTROLLED_RUNTIME_ENV = /^(?:AWS_|AZURE_|GOOGLE_|GEMINI_|ANTHROPIC_|OPENAI_|OPENROUTER_|CODEX_|CODEBUDDY_|HERMES_|PI_|KIMI_|MIMO_|MIMOCODE_|OPENCODE_|QWEN_|DASHSCOPE_|CLAUDE_|OCR_|CLOUDSDK_|VERTEX_|CLOUD_ML_|MOONSHOT_|CONNECTOR_TEST_|MELDWORK_TEST_)/
+const BLOCKED_RUNTIME_ENV = /^(?:NODE_OPTIONS|NODE_PATH|LD_PRELOAD|LD_LIBRARY_PATH|DYLD_|ELECTRON_RUN_AS_NODE)$/
 
 function agentExecutionError(code, diagnostic = '') {
   return agentRuntimeError(code, diagnostic)
 }
 
-function authConfigurationFailure(detail) {
-  return /api[ _-]?key|access[ _-]?token|refresh[ _-]?token|auth[ _-]?token|credential|auth(?:entication|orization)?|log(?:ged)?[ -]?in|sign(?:ed)?[ -]?in|unauthorized|forbidden|\b(?:401|403)\b|select an auth type|(?:provider|model).{0,80}(?:reject|configur|missing|invalid)|(?:reject|configur|missing|invalid).{0,80}(?:provider|model)|令牌|凭据|登录|认证|鉴权|(?:提供商|供应商|模型).{0,40}(?:配置|拒绝|缺失|无效)|(?:配置|拒绝|缺失|无效).{0,40}(?:提供商|供应商|模型)/i
-    .test(String(detail || ''))
-}
-
 function invalidSessionFailure(detail) {
   const text = String(detail || '').trim()
-  if (!text || authConfigurationFailure(text)
+  if (!text || authFailureCertainty(text)
       || /\b(?:api|access|refresh|auth|session)[ _-]?token\b/i.test(text)) return false
+  // A resumed native session that no longer fits the model context cannot be
+  // continued; rebuilding it with compact continuation context is the fix.
+  if (isContextOverflow(text)) return true
+  if (/^(?:Error: )?Resume retains gateway session policy; creation overrides are unsupported on resume\./m.test(text)
+      && /--yolo differs from this session's launch/.test(text)) return true
+  // Runtime crashes ("thread 'main' panicked ... invalid ...") and parser
+  // errors mention threads or invalid input without saying anything about the
+  // stored session. Discarding a healthy session for them loses context.
+  if (/\bpanicked\b|\bSyntaxError\b|\binvalid JSON\b|\bUnexpected token\b|\bstack backtrace\b/i.test(text)) {
+    return false
+  }
   return /\b(?:no|unknown|invalid|expired|missing|stale)\s+(?:saved\s+)?(?:session|conversation|thread)\b|\b(?:session|conversation|thread)(?:\s+(?:id|key|reference))?\b[^\n]{0,100}\b(?:not found|does not exist|no longer exists|invalid|unknown|expired|has expired|was deleted|cannot be resumed)\b/i
     .test(text)
 }
 
 function failedAgentProcessError(detail, options = {}) {
   if (!detail) return agentExecutionError('LOCAL_AGENT_EXITED')
+  if (options.kind === 'zcode' && /\bModel provider is missing an API key:/i.test(detail)) {
+    return agentExecutionError('LOCAL_AGENT_AUTH_REQUIRED', 'Missing API key for the configured Zcode provider.')
+  }
+  if (options.kind === 'workbuddy' && options.model && authFailureCode(detail)) {
+    return agentExecutionError('LOCAL_WORKBUDDY_PROVIDER_AUTH', detail)
+  }
   return agentExecutionError(
     options.sessionRef && invalidSessionFailure(detail)
       ? 'LOCAL_AGENT_SESSION_INVALID'
-      : authConfigurationFailure(detail)
-        ? 'LOCAL_AGENT_AUTH_REQUIRED'
-        : 'LOCAL_AGENT_PROCESS_FAILED',
+      : authFailureCode(detail) || 'LOCAL_AGENT_PROCESS_FAILED',
     detail,
   )
 }
@@ -60,7 +77,10 @@ function openClawChildEnvironment(workdir, options, platform) {
     throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
   }
 
-  const env = systemChildEnvironment(process.env, platform)
+  const env = {
+    ...systemChildEnvironment(process.env, platform),
+    ...networkEnvironment(source, platform),
+  }
   for (const key of [
     'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH',
     'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME',
@@ -70,7 +90,7 @@ function openClawChildEnvironment(workdir, options, platform) {
   }
 
   for (const key of OPENCLAW_RUNTIME_PATH_KEYS) env[key] = source[key]
-  env[guard.credentialKey] = source[guard.credentialKey]
+  for (const key of guard.credentialKeys) env[key] = source[key]
   const isolatedHome = source.OPENCLAW_HOME
   env.HOME = isolatedHome
   env.USERPROFILE = isolatedHome
@@ -79,6 +99,10 @@ function openClawChildEnvironment(workdir, options, platform) {
   env.XDG_STATE_HOME = path.join(isolatedHome, '.local', 'state')
   env.XDG_CACHE_HOME = path.join(isolatedHome, '.cache')
   env.XDG_RUNTIME_DIR = path.join(isolatedHome, '.runtime')
+  env.TMPDIR = env.XDG_RUNTIME_DIR
+  env.TMP = env.XDG_RUNTIME_DIR
+  env.TEMP = env.XDG_RUNTIME_DIR
+  env.OPENCLAW_DISABLE_BONJOUR = '1'
   env.APPDATA = path.join(isolatedHome, 'AppData', 'Roaming')
   env.LOCALAPPDATA = path.join(isolatedHome, 'AppData', 'Local')
   env.PATH = searchPath({ platform })
@@ -94,16 +118,33 @@ function childEnvironment(agent, workdir, options, platform) {
       ? { HERMES_EXEC_ASK: '', HERMES_YOLO_MODE: '1' }
       : { HERMES_EXEC_ASK: '1', HERMES_YOLO_MODE: '' }
     : {}
-  const openCodeSafetyEnv = agent.kind === 'opencode'
-      && options.sandbox !== 'workspace-write'
-    ? { OPENCODE_PERMISSION: OPENCODE_READ_ONLY_PERMISSION }
-    : {}
+  const openCodeSafetyEnv = {}
+  // ACP has no terminal UI for question/plan transitions. Match the native
+  // headless runner: return the answer to Meldwork instead of waiting forever.
+  const headlessPermissions = { question: 'deny', plan_enter: 'deny', plan_exit: 'deny' }
+  if (agent.kind === 'opencode') {
+    openCodeSafetyEnv.OPENCODE_PERMISSION = JSON.stringify({
+      ...(options.sandbox !== 'workspace-write' ? JSON.parse(OPENCODE_READ_ONLY_PERMISSION) : {}),
+      ...headlessPermissions,
+    })
+  }
+  if (agent.kind === 'mimo') {
+    // MiMo applies read/write permissions with ACP session/set_mode. Keep
+    // process-wide permissions stable when the discussion changes phase.
+    openCodeSafetyEnv.MIMOCODE_PERMISSION = JSON.stringify(headlessPermissions)
+  }
   const source = { ...process.env, ...options.env }
+  const controlled = Object.fromEntries(Object.entries(options.env || {}).filter(([key, value]) => (
+    typeof value === 'string'
+      && (CONTROLLED_RUNTIME_ENV.test(key) || NETWORK_ENV_KEYS.includes(key))
+      && !BLOCKED_RUNTIME_ENV.test(key)
+  )))
   return {
     ...systemChildEnvironment(process.env, platform),
-    ...options.env,
+    ...controlled,
     ...hermesSafetyEnv,
     ...openCodeSafetyEnv,
+    ...launchEnvironment(agent.kind, agent.executable, { platform }),
     PATH: searchPath({ platform, env: source }),
   }
 }

desktop/src/agents/cli/cli-runtime-event-mappers.cjs

@@ -1,6 +1,5 @@
 const {
   runtimeCommandSummary,
-  runtimeEventId,
   runtimeToolOperation,
   runtimeToolResultDetail,
   runtimeToolTitle,
@@ -64,9 +63,21 @@ function streamBlockId(event, update, index = update?.index, messageId = '') {
   return `${parent}:${message}:${Number.isInteger(index) ? index : 'block'}`
 }
 
+function streamBlockKey(event, index, messageId = '') {
+  const parent = event?.parent_tool_use_id || 'root'
+  const message = String(messageId || '')
+  return `${parent}:${message ? `${message}:` : ''}${Number.isInteger(index) ? index : 'block'}`
+}
+
+function clearStreamBlock(state, blockKey, id) {
+  if (state.blockIds.get(blockKey) === id) state.blockIds.delete(blockKey)
+  state.blocks.delete(id)
+}
+
 function createClaudeQwenRuntimeState() {
   return {
     blocks: new Map(),
+    blockIds: new Map(),
     completedTools: new Set(),
     messageIds: new Map(),
     plans: new Map(),
@@ -77,6 +88,14 @@ function createClaudeQwenRuntimeState() {
   }
 }
 
+function createGeminiRuntimeState() {
+  return {
+    completedTools: new Set(),
+    toolSummaries: new Map(),
+    toolTitles: new Map(),
+  }
+}
+
 function reasoningLifecycleEvent(state, id, status, summary = '') {
   const signature = `${status}:${summary}`
   if (state.reasoning.get(id) === signature) return null
@@ -144,6 +163,10 @@ function toolResultLifecycleEvent(state, block, fallbackId = '') {
   const id = String(block?.tool_use_id || block?.toolUseId || block?.id || fallbackId)
   if (id && state.completedTools.has(id)) return null
   if (id) state.completedTools.add(id)
+  for (const [key, blockId] of state.blockIds) {
+    if (blockId === id) state.blockIds.delete(key)
+  }
+  state.blocks.delete(id)
   return {
     ...(id ? { id } : {}),
     type: 'tool_result_summary',
@@ -165,11 +188,14 @@ function claudeQwenRuntimeEvents(event, state) {
       return []
     }
     const messageId = update.message_id || state.messageIds.get(parent) || ''
-    const id = streamBlockId(event, update, update.index, messageId)
+    const blockKey = streamBlockKey(event, update.index, messageId)
+    let id = state.blockIds.get(blockKey) || streamBlockId(event, update, update.index, messageId)
     if (update.type === 'content_block_start') {
       const block = update.content_block
       if (!block || typeof block !== 'object') return []
+      if (typeof block.id === 'string' && block.id) id = block.id
       state.blocks.set(id, block)
+      state.blockIds.set(blockKey, id)
       if (block.type === 'tool_use') {
         return [toolStartLifecycleEvent(state, block, id)].filter(Boolean)
       }
@@ -186,13 +212,26 @@ function claudeQwenRuntimeEvents(event, state) {
           && update.delta?.type === 'text_delta' && typeof update.delta.text === 'string') {
         return [{ type: 'answer_delta', status: 'running', delta: update.delta.text }]
       }
+      if (update.delta?.type === 'input_json_delta' && state.blocks.get(id)?.type === 'tool_use') {
+        return [{
+          id,
+          type: 'tool_update',
+          title: state.toolTitles.get(id) || runtimeToolTitle({ type: 'tool_use' }),
+          status: 'running',
+          ...(state.toolSummaries.get(id) ? { summary: state.toolSummaries.get(id) } : {}),
+        }]
+      }
       if (update.delta?.type === 'thinking_delta') {
         return [reasoningLifecycleEvent(state, `reasoning:${id}`, 'running')].filter(Boolean)
       }
       return []
     }
-    if (update.type === 'content_block_stop' && state.blocks.get(id)?.type === 'thinking') {
-      return [reasoningLifecycleEvent(state, `reasoning:${id}`, 'completed')].filter(Boolean)
+    if (update.type === 'content_block_stop') {
+      const block = state.blocks.get(id)
+      clearStreamBlock(state, blockKey, id)
+      if (block?.type === 'thinking') {
+        return [reasoningLifecycleEvent(state, `reasoning:${id}`, 'completed')].filter(Boolean)
+      }
     }
     return []
   }
@@ -239,53 +278,139 @@ function claudeQwenRuntimeEvents(event, state) {
   return events.filter(Boolean)
 }
 
-function jsonCliRuntimeEvents(kind, event) {
+function kimiStreamJsonRuntimeEvents(event) {
   if (!event || typeof event !== 'object') return []
-  if (kind === 'kimi' && event.role === 'assistant' && typeof event.content === 'string') {
+  if (event.role === 'assistant' && typeof event.content === 'string') {
     return [{ type: 'answer_delta', status: 'running', delta: event.content }]
   }
-  if (kind === 'gemini' && event.type === 'message' && event.role === 'assistant'
+  return []
+}
+
+function mimoJsonRuntimeEvents(event) {
+  if (!event || typeof event !== 'object') return []
+  if (event.type === 'text' && typeof event.part?.text === 'string') {
+    return [{ type: 'answer_delta', status: 'running', delta: event.part.text }]
+  }
+  return []
+}
+
+function geminiToolId(event) {
+  return typeof event?.tool_id === 'string' && event.tool_id ? event.tool_id : ''
+}
+
+function geminiStreamJsonRuntimeEvents(event, state) {
+  if (!event || typeof event !== 'object') return []
+  if (event.type === 'message' && event.role === 'assistant'
       && typeof event.content === 'string') {
     return [{ type: 'answer_delta', status: 'running', delta: event.content }]
   }
-  if (kind === 'mimo' && event.type === 'text' && typeof event.part?.text === 'string') {
-    return [{ type: 'answer_delta', status: 'running', delta: event.part.text }]
+  const id = geminiToolId(event)
+  if (!id) return []
+  if (event.type === 'tool_use') {
+    const tool = { ...event, id, name: event.tool_name, input: event.parameters }
+    const summary = runtimeToolOperation(tool)
+    const title = runtimeToolTitle(tool)
+    state?.toolSummaries.set(id, summary)
+    state?.toolTitles.set(id, title)
+    return [{
+      id,
+      type: 'tool_start',
+      title,
+      status: 'running',
+      ...(summary ? { summary } : {}),
+    }]
   }
-  if (kind === 'opencode' && event.type === 'text' && event.part?.type === 'text'
+  if (event.type === 'tool_result' && ['success', 'error'].includes(event.status)) {
+    if (state?.completedTools.has(id)) return []
+    state?.completedTools.add(id)
+    const detail = runtimeToolResultDetail(event)
+    return [{
+      id,
+      type: 'tool_result_summary',
+      title: state?.toolTitles.get(id) || runtimeToolTitle(event),
+      status: event.status === 'success' ? 'completed' : 'failed',
+      ...(state?.toolSummaries.get(id) ? { summary: state.toolSummaries.get(id) } : {}),
+      ...(detail ? { detail } : {}),
+    }]
+  }
+  return []
+}
+
+function openCodeJsonRuntimeEvents(event) {
+  if (!event || typeof event !== 'object') return []
+  if (event.type === 'text' && event.part?.type === 'text'
       && typeof event.part.text === 'string') {
     return [{ type: 'answer_delta', status: 'running', delta: event.part.text }]
   }
+  return []
+}
 
-  const type = String(event.type || event.part?.type || '').toLowerCase()
-  if (/\bplan(?:_update|_removed)?\b/.test(type)) {
-    const summary = typeof event.summary === 'string'
-      ? event.summary
-      : typeof event.content === 'string' ? event.content : event.text
+function createPiRuntimeState() {
+  return {
+    reasoning: new Map(),
+    tools: new Map(),
+  }
+}
+
+function piJsonRuntimeEvents(event, state) {
+  if (!event || typeof event !== 'object') return []
+  const update = event.assistantMessageEvent
+  if (event.type === 'message_update' && update && typeof update === 'object') {
+    const index = Number.isInteger(update.contentIndex) ? update.contentIndex : 0
+    const id = `content:${index}`
+    if (update.type === 'thinking_start') {
+      state.reasoning.set(id, '')
+      return [{ id, type: 'reasoning_summary', title: 'reasoning', status: 'running' }]
+    }
+    if (update.type === 'thinking_delta' && typeof update.delta === 'string') {
+      const summary = `${state.reasoning.get(id) || ''}${update.delta}`.slice(-2000)
+      state.reasoning.set(id, summary)
+      return [{ id, type: 'reasoning_summary', title: 'reasoning', status: 'running', summary }]
+    }
+    if (update.type === 'thinking_end') {
+      const summary = String(update.content || state.reasoning.get(id) || '').trim()
+      state.reasoning.set(id, summary)
+      return [{ id, type: 'reasoning_summary', title: 'reasoning', status: 'completed', ...(summary ? { summary } : {}) }]
+    }
+    if (update.type === 'text_delta' && typeof update.delta === 'string') {
+      return [{ type: 'answer_delta', status: 'running', delta: update.delta }]
+    }
+    if (['toolcall_start', 'tool_call_start'].includes(update.type)) {
+      const toolId = String(update.toolCallId || update.id || `tool:${index}`)
+      const title = String(update.toolName || update.name || 'tool')
+      state.tools.set(toolId, title)
+      return [{ id: toolId, type: 'tool_start', title, status: 'running' }]
+    }
+    if (['toolcall_end', 'tool_call_end'].includes(update.type)) {
+      const toolId = String(update.toolCallId || update.id || `tool:${index}`)
+      return [{
+        id: toolId,
+        type: 'tool_result_summary',
+        title: state.tools.get(toolId) || String(update.toolName || update.name || 'tool'),
+        status: update.isError === true || update.error ? 'failed' : 'completed',
+      }]
+    }
+  }
+  if (event.type === 'tool_execution_start' || event.type === 'tool_start') {
+    const id = String(event.toolCallId || event.id || 'tool')
+    const title = String(event.toolName || event.name || 'tool')
+    state.tools.set(id, title)
+    return [{ id, type: 'tool_start', title, status: 'running' }]
+  }
+  if (event.type === 'tool_execution_end' || event.type === 'tool_end') {
+    const id = String(event.toolCallId || event.id || 'tool')
     return [{
-      id: runtimeEventId(event),
-      type: 'plan',
-      title: 'plan',
-      status: /removed/.test(type) ? 'stopped' : runtimeEventStatus(event.status),
-      ...(typeof summary === 'string' ? { summary } : {}),
+      id,
+      type: 'tool_result_summary',
+      title: state.tools.get(id) || String(event.toolName || event.name || 'tool'),
+      status: event.isError === true || event.error ? 'failed' : 'completed',
     }]
   }
-  if (!/tool|function_call/.test(type)) return []
-  const status = runtimeEventStatus(
-    event.status || event.part?.status || event.part?.state?.status,
-  )
-  const completed = ['completed', 'failed', 'stopped', 'timeout'].includes(status)
-    || /result|complete|finish|end/.test(type)
-  const update = /update|progress/.test(type)
-  const summary = runtimeToolOperation(event)
-  const detail = completed ? runtimeToolResultDetail(event) : ''
-  return [{
-    id: runtimeEventId(event),
-    type: completed ? 'tool_result_summary' : update ? 'tool_update' : 'tool_start',
-    title: runtimeToolTitle(event),
-    status: status || (completed ? 'completed' : 'running'),
-    ...(summary ? { summary } : {}),
-    ...(detail ? { detail } : {}),
-  }]
+  return []
+}
+
+function finalOnlyRuntimeEvents() {
+  return []
 }
 
 function acpPlanSummary(update) {
@@ -300,22 +425,50 @@ function acpPlanSummary(update) {
 }
 
 function createAcpRuntimeState() {
-  return { tools: new Map() }
+  return { tools: new Map(), reasoning: new Map() }
+}
+
+const ACP_TOOL_KINDS = new Set([
+  'read', 'edit', 'delete', 'move', 'search',
+  'execute', 'think', 'fetch', 'switch_mode', 'other',
+])
+
+function acpToolOperation(update) {
+  const name = ACP_TOOL_KINDS.has(update.kind) ? update.kind : 'tool'
+  const input = update.rawInput ?? update.input ?? update.arguments ?? update.args
+  if (typeof update.command === 'string'
+      || (input && typeof input === 'object' && !Array.isArray(input)
+        && (Object.hasOwn(input, 'command') || Object.hasOwn(input, 'cmd')))) {
+    return `${name}: [operation hidden]`
+  }
+  return runtimeToolOperation({ ...update, name, title: undefined })
 }
 
 function acpRuntimeEvents(update, state) {
   if (!update || typeof update !== 'object') return []
   if (update.sessionUpdate === 'agent_message_chunk' && update.content?.type === 'text') {
-    return [{ type: 'answer_delta', status: 'running', delta: update.content.text }]
+    // Close an open reasoning phase once the visible answer starts.
+    const closed = state?.reasoning?.get('reasoning:acp')?.startsWith('running:')
+      ? reasoningLifecycleEvent(state, 'reasoning:acp', 'completed')
+      : null
+    return [
+      ...(closed ? [closed] : []),
+      { type: 'answer_delta', status: 'running', delta: update.content.text },
+    ]
   }
   if (update.sessionUpdate === 'agent_thought_chunk' && update.content?.type === 'text') {
-    return []
+    // Thinking is real progress: report a text-free reasoning status so the
+    // watchdog and the trace know the Agent is working. The private thought
+    // text itself never leaves the main process.
+    if (!state?.reasoning) return []
+    const event = reasoningLifecycleEvent(state, 'reasoning:acp', 'running')
+    return event ? [event] : []
   }
   if (update.sessionUpdate === 'tool_call' || update.sessionUpdate === 'tool_call_update') {
     const status = runtimeEventStatus(update.status)
     const completed = ['completed', 'failed', 'stopped', 'timeout'].includes(status)
     const id = String(update.toolCallId || '')
-    const operation = runtimeToolOperation(update)
+    const operation = acpToolOperation(update)
     if (id && operation && update.sessionUpdate === 'tool_call') state?.tools.set(id, operation)
     const summary = state?.tools.get(id) || operation
     const detail = completed ? runtimeToolResultDetail(update) : ''
@@ -349,5 +502,12 @@ module.exports = {
   codexRuntimeEvents,
   createAcpRuntimeState,
   createClaudeQwenRuntimeState,
-  jsonCliRuntimeEvents,
+  createGeminiRuntimeState,
+  finalOnlyRuntimeEvents,
+  geminiStreamJsonRuntimeEvents,
+  kimiStreamJsonRuntimeEvents,
+  mimoJsonRuntimeEvents,
+  openCodeJsonRuntimeEvents,
+  piJsonRuntimeEvents,
+  createPiRuntimeState,
 }

desktop/src/agents/cli/cli-runtime-event-sanitizer.cjs

@@ -22,16 +22,169 @@ const RUNTIME_EVENT_LIMITS = Object.freeze({
   delta: 4000,
 })
 
+function utf8ByteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8')
+}
+
 function redactChildSecrets(value, env) {
   let result = String(value || '')
-  for (const [name, secret] of Object.entries(env)) {
-    if (!/(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|AUTHORIZATION)/i.test(name)
-        || typeof secret !== 'string' || secret.length < 8) continue
+  for (const secret of childSecrets(env)) {
     result = result.split(secret).join('[redacted]')
   }
   return result
 }
 
+function childSecrets(env) {
+  const secrets = new Set()
+  for (const [name, value] of Object.entries(env || {})) {
+    if (typeof value !== 'string' || !value) continue
+    if (/(?:API[_-]?KEY|ACCESS[_-]?KEY|TOKEN|SECRET|PASSWORD|AUTHORIZATION)/i.test(name)
+        && utf8ByteLength(value) >= 8) secrets.add(value)
+    if (!/^(?:https?|all)_proxy$/i.test(name)) continue
+    if (value.includes('@')) secrets.add(value)
+    try {
+      const url = new URL(value)
+      if (!url.username && !url.password) continue
+      secrets.add(value)
+      secrets.add(url.href)
+      const userinfo = `${url.username}:${url.password}`
+      secrets.add(userinfo)
+      const decoded = decodeURIComponent(userinfo)
+      secrets.add(decoded)
+      secrets.add(Buffer.from(decoded).toString('base64'))
+      for (const part of [url.username, url.password]) {
+        if (utf8ByteLength(part) >= 8) secrets.add(part)
+        const literal = decodeURIComponent(part)
+        if (utf8ByteLength(literal) >= 8) secrets.add(literal)
+      }
+    } catch { /* malformed proxy URLs are diagnosed by the native runtime */ }
+  }
+  return [...secrets].sort((left, right) => right.length - left.length)
+}
+
+function assignmentNameVariants(parts) {
+  return parts.slice(1).reduce(
+    (names, part) => names.flatMap(name => ['', '_', '-'].map(separator => `${name}${separator}${part}`)),
+    [parts[0]],
+  )
+}
+
+const ASSIGNMENT_NAME_FRAGMENTS = [
+  ...assignmentNameVariants(['api', 'key']),
+  ...assignmentNameVariants(['access', 'key']),
+  ...assignmentNameVariants(['access', 'key', 'id']),
+  ...assignmentNameVariants(['secret', 'access', 'key']),
+  ...assignmentNameVariants(['access', 'token']),
+  ...assignmentNameVariants(['refresh', 'token']),
+  ...assignmentNameVariants(['auth', 'token']),
+  ...assignmentNameVariants(['database', 'url']),
+  ...assignmentNameVariants(['connection', 'string']),
+  ...assignmentNameVariants(['private', 'key']),
+  'dsn', 'token', 'secret', 'password', 'credential', 'authorization',
+]
+
+function tokenPrefixSuffixLength(value, token, requireBoundary = true, minimumLength = 1) {
+  const lowerValue = value.toLowerCase()
+  const lowerToken = token.toLowerCase()
+  for (let length = Math.min(value.length, token.length); length > 0; length -= 1) {
+    if (length < minimumLength) break
+    if (!lowerValue.endsWith(lowerToken.slice(0, length))) continue
+    const start = value.length - length
+    if (!requireBoundary || start === 0 || !/[A-Za-z0-9_]/.test(value[start - 1])) return length
+  }
+  return 0
+}
+
+function pathSuffixLength(value) {
+  const matches = [
+    value.match(/file:\/\/\/[^\s"'`<>|,;)}\]]+$/i),
+    value.match(/(?<![A-Za-z0-9:])(?:[A-Za-z]:[\\/]|\\\\)[^\s"'`<>|,;)}\]]+$/),
+    value.match(/(?<![\p{L}\p{N}:/])\/+[^\s"'`<>|,;)}\]]+$/u),
+  ]
+  return Math.max(...matches.map(match => match?.[0]?.length || 0))
+}
+
+function boundarySensitiveSuffixLength(value, secrets) {
+  let retained = 0
+  const retain = (length) => { retained = Math.max(retained, length || 0) }
+  // Keep a word boundary across chunks: a slash in the next chunk may be
+  // prose (云/端), not the start of an absolute filesystem path.
+  retain(value.match(/(?=[^\x00-\x7f])[\p{L}\p{N}]$/u)?.[0]?.length)
+  for (const secret of secrets) {
+    const limit = Math.min(value.length, secret.length - 1)
+    for (let length = limit; length > retained; length -= 1) {
+      if (value.endsWith(secret.slice(0, length))) {
+        retain(length)
+        break
+      }
+    }
+  }
+  retain(tokenPrefixSuffixLength(value, 'AKIA'))
+  retain(tokenPrefixSuffixLength(value, 'bearer'))
+  for (const name of ASSIGNMENT_NAME_FRAGMENTS) {
+    retain(tokenPrefixSuffixLength(value, name, false))
+  }
+  const pathLength = pathSuffixLength(value)
+  if (pathLength) retain(pathLength)
+  retain(value.match(/(?<![\p{L}\p{N}:/])\/+$/u)?.[0]?.length)
+
+  const matches = [
+    value.match(/\bAKIA[0-9A-Z]{0,15}$/),
+    value.match(/\bbearer\s+[A-Za-z0-9._~+\/-]*$/i),
+    value.match(/(["']?)(?:[A-Za-z0-9_.-]*(?:api[_-]?key|access[_-]?key(?:[_-]?id)?|secret[_-]?access[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|database[_-]?url|connection[_-]?string|dsn|token|secret|password|credential|authorization|private[_-]?key)[A-Za-z0-9_.-]*)\1\s*[:=]\s*(?:"[^"\r\n]*|'[^'\r\n]*'|\[[^\]\r\n]*\]|[^\s,;}\]]*)$/i),
+    value.match(/\b[A-Za-z][A-Za-z0-9+.-]*:\/{0,1}$/),
+    value.match(/\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s\/@]*$/),
+    value.match(/\bhttps?$/i),
+  ]
+  for (const match of matches) retain(match?.[0]?.length)
+  retain(value.match(/-----BEGIN [A-Z0-9 ]*$/i)?.[0]?.length)
+  const privateKey = value.match(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*$/i)
+  if (privateKey && !/-----END [A-Z0-9 ]*PRIVATE KEY-----\s*$/i.test(privateKey[0])) {
+    retain(privateKey[0].length)
+  }
+  return retained
+}
+
+function pendingAnswerDeltaIsSensitive(value, secrets) {
+  if (utf8ByteLength(value) >= 8 && secrets.some(secret => secret.startsWith(value))) return true
+  if (/\bAKIA[0-9A-Z]*$/.test(value)) return true
+  if (/\bbearer\s+[A-Za-z0-9._~+\/-]+$/i.test(value)) return true
+  if (/(["']?)(?:[A-Za-z0-9_.-]*(?:api[_-]?key|access[_-]?key(?:[_-]?id)?|secret[_-]?access[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|database[_-]?url|connection[_-]?string|dsn|token|secret|password|credential|authorization|private[_-]?key)[A-Za-z0-9_.-]*)\1\s*[:=]\s*[^\s,;}\]]*$/i.test(value)) return true
+  if (/\b[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s\/@:]+:[^\s\/@]*$/i.test(value)) return true
+  return /-----BEGIN [A-Z0-9 ]*$/i.test(value)
+    || /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*$/i.test(value)
+}
+
+function createAnswerDeltaRedactor(env) {
+  const secrets = childSecrets(env)
+  let pending = ''
+
+  return {
+    push(value) {
+      const combined = redactChildSecrets(pending + String(value || ''), env)
+      const retained = boundarySensitiveSuffixLength(combined, secrets)
+      pending = retained ? combined.slice(-retained) : ''
+      return sanitizeRuntimeEventText(
+        retained ? combined.slice(0, -retained) : combined,
+        env,
+        Number.MAX_SAFE_INTEGER,
+        false,
+        false,
+      )
+    },
+    flush(terminalText = '') {
+      if (!pending) return ''
+      const value = pending
+      pending = ''
+      const combined = value + String(terminalText || '')
+      if (redactChildSecrets(combined, env) !== combined) return ''
+      if (pendingAnswerDeltaIsSensitive(value, secrets)) return '[redacted]'
+      if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s\/@:]+(?:\/[^\s]*)?$/.test(value)) return value
+      return sanitizeRuntimeEventText(value, env, Number.MAX_SAFE_INTEGER, false, false)
+    },
+  }
+}
+
 function runtimeEventStatus(value, fallback = '') {
   const normalized = String(value || '').toLowerCase()
   const aliases = {
@@ -46,13 +199,17 @@ function runtimeEventStatus(value, fallback = '') {
   return RUNTIME_EVENT_STATUSES.has(status) ? status : fallback
 }
 
+function terminalAnswerStatus(status) {
+  return ['completed', 'failed', 'partial', 'stopped', 'timeout'].includes(status)
+}
+
 function sanitizeRuntimeEventText(value, childEnv, limit, singleLine = false, trim = true) {
   let text = stripAnsi(redactChildSecrets(value, childEnv))
     .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
     .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/gi, '[redacted private key]')
     .replace(/file:\/\/\/[^\s"'`<>|,;)}\]]+/gi, '[path]')
     .replace(/(?<![A-Za-z0-9:])(?:[A-Za-z]:[\\/]|\\\\)[^\s"'`<>|,;)}\]]+/g, '[path]')
-    .replace(/(?<![A-Za-z0-9:])\/(?!\/)[^\s"'`<>|,;)}\]]+/g, '[path]')
+    .replace(/(?<![\p{L}\p{N}:/])\/+[^\s"'`<>|,;)}\]]+/gu, '[path]')
     .replace(/(["']?)(?:[A-Za-z0-9_.-]*(?:api[_-]?key|access[_-]?key(?:[_-]?id)?|secret[_-]?access[_-]?key|access[_-]?token|refresh[_-]?token|auth[_-]?token|database[_-]?url|connection[_-]?string|dsn|token|secret|password|credential|authorization|private[_-]?key)[A-Za-z0-9_.-]*)\1\s*[:=]\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|\[[^\]\r\n]*\]|[^\s,;}\]]+)/gi, 'credential=[redacted]')
     .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[redacted]')
     .replace(/\bbearer\s+[A-Za-z0-9._~+\/-]+=*/gi, 'Bearer [redacted]')
@@ -66,7 +223,10 @@ function sanitizeRuntimeEventText(value, childEnv, limit, singleLine = false, tr
 function createRuntimeEventEmitter(options, childEnv) {
   const callback = typeof options.onEvent === 'function' ? options.onEvent : null
   const activity = typeof options.onActivity === 'function' ? options.onActivity : null
-  let emittedAnswerDelta = false
+  let deliveredAnswer = ''
+  let finalized = false
+  const openTools = new Map()
+  const answerDeltaRedactor = createAnswerDeltaRedactor(childEnv)
   const deliver = (event) => {
     if (!callback) return
     try {
@@ -74,6 +234,26 @@ function createRuntimeEventEmitter(options, childEnv) {
       if (pending && typeof pending.catch === 'function') pending.catch(() => {})
     } catch { /* runtime events are best-effort */ }
   }
+  const deliverAnswerDelta = (base, delta) => {
+    if (!delta) return false
+    const replace = base.replace === true
+    deliveredAnswer = replace ? delta : deliveredAnswer + delta
+    const eventBase = { ...base }
+    delete eventBase.replace
+    for (let offset = 0; offset < delta.length; offset += RUNTIME_EVENT_LIMITS.delta) {
+      deliver({
+        ...eventBase,
+        ...(replace && offset === 0 ? { replace: true } : {}),
+        delta: delta.slice(offset, offset + RUNTIME_EVENT_LIMITS.delta),
+      })
+    }
+    return true
+  }
+  const flushAnswerDelta = (
+    base = { type: 'answer_delta', status: 'completed' }, terminalText = '',
+  ) => {
+    return deliverAnswerDelta(base, answerDeltaRedactor.flush(terminalText))
+  }
   const emit = (input) => {
     try { activity?.() } catch { /* activity is best-effort */ }
     if (!callback || !input || !RUNTIME_EVENT_TYPES.has(input.type)) return
@@ -91,32 +271,68 @@ function createRuntimeEventEmitter(options, childEnv) {
       )
       if (text) base[field] = text
     }
+    if (base.id && input.type === 'tool_start') {
+      openTools.set(base.id, {
+        id: base.id,
+        ...(base.title ? { title: base.title } : {}),
+      })
+    } else if (base.id && input.type === 'tool_result_summary') {
+      openTools.delete(base.id)
+    }
     if (input.type !== 'answer_delta') {
       deliver(base)
       return
     }
-    const delta = sanitizeRuntimeEventText(
-      input.delta,
-      childEnv,
-      Number.MAX_SAFE_INTEGER,
-      false,
-      false,
-    )
-    if (!delta) return
-    emittedAnswerDelta = true
-    for (let offset = 0; offset < delta.length; offset += RUNTIME_EVENT_LIMITS.delta) {
+    const delta = answerDeltaRedactor.push(input.delta)
+    deliverAnswerDelta(base, terminalAnswerStatus(status) ? delta + answerDeltaRedactor.flush() : delta)
+  }
+  const finalize = ({ text = '', status = 'completed' } = {}) => {
+    if (finalized) return false
+    finalized = true
+    const answerStatus = runtimeEventStatus(status, 'failed')
+    const toolStatus = answerStatus === 'completed' ? 'partial' : answerStatus
+    for (const tool of openTools.values()) {
       deliver({
-        ...base,
-        delta: delta.slice(offset, offset + RUNTIME_EVENT_LIMITS.delta),
+        type: 'tool_result_summary',
+        id: tool.id,
+        status: toolStatus,
+        ...(tool.title ? { title: tool.title } : {}),
       })
     }
+    openTools.clear()
+    const flushedAnswerDelta = flushAnswerDelta(
+      { type: 'answer_delta', status: answerStatus },
+      text,
+    )
+    if (text) {
+      const finalAnswerRedactor = createAnswerDeltaRedactor(childEnv)
+      const finalAnswer = finalAnswerRedactor.push(text) + finalAnswerRedactor.flush()
+      if (!deliveredAnswer) {
+        deliverAnswerDelta({ type: 'answer_delta', status: answerStatus }, finalAnswer)
+      } else if (!flushedAnswerDelta && finalAnswer === deliveredAnswer) {
+        deliverAnswerDelta(
+          { type: 'answer_delta', status: answerStatus, replace: true },
+          finalAnswer,
+        )
+      } else if (finalAnswer.startsWith(deliveredAnswer)) {
+        deliverAnswerDelta(
+          { type: 'answer_delta', status: answerStatus },
+          finalAnswer.slice(deliveredAnswer.length),
+        )
+      } else {
+        deliverAnswerDelta(
+          { type: 'answer_delta', status: answerStatus, replace: true },
+          finalAnswer,
+        )
+      }
+    }
+    return true
   }
   return {
     emit,
-    emitFinalAnswer(text) {
-      if (!emittedAnswerDelta) {
-        emit({ type: 'answer_delta', status: 'completed', delta: text })
-      }
+    finalize,
+    emitFinalAnswer(text, outcome = 'completed') {
+      return finalize({ text, status: outcome })
     },
   }
 }

desktop/src/agents/cli/cli-runtime-events.cjs

@@ -13,10 +13,12 @@ const {
   parseMimoOutput,
   parseOpenCodeOutput,
   parseOpenCodeReviewOutput,
+  parsePiOutput,
   parseWorkBuddyOutput,
   readHermesFinalResponse,
   readHermesMessageWatermark,
   stripAnsi,
+  stripExactMeldworkPromptEcho,
   structuredCliError,
 } = require('./cli-output-parsers.cjs')
 const {
@@ -29,7 +31,6 @@ const {
   codexRuntimeEvents,
   createAcpRuntimeState,
   createClaudeQwenRuntimeState,
-  jsonCliRuntimeEvents,
 } = require('./cli-runtime-event-mappers.cjs')
 const { runtimeCommandSummary } = require('./cli-runtime-summaries.cjs')
 
@@ -45,7 +46,6 @@ module.exports = {
   createRuntimeEventEmitter,
   createStructuredOutputAccumulator,
   hermesSessionRef,
-  jsonCliRuntimeEvents,
   normalizeOpenClawOutput,
   parseClaudeQwenOutput,
   parseCodexOutput,
@@ -55,11 +55,13 @@ module.exports = {
   parseMimoOutput,
   parseOpenCodeOutput,
   parseOpenCodeReviewOutput,
+  parsePiOutput,
   parseWorkBuddyOutput,
   readHermesFinalResponse,
   readHermesMessageWatermark,
   redactChildSecrets,
   runtimeCommandSummary,
   stripAnsi,
+  stripExactMeldworkPromptEcho,
   structuredCliError,
 }

desktop/src/agents/cli/cli-runtime-summaries.cjs

@@ -89,163 +89,8 @@ function runtimeInputSummary(value) {
   }).join(', ')
 }
 
-function runtimeCommandTokens(value) {
-  const input = String(value || '')
-  const tokens = []
-  let word = ''
-  let quote = ''
-  let escaped = false
-  const pushWord = () => {
-    if (!word) return
-    tokens.push({ type: 'word', value: word })
-    word = ''
-  }
-  const pushOperator = (operator) => {
-    pushWord()
-    if (operator === ';' && tokens.at(-1)?.type === 'operator') return
-    tokens.push({ type: 'operator', value: operator })
-  }
-
-  for (let index = 0; index < input.length; index += 1) {
-    const char = input[index]
-    if (escaped) {
-      if (char !== '\n' && char !== '\r') word += char
-      escaped = false
-      continue
-    }
-    if (quote) {
-      if (char === quote) {
-        quote = ''
-        continue
-      }
-      if (char === '\\' && quote === '"' && index + 1 < input.length) {
-        index += 1
-        word += input[index]
-        continue
-      }
-      word += char
-      continue
-    }
-    if (char === '\\') {
-      escaped = true
-      continue
-    }
-    if (char === '"' || char === "'") {
-      quote = char
-      continue
-    }
-    if (char === '\r' || char === '\n') {
-      if (char === '\r' && input[index + 1] === '\n') index += 1
-      pushOperator(';')
-      continue
-    }
-    if (/\s/u.test(char)) {
-      pushWord()
-      continue
-    }
-    if (char === '&' && input[index + 1] === '&') {
-      pushOperator('&&')
-      index += 1
-      continue
-    }
-    if (char === '|') {
-      pushOperator(input[index + 1] === '|' ? '||' : '|')
-      if (input[index + 1] === '|') index += 1
-      continue
-    }
-    if (char === ';') {
-      pushOperator(';')
-      continue
-    }
-    if (char === '>' || char === '<') {
-      if (/^\d+$/u.test(word)) word = ''
-      else pushWord()
-      if (input[index + 1] === char) index += 1
-      tokens.push({ type: 'redirect' })
-      continue
-    }
-    word += char
-  }
-  pushWord()
-  return tokens
-}
-
-function unwrapRuntimeShellCommand(tokens) {
-  if (tokens.length !== 3 || tokens.some(token => token.type !== 'word')
-      || !['-c', '-lc'].includes(tokens[1].value)) return tokens
-  const rawShell = String(tokens[0].value || '')
-  const shell = rawShell.split(/[\\/]/u).at(-1).toLowerCase()
-  if (!['sh', 'bash', 'zsh'].includes(shell)) return tokens
-  const unwrapped = runtimeCommandTokens(tokens[2].value)
-  return unwrapped.length ? unwrapped : tokens
-}
-
-function runtimeCommandSummary(value) {
-  const tokens = unwrapRuntimeShellCommand(runtimeCommandTokens(value))
-  const segments = []
-  let connector = ''
-  let segment = []
-  let hideRedirectTarget = false
-  for (const token of tokens) {
-    if (token.type === 'operator') {
-      if (segment.length) segments.push({ connector, tokens: segment })
-      connector = token.value
-      segment = []
-      hideRedirectTarget = false
-      continue
-    }
-    if (token.type === 'redirect') {
-      hideRedirectTarget = true
-      continue
-    }
-    if (hideRedirectTarget) {
-      hideRedirectTarget = false
-      continue
-    }
-    if (token.type === 'word') segment.push(token.value)
-  }
-  if (segment.length) segments.push({ connector, tokens: segment })
-
-  const safeSubcommands = new Set([
-    'build', 'diff', 'exec', 'pack', 'run', 'show', 'status', 'test', 'typecheck',
-  ])
-  const summarizeSegment = (items) => {
-    let index = 0
-    if (items[index] === 'env') index += 1
-    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(items[index] || '')) index += 1
-    const rawVerb = String(items[index] || '')
-    const basename = rawVerb.split(/[\\/]/u).at(-1).replace(/\.(?:cmd|bat|exe)$/iu, '')
-    const verb = /^[A-Za-z0-9_.+-]{1,80}$/u.test(basename) ? basename : 'shell'
-    const remaining = items.slice(index + 1)
-    const subcommandName = String(remaining[0] || '').toLowerCase()
-    const subcommand = safeSubcommands.has(subcommandName) ? subcommandName : ''
-    const flags = []
-    let hiddenCount = 0
-    remaining.forEach((token, remainingIndex) => {
-      if (remainingIndex === 0 && subcommand) return
-      if (flags.length < 6 && /^(?:-[A-Za-z0-9]|--[A-Za-z0-9][A-Za-z0-9-]*)$/u.test(token)) {
-        flags.push(token)
-      } else {
-        hiddenCount += 1
-      }
-    })
-    return [
-      verb,
-      subcommand,
-      ...flags,
-      hiddenCount ? `(${hiddenCount} hidden argument${hiddenCount === 1 ? '' : 's'})` : '',
-    ].filter(Boolean).join(' ')
-  }
-
-  const visibleSegments = segments.slice(0, 3)
-  const summary = visibleSegments.map((item, index) => [
-    index ? item.connector : '',
-    summarizeSegment(item.tokens),
-  ].filter(Boolean).join(' ')).join(' ')
-  const omitted = Math.max(0, segments.length - visibleSegments.length)
-  return [summary || 'shell', omitted ? `(${omitted} more commands)` : '']
-    .filter(Boolean)
-    .join(' ')
+function runtimeCommandSummary(_value) {
+  return 'command'
 }
 
 function runtimeToolOperation(event) {

desktop/src/agents/cli/cli-turn-completion.cjs

@@ -0,0 +1,41 @@
+const { randomUUID } = require('node:crypto')
+
+// A contribution ends only on an explicit, invocation-specific signal from
+// the assistant. Tool output and acknowledgements cannot finish a turn.
+function createTurnCompletion() {
+  const marker = `[[MELDWORK_TURN_DONE:${randomUUID()}]]`
+  let text = ''
+  let delivered = 0
+  let completed = false
+  return {
+    instruction: `This is one scheduled contribution. Other participants cannot run until you return. Complete only the contribution requested for this invocation; do not poll or wait for their approvals. After your answer and any required collaboration receipt, output this exact signal on its own final line: ${marker}\nThe signal ends only your invocation, never the group task. Do not quote or explain it, and do not output it before all your tools have finished.`,
+    push(delta, toolsFinished = true) {
+      if (completed) return { delta: '', completed: true }
+      text += delta
+      const index = text.lastIndexOf(marker)
+      if (toolsFinished && index > 0 && text[index - 1] === '\n'
+          && /^(?:[ \t]*\r?\n|[ \t]*$)/.test(text.slice(index + marker.length))) {
+        const before = text.slice(0, index)
+        const fences = before.match(/^\s*(?:```|~~~)/gm) || []
+        if (fences.length % 2 === 0 && before.trim()) {
+          completed = true
+          const visible = before.slice(delivered)
+          text = before
+          delivered = text.length
+          return { delta: visible, completed: true }
+        }
+      }
+      let held = 0
+      for (let length = Math.min(marker.length, text.length); length > 0; length--) {
+        if (text.endsWith(marker.slice(0, length))) { held = length; break }
+      }
+      const end = text.length - held
+      const visible = text.slice(delivered, end)
+      delivered = end
+      return { delta: visible, completed: false }
+    },
+    get completed() { return completed },
+  }
+}
+
+module.exports = { createTurnCompletion }

desktop/src/agents/cli/mimo-native-config.cjs

@@ -0,0 +1,23 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const os = require('node:os')
+
+function mimoConfiguredProvider(options = {}) {
+  const env = options.env || process.env
+  const root = env.XDG_CONFIG_HOME || path.join(options.home || os.homedir(), '.config')
+  try {
+    const file = path.join(root, 'mimocode', 'mimocode.json')
+    if (fs.statSync(file).size > 2 * 1024 * 1024) return false
+    const config = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (typeof config.model !== 'string' || !config.model.includes('/')) return false
+    const provider = config.provider?.[config.model.split('/')[0]]
+    let key = provider?.options?.apiKey
+    if (typeof key !== 'string' || !key.trim()) return false
+    const reference = key.match(/^\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/)
+    if (reference) key = env[reference[1]]
+    else if (/^\{.*\}$/.test(key)) return false
+    return typeof key === 'string' && Boolean(key.trim())
+  } catch { return false }
+}
+
+module.exports = { mimoConfiguredProvider }

desktop/src/agents/cli/openclaw-runtime.cjs

@@ -1,10 +1,10 @@
 const crypto = require('node:crypto')
 const fs = require('node:fs')
 const path = require('node:path')
+const { isDeepStrictEqual } = require('node:util')
 
 const { atomicWritePrivateFile } = require('../../security/private-file.cjs')
 
-const MANAGED_OPENCLAW_PROVIDER_ID = 'roundrelay-desktop'
 const READ_ONLY_TOOLS = [
   'read', 'web_search', 'web_fetch', 'memory_search', 'memory_get', 'session_status',
 ]
@@ -36,11 +36,12 @@ const OPENCLAW_RUNTIME_PATH_ENV_KEYS = Object.freeze([
   'OPENCLAW_WORKSPACE_DIR',
 ])
 const OPENCLAW_RUNTIME_CREDENTIAL_KEYS = new Set([
-  'ROUNDRELAY_OPENCLAW_API_KEY',
-  'ROUNDRELAY_OPENCLAW_NATIVE_API_KEY',
+  'MELDWORK_OPENCLAW_NATIVE_API_KEY',
+  'OPENCLAW_GATEWAY_TOKEN',
 ])
 const issuedOpenClawRuntimeGuards = new WeakSet()
 const openClawRuntimeCredentialDigests = new WeakMap()
+const openClawRuntimeConfigs = new WeakMap()
 const OPENCLAW_ENV_SECRET_NAME = /^[A-Z][A-Z0-9_]{0,127}$/
 const OPENCLAW_SECRET_MARKERS = new Set([
   'secretref-managed',
@@ -88,7 +89,7 @@ function directoryIdentity(filename) {
   })
 }
 
-function fileIdentity(filename) {
+function readRuntimeConfigFile(filename) {
   const resolved = path.resolve(filename)
   const entry = fs.lstatSync(resolved)
   if (!entry.isFile() || entry.isSymbolicLink() || fs.realpathSync(resolved) !== resolved) {
@@ -98,14 +99,22 @@ function fileIdentity(filename) {
   const descriptor = fs.openSync(resolved, fs.constants.O_RDONLY | noFollow)
   try {
     const before = fs.fstatSync(descriptor)
-    if (!before.isFile() || !sameFilesystemIdentity(before, {
+    if (!before.isFile() || before.size > 256 * 1024 || !sameFilesystemIdentity(before, {
       dev: identityValue(entry.dev),
       ino: identityValue(entry.ino),
       birthtime: identityValue(entry.birthtimeMs),
     })) {
       throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
     }
-    const contents = fs.readFileSync(descriptor)
+    const buffer = Buffer.alloc(256 * 1024 + 1)
+    let length = 0
+    while (length < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, length, buffer.length - length, null)
+      if (!count) break
+      length += count
+    }
+    if (length === buffer.length) throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
+    const contents = buffer.subarray(0, length)
     const after = fs.fstatSync(descriptor)
     const current = fs.lstatSync(resolved)
     if (!sameFilesystemIdentity(after, {
@@ -120,7 +129,7 @@ function fileIdentity(filename) {
         }) || fs.realpathSync(resolved) !== resolved) {
       throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
     }
-    return Object.freeze({
+    const identity = Object.freeze({
       path: resolved,
       dev: identityValue(before.dev),
       ino: identityValue(before.ino),
@@ -129,11 +138,16 @@ function fileIdentity(filename) {
       size: contents.length,
       digest: crypto.createHash('sha256').update(contents).digest('hex'),
     })
+    return { identity, contents: contents.toString('utf8') }
   } finally {
     fs.closeSync(descriptor)
   }
 }
 
+function fileIdentity(filename) {
+  return readRuntimeConfigFile(filename).identity
+}
+
 function validateDirectoryIdentities(identities) {
   for (const expected of identities) {
     const current = directoryIdentity(expected.path)
@@ -157,26 +171,7 @@ function validateFileIdentity(expected) {
   }
 }
 
-function normalizeProvider(input) {
-  const apiKey = typeof input?.OPENAI_API_KEY === 'string' ? input.OPENAI_API_KEY.trim() : ''
-  const baseUrl = String(input?.OPENAI_BASE_URL || '')
-    .trim()
-    .replace(/\/+$/, '')
-    .replace(/\/chat\/completions$/i, '')
-  const model = String(input?.OPENAI_MODEL || '').trim()
-  let parsed
-  try { parsed = new URL(baseUrl) } catch { throw new Error('OPENCLAW_PROVIDER_INVALID') }
-  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname)
-  if (!apiKey || apiKey.length > 8192 || isOpenClawSecretReference(apiKey)
-      || !model || model.length > 120
-      || (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback))
-      || parsed.username || parsed.password || parsed.search || parsed.hash) {
-    throw new Error('OPENCLAW_PROVIDER_INVALID')
-  }
-  return { apiKey, baseUrl, model }
-}
-
-function runtimePaths({ storageRoot, workdir, sessionRef, configName }) {
+function runtimePaths({ storageRoot, workdir, sessionRef, configName, runtimeVersion }) {
   if (!path.isAbsolute(storageRoot) || !path.isAbsolute(workdir)) {
     throw new Error('OPENCLAW_RUNTIME_INVALID_SCOPE')
   }
@@ -188,8 +183,15 @@ function runtimePaths({ storageRoot, workdir, sessionRef, configName }) {
     throw new Error('OPENCLAW_RUNTIME_INVALID_SCOPE')
   }
   const resolvedWorkdir = path.resolve(workdir)
+  // The managed scope is keyed by session, workspace, and CLI version. OpenClaw
+  // refuses to start on state written by an older CLI ("Legacy workspace setup
+  // state requires migration"), so a version-scoped directory gives an upgraded
+  // CLI a fresh isolated scope instead of a guaranteed startup failure.
+  const versionSegment = String(runtimeVersion || '').trim()
   const scope = crypto.createHash('sha256')
-    .update(`${sessionRef || 'configure'}\0${resolvedWorkdir}`)
+    .update(versionSegment
+      ? `${sessionRef || 'configure'}\0${resolvedWorkdir}\0${versionSegment}`
+      : `${sessionRef || 'configure'}\0${resolvedWorkdir}`)
     .digest('hex')
     .slice(0, 24)
   const runtimeRoot = path.join(resolvedStorageRoot, 'openclaw-managed', scope)
@@ -239,7 +241,16 @@ function toolPolicy(allowWrite) {
   }
 }
 
-function writeRuntimeConfig(runtime, config, credentialKey, credentialValue) {
+function writeRuntimeConfig(runtime, config, credentials, credentialKey) {
+  const credentialEntries = Object.entries(credentials || {})
+  if (!credentialEntries.length
+      || credentialEntries.some(([key, value]) => (
+        !OPENCLAW_RUNTIME_CREDENTIAL_KEYS.has(key)
+          || typeof value !== 'string' || !value
+      ))
+      || !credentials[credentialKey]) {
+    throw new Error('OPENCLAW_RUNTIME_CREDENTIAL_SCOPE_INVALID')
+  }
   const contents = `${JSON.stringify(config, null, 2)}\n`
   validateDirectoryIdentities(runtime.directoryIdentities)
   atomicWritePrivateFile(runtime.configPath, contents)
@@ -255,41 +266,155 @@ function writeRuntimeConfig(runtime, config, credentialKey, credentialValue) {
       OPENCLAW_WORKSPACE_DIR: runtime.resolvedWorkdir,
     }),
     credentialKey,
+    credentialKeys: Object.freeze(credentialEntries.map(([key]) => key)),
   })
   issuedOpenClawRuntimeGuards.add(guard)
-  openClawRuntimeCredentialDigests.set(
-    guard,
-    crypto.createHash('sha256').update(credentialValue).digest('hex'),
-  )
+  openClawRuntimeConfigs.set(guard, contents)
+  openClawRuntimeCredentialDigests.set(guard, Object.freeze(Object.fromEntries(
+    credentialEntries.map(([key, value]) => [
+      key,
+      crypto.createHash('sha256').update(value).digest('hex'),
+    ]),
+  )))
   return guard
 }
 
-function validateOpenClawRuntimeGuard(guard, env = {}) {
-  const credentialDigest = guard && typeof guard === 'object'
+function validateRuntimeScope(guard, env = {}) {
+  const credentialDigests = guard && typeof guard === 'object'
     ? openClawRuntimeCredentialDigests.get(guard)
     : undefined
   if (!guard || typeof guard !== 'object' || !issuedOpenClawRuntimeGuards.has(guard)
       || !Array.isArray(guard.directories)
       || !guard.config || !guard.paths
       || !OPENCLAW_RUNTIME_CREDENTIAL_KEYS.has(guard.credentialKey)
-      || typeof credentialDigest !== 'string') {
+      || !Array.isArray(guard.credentialKeys) || !guard.credentialKeys.length
+      || guard.credentialKeys.some(key => !OPENCLAW_RUNTIME_CREDENTIAL_KEYS.has(key))
+      || !credentialDigests || typeof credentialDigests !== 'object') {
     throw new Error('OPENCLAW_RUNTIME_GUARD_REQUIRED')
   }
   for (const key of OPENCLAW_RUNTIME_PATH_ENV_KEYS) {
     if (env[key] !== guard.paths[key]) throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
   }
-  if (typeof env[guard.credentialKey] !== 'string' || !env[guard.credentialKey]) {
-    throw new Error('OPENCLAW_RUNTIME_CREDENTIAL_SCOPE_INVALID')
-  }
-  if (crypto.createHash('sha256').update(env[guard.credentialKey]).digest('hex')
-      !== credentialDigest) {
-    throw new Error('OPENCLAW_RUNTIME_CREDENTIAL_SCOPE_INVALID')
+  for (const key of guard.credentialKeys) {
+    if (typeof env[key] !== 'string' || !env[key]
+        || crypto.createHash('sha256').update(env[key]).digest('hex')
+          !== credentialDigests[key]) {
+      throw new Error('OPENCLAW_RUNTIME_CREDENTIAL_SCOPE_INVALID')
+    }
   }
   validateDirectoryIdentities(guard.directories)
+}
+
+function validateOpenClawRuntimeGuard(guard, env = {}) {
+  validateRuntimeScope(guard, env)
   validateFileIdentity(guard.config)
   return true
 }
 
+function comparableMigratedConfig(config) {
+  // OpenClaw materializes the implicit main agent and stamps migrations at startup.
+  const result = JSON.parse(JSON.stringify(config))
+  const meta = result.meta
+  if (meta && typeof meta === 'object' && !Array.isArray(meta)
+      && Object.keys(meta).every(key => ['migrations', 'lastTouchedVersion', 'lastTouchedAt'].includes(key))
+      && (meta.lastTouchedVersion === undefined || /^\d{4}\.\d{1,2}\.\d{1,2}(?:[-+.][\w.-]+)?$/.test(meta.lastTouchedVersion))
+      && (meta.lastTouchedAt === undefined || (typeof meta.lastTouchedAt === 'string' && Number.isFinite(Date.parse(meta.lastTouchedAt))))
+      && (meta.migrations === undefined || isDeepStrictEqual(meta.migrations, { modelPolicyAllowlist: true }))) {
+    delete result.meta
+  }
+  if (isDeepStrictEqual(result.agents?.entries, { main: {} })) delete result.agents.entries
+  if (isDeepStrictEqual(result.discovery?.wideArea, { enabled: false })) {
+    result.discovery.wideArea = {}
+  }
+  return result
+}
+
+function refreshOpenClawRuntimeAfterStartup(options) {
+  const guard = options?.openClawRuntimeGuard
+  const env = options?.env || {}
+  validateRuntimeScope(guard, env)
+  const { identity: config, contents } = readRuntimeConfigFile(guard.config.path)
+  if (process.platform !== 'win32' && (config.mode & 0o777) !== 0o600) {
+    throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
+  }
+  validateDirectoryIdentities(guard.directories)
+  validateFileIdentity(config)
+  let equivalent = false
+  try {
+    equivalent = isDeepStrictEqual(
+      comparableMigratedConfig(JSON.parse(openClawRuntimeConfigs.get(guard))),
+      comparableMigratedConfig(JSON.parse(contents)),
+    )
+  } catch { /* malformed config is rejected below */ }
+  if (!equivalent) throw new Error('OPENCLAW_RUNTIME_UNSAFE_PATH')
+  const refreshed = Object.freeze({ ...guard, config })
+  issuedOpenClawRuntimeGuards.add(refreshed)
+  openClawRuntimeConfigs.set(refreshed, contents)
+  openClawRuntimeCredentialDigests.set(refreshed, openClawRuntimeCredentialDigests.get(guard))
+  return { ...options, openClawRuntimeGuard: refreshed }
+}
+
+function configureOpenClawGatewayRuntime(options, port) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('OPENCLAW_GATEWAY_PORT_INVALID')
+  }
+  const guard = options?.openClawRuntimeGuard
+  const env = options?.env || {}
+  validateOpenClawRuntimeGuard(guard, env)
+
+  const config = JSON.parse(openClawRuntimeConfigs.get(guard))
+  const gatewayCredentialKey = 'OPENCLAW_GATEWAY_TOKEN'
+  const nextConfig = {
+    ...config,
+    logging: {
+      ...(config.logging || {}),
+      file: path.join(guard.paths.OPENCLAW_STATE_DIR, 'gateway.log'),
+    },
+    update: {
+      ...(config.update || {}),
+      checkOnStart: false,
+      auto: { ...(config.update?.auto || {}), enabled: false },
+    },
+    discovery: {
+      ...(config.discovery || {}),
+      wideArea: { ...(config.discovery?.wideArea || {}), enabled: false },
+      mdns: { ...(config.discovery?.mdns || {}), mode: 'off' },
+    },
+    gateway: {
+      ...(config.gateway || {}),
+      port,
+      mode: 'local',
+      bind: 'loopback',
+      controlUi: { ...(config.gateway?.controlUi || {}), enabled: false },
+      auth: {
+        mode: 'token',
+        token: { source: 'env', provider: 'default', id: gatewayCredentialKey },
+      },
+      tailscale: { ...(config.gateway?.tailscale || {}), mode: 'off' },
+    },
+  }
+  const credentials = Object.fromEntries(
+    guard.credentialKeys.map(key => [key, env[key]]),
+  )
+  const runtime = {
+    resolvedWorkdir: guard.paths.OPENCLAW_WORKSPACE_DIR,
+    home: guard.paths.OPENCLAW_HOME,
+    state: guard.paths.OPENCLAW_STATE_DIR,
+    configPath: guard.paths.OPENCLAW_CONFIG_PATH,
+    directoryIdentities: guard.directories,
+  }
+  return {
+    ...options,
+    env: { ...env },
+    openClawRuntimeGuard: writeRuntimeConfig(
+      runtime,
+      nextConfig,
+      credentials,
+      guard.credentialKey,
+    ),
+  }
+}
+
 function normalizedNativeModel(input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null
   const id = String(input.id || '').trim()
@@ -319,59 +444,8 @@ function normalizedNativeModel(input) {
   return model
 }
 
-function managedOpenClawOptions({
-  storageRoot, workdir, sessionRef = '', allowWrite = false, provider,
-}) {
-  const normalized = normalizeProvider(provider)
-  const configName = allowWrite
-    ? 'openclaw.provider.workspace-write.json'
-    : 'openclaw.provider.read-only.json'
-  const runtime = runtimePaths({
-    storageRoot, workdir, sessionRef, configName,
-  })
-  const { resolvedWorkdir, home, state, configPath } = runtime
-
-  const modelRef = `${MANAGED_OPENCLAW_PROVIDER_ID}/${normalized.model}`
-  const config = {
-    agents: {
-      defaults: {
-        workspace: resolvedWorkdir,
-        model: { primary: modelRef },
-        skipBootstrap: true,
-      },
-    },
-    models: {
-      mode: 'replace',
-      providers: {
-        [MANAGED_OPENCLAW_PROVIDER_ID]: {
-          baseUrl: normalized.baseUrl,
-          apiKey: {
-            source: 'env', provider: 'default', id: 'ROUNDRELAY_OPENCLAW_API_KEY',
-          },
-          api: 'openai-completions',
-          models: [{ id: normalized.model, name: normalized.model, input: ['text'] }],
-        },
-      },
-    },
-    tools: toolPolicy(allowWrite),
-  }
-  const credentialKey = 'ROUNDRELAY_OPENCLAW_API_KEY'
-  const openClawRuntimeGuard = writeRuntimeConfig(runtime, config, credentialKey, normalized.apiKey)
-
-  return {
-    openClawRuntimeGuard,
-    env: {
-      OPENCLAW_HOME: home,
-      OPENCLAW_STATE_DIR: state,
-      OPENCLAW_CONFIG_PATH: configPath,
-      OPENCLAW_WORKSPACE_DIR: resolvedWorkdir,
-      [credentialKey]: normalized.apiKey,
-    },
-  }
-}
-
 function nativeOpenClawOptions({
-  storageRoot, workdir, sessionRef = '', allowWrite = false, runtime,
+  storageRoot, workdir, sessionRef = '', allowWrite = false, runtime, openclawVersion,
 }) {
   const modelRef = String(runtime?.model || '').trim()
   const provider = runtime?.provider
@@ -403,10 +477,12 @@ function nativeOpenClawOptions({
     ? 'openclaw.native.workspace-write.json'
     : 'openclaw.native.read-only.json'
   const runtimePathsResult = runtimePaths({
-    storageRoot, workdir, sessionRef, configName,
+    storageRoot, workdir, sessionRef, configName, runtimeVersion: openclawVersion,
   })
   const { resolvedWorkdir, home, state, configPath } = runtimePathsResult
   const modelConfig = { primary: modelRef }
+  const gatewayCredentialKey = 'OPENCLAW_GATEWAY_TOKEN'
+  const gatewayToken = crypto.randomBytes(32).toString('base64url')
   const config = {
     agents: {
       defaults: {
@@ -421,7 +497,7 @@ function nativeOpenClawOptions({
         [providerId]: {
           baseUrl: baseUrl.replace(/\/+$/, ''),
           apiKey: {
-            source: 'env', provider: 'default', id: 'ROUNDRELAY_OPENCLAW_NATIVE_API_KEY',
+            source: 'env', provider: 'default', id: 'MELDWORK_OPENCLAW_NATIVE_API_KEY',
           },
           api,
           models: [model],
@@ -429,10 +505,22 @@ function nativeOpenClawOptions({
       },
     },
     tools: toolPolicy(allowWrite),
+    gateway: {
+      mode: 'local',
+      bind: 'loopback',
+      auth: {
+        mode: 'token',
+        token: { source: 'env', provider: 'default', id: gatewayCredentialKey },
+      },
+      controlUi: { enabled: false },
+    },
   }
-  const credentialKey = 'ROUNDRELAY_OPENCLAW_NATIVE_API_KEY'
+  const credentialKey = 'MELDWORK_OPENCLAW_NATIVE_API_KEY'
   const openClawRuntimeGuard = writeRuntimeConfig(
-    runtimePathsResult, config, credentialKey, apiKey,
+    runtimePathsResult,
+    config,
+    { [credentialKey]: apiKey, [gatewayCredentialKey]: gatewayToken },
+    credentialKey,
   )
   return {
     openClawRuntimeGuard,
@@ -442,13 +530,15 @@ function nativeOpenClawOptions({
       OPENCLAW_CONFIG_PATH: configPath,
       OPENCLAW_WORKSPACE_DIR: resolvedWorkdir,
       [credentialKey]: apiKey,
+      [gatewayCredentialKey]: gatewayToken,
     },
   }
 }
 
 module.exports = {
+  configureOpenClawGatewayRuntime,
   isOpenClawSecretReference,
-  managedOpenClawOptions,
   nativeOpenClawOptions,
+  refreshOpenClawRuntimeAfterStartup,
   validateOpenClawRuntimeGuard,
 }

desktop/src/agents/cli/workbuddy-runtime.cjs

@@ -0,0 +1,89 @@
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { launchEnvironment } = require('./cli-discovery.cjs')
+
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,119}$/
+
+function workBuddyModels(options = {}) {
+  const env = options.env || process.env
+  const root = env.CODEBUDDY_CONFIG_DIR || path.join(options.home || os.homedir(), '.workbuddy')
+  try {
+    const filename = path.join(root, 'models.json')
+    const stat = fs.statSync(filename)
+    if (!stat.isFile() || stat.size > 2 * 1024 * 1024) return []
+    const value = JSON.parse(fs.readFileSync(filename, 'utf8'))
+    const models = Array.isArray(value) ? value : value.models
+    return (Array.isArray(models) ? models : []).filter(model => (
+      typeof model?.id === 'string' && MODEL_ID.test(model.id)
+      && typeof model.apiKey === 'string' && model.apiKey.trim()
+      && model.supportsToolCall === true && validUrl(model.url)
+    )).slice(0, 64)
+  } catch { return [] }
+}
+
+function validUrl(value) {
+  try {
+    const url = new URL(value)
+    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
+  } catch { return false }
+}
+
+function workBuddySettings(options = {}) {
+  return {
+    modelId: options.modelId || '',
+    models: workBuddyModels(options).map(model => ({
+      id: model.id, name: String(model.name || model.id).slice(0, 120),
+    })),
+  }
+}
+
+function workBuddyEnvironment(options = {}) {
+  if (!options.modelId) return {}
+  const model = workBuddyModels(options).find(model => model.id === options.modelId)
+  if (!model) throw new Error('LOCAL_WORKBUDDY_MODEL_UNAVAILABLE')
+  // Use the CLI's supported provider settings, without copying desktop account
+  // tokens or attempting to unlock its host-managed encrypted credential store.
+  return {
+    CODEBUDDY_CONFIG_DIR: (options.env || process.env).CODEBUDDY_CONFIG_DIR
+      || path.join(options.home || os.homedir(), '.workbuddy'),
+    CODEBUDDY_MODEL: `custom-local:${model.id}`,
+    CODEBUDDY_API_KEY: model.apiKey,
+    CODEBUDDY_BASE_URL: model.url,
+  }
+}
+
+function workBuddyCredentialState(options = {}) {
+  if (options.modelId) {
+    try {
+      workBuddyEnvironment(options)
+      return { state: 'ready', source: 'native-credential' }
+    } catch { return { state: 'unknown', source: 'workbuddy-model-unavailable' } }
+  }
+  const env = options.env || process.env
+  if (env.CODEBUDDY_API_KEY?.trim() || env.CODEBUDDY_AUTH_TOKEN?.trim()) {
+    return { state: 'ready', source: 'native-credential' }
+  }
+  // A models.json entry is not a selected provider. The desktop app's shared
+  // encrypted login also cannot be decoded by its standalone lite CLI.
+  if (launchEnvironment('workbuddy', options.executable, options).CODEBUDDY_FORCE_LITE_WB_BUNDLE !== '1') {
+    return { state: 'unknown', source: 'unverified' }
+  }
+  const home = options.home || os.homedir()
+  const platform = options.platform || process.platform
+  const root = platform === 'darwin' ? path.join(home, 'Library', 'Application Support')
+    : platform === 'win32' ? path.join(home, 'AppData', 'Local')
+      : path.join(home, '.local', 'share')
+  try {
+    const filename = path.join(root, 'CodeBuddyExtension', 'Data', 'Public', 'auth', 'workbuddy-desktop.info')
+    if (fs.statSync(filename).size <= 2 * 1024 * 1024) {
+      const auth = JSON.parse(fs.readFileSync(filename, 'utf8')).auth
+      if (auth?.accessToken && typeof auth.accessToken === 'object') {
+        return { state: 'unknown', source: 'workbuddy-desktop-locked' }
+      }
+    }
+  } catch { /* native CLI may still have an independent login */ }
+  return { state: 'unknown', source: 'unverified' }
+}
+
+module.exports = { workBuddyCredentialState, workBuddyEnvironment, workBuddySettings }

desktop/src/agents/cloud/cloud-agent-bridge-server.cjs

@@ -0,0 +1,276 @@
+const fs = require('node:fs')
+const http = require('node:http')
+const os = require('node:os')
+const path = require('node:path')
+const { spawn, spawnSync } = require('node:child_process')
+
+const requestedPort = Number(process.env.MELDWORK_AGENT_BRIDGE_PORT || 8765)
+const PORT = Number.isInteger(requestedPort) && requestedPort >= 1024 && requestedPort <= 65535
+  ? requestedPort
+  : 8765
+const MAX_REQUEST_BYTES = 4 * 1024 * 1024
+const MAX_RESPONSE_BYTES = 256 * 1024
+const MAX_SKILLS = 64
+const PUBLIC_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/
+
+const AGENT_DEFINITIONS = Object.freeze([
+  {
+    id: 'codex', label: 'Codex',
+    description: 'Codex CLI exposed through an SSH-local Bridge.',
+    auth(command) { return command('codex', ['login', 'status']).status === 0 },
+  },
+  {
+    id: 'hermes', label: 'Hermes',
+    description: 'Hermes Agent exposed through an SSH-local Bridge.',
+    auth() { return true },
+  },
+  {
+    id: 'claude', label: 'Claude Code',
+    description: 'Claude Code exposed through an SSH-local Bridge.',
+    auth(command) {
+      const result = command('claude', ['auth', 'status'])
+      if (result.status !== 0) return false
+      try { return JSON.parse(String(result.stdout || '')).loggedIn === true } catch { return false }
+    },
+  },
+])
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) })
+  res.end(payload)
+}
+
+function versionFrom(value) {
+  return String(value || '').match(/(?:^|[^0-9])v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)?.[1] || ''
+}
+
+function commandResult(spawnSyncFn, command, args) {
+  const result = spawnSyncFn(command, args, { encoding: 'utf8', timeout: 5000 }) || {}
+  return {
+    status: Number.isInteger(result.status) ? result.status : 1,
+    stdout: String(result.stdout || ''),
+  }
+}
+
+function listSkills(kind, options = {}) {
+  const readdirSync = options.readdirSync || fs.readdirSync
+  const home = options.home || os.homedir()
+  const roots = {
+    codex: [path.join(home, '.codex', 'skills'), path.join(home, '.agents', 'skills')],
+    hermes: [path.join(home, '.hermes', 'skills'), path.join(home, '.agents', 'skills')],
+    claude: [path.join(home, '.claude', 'skills'), path.join(home, '.agents', 'skills')],
+  }[kind] || []
+  const names = new Set()
+  for (const root of roots) {
+    let entries = []
+    try { entries = readdirSync(root, { withFileTypes: true }) } catch { continue }
+    for (const entry of entries) {
+      if (names.size >= MAX_SKILLS) break
+      if ((entry.isDirectory?.() || entry.isSymbolicLink?.()) && PUBLIC_NAME.test(entry.name)) names.add(entry.name)
+    }
+  }
+  return [...names].sort().map(name => ({ namespace: kind, slug: name, name }))
+}
+
+function discoverAgents(options = {}) {
+  const spawnSyncFn = options.spawnSync || spawnSync
+  const listSkillsFn = options.listSkills || (kind => listSkills(kind))
+  const command = (name, args) => commandResult(spawnSyncFn, name, args)
+  const agents = []
+  for (const definition of AGENT_DEFINITIONS) {
+    const versionResult = command(definition.id, ['--version'])
+    const version = versionResult.status === 0 ? versionFrom(versionResult.stdout) : ''
+    if (!version) continue
+    const available = definition.auth(command)
+    agents.push({
+      id: definition.id,
+      sourceKind: definition.id,
+      label: definition.label,
+      version,
+      description: definition.description,
+      domains: ['general'],
+      inputTypes: ['text'],
+      permissionModes: ['read-only'],
+      available,
+      credentialState: available ? 'ready' : 'missing',
+      skills: listSkillsFn(definition.id),
+      session: {
+        supported: true,
+        resume: true,
+        cancel: true,
+        checkpoint: false,
+      },
+    })
+  }
+  return agents
+}
+
+function invocationFor(agentId, prompt, sessionRef = '') {
+  if (agentId === 'codex') {
+    return {
+      command: 'codex',
+      args: sessionRef
+        ? ['exec', 'resume', '--json', '--skip-git-repo-check', '--sandbox', 'read-only', sessionRef, '-']
+        : ['exec', '--json', '--skip-git-repo-check', '--sandbox', 'read-only', '-'],
+      input: prompt,
+    }
+  }
+  if (agentId === 'hermes') {
+    return {
+      command: 'hermes',
+      args: ['chat', '--quiet', ...(sessionRef ? ['--resume', sessionRef] : []), '--query', prompt],
+      input: '',
+    }
+  }
+  if (agentId === 'claude') {
+    return {
+      command: 'claude',
+      args: [
+        '--print', '--output-format', 'json', '--permission-mode', 'plan',
+        ...(sessionRef ? ['--resume', sessionRef] : []), prompt,
+      ],
+      input: '',
+    }
+  }
+  throw new Error('REMOTE_AGENT_UNSUPPORTED')
+}
+
+function parseAgentOutput(agentId, stdout) {
+  if (agentId === 'codex') {
+    const messages = []
+    let sessionRef = ''
+    for (const line of String(stdout || '').split(/\r?\n/)) {
+      try {
+        const event = JSON.parse(line)
+        if (event.type === 'thread.started' && typeof event.thread_id === 'string') sessionRef = event.thread_id
+        if (event.type === 'item.completed' && event.item?.type === 'agent_message'
+            && typeof event.item.text === 'string') messages.push(event.item.text)
+      } catch { /* ignore non-JSON diagnostics */ }
+    }
+    const text = messages.join('\n').trim()
+    return text ? { text, sessionRef, outcome: 'completed' } : null
+  }
+  if (agentId === 'hermes') {
+    const lines = String(stdout || '').split(/\r?\n/)
+    let sessionRef = ''
+    const text = lines.filter((line) => {
+      const match = line.match(/^session_id:\s*(\S+)\s*$/)
+      if (match) {
+        sessionRef = match[1]
+        return false
+      }
+      return true
+    }).join('\n').trim()
+    return text ? { text, sessionRef, outcome: 'completed' } : null
+  }
+  if (agentId === 'claude') {
+    let result
+    try { result = JSON.parse(String(stdout || '')) } catch { return null }
+    if (result?.is_error === true || typeof result?.result !== 'string' || !result.result.trim()) return null
+    return { text: result.result.trim(), sessionRef: String(result.session_id || ''), outcome: 'completed' }
+  }
+  return null
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.on('data', chunk => {
+      body += chunk.toString('utf8')
+      if (Buffer.byteLength(body) > MAX_REQUEST_BYTES) reject(new Error('request too large'))
+    })
+    req.once('end', () => resolve(body))
+    req.once('error', reject)
+  })
+}
+
+function parentSessionDetached(parentPid = process.ppid, readFileSync = fs.readFileSync) {
+  if (!Number.isInteger(parentPid) || parentPid <= 1 || process.ppid === 1) return true
+  try {
+    const stat = String(readFileSync(`/proc/${parentPid}/stat`, 'utf8'))
+    const match = stat.match(/^\d+\s+\(.+\)\s+\S+\s+(\d+)\s/)
+    return match ? Number(match[1]) === 1 : false
+  } catch {
+    return true
+  }
+}
+
+function runAgent(agentId, prompt, sessionRef = '') {
+  return new Promise(resolve => {
+    let invocation
+    try { invocation = invocationFor(agentId, prompt, sessionRef) } catch {
+      resolve({ outcome: 'failed', failure: { code: 'REMOTE_AGENT_UNSUPPORTED' } })
+      return
+    }
+    const child = spawn(invocation.command, invocation.args, {
+      stdio: ['pipe', 'pipe', 'pipe'], cwd: process.env.HOME || undefined,
+    })
+    let stdout = ''
+    child.stdout.on('data', chunk => {
+      stdout += chunk.toString('utf8')
+      if (Buffer.byteLength(stdout) > MAX_RESPONSE_BYTES) child.kill('SIGTERM')
+    })
+    child.stderr.resume()
+    child.once('error', () => resolve({ outcome: 'failed', failure: { code: 'REMOTE_AGENT_UNAVAILABLE' } }))
+    child.once('close', code => {
+      if (code !== 0) return resolve({ outcome: 'failed', failure: { code: 'REMOTE_AGENT_FAILED' } })
+      resolve(parseAgentOutput(agentId, stdout)
+        || { outcome: 'failed', failure: { code: 'REMOTE_AGENT_RESPONSE_INVALID' } })
+    })
+    child.stdin.end(invocation.input)
+  })
+}
+
+function createServer() {
+  return http.createServer(async (req, res) => {
+    if (req.method === 'GET' && req.url === '/.well-known/meldwork-agent-bridge') {
+      return json(res, 200, {
+        protocol: 'meldwork-agent-bridge', version: 1,
+        server: { id: 'ssh-session', label: 'SSH Agent Server' },
+        agents: discoverAgents(),
+      })
+    }
+    const match = req.method === 'POST' && req.url?.match(/^\/v1\/agents\/([A-Za-z0-9._-]+)\/runs$/)
+    if (!match) return json(res, 404, { error: 'NOT_FOUND' })
+    try {
+      const body = JSON.parse(await readBody(req))
+      const agent = discoverAgents().find(item => item.id === match[1] && item.available)
+      if (!agent || typeof body.prompt !== 'string' || body.permissionMode !== 'read-only') {
+        return json(res, 400, { error: 'REQUEST_INVALID' })
+      }
+      return json(res, 200, await runAgent(agent.id, body.prompt, body.sessionRef || ''))
+    } catch {
+      return json(res, 400, { error: 'REQUEST_INVALID' })
+    }
+  })
+}
+
+function startServer() {
+  const server = createServer()
+  const parentPid = process.ppid
+  const parentTimer = setInterval(() => {
+    if (!parentSessionDetached(parentPid)) return
+    server.close(() => process.exit(0))
+  }, 1000)
+  server.once('close', () => clearInterval(parentTimer))
+  server.listen(PORT, '127.0.0.1', () => {
+    process.stdout.write(`MELDWORK_AGENT_BRIDGE_READY ${PORT}\n`)
+  })
+  process.once('SIGTERM', () => server.close(() => process.exit(0)))
+  process.once('SIGINT', () => server.close(() => process.exit(0)))
+  return server
+}
+
+if (require.main === module || !require.main) startServer()
+
+module.exports = {
+  createServer,
+  discoverAgents,
+  invocationFor,
+  listSkills,
+  parentSessionDetached,
+  parseAgentOutput,
+  runAgent,
+  startServer,
+}

desktop/src/agents/cloud/cloud-agent-bridge.cjs

@@ -0,0 +1,719 @@
+const crypto = require('node:crypto')
+const { spawn } = require('node:child_process')
+const fs = require('node:fs')
+const net = require('node:net')
+
+const { canonicalJson } = require('../../collaboration/outcome-records.cjs')
+const { atomicWritePrivateFile } = require('../../security/private-file.cjs')
+const { createAgentConnectorManifest } = require('../connectors/agent-connector-manifest.cjs')
+
+const BRIDGE_PROTOCOL = 'meldwork-agent-bridge'
+const BRIDGE_VERSION = 1
+const BRIDGE_RECIPE_ID = 'external.cloud-agent-bridge'
+const SSH_RECIPE_ID = 'external.cloud-agent-ssh'
+const BRIDGE_UPSTREAM_ID = 'meldwork-cloud'
+const BRIDGE_UPSTREAM_VERSION = '1.0.0'
+const BRIDGE_ID = /^cloud-bridge-[a-f0-9]{24}$/
+const PUBLIC_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/
+const MAX_RESPONSE_BYTES = 256 * 1024
+const MAX_AGENTS = 32
+const MAX_SKILLS = 64
+const STORE_VERSION = 1
+const DEFAULT_REQUEST_TIMEOUT_MS = 3 * 60 * 1000
+const DEFAULT_RUN_TIMEOUT_MS = 10 * 60 * 1000
+const MAX_REQUEST_TIMEOUT_MS = 15 * 60 * 1000
+const SSH_DISCOVERY_COMMAND = 'if command -v codex >/dev/null 2>&1; then codex --version; fi'
+const SSH_CODEX_COMMAND = 'exec codex exec --json --skip-git-repo-check --sandbox read-only -'
+const SSH_TUNNEL_READY = 'MELDWORK_AGENT_BRIDGE_READY'
+const SSH_BRIDGE_SCRIPT = fs.readFileSync(require.resolve('./cloud-agent-bridge-server.cjs'), 'utf8')
+
+function loginShellCommand(command) {
+  const escaped = String(command).replace(/'/g, `'"'"'`)
+  return `bash -lc '${escaped}'`
+}
+
+function bridgeError(code) {
+  const error = new Error(code)
+  error.code = code
+  return error
+}
+
+function fail(code) {
+  throw bridgeError(code)
+}
+
+function clone(value) {
+  return JSON.parse(canonicalJson(value))
+}
+
+function cleanText(value, max = 240) {
+  const text = String(value || '').trim()
+  if (!text || text.length > max || /[\u0000-\u001f\u007f]/.test(text)) return ''
+  return text
+}
+
+function normalizeSkill(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null
+  const namespace = cleanText(input.namespace, 80)
+  const slug = cleanText(input.slug, 120)
+  const name = cleanText(input.name || input.slug, 120)
+  if (!PUBLIC_ID.test(namespace) || !PUBLIC_ID.test(slug) || !name) return null
+  return { namespace, slug, name }
+}
+
+function normalizeAddress(value) {
+  const raw = String(value || '').trim().replace(/\/$/, '')
+  const address = /^[a-z][a-z\d+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`
+  let parsed
+  try { parsed = new URL(address) } catch { fail('CLOUD_AGENT_BRIDGE_ADDRESS_INVALID') }
+  if (!['https:'].includes(parsed.protocol)
+      || parsed.username || parsed.password || parsed.pathname !== '/'
+      || parsed.search || parsed.hash || !parsed.hostname
+      || net.isIP(parsed.hostname) === 0) {
+    fail('CLOUD_AGENT_BRIDGE_ADDRESS_INVALID')
+  }
+  return parsed.origin
+}
+
+function normalizeSshAddress(value) {
+  const raw = String(value || '').trim()
+  if (!raw || /^[a-z][a-z\d+.-]*:\/\//i.test(raw) || /[\s@/?#]/.test(raw)) {
+    fail('CLOUD_AGENT_SSH_ADDRESS_INVALID')
+  }
+  const match = raw.match(/^([^:]+)(?::(\d{1,5}))?$/)
+  if (!match || net.isIP(match[1]) === 0) fail('CLOUD_AGENT_SSH_ADDRESS_INVALID')
+  const port = match[2] ? Number(match[2]) : 22
+  if (!Number.isInteger(port) || port < 1 || port > 65535) fail('CLOUD_AGENT_SSH_ADDRESS_INVALID')
+  return { host: match[1], port, address: port === 22 ? match[1] : `${match[1]}:${port}` }
+}
+
+function normalizeTunnelEndpoint(value) {
+  let parsed
+  try { parsed = new URL(String(value || '')) } catch { fail('CLOUD_AGENT_SSH_TUNNEL_INVALID') }
+  if (parsed.protocol !== 'http:' || parsed.hostname !== '127.0.0.1'
+      || parsed.pathname !== '/' || parsed.search || parsed.hash
+      || parsed.username || parsed.password || !parsed.port) {
+    fail('CLOUD_AGENT_SSH_TUNNEL_INVALID')
+  }
+  return parsed.origin
+}
+
+function normalizeAgent(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    fail('CLOUD_AGENT_BRIDGE_MANIFEST_INVALID')
+  }
+  const id = cleanText(input.id, 80)
+  const sourceKind = cleanText(input.sourceKind || input.id, 80)
+  const label = cleanText(input.label || input.name, 120)
+  const version = cleanText(input.version, 80)
+  if (!PUBLIC_ID.test(id) || !PUBLIC_ID.test(sourceKind) || !label || !version) {
+    fail('CLOUD_AGENT_BRIDGE_MANIFEST_INVALID')
+  }
+  const domains = Array.isArray(input.domains) && input.domains.length
+    ? input.domains.map(item => cleanText(item, 80)).filter(item => PUBLIC_ID.test(item))
+    : ['general']
+  const inputTypes = Array.isArray(input.inputTypes) && input.inputTypes.length
+    ? input.inputTypes.filter(item => ['text', 'image', 'audio', 'video', 'file', 'structured-data'].includes(item))
+    : ['text']
+  const permissionModes = Array.isArray(input.permissionModes) && input.permissionModes.length
+    ? input.permissionModes.filter(item => ['read-only', 'workspace-write'].includes(item))
+    : ['read-only']
+  if (!domains.length || !inputTypes.includes('text') || !permissionModes.length) {
+    fail('CLOUD_AGENT_BRIDGE_MANIFEST_INVALID')
+  }
+  const credentialState = ['ready', 'missing', 'unknown'].includes(input.credentialState)
+    ? input.credentialState
+    : (input.available === false ? 'unknown' : 'ready')
+  const skills = (Array.isArray(input.skills) ? input.skills : [])
+    .map(normalizeSkill)
+    .filter(Boolean)
+    .slice(0, MAX_SKILLS)
+  return {
+    id, sourceKind, label, version,
+    description: cleanText(input.description, 400),
+    available: input.available !== false,
+    credentialState,
+    skills,
+    domains: [...new Set(domains)].slice(0, 16),
+    inputTypes: [...new Set(inputTypes)].slice(0, 16),
+    permissionModes: [...new Set(permissionModes)],
+    session: {
+      supported: input.session?.supported !== false,
+      resume: input.session?.resume !== false,
+      cancel: input.session?.cancel !== false,
+      checkpoint: false,
+    },
+  }
+}
+
+function normalizeProbe(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || value.protocol !== BRIDGE_PROTOCOL || value.version !== BRIDGE_VERSION
+      || !Array.isArray(value.agents) || !value.agents.length || value.agents.length > MAX_AGENTS) {
+    fail('CLOUD_AGENT_BRIDGE_MANIFEST_INVALID')
+  }
+  const serverLabel = cleanText(value.server?.label || value.server?.name, 120)
+  return {
+    serverId: cleanText(value.server?.id, 120),
+    serverLabel: serverLabel || 'Cloud Agent Server',
+    agents: value.agents.map(normalizeAgent),
+  }
+}
+
+function bridgeIdFor(address) {
+  return `cloud-bridge-${crypto.createHash('sha256').update(address).digest('hex').slice(0, 24)}`
+}
+
+function instanceIdFor(bridgeId, agentId) {
+  return `cloud-${crypto.createHash('sha256').update(`${bridgeId}:${agentId}`).digest('hex').slice(0, 24)}`
+}
+
+function manifestFor(record, agent) {
+  const ssh = record.transport === 'ssh'
+  const tunnel = record.transport === 'ssh-tunnel'
+  return createAgentConnectorManifest({
+    connectorId: instanceIdFor(record.bridgeId, agent.id),
+    connectorVersion: '1.0.0',
+    kind: 'agent',
+    label: `${agent.label} @ ${record.label}`,
+    description: agent.description || `Agent CLI exposed by ${record.label}.`,
+    transport: ssh ? { type: 'cli', protocol: 'jsonl' } : { type: 'http', protocol: 'json' },
+    upstream: ssh
+      ? { id: agent.id, minVersion: BRIDGE_UPSTREAM_VERSION, maxVersion: BRIDGE_UPSTREAM_VERSION }
+      : { id: BRIDGE_UPSTREAM_ID, minVersion: BRIDGE_UPSTREAM_VERSION, maxVersion: BRIDGE_UPSTREAM_VERSION },
+    invocation: { recipeId: ssh ? SSH_RECIPE_ID : BRIDGE_RECIPE_ID, idempotencyMode: 'durable' },
+    domains: agent.domains,
+    session: agent.session,
+    inputTypes: agent.inputTypes,
+    permissionModes: agent.permissionModes,
+    eventProtocolVersion: 1,
+    eventTypes: ['Completed', 'Failed', 'Cancelled'],
+    usage: {
+      inputTokens: false, outputTokens: false, costMicros: false,
+      toolCalls: false, outboundBytes: !ssh && !tunnel, elapsedMs: true,
+    },
+    outboundDestinations: ssh || tunnel ? [] : [record.address],
+    credentials: { mode: 'none', slots: [] },
+    license: 'LicenseRef-Meldwork-NC',
+  })
+}
+
+function instanceFor(record, agent, manifest) {
+  return {
+    instanceId: manifest.connectorId,
+    connectorId: manifest.connectorId,
+    connectorVersion: manifest.connectorVersion,
+    upstreamVersion: BRIDGE_UPSTREAM_VERSION,
+    label: manifest.label,
+    credentialRef: null,
+    manifestId: manifest.manifestId,
+    bridgeId: record.bridgeId,
+    agentId: agent.id,
+  }
+}
+
+class CloudAgentBridgeStore {
+  constructor(options = {}) {
+    if (!options || typeof options.storagePath !== 'string' || !options.storagePath
+        || typeof options.fetch !== 'function') {
+      fail('CLOUD_AGENT_BRIDGE_OPTIONS_INVALID')
+    }
+    this.storagePath = options.storagePath
+    this.fetch = options.fetch
+    this.spawn = options.spawn || spawn
+    this.sshExecute = typeof options.sshExecute === 'function' ? options.sshExecute : null
+    this.sshTunnelStart = typeof options.sshTunnelStart === 'function' ? options.sshTunnelStart : null
+    this.tunnels = new Map()
+    this.timeoutMs = Number.isFinite(options.timeoutMs)
+      ? Math.max(1000, Math.min(MAX_REQUEST_TIMEOUT_MS, Math.floor(options.timeoutMs)))
+      : DEFAULT_REQUEST_TIMEOUT_MS
+    this.runTimeoutMs = Number.isFinite(options.runTimeoutMs)
+      ? Math.max(1000, Math.min(MAX_REQUEST_TIMEOUT_MS, Math.floor(options.runTimeoutMs)))
+      : DEFAULT_RUN_TIMEOUT_MS
+    this.records = this.read().records
+  }
+
+  read() {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.storagePath, 'utf8'))
+      if (parsed?.version !== STORE_VERSION || !Array.isArray(parsed.records)) throw new Error('invalid')
+      return { version: STORE_VERSION, records: parsed.records.map(value => this.normalizeRecord(value)) }
+    } catch {
+      return { version: STORE_VERSION, records: [] }
+    }
+  }
+
+  normalizeRecord(value) {
+    const transport = ['ssh', 'ssh-tunnel'].includes(value?.transport) ? value.transport : 'bridge'
+    const sshAddress = ['ssh', 'ssh-tunnel'].includes(transport) ? normalizeSshAddress(value?.address) : null
+    const address = sshAddress?.address || normalizeAddress(value?.address)
+    const bridgeId = String(value?.bridgeId || bridgeIdFor(`${transport}:${address}`))
+    if (!BRIDGE_ID.test(bridgeId)) fail('CLOUD_AGENT_BRIDGE_STORE_INVALID')
+    const agents = Array.isArray(value?.agents) ? value.agents.map(normalizeAgent).slice(0, MAX_AGENTS) : []
+    return {
+      bridgeId,
+      transport,
+      address,
+      endpoint: transport === 'ssh-tunnel' ? normalizeTunnelEndpoint(value?.endpoint) : '',
+      label: cleanText(value?.label, 120) || (transport === 'ssh' ? address : 'Cloud Agent Server'),
+      serverId: cleanText(value?.serverId, 120),
+      agents,
+      available: transport === 'ssh-tunnel' ? false : value?.available === true,
+      lastError: cleanText(value?.lastError, 120),
+      checkedAt: cleanText(value?.checkedAt, 40),
+    }
+  }
+
+  persist() {
+    atomicWritePrivateFile(this.storagePath, `${JSON.stringify({ version: STORE_VERSION, records: this.records })}\n`)
+  }
+
+  async request(pathname, options = {}) {
+    const controller = new AbortController()
+    const timeoutMs = Number.isFinite(options.timeoutMs)
+      ? Math.max(1000, Math.min(MAX_REQUEST_TIMEOUT_MS, Math.floor(options.timeoutMs)))
+      : this.timeoutMs
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    const activityIntervalMs = Math.min(1000, Math.max(10, Math.floor(timeoutMs / 4)))
+    const reportActivity = () => {
+      try { options.onActivity?.() } catch { /* activity reporting must not fail the request */ }
+    }
+    reportActivity()
+    const activityTimer = options.onActivity
+      ? setInterval(reportActivity, activityIntervalMs)
+      : null
+    const abortFromCaller = () => controller.abort()
+    options.signal?.addEventListener?.('abort', abortFromCaller, { once: true })
+    try {
+      const response = await this.fetch(`${options.address}${pathname}`, {
+        method: options.method || 'GET',
+        redirect: 'error',
+        signal: controller.signal,
+        headers: { accept: 'application/json', ...(options.body ? { 'content-type': 'application/json' } : {}) },
+        ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+      })
+      if (!response?.ok) throw bridgeError(`CLOUD_AGENT_BRIDGE_HTTP_${response?.status || 'FAILED'}`)
+      const text = await response.text()
+      if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSE_BYTES) fail('CLOUD_AGENT_BRIDGE_RESPONSE_TOO_LARGE')
+      try { return JSON.parse(text) } catch { fail('CLOUD_AGENT_BRIDGE_RESPONSE_INVALID') }
+    } catch (error) {
+      if (error?.name === 'AbortError') fail('CLOUD_AGENT_BRIDGE_TIMEOUT')
+      throw error
+    } finally {
+      clearTimeout(timer)
+      if (activityTimer) clearInterval(activityTimer)
+      options.signal?.removeEventListener?.('abort', abortFromCaller)
+    }
+  }
+
+  async probe(address) {
+    const normalizedAddress = normalizeAddress(address)
+    return normalizeProbe(await this.request('/.well-known/meldwork-agent-bridge', { address: normalizedAddress }))
+  }
+
+  async sshCommand(address, command, input = '', signal) {
+    const parsed = normalizeSshAddress(address)
+    if (signal?.aborted) fail('CLOUD_AGENT_SSH_CANCELLED')
+    if (this.sshExecute) return this.sshExecute({
+      address: parsed.address, command, input, signal,
+    })
+    const args = [
+      '-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', '-o', 'StrictHostKeyChecking=yes',
+      ...(parsed.port === 22 ? [] : ['-p', String(parsed.port)]),
+      parsed.host, command,
+    ]
+    return new Promise((resolve, reject) => {
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+      const child = this.spawn('ssh', args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+      const finish = (error, value) => {
+        if (settled) return
+        settled = true
+        signal?.removeEventListener?.('abort', abort)
+        if (error) reject(error)
+        else resolve(value)
+      }
+      const append = (target, chunk) => {
+        const next = `${target}${Buffer.from(chunk).toString('utf8')}`
+        if (Buffer.byteLength(next, 'utf8') > MAX_RESPONSE_BYTES) {
+          child.kill('SIGTERM')
+          finish(bridgeError('CLOUD_AGENT_SSH_RESPONSE_TOO_LARGE'))
+          return target
+        }
+        return next
+      }
+      const abort = () => {
+        child.kill('SIGTERM')
+        finish(bridgeError('CLOUD_AGENT_SSH_CANCELLED'))
+      }
+      child.once('error', () => finish(bridgeError('CLOUD_AGENT_SSH_UNAVAILABLE')))
+      child.stdout.on('data', chunk => { stdout = append(stdout, chunk) })
+      child.stderr.on('data', chunk => { stderr = append(stderr, chunk) })
+      child.once('close', code => {
+        if (signal?.aborted) return finish(bridgeError('CLOUD_AGENT_SSH_CANCELLED'))
+        if (code !== 0) return finish(bridgeError('CLOUD_AGENT_SSH_UNAVAILABLE'))
+        finish(null, { stdout, stderr })
+      })
+      signal?.addEventListener?.('abort', abort, { once: true })
+      child.stdin.end(input)
+    })
+  }
+
+  async allocateLocalPort() {
+    return new Promise((resolve, reject) => {
+      const server = net.createServer()
+      server.once('error', reject)
+      server.listen(0, '127.0.0.1', () => {
+        const port = server.address()?.port
+        server.close(error => error ? reject(error) : resolve(port))
+      })
+    })
+  }
+
+  async startSshTunnel(address) {
+    const parsed = normalizeSshAddress(address)
+    if (this.sshTunnelStart) return this.sshTunnelStart({ address: parsed.address })
+    const localPort = await this.allocateLocalPort()
+    const remotePort = localPort
+    const args = [
+      '-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=5', '-o', 'StrictHostKeyChecking=yes',
+      '-L', `127.0.0.1:${localPort}:127.0.0.1:${remotePort}`,
+      ...(parsed.port === 22 ? [] : ['-p', String(parsed.port)]),
+      parsed.host, loginShellCommand(`MELDWORK_AGENT_BRIDGE_PORT=${remotePort} exec node -`),
+    ]
+    const child = this.spawn('ssh', args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+    child.stderr.resume()
+    return new Promise((resolve, reject) => {
+      let output = ''
+      let settled = false
+      const timer = setTimeout(() => finish(bridgeError('CLOUD_AGENT_SSH_TUNNEL_TIMEOUT')), this.timeoutMs)
+      const finish = error => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        if (error) {
+          child.kill('SIGTERM')
+          reject(error)
+          return
+        }
+        resolve({ child, endpoint: `http://127.0.0.1:${localPort}` })
+      }
+      child.once('error', () => finish(bridgeError('CLOUD_AGENT_SSH_TUNNEL_UNAVAILABLE')))
+      child.stdout.on('data', chunk => {
+        output += Buffer.from(chunk).toString('utf8')
+        if (Buffer.byteLength(output, 'utf8') > 16 * 1024) {
+          finish(bridgeError('CLOUD_AGENT_SSH_TUNNEL_PROTOCOL'))
+          return
+        }
+        if (new RegExp(`${SSH_TUNNEL_READY}\\s+${remotePort}\\b`).test(output)) finish()
+      })
+      child.once('close', code => {
+        if (!settled) finish(bridgeError(code === 0
+          ? 'CLOUD_AGENT_SSH_TUNNEL_UNAVAILABLE'
+          : 'CLOUD_AGENT_SSH_TUNNEL_FAILED'))
+      })
+      child.stdin.end(SSH_BRIDGE_SCRIPT)
+    })
+  }
+
+  stopTunnel(bridgeId) {
+    const tunnel = this.tunnels.get(bridgeId)
+    if (!tunnel) return
+    this.tunnels.delete(bridgeId)
+    try { tunnel.child?.kill('SIGTERM') } catch { /* already closed */ }
+  }
+
+  async ensureSshTunnel(record) {
+    const existing = this.tunnels.get(record.bridgeId)
+    if (existing?.child && !existing.child.killed) return existing.endpoint
+    const tunnel = await this.startSshTunnel(record.address)
+    this.tunnels.set(record.bridgeId, tunnel)
+    tunnel.child?.once?.('close', () => {
+      if (this.tunnels.get(record.bridgeId) === tunnel) this.tunnels.delete(record.bridgeId)
+    })
+    return tunnel.endpoint
+  }
+
+  async probeSsh(address) {
+    const result = await this.sshCommand(address, SSH_DISCOVERY_COMMAND)
+    const version = String(result.stdout || '').match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/)?.[1]
+    if (!version) fail('CLOUD_AGENT_SSH_NO_AGENT')
+    return {
+      serverId: '',
+      serverLabel: normalizeSshAddress(address).address,
+      agents: [{
+        id: 'codex', label: 'Codex CLI', version, description: '', domains: ['general'],
+        inputTypes: ['text'], permissionModes: ['read-only'],
+        session: { supported: false, resume: false, cancel: true, checkpoint: false },
+      }],
+    }
+  }
+
+  async connect(input = {}) {
+    const rawAddress = String(input.address || '').trim()
+    let sshError = null
+    if (!/^[a-z][a-z\d+.-]*:\/\//i.test(rawAddress)) {
+      try { return await this.connectSshTunnel(input) } catch (error) { sshError = error }
+      try { return await this.connectSsh(input) } catch (error) { sshError = error }
+    }
+    try {
+      const address = normalizeAddress(input.address)
+      const probe = await this.probe(address)
+      const bridgeId = bridgeIdFor(address)
+      const record = this.normalizeRecord({
+        bridgeId,
+        address,
+        label: cleanText(input.label, 120) || probe.serverLabel,
+        serverId: probe.serverId,
+        agents: probe.agents,
+        available: true,
+        lastError: '',
+        checkedAt: new Date().toISOString(),
+      })
+      const index = this.records.findIndex(item => item.bridgeId === bridgeId)
+      if (index >= 0) this.records[index] = record
+      else this.records.push(record)
+      this.records.sort((left, right) => left.label.localeCompare(right.label) || left.bridgeId.localeCompare(right.bridgeId))
+      this.persist()
+      return this.publicRecord(record)
+    } catch (error) {
+      throw sshError || error
+    }
+  }
+
+  async connectSsh(input = {}) {
+    const sshAddress = normalizeSshAddress(input.address)
+    const probe = await this.probeSsh(sshAddress.address)
+    const bridgeId = bridgeIdFor(`ssh:${sshAddress.address}`)
+    const record = this.normalizeRecord({
+      bridgeId,
+      transport: 'ssh',
+      address: sshAddress.address,
+      label: cleanText(input.label, 120) || probe.serverLabel,
+      serverId: probe.serverId,
+      agents: probe.agents,
+      available: true,
+      lastError: '',
+      checkedAt: new Date().toISOString(),
+    })
+    const index = this.records.findIndex(item => item.bridgeId === bridgeId)
+    if (index >= 0) this.records[index] = record
+    else this.records.push(record)
+    this.records.sort((left, right) => left.label.localeCompare(right.label) || left.bridgeId.localeCompare(right.bridgeId))
+    this.persist()
+    return this.publicRecord(record)
+  }
+
+  async connectSshTunnel(input = {}) {
+    const sshAddress = normalizeSshAddress(input.address)
+    const existing = this.records.find(record => (
+      record.address === sshAddress.address && ['ssh', 'ssh-tunnel'].includes(record.transport)
+    ))
+    const bridgeId = existing?.bridgeId || bridgeIdFor(`ssh-tunnel:${sshAddress.address}`)
+    const endpoint = await this.ensureSshTunnel({ bridgeId, address: sshAddress.address })
+    try {
+      const probe = normalizeProbe(await this.request('/.well-known/meldwork-agent-bridge', { address: endpoint }))
+      const record = this.normalizeRecord({
+        bridgeId,
+        transport: 'ssh-tunnel',
+        address: sshAddress.address,
+        endpoint,
+        label: cleanText(input.label, 120) || probe.serverLabel,
+        serverId: probe.serverId,
+        agents: probe.agents,
+        available: true,
+        lastError: '',
+        checkedAt: new Date().toISOString(),
+      })
+      record.available = true
+      const index = this.records.findIndex(item => item.bridgeId === bridgeId)
+      if (index >= 0) this.records[index] = record
+      else this.records.push(record)
+      this.records = this.records.filter(item => (
+        item.bridgeId === bridgeId || item.address !== sshAddress.address
+      ))
+      this.records.sort((left, right) => left.label.localeCompare(right.label) || left.bridgeId.localeCompare(right.bridgeId))
+      this.persist()
+      return this.publicRecord(record)
+    } catch (error) {
+      this.stopTunnel(bridgeId)
+      throw error
+    }
+  }
+
+  async refresh() {
+    for (const current of this.records) {
+      try {
+        let probe
+        if (current.transport === 'ssh-tunnel') {
+          current.endpoint = await this.ensureSshTunnel(current)
+          probe = normalizeProbe(await this.request('/.well-known/meldwork-agent-bridge', {
+            address: current.endpoint,
+          }))
+          current.available = true
+        } else if (current.transport === 'ssh') {
+          try {
+            current.endpoint = await this.ensureSshTunnel(current)
+            probe = normalizeProbe(await this.request('/.well-known/meldwork-agent-bridge', {
+              address: current.endpoint,
+            }))
+            current.transport = 'ssh-tunnel'
+            current.available = true
+          } catch {
+            probe = await this.probeSsh(current.address)
+          }
+        } else {
+          probe = await this.probe(current.address)
+        }
+        Object.assign(current, {
+          serverId: probe.serverId,
+          agents: probe.agents.map(normalizeAgent),
+          available: true,
+          lastError: '', checkedAt: new Date().toISOString(),
+        })
+      } catch (error) {
+        if (current.transport === 'ssh-tunnel') this.stopTunnel(current.bridgeId)
+        current.available = false
+        current.lastError = String(error?.code || 'CLOUD_AGENT_BRIDGE_PROBE_FAILED').slice(0, 120)
+      }
+    }
+    this.persist()
+    return this.list()
+  }
+
+  publicRecord(record) {
+    return clone({
+      bridgeId: record.bridgeId, address: record.address, label: record.label,
+      transport: record.transport,
+      serverId: record.serverId, available: record.available,
+      lastError: record.lastError, checkedAt: record.checkedAt,
+      agents: record.agents.map(agent => ({
+        id: agent.id, sourceKind: agent.sourceKind, label: agent.label, version: agent.version,
+        description: agent.description, domains: agent.domains,
+        available: agent.available,
+        credentialState: agent.credentialState,
+        skills: agent.skills,
+      })),
+    })
+  }
+
+  list() {
+    return this.records.map(record => this.publicRecord(record))
+  }
+
+  remove(bridgeId) {
+    const id = String(bridgeId || '')
+    const index = this.records.findIndex(record => record.bridgeId === id)
+    if (index < 0) fail('CLOUD_AGENT_BRIDGE_NOT_FOUND')
+    this.stopTunnel(id)
+    this.records.splice(index, 1)
+    this.persist()
+    return { deleted: true, bridgeId: id }
+  }
+
+  connectorEntries() {
+    return this.records.filter(record => record.available).flatMap(record => record.agents
+      .filter(agent => agent.available !== false)
+      .map(agent => {
+      const manifest = manifestFor(record, agent)
+      return { record: clone(record), agent: clone(agent), manifest, instance: instanceFor(record, agent, manifest) }
+      }))
+  }
+
+  catalogEntries() {
+    return this.records.flatMap(record => record.agents.map(agent => ({
+      kind: instanceIdFor(record.bridgeId, agent.id),
+      sourceKind: agent.sourceKind,
+      label: `${agent.label} @ ${record.label}`,
+      name: `${agent.label} @ ${record.label}`,
+      description: agent.description,
+      version: agent.version,
+      installed: true,
+      installSupported: false,
+      installErrorCode: '',
+      imageAttachmentLimit: 0,
+      custom: false,
+      connector: true,
+      cloud: true,
+      available: record.available && agent.available !== false,
+      credentialState: agent.credentialState,
+      serverLabel: record.label,
+    })))
+  }
+
+  skillsForInstance(instanceId) {
+    const id = String(instanceId || '')
+    for (const record of this.records) {
+      const agent = record.agents.find(item => instanceIdFor(record.bridgeId, item.id) === id)
+      if (agent) return clone(agent.skills)
+    }
+    return null
+  }
+
+  async run(input) {
+    const bridgeId = String(input?.bridgeId || '')
+    const agentId = String(input?.agentId || '')
+    const record = this.records.find(item => item.bridgeId === bridgeId && item.available)
+    if (!record || !PUBLIC_ID.test(agentId)) fail('CLOUD_AGENT_BRIDGE_NOT_FOUND')
+    const agent = record.agents.find(item => item.id === agentId)
+    if (!agent) fail('CLOUD_AGENT_BRIDGE_AGENT_NOT_FOUND')
+    if (agent.available === false) fail('CLOUD_AGENT_BRIDGE_AGENT_UNAVAILABLE')
+    if (record.transport === 'ssh') return this.runSsh(record, agent, input)
+    return this.request(`/v1/agents/${encodeURIComponent(agentId)}/runs`, {
+      address: record.transport === 'ssh-tunnel' ? record.endpoint : record.address,
+      method: 'POST',
+      signal: input.signal,
+      timeoutMs: this.runTimeoutMs,
+      onActivity: input.onActivity,
+      body: {
+        prompt: input.prompt,
+        sessionRef: input.sessionRef || null,
+        permissionMode: input.permissionMode,
+        operationId: input.operationId,
+        resume: input.resume || null,
+      },
+    })
+  }
+
+  async runSsh(record, agent, input) {
+    if (agent.id !== 'codex' || input.permissionMode !== 'read-only') {
+      fail('CLOUD_AGENT_SSH_PERMISSION_UNSUPPORTED')
+    }
+    const result = await this.sshCommand(record.address, SSH_CODEX_COMMAND, input.prompt, input.signal)
+    const messages = []
+    let sessionRef = ''
+    for (const line of String(result.stdout || '').split('\n')) {
+      try {
+        const event = JSON.parse(line)
+        if (event.type === 'thread.started' && typeof event.thread_id === 'string') sessionRef = event.thread_id
+        if (event.type === 'item.completed' && event.item?.type === 'agent_message'
+            && typeof event.item.text === 'string') messages.push(event.item.text)
+      } catch { /* SSH transport permits only Codex JSONL output */ }
+    }
+    const text = messages.join('\n').trim()
+    if (!text) fail('CLOUD_AGENT_SSH_RESPONSE_INVALID')
+    return { text, sessionRef: '', outcome: 'completed' }
+  }
+
+  bridgeForInstance(instanceId) {
+    for (const entry of this.connectorEntries()) {
+      if (entry.instance.instanceId === instanceId) return entry
+    }
+    return null
+  }
+
+  close() {
+    for (const bridgeId of this.tunnels.keys()) this.stopTunnel(bridgeId)
+  }
+}
+
+module.exports = {
+  BRIDGE_RECIPE_ID,
+  SSH_RECIPE_ID,
+  CloudAgentBridgeStore,
+  loginShellCommand,
+  manifestFor,
+  normalizeAddress,
+  normalizeProbe,
+}

desktop/src/agents/cloud/cloud-agent-runtime.cjs

@@ -187,6 +187,7 @@ class CloudAgentRuntime {
     this.listeners = new Set()
     this.started = false
     this.stopping = false
+    this.preserveWaitingRun = () => false
     this.ledgerFacade = null
     for (const connector of connectorEntries(options.connectors)) this.registerConnector(connector)
   }
@@ -230,6 +231,7 @@ class CloudAgentRuntime {
               ),
             })
             for (const record of preserved.values()) target.checkpoint(record)
+            runtime.preserveWaitingRun = callerPreserve
             return changed.filter(record => !preserved.has(record.runId))
           }
         }
@@ -764,6 +766,7 @@ class CloudAgentRuntime {
       this.runLedger.recoverInterrupted({
         remoteConnectorIds: this.connectorIds(),
         recoveryOwnerId: this.recoveryOwnerId,
+        preserveWaitingRun: this.preserveWaitingRun,
       })
       const recoveries = this.runLedger.remoteRecoveries(this.recoveryOwnerId)
       for (const claim of recoveries) {

desktop/src/agents/connectors/agent-connector-local.cjs

@@ -17,6 +17,7 @@ const {
   MAX_PACKAGE_BYTES,
   createAgentConnectorPackage,
 } = require('./agent-connector-package-store.cjs')
+const { BRIDGE_RECIPE_ID, SSH_RECIPE_ID } = require('../cloud/cloud-agent-bridge.cjs')
 
 const LOCAL_DELEGATE_RECIPE_ID = 'external.local-agent.delegate'
 const MAX_LOCAL_MANIFESTS = 64
@@ -48,7 +49,7 @@ const SAMPLE_AGENT_CONNECTOR_MANIFEST = createAgentConnectorManifest({
   },
   outboundDestinations: [],
   credentials: { mode: 'none', slots: [] },
-  license: 'LicenseRef-Meldwork-NC',
+  license: 'Apache-2.0',
 })
 const SAMPLE_CREDENTIAL_AGENT_CONNECTOR_MANIFEST = createAgentConnectorManifest({
   connectorId: 'external.codex-provider-sample',
@@ -81,7 +82,7 @@ const SAMPLE_CREDENTIAL_AGENT_CONNECTOR_MANIFEST = createAgentConnectorManifest(
     mode: 'credential-ref',
     slots: [{ slotId: 'openai-api-key', type: 'api-key', required: true }],
   },
-  license: 'LicenseRef-Meldwork-NC',
+  license: 'Apache-2.0',
 })
 const APPROVED_AGENT_CONNECTOR_MANIFESTS = Object.freeze([
   SAMPLE_AGENT_CONNECTOR_MANIFEST,
@@ -116,7 +117,7 @@ const SAMPLE_LOCAL_ECHO_AGENT_CONNECTOR_MANIFEST = createAgentConnectorManifest(
   },
   outboundDestinations: [],
   credentials: { mode: 'none', slots: [] },
-  license: 'LicenseRef-Meldwork-NC',
+  license: 'Apache-2.0',
 })
 const SAMPLE_LOCAL_ECHO_AGENT_CONNECTOR_PACKAGE = createAgentConnectorPackage({
   publisher: { id: 'meldwork', name: 'Meldwork' },
@@ -137,7 +138,7 @@ function fail(code) {
 function exactOptions(value) {
   return value && typeof value === 'object' && !Array.isArray(value)
     && Object.keys(value).every(key => [
-      'fetch', 'instanceStore', 'manifestDirectory', 'packageStore', 'runAgent', 'seedSample',
+      'cloudBridges', 'fetch', 'instanceStore', 'manifestDirectory', 'packageStore', 'runAgent', 'seedSample',
     ].includes(key))
 }
 
@@ -240,6 +241,7 @@ class LocalAgentConnectors {
     this.upstreams = new Map()
     this.detectedUpstreams = []
     this.lastDiagnostics = []
+    this.cloudBridges = options.cloudBridges || null
   }
 
   createRegistry() {
@@ -247,7 +249,7 @@ class LocalAgentConnectors {
       ? this.packageStore.installedPackages().map(item => item.manifest)
       : []
     return new AgentConnectorRegistry({
-      approvedRecipeIds: [LOCAL_DELEGATE_RECIPE_ID, ...SDK_RECIPE_IDS],
+      approvedRecipeIds: [LOCAL_DELEGATE_RECIPE_ID, BRIDGE_RECIPE_ID, SSH_RECIPE_ID, ...SDK_RECIPE_IDS],
       approvedExternalManifestIds: [
         ...APPROVED_AGENT_CONNECTOR_MANIFESTS.map(item => item.manifestId),
         ...installedPackageManifests.map(item => item.manifestId),
@@ -262,6 +264,8 @@ class LocalAgentConnectors {
         [LOCAL_DELEGATE_RECIPE_ID]: input => this.runDelegated(input),
         [SDK_LOCAL_ECHO_RECIPE_ID]: input => this.runLocalEcho(input),
         [SDK_HTTP_JSON_RECIPE_ID]: input => this.runHttpJson(input),
+        [BRIDGE_RECIPE_ID]: input => this.runCloudBridge(input),
+        [SSH_RECIPE_ID]: input => this.runCloudBridge(input),
       },
     })
   }
@@ -350,6 +354,29 @@ class LocalAgentConnectors {
       diagnostics.push({ name: 'instances', code: safeFailureCode(error) })
     }
     const manifests = registry.listManifests()
+    for (const entry of this.cloudBridges?.connectorEntries?.() || []) {
+      try {
+        const manifest = registry.registerBuiltin(entry.manifest)
+        const instance = registry.registerInstance({
+          instanceId: entry.instance.instanceId,
+          connectorId: manifest.connectorId,
+          connectorVersion: manifest.connectorVersion,
+          upstreamVersion: entry.instance.upstreamVersion,
+          label: entry.instance.label,
+          credentialRef: null,
+        })
+        upstreams.set(instance.instanceId, Object.freeze({
+          kind: instance.instanceId,
+          label: instance.label,
+          name: instance.label,
+          version: instance.upstreamVersion,
+          compatibilityState: 'compatible',
+          cloud: true,
+        }))
+      } catch (error) {
+        diagnostics.push({ name: entry.instance.instanceId, code: safeFailureCode(error) })
+      }
+    }
     for (const stored of storedInstances) {
       const manifest = manifests.find(item => (
         item.manifestId === stored.manifestId
@@ -405,9 +432,10 @@ class LocalAgentConnectors {
 
   detectAgents() {
     return this.runtime.detectAgents().map((agent) => {
-      const { instance } = this.registry.resolveInstance(agent.connectorInstanceId)
+      const { instance, manifest } = this.registry.resolveInstance(agent.connectorInstanceId)
       return Object.freeze({
         ...agent,
+        cloud: [BRIDGE_RECIPE_ID, SSH_RECIPE_ID].includes(manifest.invocation.recipeId),
         credentialConfigured: Boolean(instance.credentialRef),
       })
     }).sort((left, right) => (
@@ -563,20 +591,24 @@ class LocalAgentConnectors {
   catalog() {
     return this.detectAgents().map((agent) => {
       const { manifest } = this.registry.resolveInstance(agent.connectorInstanceId)
+      const cloud = [BRIDGE_RECIPE_ID, SSH_RECIPE_ID].includes(manifest.invocation.recipeId)
+      const cloudEntry = cloud ? this.cloudBridges?.bridgeForInstance?.(agent.kind) : null
       return Object.freeze({
         kind: agent.kind,
+        sourceKind: cloudEntry?.agent?.sourceKind || '',
         label: agent.label,
         name: agent.name,
         description: manifest.description,
-        version: agent.version,
+        version: cloudEntry?.agent?.version || agent.version,
         installed: true,
         installSupported: false,
         installErrorCode: '',
-        providerCompatible: false,
-        providerMode: 'connector',
-        imageAttachmentLimit: manifest.inputTypes.includes('image') ? 4 : 0,
-        custom: true,
+        imageAttachmentLimit: manifest.inputTypes.includes('image') ? 32 : 0,
+        custom: !cloud,
         connector: true,
+        cloud,
+        credentialState: cloudEntry?.agent?.credentialState || 'unknown',
+        serverLabel: cloudEntry?.record?.label || '',
         connectorId: manifest.connectorId,
         connectorVersion: manifest.connectorVersion,
         upstreamVersion: agent.upstreamVersion,
@@ -597,10 +629,10 @@ class LocalAgentConnectors {
     if (!this.has(kind)) return null
     const snapshot = this.registry.runSnapshot(kind)
     return {
-      image: snapshot.capabilities.inputTypes.includes('image') ? 4 : 0,
-      audio: snapshot.capabilities.inputTypes.includes('audio') ? 4 : 0,
-      video: snapshot.capabilities.inputTypes.includes('video') ? 4 : 0,
-      file: snapshot.capabilities.inputTypes.includes('file') ? 4 : 0,
+      image: snapshot.capabilities.inputTypes.includes('image') ? 32 : 0,
+      audio: snapshot.capabilities.inputTypes.includes('audio') ? 32 : 0,
+      video: snapshot.capabilities.inputTypes.includes('video') ? 32 : 0,
+      file: snapshot.capabilities.inputTypes.includes('file') ? 32 : 0,
     }
   }
 
@@ -768,6 +800,64 @@ class LocalAgentConnectors {
       return { outcome: 'failed', failure }
     }
   }
+
+  async runCloudBridge(input) {
+    const entry = this.cloudBridges?.bridgeForInstance?.(input.connector.instanceId)
+    if (!entry) fail('CLOUD_AGENT_BRIDGE_NOT_FOUND')
+    const terminal = {
+      eventId: `${input.agentRunId}:terminal`,
+      cursor: `${input.agentRunId}:terminal`,
+      sequence: 1,
+    }
+    try {
+      if (!['ssh', 'ssh-tunnel'].includes(entry.record.transport)) {
+        input.onOutboundPayload({ destination: entry.record.address, transport: 'http' })
+      }
+      const result = await this.cloudBridges.run({
+        bridgeId: entry.record.bridgeId,
+        agentId: entry.agent.id,
+        prompt: input.prompt,
+        sessionRef: input.sessionRef,
+        // Cloud bridge tasks never receive local workspace write authority.
+        permissionMode: 'read-only',
+        operationId: input.operationId,
+        resume: input.resume,
+        signal: input.signal,
+        onActivity: input.onActivity,
+      })
+      if (!result || typeof result !== 'object' || Array.isArray(result)
+          || typeof result.text !== 'string' || result.text.includes('\u0000')
+          || (result.sessionRef !== undefined
+            && (typeof result.sessionRef !== 'string' || result.sessionRef.length > 8192
+              || /[\u0000-\u001f\u007f]/.test(result.sessionRef)))
+          || !['completed', 'partial', 'failed', 'cancelled'].includes(result.outcome || 'completed')) {
+        fail('CLOUD_AGENT_BRIDGE_RESPONSE_INVALID')
+      }
+      if (result.outcome === 'failed') {
+        const failure = failureDetails(result.failure || result)
+        input.emit({ ...terminal, type: 'Failed', ...failure })
+        return { outcome: 'failed', failure }
+      }
+      if (result.outcome === 'cancelled') {
+        input.emit({ ...terminal, type: 'Cancelled', reason: 'user' })
+        return { outcome: 'cancelled', sessionRef: result.sessionRef || input.sessionRef || '' }
+      }
+      input.emit({ ...terminal, type: 'Completed', outcome: result.outcome || 'completed' })
+      return {
+        text: result.text,
+        sessionRef: typeof result.sessionRef === 'string' ? result.sessionRef : input.sessionRef || '',
+        outcome: result.outcome || 'completed',
+      }
+    } catch (error) {
+      if (input.signal?.aborted || error?.name === 'AbortError') {
+        input.emit({ ...terminal, type: 'Cancelled', reason: 'user' })
+        return { outcome: 'cancelled', sessionRef: input.sessionRef || '' }
+      }
+      const failure = failureDetails(error)
+      input.emit({ ...terminal, type: 'Failed', ...failure })
+      return { outcome: 'failed', failure }
+    }
+  }
 }
 
 module.exports = {

desktop/src/agents/custom-agent-contract.cjs

@@ -7,7 +7,7 @@ const PROMPT_MODES = new Set(['stdin', 'argument'])
 const MAX_AGENTS = 32
 const MAX_ARGUMENTS = 24
 const MAX_ARGUMENT_LENGTH = 512
-const MAX_ATTACHMENTS = 4
+const MAX_ATTACHMENTS = 32
 const MAX_PROMPT_BYTES = 1024 * 1024
 const MAX_STDOUT_BYTES = 4 * 1024 * 1024
 const MAX_STDERR_BYTES = 1024 * 1024
@@ -127,13 +127,10 @@ function publicProfile(definition, version = '') {
     promptMode: definition.promptMode,
     custom: true,
     recommended: false,
-    providerCompatible: false,
-    providerSupport: 'custom-cli',
-    providerMode: 'custom',
     installed: true,
     installSupported: false,
     installErrorCode: '',
-    imageAttachmentLimit: MAX_ATTACHMENTS,
+    imageAttachmentLimit: 32,
     attachmentTypes: ['image', 'audio', 'video', 'file'],
     version: String(version || '').slice(0, VERSION_LINE_LIMIT),
   }

desktop/src/agents/installer/agent-installer-contract.cjs

@@ -4,6 +4,17 @@ const fs = require('node:fs')
 const path = require('node:path')
 const { promisify } = require('node:util')
 const { searchPath } = require('../cli/cli-adapters.cjs')
+const { compareReleaseVersions, extractAgentVersion } = require('../agent-compatibility.cjs')
+
+// True when the installed CLI is the recipe's version or newer. A substring
+// test treated "11.2.3" as "1.2.3" and offered downgrades for newer CLIs.
+function installedVersionCurrent(installedVersion, targetVersion) {
+  const installed = extractAgentVersion(installedVersion).split('-')[0]
+  const target = extractAgentVersion(targetVersion).split('-')[0]
+  const comparison = installed && target ? compareReleaseVersions(installed, target) : null
+  if (comparison != null) return comparison >= 0
+  return Boolean(targetVersion) && String(installedVersion || '').includes(targetVersion)
+}
 
 const execFileAsync = promisify(execFile)
 const DETECTION_CACHE_TTL_MS = 30000
@@ -53,6 +64,12 @@ const NPM_RELEASES = Object.freeze({
     version: '2026.7.1-2',
     integrity: 'sha512-ycF3yPcbjN6bUPeaUx6Mh6vze1hQWoD3CT/wWcmD7a8xaHHHRUaAlaq+lFxMHf1ssEgODVAwjlzYqp2twkYZ7g==',
   }),
+  pi: Object.freeze({
+    packageName: '@earendil-works/pi-coding-agent',
+    version: '0.84.2',
+    integrity: 'sha512-l4E+B7hgXKWddRo8bC/eSue2aWZjEgJ9xIpf5p0Og+lq8a2TArCwJ0HCoCPCgaBP/tN4zbYH/wOwvx9pJpeLCA==',
+    ignoreScripts: true,
+  }),
   qwen: Object.freeze({
     packageName: '@qwen-code/qwen-code',
     version: '0.21.5',
@@ -93,50 +110,17 @@ const NPM_RELEASES = Object.freeze({
 const ALLOWED_SCRIPT_URLS = new Set(Object.values(HERMES_RECIPES).map(recipe => recipe.url))
 
 const AGENT_CATALOG = Object.freeze([
-  {
-    kind: 'hermes', label: 'Hermes', recommended: true, providerCompatible: true,
-    providerSupport: 'supported',
-  },
-  {
-    kind: 'openclaw', label: 'OpenClaw', recommended: true, providerCompatible: true,
-    providerSupport: 'supported',
-  },
-  {
-    kind: 'workbuddy', label: 'WorkBuddy', recommended: true, providerCompatible: true,
-    providerSupport: 'experimental',
-  },
-  {
-    kind: 'kimi', label: 'Kimi Code', recommended: false, providerCompatible: false,
-    providerSupport: 'native-config',
-  },
-  {
-    kind: 'mimo', label: 'MiMo Code', recommended: false, providerCompatible: false,
-    providerSupport: 'native-config',
-  },
-  {
-    kind: 'codex', label: 'Codex', recommended: false, providerCompatible: false,
-    providerSupport: 'responses-required',
-  },
-  {
-    kind: 'claude', label: 'Claude Code', recommended: false, providerCompatible: false,
-    providerSupport: 'anthropic-required',
-  },
-  {
-    kind: 'gemini', label: 'Gemini CLI', recommended: false, providerCompatible: false,
-    providerSupport: 'native-config',
-  },
-  {
-    kind: 'opencode', label: 'OpenCode', recommended: false, providerCompatible: false,
-    providerSupport: 'native-config',
-  },
-  {
-    kind: 'qwen', label: 'Qwen Code', recommended: false, providerCompatible: true,
-    providerSupport: 'supported',
-  },
-  {
-    kind: 'opencodereview', label: 'OpenCodeReview', recommended: false, providerCompatible: true,
-    providerSupport: 'supported',
-  },
+  { kind: 'codex', label: 'Codex', recommended: false },
+  { kind: 'claude', label: 'Claude Code', recommended: false },
+  { kind: 'hermes', label: 'Hermes', recommended: true },
+  { kind: 'workbuddy', label: 'WorkBuddy', recommended: true },
+  { kind: 'openclaw', label: 'OpenClaw', recommended: true },
+  { kind: 'pi', label: 'Pi Agent', recommended: false },
+  { kind: 'opencode', label: 'OpenCode', recommended: false },
+  { kind: 'opencodereview', label: 'OpenCodeReview', recommended: false },
+  { kind: 'kimi', label: 'Kimi Code', recommended: false },
+  { kind: 'mimo', label: 'MiMo Code', recommended: false },
+  { kind: 'qwen', label: 'Qwen Code', recommended: false },
 ])
 
 function installRecipe(kind, platform) {
@@ -366,6 +350,7 @@ function verifiedRecipeAgent(agent, recipe) {
 }
 
 module.exports = {
+  installedVersionCurrent,
   AGENT_CATALOG,
   DETECTION_CACHE_TTL_MS,
   abortError,

desktop/src/agents/installer/agent-installer-runtime.cjs

@@ -68,7 +68,7 @@ function downloadResponse(url, signal, redirects = 0) {
 async function defaultDownloadScript(url, signal) {
   if (signal?.aborted) throw abortError()
   const parsed = validateScriptUrl(url)
-  const directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'roundrelay-agent-install-'))
+  const directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'meldwork-agent-install-'))
   const extension = parsed.pathname.endsWith('.ps1') ? '.ps1' : '.sh'
   const target = path.join(directory, `installer${extension}`)
   let bytes = 0
@@ -99,7 +99,7 @@ async function defaultDownloadScript(url, signal) {
 async function defaultRemoveDownload(target) {
   if (!target) return
   const directory = path.dirname(target)
-  if (!path.basename(directory).startsWith('roundrelay-agent-install-')) return
+  if (!path.basename(directory).startsWith('meldwork-agent-install-')) return
   await fs.promises.rm(directory, { recursive: true, force: true })
 }
 

desktop/src/agents/installer/agent-installer.cjs

@@ -3,6 +3,7 @@ const fs = require('node:fs')
 const { randomUUID } = require('node:crypto')
 const { DISPLAY_LIMIT, listLocalAgentSkills } = require('../../skills/local-skill-catalog.cjs')
 const {
+  installedVersionCurrent,
   AGENT_CATALOG,
   DETECTION_CACHE_TTL_MS,
   abortError,
@@ -60,12 +61,15 @@ function publicCompatibility(agent) {
     ? agent.versionIdentified
     : Boolean(resolvedVersion)
   const compatible = compatibilityState === 'compatible'
-  const incompatibilityReason = compatibilityState === 'incompatible'
+  const incompatibilityReason = compatibilityState === 'unknown'
+      && agent.incompatibilityReason === 'LOCAL_AGENT_CAPABILITY_PROBE_TIMEOUT'
+    ? 'LOCAL_AGENT_CAPABILITY_PROBE_TIMEOUT'
+    : compatibilityState === 'incompatible'
     ? (COMPATIBILITY_REASONS.has(agent.incompatibilityReason)
         ? agent.incompatibilityReason
         : 'LOCAL_AGENT_VERSION_UNSUPPORTED')
     : ''
-  const incompatibilityProbe = compatibilityState === 'incompatible'
+  const incompatibilityProbe = Boolean(incompatibilityReason)
     && /^[a-z0-9-]{1,80}$/.test(String(agent.incompatibilityProbe || ''))
     ? agent.incompatibilityProbe
     : ''
@@ -164,6 +168,10 @@ class AgentInstaller extends EventEmitter {
       agents: AGENT_CATALOG.map(profile => {
         const agent = installed.get(profile.kind)
         const recipe = installRecipe(profile.kind, this.platform)
+        const targetVersion = recipe?.detectedVersion || recipe?.version || ''
+        const currentVersion = String(agent?.version || '')
+        const upToDate = Boolean(agent && targetVersion
+          && installedVersionCurrent(currentVersion, targetVersion))
         let installSupported = Boolean(recipe)
         let installErrorCode = ''
         if (!recipe) {
@@ -177,6 +185,8 @@ class AgentInstaller extends EventEmitter {
           ...profile,
           installed: Boolean(agent),
           version: agent?.version || '',
+          targetVersion,
+          installAction: agent ? (upToDate ? 'current' : 'update') : 'install',
           ...publicCompatibility(agent),
           installSupported,
           installErrorCode,
@@ -230,7 +240,10 @@ class AgentInstaller extends EventEmitter {
     this.invalidateDetectionCache()
     const installed = await abortable(this.detectedAgents(), signal)
     if (signal.aborted) throw abortError()
-    if (installed.some(agent => agent.kind === profile.kind)) {
+    const current = installed.find(agent => agent.kind === profile.kind)
+    const targetVersion = recipe.detectedVersion || recipe.version
+    if (current && (current.compatibilityState !== 'compatible'
+      || installedVersionCurrent(current.version, targetVersion))) {
       throw installerError('INSTALL_AGENT_ALREADY_INSTALLED')
     }
     let command = recipe.interpreter || ''
@@ -295,7 +308,9 @@ class AgentInstaller extends EventEmitter {
           throw installerError('INSTALL_AGENT_INTEGRITY_FAILED')
         }
         args = [
-          'install', '--global', npmPackageSpec(recipe),
+          'install', '--global',
+          ...(recipe.ignoreScripts ? ['--ignore-scripts'] : []),
+          npmPackageSpec(recipe),
           '--registry', NPM_REGISTRY,
         ]
       }

desktop/src/agents/local-agent-readiness.cjs

@@ -1,10 +1,14 @@
 const { execFile } = require('node:child_process')
+const { createHash } = require('node:crypto')
 const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
 const { promisify } = require('node:util')
 const { prepareCommand, searchPath } = require('./cli/cli-adapters.cjs')
 const { isOpenClawSecretReference } = require('./cli/openclaw-runtime.cjs')
+const { NETWORK_ENV_KEYS, networkEnvironment } = require('./cli/cli-network-environment.cjs')
+const { workBuddyCredentialState } = require('./cli/workbuddy-runtime.cjs')
+const { mimoConfiguredProvider } = require('./cli/mimo-native-config.cjs')
 
 const execFileAsync = promisify(execFile)
 
@@ -27,12 +31,21 @@ const OPENCLAW_MODEL_INPUTS = new Set(['text', 'image', 'audio', 'video'])
 const MAX_CREDENTIAL_FILE_BYTES = 2 * 1024 * 1024
 const MAX_SHELL_ENV_BYTES = 256 * 1024
 const SHELL_ENV_CACHE_TTL_MS = 30000
-const SHELL_ENV_MARKER = '__ROUNDRELAY_NATIVE_ENV_V1__'
+// A login shell that loads nvm/conda/compinit can take several seconds,
+// especially right after boot or under load.
+const SHELL_ENV_TIMEOUT_MS = 10000
+// When the shell does not answer and nothing better is known, retry soon
+// instead of pinning the bare app environment for the whole cache window.
+const SHELL_ENV_FAILURE_TTL_MS = 5000
+const SHELL_ENV_MARKER = '__MELDWORK_NATIVE_ENV_V1__'
+const VERTEX_MODEL_REGION_KEY = /^VERTEX_REGION_[A-Z0-9_]{1,120}$/
 const CREDENTIAL_ENV_KEYS = Object.freeze({
   codex: ['OPENAI_API_KEY'],
   hermes: ['OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'ANTHROPIC_API_KEY'],
   openclaw: ['OPENAI_API_KEY', 'OPENROUTER_API_KEY'],
-  workbuddy: ['CODEBUDDY_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY'],
+  workbuddy: ['CODEBUDDY_API_KEY', 'CODEBUDDY_AUTH_TOKEN'],
+  zcode: ['ANTHROPIC_API_KEY'],
+  pi: ['PI_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY', 'GEMINI_API_KEY'],
   kimi: ['MOONSHOT_API_KEY', 'KIMI_API_KEY', 'KIMI_MODEL_API_KEY', 'OPENAI_API_KEY'],
   mimo: ['MIMO_API_KEY'],
   claude: ['ANTHROPIC_API_KEY'],
@@ -41,29 +54,60 @@ const CREDENTIAL_ENV_KEYS = Object.freeze({
   opencode: ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY'],
   opencodereview: ['OCR_LLM_TOKEN', 'OPENAI_API_KEY'],
 })
+const GOOGLE_CLOUD_ENV_KEYS = [
+  'GOOGLE_APPLICATION_CREDENTIALS', 'GOOGLE_CLOUD_PROJECT', 'GCLOUD_PROJECT',
+  'GOOGLE_CLOUD_LOCATION', 'GOOGLE_CLOUD_QUOTA_PROJECT', 'CLOUDSDK_CONFIG',
+]
 const RUNTIME_ENV_KEYS = Object.freeze({
-  codex: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL'],
+  codex: ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL', 'CODEX_HOME'],
   hermes: [
     'OPENAI_API_KEY', 'OPENROUTER_API_KEY', 'ANTHROPIC_API_KEY',
     'OPENAI_BASE_URL', 'OPENAI_MODEL', 'HERMES_INFERENCE_PROVIDER', 'HERMES_INFERENCE_MODEL',
+    'HERMES_HOME',
   ],
   openclaw: ['OPENAI_API_KEY', 'OPENROUTER_API_KEY'],
   workbuddy: [
-    'CODEBUDDY_API_KEY', 'CODEBUDDY_BASE_URL', 'CODEBUDDY_MODEL',
+    'CODEBUDDY_API_KEY', 'CODEBUDDY_AUTH_TOKEN', 'CODEBUDDY_BASE_URL', 'CODEBUDDY_MODEL',
+    'CODEBUDDY_CONFIG_DIR',
+  ],
+  zcode: ['ANTHROPIC_API_KEY'],
+  pi: [
+    'PI_API_KEY', 'PI_BASE_URL', 'PI_MODEL',
     'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL', 'ANTHROPIC_API_KEY',
+    'OPENROUTER_API_KEY', 'GEMINI_API_KEY', 'PI_CODING_AGENT_DIR',
   ],
   kimi: [
     'MOONSHOT_API_KEY', 'KIMI_API_KEY', 'KIMI_MODEL_API_KEY',
     'KIMI_MODEL_BASE_URL', 'KIMI_MODEL_NAME',
+    'KIMI_MODEL_PROVIDER_TYPE', 'KIMI_MODEL_CAPABILITIES',
+    'KIMI_MODEL_MAX_CONTEXT_SIZE', 'KIMI_MODEL_MAX_OUTPUT_SIZE',
+    'KIMI_CODE_HOME',
     'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL',
   ],
-  mimo: ['MIMO_API_KEY', 'MIMO_BASE_URL', 'MIMO_MODEL'],
-  claude: ['ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_MODEL'],
-  qwen: ['DASHSCOPE_API_KEY', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL'],
-  gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GEMINI_MODEL'],
+  mimo: ['MIMO_API_KEY', 'MIMO_BASE_URL', 'MIMO_MODEL', 'MIMOCODE_CONFIG_DIR', 'MIMOCODE_CONFIG_CONTENT'],
+  claude: [
+    'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN',
+    'ANTHROPIC_BASE_URL', 'ANTHROPIC_MODEL', 'CLAUDE_CONFIG_DIR',
+    'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+    'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'CLAUDE_CODE_USE_MANTLE',
+    'AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN', 'AWS_BEARER_TOKEN_BEDROCK',
+    'AWS_PROFILE', 'AWS_REGION', 'AWS_DEFAULT_REGION', 'AWS_CONFIG_FILE', 'AWS_SHARED_CREDENTIALS_FILE',
+    'AWS_ROLE_ARN', 'AWS_ROLE_SESSION_NAME', 'AWS_WEB_IDENTITY_TOKEN_FILE',
+    'ANTHROPIC_BEDROCK_BASE_URL', 'ANTHROPIC_BEDROCK_MANTLE_BASE_URL', 'ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION',
+    ...GOOGLE_CLOUD_ENV_KEYS,
+    'CLOUD_ML_REGION', 'ANTHROPIC_VERTEX_PROJECT_ID', 'ANTHROPIC_VERTEX_BASE_URL',
+    'ANTHROPIC_FOUNDRY_RESOURCE', 'ANTHROPIC_FOUNDRY_BASE_URL',
+    'ANTHROPIC_FOUNDRY_API_KEY', 'ANTHROPIC_FOUNDRY_AUTH_TOKEN',
+    'AZURE_CLIENT_ID', 'AZURE_TENANT_ID', 'AZURE_CLIENT_SECRET', 'AZURE_AUTHORITY_HOST',
+    'AZURE_CLIENT_CERTIFICATE_PATH', 'AZURE_CLIENT_CERTIFICATE_PASSWORD', 'AZURE_FEDERATED_TOKEN_FILE',
+    'AZURE_CONFIG_DIR',
+  ],
+  qwen: ['DASHSCOPE_API_KEY', 'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL', 'QWEN_HOME'],
+  gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GEMINI_MODEL', 'GOOGLE_GEMINI_BASE_URL', ...GOOGLE_CLOUD_ENV_KEYS],
   opencode: [
     'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENROUTER_API_KEY',
     'OPENAI_BASE_URL', 'OPENAI_MODEL',
+    'OPENCODE_CONFIG', 'OPENCODE_CONFIG_DIR', 'OPENCODE_CONFIG_CONTENT',
   ],
   opencodereview: [
     'OCR_LLM_TOKEN', 'OCR_LLM_URL', 'OCR_LLM_MODEL', 'OCR_USE_ANTHROPIC',
@@ -72,6 +116,7 @@ const RUNTIME_ENV_KEYS = Object.freeze({
 })
 const SHELL_ENV_KEYS = Object.freeze([...new Set([
   'PATH',
+  ...NETWORK_ENV_KEYS,
   ...Object.values(RUNTIME_ENV_KEYS).flat(),
 ])])
 let shellEnvironmentCache = null
@@ -89,6 +134,8 @@ function readCredentialFile(filename) {
 function containsCredential(value) {
   if (!value || typeof value !== 'object') return false
   if (Array.isArray(value)) return value.some(containsCredential)
+  if (value.type === 'api_key' && credentialLiteral(value.key)) return true
+  if (value.type === 'oauth' && (credentialLiteral(value.access) || credentialLiteral(value.refresh))) return true
   return Object.entries(value).some(([key, child]) => {
     if (CREDENTIAL_FIELD.test(key) && credentialLiteral(child)) return true
     return child && typeof child === 'object' && containsCredential(child)
@@ -128,8 +175,10 @@ function textContainsCredential(filename) {
 
 function nativeCredentialEnvironment(kind, env = process.env) {
   const result = {}
-  for (const key of RUNTIME_ENV_KEYS[kind] || []) {
-    if (typeof env[key] === 'string' && env[key].trim()) result[key] = env[key]
+  const keys = [...(RUNTIME_ENV_KEYS[kind] || []), ...(kind === 'claude'
+    ? Object.keys(env).filter(key => VERTEX_MODEL_REGION_KEY.test(key)) : [])]
+  for (const key of keys) {
+    if (typeof env[key] === 'string') result[key] = env[key]
   }
   return result
 }
@@ -142,24 +191,42 @@ function nativeCredentialKeyEnvironment(kind, env = process.env) {
   return result
 }
 
-function allowedShellEnvironment(env = process.env) {
+function allowedShellEnvironment(env = process.env, platform = process.platform) {
+  const source = { ...env, ...networkEnvironment(env, platform) }
   const result = {}
-  for (const key of SHELL_ENV_KEYS) {
-    const value = env[key]
-    if (typeof value !== 'string' || !value || value.length > MAX_SHELL_ENV_BYTES) continue
+  for (const key of [...SHELL_ENV_KEYS, ...Object.keys(source).filter(key => VERTEX_MODEL_REGION_KEY.test(key))]) {
+    const value = source[key]
+    if (typeof value !== 'string' || value.length > MAX_SHELL_ENV_BYTES) continue
     result[key] = value
   }
   return result
 }
 
-function nativeShellCommand() {
+function nativeShellCommand(shellName) {
   const keys = SHELL_ENV_KEYS.join(' ')
+  // Enumerate names only; do not dump unrelated values or depend on Electron RunAsNode.
+  const regionNames = shellName === 'zsh'
+    ? 'builtin print -rl -- ${(k)parameters[(I)VERTEX_REGION_*]}'
+    : [
+        'if [ -n "${BASH_VERSION-}" ]; then',
+        '  builtin compgen -e VERTEX_REGION_',
+        'elif [ -x /bin/bash ]; then',
+        "  BASH_ENV= ENV= /bin/bash --noprofile --norc -c 'builtin compgen -e VERTEX_REGION_'",
+        'fi',
+      ].join('\n')
   return [
     `printf '${SHELL_ENV_MARKER}\\0'`,
-    `for __roundrelay_key in ${keys}; do`,
-    '  eval "__roundrelay_value=\\${$__roundrelay_key-}"',
-    '  if [ -n "$__roundrelay_value" ]; then',
-    "    printf '%s=%s\\0' \"$__roundrelay_key\" \"$__roundrelay_value\"",
+    `for __meldwork_key in ${keys} $(${regionNames}); do`,
+    '  case "$__meldwork_key" in ""|*[!A-Za-z0-9_]*) continue ;; esac',
+    '  case "$__meldwork_key" in VERTEX_REGION_*)',
+    '    __meldwork_model=${__meldwork_key#VERTEX_REGION_}',
+    '    case "$__meldwork_model" in ""|*[!A-Z0-9_]*) continue ;; esac',
+    '    [ ${#__meldwork_model} -le 120 ] || continue ;;',
+    '  esac',
+    '  eval "__meldwork_value=\\${$__meldwork_key-}"',
+    '  eval "__meldwork_set=\\${$__meldwork_key+x}"',
+    '  if [ -n "$__meldwork_set" ]; then',
+    "    printf '%s=%s\\0' \"$__meldwork_key\" \"$__meldwork_value\"",
     '  fi',
     'done',
   ].join('\n')
@@ -177,7 +244,8 @@ function parseNativeShellEnvironment(output) {
     if (separator <= 0) continue
     const key = entry.slice(0, separator)
     const value = entry.slice(separator + 1)
-    if (!allowed.has(key) || !value || value.length > MAX_SHELL_ENV_BYTES) continue
+    if ((!allowed.has(key) && !VERTEX_MODEL_REGION_KEY.test(key))
+        || value.length > MAX_SHELL_ENV_BYTES) continue
     result[key] = value
   }
   return result
@@ -187,7 +255,7 @@ async function queryNativeShellEnvironment(options = {}) {
   const source = options.env || process.env
   const platform = options.platform || process.platform
   const home = options.home || os.homedir()
-  const fallback = allowedShellEnvironment(source)
+  const fallback = allowedShellEnvironment(source, platform)
   if (platform === 'win32') return { env: fallback, source: 'process' }
   const shell = String(options.shell || source.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/sh'))
   const shellName = path.basename(shell)
@@ -202,9 +270,9 @@ async function queryNativeShellEnvironment(options = {}) {
   try {
     const result = await execFileFn(
       shell,
-      [shellName === 'sh' ? '-lc' : '-lic', nativeShellCommand()],
+      [shellName === 'sh' ? '-lc' : '-lic', nativeShellCommand(shellName)],
       {
-        timeout: 5000,
+        timeout: SHELL_ENV_TIMEOUT_MS,
         maxBuffer: MAX_SHELL_ENV_BYTES,
         windowsHide: true,
         env: childEnv,
@@ -216,30 +284,61 @@ async function queryNativeShellEnvironment(options = {}) {
       source: Object.keys(loaded).some(key => key !== 'PATH') ? 'native-shell' : 'process',
     }
   } catch {
-    return { env: fallback, source: 'process' }
+    return { env: fallback, source: 'process', failed: true }
   }
 }
 
+function publicShellEnvironment({ env, source }) {
+  return { env, source }
+}
+
+let lastGoodShellEnvironment = null
+
 function resolveNativeShellEnvironment(options = {}) {
   const useCache = options.cache !== false && !options.execFileFn
-  if (!useCache) return queryNativeShellEnvironment(options)
+  if (!useCache) return queryNativeShellEnvironment(options).then(publicShellEnvironment)
   const source = options.env || process.env
   const platform = options.platform || process.platform
   const home = options.home || os.homedir()
   const shell = String(options.shell || source.SHELL || '')
-  const key = [platform, home, shell, String(source.PATH || '')].join('\u0000')
+  const environmentHash = createHash('sha256')
+    .update(JSON.stringify(allowedShellEnvironment(source, platform))).digest('hex')
+  const key = [platform, home, shell, environmentHash].join('\u0000')
   const now = Date.now()
-  if (shellEnvironmentCache?.key === key && shellEnvironmentCache.expiresAt > now) {
+  if (options.refresh !== true && shellEnvironmentCache?.key === key
+      && shellEnvironmentCache.expiresAt > now) {
     return shellEnvironmentCache.promise
   }
-  const promise = queryNativeShellEnvironment(options)
-  shellEnvironmentCache = { key, expiresAt: now + SHELL_ENV_CACHE_TTL_MS, promise }
-  return promise
+  // The window is measured from when the capture finishes, so a capture that
+  // used up its whole timeout is not already stale when it returns.
+  const entry = { key, promise: null, expiresAt: now + SHELL_ENV_CACHE_TTL_MS }
+  entry.promise = queryNativeShellEnvironment(options).then((result) => {
+    entry.expiresAt = Date.now() + SHELL_ENV_CACHE_TTL_MS
+    if (!result.failed) {
+      if (result.source === 'native-shell') lastGoodShellEnvironment = { key, result }
+      return publicShellEnvironment(result)
+    }
+    // The login shell did not answer (slow rc file, timeout, startup error).
+    // The bare app environment has none of the user's PATH entries or API
+    // keys, so an Agent started with it fails with misleading sign-in errors.
+    // Keep using what the shell last produced for this account instead.
+    if (lastGoodShellEnvironment?.key === key) {
+      return publicShellEnvironment(lastGoodShellEnvironment.result)
+    }
+    entry.expiresAt = Date.now() + SHELL_ENV_FAILURE_TTL_MS
+    return publicShellEnvironment(result)
+  })
+  shellEnvironmentCache = entry
+  return entry.promise
 }
 
 function nativeCredentialState(kind, options = {}) {
+  if (kind === 'workbuddy') return workBuddyCredentialState(options)
   const home = options.home || os.homedir()
   const env = options.env || process.env
+  const codexHome = env.CODEX_HOME || path.join(home, '.codex')
+  const claudeHome = env.CLAUDE_CONFIG_DIR || path.join(home, '.claude')
+  const piHome = env.PI_CODING_AGENT_DIR || path.join(home, '.pi', 'agent')
   if (Object.keys(nativeCredentialKeyEnvironment(kind, env)).length) {
     return {
       state: 'ready',
@@ -248,22 +347,30 @@ function nativeCredentialState(kind, options = {}) {
   }
 
   const jsonFiles = {
-    codex: [path.join(home, '.codex', 'auth.json'), path.join(home, '.codex', 'config.json')],
+    zcode: [path.join(home, '.zcode', 'cli', 'config.json')],
+    codex: [path.join(codexHome, 'auth.json'), path.join(codexHome, 'config.json')],
     hermes: [path.join(home, '.hermes', 'auth.json'), path.join(home, '.hermes', 'config.json')],
     openclaw: [path.join(home, '.openclaw', 'openclaw.json')],
-    workbuddy: [path.join(home, '.workbuddy', 'models.json')],
+    pi: [
+      path.join(piHome, 'auth.json'),
+      path.join(piHome, 'models.json'),
+      path.join(home, '.pi', 'auth.json'),
+      path.join(home, '.pi', 'config.json'),
+      path.join(home, '.pi-agent', 'auth.json'),
+      path.join(home, '.pi-agent', 'config.json'),
+    ],
     kimi: [path.join(home, '.kimi-code', 'credentials', 'kimi-code.json')],
     claude: [
-      path.join(home, '.claude', '.credentials.json'),
-      path.join(home, '.claude', 'settings.json'),
-      path.join(home, '.claude', 'settings.local.json'),
+      path.join(claudeHome, '.credentials.json'),
+      path.join(claudeHome, 'settings.json'),
+      path.join(claudeHome, 'settings.local.json'),
     ],
     qwen: [path.join(home, '.qwen', 'oauth_creds.json'), path.join(home, '.qwen', 'settings.json')],
     gemini: [
       path.join(home, '.gemini', 'oauth_creds.json'),
       path.join(home, '.gemini', 'settings.json'),
     ],
-    opencode: [path.join(home, '.local', 'share', 'opencode', 'auth.json')],
+    opencode: [path.join(env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'opencode', 'auth.json')],
     opencodereview: [path.join(home, '.opencodereview', 'config.json')],
   }[kind] || []
   if (jsonFiles.some(jsonContainsCredential)) {
@@ -271,21 +378,26 @@ function nativeCredentialState(kind, options = {}) {
   }
 
   const textFiles = {
-    codex: [path.join(home, '.codex', '.env'), path.join(home, '.codex', 'config.toml')],
+    codex: [path.join(codexHome, '.env'), path.join(codexHome, 'config.toml')],
     hermes: [
       path.join(home, '.hermes', '.env'),
       path.join(home, '.hermes', 'config.yaml'),
       path.join(home, '.hermes', 'config.yml'),
     ],
     openclaw: [path.join(home, '.openclaw', '.env')],
-    workbuddy: [path.join(home, '.workbuddy', '.env')],
+    pi: [
+      path.join(home, '.pi', '.env'),
+      path.join(home, '.pi', 'config.toml'),
+      path.join(home, '.pi-agent', '.env'),
+      path.join(home, '.pi-agent', 'config.toml'),
+    ],
     kimi: [
       path.join(home, '.kimi', 'config.toml'),
       path.join(home, '.kimi-code', 'config.toml'),
       path.join(home, '.kimi-code', '.env'),
     ],
     mimo: [path.join(home, '.mimo', '.env'), path.join(home, '.mimocode', '.env')],
-    claude: [path.join(home, '.claude', '.env')],
+    claude: [path.join(claudeHome, '.env')],
     qwen: [path.join(home, '.qwen', '.env')],
     gemini: [path.join(home, '.gemini', '.env')],
     opencode: [
@@ -305,13 +417,14 @@ function probeEnvironment(kind, options = {}) {
   const source = options.env || process.env
   const platform = options.platform || process.platform
   const home = options.home || os.homedir()
-  const env = {}
+  const env = networkEnvironment(source, platform)
   for (const key of [
     'USER', 'LOGNAME', 'TMPDIR', 'TMP', 'TEMP',
     'LANG', 'LANGUAGE', 'LC_ALL', 'LC_CTYPE',
     'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'USERNAME',
     'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT',
     'APPDATA', 'LOCALAPPDATA',
+    'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME',
   ]) {
     if (typeof source[key] === 'string' && source[key]) env[key] = source[key]
   }
@@ -325,6 +438,13 @@ function probeEnvironment(kind, options = {}) {
 function claudeAuthState(output) {
   try {
     const status = JSON.parse(String(output || '').trim())
+    // Cloud status recognizes a provider selection without checking SDK credentials.
+    if (status?.loggedIn === true && status.authMethod === 'third_party') {
+      return { state: 'unknown', source: 'unverified' }
+    }
+    if (status?.loggedIn === true && status.authMethod === 'api_key') {
+      return { state: 'ready', source: 'native-credential' }
+    }
     if (status?.loggedIn === true) return { state: 'ready', source: 'native-auth-status' }
     if (status?.loggedIn === false) return { state: 'missing', source: 'native-auth-status' }
   } catch { /* keep the file-based result */ }
@@ -633,8 +753,12 @@ async function queryMimoAuthState(options = {}) {
 }
 
 async function resolveNativeCredentialState(kind, options = {}) {
+  if (kind === 'workbuddy') return workBuddyCredentialState(options)
   const current = nativeCredentialState(kind, options)
   if (kind === 'mimo') {
+    if (current.state === 'ready' || mimoConfiguredProvider(options)) {
+      return { state: 'ready', source: 'native-credential' }
+    }
     return await queryMimoAuthState(options) || current
   }
   if (kind === 'openclaw') {
@@ -649,8 +773,7 @@ async function resolveNativeCredentialState(kind, options = {}) {
       ? status.credentialState
       : { state: 'unknown', source: 'native-runtime-unavailable' }
   }
-  if (kind !== 'claude' || !options.executable
-      || Object.keys(nativeCredentialKeyEnvironment(kind, options.env)).length) return current
+  if (kind !== 'claude' || !options.executable) return current
 
   const platform = options.platform || process.platform
   const prepareCommandFn = options.prepareCommandFn || prepareCommand

desktop/src/attachments/attachment-service.cjs

@@ -7,11 +7,20 @@ const {
 
 const MEDIA_SCHEME = 'meldwork-media'
 const ATTACHMENT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/
-const MAX_ATTACHMENT_PICK_REQUEST = 4
-const MAX_ATTACHMENT_DISCARD_REQUEST = 4
+const MAX_ATTACHMENT_PICK_REQUEST = 32
+const MAX_ATTACHMENT_DISCARD_REQUEST = 32
 
 function attachmentIdsFromSnapshot(snapshot, groupId = '') {
   const ids = []
+  for (const task of snapshot?.deliveryTasks || []) {
+    if (groupId && task.groupId !== groupId) continue
+    for (const version of task.versions) {
+      for (const attachment of version.attachments) ids.push(attachment.id)
+    }
+    for (const attempt of task.attempts) {
+      for (const source of attempt.sources) if (source.attachmentId) ids.push(source.attachmentId)
+    }
+  }
   for (const message of Array.isArray(snapshot?.messages) ? snapshot.messages : []) {
     if (groupId && message?.groupId !== groupId) continue
     for (const attachment of Array.isArray(message?.attachments) ? message.attachments : []) {

desktop/src/collaboration/answer-marker-filter.cjs

@@ -0,0 +1,81 @@
+const { V4_RECEIPT_MARKER_PREFIX } = require('./collaboration-receipt.cjs')
+
+// Control markers an Agent appends to its answer. They steer the harness and
+// must never reach the user's screen, even while the answer is still streaming.
+const CONSENSUS_MARKERS = Object.freeze([
+  '[[MELDWORK_CONSENSUS:agree]]',
+  '[[MELDWORK_CONSENSUS:continue]]',
+])
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+// Length of the longest buffer suffix that could still grow into a marker.
+function heldSuffixLength(buffer, markers) {
+  let hold = 0
+  for (const marker of markers) {
+    for (let size = Math.min(marker.length - 1, buffer.length); size > hold; size -= 1) {
+      if (buffer.slice(-size).toLowerCase() === marker.slice(0, size).toLowerCase()) {
+        hold = size
+        break
+      }
+    }
+  }
+  return hold
+}
+
+// Streams answer deltas through a marker filter.
+//   plain    nothing to hide: deltas pass through untouched.
+//   auto     hide the legacy consensus markers.
+//   receipt  hide the consensus markers and everything from the start of the
+//            collaboration receipt on (the receipt is parsed from the final text).
+// `push` returns the text that is safe to show now; text that might be the
+// start of a marker is held back until the next delta settles it, and
+// `flush` releases what is left once the answer has finished.
+function createAnswerMarkerFilter({ mode = 'plain' } = {}) {
+  if (mode === 'plain') {
+    return { push: delta => String(delta || ''), flush: () => '' }
+  }
+  const hideReceipt = mode === 'receipt'
+  const markers = hideReceipt
+    ? [...CONSENSUS_MARKERS, V4_RECEIPT_MARKER_PREFIX]
+    : [...CONSENSUS_MARKERS]
+  const pattern = new RegExp(markers.map(escapeRegExp).join('|'), 'i')
+  let buffer = ''
+  let receiptStarted = false
+  return {
+    push(delta) {
+      if (receiptStarted) return ''
+      buffer += String(delta || '')
+      let visible = ''
+      while (buffer && !receiptStarted) {
+        const match = pattern.exec(buffer)
+        if (match) {
+          visible += buffer.slice(0, match.index)
+          buffer = buffer.slice(match.index + match[0].length)
+          if (hideReceipt
+              && match[0].toLowerCase() === V4_RECEIPT_MARKER_PREFIX.toLowerCase()) {
+            receiptStarted = true
+          }
+          continue
+        }
+        const hold = heldSuffixLength(buffer, markers)
+        visible += hold ? buffer.slice(0, -hold) : buffer
+        buffer = hold ? buffer.slice(-hold) : ''
+        break
+      }
+      return visible
+    },
+    flush(finalText = '') {
+      const rest = buffer
+      buffer = ''
+      if (!hideReceipt) return rest
+      // A held fragment is real answer text only when the final answer ends
+      // with it; otherwise it was the start of the (hidden) receipt.
+      return !receiptStarted && rest && String(finalText).endsWith(rest) ? rest : ''
+    },
+  }
+}
+
+module.exports = { CONSENSUS_MARKERS, createAnswerMarkerFilter }

desktop/src/collaboration/collaboration-receipt.cjs

@@ -0,0 +1,295 @@
+const { canonicalJson } = require('./context-pack-records.cjs')
+const { parseLenientTaskDecision } = require('./task-decision.cjs')
+
+const SHA256 = /^[a-f0-9]{64}$/
+
+const V4_AGENT_PHASES = new Set([
+  'proposal', 'discussion', 'challenge', 'work', 'synthesis', 'verification',
+])
+const V4_RECEIPT_MARKER_PREFIX = '[[MELDWORK_COLLABORATION'
+const V4_RECEIPT_MARKER = /\s*\[\[MELDWORK_COLLABORATION(?:_JSON)?:([\s\S]*?)\]\]/i
+const V4_RECEIPT_BLOCK = /\s*\[\[MELDWORK_COLLABORATION(?:_JSON)?\]\]([\s\S]*?)\[\[\/MELDWORK_COLLABORATION(?:_JSON)?\]\]/i
+const LEGACY_CONSENSUS_MARKER = /^\s*\[\[MELDWORK_CONSENSUS:(?:agree|continue)\]\]\s*$/gim
+const V4_RECEIPT_MAX_TEXT = 800
+const V4_RECEIPT_MAX_ITEMS = 16
+const V4_RECEIPT_MAX_BYTES = 16 * 1024
+
+function isV4InternalProtocolCommentary(value) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim()
+  if (!text || text.length > 4000 || /\[\[MELDWORK_COLLABORATION/i.test(text)) return false
+  const mentionsControl = /(?:\breceipt\b|structured marker|MELDWORK framework|ExitPlanMode|\u7ed3\u6784\u5316\s*receipt|receipt\s*\u6807\u8bb0)/i.test(text)
+  const describesInternalProcess = /(?:coordination\/self-introduction|not a code implementation task|no plan file|implementation planning|plan mode|waiting for (?:the )?(?:next|subsequent).*(?:phase|instruction)|\u534f\u4f5c\u534f\u8c03\u7c7b\u6587\u672c\u4ea7\u51fa|\u975e\u4ee3\u7801\u5b9e\u73b0\u4efb\u52a1|\u6267\u884c\u8ba1\u5212\u6d41\u7a0b|\u4e0d\u8c03\u7528\s*ExitPlanMode|\u672c\u8f6e\u4ea4\u4ed8|\u7b49\u5f85\u540e\u7eed.*(?:\u9636\u6bb5|\u6307\u4ee4))/i.test(text)
+  return mentionsControl && describesInternalProcess
+}
+
+function stripV4InternalProtocolTail(value) {
+  const paragraphs = String(value || '').trim().split(/\n{2,}/)
+  while (paragraphs.length && isV4InternalProtocolCommentary(paragraphs.at(-1))) {
+    paragraphs.pop()
+  }
+  return paragraphs.join('\n\n').trim()
+}
+
+function boundedReceiptText(value, limit = V4_RECEIPT_MAX_TEXT) {
+  if (typeof value !== 'string' || value.trim().length > limit) return ''
+  const text = cleanReceiptText(value, limit)
+  return text && !text.includes('\u0000') ? text : ''
+}
+
+function boundedReceiptList(value) {
+  if (value == null) return []
+  if (!Array.isArray(value) || value.length > V4_RECEIPT_MAX_ITEMS) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  const result = value.map(item => boundedReceiptText(item))
+  if (result.some(item => !item)) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  return result
+}
+
+// A decision that is still unreadable after normalisation is treated as no
+// decision: the orchestrator then asks the owner again instead of failing
+// the Agent and removing it from the discussion.
+function leniencyTaskDecision(value, summary) {
+  try {
+    return { taskDecision: parseLenientTaskDecision(value, { fallbackReason: summary }) }
+  } catch {
+    return {}
+  }
+}
+
+function parseV4CollaborationReceiptStrict(result, required = false, expectedPhase = '', options = {}) {
+  const rawText = typeof result?.text === 'string' ? result.text : ''
+  if (!required) return { text: rawText, collaboration: null }
+  let text = rawText
+  let receipt = result?.collaboration
+  // Natural discussion turns are free-form answers; a slightly malformed
+  // receipt there must not fail the turn and end the discussion. Strict
+  // phased-V4 receipts keep failing closed.
+  const lenient = expectedPhase === 'discussion'
+  let trailingVisibleText = ''
+  let unreadableReceipt = false
+  const block = rawText.match(V4_RECEIPT_BLOCK) || rawText.match(V4_RECEIPT_MARKER)
+  if (block) {
+    const markerStart = Number(block.index) || 0
+    const suffix = rawText.slice(markerStart + block[0].length).trim()
+    // A closing code fence after the receipt is formatting, not content.
+    if (suffix && !isV4InternalProtocolCommentary(suffix) && !/^[\s`~]*$/.test(suffix)) {
+      if (!lenient) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+      trailingVisibleText = suffix
+    }
+    const encoded = String(block[1] || '').trim()
+    if (!encoded || Buffer.byteLength(encoded) > V4_RECEIPT_MAX_BYTES) {
+      if (!lenient) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+      unreadableReceipt = true
+    }
+    if (!unreadableReceipt) {
+      try {
+        let parsed
+        try {
+          parsed = JSON.parse(encoded)
+        } catch (error) {
+          if (!lenient) throw error
+          // Common hand-written slips: smart quotes and trailing commas.
+          parsed = JSON.parse(encoded
+            .replace(/[\u201c\u201d]/g, '"')
+            .replace(/[\u2018\u2019]/g, "'")
+            .replace(/,\s*([}\]])/g, '$1'))
+        }
+        if (receipt != null && canonicalJson(receipt) !== canonicalJson(parsed)) {
+          throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_MISMATCH')
+        }
+        receipt = parsed
+      } catch (error) {
+        if (error?.message === 'LOCAL_RUN_COLLABORATION_RECEIPT_MISMATCH') throw error
+        if (!lenient) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+        unreadableReceipt = true
+      }
+    }
+    text = rawText.slice(0, markerStart) + (trailingVisibleText ? `\n\n${trailingVisibleText}` : '')
+  } else if (/\[\[MELDWORK_COLLABORATION/i.test(rawText)) {
+    if (!lenient) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    unreadableReceipt = true
+    text = rawText.slice(0, rawText.search(/\[\[MELDWORK_COLLABORATION/i))
+  }
+  if (unreadableReceipt) receipt = null
+  if (lenient && receipt && typeof receipt === 'object' && !Array.isArray(receipt)) {
+    // Keep only discussion fields and fill a missing summary, so an extra key
+    // or a long summary does not discard the Agent's whole contribution.
+    const decisionReason = typeof receipt.taskDecision?.reason === 'string'
+      ? receipt.taskDecision.reason
+      : ''
+    const summary = typeof receipt.summary === 'string' && receipt.summary.trim()
+      ? receipt.summary.trim().slice(0, V4_RECEIPT_MAX_TEXT)
+      : (decisionReason.trim().slice(0, V4_RECEIPT_MAX_TEXT) || 'Discussion contribution')
+    receipt = {
+      version: 1,
+      phase: 'discussion',
+      summary,
+      ...(receipt.taskDecision != null ? { taskDecision: receipt.taskDecision } : {}),
+    }
+  }
+  text = stripV4InternalProtocolTail(
+    text.replace(LEGACY_CONSENSUS_MARKER, '').replace(/\n{3,}/g, '\n\n'),
+  )
+  if (receipt == null && options.allowMissingV4Receipt === true && text) {
+    return { text, collaboration: null }
+  }
+  if (receipt == null && expectedPhase === 'proposal'
+      && options.allowMissingProposalReceipt === true && text) {
+    receipt = {
+      version: 1,
+      phase: 'proposal',
+      summary: 'The Agent returned a visible proposal without a structured receipt.',
+      capabilities: ['Delivered a user-facing proposal'],
+      intendedWork: ['Addressed the current user task'],
+      deliverables: ['Visible Agent response'],
+      dependencies: [],
+    }
+  }
+  if (receipt == null) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_REQUIRED')
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  try {
+    if (Buffer.byteLength(canonicalJson(receipt)) > V4_RECEIPT_MAX_BYTES) {
+      throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    }
+  } catch (error) {
+    if (error?.message === 'LOCAL_RUN_COLLABORATION_RECEIPT_INVALID') throw error
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  const phase = String(expectedPhase || '')
+  const summary = boundedReceiptText(receipt.summary)
+  const allowed = new Set([
+    'version', 'phase', 'summary',
+    ...(phase === 'discussion' ? ['taskDecision'] : []),
+    ...(['challenge', 'verification'].includes(phase) ? ['verdict'] : []),
+    ...(phase === 'proposal'
+      ? ['capabilities', 'intendedWork', 'deliverables', 'dependencies'] : []),
+    ...(phase === 'challenge'
+      ? [
+          'proposedAssignments', 'finalizerKind', 'verifierKinds',
+          'supportedPlanHash', 'agreeToPlan',
+        ] : []),
+    ...(phase === 'work' ? ['workItemId', 'deliverables'] : []),
+    ...(phase === 'synthesis' ? ['resolvedIssueIds'] : []),
+  ])
+  if (!V4_AGENT_PHASES.has(phase) || !summary
+      || Object.keys(receipt).some(key => !allowed.has(key))
+      || (receipt.version != null && receipt.version !== 1)
+      || (receipt.phase != null && receipt.phase !== phase)) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  if (['challenge', 'verification'].includes(phase)
+      && !['support', 'contradict'].includes(receipt.verdict)) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  const resolvedIssueIds = phase === 'synthesis'
+    ? boundedReceiptList(receipt.resolvedIssueIds)
+    : null
+  if (phase === 'synthesis' && !Array.isArray(receipt.resolvedIssueIds)) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  if (phase === 'challenge' && receipt.supportedPlanHash != null
+      && !SHA256.test(String(receipt.supportedPlanHash))) {
+    throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+  }
+  const proposalList = (field, requireItem = false) => {
+    if (!Array.isArray(receipt[field])) {
+      throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    }
+    const list = boundedReceiptList(receipt[field])
+    if (requireItem && list.length === 0) {
+      throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    }
+    return list
+  }
+  const boundedList = value => {
+    if (value == null) return []
+    if (!Array.isArray(value) || value.length > V4_RECEIPT_MAX_ITEMS) {
+      throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    }
+    const result = value.map(item => boundedReceiptText(item))
+    if (result.some(item => !item)) throw new Error('LOCAL_RUN_COLLABORATION_RECEIPT_INVALID')
+    return result
+  }
+  const normalized = {
+    version: 1,
+    phase,
+    summary,
+    ...(phase === 'discussion' && receipt.taskDecision != null
+      ? leniencyTaskDecision(receipt.taskDecision, summary) : {}),
+    ...(['challenge', 'verification'].includes(phase) ? { verdict: receipt.verdict } : {}),
+    ...(phase === 'proposal' ? {
+      capabilities: proposalList('capabilities', true),
+      intendedWork: proposalList('intendedWork', true),
+      deliverables: proposalList('deliverables', true),
+      dependencies: proposalList('dependencies'),
+    } : {}),
+    ...(phase === 'challenge' ? {
+      ...(Array.isArray(receipt.proposedAssignments)
+        ? {
+            proposedAssignments: receipt.proposedAssignments.map(assignment => (
+              assignment && typeof assignment === 'object' && !Array.isArray(assignment)
+                && assignment.role === 'finalizer'
+                ? { ...assignment, role: 'integrator' }
+                : assignment
+            )),
+          }
+        : {}),
+      ...(receipt.finalizerKind ? { finalizerKind: boundedReceiptText(receipt.finalizerKind, 120) } : {}),
+      ...(Array.isArray(receipt.verifierKinds) ? { verifierKinds: boundedList(receipt.verifierKinds) } : {}),
+      ...(receipt.supportedPlanHash ? { supportedPlanHash: receipt.supportedPlanHash } : {}),
+      ...(typeof receipt.agreeToPlan === 'boolean' ? { agreeToPlan: receipt.agreeToPlan } : {}),
+    } : {}),
+    ...(phase === 'work' ? {
+      ...(receipt.workItemId ? { workItemId: boundedReceiptText(receipt.workItemId, 120) } : {}),
+      deliverables: boundedList(receipt.deliverables),
+    } : {}),
+    ...(phase === 'synthesis' ? { resolvedIssueIds } : {}),
+  }
+  return { text, collaboration: Object.freeze(JSON.parse(canonicalJson(normalized))) }
+}
+
+function parseV4CollaborationReceipt(result, required = false, expectedPhase = '', options = {}) {
+  try {
+    return parseV4CollaborationReceiptStrict(result, required, expectedPhase, options)
+  } catch (error) {
+    const code = String(error?.message || '')
+    if (expectedPhase !== 'proposal'
+        || options.allowMissingProposalReceipt !== true
+        || !['LOCAL_RUN_COLLABORATION_RECEIPT_INVALID', 'LOCAL_RUN_COLLABORATION_RECEIPT_REQUIRED']
+          .includes(code)) {
+      throw error
+    }
+    const rawText = typeof result?.text === 'string' ? result.text : ''
+    const markerIndex = rawText.search(/\[\[MELDWORK_COLLABORATION/i)
+    const visibleText = (markerIndex >= 0 ? rawText.slice(0, markerIndex) : rawText)
+      .replace(LEGACY_CONSENSUS_MARKER, '')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim()
+    if (!visibleText) throw error
+    return {
+      text: visibleText,
+      collaboration: Object.freeze({
+        version: 1,
+        phase: 'proposal',
+        summary: 'The Agent returned a visible proposal without a valid structured receipt.',
+        capabilities: ['Delivered a user-facing proposal'],
+        intendedWork: ['Addressed the current user task'],
+        deliverables: ['Visible Agent response'],
+        dependencies: [],
+      }),
+    }
+  }
+}
+
+function cleanReceiptText(value, limit) {
+  return String(value || '').trim().slice(0, limit)
+}
+
+module.exports = {
+  V4_AGENT_PHASES,
+  V4_RECEIPT_MARKER_PREFIX,
+  parseV4CollaborationReceipt,
+}

desktop/src/collaboration/collaboration-records.cjs

@@ -3,6 +3,23 @@ const { z } = require('zod')
 
 const { canonicalJson } = require('./context-pack-records.cjs')
 const { redactSecrets } = require('../security/secret-redaction.cjs')
+const {
+  applyCollaborationReceipt,
+  buildCollaborationPackage,
+  collaborationPackageIndexText,
+  collaborationChars,
+  collaborationPayloadBudget,
+  createCollaborationReceipt,
+  createOrchestrationV4,
+  enforceCollaborationBudget,
+  parseCollaborationControlBlock,
+  parseCollaborationText,
+  parseOrchestrationV4,
+  parseResultCollaboration,
+  normalizeCollaborationControlBlock,
+  normalizeOrchestrationV4,
+  parseCollaborationReceipt,
+} = require('./orchestration-v4-records.cjs')
 
 const COLLABORATION_STATE_VERSION = 1
 const HANDOFF_VERSION = 1
@@ -17,6 +34,7 @@ const HANDOFF_ID = /^handoff-[a-f0-9]{64}$/
 const BLACKBOARD_ENTRY_ID = /^blackboard-entry-[a-f0-9]{64}$/
 const SHA256 = /^[a-f0-9]{64}$/
 const ROLES = ['primary', 'reviewer', 'arbiter']
+const OWNER_ROLES = [...ROLES, 'integrator', 'worker', 'verifier']
 const trustedStates = new WeakSet()
 
 function collaborationError(code) {
@@ -39,6 +57,7 @@ const publicIdSchema = z.string().regex(PUBLIC_ID)
 const handoffIdSchema = z.string().regex(HANDOFF_ID)
 const entryIdSchema = z.string().regex(BLACKBOARD_ENTRY_ID)
 const roleSchema = z.enum(ROLES)
+const ownerRoleSchema = z.enum(OWNER_ROLES)
 const boundedTextSchema = z.string().min(1).max(MAX_TEXT_CHARS)
 const optionalTextSchema = z.string().max(MAX_TEXT_CHARS)
 
@@ -51,6 +70,15 @@ const actorSchema = z.discriminatedUnion('type', [
   }),
 ])
 
+const ownerSchema = z.discriminatedUnion('type', [
+  z.strictObject({ type: z.literal('harness') }),
+  z.strictObject({
+    type: z.literal('agent'),
+    agentKind: publicIdSchema,
+    role: ownerRoleSchema,
+  }),
+])
+
 const destinationSchema = z.strictObject({
   agentKind: publicIdSchema,
   role: roleSchema,
@@ -106,7 +134,7 @@ const entryContentFields = {
   subject: boundedTextSchema,
   statement: optionalTextSchema,
   value: optionalTextSchema,
-  owner: actorSchema,
+  owner: ownerSchema,
   audience: audienceSchema,
   lifecycle: lifecycleSchema,
   provenance: provenanceSchema,
@@ -263,6 +291,13 @@ function validActor(value) {
     && PUBLIC_ID.test(value.agentKind) && ROLES.includes(value.role)
 }
 
+function validOwner(value) {
+  if (!isRecord(value) || !['harness', 'agent'].includes(value.type)) return false
+  if (value.type === 'harness') return exactFields(value, ['type'])
+  return exactFields(value, ['type', 'agentKind', 'role'])
+    && PUBLIC_ID.test(value.agentKind) && OWNER_ROLES.includes(value.role)
+}
+
 function validProvenance(value) {
   return exactFields(value, [
     'runId', 'taskId', 'round', 'agentRunId', 'artifactIds', 'evidenceIds',
@@ -316,7 +351,7 @@ function validEntryRecord(record) {
       || !validText(record.subject)
       || !validText(record.statement, false)
       || !validText(record.value, false)
-      || !validActor(record.owner)
+      || !validOwner(record.owner)
       || !exactFields(record.audience, ['roles', 'agentKinds'])
       || !uniqueValidArray(record.audience.roles, role => ROLES.includes(role), ROLES.length)
       || !uniqueValidArray(record.audience.agentKinds, id => PUBLIC_ID.test(id), 32)
@@ -498,9 +533,40 @@ function publicCollaborationText(value, limit = MAX_TEXT_CHARS) {
     .slice(0, limit)
 }
 
+const PRIVATE_FILESYSTEM_ROOT = /^\/(?:Users|home|private|var|tmp|etc|opt|Volumes|root|usr|System|Library|Applications|mnt|srv)(?:\/|$)/
+
+function peerPathText(candidate, workspaceRoot) {
+  const trailing = candidate.match(/[.,;:!?]+$/)?.[0] || ''
+  const clean = trailing ? candidate.slice(0, -trailing.length) : candidate
+  if (workspaceRoot && (clean === workspaceRoot || clean.startsWith(`${workspaceRoot}/`))) {
+    return `${clean === workspaceRoot ? '.' : clean.slice(workspaceRoot.length + 1)}${trailing}`
+  }
+  if (PRIVATE_FILESYSTEM_ROOT.test(clean)) return `[path]${trailing}`
+  // Routes and commands such as /api/users or /login are not local files.
+  return candidate
+}
+
+// Peer-visible text for natural discussion transcripts. Unlike
+// publicCollaborationText, files inside the shared workspace stay readable as
+// workspace-relative paths and non-filesystem tokens (API routes, slash
+// commands) are kept; other absolute local paths and secrets stay redacted.
+function peerCollaborationText(value, options = {}) {
+  const workspaceRoot = typeof options.workspaceRoot === 'string'
+    ? options.workspaceRoot.replace(/\/+$/, '')
+    : ''
+  return redactSecrets(String(value || ''))
+    .replace(/\bfile:\/\/(\/[^\s"'`<>]+)/giu, (_match, filePath) => peerPathText(filePath, workspaceRoot))
+    .replace(/(^|[\s("'`])(\/(?!\/)[^\s"'`<>)]*)/gmu, (_match, lead, candidate) => (
+      `${lead}${peerPathText(candidate, workspaceRoot)}`
+    ))
+    .replace(/\b[A-Za-z]:\\(?:[^\s"'`<>]+\\)*[^\s"'`<>]*/gu, '[path]')
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
+    .trim()
+}
+
 function collaborationPackageText(handoff, entries) {
   const lines = [
-    'ROUNDRELAY_COLLABORATION_PACKAGE_V1',
+    'MELDWORK_COLLABORATION_PACKAGE_V1',
     `Role: ${handoff.destination.role}`,
     `Objective: ${handoff.objective}`,
     `Expected output: ${handoff.expectedOutput}`,
@@ -522,6 +588,7 @@ function collaborationPackageText(handoff, entries) {
 }
 
 module.exports = {
+  peerCollaborationText,
   BLACKBOARD_ENTRY_VERSION,
   COLLABORATION_STATE_VERSION,
   HANDOFF_VERSION,
@@ -538,4 +605,19 @@ module.exports = {
   publicCollaborationText,
   roleForIndex,
   visibleBlackboardEntries,
+  applyCollaborationReceipt,
+  buildCollaborationPackage,
+  collaborationPackageIndexText,
+  collaborationChars,
+  collaborationPayloadBudget,
+  createCollaborationReceipt,
+  createOrchestrationV4,
+  enforceCollaborationBudget,
+  parseCollaborationControlBlock,
+  parseCollaborationText,
+  parseOrchestrationV4,
+  parseResultCollaboration,
+  normalizeCollaborationControlBlock,
+  normalizeOrchestrationV4,
+  parseCollaborationReceipt,
 }

desktop/src/collaboration/task-decision.cjs

@@ -0,0 +1,92 @@
+const { redactSecrets } = require('../security/secret-redaction.cjs')
+
+function parseTaskDecision(input) {
+  const invalid = () => { throw new Error('LOCAL_RUN_TASK_DECISION_INVALID') }
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+      || Object.keys(input).some(key => !['status', 'reason', 'deliverables', 'handoffTo', 'nextKinds', 'reviewedVersion'].includes(key))
+      || !['completed', 'continue', 'blocked', 'needs-human'].includes(input.status)) invalid()
+  const text = (value, limit) => {
+    if (typeof value !== 'string' || !value.trim() || value.length > limit
+        || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)) invalid()
+    return redactSecrets(value.trim())
+  }
+  const reason = text(input.reason, 1600)
+  if (!Array.isArray(input.deliverables) || input.deliverables.length > 16) invalid()
+  const deliverables = input.deliverables.map(value => text(value, 800))
+  if (input.status === 'completed' && !deliverables.length) invalid()
+  if (input.handoffTo != null && (input.status !== 'continue'
+      || typeof input.handoffTo !== 'string'
+      || !/^[a-z0-9][a-z0-9-]{0,79}$/.test(input.handoffTo))) invalid()
+  if (input.nextKinds != null && (!Array.isArray(input.nextKinds)
+      || input.nextKinds.length > 32
+      || input.nextKinds.some(kind => typeof kind !== 'string'
+        || !/^[a-z0-9][a-z0-9-]{0,79}$/i.test(kind))
+      || (input.nextKinds.length > 0 && input.status !== 'continue'))) invalid()
+  const nextKinds = input.nextKinds?.map(kind => kind.toLowerCase())
+  if (nextKinds && new Set(nextKinds).size !== nextKinds.length) invalid()
+  if (input.reviewedVersion != null && (typeof input.reviewedVersion !== 'string'
+      || !/^[a-f0-9]{64}$/.test(input.reviewedVersion))) invalid()
+  return {
+    status: input.status, reason, deliverables,
+    ...(input.handoffTo != null ? { handoffTo: input.handoffTo } : {}),
+    ...(nextKinds ? { nextKinds } : {}),
+    ...(input.reviewedVersion != null ? { reviewedVersion: input.reviewedVersion } : {}),
+  }
+}
+
+const STATUS_SYNONYMS = new Map([
+  ['completed', 'completed'], ['complete', 'completed'], ['done', 'completed'],
+  ['finished', 'completed'], ['success', 'completed'], ['succeeded', 'completed'],
+  ['continue', 'continue'], ['continuing', 'continue'], ['in-progress', 'continue'],
+  ['in_progress', 'continue'], ['ongoing', 'continue'], ['pending', 'continue'],
+  ['blocked', 'blocked'], ['blocker', 'blocked'],
+  ['needs-human', 'needs-human'], ['needs_human', 'needs-human'],
+  ['needs human', 'needs-human'], ['needshuman', 'needs-human'], ['human', 'needs-human'],
+])
+
+function agentKindToken(value) {
+  return typeof value === 'string'
+    ? value.trim().replace(/^@+/, '').toLowerCase()
+    : ''
+}
+
+// Agents write task decisions by hand at the end of free text. Small slips
+// (capitalised status, "done", an @handle, a single string instead of a list,
+// a completed answer without a separate file) used to fail the whole turn
+// and silently end the discussion. Normalise them first; the strict parser
+// still validates the result.
+function normalizeTaskDecision(input, options = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input
+  const status = STATUS_SYNONYMS.get(String(input.status || '').trim().toLowerCase())
+    || String(input.status || '')
+  const textList = value => (Array.isArray(value) ? value : (value == null ? [] : [value]))
+    .filter(item => typeof item === 'string' && item.trim())
+    .map(item => item.trim().slice(0, 800))
+    .slice(0, 16)
+  const reason = typeof input.reason === 'string' && input.reason.trim()
+    ? input.reason.trim().slice(0, 1600)
+    : String(options.fallbackReason || '').trim().slice(0, 1600) || 'No reason given.'
+  let deliverables = textList(input.deliverables)
+  // A completed answer is itself the deliverable when nothing else was named.
+  if (status === 'completed' && !deliverables.length) deliverables = ['The answer in this message']
+  const nextKinds = [...new Set(textList(input.nextKinds).map(agentKindToken).filter(Boolean))]
+  const handoffTo = agentKindToken(input.handoffTo)
+  return {
+    status,
+    reason,
+    deliverables,
+    ...(status === 'continue' && handoffTo ? { handoffTo } : {}),
+    // Keep an explicit list (even an empty one) so the stored decision says
+    // what the Agent wrote; peers can only be requested while continuing.
+    ...(input.nextKinds != null
+      ? { nextKinds: status === 'continue' ? nextKinds.slice(0, 32) : [] }
+      : {}),
+    ...(input.reviewedVersion != null ? { reviewedVersion: input.reviewedVersion } : {}),
+  }
+}
+
+function parseLenientTaskDecision(input, options = {}) {
+  return parseTaskDecision(normalizeTaskDecision(input, options))
+}
+
+module.exports = { normalizeTaskDecision, parseLenientTaskDecision, parseTaskDecision }

desktop/src/gates/human-gate-coordinator.cjs

@@ -208,9 +208,11 @@ class HumanGateCoordinator {
       status,
       optionId: option.optionId,
       actorId: input.actorId || 'local-user',
-      decidedAt: input.decidedAt || this.now(),
+      decidedAt: input.decidedAt || current.decision?.decidedAt || this.now(),
       ...(response ? { response } : {}),
     })
+    // Recovery owns recorded decisions; repeated submissions must not dispatch them again.
+    if (current.status !== 'pending') return publicHumanGate(record)
     this.clearExpiry(record.gateId)
     try {
       this.onResumed(record, record.decision)

desktop/src/main.cjs

@@ -1,6 +1,8 @@
 const electron = require('electron')
 const { app, BrowserWindow, dialog, ipcMain, Menu, Notification, protocol, shell } = electron
+const fs = require('node:fs')
 const path = require('node:path')
+const { redactSecrets } = require('./security/secret-redaction.cjs')
 const { AttachmentStore } = require('./attachments/attachment-store.cjs')
 const { ContentBlobStore } = require('./attachments/content-blob-store.cjs')
 const { ContextPackStore } = require('./collaboration/context-pack-store.cjs')
@@ -18,12 +20,19 @@ const {
   captureArtifactOutputState,
   importAgentOutputs,
 } = require('./agents/agent-output-importer.cjs')
-const { detectAgents, imageAttachmentLimit, runAgent } = require('./agents/cli/cli-adapters.cjs')
+const {
+  detectAgents,
+  imageAttachmentLimit,
+  runAgent,
+  shutdownAcpSessionRuntime,
+} = require('./agents/cli/cli-adapters.cjs')
 const { AgentInstaller } = require('./agents/installer/agent-installer.cjs')
+const { networkEnvironment } = require('./agents/cli/cli-network-environment.cjs')
 const { AgentConnectorInstanceStore } = require('./agents/connectors/agent-connector-instance-store.cjs')
 const { LocalAgentConnectors } = require('./agents/connectors/agent-connector-local.cjs')
 const { AgentConnectorPackageStore } = require('./agents/connectors/agent-connector-package-store.cjs')
 const { CloudAgentOperationStore } = require('./agents/cloud/cloud-agent-operation-store.cjs')
+const { CloudAgentBridgeStore } = require('./agents/cloud/cloud-agent-bridge.cjs')
 const {
   CloudAgentRuntime,
   createCloudAgentStartRetry = ({ runtime }) => Object.freeze({
@@ -41,9 +50,8 @@ const {
   resolveNativeShellEnvironment,
 } = require('./agents/local-agent-readiness.cjs')
 const { LocalWorkspace } = require('./workspace/local-workspace.cjs')
-const { MediaGenerationRuntime } = require('./media/media-generation-runtime.cjs')
-const { resolveMediaProvider } = require('./media/media-provider-resolution.cjs')
 const { registerDesktopIpc } = require('./shell/main-ipc.cjs')
+const { workBuddyEnvironment, workBuddySettings } = require('./agents/cli/workbuddy-runtime.cjs')
 const {
   isAllowedExternalUrl,
   isAllowedLocalNavigation: isAllowedLocalNavigationForPaths,
@@ -64,28 +72,41 @@ const {
   resolveKnowledgeBaseSources,
 } = require('./knowledge/local-knowledge-base.cjs')
 const { LocalKnowledgeConnectors } = require('./knowledge/local-knowledge-connectors.cjs')
-const { ProviderStore } = require('./providers/provider-store.cjs')
-const {
-  EXTERNAL_PROVIDER_KINDS,
-  providerAgentKind,
-  providerOptionsFor,
-} = require('./providers/provider-options.cjs')
+const { nativeOpenClawOptions } = require('./agents/cli/openclaw-runtime.cjs')
+const { migrateLegacyProductData } = require('./product-data-migration.cjs')
 const LOCAL_AGENT_KINDS = new Set([
-  'codex', 'hermes', 'openclaw', 'workbuddy', 'kimi', 'mimo', 'claude', 'gemini', 'opencode', 'qwen',
+  'codex', 'hermes', 'openclaw', 'workbuddy', 'zcode', 'pi', 'kimi', 'mimo', 'claude', 'gemini', 'opencode', 'qwen',
   'opencodereview',
 ])
 const QUIT_CLEANUP_TIMEOUT_MS = 2500
 let mainWindow = null
+
+// Faults outside a request handler are written to a small private log in
+// userData (secrets redacted, size-capped) instead of disappearing or
+// taking the app down, so instability reports have evidence.
+function recordMainProcessFault(kind, detail) {
+  const text = String(detail?.stack || detail?.message || detail || '').slice(0, 4000)
+  console.error(`[meldwork] ${kind}`, text)
+  try {
+    const file = path.join(app.getPath('userData'), 'meldwork-diagnostics.log')
+    try {
+      if (fs.statSync(file).size > 1024 * 1024) fs.renameSync(file, `${file}.1`)
+    } catch { /* first entry */ }
+    fs.appendFileSync(file, `${new Date().toISOString()} ${kind} ${redactSecrets(text)}\n`, { mode: 0o600 })
+  } catch { /* diagnostics must never throw */ }
+}
+process.on('unhandledRejection', reason => recordMainProcessFault('unhandledRejection', reason))
+process.on('uncaughtException', error => recordMainProcessFault('uncaughtException', error))
 let workspace = null
 let workspaceChangedListener = null
 let workspaceRunFinishedListener = null
 let workspaceRunEventListener = null
 let installer = null
 let localAgentRefreshQueue = Promise.resolve()
-let providerStore = null
 let customAgentStore = null
 let agentConnectors = null
 let cloudAgentRuntime = null
+let cloudAgentBridges = null
 let cloudAgentStartRetry = null
 let channelIngressRuntime = null
 let knowledgeBaseStore = null
@@ -218,21 +239,9 @@ function openExternalUrl(value) {
   return true
 }
 
-function providerOptions(kind, context = {}) {
-  if (!EXTERNAL_PROVIDER_KINDS.has(kind)) return {}
-  const status = providerStore?.status(kind) || {}
-  if (!status.configured && !(kind === 'openclaw' && context.nativeRuntime)) return {}
-  return providerOptionsFor(
-    kind,
-    status.configured ? providerStore.envForAgent(kind) : {},
-    context,
-    status,
-  )
-}
-
-async function nativeShellEnvironment() {
+async function nativeShellEnvironment(options = {}) {
   const home = app.getPath('home')
-  const resolved = await resolveNativeShellEnvironment({ home })
+  const resolved = await resolveNativeShellEnvironment({ home, refresh: options.refresh === true })
   return {
     ...resolved,
     env: { ...process.env, ...resolved.env },
@@ -245,39 +254,8 @@ async function detectLocalAgents() {
   return detectAgents({ env: shellEnvironment.env, home: shellEnvironment.home })
 }
 
-function mediaFallbackProviders(env = process.env) {
-  const apiKey = String(
-    env.ZGCI_MEDIA_API_KEY
-      || env.ZGCI_API_KEY
-      || env.ZCGI_API_KEY
-      || env.ZGCI_LLM_API_KEY
-      || '',
-  ).trim()
-  if (!apiKey) return []
-  const baseUrl = String(env.ZGCI_MEDIA_BASE_URL || 'https://hub.zgci.org/v1')
-    .trim()
-    .replace(/\/+$/, '')
-    .replace(/\/chat\/completions$/i, '')
-  let parsed
-  try { parsed = new URL(baseUrl) } catch { return [] }
-  if (parsed.protocol !== 'https:' || parsed.username || parsed.password
-      || parsed.search || parsed.hash) {
-    return []
-  }
-  return [{
-    kind: 'zgci-media',
-    status: {
-      configured: true,
-      provider: 'ZGCI Media',
-      baseUrl,
-      model: 'glm',
-    },
-    credentials: { OPENAI_API_KEY: apiKey },
-  }]
-}
-
 function workspaceStoragePath(userData = app.getPath('userData')) {
-  return path.join(userData, 'roundrelay-workspace.json')
+  return path.join(userData, 'meldwork-workspace.json')
 }
 
 function notifyWorkspaceChanged(snapshot) {
@@ -365,28 +343,34 @@ async function runCoreAgent(agent, prompt, workdir, options = {}) {
   const connectorCredentialIsolation = options.connectorCredentialIsolation === true
   const runOptions = { ...options }
   delete runOptions.connectorCredentialIsolation
-  const status = providerStore.status(agent.kind)
   const shellEnvironment = connectorCredentialIsolation ? null : await nativeShellEnvironment()
-  const nativeRuntime = !connectorCredentialIsolation
-    && agent.kind === 'openclaw' && !status.configured
+  // OpenClaw runs through its isolated native runtime scope; every other Agent
+  // CLI uses its own native credentials.
+  const nativeRuntime = !connectorCredentialIsolation && agent.kind === 'openclaw'
     ? await resolveNativeOpenClawRuntime({
         executable: agent.executable,
         env: shellEnvironment.env,
         home: shellEnvironment.home,
       })
     : null
-  const injected = connectorCredentialIsolation
+  const injected = connectorCredentialIsolation || agent.kind !== 'openclaw' || !nativeRuntime
     ? {}
-    : providerOptions(agent.kind, {
-        ...runOptions,
-        workdir,
+    : nativeOpenClawOptions({
         storageRoot: app.getPath('userData'),
-        nativeRuntime,
+        workdir,
+        sessionRef: runOptions.sessionRef,
+        allowWrite: runOptions.sandbox === 'workspace-write',
+        runtime: nativeRuntime,
+        openclawVersion: agent.version,
       })
   const nativeEnv = connectorCredentialIsolation || agent.kind === 'openclaw'
     ? {}
     : {
         ...nativeCredentialEnvironment(agent.kind, shellEnvironment.env),
+        ...(agent.kind === 'workbuddy' ? workBuddyEnvironment({
+          env: shellEnvironment.env, home: shellEnvironment.home,
+          modelId: workspace?.state.agentPreferences.workbuddy?.modelId,
+        }) : {}),
         ...(shellEnvironment.env.PATH ? { PATH: shellEnvironment.env.PATH } : {}),
       }
   const callerEnv = connectorCredentialIsolation || agent.kind !== 'openclaw'
@@ -395,19 +379,22 @@ async function runCoreAgent(agent, prompt, workdir, options = {}) {
   return runAgent(agent, prompt, workdir, {
     ...runOptions,
     ...injected,
-    env: { ...nativeEnv, ...callerEnv, ...injected.env },
+    env: {
+      ...networkEnvironment(shellEnvironment?.env),
+      ...nativeEnv, ...callerEnv, ...injected.env,
+    },
   })
 }
 
 function localAttachmentSupport(kind) {
   if (customAgentStore?.has(kind)) {
-    return { image: 4, audio: 4, video: 4, file: 4 }
+    return { image: 32, audio: 32, video: 32, file: 32 }
   }
   const connectorSupport = agentConnectors?.attachmentSupport(kind)
   if (connectorSupport) return connectorSupport
   return {
     image: imageAttachmentLimit(kind),
-    file: kind === 'opencodereview' ? 0 : 4,
+    file: kind === 'opencodereview' ? 0 : 32,
   }
 }
 
@@ -466,7 +453,7 @@ async function requestLocalSkillTrust({ binding, coordinates, manifest }) {
 
 function createWorkspace() {
   cloudAgentStartRetry?.cancel()
-  const privateRoot = path.join(app.getPath('userData'), 'roundrelay-private')
+  const privateRoot = path.join(app.getPath('userData'), 'meldwork-private')
   const contentBlobStore = new ContentBlobStore({
     rootPath: path.join(privateRoot, 'content-blobs'),
   })
@@ -500,13 +487,14 @@ function createWorkspace() {
       safeStorage: lazySafeStorage,
     }),
     runAgent: runCoreAgent,
+    cloudBridges: cloudAgentBridges,
   })
   const outcomeStore = new OutcomeStore({
     rootPath: path.join(privateRoot, 'outcomes'),
     contentBlobStore,
   })
   const runLedger = new RunLedger({
-    storagePath: path.join(app.getPath('userData'), 'roundrelay-run-ledger.json'),
+    storagePath: path.join(app.getPath('userData'), 'meldwork-run-ledger.json'),
   })
   const runtime = new CloudAgentRuntime({
     runLedger,
@@ -524,17 +512,6 @@ function createWorkspace() {
     }),
     connectors: [],
   })
-  const mediaGeneration = new MediaGenerationRuntime({
-    getProvider: (kind, type, excludedKinds) => resolveMediaProvider({
-      requestedKind: kind,
-      type,
-      kinds: EXTERNAL_PROVIDER_KINDS,
-      excludedKinds,
-      statusFor: candidateKind => providerStore.status(candidateKind),
-      credentialsFor: candidateKind => providerStore.envForAgent(candidateKind),
-      fallbackProviders: mediaFallbackProviders(),
-    }),
-  })
   const localWorkspace = new LocalWorkspace({
     storagePath: workspaceStoragePath(),
     contentBlobStore,
@@ -545,6 +522,7 @@ function createWorkspace() {
     agentFitMatrix: FROZEN_AGENT_FIT_MATRIX,
     runLedger: cloudAgentRuntime.workspaceLedger(),
     detectAgents: async () => {
+      await cloudAgentBridges?.refresh()
       const [installedAgents, customAgents] = await Promise.all([
         installer.detectedAgents(),
         customAgentStore.detectAgents(),
@@ -573,12 +551,12 @@ function createWorkspace() {
         env: shellEnvironment.env,
         home: shellEnvironment.home,
         credentialSource: shellEnvironment.source,
+        ...(kind === 'workbuddy' ? { modelId: workspace?.state.agentPreferences.workbuddy?.modelId } : {}),
       })
     },
     agentLabel: kind => customAgentStore.label(kind) || agentConnectors.label(kind),
-    sharedProviderReady: kind => EXTERNAL_PROVIDER_KINDS.has(kind) && providerStore.status(kind).configured,
     connectorRuntime: agentConnectors,
-    generateMedia: input => mediaGeneration.generate(input),
+    naturalAgentResponses: true,
     runAgent: async (agent, prompt, workdir, options = {}) => {
       if (customAgentStore.has(agent.kind)) {
         return customAgentStore.run(agent.kind, prompt, workdir, {
@@ -604,6 +582,7 @@ function createWorkspace() {
 }
 
 async function localAgentCatalog() {
+  await cloudAgentBridges?.refresh()
   const [catalog, customAgents, installedAgents] = await Promise.all([
     installer.catalog(),
     customAgentStore.catalog(),
@@ -611,10 +590,17 @@ async function localAgentCatalog() {
   ])
   agentConnectors?.refresh(installedAgents)
   const connectorAgents = agentConnectors?.catalog() || []
+  const mergedAgents = new Map()
+  for (const agent of [...catalog.agents, ...customAgents, ...connectorAgents]) {
+    mergedAgents.set(agent.kind, agent)
+  }
+  for (const agent of cloudAgentBridges?.catalogEntries?.() || []) {
+    mergedAgents.set(agent.kind, { ...(mergedAgents.get(agent.kind) || {}), ...agent })
+  }
   const states = new Map((workspace?.snapshot().agents || []).map(agent => [agent.kind, agent]))
   return {
     ...catalog,
-    agents: [...catalog.agents, ...customAgents, ...connectorAgents].map((agent) => {
+    agents: [...mergedAgents.values()].map((agent) => {
       const state = states.get(agent.kind)
       const support = localAttachmentSupport(agent.kind)
       return {
@@ -629,7 +615,9 @@ async function localAgentCatalog() {
         recentlyVerified: Boolean(agent.installed && state?.recentlyVerified),
         capabilities: state?.capabilities || agent.capabilities || null,
         available: Boolean(agent.installed && state?.invocable),
-        credentialState: agent.installed ? (state?.credentialState || 'unknown') : 'missing',
+        credentialState: agent.installed
+          ? (state?.credentialState || agent.credentialState || 'unknown')
+          : 'missing',
         availabilitySource: agent.installed ? (state?.availabilitySource || 'unverified') : 'none',
         showInSidebar: Boolean(agent.installed && state?.showInSidebar),
         attachmentTypes: Object.entries(support)
@@ -645,6 +633,7 @@ async function refreshLocalAgentState() {
   if (!target) return null
   const task = localAgentRefreshQueue.then(async () => {
     if (workspace !== target) return workspace?.snapshot() || null
+    await nativeShellEnvironment({ refresh: true })
     const snapshot = await target.refreshAgents()
     if (workspace !== target) return workspace?.snapshot() || null
     return snapshot
@@ -713,6 +702,14 @@ function createWindow() {
     showOfflinePage(errorCode)
   })
   mainWindow.webContents.on('did-finish-load', flushPendingOpenGroup)
+  // A crashed renderer used to leave a blank window; reload it so the
+  // workspace (whose state lives in the main process) comes back.
+  mainWindow.webContents.on('render-process-gone', (_event, details) => {
+    recordMainProcessFault('render-process-gone', details?.reason || 'unknown')
+    if (details?.reason !== 'clean-exit' && mainWindow && !mainWindow.isDestroyed()) {
+      mainWindow.webContents.reload()
+    }
+  })
   mainWindow.on('closed', () => {
     mainWindow = null
   })
@@ -749,8 +746,13 @@ function registerIpc() {
     getAttachmentStore: () => attachmentStore,
     getAgentConnectors: () => agentConnectors,
     getCloudAgentRuntime: () => cloudAgentRuntime,
+    getCloudAgentBridges: () => cloudAgentBridges,
     getMainWindow: () => mainWindow,
     getWorkspace: () => workspace,
+    getWorkBuddySettings: async () => {
+      const shell = await nativeShellEnvironment()
+      return workBuddySettings({ ...shell, modelId: workspace?.state.agentPreferences.workbuddy?.modelId })
+    },
     installer,
     isShutdownStarted: () => shutdownStarted,
     knowledgeBaseStore,
@@ -761,8 +763,6 @@ function registerIpc() {
     openExternalUrl,
     getOutcomeStore: () => workspace?.outcomeStore,
     getSkillTrustStore: () => skillTrustStore,
-    providerStore,
-    providerAgentKind,
     refreshLocalAgentState,
     registerTrustedHandle,
     skillCatalog,
@@ -777,17 +777,32 @@ if (!hasSingleInstanceLock) {
   app.on('second-instance', activateMainWindow)
 
   app.whenReady().then(async () => {
+    try {
+      migrateLegacyProductData(app.getPath('userData'))
+    } catch (error) {
+      console.error(
+        'MELDWORK_PRODUCT_DATA_MIGRATION_ABORTED',
+        error?.diagnostic || { status: 'failed', code: String(error?.code || '') },
+      )
+      app.quit()
+      return
+    }
     const attachmentReferences = persistedAttachmentReferences(workspaceStoragePath())
     customAgentStore = new CustomAgentStore({
-      storagePath: path.join(app.getPath('userData'), 'roundrelay-custom-agents.json'),
+      storagePath: path.join(app.getPath('userData'), 'meldwork-custom-agents.json'),
     })
-    providerStore = new ProviderStore({
-      storagePath: path.join(app.getPath('userData'), 'roundrelay-provider.json'),
-      safeStorage: lazySafeStorage,
-      allowedKinds: [...LOCAL_AGENT_KINDS],
+    cloudAgentBridges = new CloudAgentBridgeStore({
+      storagePath: path.join(app.getPath('userData'), 'meldwork-cloud-agent-bridges.json'),
+      fetch: globalThis.fetch,
     })
+    // The shared Provider store was removed; drop any legacy encrypted
+    // credentials so they do not linger on disk unread.
+    try {
+      const { rmSync } = require('node:fs')
+      rmSync(path.join(app.getPath('userData'), 'meldwork-provider.json'), { force: true })
+    } catch { /* best-effort cleanup */ }
     knowledgeBaseStore = new KnowledgeBaseStore({
-      storagePath: path.join(app.getPath('userData'), 'roundrelay-knowledge-base.json'),
+      storagePath: path.join(app.getPath('userData'), 'meldwork-knowledge-base.json'),
     })
     try {
       attachmentStore = new AttachmentStore({
@@ -855,8 +870,15 @@ if (!hasSingleInstanceLock) {
     if (installRunning) installer.cancel(installerState.taskId)
     quitCleanup = runQuitCleanup([
       () => channelIngressRuntime?.shutdown(),
+      () => cloudAgentBridges?.close(),
       () => cloudAgentRuntime?.shutdown(),
-      () => workspace?.stopAll(),
+      async () => {
+        try {
+          await workspace?.stopAll()
+        } finally {
+          await shutdownAcpSessionRuntime()
+        }
+      },
       () => installer?.waitForIdle(),
     ]).then(() => {
       app.exit(0)

desktop/src/preload.cjs

@@ -117,9 +117,30 @@ if (isLocalDocument) Object.assign(desktopApi, {
     ),
     cancel: runId => ipcRenderer.invoke('local-cloud-agent:cancel', runId),
   }),
+  cloudAgentBridge: Object.freeze({
+    list: () => ipcRenderer.invoke('local-cloud-agent-bridge:list'),
+    connect: input => ipcRenderer.invoke('local-cloud-agent-bridge:connect', input),
+    refresh: () => ipcRenderer.invoke('local-cloud-agent-bridge:refresh'),
+    delete: bridgeId => ipcRenderer.invoke('local-cloud-agent-bridge:delete', bridgeId),
+  }),
   localOutcome: Object.freeze({
     recordAdoption: input => ipcRenderer.invoke('local-outcome:record-adoption', input),
   }),
+  localDelivery: Object.freeze({
+    save: input => ipcRenderer.invoke('local-delivery:save', input),
+    review: input => ipcRenderer.invoke('local-delivery:review', input),
+    revise: input => ipcRenderer.invoke('local-delivery:revise', input),
+    reuse: input => ipcRenderer.invoke('local-delivery:reuse', input),
+    export: input => ipcRenderer.invoke('local-delivery:export', input),
+  }),
+  workBuddy: Object.freeze({
+    settings: () => ipcRenderer.invoke('local-workbuddy:settings'),
+    setModel: modelId => ipcRenderer.invoke('local-workbuddy:set-model', modelId),
+  }),
+  workPreferences: Object.freeze({
+    get: () => ipcRenderer.invoke('local-work-preferences:get'),
+    save: input => ipcRenderer.invoke('local-work-preferences:save', input),
+  }),
   agentInstaller: Object.freeze({
     catalog: () => ipcRenderer.invoke('local-agent-installer:catalog'),
     skills: kind => ipcRenderer.invoke('local-agent-installer:skills', kind),
@@ -170,13 +191,6 @@ if (isLocalDocument) Object.assign(desktopApi, {
     open: id => ipcRenderer.invoke('local-attachments:open', id),
     discard: ids => ipcRenderer.invoke('local-attachments:discard', ids),
   }),
-  localAgentProvider: Object.freeze({
-    status: kind => ipcRenderer.invoke('local-agent-provider:status', kind),
-    probe: kind => ipcRenderer.invoke('local-agent-provider:probe', kind),
-    save: (kind, input) => ipcRenderer.invoke('local-agent-provider:save', kind, input),
-    activate: (kind, preset) => ipcRenderer.invoke('local-agent-provider:activate', kind, preset),
-    delete: (kind, preset) => ipcRenderer.invoke('local-agent-provider:delete', kind, preset),
-  }),
   localKnowledgeBase: Object.freeze({
     status: kind => (kind ? ipcRenderer.invoke('local-knowledge-base:status', kind) : ipcRenderer.invoke('local-knowledge-base:status')),
     openGuide: (kind, action) => ipcRenderer.invoke('local-knowledge-base:open-guide', kind, action),
@@ -207,4 +221,4 @@ if (isLocalDocument) Object.assign(desktopApi, {
   }),
 })
 
-contextBridge.exposeInMainWorld('roundrelayDesktop', Object.freeze(desktopApi))
+contextBridge.exposeInMainWorld('meldworkDesktop', Object.freeze(desktopApi))

desktop/src/product-data-migration.cjs

@@ -0,0 +1,88 @@
+const fs = require('node:fs')
+const path = require('node:path')
+
+const LEGACY_PRODUCT_STEM = ['round', 'relay'].join('')
+
+const MIGRATIONS = Object.freeze([
+  ['workspace.json', 'workspace.json'],
+  ['run-ledger.json', 'run-ledger.json'],
+  ['custom-agents.json', 'custom-agents.json'],
+  ['knowledge-base.json', 'knowledge-base.json'],
+  ['private', 'private'],
+])
+
+function migrationFailure({ cause, failedStep, failedMove, completed, rolledBack, rollbackFailures }) {
+  const recoveryRequired = rollbackFailures.length > 0
+  const code = recoveryRequired
+    ? 'MELDWORK_PRODUCT_DATA_MIGRATION_RECOVERY_REQUIRED'
+    : 'MELDWORK_PRODUCT_DATA_MIGRATION_FAILED'
+  const error = new Error(code, { cause })
+  error.code = code
+  error.diagnostic = Object.freeze({
+    status: recoveryRequired ? 'recovery-required' : 'rolled-back',
+    failedStep,
+    failed: Object.freeze({
+      source: failedMove.source,
+      destination: failedMove.destination,
+      code: String(cause?.code || ''),
+    }),
+    completed: Object.freeze(completed.map(move => Object.freeze({ ...move }))),
+    rolledBack: Object.freeze(rolledBack.map(move => Object.freeze({ ...move }))),
+    rollbackFailures: Object.freeze(rollbackFailures.map(item => Object.freeze({
+      source: item.move.source,
+      destination: item.move.destination,
+      code: String(item.error?.code || ''),
+    }))),
+  })
+  return error
+}
+
+function migrateLegacyProductData(userData, options = {}) {
+  const root = path.resolve(String(userData || ''))
+  const renameSync = typeof options.renameSync === 'function' ? options.renameSync : fs.renameSync
+  const plan = MIGRATIONS.map(([legacySuffix, currentSuffix]) => ({
+    source: path.join(root, `${LEGACY_PRODUCT_STEM}-${legacySuffix}`),
+    destination: path.join(root, `meldwork-${currentSuffix}`),
+  }))
+  const migrated = []
+  const completed = []
+  for (let index = 0; index < plan.length; index += 1) {
+    const move = plan[index]
+    if (!fs.existsSync(move.source) || fs.existsSync(move.destination)) continue
+    try {
+      renameSync(move.source, move.destination)
+      completed.push(move)
+      migrated.push(move.destination)
+    } catch (cause) {
+      const rolledBack = []
+      const rollbackFailures = []
+      for (const completedMove of [...completed].reverse()) {
+        try {
+          const sourceExists = fs.existsSync(completedMove.source)
+          const destinationExists = fs.existsSync(completedMove.destination)
+          if (!sourceExists && destinationExists) {
+            renameSync(completedMove.destination, completedMove.source)
+          } else if (!(sourceExists && !destinationExists)) {
+            throw Object.assign(new Error('MELDWORK_PRODUCT_DATA_MIGRATION_ROLLBACK_CONFLICT'), {
+              code: 'MELDWORK_PRODUCT_DATA_MIGRATION_ROLLBACK_CONFLICT',
+            })
+          }
+          rolledBack.push(completedMove)
+        } catch (error) {
+          rollbackFailures.push({ move: completedMove, error })
+        }
+      }
+      throw migrationFailure({
+        cause,
+        failedStep: index + 1,
+        failedMove: move,
+        completed,
+        rolledBack,
+        rollbackFailures,
+      })
+    }
+  }
+  return migrated
+}
+
+module.exports = { migrateLegacyProductData }

desktop/src/providers/provider-options.cjs

@@ -1,171 +0,0 @@
-const { managedOpenClawOptions, nativeOpenClawOptions } = require('../agents/cli/openclaw-runtime.cjs')
-
-const EXTERNAL_PROVIDER_KINDS = new Set([
-  'codex', 'hermes', 'openclaw', 'workbuddy', 'kimi', 'mimo', 'claude', 'gemini', 'opencode', 'qwen',
-  'opencodereview',
-])
-
-const OFFICIAL_PROVIDER_BASE_URLS = Object.freeze({
-  codex: 'https://api.openai.com/v1',
-  hermes: 'https://api.openai.com/v1',
-  openclaw: 'https://api.openai.com/v1',
-  workbuddy: '',
-  kimi: 'https://api.moonshot.cn/v1',
-  mimo: '',
-  claude: 'https://api.anthropic.com',
-  gemini: 'https://generativelanguage.googleapis.com/v1beta',
-  opencode: '',
-  qwen: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
-  opencodereview: 'https://api.openai.com/v1',
-})
-
-function chatCompletionsUrl(baseUrl) {
-  const normalized = String(baseUrl || '').trim().replace(/\/+$/, '')
-  if (!normalized) return ''
-  return /\/chat\/completions$/i.test(normalized)
-    ? normalized
-    : `${normalized}/chat/completions`
-}
-
-function providerPresetFromStatus(kind, status = {}) {
-  if (['official', 'openrouter', 'custom'].includes(status.activePreset)) {
-    return status.activePreset
-  }
-  const provider = String(status.provider || '').trim().toLowerCase()
-  const baseUrl = String(status.baseUrl || '').trim().replace(/\/+$/, '')
-  if (/openrouter/i.test(provider) || /openrouter\.ai$/i.test(new URL(baseUrl || 'https://example.com').hostname)) {
-    return 'openrouter'
-  }
-  if (OFFICIAL_PROVIDER_BASE_URLS[kind]
-      && baseUrl
-      && baseUrl === OFFICIAL_PROVIDER_BASE_URLS[kind]) {
-    return 'official'
-  }
-  return 'custom'
-}
-
-function providerOptionsFor(kind, generic, context = {}, status = {}) {
-  const preset = providerPresetFromStatus(kind, status)
-  if (kind === 'codex') return { env: generic }
-  if (kind === 'hermes') {
-    return {
-      provider: { id: 'openai-api', model: generic.OPENAI_MODEL },
-      env: {
-        ...generic,
-        HERMES_INFERENCE_PROVIDER: 'openai-api',
-        HERMES_INFERENCE_MODEL: generic.OPENAI_MODEL,
-      },
-    }
-  }
-  if (kind === 'workbuddy') {
-    return {
-      env: {
-        ...generic,
-        CODEBUDDY_MODEL: generic.OPENAI_MODEL,
-        CODEBUDDY_API_KEY: generic.OPENAI_API_KEY,
-        CODEBUDDY_BASE_URL: generic.OPENAI_BASE_URL,
-      },
-    }
-  }
-  if (kind === 'kimi') {
-    return {
-      env: {
-        ...generic,
-        MOONSHOT_API_KEY: generic.OPENAI_API_KEY,
-        KIMI_API_KEY: generic.OPENAI_API_KEY,
-        KIMI_MODEL_API_KEY: generic.OPENAI_API_KEY,
-        KIMI_MODEL_BASE_URL: generic.OPENAI_BASE_URL,
-        KIMI_MODEL_NAME: generic.OPENAI_MODEL,
-      },
-    }
-  }
-  if (kind === 'mimo') {
-    return {
-      env: {
-        ...generic,
-        MIMO_API_KEY: generic.OPENAI_API_KEY,
-        MIMO_BASE_URL: generic.OPENAI_BASE_URL,
-        MIMO_MODEL: generic.OPENAI_MODEL,
-      },
-    }
-  }
-  if (kind === 'claude') {
-    return {
-      env: {
-        ...generic,
-        ANTHROPIC_API_KEY: generic.OPENAI_API_KEY,
-        ANTHROPIC_BASE_URL: generic.OPENAI_BASE_URL,
-        ANTHROPIC_MODEL: generic.OPENAI_MODEL,
-      },
-    }
-  }
-  if (kind === 'gemini') {
-    return {
-      env: {
-        ...generic,
-        GEMINI_API_KEY: generic.OPENAI_API_KEY,
-        GOOGLE_API_KEY: generic.OPENAI_API_KEY,
-        GEMINI_MODEL: generic.OPENAI_MODEL,
-      },
-    }
-  }
-  if (kind === 'qwen') {
-    return {
-      provider: { id: 'openai', model: generic.OPENAI_MODEL },
-      env: {
-        ...generic,
-        DASHSCOPE_API_KEY: generic.OPENAI_API_KEY,
-      },
-    }
-  }
-  if (kind === 'opencode') {
-    return {
-      env: {
-        ...generic,
-        ...(preset === 'openrouter' ? { OPENROUTER_API_KEY: generic.OPENAI_API_KEY } : {}),
-      },
-    }
-  }
-  if (kind === 'opencodereview') {
-    return {
-      env: {
-        ...generic,
-        OCR_LLM_URL: chatCompletionsUrl(generic.OPENAI_BASE_URL),
-        OCR_LLM_TOKEN: generic.OPENAI_API_KEY,
-        OCR_LLM_MODEL: generic.OPENAI_MODEL,
-        OCR_USE_ANTHROPIC: 'false',
-      },
-    }
-  }
-  if (kind === 'openclaw' && context.storageRoot && context.workdir) {
-    if (!generic?.OPENAI_API_KEY) {
-      return nativeOpenClawOptions({
-        storageRoot: context.storageRoot,
-        workdir: context.workdir,
-        sessionRef: context.sessionRef,
-        allowWrite: context.sandbox === 'workspace-write',
-        runtime: context.nativeRuntime,
-      })
-    }
-    return managedOpenClawOptions({
-      storageRoot: context.storageRoot,
-      workdir: context.workdir,
-      sessionRef: context.sessionRef,
-      allowWrite: context.sandbox === 'workspace-write',
-      provider: generic,
-    })
-  }
-  return {}
-}
-
-function providerAgentKind(value) {
-  const kind = String(value || '').trim()
-  if (!EXTERNAL_PROVIDER_KINDS.has(kind)) throw new Error('PROVIDER_AGENT_UNSUPPORTED')
-  return kind
-}
-
-module.exports = {
-  EXTERNAL_PROVIDER_KINDS,
-  providerAgentKind,
-  providerOptionsFor,
-}

desktop/src/providers/provider-store.cjs

@@ -1,377 +0,0 @@
-const fs = require('node:fs')
-
-const { atomicWritePrivateFile } = require('../security/private-file.cjs')
-
-const STORE_VERSION = 3
-const SINGLE_PROFILE_STORE_VERSION = 2
-const LEGACY_STORE_VERSION = 1
-const PROVIDER_KIND = /^[a-z0-9][a-z0-9-]{0,31}$/
-const PROVIDER_PRESETS = new Set(['official', 'openrouter', 'custom'])
-const EMPTY_METADATA = Object.freeze({ provider: '', baseUrl: '', model: '' })
-const OPENROUTER_PROVIDER = Object.freeze({
-  provider: 'OpenRouter',
-  baseUrl: 'https://openrouter.ai/api/v1',
-})
-const OFFICIAL_PROVIDERS = Object.freeze({
-  codex: { provider: 'OpenAI', baseUrl: 'https://api.openai.com/v1' },
-  hermes: { provider: 'OpenAI API', baseUrl: 'https://api.openai.com/v1' },
-  openclaw: { provider: 'OpenAI API', baseUrl: 'https://api.openai.com/v1' },
-  workbuddy: { provider: 'WorkBuddy Official', baseUrl: '' },
-  kimi: { provider: 'Moonshot AI', baseUrl: 'https://api.moonshot.cn/v1' },
-  mimo: { provider: 'MiMo Native', baseUrl: '' },
-  claude: { provider: 'Anthropic', baseUrl: 'https://api.anthropic.com' },
-  gemini: { provider: 'Google AI Studio', baseUrl: 'https://generativelanguage.googleapis.com/v1beta' },
-  opencode: { provider: 'OpenCode Provider', baseUrl: '' },
-  qwen: { provider: 'DashScope', baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1' },
-  opencodereview: { provider: 'OpenAI API', baseUrl: 'https://api.openai.com/v1' },
-})
-function normalizeMetadata(input) {
-  const provider = String(input?.provider || '').trim()
-  let baseUrl = String(input?.baseUrl || '').trim().replace(/\/+$/, '')
-  baseUrl = baseUrl.replace(/\/chat\/completions$/i, '')
-  const model = String(input?.model || '').trim()
-  if (!provider || provider.length > 80 || !baseUrl || baseUrl.length > 300
-      || !model || model.length > 160) {
-    throw new Error('PROVIDER_INVALID_METADATA')
-  }
-  let parsed
-  try { parsed = new URL(baseUrl) } catch { throw new Error('PROVIDER_INVALID_METADATA') }
-  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname)
-  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
-    throw new Error('PROVIDER_INSECURE_BASE_URL')
-  }
-  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
-    throw new Error('PROVIDER_INVALID_METADATA')
-  }
-  return { provider, baseUrl, model }
-}
-
-function sortedKeys(value) {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    ? Reflect.ownKeys(value).sort().join(',')
-    : ''
-}
-
-function inferStoredPreset(entry) {
-  const provider = String(entry?.provider || '').toLowerCase()
-  const baseUrl = String(entry?.baseUrl || '')
-  return /openrouter/i.test(provider) || /(^|\.)openrouter\.ai$/i.test(hostname(baseUrl))
-    ? 'openrouter'
-    : 'custom'
-}
-
-function hostname(value) {
-  try { return new URL(value).hostname } catch { return '' }
-}
-
-function validatePresetMetadata(kind, preset, metadata) {
-  if (preset === 'custom') return metadata
-  const expected = preset === 'openrouter' ? OPENROUTER_PROVIDER : OFFICIAL_PROVIDERS[kind]
-  if (!expected?.baseUrl
-      || metadata.provider !== expected.provider
-      || metadata.baseUrl !== expected.baseUrl) {
-    throw new Error('PROVIDER_INVALID_METADATA')
-  }
-  return metadata
-}
-
-class ProviderStore {
-  constructor({ storagePath, safeStorage, allowedKinds = [] }) {
-    if (typeof storagePath !== 'string' || !storagePath) {
-      throw new Error('PROVIDER_STORAGE_PATH_REQUIRED')
-    }
-    const normalizedKinds = [...new Set(allowedKinds.map(kind => String(kind || '').trim()))]
-    if (!normalizedKinds.length || normalizedKinds.some(kind => !PROVIDER_KIND.test(kind))) {
-      throw new Error('PROVIDER_AGENT_KINDS_REQUIRED')
-    }
-    this.storagePath = storagePath
-    this.safeStorage = safeStorage
-    this.allowedKinds = new Set(normalizedKinds)
-  }
-
-  encryptionAvailable() {
-    try {
-      return Boolean(this.safeStorage?.isEncryptionAvailable?.())
-    } catch {
-      return false
-    }
-  }
-
-  status(kind, { probeEncryption = false } = {}) {
-    const targetKind = this.normalizeKind(kind)
-    const credentialStored = fs.existsSync(this.storagePath)
-    if (!credentialStored && !probeEncryption) {
-      return {
-        provider: '',
-        baseUrl: '',
-        model: '',
-        activePreset: 'official',
-        profiles: {},
-        encryptionAvailable: null,
-        configured: false,
-      }
-    }
-
-    const encryptionAvailable = this.encryptionAvailable()
-    let metadata = EMPTY_METADATA
-    let configured = false
-    let activePreset = 'official'
-    const profiles = {}
-    if (encryptionAvailable && credentialStored) {
-      try {
-        const agent = this.readDocument().agents[targetKind]
-        if (agent) {
-          activePreset = agent.activePreset
-          for (const [preset, entry] of Object.entries(agent.profiles)) {
-            try {
-              this.decryptEntry(entry)
-              profiles[preset] = {
-                provider: entry.provider,
-                baseUrl: entry.baseUrl,
-                model: entry.model,
-                configured: true,
-              }
-            } catch { /* keep an unreadable profile unavailable */ }
-          }
-          const activeEntry = profiles[activePreset]
-          if (activeEntry) {
-            metadata = activeEntry
-            configured = true
-          }
-        }
-      } catch { /* unreadable credentials stay unavailable */ }
-    }
-    return {
-      provider: metadata.provider,
-      baseUrl: metadata.baseUrl,
-      model: metadata.model,
-      activePreset,
-      profiles,
-      encryptionAvailable,
-      configured,
-    }
-  }
-
-  save(kind, input) {
-    const targetKind = this.normalizeKind(kind)
-    if (sortedKeys(input) !== 'apiKey,baseUrl,model,preset,provider'
-        || typeof input.apiKey !== 'string' || !input.apiKey.trim()
-        || input.apiKey.trim().length > 8192) {
-      throw new Error('PROVIDER_INVALID_CREDENTIAL')
-    }
-    this.requireEncryption()
-
-    const apiKey = input.apiKey.trim()
-    const preset = this.normalizePreset(input.preset)
-    const metadata = validatePresetMetadata(targetKind, preset, normalizeMetadata(input))
-    let encrypted
-    try {
-      encrypted = this.safeStorage.encryptString(apiKey)
-      if (!Buffer.isBuffer(encrypted) || encrypted.length === 0
-          || this.safeStorage.decryptString(encrypted) !== apiKey) {
-        throw new Error('invalid encryption result')
-      }
-    } catch {
-      throw new Error('PROVIDER_ENCRYPTION_FAILED')
-    }
-
-    const document = fs.existsSync(this.storagePath)
-      ? this.readDocument()
-      : { version: STORE_VERSION, agents: {} }
-    const agent = document.agents[targetKind] || { activePreset: 'official', profiles: {} }
-    agent.profiles[preset] = {
-      ...metadata,
-      encrypted: encrypted.toString('base64'),
-    }
-    agent.activePreset = preset
-    document.agents[targetKind] = agent
-    atomicWritePrivateFile(this.storagePath, JSON.stringify(document))
-    return this.status(targetKind)
-  }
-
-  activate(kind, preset) {
-    const targetKind = this.normalizeKind(kind)
-    const targetPreset = this.normalizePreset(preset)
-    if (!fs.existsSync(this.storagePath)) {
-      if (targetPreset !== 'official') throw new Error('PROVIDER_PROFILE_UNAVAILABLE')
-      return this.status(targetKind, { probeEncryption: true })
-    }
-    this.requireEncryption()
-    const document = this.readDocument()
-    const agent = document.agents[targetKind] || { activePreset: 'official', profiles: {} }
-    if (targetPreset !== 'official' && !agent.profiles[targetPreset]) {
-      throw new Error('PROVIDER_PROFILE_UNAVAILABLE')
-    }
-    if (agent.profiles[targetPreset]) this.decryptEntry(agent.profiles[targetPreset])
-    agent.activePreset = targetPreset
-    document.agents[targetKind] = agent
-    atomicWritePrivateFile(this.storagePath, JSON.stringify(document))
-    return this.status(targetKind)
-  }
-
-  delete(kind, preset = '') {
-    const targetKind = this.normalizeKind(kind)
-    if (fs.existsSync(this.storagePath)) {
-      const document = this.readDocument()
-      if (preset) {
-        const targetPreset = this.normalizePreset(preset)
-        const agent = document.agents[targetKind]
-        if (agent) {
-          delete agent.profiles[targetPreset]
-          if (agent.activePreset === targetPreset) agent.activePreset = 'official'
-          if (Object.keys(agent.profiles).length) document.agents[targetKind] = agent
-          else delete document.agents[targetKind]
-        }
-      } else {
-        delete document.agents[targetKind]
-      }
-      if (Object.keys(document.agents).length) {
-        atomicWritePrivateFile(this.storagePath, JSON.stringify(document))
-      } else {
-        fs.unlinkSync(this.storagePath)
-      }
-    }
-    return this.status(targetKind, { probeEncryption: true })
-  }
-
-  envForAgent(kind) {
-    const targetKind = this.normalizeKind(kind)
-    this.requireEncryption()
-    const agent = this.readDocument().agents[targetKind]
-    const entry = agent?.profiles?.[agent.activePreset]
-    if (!entry) throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    return {
-      OPENAI_API_KEY: this.decryptEntry(entry),
-      OPENAI_BASE_URL: entry.baseUrl,
-      OPENAI_MODEL: entry.model,
-    }
-  }
-
-  requireEncryption() {
-    if (!this.encryptionAvailable()) throw new Error('PROVIDER_ENCRYPTION_UNAVAILABLE')
-  }
-
-  normalizeKind(kind) {
-    const normalized = String(kind || '').trim()
-    if (!PROVIDER_KIND.test(normalized) || !this.allowedKinds.has(normalized)) {
-      throw new Error('PROVIDER_AGENT_UNSUPPORTED')
-    }
-    return normalized
-  }
-
-  normalizePreset(preset) {
-    const normalized = String(preset || '').trim().toLowerCase()
-    if (!PROVIDER_PRESETS.has(normalized)) throw new Error('PROVIDER_PRESET_UNSUPPORTED')
-    return normalized
-  }
-
-  decryptEntry(entry) {
-    this.requireEncryption()
-    try {
-      const encrypted = Buffer.from(entry.encrypted, 'base64')
-      if (!encrypted.length || encrypted.toString('base64') !== entry.encrypted) {
-        throw new Error('invalid ciphertext')
-      }
-      const apiKey = this.safeStorage.decryptString(encrypted)
-      if (typeof apiKey !== 'string' || !apiKey.trim()) throw new Error('invalid credential')
-      return apiKey
-    } catch {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-  }
-
-  readDocument() {
-    let payload
-    try {
-      payload = JSON.parse(fs.readFileSync(this.storagePath, 'utf8'))
-    } catch {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-    if (payload?.version === LEGACY_STORE_VERSION) {
-      if (sortedKeys(payload) !== 'baseUrl,encrypted,model,provider,version'
-          || typeof payload.encrypted !== 'string') {
-        throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-      }
-      const rawEntry = {
-        provider: payload.provider,
-        baseUrl: payload.baseUrl,
-        model: payload.model,
-        encrypted: payload.encrypted,
-      }
-      return {
-        version: STORE_VERSION,
-        agents: Object.fromEntries([...this.allowedKinds].map((kind) => {
-          const entry = this.normalizeEntry(rawEntry)
-          const preset = inferStoredPreset(entry)
-          return [kind, {
-            activePreset: preset,
-            profiles: { [preset]: { ...entry } },
-          }]
-        })),
-      }
-    }
-    if (payload?.version === SINGLE_PROFILE_STORE_VERSION) {
-      if (sortedKeys(payload) !== 'agents,version'
-          || !payload.agents || typeof payload.agents !== 'object'
-          || Array.isArray(payload.agents)) {
-        throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-      }
-      const agents = {}
-      for (const [kind, rawEntry] of Object.entries(payload.agents)) {
-        if (!this.allowedKinds.has(kind)) throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-        const entry = this.normalizeEntry(rawEntry)
-        const preset = inferStoredPreset(entry)
-        agents[kind] = { activePreset: preset, profiles: { [preset]: entry } }
-      }
-      return { version: STORE_VERSION, agents }
-    }
-    if (sortedKeys(payload) !== 'agents,version'
-        || payload.version !== STORE_VERSION
-        || !payload.agents || typeof payload.agents !== 'object'
-        || Array.isArray(payload.agents)) {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-    const agents = {}
-    for (const [kind, entry] of Object.entries(payload.agents)) {
-      if (!this.allowedKinds.has(kind)) throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-      agents[kind] = this.normalizeAgentEntry(entry)
-    }
-    return { version: STORE_VERSION, agents }
-  }
-
-  normalizeAgentEntry(entry) {
-    try {
-      if (sortedKeys(entry) !== 'activePreset,profiles'
-          || !entry.profiles || typeof entry.profiles !== 'object'
-          || Array.isArray(entry.profiles)) {
-        throw new Error('invalid agent entry')
-      }
-      const activePreset = this.normalizePreset(entry.activePreset)
-      const profiles = {}
-      for (const [preset, profile] of Object.entries(entry.profiles)) {
-        const normalizedPreset = this.normalizePreset(preset)
-        profiles[normalizedPreset] = this.normalizeEntry(profile)
-      }
-      if (activePreset !== 'official' && !profiles[activePreset]) {
-        throw new Error('missing active profile')
-      }
-      return { activePreset, profiles }
-    } catch {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-  }
-
-  normalizeEntry(entry) {
-    if (sortedKeys(entry) !== 'baseUrl,encrypted,model,provider'
-        || typeof entry.encrypted !== 'string') {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-    const encrypted = Buffer.from(entry.encrypted, 'base64')
-    if (!encrypted.length || encrypted.toString('base64') !== entry.encrypted) {
-      throw new Error('PROVIDER_CREDENTIAL_UNAVAILABLE')
-    }
-    return { ...normalizeMetadata(entry), encrypted: entry.encrypted }
-  }
-}
-
-module.exports = { ProviderStore }

desktop/src/runs/failure-policy.cjs

@@ -1,3 +1,11 @@
+const {
+  authFailureCertainty,
+  isNetworkFailure,
+  isProviderUnavailable,
+  isRateLimited,
+  retryAfterFromText,
+} = require('./failure-signals.cjs')
+
 const FAILURE_CATEGORIES = Object.freeze([
   'authentication',
   'compatibility',
@@ -121,23 +129,47 @@ function retryAfterMs(error, now) {
     const parsed = parseRetryAfter(headerValue(headers, 'retry-after'), now)
     if (parsed != null) return parsed
   }
-  return null
+  // Local CLIs surface provider throttling as text ("retry after 20s").
+  return retryAfterFromText(error?.diagnostic || error?.message)
+}
+
+// A local CLI process failure carries a code-derived category (usually
+// protocol). Its diagnostic often proves a transient provider condition, so
+// refine it before deciding whether to retry and how long to wait.
+function transientCategoryFromText(detail) {
+  if (!detail) return ''
+  if (isRateLimited(detail)) return 'rate_limit'
+  if (isNetworkFailure(detail)) return 'network'
+  if (isProviderUnavailable(detail)) return 'provider'
+  return ''
 }
 
 function classifiedCategory(error, code, status) {
   const explicit = String(error?.failure?.category || '')
-  if (FAILURE_CATEGORY_SET.has(explicit)) return explicit
   const detail = String(error?.diagnostic || error?.message || '')
+  if (FAILURE_CATEGORY_SET.has(explicit)) {
+    if (['protocol', 'execution'].includes(explicit)) {
+      const refined = transientCategoryFromText(error?.diagnostic || '')
+      if (refined) return refined
+    }
+    return explicit
+  }
   if (code === 'LOCAL_BUDGET_EXHAUSTED') return 'budget'
   if (/PERMISSION/.test(code)) return 'permission'
   if (code === 'LOCAL_AGENT_EXECUTION_STOPPED' || /CANCEL|ABORT/.test(code)) {
     return 'cancellation'
   }
   if (code === 'LOCAL_AGENT_SESSION_INVALID') return 'session'
-  if (status === 401 || status === 403 || code === 'LOCAL_AGENT_AUTH_REQUIRED'
-      || /unauthori[sz]ed|forbidden|invalid token/i.test(detail)) return 'authentication'
+  // Only explicit sign-in statements prove that credentials are gone. A 403,
+  // a proxy refusal, or "unauthorized" inside unrelated output is retried as
+  // a provider-side refusal instead of stopping the Agent for the run.
+  const authCertainty = authFailureCertainty(detail)
+  if (status === 401 || code === 'LOCAL_AGENT_AUTH_REQUIRED'
+      || authCertainty === 'definitive') return 'authentication'
+  if (status === 403 || code === 'LOCAL_AGENT_ACCESS_DENIED'
+      || authCertainty === 'ambiguous') return 'provider'
   if (status === 429 || /RATE_LIMIT|TOO_MANY_REQUESTS/.test(code)
-      || /rate limit|too many requests/i.test(detail)) return 'rate_limit'
+      || isRateLimited(detail)) return 'rate_limit'
   if (NETWORK_CODES.has(code) || /NETWORK|CONNECTION/.test(code)
       || /socket hang up|temporary failure|network error/i.test(detail)) return 'network'
   if (status != null && status >= 500) return 'provider'
@@ -147,7 +179,7 @@ function classifiedCategory(error, code, status) {
   if (/INCOMPAT|UNSUPPORTED|PROTOCOL_UNAVAILABLE|REVIEW_ONLY|VERSION_MISMATCH/.test(code)) {
     return 'compatibility'
   }
-  if (/SPAWN|EXITED|PROCESS|PROTOCOL|OUTCOME|OUTPUT_LIMIT|EMPTY_RESPONSE/.test(code)) {
+  if (/SPAWN|EXITED|PROCESS|PROTOCOL|OUTCOME|OUTPUT_LIMIT|EMPTY_RESPONSE|COLLABORATION_RECEIPT/.test(code)) {
     return 'protocol'
   }
   return 'execution'
@@ -157,7 +189,7 @@ function retryability(category, error) {
   if (category === 'session') return 'refresh_session'
   if (category === 'authentication') return 'never'
   if (category === 'compatibility') return 'never'
-  if (['rate_limit', 'network', 'provider'].includes(category)) return 'retry'
+  if (['rate_limit', 'network', 'provider', 'timeout', 'protocol'].includes(category)) return 'retry'
   if (error?.failure?.retryable === true) return 'retry'
   return 'never'
 }
@@ -244,18 +276,30 @@ function retryDecision(input, options = {}) {
   if (safety?.sideEffectsPossible === true && safety.idempotencyMode !== 'durable') {
     return Object.freeze({ ...base, action: 'human_gate', exhausted: false })
   }
-  const maxDelayMs = Math.max(1, boundedInteger(
+  const configuredMaxDelayMs = Math.max(1, boundedInteger(
     options.maxDelayMs, 10 * 1000, 24 * 60 * 60 * 1000,
   ))
+  // Provider throttling needs a longer and server-directed wait than a crashed
+  // process. Honor Retry-After up to the rate-limit cap instead of hammering
+  // the provider with the generic sub-second backoff.
+  const rateLimited = failure.category === 'rate_limit'
+  const maxDelayMs = rateLimited
+    ? Math.max(configuredMaxDelayMs, boundedInteger(
+      options.rateLimitMaxDelayMs, 60 * 1000, 24 * 60 * 60 * 1000,
+    ))
+    : configuredMaxDelayMs
   const backoff = boundedBackoffDelay(attempt, { ...options, maxDelayMs })
   const requestedDelay = failure.retryAfterMs == null
     ? 0
     : Math.min(maxDelayMs, boundedInteger(failure.retryAfterMs, 0, maxDelayMs))
+  const minimumDelay = rateLimited && failure.retryAfterMs == null
+    ? Math.min(maxDelayMs, boundedInteger(options.rateLimitMinDelayMs, 0, maxDelayMs))
+    : 0
   return Object.freeze({
     ...base,
     action: 'retry',
     exhausted: false,
-    delayMs: Math.max(backoff, requestedDelay),
+    delayMs: Math.max(backoff, requestedDelay, minimumDelay),
   })
 }
 

desktop/src/runs/failure-signals.cjs

@@ -0,0 +1,129 @@
+// Pure text classifiers for local Agent failure diagnostics.
+//
+// Agent CLIs report failures as free text on stderr or inside structured error
+// results. Classification decides whether Meldwork retries, asks the user to
+// sign in again, or rebuilds a native session, so every rule here errs on the
+// side of "ambiguous": only explicit login and API-key statements count as a
+// definitive authentication failure. A bare 403, a proxy refusal, or a word
+// such as "unauthorized" inside unrelated output must never mark an installed
+// Agent as signed out.
+
+const MAX_SIGNAL_TEXT_CHARS = 64 * 1024
+
+const LOG_PREFIX = /^(?:\[[^\]]{1,40}\]\s*|(?:error|fatal|err|warning)\s*[:!-]\s*|[✗✘×!]\s*)+/i
+
+const DEFINITIVE_AUTH_LINE = [
+  /^(?:invalid|expired|missing|incorrect|revoked)\s+(?:api[ _-]?key|(?:access|refresh|auth|oauth|bearer)[ _-]?token|credentials?)\b/i,
+  /^(?:authentication|authorization)\s+(?:failed|required)\b/i,
+  /^(?:please\s+)?(?:log|sign)\s+in\b/i,
+  /^(?:please\s+)?run\s+\S*\s*(?:\/)?login\b/i,
+  /^not\s+(?:logged|signed)\s+in\b/i,
+  /^you\s+are\s+not\s+(?:logged|signed)\s+in\b/i,
+  /^select an auth type\b/i,
+  /^oauth\s+token\s+(?:has\s+)?(?:expired|is\s+invalid|was\s+revoked)\b/i,
+  /^HTTP\s+401\s*:/i,
+  /^provider rejected\b/i,
+  /^(?:认证|鉴权|登录)(?:失败|过期)/,
+  /^(?:令牌|凭据|密钥)(?:无效|缺失|已过期)/,
+  /^请(?:先|重新)登录/,
+  /^未登录/,
+]
+
+const DEFINITIVE_AUTH_ANYWHERE = /"type"\s*:\s*"authentication_error"|\binvalid_api_key\b|\bincorrect api key provided\b|\binvalid x-api-key\b/i
+
+// Ambiguous refusals must lead a diagnostic line. Tool output such as
+// "Failed to download docs: HTTP 403 Forbidden" mentions a refusal of some
+// unrelated resource and stays a plain process failure.
+const AMBIGUOUS_AUTH_LINE = [
+  /^HTTP\s+403\s*:/i,
+  /^(?:403\s+)?forbidden\b/i,
+  /^unauthori[sz]ed\b/i,
+  /^access denied\b/i,
+  /^invalid token\b/i,
+]
+
+const AMBIGUOUS_AUTH_ANYWHERE = /"type"\s*:\s*"permission_error"/i
+
+const RATE_LIMIT = /\b429\b|too many requests|rate[ _-]?limit(?:ed|ing)?\b|\boverloaded(?:_error)?\b|\bquota (?:exceeded|exhausted)\b|\bresource[ _-]?exhausted\b|\binsufficient_quota\b|\b529\b/i
+
+const NETWORK = /\b(?:ECONNRESET|ECONNREFUSED|ECONNABORTED|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|ENETDOWN|EHOSTUNREACH)\b|socket hang up|fetch failed|network (?:error|is unreachable)|connection (?:reset|refused|closed|timed out)|getaddrinfo|tls handshake|ssl handshake|proxy (?:error|connection)/i
+
+const PROVIDER_UNAVAILABLE = /\b(?:HTTP\s*)?50[0234]\b\s*(?::|-)?\s*(?:internal server error|bad gateway|service unavailable|gateway timeout)|\bservice unavailable\b|\bbad gateway\b|\bgateway timeout\b|\binternal server error\b|"type"\s*:\s*"api_error"|\bupstream connect error\b/i
+
+const CONTEXT_OVERFLOW = /prompt is too long|context[_ ]length[_ ]exceeded|maximum context length|context window (?:exceeded|is full|limit)|input is too long|too many (?:input )?tokens|exceeds? the (?:maximum|model'?s?) context|context_window_exceeded|request too large for model/i
+
+function signalText(value) {
+  return String(value || '').slice(0, MAX_SIGNAL_TEXT_CHARS)
+}
+
+function diagnosticLines(value) {
+  return signalText(value)
+    .split(/\r?\n/)
+    .map(line => line.trim().replace(LOG_PREFIX, '').trim())
+    .filter(Boolean)
+}
+
+// Returns 'definitive', 'ambiguous', or ''.
+function authFailureCertainty(value) {
+  const text = signalText(value)
+  if (!text.trim()) return ''
+  const lines = diagnosticLines(text)
+  if (DEFINITIVE_AUTH_ANYWHERE.test(text)
+      || lines.some(line => DEFINITIVE_AUTH_LINE.some(pattern => pattern.test(line)))) {
+    return 'definitive'
+  }
+  if (lines.some(line => AMBIGUOUS_AUTH_LINE.some(pattern => pattern.test(line)))
+      || AMBIGUOUS_AUTH_ANYWHERE.test(text)) {
+    return 'ambiguous'
+  }
+  return ''
+}
+
+function isRateLimited(value) {
+  return RATE_LIMIT.test(signalText(value))
+}
+
+function isNetworkFailure(value) {
+  return NETWORK.test(signalText(value))
+}
+
+function isProviderUnavailable(value) {
+  return PROVIDER_UNAVAILABLE.test(signalText(value))
+}
+
+function isContextOverflow(value) {
+  return CONTEXT_OVERFLOW.test(signalText(value))
+}
+
+const RETRY_AFTER_PATTERNS = [
+  /retry[- ]after["']?\s*[:=]?\s*(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|secs?|seconds?|m|mins?|minutes?)?/i,
+  /(?:try|retry) again in\s+(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|secs?|seconds?|m|mins?|minutes?)?/i,
+  /(?:reset|resets) in\s+(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|secs?|seconds?|m|mins?|minutes?)/i,
+]
+
+const MAX_RETRY_AFTER_MS = 5 * 60 * 1000
+
+function retryAfterFromText(value) {
+  const text = signalText(value)
+  for (const pattern of RETRY_AFTER_PATTERNS) {
+    const match = text.match(pattern)
+    if (!match) continue
+    const amount = Number(match[1])
+    if (!Number.isFinite(amount) || amount < 0) continue
+    const unit = String(match[2] || 's').toLowerCase()
+    const multiplier = unit.startsWith('ms') || unit.startsWith('milli')
+      ? 1
+      : unit.startsWith('m') ? 60 * 1000 : 1000
+    return Math.min(MAX_RETRY_AFTER_MS, Math.round(amount * multiplier))
+  }
+  return null
+}
+
+module.exports = {
+  authFailureCertainty,
+  isContextOverflow,
+  isNetworkFailure,
+  isProviderUnavailable,
+  isRateLimited,
+  retryAfterFromText,
+}

desktop/src/runs/invocation-watchdog.cjs

@@ -0,0 +1,144 @@
+const REAL_CLOCK = Object.freeze({
+  now: () => Date.now(),
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: handle => clearTimeout(handle),
+})
+
+function positiveFinite(value) {
+  return Number.isFinite(value) && value > 0
+}
+
+// Stops an Agent invocation that has gone quiet. Three windows apply:
+//  - startup: strict turns (autonomous discussion) must show any sign of life
+//    within `timeoutMs`; once they do, the deadline is lifted.
+//  - inactivity: any activity refreshes `timeoutMs`, or `toolTimeoutMs` while a
+//    tool call is running.
+//  - stall: strict turns also stop after three inactivity windows without
+//    substantive progress, so a CLI that emits empty heartbeats forever still
+//    ends and the remaining participants can continue. Other turns keep
+//    running while the process is active; the user can stop them.
+// Raw process output only proves liveness (`liveness`); mapped events, answer
+// text, tool lifecycle and structured progress count as progress (`progress`).
+function createInvocationWatchdog({
+  timeoutMs,
+  toolTimeoutMs,
+  strict = false,
+  isStopped = () => false,
+  onTimeout = () => {},
+  clock = REAL_CLOCK,
+} = {}) {
+  const enabled = positiveFinite(timeoutMs)
+  const startedAt = clock.now()
+  const startupDeadlineAt = strict && enabled ? startedAt + timeoutMs : Number.POSITIVE_INFINITY
+  let lastProgressAt = startedAt
+  let lastSubstantiveAt = startedAt
+  let paused = false
+  let established = false
+  let toolActive = false
+  const activeToolIds = new Set()
+  let closed = false
+  let timedOut = false
+  let timeoutError = null
+  let timer = null
+  let rejectTimeout = () => {}
+  const promise = new Promise((_, reject) => { rejectTimeout = reject })
+  promise.catch(() => {})
+
+  function disarm() {
+    clock.clearTimeout(timer)
+    timer = null
+  }
+
+  function arm() {
+    if (timer || paused || isStopped() || !enabled) return
+    const now = clock.now()
+    const inactivityWindowMs = toolActive ? toolTimeoutMs : timeoutMs
+    const inactivityRemainingMs = Math.max(0, inactivityWindowMs - (now - lastProgressAt))
+    const startupRemainingMs = Math.max(
+      0, (established ? Number.POSITIVE_INFINITY : startupDeadlineAt) - now,
+    )
+    const stallWindowMs = !strict
+      ? Number.POSITIVE_INFINITY
+      : (toolActive ? toolTimeoutMs : timeoutMs * 3)
+    const stallRemainingMs = Math.max(0, stallWindowMs - (now - lastSubstantiveAt))
+    const remainingMs = Math.min(inactivityRemainingMs, startupRemainingMs, stallRemainingMs)
+    timer = clock.setTimeout(() => {
+      timer = null
+      if (paused || isStopped()) return
+      timedOut = true
+      timeoutError = new Error('LOCAL_AGENT_TIMEOUT')
+      onTimeout(timeoutError)
+      rejectTimeout(timeoutError)
+    }, remainingMs)
+  }
+
+  function rearm() {
+    if (paused) return
+    disarm()
+    arm()
+  }
+
+  function inactive() {
+    return closed || isStopped()
+  }
+
+  // The process produced something meaningful: refresh every window.
+  function progress() {
+    if (inactive()) return
+    lastProgressAt = clock.now()
+    lastSubstantiveAt = lastProgressAt
+    rearm()
+  }
+
+  arm()
+
+  return {
+    promise,
+    get timedOut() { return timedOut },
+    get error() { return timeoutError },
+    progress,
+    // The process is alive but has not said anything yet (stdout/stderr bytes,
+    // ACP traffic): lift the startup deadline and refresh the inactivity
+    // window outside tool calls.
+    liveness() {
+      if (inactive()) return
+      established = true
+      if (!toolActive) lastProgressAt = clock.now()
+      rearm()
+    },
+    // First proof that the run started. Lifts the startup deadline only.
+    establish() {
+      if (established || isStopped()) return
+      established = true
+      rearm()
+    },
+    toolStarted(toolCallId = '') {
+      if (toolCallId) activeToolIds.add(String(toolCallId))
+      toolActive = true
+      progress()
+    },
+    toolFinished(toolCallId = '') {
+      if (toolCallId) activeToolIds.delete(String(toolCallId))
+      else activeToolIds.clear()
+      toolActive = activeToolIds.size > 0
+      progress()
+    },
+    // Waiting for a person (Human Gate) is not the Agent being quiet.
+    pause() {
+      paused = true
+      disarm()
+    },
+    resume() {
+      paused = false
+      lastProgressAt = clock.now()
+      lastSubstantiveAt = lastProgressAt
+      arm()
+    },
+    close() {
+      closed = true
+      disarm()
+    },
+  }
+}
+
+module.exports = { createInvocationWatchdog }

desktop/src/runs/run-harness-context.cjs

@@ -122,6 +122,8 @@ function normalizeSessionMeta(input) {
     meta.inheritedTaskIds = inheritedTaskIds
     meta.provenanceCompleteness = provenanceCompleteness
   }
+  const lastDeliveredMessageId = cleanId(input.lastDeliveredMessageId)
+  if (lastDeliveredMessageId) meta.lastDeliveredMessageId = lastDeliveredMessageId
   return meta
 }
 
@@ -157,6 +159,8 @@ function nextSessionMeta(meta, usage = {}) {
     if (Object.hasOwn(usage, field)) next[field] = usage[field]
     else if (Object.hasOwn(previous, field)) next[field] = previous[field]
   }
+  if (usage.lastDeliveredMessageId) next.lastDeliveredMessageId = usage.lastDeliveredMessageId
+  else if (previous.lastDeliveredMessageId) next.lastDeliveredMessageId = previous.lastDeliveredMessageId
   return normalizeSessionMeta(next)
 }
 

desktop/src/runs/run-harness-normalization.cjs

@@ -1,4 +1,5 @@
 const MAX_CAPSULE_EVENTS = 12
+const { parseTaskDecision } = require('../collaboration/task-decision.cjs')
 
 const { redactSecrets } = require('../security/secret-redaction.cjs')
 const { normalizeContentBlobRef } = require('../attachments/content-blob-store.cjs')
@@ -31,6 +32,10 @@ const FINAL_STATUSES = new Set([
 const CAPSULE_EVENT_TYPES = new Set([
   'reasoning_summary', 'plan', 'tool_start', 'tool_update', 'tool_result_summary', 'warning',
 ])
+const TRACE_PHASES = new Set([
+  'proposal', 'challenge', 'coordination', 'work', 'synthesis', 'verification', 'commit',
+  'discussion', 'synthesis-recovery', 'manual_retry',
+])
 const INCOMPLETE_TOOL_EVENT_TYPES = new Set(['tool_start', 'tool_update'])
 const FAILED_TOOL_STATUSES = new Set(['failed', 'stopped', 'timeout', 'interrupted'])
 const PUBLIC_ID = /^[A-Za-z0-9._:-]{1,120}$/
@@ -109,6 +114,7 @@ function normalizeRawEvent(input) {
   if (detail) event.detail = detail
   if (delta) event.delta = delta
   if (type === 'answer_delta' && !delta) return null
+  if (type === 'answer_delta' && input.replace === true) event.replace = true
   return event
 }
 
@@ -163,25 +169,31 @@ function normalizeSourceMessageIds(value) {
     .slice(0, 32)
 }
 
-function normalizeOutcomeRefs(input) {
+function normalizeOutcomeRefs(input, options = {}) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return {}
   const refs = {}
-  let remaining = MAX_OUTCOME_REFS
+  const strict = options.strict === true
   for (const [field, pattern] of Object.entries(OUTCOME_REF_PATTERNS)) {
-    if (!remaining) break
-    const values = [...new Set((Array.isArray(input[field]) ? input[field] : [])
+    const raw = Array.isArray(input[field]) ? input[field] : []
+    if (strict && raw.length > MAX_OUTCOME_REFS) {
+      throw new Error('RUN_HARNESS_V4_OUTCOME_REFS_INVALID')
+    }
+    const values = [...new Set(raw
       .map(value => String(value || ''))
       .filter(value => pattern.test(value)))]
-      .slice(0, remaining)
+      .slice(0, MAX_OUTCOME_REFS)
     if (values.length) refs[field] = values
-    remaining -= values.length
+  }
+  const rawWorkflowOutcomeRefs = Array.isArray(input.workflowOutcomeRefs)
+    ? input.workflowOutcomeRefs
+    : []
+  if (strict && rawWorkflowOutcomeRefs.length > MAX_OUTCOME_REFS) {
+    throw new Error('RUN_HARNESS_V4_OUTCOME_REFS_INVALID')
   }
   const workflowOutcomeRefs = []
   const seenWorkflowOutcomeRefs = new Set()
-  for (const value of Array.isArray(input.workflowOutcomeRefs)
-    ? input.workflowOutcomeRefs
-    : []) {
-    if (!remaining) break
+  for (const value of rawWorkflowOutcomeRefs) {
+    if (workflowOutcomeRefs.length >= MAX_OUTCOME_REFS) break
     let ref
     try {
       ref = normalizeContentBlobRef(value)
@@ -192,7 +204,6 @@ function normalizeOutcomeRefs(input) {
     if (seenWorkflowOutcomeRefs.has(key)) continue
     seenWorkflowOutcomeRefs.add(key)
     workflowOutcomeRefs.push(ref)
-    remaining -= 1
   }
   if (workflowOutcomeRefs.length) refs.workflowOutcomeRefs = workflowOutcomeRefs
   return refs
@@ -242,6 +253,10 @@ function normalizeContextStats(input) {
     const value = String(input[field] || '')
     if (SHA256.test(value)) context[field] = value
   }
+  const operationId = cleanId(input.operationId)
+  if (operationId) context.operationId = operationId
+  const snapshotHash = String(input.snapshotHash || '')
+  if (SHA256.test(snapshotHash)) context.snapshotHash = snapshotHash
   if (input.sessionRotated === true) context.sessionRotated = true
   const contextPackId = normalizeContextPackId(input.contextPackId)
   if (contextPackId) context.contextPackId = contextPackId
@@ -258,6 +273,10 @@ function normalizeContextStats(input) {
   if (externalRunRef) context.externalRunRef = externalRunRef
   const outcomeRefs = normalizeOutcomeRefs(input.outcomeRefs)
   if (Object.keys(outcomeRefs).length) context.outcomeRefs = outcomeRefs
+  if (input.taskDecision != null) {
+    try { context.taskDecision = parseTaskDecision(input.taskDecision) }
+    catch { /* malformed task judgments cannot authorize completion */ }
+  }
   const connectorContext = normalizeConnectorContext(input)
   if (connectorContext) Object.assign(context, connectorContext)
   return context
@@ -322,6 +341,11 @@ function normalizeCapsuleRound(value, runId, agentRunId, hasExplicitRound) {
   return inferred <= 100000 ? inferred : null
 }
 
+function normalizeTracePhase(value) {
+  const phase = cleanText(value, 40, { inline: true }).toLowerCase()
+  return TRACE_PHASES.has(phase) ? phase : ''
+}
+
 function normalizeTraceCapsule(input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null
   const runId = cleanId(input.runId)
@@ -333,6 +357,8 @@ function normalizeTraceCapsule(input) {
     agentRunId,
     Object.prototype.hasOwnProperty.call(input, 'round'),
   )
+  const phase = normalizeTracePhase(input.phase)
+  const executionSequence = boundedNumber(input.executionSequence, 1, 100000)
   const events = (Array.isArray(input.events) ? input.events : [])
     .slice(0, MAX_CAPSULE_EVENTS)
     .map(normalizeCapsuleEvent)
@@ -341,6 +367,8 @@ function normalizeTraceCapsule(input) {
     runId,
     agentRunId,
     ...(round != null ? { round } : {}),
+    ...(phase ? { phase } : {}),
+    ...(executionSequence != null ? { executionSequence } : {}),
     status: cleanStatus(input.status, 'completed'),
     summary: cleanText(input.summary, 1200),
     events,
@@ -357,6 +385,7 @@ function traceCapsuleFromAgentRun(input, options = {}) {
   const kind = cleanId(input.kind || input.agentKind)
   if (!runId || !agentRunId || !kind) return null
   const round = boundedNumber(input.round, 0, 100000)
+  const phase = normalizeTracePhase(options.phase || input.phase)
   const status = cleanStatus(options.status || input.status, 'interrupted')
   const capsuleEvents = (Array.isArray(input.events) ? input.events : [])
     .filter(item => CAPSULE_EVENT_TYPES.has(String(item?.type || '').toLowerCase()))
@@ -381,6 +410,10 @@ function traceCapsuleFromAgentRun(input, options = {}) {
     runId,
     agentRunId,
     round,
+    ...(phase ? { phase } : {}),
+    ...(Number.isInteger(options.executionSequence)
+      ? { executionSequence: options.executionSequence }
+      : {}),
     status,
     summary: narrative?.summary || input.summary || '',
     events: capsuleEvents,

desktop/src/runs/run-harness.cjs

@@ -149,7 +149,7 @@ class RunHarness {
     return next
   }
 
-  beginAgent(kind, round = 0, sourceMessageIds = []) {
+  beginAgent(kind, round = 0, sourceMessageIds = [], options = {}) {
     const safeKind = cleanId(kind)
     if (!safeKind) throw new Error('RUN_HARNESS_AGENT_REQUIRED')
     if (!this.targetKinds.includes(safeKind)) {
@@ -184,6 +184,10 @@ class RunHarness {
       seenSeqs: [],
       eventCursor: 0,
       context: {},
+      // Per-topic dispatch order; the live bubble and the saved reply share it.
+      ...(Number.isSafeInteger(options?.turnSeq) && options.turnSeq > 0
+        ? { turnSeq: options.turnSeq }
+        : {}),
     }
     this.agentRuns.push(run)
     while (this.agentRuns.length > this.maxAgentRuns) {
@@ -196,7 +200,8 @@ class RunHarness {
   record(run, normalized) {
     let input = normalized
     if (normalized.type === 'answer_delta') {
-      const remaining = Math.max(0, this.maxOutputChars - run.output.length)
+      const currentLength = normalized.replace === true ? 0 : run.output.length
+      const remaining = Math.max(0, this.maxOutputChars - currentLength)
       if (!remaining) {
         run.truncated = true
         return null
@@ -220,7 +225,7 @@ class RunHarness {
       run.seenSeqs.splice(0, run.seenSeqs.length - MAX_SEEN_EVENT_SEQUENCES)
     }
     if (event.type === 'answer_delta') {
-      const next = `${run.output}${event.delta}`
+      const next = event.replace === true ? event.delta : `${run.output}${event.delta}`
       if (next.length > this.maxOutputChars) run.truncated = true
       run.output = next.slice(0, this.maxOutputChars)
       return event
@@ -297,10 +302,15 @@ class RunHarness {
       status: run.status,
       title: 'agent',
     })
+    const phase = context && typeof context === 'object' ? context.phase : ''
     run.context = normalizeContextStats(context)
     const capsule = traceCapsuleFromAgentRun(run, {
       runId: this.runId,
       status: run.status,
+      phase,
+      executionSequence: context && Number.isInteger(context.executionSequence)
+        ? context.executionSequence
+        : undefined,
       context: run.context,
     })
     return { event, capsule }
@@ -322,6 +332,7 @@ class RunHarness {
       seenSeqs: [...run.seenSeqs],
       eventCursor: run.eventCursor,
       context: { ...run.context },
+      ...(run.turnSeq ? { turnSeq: run.turnSeq } : {}),
     }))
   }
 }

desktop/src/runs/run-journal.cjs

@@ -3,8 +3,10 @@ const fs = require('node:fs')
 const path = require('node:path')
 
 const { hasValidStoredRecordShape } = require('./run-ledger-records.cjs')
+const { atomicWritePrivateFile } = require('../security/private-file.cjs')
 
 const JOURNAL_VERSION = 1
+const DEFAULT_COMPACTION_BYTES = 4 * 1024 * 1024
 const JOURNAL_ID = /^[A-Za-z0-9._:-]{1,160}$/
 const MAX_CHANGE_ITEMS = 1024
 const CHANGE_FIELDS = new Set(['replace', 'upserts', 'removedRunIds'])
@@ -26,8 +28,8 @@ const CONTEXT_FIELDS = new Set([
   'includedCount', 'omittedCount', 'charCount', 'sessionRotated', 'externalRunRef',
   'contextMode', 'promptChars', 'contextPackId', 'contextPackState', 'deliveryRecordIds',
   'sessionProvenance', 'outcomeRefs', 'sourceCount', 'sourceHash', 'promptBytes',
-  'promptHash', 'wirePayloadBytes', 'wirePayloadHash',
-  'connector', 'connectorEventState',
+  'promptHash', 'wirePayloadBytes', 'wirePayloadHash', 'operationId', 'snapshotHash',
+  'connector', 'connectorEventState', 'taskDecision',
 ])
 
 function clone(value) {
@@ -89,6 +91,9 @@ class RunJournal {
       ? options.storagePath.trim()
       : ''
     if (!this.storagePath) throw new Error('RUN_JOURNAL_STORAGE_REQUIRED')
+    this.compactionBytes = Number.isFinite(options.compactionBytes)
+      ? Math.max(1024, Math.floor(options.compactionBytes))
+      : DEFAULT_COMPACTION_BYTES
     this.sequence = 0
     this.loadError = null
     this.hasBaseline = false
@@ -231,6 +236,56 @@ class RunJournal {
     this.commit(transactionId, timestamp)
   }
 
+  compact(runs, timestamp) {
+    this.assertLoaded()
+    const change = {
+      replace: true,
+      upserts: clone(runs),
+      removedRunIds: [],
+    }
+    if (!validChange(change)) throw new Error('RUN_JOURNAL_CHANGE_INVALID')
+    const transactionId = `txn-${timestamp}-${crypto.randomBytes(8).toString('hex')}`
+    const entries = [
+      {
+        version: JOURNAL_VERSION,
+        sequence: 1,
+        transactionId,
+        timestamp,
+        phase: 'prepare',
+        change,
+      },
+      {
+        version: JOURNAL_VERSION,
+        sequence: 2,
+        transactionId,
+        timestamp,
+        phase: 'commit',
+      },
+    ]
+    atomicWritePrivateFile(
+      this.storagePath,
+      `${entries.map(entry => JSON.stringify(entry)).join('\n')}\n`,
+    )
+    this.sequence = 2
+    this.runs.clear()
+    this.pending.clear()
+    this.hasBaseline = false
+    this.apply(change)
+  }
+
+  compactIfNeeded(runs, timestamp) {
+    this.assertLoaded()
+    try {
+      if (!fs.existsSync(this.storagePath) || fs.statSync(this.storagePath).size < this.compactionBytes) {
+        return false
+      }
+      this.compact(runs, timestamp)
+      return true
+    } catch {
+      return false
+    }
+  }
+
   recover() {
     this.assertLoaded()
     return this.hasBaseline ? clone([...this.runs.values()]) : null

desktop/src/runs/run-ledger-records.cjs

@@ -1,4 +1,5 @@
 const { redactSecrets } = require('../security/secret-redaction.cjs')
+const { parseTaskDecision } = require('../collaboration/task-decision.cjs')
 const { normalizeExternalRunRef } = require('../agents/agent-runtime-contract.cjs')
 const { parseConnectorRunSnapshot } = require('../agents/connectors/agent-connector-registry.cjs')
 const { parseRunEventState } = require('./run-event-protocol.cjs')
@@ -27,6 +28,7 @@ const {
 } = require('./failure-policy.cjs')
 const { parseCollaborationState } = require('../collaboration/collaboration-records.cjs')
 const { parseTaskGraphCursor } = require('../collaboration/task-graph-records.cjs')
+const { parseOrchestrationV4 } = require('../collaboration/orchestration-v4-records.cjs')
 
 const DEFAULT_MAX_DURABLE_AGENT_RUNS = 256
 const MAX_TARGET_KINDS = 32
@@ -41,8 +43,8 @@ const CONTEXT_FIELDS = new Set([
   'includedCount', 'omittedCount', 'charCount', 'sessionRotated', 'externalRunRef',
   'contextMode', 'promptChars', 'contextPackId', 'contextPackState', 'deliveryRecordIds',
   'sessionProvenance', 'outcomeRefs', 'sourceCount', 'sourceHash', 'promptBytes',
-  'promptHash', 'wirePayloadBytes', 'wirePayloadHash',
-  'connector', 'connectorEventState',
+  'promptHash', 'wirePayloadBytes', 'wirePayloadHash', 'operationId', 'snapshotHash',
+  'connector', 'connectorEventState', 'taskDecision',
 ])
 const CONTEXT_PACK_STATES = new Set(['captured', 'legacy-unavailable'])
 const REQUIRED_BUDGET_FIELDS = new Set(['limits', 'used', 'source', 'enforcement', 'startedAt'])
@@ -54,18 +56,31 @@ const HUMAN_GATE_ID = /^human-gate-[a-f0-9]{64}$/
 const SHA256 = /^[a-f0-9]{64}$/
 const CONTINUATION_FIELDS = new Set([
   'gateId', 'gateType', 'resumeKind', 'state', 'agentRunId', 'agentKind',
+  'publicAgentRunId',
   'round', 'createdAt', 'updatedAt', 'requestId', 'requestHash',
-  'sessionRefHash', 'sessionProvenanceHash',
+  'sessionRefHash', 'sessionProvenanceHash', 'stateEpoch',
+  'phase', 'slotId', 'operationId', 'snapshotHash',
+])
+const CONTINUATION_INVOCATION_FIELDS = ['phase', 'slotId', 'operationId', 'snapshotHash']
+const CONTINUATION_V4_PHASES = new Set([
+  'proposal', 'discussion', 'challenge', 'work', 'synthesis', 'verification',
 ])
 const CONTINUATION_GATE_TYPES = new Set(['permission', 'budget', 'decision', 'retry', 'input'])
-const CONTINUATION_RESUME_KINDS = new Set(['agent_slot', 'role_review_decision'])
+const CONTINUATION_RESUME_KINDS = new Set([
+  'agent_slot', 'role_review_decision', 'v4_human_gate', 'v4_synthesis_recovery', 'v4_task_decision',
+])
 const CONTINUATION_STATES = new Set([
   'pending', 'ready', 'resuming', 'completed', 'failed', 'cancelled',
 ])
+const ACTIVE_CONTINUATION_STATES = new Set(['pending', 'ready', 'resuming'])
 const ORCHESTRATION_FIELDS = new Set([
   'version', 'workflow', 'currentKind', 'pendingKinds', 'activeKinds',
   'successfulKinds', 'agreementKinds', 'attachmentRecipients',
-  'totalSuccesses', 'terminalFailureOccurred', 'collaboration', 'template', 'taskGraph',
+  'totalSuccesses', 'terminalFailureOccurred', 'executionSequence',
+  'collaboration', 'template', 'taskGraph',
+  'phase', 'discussionStyle', 'discussionWriterKind', 'batchId', 'round', 'currentKinds', 'snapshotHash', 'snapshot', 'plan',
+  'slots', 'deliveryWatermarks', 'deliveryState', 'commitState', 'challengeBindings', 'synthesisBinding',
+  'synthesisRecovery', 'convergence', 'coordinationPlan', 'workReceipts', 'candidateCommit',
 ])
 const ORCHESTRATION_WORKFLOWS = new Set(['manual', 'auto'])
 
@@ -226,7 +241,7 @@ function normalizeAgentRun(input, parent, fallbackTimestamp) {
     'includedCount', 'omittedCount', 'charCount', 'sessionRotated', 'externalRunRef',
     'contextMode', 'promptChars', 'contextPackId', 'deliveryRecordIds', 'sessionProvenance', 'outcomeRefs',
     'sourceCount', 'sourceHash', 'promptBytes', 'promptHash', 'wirePayloadBytes', 'wirePayloadHash',
-    'connector', 'connectorEventState',
+    'operationId', 'snapshotHash', 'connector', 'connectorEventState', 'taskDecision',
   ].some(key => hasOwn(input.context, key))
   const rawEvents = Array.isArray(input.events) ? input.events : []
   const rawSourceIds = Array.isArray(input.sourceMessageIds) ? input.sourceMessageIds : []
@@ -364,6 +379,8 @@ function normalizeContinuation(input) {
   const resumeKind = String(input.resumeKind || '')
   const state = String(input.state || '')
   const agentRunId = cleanId(input.agentRunId)
+  const hasPublicAgentRunId = hasOwn(input, 'publicAgentRunId')
+  const publicAgentRunId = cleanId(input.publicAgentRunId)
   const agentKind = cleanId(input.agentKind)
   const round = boundedNumber(input.round, 0, 100000)
   const createdAt = safeTimestamp(input.createdAt, 0)
@@ -372,30 +389,103 @@ function normalizeContinuation(input) {
   const requestHash = String(input.requestHash || '')
   const sessionRefHash = String(input.sessionRefHash || '')
   const sessionProvenanceHash = String(input.sessionProvenanceHash || '')
+  const hasStateEpoch = hasOwn(input, 'stateEpoch')
+  const stateEpoch = boundedNumber(input.stateEpoch, 0, 1000000)
+  const invocationFieldCount = CONTINUATION_INVOCATION_FIELDS
+    .filter(field => hasOwn(input, field)).length
+  const hasInvocationBinding = invocationFieldCount === CONTINUATION_INVOCATION_FIELDS.length
+  const phase = String(input.phase || '')
+  const slotId = cleanId(input.slotId)
+  const operationId = cleanId(input.operationId)
+  const snapshotHash = String(input.snapshotHash || '')
   const hasRequestBinding = requestId && SHA256.test(requestHash)
     && SHA256.test(sessionRefHash) && SHA256.test(sessionProvenanceHash)
   if (!HUMAN_GATE_ID.test(gateId) || !CONTINUATION_GATE_TYPES.has(gateType)
       || !CONTINUATION_RESUME_KINDS.has(resumeKind)
       || !CONTINUATION_STATES.has(state) || !agentRunId || !agentKind
+      || (hasPublicAgentRunId && !publicAgentRunId)
       || (resumeKind === 'role_review_decision' && gateType !== 'decision')
-      || (gateType === 'input' && !hasRequestBinding)
+      || (resumeKind === 'v4_task_decision'
+        && (gateType !== 'input' || !hasInvocationBinding || phase !== 'discussion'))
+      || (resumeKind === 'v4_human_gate'
+        && (gateType !== 'decision' || !hasStateEpoch || stateEpoch < 1))
+      || (resumeKind === 'v4_synthesis_recovery'
+        && (gateType !== 'decision' || !hasStateEpoch))
+      || (!['v4_human_gate', 'v4_synthesis_recovery'].includes(resumeKind) && hasStateEpoch)
+      || (invocationFieldCount > 0 && !hasInvocationBinding)
+      || (hasInvocationBinding && (!['agent_slot', 'v4_task_decision'].includes(resumeKind)
+        || !CONTINUATION_V4_PHASES.has(phase) || !slotId || !operationId
+        || !SHA256.test(snapshotHash)))
+      || (gateType === 'input' && resumeKind !== 'v4_task_decision' && !hasRequestBinding)
       || (!hasRequestBinding && [requestId, requestHash, sessionRefHash, sessionProvenanceHash]
         .some(Boolean))) return undefined
   return {
-    gateId, gateType, resumeKind, state, agentRunId, agentKind,
+    gateId, gateType, resumeKind, state, agentRunId,
+    ...(hasPublicAgentRunId ? { publicAgentRunId } : {}),
+    agentKind,
     round, createdAt, updatedAt,
+    ...(hasStateEpoch ? { stateEpoch } : {}),
+    ...(hasInvocationBinding ? { phase, slotId, operationId, snapshotHash } : {}),
     ...(hasRequestBinding ? {
       requestId, requestHash, sessionRefHash, sessionProvenanceHash,
     } : {}),
   }
 }
 
+function continuationBindingMatchesOrchestration(continuation, orchestration) {
+  if (continuation?.publicAgentRunId && ACTIVE_CONTINUATION_STATES.has(continuation.state)) {
+    if (orchestration?.version !== 4) return false
+    const slots = orchestration.slots.filter(slot => (
+      slot.agentKind === continuation.agentKind
+        && slot.agentRunId === continuation.publicAgentRunId
+    ))
+    if (slots.length !== 1) return false
+    if (continuation.resumeKind === 'agent_slot'
+        && slots[0].slotId !== continuation.slotId) return false
+  }
+  const hasBinding = CONTINUATION_INVOCATION_FIELDS.every(field => hasOwn(continuation || {}, field))
+  if (!hasBinding) return true
+  if (!['agent_slot', 'v4_task_decision'].includes(continuation.resumeKind)
+      || orchestration?.version !== 4) return false
+  if (!['pending', 'ready', 'resuming'].includes(continuation.state)) return true
+  const slots = orchestration.slots.filter(slot => slot.slotId === continuation.slotId)
+  const orchestrationRound = orchestration.workflow === 'manual'
+    ? (orchestration.snapshot?.round || 0)
+    : orchestration.round
+  return orchestration.phase === continuation.phase
+    && orchestrationRound === continuation.round
+    && orchestration.snapshotHash === continuation.snapshotHash
+    && slots.length === 1
+    && slots[0].agentKind === continuation.agentKind
+    && slots[0].phase === continuation.phase
+    && slots[0].operationId === continuation.operationId
+    && slots[0].snapshotHash === continuation.snapshotHash
+}
+
+function continuationPublicAttemptMatches(continuation, agentRuns) {
+  if (!continuation?.publicAgentRunId
+      || !ACTIVE_CONTINUATION_STATES.has(continuation.state)) return true
+  return agentRuns.filter(agentRun => (
+    agentRun?.agentRunId === continuation.publicAgentRunId
+      && agentRun?.kind === continuation.agentKind
+  )).length === 1
+}
+
 function normalizeOrchestration(input) {
   if (input == null) return null
   if (!isRecord(input) || Object.keys(input).some(field => !ORCHESTRATION_FIELDS.has(field))) {
     return undefined
   }
   const version = boundedNumber(input.version, 0, 100)
+  if (version === 4) {
+    try {
+      const parsed = parseOrchestrationV4(input)
+      if (hasOwn(parsed, 'collaboration')) parseCollaborationState(parsed.collaboration)
+      return parsed
+    } catch {
+      return undefined
+    }
+  }
   const workflow = String(input.workflow || '')
   const currentKind = cleanId(input.currentKind)
   const pendingKinds = normalizeKinds(input.pendingKinds)
@@ -404,10 +494,21 @@ function normalizeOrchestration(input) {
   const agreementKinds = normalizeKinds(input.agreementKinds)
   const attachmentRecipients = normalizeKinds(input.attachmentRecipients)
   const totalSuccesses = boundedNumber(input.totalSuccesses, 0, 1000000)
+  const executionSequence = boundedNumber(input.executionSequence, 0, 1000000)
+  const v4OnlyFields = [
+    'phase', 'discussionStyle', 'discussionWriterKind', 'batchId', 'round', 'currentKinds', 'snapshotHash', 'snapshot', 'plan',
+    'slots', 'deliveryWatermarks', 'deliveryState', 'commitState', 'challengeBindings',
+    'synthesisBinding', 'synthesisRecovery', 'convergence', 'candidateCommit',
+  ]
   if (![1, 2, 3].includes(version) || !ORCHESTRATION_WORKFLOWS.has(workflow)
       || (version === 1 && hasOwn(input, 'collaboration'))
       || (version === 2 && workflow !== 'auto')
       || (version < 3 && (hasOwn(input, 'template') || hasOwn(input, 'taskGraph')))
+      || (hasOwn(input, 'executionSequence')
+        && (!Number.isInteger(input.executionSequence)
+          || input.executionSequence < 0
+          || input.executionSequence > 1000000))
+      || (version < 4 && v4OnlyFields.some(field => hasOwn(input, field)))
       || (version === 3 && (workflow !== 'auto' || input.template !== 'task-graph'))) {
     return undefined
   }
@@ -438,11 +539,46 @@ function normalizeOrchestration(input) {
     attachmentRecipients,
     totalSuccesses,
     terminalFailureOccurred: input.terminalFailureOccurred === true,
+    ...(hasOwn(input, 'executionSequence') ? { executionSequence } : {}),
     ...(version >= 2 ? { collaboration } : {}),
     ...(version === 3 ? { template: 'task-graph', taskGraph } : {}),
   }
 }
 
+function orchestrationKinds(orchestration) {
+  if (!orchestration) return []
+  return [
+    orchestration.currentKind,
+    ...(orchestration.currentKinds || []),
+    ...(orchestration.pendingKinds || []),
+    ...(orchestration.activeKinds || []),
+    ...(orchestration.successfulKinds || []),
+    ...(orchestration.agreementKinds || []),
+    ...(orchestration.attachmentRecipients || []),
+    ...(orchestration.taskGraph?.graph.nodes.map(node => node.agentKind) || []),
+    ...(orchestration.plan?.assignments?.map(assignment => assignment.agentKind) || []),
+    ...(orchestration.slots?.map(slot => slot.agentKind) || []),
+    ...(orchestration.deliveryWatermarks?.map(watermark => watermark.agentKind) || []),
+    ...(orchestration.commitState?.committedKinds || []),
+    ...(orchestration.commitState?.pendingKinds || []),
+    ...(orchestration.commitState?.writerKind ? [orchestration.commitState.writerKind] : []),
+    ...(orchestration.candidateCommit?.writerKind ? [orchestration.candidateCommit.writerKind] : []),
+    ...(orchestration.synthesisBinding?.candidates?.map(candidate => candidate.kind) || []),
+    ...(orchestration.synthesisBinding ? [
+      orchestration.synthesisBinding.writerKind,
+      ...orchestration.synthesisBinding.verificationKinds,
+    ] : []),
+    ...(orchestration.synthesisRecovery ? [
+      orchestration.synthesisRecovery.originalWriterKind,
+      orchestration.synthesisRecovery.activeWriterKind,
+      ...orchestration.synthesisRecovery.verificationKinds,
+      ...orchestration.synthesisRecovery.rankedKinds,
+      ...orchestration.synthesisRecovery.triedWriters,
+      ...orchestration.synthesisRecovery.attempts.map(attempt => attempt.writerKind),
+    ] : []),
+  ].filter(Boolean)
+}
+
 function hasValidStoredRecordShape(input) {
   if (!isRecord(input)) return false
   if (!hasStoredFieldTypes(input, [
@@ -465,16 +601,21 @@ function hasValidStoredRecordShape(input) {
   if (hasOwn(input, 'budget') && !hasValidStoredBudgetSnapshot(input.budget)) return false
   if (hasOwn(input, 'attemptHistory')
       && !hasValidStoredAttemptHistory(input.attemptHistory)) return false
+  const continuation = hasOwn(input, 'continuation')
+    ? normalizeContinuation(input.continuation)
+    : null
   if (hasOwn(input, 'continuation')) {
-    const continuation = normalizeContinuation(input.continuation)
     if (continuation === undefined
         || canonicalJson(continuation) !== canonicalJson(input.continuation)) return false
   }
+  const storedOrchestration = hasOwn(input, 'orchestration')
+    ? normalizeOrchestration(input.orchestration)
+    : null
   if (hasOwn(input, 'orchestration')) {
-    const orchestration = normalizeOrchestration(input.orchestration)
-    if (orchestration === undefined
-        || canonicalJson(orchestration) !== canonicalJson(input.orchestration)) return false
+    if (storedOrchestration === undefined
+        || canonicalJson(storedOrchestration) !== canonicalJson(input.orchestration)) return false
   }
+  if (!continuationBindingMatchesOrchestration(continuation, storedOrchestration)) return false
   if (hasOwn(input, 'remoteJob')) {
     if (!isRecord(input.remoteJob)
         || Object.keys(input.remoteJob).some(field => !REMOTE_JOB_FIELDS.has(field))
@@ -507,28 +648,29 @@ function hasValidStoredRecordShape(input) {
     !Array.isArray(input.targetKinds)
     || input.targetKinds.some(kind => typeof kind !== 'string' || !cleanId(kind))
   )) return false
-  if (!hasOwn(input, 'agentRuns')) return true
+  if (!hasOwn(input, 'agentRuns')) return !continuation?.publicAgentRunId
+    || !ACTIVE_CONTINUATION_STATES.has(continuation.state)
   if (!Array.isArray(input.agentRuns)) return false
 
   const targetKinds = normalizeKinds(input.targetKinds)
   const orchestration = normalizeOrchestration(input.orchestration)
-  if (orchestration && [
-    orchestration.currentKind,
-    ...orchestration.pendingKinds,
-    ...orchestration.activeKinds,
-    ...orchestration.successfulKinds,
-    ...orchestration.agreementKinds,
-    ...orchestration.attachmentRecipients,
-    ...(orchestration.taskGraph?.graph.nodes.map(node => node.agentKind) || []),
-  ].filter(Boolean).some(kind => !targetKinds.includes(kind))) return false
+  if (orchestration && orchestrationKinds(orchestration)
+    .some(kind => !targetKinds.includes(kind))) return false
   const parent = {
     runId: cleanId(input.runId),
     groupId: cleanGroupId(input.groupId),
     threadRootId: cleanId(input.threadRootId),
     targetKinds,
   }
+  const candidateCommit = orchestration?.candidateCommit
+  if (candidateCommit && (
+    candidateCommit.runId !== parent.runId
+      || candidateCommit.taskId !== cleanId(input.taskId)
+      || candidateCommit.groupId !== parent.groupId
+      || candidateCommit.threadRootId !== parent.threadRootId
+  )) return false
   const fallbackTimestamp = safeTimestamp(input.startedAt, 0)
-  return input.agentRuns.every(agentRun => {
+  const validAgentRuns = input.agentRuns.every(agentRun => {
     if (!isRecord(agentRun)) return false
     if (!hasStoredFieldTypes(agentRun, [
       'agentRunId', 'kind', 'output', 'reason',
@@ -563,6 +705,11 @@ function hasValidStoredRecordShape(input) {
             && (typeof agentRun.context[field] !== 'string'
               || !SHA256.test(agentRun.context[field]))) return false
       }
+      if (hasOwn(agentRun.context, 'operationId')
+          && cleanId(agentRun.context.operationId) !== agentRun.context.operationId) return false
+      if (hasOwn(agentRun.context, 'snapshotHash')
+          && (typeof agentRun.context.snapshotHash !== 'string'
+            || !SHA256.test(agentRun.context.snapshotHash))) return false
       if (hasOwn(agentRun.context, 'contextPackId')
           && normalizeContextPackId(agentRun.context.contextPackId)
             !== agentRun.context.contextPackId) return false
@@ -590,6 +737,12 @@ function hasValidStoredRecordShape(input) {
             || canonicalJson(normalizedProvenance)
               !== canonicalJson(agentRun.context.sessionProvenance)) return false
       }
+      if (hasOwn(agentRun.context, 'taskDecision')) {
+        try {
+          if (canonicalJson(parseTaskDecision(agentRun.context.taskDecision))
+              !== canonicalJson(agentRun.context.taskDecision)) return false
+        } catch { return false }
+      }
       if (hasOwn(agentRun.context, 'outcomeRefs')) {
         if (!isRecord(agentRun.context.outcomeRefs)) return false
         const normalizedOutcomeRefs = normalizeOutcomeRefs(agentRun.context.outcomeRefs)
@@ -658,6 +811,7 @@ function hasValidStoredRecordShape(input) {
       }, normalized.lastActivityAt).length === 1
     ))
   })
+  return validAgentRuns && continuationPublicAttemptMatches(continuation, input.agentRuns)
 }
 
 function selectedValue(input, existing, key) {
@@ -759,16 +913,15 @@ function normalizeRecord(input, options = {}) {
   const rawOrchestration = selectedValue(input, existing, 'orchestration')
   const orchestration = normalizeOrchestration(rawOrchestration)
   if (orchestration === undefined) return null
-  if (orchestration && orchestration.workflow !== mode) return null
-  if (orchestration && [
-    orchestration.currentKind,
-    ...orchestration.pendingKinds,
-    ...orchestration.activeKinds,
-    ...orchestration.successfulKinds,
-    ...orchestration.agreementKinds,
-    ...orchestration.attachmentRecipients,
-    ...(orchestration.taskGraph?.graph.nodes.map(node => node.agentKind) || []),
-  ].filter(Boolean).some(kind => !targetKinds.includes(kind))) return null
+  if (!continuationBindingMatchesOrchestration(continuation, orchestration)) return null
+  if (!continuationPublicAttemptMatches(continuation, agentRuns)) return null
+  if (orchestration && orchestration.version < 4 && orchestration.workflow !== mode) return null
+  if (orchestration && orchestration.version === 4) {
+    const expectedWorkflow = orchestration.template === 'discussion' ? 'auto' : 'manual'
+    if (![expectedWorkflow, orchestration.template].includes(orchestration.workflow)) return null
+  }
+  if (orchestration && orchestrationKinds(orchestration)
+    .some(kind => !targetKinds.includes(kind))) return null
 
   const record = {
     runId,

desktop/src/runs/run-ledger.cjs

@@ -107,8 +107,9 @@ function journalRun(record, existing = null, includeAllAgents = false) {
   const previous = new Map((existing?.agentRuns || []).map(agentRun => [
     agentRun.agentRunId, agentRun,
   ]))
+  const publicAgentRunId = record.continuation?.publicAgentRunId || ''
   const agentRuns = record.agentRuns.filter((agentRun) => {
-    if (includeAllAgents) return true
+    if (includeAllAgents || agentRun.agentRunId === publicAgentRunId) return true
     const prior = previous.get(agentRun.agentRunId)
     return !prior || journalAgentSignature(prior) !== journalAgentSignature(agentRun)
   }).map(journalAgentRun)
@@ -164,7 +165,10 @@ class RunLedger {
     ))
     this.loadError = null
     this.snapshotError = null
-    this.journal = new RunJournal({ storagePath: this.journalPath })
+    this.journal = new RunJournal({
+      storagePath: this.journalPath,
+      compactionBytes: options.journalCompactionBytes,
+    })
     this.runs = this.load()
   }
 
@@ -307,7 +311,7 @@ class RunLedger {
   persist(runs = this.runs) {
     atomicWritePrivateFile(
       this.storagePath,
-      `${JSON.stringify({ version: STORE_VERSION, runs }, null, 2)}\n`,
+      `${JSON.stringify({ version: STORE_VERSION, runs })}\n`,
     )
   }
 
@@ -372,6 +376,7 @@ class RunLedger {
     }
     this.runs = nextRuns
     this.snapshotError = null
+    this.journal.compactIfNeeded(this.journalBaseline(), timestamp)
   }
 
   checkpoint(record) {

desktop/src/runs/run-scheduler.cjs

@@ -1,13 +1,20 @@
-const DEFAULT_TASK_CONCURRENCY = 2
-const DEFAULT_WORKSPACE_CONCURRENCY = 2
-const DEFAULT_GLOBAL_CONCURRENCY = 4
+const DEFAULT_TASK_CONCURRENCY = null
+const DEFAULT_WORKSPACE_CONCURRENCY = null
+const DEFAULT_GLOBAL_CONCURRENCY = null
+const schedulerPauseTokens = new WeakMap()
+const schedulerLeaseBindings = new WeakMap()
 
 function positiveLimit(value, fallback) {
+  if (value == null) return fallback
   const number = Number(value)
   if (!Number.isFinite(number) || number < 1) return fallback
   return Math.min(1024, Math.floor(number))
 }
 
+function belowLimit(active, limit) {
+  return limit === null || active < limit
+}
+
 function schedulerError(code) {
   return Object.assign(new Error(code), { code })
 }
@@ -18,6 +25,28 @@ function resourceKey(value, code) {
   return key
 }
 
+function installTaskPause(scheduler, taskId) {
+  const token = Object.freeze({})
+  const pauses = schedulerPauseTokens.get(scheduler)
+  const tokens = pauses.get(taskId) || new Set()
+  tokens.add(token)
+  pauses.set(taskId, tokens)
+  return token
+}
+
+function removeTaskPause(scheduler, taskId, token) {
+  const pauses = schedulerPauseTokens.get(scheduler)
+  const tokens = pauses.get(taskId)
+  if (!tokens) return
+  tokens.delete(token)
+  if (!tokens.size) pauses.delete(taskId)
+}
+
+function taskPauseAllows(scheduler, entry) {
+  const tokens = schedulerPauseTokens.get(scheduler).get(entry.taskId)
+  return !tokens?.size || (entry.pauseToken && tokens.has(entry.pauseToken))
+}
+
 class RunScheduler {
   constructor(options = {}) {
     this.limits = Object.freeze({
@@ -29,8 +58,10 @@ class RunScheduler {
     this.activeGlobal = 0
     this.activeTasks = new Map()
     this.activeWorkspaces = new Map()
+    this.activeWorkspaceWriters = new Set()
     this.queue = []
     this.sequence = 0
+    schedulerPauseTokens.set(this, new Map())
   }
 
   resourceCount(collection, key) {
@@ -38,9 +69,12 @@ class RunScheduler {
   }
 
   canGrant(entry) {
-    return this.activeGlobal < this.limits.global
-      && this.resourceCount(this.activeTasks, entry.taskId) < this.limits.task
-      && this.resourceCount(this.activeWorkspaces, entry.workspaceKey) < this.limits.workspace
+    return taskPauseAllows(this, entry)
+      && (entry.permissionMode !== 'workspace-write'
+        || !this.activeWorkspaceWriters.has(entry.workspaceKey))
+      && belowLimit(this.activeGlobal, this.limits.global)
+      && belowLimit(this.resourceCount(this.activeTasks, entry.taskId), this.limits.task)
+      && belowLimit(this.resourceCount(this.activeWorkspaces, entry.workspaceKey), this.limits.workspace)
   }
 
   changeCount(collection, key, change) {
@@ -53,12 +87,14 @@ class RunScheduler {
     this.activeGlobal += 1
     this.changeCount(this.activeTasks, entry.taskId, 1)
     this.changeCount(this.activeWorkspaces, entry.workspaceKey, 1)
+    if (entry.permissionMode === 'workspace-write') this.activeWorkspaceWriters.add(entry.workspaceKey)
     entry.signal?.removeEventListener('abort', entry.abortHandler)
     let released = false
     const lease = Object.freeze({
       leaseId: entry.requestId,
       taskId: entry.taskId,
       workspaceKey: entry.workspaceKey,
+      permissionMode: entry.permissionMode,
       queuedAt: entry.queuedAt,
       acquiredAt: this.now(),
       release: () => {
@@ -67,10 +103,17 @@ class RunScheduler {
         this.activeGlobal -= 1
         this.changeCount(this.activeTasks, entry.taskId, -1)
         this.changeCount(this.activeWorkspaces, entry.workspaceKey, -1)
+        if (entry.permissionMode === 'workspace-write') this.activeWorkspaceWriters.delete(entry.workspaceKey)
         this.drain()
         return true
       },
     })
+    schedulerLeaseBindings.set(lease, Object.freeze({
+      taskId: entry.taskId,
+      workspaceKey: entry.workspaceKey,
+      permissionMode: entry.permissionMode,
+      signal: entry.signal,
+    }))
     entry.resolve(lease)
   }
 
@@ -90,12 +133,16 @@ class RunScheduler {
     }
   }
 
-  acquire(input = {}) {
+  #enqueueAcquire(input = {}, pauseToken = null) {
     let taskId
     let workspaceKey
+    const permissionMode = input.permissionMode == null ? 'read-only' : input.permissionMode
     try {
       taskId = resourceKey(input.taskId, 'RUN_SCHEDULER_TASK_REQUIRED')
       workspaceKey = resourceKey(input.workspaceKey, 'RUN_SCHEDULER_WORKSPACE_REQUIRED')
+      if (!['read-only', 'workspace-write'].includes(permissionMode)) {
+        throw schedulerError('RUN_SCHEDULER_PERMISSION_INVALID')
+      }
     } catch (error) {
       return Promise.reject(error)
     }
@@ -106,12 +153,14 @@ class RunScheduler {
         requestId: `lease-${++this.sequence}`,
         taskId,
         workspaceKey,
+        permissionMode,
         queuedAt: this.now(),
         signal,
         resolve,
         reject,
         cancelled: false,
         abortHandler: null,
+        pauseToken,
       }
       entry.abortHandler = () => {
         if (entry.cancelled) return
@@ -127,6 +176,10 @@ class RunScheduler {
     })
   }
 
+  acquire(input = {}) {
+    return this.#enqueueAcquire(input)
+  }
+
   async withLease(input, operation) {
     if (typeof operation !== 'function') throw schedulerError('RUN_SCHEDULER_OPERATION_REQUIRED')
     let activeLease = await this.acquire(input)
@@ -135,6 +188,7 @@ class RunScheduler {
       get leaseId() { return activeLease?.leaseId || '' },
       get taskId() { return activeLease?.taskId || '' },
       get workspaceKey() { return activeLease?.workspaceKey || '' },
+      get permissionMode() { return activeLease?.permissionMode || '' },
       get queuedAt() { return activeLease?.queuedAt || 0 },
       get acquiredAt() { return activeLease?.acquiredAt || 0 },
       release: () => {
@@ -144,25 +198,37 @@ class RunScheduler {
         activeLease = null
         return current?.release() || false
       },
-      suspend: async (waitingOperation) => {
+      suspend: async (waitingOperation, options = {}) => {
         if (typeof waitingOperation !== 'function') {
           throw schedulerError('RUN_SCHEDULER_OPERATION_REQUIRED')
         }
         if (closed || !activeLease) throw schedulerError('RUN_SCHEDULER_LEASE_INACTIVE')
-        activeLease.release()
-        activeLease = null
-        let result
-        let failure
+        const binding = schedulerLeaseBindings.get(activeLease)
+        const taskId = binding.taskId
+        const pauseToken = options?.pauseTask === true
+          ? installTaskPause(this, taskId)
+          : null
         try {
-          result = await waitingOperation()
-        } catch (error) {
-          failure = error
+          activeLease.release()
+          activeLease = null
+          let result
+          let failure
+          try {
+            result = await waitingOperation()
+          } catch (error) {
+            failure = error
+          }
+          if (!closed && !binding.signal?.aborted) {
+            activeLease = await this.#enqueueAcquire(binding, pauseToken)
+          }
+          if (failure) throw failure
+          return result
+        } finally {
+          if (pauseToken) {
+            removeTaskPause(this, taskId, pauseToken)
+            this.drain()
+          }
         }
-        if (!closed && !input?.signal?.aborted) {
-          activeLease = await this.acquire(input)
-        }
-        if (failure) throw failure
-        return result
       },
     })
     try {

desktop/src/shell/delivery-ipc.cjs

@@ -0,0 +1,86 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { z } = require('zod')
+
+const id = z.string().min(1).max(120).regex(/^[A-Za-z0-9._:-]+$/)
+function request(schema, input) {
+  const parsed = schema.safeParse(input)
+  if (!parsed.success) throw new Error('LOCAL_DELIVERY_INVALID')
+  return parsed.data
+}
+
+function registerDeliveryIpc({ registerTrustedHandle, getWorkspace, getAttachmentStore, dialog, getMainWindow }) {
+  const workspace = () => {
+    const value = getWorkspace()
+    if (!value) throw new Error('LOCAL_WORKSPACE_UNAVAILABLE')
+    return value
+  }
+  for (const method of ['save', 'review', 'revise']) {
+    registerTrustedHandle(`local-delivery:${method}`, input => {
+      const current = workspace()
+      if (method === 'review' && input?.accept === true) {
+        const task = current.delivery.task(input.taskId)
+        const version = current.delivery.version(task, input.versionId)
+        for (const attachment of version.attachments) {
+          const store = getAttachmentStore()
+          if (!store) throw new Error('LOCAL_ATTACHMENT_STORAGE_UNAVAILABLE')
+          store.read(attachment.id)
+        }
+      }
+      const result = current.delivery[method](input)
+      current.emitChanged()
+      return { taskId: method === 'save' ? result : input.taskId }
+    })
+  }
+  registerTrustedHandle('local-delivery:reuse', input => {
+    const { taskId } = request(z.strictObject({ taskId: id }), input)
+    const current = workspace()
+    const task = current.delivery.task(taskId)
+    const original = current.getGroup(task.groupId)
+    const root = path.join(path.dirname(current.storagePath), 'delivery-workspaces')
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 })
+    const workdir = fs.mkdtempSync(path.join(root, 'task-'))
+    let group
+    try {
+      group = current.createGroup({
+        name: task.brief.title, agentKinds: original.agentKinds,
+        conversationType: original.conversationType,
+        directAgentKind: original.directAgentKind,
+        workdir, allowWrite: false,
+      })
+      const newTaskId = current.delivery.save({ groupId: group.id, brief: task.brief })
+      current.emitChanged()
+      return { taskId: newTaskId, groupId: group.id }
+    } catch (error) {
+      if (group) current.deleteGroup(group.id)
+      fs.rmdirSync(workdir)
+      throw error
+    }
+  })
+  registerTrustedHandle('local-delivery:export', async input => {
+    const { taskId, versionId, attachmentId } = request(z.strictObject({
+      taskId: id, versionId: id, attachmentId: id.optional(),
+    }), input)
+    const current = workspace()
+    const task = current.delivery.task(taskId)
+    const version = current.delivery.version(task, versionId)
+    const attachment = attachmentId ? version.attachments.find(item => item.id === attachmentId) : null
+    if (attachmentId && !attachment) throw new Error('LOCAL_DELIVERY_NOT_FOUND')
+    let bytes
+    if (attachment) {
+      const store = getAttachmentStore()
+      if (!store) throw new Error('LOCAL_ATTACHMENT_STORAGE_UNAVAILABLE')
+      bytes = store.read(attachment.id)
+    } else bytes = Buffer.from(current.delivery.markdown(taskId, versionId), 'utf8')
+    const filename = (attachment?.name || `${task.brief.title}-V${task.versions.indexOf(version) + 1}.md`)
+      .replace(/[\\/\x00-\x1f:*?"<>|]/g, '_')
+    const result = await dialog.showSaveDialog(getMainWindow(), { defaultPath: filename })
+    if (result.canceled || !result.filePath) return { saved: false }
+    try {
+      fs.writeFileSync(result.filePath, bytes, { mode: 0o600, flag: fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW })
+    } catch { throw new Error('LOCAL_DELIVERY_EXPORT_FAILED') }
+    return { saved: true }
+  })
+}
+
+module.exports = { registerDeliveryIpc }

desktop/src/shell/main-ipc.cjs

@@ -1,6 +1,8 @@
 const { ADOPTION_ACTION_STATUSES } = require('../collaboration/outcome-records.cjs')
 const { statusForHumanGateOption } = require('../gates/human-gate-coordinator.cjs')
 const { ATTACHMENT_FILE_EXTENSIONS } = require('../attachments/attachment-records.cjs')
+const { registerDeliveryIpc } = require('./delivery-ipc.cjs')
+const { loadedWorkPreferences, parseWorkPreferences } = require('../workspace/work-preferences.cjs')
 
 const LOCAL_GROUP_IDENTIFIER = /^[^\u0000-\u001f\u007f]{1,100}$/u
 const LOCAL_RUN_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/
@@ -25,6 +27,32 @@ function isPlainObject(value) {
   return prototype === Object.prototype || prototype === null
 }
 
+function normalizeWorkspaceProtocol(input) {
+  if (!isPlainObject(input)) return input
+  const selected = []
+  if (Object.hasOwn(input, 'protocol')) {
+    if (!['legacy', 'v4'].includes(input.protocol)) {
+      throw new Error('LOCAL_MESSAGE_PROTOCOL_INVALID')
+    }
+    selected.push(input.protocol)
+  }
+  for (const key of ['harnessVersion', 'collaborationVersion']) {
+    if (!Object.hasOwn(input, key)) continue
+    if (![3, 4].includes(input[key])) throw new Error('LOCAL_MESSAGE_PROTOCOL_INVALID')
+    selected.push(input[key] === 4 ? 'v4' : 'legacy')
+  }
+  if (Object.hasOwn(input, 'v4')) {
+    if (typeof input.v4 !== 'boolean') throw new Error('LOCAL_MESSAGE_PROTOCOL_INVALID')
+    selected.push(input.v4 ? 'v4' : 'legacy')
+  }
+  if (new Set(selected).size > 1) throw new Error('LOCAL_MESSAGE_PROTOCOL_INVALID')
+  const normalized = { ...input, protocol: selected[0] || 'legacy' }
+  delete normalized.harnessVersion
+  delete normalized.collaborationVersion
+  delete normalized.v4
+  return normalized
+}
+
 function boundedIds(value, pattern) {
   return Array.isArray(value) && value.length <= 64
     && new Set(value).size === value.length
@@ -137,6 +165,7 @@ function sanitizeCloudAgentSnapshot(snapshot) {
 }
 
 function registerDesktopIpc(options) {
+  registerDeliveryIpc(options)
   const {
     app,
     attachmentIdsFromSnapshot,
@@ -146,11 +175,13 @@ function registerDesktopIpc(options) {
     getAttachmentStore,
     getAgentConnectors,
     getCloudAgentRuntime,
+    getCloudAgentBridges,
     getKnowledgeConnectors,
     getMainWindow,
     getOutcomeStore,
     getSkillTrustStore,
     getWorkspace,
+    getWorkBuddySettings,
     installer,
     isShutdownStarted,
     knowledgeBaseStore,
@@ -158,8 +189,6 @@ function registerDesktopIpc(options) {
     loadKnowledgeBaseSources,
     localAgentCatalog,
     openExternalUrl,
-    providerStore,
-    providerAgentKind,
     refreshLocalAgentState,
     registerTrustedHandle,
     skillCatalog,
@@ -220,11 +249,12 @@ function registerDesktopIpc(options) {
   registerTrustedHandle('local-workspace:send', async (input) => {
     const workspace = getWorkspace()
     if (!workspace) throw new Error('LOCAL_WORKSPACE_UNAVAILABLE')
-    if ((!Array.isArray(input?.targetKinds) || !input.targetKinds.length)
-        && input?.routingMode !== 'automatic') {
+    const normalizedInput = normalizeWorkspaceProtocol(input)
+    if ((!Array.isArray(normalizedInput?.targetKinds) || !normalizedInput.targetKinds.length)
+        && normalizedInput?.routingMode !== 'automatic') {
       throw new Error('LOCAL_MESSAGE_TARGET_REQUIRED')
     }
-    return workspace.sendMessage(input)
+    return workspace.sendMessage(normalizedInput)
   })
   registerTrustedHandle('local-workspace:stop', (groupId, runId) => {
     const workspace = getWorkspace()
@@ -335,6 +365,44 @@ function registerDesktopIpc(options) {
     if (!LOCAL_RUN_IDENTIFIER.test(normalizedRunId)) throw new Error('CLOUD_AGENT_RUN_INVALID')
     return runtime.cancel(normalizedRunId)
   })
+  registerTrustedHandle('local-cloud-agent-bridge:list', (...args) => {
+    if (args.length) throw new Error('CLOUD_AGENT_BRIDGE_REQUEST_INVALID')
+    const bridges = getCloudAgentBridges?.()
+    if (!bridges) throw new Error('CLOUD_AGENT_BRIDGE_RUNTIME_UNAVAILABLE')
+    return bridges.list()
+  })
+  registerTrustedHandle('local-cloud-agent-bridge:connect', async (...args) => {
+    if (args.length !== 1 || !args[0] || typeof args[0] !== 'object'
+        || Array.isArray(args[0])
+        || Reflect.ownKeys(args[0]).some(key => !['address', 'label'].includes(key))
+        || typeof args[0].address !== 'string'
+        || (args[0].label !== undefined && typeof args[0].label !== 'string')) {
+      throw new Error('CLOUD_AGENT_BRIDGE_REQUEST_INVALID')
+    }
+    const bridges = getCloudAgentBridges?.()
+    if (!bridges) throw new Error('CLOUD_AGENT_BRIDGE_RUNTIME_UNAVAILABLE')
+    const result = await bridges.connect(args[0])
+    await refreshLocalAgentState()
+    return result
+  })
+  registerTrustedHandle('local-cloud-agent-bridge:refresh', async (...args) => {
+    if (args.length) throw new Error('CLOUD_AGENT_BRIDGE_REQUEST_INVALID')
+    const bridges = getCloudAgentBridges?.()
+    if (!bridges) throw new Error('CLOUD_AGENT_BRIDGE_RUNTIME_UNAVAILABLE')
+    const result = await bridges.refresh()
+    await refreshLocalAgentState()
+    return result
+  })
+  registerTrustedHandle('local-cloud-agent-bridge:delete', async (...args) => {
+    if (args.length !== 1 || typeof args[0] !== 'string') {
+      throw new Error('CLOUD_AGENT_BRIDGE_REQUEST_INVALID')
+    }
+    const bridges = getCloudAgentBridges?.()
+    if (!bridges) throw new Error('CLOUD_AGENT_BRIDGE_RUNTIME_UNAVAILABLE')
+    const result = bridges.remove(args[0])
+    await refreshLocalAgentState()
+    return result
+  })
   registerTrustedHandle('local-outcome:record-adoption', (...args) => {
     if (args.length !== 1) throw new Error('LOCAL_ADOPTION_REQUEST_INVALID')
     const outcomeStore = getOutcomeStore?.()
@@ -353,11 +421,61 @@ function registerDesktopIpc(options) {
   })
   registerTrustedHandle('local-workspace:default-directory', () => app.getPath('documents'))
   registerTrustedHandle('local-agent-installer:catalog', async () => localAgentCatalog())
+  registerTrustedHandle('local-workbuddy:settings', () => getWorkBuddySettings())
+  registerTrustedHandle('local-work-preferences:get', () => loadedWorkPreferences(getWorkspace()?.state.workPreferences))
+  registerTrustedHandle('local-work-preferences:save', (...args) => {
+    if (args.length !== 1) throw new Error('LOCAL_WORK_PREFERENCES_INVALID')
+    const value = parseWorkPreferences(args[0])
+    const workspace = getWorkspace()
+    if (!workspace) throw new Error('LOCAL_WORKSPACE_UNAVAILABLE')
+    if (workspace.activeRuns.size || workspace.preparingRuns?.size) throw new Error('LOCAL_WORK_PREFERENCES_BUSY')
+    const previous = workspace.state.workPreferences
+    workspace.state.workPreferences = value
+    try { workspace.save() } catch (error) {
+      if (previous) workspace.state.workPreferences = previous
+      else delete workspace.state.workPreferences
+      throw error
+    }
+    workspace.emitChanged()
+    return value
+  })
+  registerTrustedHandle('local-workbuddy:set-model', async (...args) => {
+    if (args.length !== 1 || typeof args[0] !== 'string' || args[0].length > 120) {
+      throw new Error('LOCAL_WORKBUDDY_MODEL_UNAVAILABLE')
+    }
+    const workspace = getWorkspace()
+    if (!workspace) throw new Error('LOCAL_WORKSPACE_UNAVAILABLE')
+    const modelId = args[0]
+    const settings = await getWorkBuddySettings()
+    if (modelId && !settings.models.some(model => model.id === modelId)) {
+      throw new Error('LOCAL_WORKBUDDY_MODEL_UNAVAILABLE')
+    }
+    if (workspace.activeRuns.size || workspace.preparingRuns?.size) {
+      throw new Error('LOCAL_WORKBUDDY_BUSY')
+    }
+    const before = workspace.state.agentPreferences.workbuddy
+    const runtime = workspace.state.agentRuntime.workbuddy
+    workspace.state.agentPreferences.workbuddy = { ...before, modelId }
+    delete workspace.state.agentRuntime.workbuddy
+    try { workspace.save() } catch (error) {
+      if (before) workspace.state.agentPreferences.workbuddy = before
+      else delete workspace.state.agentPreferences.workbuddy
+      if (runtime) workspace.state.agentRuntime.workbuddy = runtime
+      throw error
+    }
+    await refreshLocalAgentState()
+    return { ...settings, modelId }
+  })
   registerTrustedHandle('local-agent-installer:skills', async (kind) => {
     const selectedKind = String(kind || '')
     if (customAgentStore.has(selectedKind)) {
       return { supported: false, skills: [], total: 0, limit: 0 }
     }
+    const cloudSkills = getCloudAgentBridges?.()?.skillsForInstance?.(selectedKind)
+    if (cloudSkills !== null && cloudSkills !== undefined) {
+      const skills = cloudSkills.map(skill => ({ ...skill, targetKind: selectedKind }))
+      return { supported: true, skills, total: skills.length, limit: 64 }
+    }
     return installer.skills(selectedKind)
   })
   registerTrustedHandle('local-skill-trust:list', () => {
@@ -589,39 +707,6 @@ function registerDesktopIpc(options) {
   registerTrustedHandle('local-attachments:preview', id => attachments.preview(String(id || '')))
   registerTrustedHandle('local-attachments:open', id => attachments.open(String(id || '')))
   registerTrustedHandle('local-attachments:discard', ids => attachments.discardUnreferenced(ids))
-  registerTrustedHandle('local-agent-provider:status', kind => (
-    providerStore.status(providerAgentKind(kind))
-  ))
-  registerTrustedHandle('local-agent-provider:probe', kind => (
-    providerStore.status(providerAgentKind(kind), { probeEncryption: true })
-  ))
-  registerTrustedHandle('local-agent-provider:save', async (kind, input) => {
-    const selectedKind = providerAgentKind(kind)
-    const result = providerStore.save(selectedKind, {
-      apiKey: input?.apiKey,
-      provider: input?.provider,
-      baseUrl: input?.baseUrl,
-      model: input?.model,
-      preset: input?.preset,
-    })
-    getWorkspace()?.markRuntimeCredential(selectedKind, 'unknown')
-    await refreshLocalAgentState()
-    return result
-  })
-  registerTrustedHandle('local-agent-provider:activate', async (kind, preset) => {
-    const selectedKind = providerAgentKind(kind)
-    const result = providerStore.activate(selectedKind, preset)
-    getWorkspace()?.markRuntimeCredential(selectedKind, 'unknown')
-    await refreshLocalAgentState()
-    return result
-  })
-  registerTrustedHandle('local-agent-provider:delete', async (kind, preset) => {
-    const selectedKind = providerAgentKind(kind)
-    const result = providerStore.delete(selectedKind, preset)
-    getWorkspace()?.markRuntimeCredential(selectedKind, 'unknown')
-    await refreshLocalAgentState()
-    return result
-  })
   registerTrustedHandle('local-knowledge-connector:list', (...args) => {
     if (args.length) throw new Error('LOCAL_KNOWLEDGE_CONNECTOR_REQUEST_INVALID')
     const connectors = getKnowledgeConnectors?.()

desktop/src/workspace/delivery-tasks.cjs

@@ -0,0 +1,257 @@
+const { randomUUID } = require('node:crypto')
+const { z } = require('zod')
+const { normalizeAttachmentMetadata } = require('./local-workspace-message-records.cjs')
+
+const id = z.string().min(1).max(120).regex(/^[A-Za-z0-9._:-]+$/)
+const text = (max) => z.string().trim().min(1).max(max)
+const briefSchema = z.strictObject({
+  title: text(120), goal: text(4000), output: text(2000),
+  outputKind: z.enum(['text', 'files']),
+  criteria: z.array(text(300)).min(1).max(20),
+  language: z.enum(['zh', 'en']),
+})
+const attachmentSchema = z.strictObject({
+  id, name: text(160), mimeType: text(160), size: z.number().int().positive(),
+})
+const sourceSchema = z.strictObject({ name: text(200), kind: text(40), attachmentId: id.optional() })
+const revisionSchema = z.strictObject({ baseVersionId: id, note: text(4000) })
+const attemptSchema = z.strictObject({
+  runId: id, messageId: id, status: text(40), createdAt: text(80),
+  input: z.string().max(200000), sources: z.array(sourceSchema).max(41),
+  revision: revisionSchema.nullable(),
+})
+const versionSchema = z.strictObject({
+  id, runId: id, createdAt: text(80),
+  responses: z.array(z.strictObject({ messageId: id, agentKind: text(40), content: z.string().max(1000000) })).max(32),
+  attachments: z.array(attachmentSchema).max(128),
+  checks: z.array(z.enum(['pending', 'met', 'unmet', 'unknown'])).max(20),
+  notes: z.string().max(4000), acceptedAt: z.string().max(80),
+})
+const taskSchema = z.strictObject({
+  id, groupId: text(100), brief: briefSchema, createdAt: text(80),
+  attempts: z.array(attemptSchema).max(200), versions: z.array(versionSchema).max(200),
+  revision: revisionSchema.nullable(),
+})
+
+function parse(schema, input) {
+  const result = schema.safeParse(input)
+  if (!result.success) throw new Error('LOCAL_DELIVERY_INVALID')
+  return result.data
+}
+
+function parseDeliveryTasks(value = []) {
+  return parse(z.array(taskSchema).max(1000), value)
+}
+
+class DeliveryTasks {
+  constructor(workspace) {
+    this.workspace = workspace
+    this.pending = new Map()
+  }
+
+  get tasks() { return this.workspace.state.deliveryTasks || [] }
+
+  task(taskId) {
+    parse(id, taskId)
+    const task = this.tasks.find(item => item.id === taskId)
+    if (!task || !this.workspace.state.groups.some(group => group.id === task.groupId)) {
+      throw new Error('LOCAL_DELIVERY_NOT_FOUND')
+    }
+    return task
+  }
+
+  version(task, versionId) {
+    parse(id, versionId)
+    const version = task.versions.find(item => item.id === versionId)
+    if (!version) throw new Error('LOCAL_DELIVERY_NOT_FOUND')
+    return version
+  }
+
+  commit(change) {
+    const previous = structuredClone(this.tasks)
+    try {
+      this.workspace.state.deliveryTasks ||= []
+      const result = change()
+      parseDeliveryTasks(this.tasks)
+      this.workspace.save()
+      return result
+    } catch (error) {
+      this.workspace.state.deliveryTasks = previous
+      throw error
+    }
+  }
+
+  idle(task) {
+    if (this.workspace.isGroupBusy(task.groupId) || this.pending.has(task.groupId)) {
+      throw new Error('LOCAL_GROUP_RUNNING')
+    }
+  }
+
+  save(input) {
+    const request = parse(z.strictObject({ groupId: text(100), taskId: id.optional(), brief: briefSchema }), input)
+    this.workspace.getGroup(request.groupId)
+    if (this.workspace.isGroupBusy(request.groupId)) throw new Error('LOCAL_GROUP_RUNNING')
+    const existing = request.taskId ? this.task(request.taskId) : null
+    if (existing && (existing.groupId !== request.groupId || existing.attempts.length)) {
+      throw new Error('LOCAL_DELIVERY_LOCKED')
+    }
+    return this.commit(() => {
+      if (existing) { existing.brief = request.brief; return existing.id }
+      const task = {
+        id: `delivery-${randomUUID()}`, groupId: request.groupId, brief: request.brief,
+        createdAt: this.workspace.now(), attempts: [], versions: [], revision: null,
+      }
+      this.tasks.push(task)
+      return task.id
+    })
+  }
+
+  prepare(input) {
+    const task = this.task(input.deliveryTaskId)
+    if (task.groupId !== input.groupId || input.regenerateMessageId || input.threadRootId) {
+      throw new Error('LOCAL_DELIVERY_INVALID')
+    }
+    this.idle(task)
+    if (task.versions.length && !task.revision) throw new Error('LOCAL_DELIVERY_REVISION_REQUIRED')
+    const brief = task.brief
+    const base = task.revision ? this.version(task, task.revision.baseVersionId) : null
+    if (task.attempts.length >= 200) throw new Error('LOCAL_DELIVERY_INPUT_LIMIT')
+    if (input.attachments != null && !Array.isArray(input.attachments)) throw new Error('LOCAL_DELIVERY_INVALID')
+    const attachments = [...new Map([...(base?.attachments || []), ...(input.attachments || [])]
+      .map(item => [item.id, item])).values()]
+    if (attachments.length > 32) throw new Error('LOCAL_ATTACHMENT_COUNT_LIMIT')
+    const prompt = [
+      brief.language === 'zh' ? '工作交付要求（请用中文回答）' : 'Work delivery requirements (respond in English)',
+      JSON.stringify(brief),
+      'Produce the requested deliverable. Identify source materials for key claims, conflicting or missing information, and unresolved issues. Never invent missing data or claim that a file exists without creating it. Human acceptance is separate from your self-review.',
+      ...(base ? ['Previous version:', ...base.responses.map(item => item.content), `Revision request: ${task.revision.note}`] : []),
+      `Additional instructions: ${String(input.text || '')}`,
+    ].join('\n\n')
+    if (prompt.length > 200000) throw new Error('LOCAL_DELIVERY_INPUT_LIMIT')
+    this.pending.set(task.groupId, { taskId: task.id, input: String(input.text || '') })
+    const { deliveryTaskId: _id, ...rest } = input
+    return { ...rest, text: prompt, attachments }
+  }
+
+  bind(groupId, controller, messageId) {
+    const pending = this.pending.get(groupId)
+    if (!pending) return
+    const task = this.task(pending.taskId)
+    const message = this.workspace.state.messages.find(item => item.id === messageId)
+    if (!message || message.groupId !== groupId) throw new Error('LOCAL_DELIVERY_INVALID')
+    this.commit(() => task.attempts.push({
+      runId: controller.runId, messageId, status: 'running', createdAt: this.workspace.now(),
+      input: pending.input, revision: task.revision ? { ...task.revision } : null,
+      sources: [
+        { name: this.workspace.getGroup(groupId).name || 'Conversation', kind: 'conversation' },
+        ...(message.attachments || []).map(item => ({ name: item.name, kind: 'attachment', attachmentId: item.id })),
+        ...(message.knowledgeBaseHints || []).map(item => ({ name: item.name, kind: item.kind })),
+        ...(message.skillHints || []).map(item => ({ name: item.name, kind: 'skill' })),
+      ],
+    }))
+  }
+
+  complete(runId, status, committedMessageIds = []) {
+    const task = this.tasks.find(item => item.attempts.some(attempt => attempt.runId === runId))
+    if (!task) return
+    const attempt = task.attempts.find(item => item.runId === runId)
+    if (!['running', 'waiting', 'preparing'].includes(attempt.status)) return
+    const messages = this.workspace.state.messages
+    const rootIndex = messages.findIndex(item => item.id === attempt.messageId)
+    const nextUserIndex = messages.findIndex((item, index) => index > rootIndex && item.groupId === task.groupId && item.role === 'user')
+    const related = messages.filter((message, index) => {
+      if (message.role !== 'agent' || message.groupId !== task.groupId) return false
+      if (committedMessageIds.includes(message.id)) return true
+      if (message.trace?.runId && message.trace.runId !== runId) return false
+      return message.trace?.runId === runId
+        || message.threadRootId === attempt.messageId
+        || (!message.threadRootId && rootIndex >= 0 && index > rootIndex && (nextUserIndex < 0 || index < nextUserIndex))
+    })
+    const outputs = related.filter(message => {
+      const phase = message.trace?.phase || message.trace?.context?.phase
+      return committedMessageIds.includes(message.id)
+        || !['proposal', 'discussion', 'challenge', 'coordination', 'work', 'verification'].includes(phase)
+    }).filter(message => message.content?.trim())
+    const attachments = [...new Map(related.flatMap(item => item.attachments || [])
+      .map(normalizeAttachmentMetadata).filter(Boolean).map(item => [item.id, item])).values()]
+    this.commit(() => {
+      attempt.status = status
+      if (!outputs.length && !attachments.length) return
+      task.versions.push({
+        id: `version-${randomUUID()}`, runId, createdAt: this.workspace.now(),
+        responses: outputs.map(item => ({ messageId: item.id, agentKind: item.agentKind, content: item.content || '' })),
+        attachments, checks: task.brief.criteria.map(() => 'pending'), notes: '', acceptedAt: '',
+      })
+      task.revision = null
+    })
+  }
+
+  recover() {
+    for (const task of this.tasks) {
+      for (const attempt of task.attempts) {
+        if (!['running', 'waiting', 'preparing'].includes(attempt.status)) continue
+        const record = this.workspace.runLedger?.list?.().find(item => item.runId === attempt.runId)
+        if (this.workspace.activeRuns.has(task.groupId)
+            || (record?.status === 'waiting' && this.workspace.canResumeHumanGateRecord(record))) continue
+        const status = record && !['running', 'waiting', 'preparing', 'queued'].includes(record.status)
+          ? record.status : 'interrupted'
+        this.complete(attempt.runId, status, [
+          ...(record?.orchestration?.commitState?.messageIds || []),
+          record?.orchestration?.candidateCommit?.messageId,
+        ].filter(Boolean))
+      }
+    }
+  }
+
+  review(input) {
+    const request = parse(z.strictObject({
+      taskId: id, versionId: id, checks: z.array(z.enum(['pending', 'met', 'unmet', 'unknown'])).max(20),
+      notes: z.string().max(4000), accept: z.boolean(),
+    }), input)
+    const task = this.task(request.taskId)
+    this.idle(task)
+    const version = this.version(task, request.versionId)
+    if (version.acceptedAt || request.checks.length !== task.brief.criteria.length) throw new Error('LOCAL_DELIVERY_LOCKED')
+    if (request.accept && (request.checks.some(check => check !== 'met')
+        || (task.brief.outputKind === 'files' && !version.attachments.length))) {
+      throw new Error('LOCAL_DELIVERY_NOT_READY')
+    }
+    this.commit(() => {
+      version.checks = request.checks
+      version.notes = request.notes.trim()
+      if (request.accept) version.acceptedAt = this.workspace.now()
+    })
+  }
+
+  revise(input) {
+    const request = parse(z.strictObject({ taskId: id, baseVersionId: id, note: text(4000) }), input)
+    const task = this.task(request.taskId)
+    this.idle(task)
+    this.version(task, request.baseVersionId)
+    this.commit(() => { task.revision = { baseVersionId: request.baseVersionId, note: request.note } })
+  }
+
+  markdown(taskId, versionId) {
+    const task = this.task(taskId)
+    const version = this.version(task, versionId)
+    const attempt = task.attempts.find(item => item.runId === version.runId)
+    const zh = task.brief.language === 'zh'
+    const checks = zh
+      ? { pending: '待检查', met: '符合', unmet: '不符合', unknown: '无法判断' }
+      : { pending: 'Not checked', met: 'Met', unmet: 'Not met', unknown: 'Unknown' }
+    return [
+      `# ${task.brief.title}`, `V${task.versions.indexOf(version) + 1} · ${version.createdAt}`,
+      `${zh ? '采用时间' : 'Accepted at'}: ${version.acceptedAt || (zh ? '未采用' : 'Not accepted')}`,
+      ...version.responses.map(item => `## ${item.agentKind}\n\n${item.content}`),
+      `## ${zh ? '输入材料（不代表逐条引用已核实）' : 'Input materials (not verified claim-level citations)'}`,
+      ...attempt.sources.map(item => `- ${item.name} (${item.kind})`),
+      `## ${zh ? '人工验收' : 'Human review'}`,
+      ...task.brief.criteria.map((criterion, index) => `- [${checks[version.checks[index]]}] ${criterion}`),
+      `## ${zh ? '备注与未决事项' : 'Notes and unresolved issues'}`, version.notes || '—',
+      `## ${zh ? '附件（需单独导出）' : 'Attachments (export separately)'}`,
+      ...version.attachments.map(item => `- ${item.name}`),
+    ].join('\n\n') + '\n'
+  }
+}
+
+module.exports = { DeliveryTasks, parseDeliveryTasks }

desktop/src/workspace/invocation-budget.cjs

@@ -0,0 +1,37 @@
+const { outboundWirePayloadBytes } = require('../collaboration/outbound-payload.cjs')
+
+// What the Agent was sent: wire bytes are reported, tokens are an estimate.
+function recordOutboundUsage(budget, outbound) {
+  if (!budget) return
+  const bytes = outboundWirePayloadBytes(outbound)
+  // A payload that was not built by the transport has no recorded wire size;
+  // skipping it is better than failing the Agent's turn over bookkeeping.
+  if (!bytes) return
+  budget.addUsageBatch([
+    { dimension: 'outboundBytes', amount: bytes.length, source: 'reported' },
+    { dimension: 'inputTokens', amount: Math.ceil(bytes.length / 4), source: 'estimated' },
+  ])
+}
+
+// What the Agent produced: prefer the usage the CLI reported over an estimate.
+function recordReplyUsage(budget, { usage, replyText, toolCallCount }) {
+  if (!budget) return
+  const reportedOutputTokens = Number(usage?.outputTokens)
+  const hasReportedOutputTokens = Number.isSafeInteger(reportedOutputTokens)
+    && reportedOutputTokens >= 0
+  const reportedCostMicros = Number(usage?.costMicros)
+  budget.addUsageBatch([
+    {
+      dimension: 'outputTokens',
+      amount: hasReportedOutputTokens ? reportedOutputTokens : Math.ceil(replyText.length / 4),
+      source: hasReportedOutputTokens ? 'reported' : 'estimated',
+    },
+    { dimension: 'toolCalls', amount: toolCallCount, source: 'estimated' },
+    ...(Number.isSafeInteger(reportedCostMicros) && reportedCostMicros >= 0
+      ? [{ dimension: 'costMicros', amount: reportedCostMicros, source: 'reported' }]
+      : []),
+    { dimension: 'elapsedMs', value: budget.elapsedValue(), source: 'reported' },
+  ])
+}
+
+module.exports = { recordOutboundUsage, recordReplyUsage }

desktop/src/workspace/invocation-failure.cjs

@@ -0,0 +1,72 @@
+const { agentStoppedError } = require('./local-workspace-inputs.cjs')
+
+// Marks how far an invocation got before it failed, so the run can decide
+// whether the operation may be retried safely.
+function attachInvocationFailure(error, input) {
+  if (!error || (typeof error !== 'object' && typeof error !== 'function')) return error
+  const existing = error.invocationFailure && typeof error.invocationFailure === 'object'
+    ? error.invocationFailure
+    : {}
+  Object.defineProperty(error, 'invocationFailure', {
+    value: Object.freeze({
+      outcomeCertainty: existing.outcomeCertainty || input.outcomeCertainty,
+      sideEffectsPossible: existing.sideEffectsPossible === true || input.sideEffectsPossible === true,
+      operationId: existing.operationId || input.operationId,
+      idempotencyMode: existing.idempotencyMode || input.idempotencyMode,
+    }),
+    enumerable: false,
+    configurable: true,
+  })
+  return error
+}
+
+// Hidden properties on an error that downstream code reads but that must not
+// leak into serialised error messages.
+function attachErrorMetadata(error, metadata) {
+  if (!error || (typeof error !== 'object' && typeof error !== 'function')) return error
+  for (const [name, value] of Object.entries(metadata)) {
+    if (!value) continue
+    Object.defineProperty(error, name, { value, enumerable: false, configurable: true })
+  }
+  return error
+}
+
+// Why an invocation ended and how to report it:
+//  - the parent run was stopped, timed out or is shutting down;
+//  - the watchdog cut a silent Agent off;
+//  - the Agent was cancelled on its own (e.g. a superseded attempt);
+//  - or it simply failed with `caughtError`.
+// `settleOutstanding` tells the caller to wait briefly for capture and run
+// promises that may still be winding down.
+function resolveInvocationStop({
+  caughtError, signal, parentAbortObserved, activeRun, agentController, watchdog,
+}) {
+  const parentTimedOut = Boolean(signal?.aborted && activeRun?.stopReason === 'timeout')
+  const parentStopped = Boolean(signal?.aborted || parentAbortObserved)
+  const parentInterrupted = parentStopped && activeRun?.stopReason === 'shutdown'
+  const agentCancelled = agentController.signal.aborted && !parentStopped && !watchdog.timedOut
+  let error = caughtError
+  let status = 'failed'
+  if (parentTimedOut) {
+    error = new Error('LOCAL_AGENT_TIMEOUT')
+    status = 'timeout'
+  } else if (parentStopped) {
+    error = caughtError?.message === 'LOCAL_AGENT_EXECUTION_STOPPED'
+      ? caughtError
+      : agentStoppedError()
+    status = parentInterrupted ? 'interrupted' : 'stopped'
+  } else if (watchdog.timedOut) {
+    error = watchdog.error || new Error('LOCAL_AGENT_TIMEOUT')
+    status = 'timeout'
+  } else if (agentCancelled) {
+    error = agentStoppedError()
+    status = 'stopped'
+  }
+  return {
+    error,
+    status,
+    settleOutstanding: parentStopped || watchdog.timedOut || agentCancelled,
+  }
+}
+
+module.exports = { attachErrorMetadata, attachInvocationFailure, resolveInvocationStop }

desktop/src/workspace/invocation-outputs.cjs

@@ -0,0 +1,113 @@
+const {
+  MAX_MESSAGE_ATTACHMENTS,
+  abortableOperation,
+  normalizeAttachmentMetadata,
+} = require('./local-workspace-inputs.cjs')
+
+// Absolute paths an Agent mentions in its reply. Quoted, backticked or
+// Markdown-linked paths may contain spaces; bare paths end at whitespace.
+function extractReportedOutputPaths(text) {
+  if (typeof text !== 'string') return []
+  const root = '\\/(?:Users|home|tmp|private\\/tmp|Volumes)\\/'
+  const delimited = [...text.matchAll(new RegExp(`[\`"'(<](${root}[^\`"'<>\\n)]+)[\`"')>]`, 'g'))]
+    .map(match => match[1])
+  const bare = (text.match(new RegExp(`${root}[^\\s"'<>\`\\]\\[)]+`, 'g')) || [])
+    .filter(value => !delimited.some(full => full !== value && full.startsWith(value)))
+  return [...new Set([...delimited, ...bare].map(value => value.trim().replace(/[.,;:!?]+$/, '')))]
+}
+
+// Files a writable Agent turn leaves behind: a snapshot of the workspace is
+// taken before the turn and compared afterwards to import generated media and
+// to describe produced artifacts. Capturing is best effort; only a stop
+// request is allowed to interrupt it.
+class InvocationOutputs {
+  constructor({ enabled, workdir, signal, agentKind, startedAt, deps }) {
+    this.enabled = enabled === true
+    this.workdir = workdir
+    this.signal = signal
+    this.agentKind = agentKind
+    this.startedAt = startedAt
+    this.deps = deps
+    this.baseline = null
+    this.artifactBaseline = null
+    this.capturePromise = null
+    this.artifactCapturePromise = null
+    this.importPromise = null
+    this.outcomePromise = null
+  }
+
+  // Promises that may still be running when the invocation is cut short.
+  pending() {
+    return [
+      this.capturePromise,
+      this.artifactCapturePromise,
+      this.importPromise,
+      this.outcomePromise,
+    ].filter(Boolean)
+  }
+
+  async tolerate(operation) {
+    try {
+      return await abortableOperation(operation, this.signal)
+    } catch (error) {
+      if (this.signal.aborted) throw error
+      return undefined
+    }
+  }
+
+  async begin() {
+    if (!this.enabled) return
+    this.artifactCapturePromise = Promise.resolve().then(
+      () => this.deps.captureArtifactOutputs(this.workdir, { signal: this.signal }),
+    )
+    this.artifactCapturePromise.catch(() => {})
+    try {
+      this.capturePromise = Promise.resolve().then(
+        () => this.deps.captureAgentOutputs(this.workdir, { signal: this.signal }),
+      )
+      this.capturePromise.catch(() => {})
+      this.baseline = await abortableOperation(() => this.capturePromise, this.signal)
+    } catch (error) {
+      if (this.signal.aborted) throw error
+    }
+    this.artifactBaseline = (await this.tolerate(() => this.artifactCapturePromise)) ?? null
+  }
+
+  // Media the Agent produced during this turn, as message attachments.
+  async importMedia(replyText) {
+    if (!this.enabled) return []
+    this.importPromise = Promise.resolve().then(() => this.deps.importAgentOutputs({
+      workdir: this.workdir,
+      baseline: this.baseline,
+      startedAt: this.startedAt,
+      agentKind: this.agentKind,
+      reportedPaths: extractReportedOutputPaths(replyText),
+      signal: this.signal,
+    }))
+    this.importPromise.catch(() => {})
+    const imported = await this.tolerate(() => this.importPromise)
+    return (Array.isArray(imported) ? imported : [])
+      .slice(0, MAX_MESSAGE_ATTACHMENTS)
+      .map(normalizeAttachmentMetadata)
+      .filter(Boolean)
+  }
+
+  // Descriptors of the artifacts the Agent wrote, for the evidence record.
+  async describeOutcomes({ runId, agentRunId }) {
+    if (!this.enabled || !this.artifactBaseline) return []
+    this.outcomePromise = Promise.resolve().then(() => this.deps.captureAgentOutcomeDescriptors({
+      workdir: this.workdir,
+      baseline: this.artifactBaseline,
+      startedAt: this.startedAt,
+      agentKind: this.agentKind,
+      runId,
+      agentRunId,
+      signal: this.signal,
+    }))
+    this.outcomePromise.catch(() => {})
+    const captured = await this.tolerate(() => this.outcomePromise)
+    return Array.isArray(captured) ? captured : []
+  }
+}
+
+module.exports = { InvocationOutputs, extractReportedOutputPaths }

desktop/src/workspace/invocation-prompt.cjs

@@ -0,0 +1,63 @@
+const { stagedAgentInputPrompt } = require('../agents/agent-input-staging.cjs')
+const { directPromptFor } = require('./local-workspace-context.cjs')
+const { cleanText } = require('./local-workspace-inputs.cjs')
+
+const RESPONSE_SCOPE_INSTRUCTION = [
+  'Final response scope:',
+  'Answer only the current user task stated above.',
+  'Use earlier messages only as supporting evidence when they help answer that current task.',
+  'Do not separately mention, summarize, continue, or complete any previous user task.',
+  'Do not append an answer to an older task after the current-task conclusion.',
+].join('\n')
+
+// Builds the prompt one Agent receives for one turn.
+//  - frozen / isolated invocations send exactly the approved prompt.
+//  - direct chats lead with the user's request; a resumed native session
+//    already holds the conversation, a new or rebuilt one gets the history.
+//  - group turns use the V4 prompt when the orchestrator supplied one, else
+//    the workspace prompt for the current mode.
+// Staged attachments and harness recovery instructions are appended to both.
+function assembleInvocationPrompt({
+  group, kind, mode, threadRootId, context, activeRun, isolated, frozen,
+  v4Prompt, promptMode, afterKind, packed, session, stagedInputs, promptFor, agentLabel,
+}) {
+  // Frozen and isolated prompts are fixed text. Staged attachments are the
+  // only thing added to a frozen one, so the Agent can open the user's files.
+  if (isolated || frozen) {
+    return [v4Prompt, stagedAgentInputPrompt(stagedInputs)].filter(Boolean).join('\n\n')
+  }
+  const runtimeInstruction = cleanText(context.runtimeInstruction, 3000)
+  const regenerationInstruction = cleanText(context.regenerationInstruction, 3000)
+  const additions = [
+    stagedAgentInputPrompt(stagedInputs),
+    runtimeInstruction ? `Harness recovery task:\n${runtimeInstruction}` : '',
+    regenerationInstruction ? `Fresh response instruction:\n${regenerationInstruction}` : '',
+  ]
+  if (group.conversationType === 'direct') {
+    return [
+      directPromptFor({
+        group,
+        label: agentLabel(kind),
+        packed,
+        skillHints: context.skillHints || [],
+        knowledgeBaseHints: context.knowledgeBaseHints || [],
+        includeHistory: session.rotated || !session.ref,
+      }),
+      ...additions,
+    ].filter(Boolean).join('\n\n')
+  }
+  return [
+    context.v4 === true && v4Prompt
+      ? v4Prompt
+      : promptFor(
+        group, kind, context.completionPolicy === 'typed' ? 'manual' : mode,
+        threadRootId, context.skillHints || [],
+        context.knowledgeBaseHints || [], afterKind, packed, promptMode,
+        activeRun?.unlimitedRounds === true,
+      ),
+    ...additions,
+    RESPONSE_SCOPE_INSTRUCTION,
+  ].filter(Boolean).join('\n')
+}
+
+module.exports = { assembleInvocationPrompt }

desktop/src/workspace/invocation-session.cjs

@@ -0,0 +1,156 @@
+const { createHash, randomUUID } = require('node:crypto')
+const { canonicalJson } = require('../collaboration/context-pack-records.cjs')
+const { nextSessionMeta, normalizeSessionMeta } = require('../runs/run-harness.cjs')
+
+const MAX_INHERITED_TASK_IDS = 64
+
+function sha256(value) {
+  return createHash('sha256').update(String(value || '')).digest('hex')
+}
+
+function createdSessionProvenance(taskId, stateless = false) {
+  if (stateless) {
+    return {
+      scope: 'none', reuse: false, origin: 'none', originTaskId: null,
+      inheritedTaskIds: [], completeness: 'complete',
+    }
+  }
+  return {
+    scope: 'conversation',
+    reuse: false,
+    origin: 'created',
+    originTaskId: taskId || null,
+    inheritedTaskIds: [],
+    completeness: 'complete',
+  }
+}
+
+function provenanceMeta(provenance) {
+  if (provenance.scope === 'unknown-legacy') {
+    return {
+      sessionScope: 'unknown-legacy',
+      originTaskId: '',
+      inheritedTaskIds: [],
+      provenanceCompleteness: 'unknown-legacy',
+    }
+  }
+  if (provenance.scope === 'none') return {}
+  return {
+    sessionScope: provenance.scope,
+    originTaskId: provenance.originTaskId || '',
+    inheritedTaskIds: provenance.inheritedTaskIds || [],
+    provenanceCompleteness: provenance.completeness,
+  }
+}
+
+function completedSessionMeta(meta, provenance, taskId, usage) {
+  let inheritedTaskIds = [...(provenance.inheritedTaskIds || [])]
+  let completeness = provenance.completeness
+  if (provenance.scope === 'conversation' && taskId
+      && taskId !== provenance.originTaskId && !inheritedTaskIds.includes(taskId)) {
+    inheritedTaskIds.push(taskId)
+    if (inheritedTaskIds.length > MAX_INHERITED_TASK_IDS) {
+      inheritedTaskIds = inheritedTaskIds.slice(-MAX_INHERITED_TASK_IDS)
+      completeness = 'partial'
+    }
+  }
+  return nextSessionMeta(meta, {
+    ...usage,
+    ...provenanceMeta({ ...provenance, inheritedTaskIds, completeness }),
+  })
+}
+
+// Binds a pending permission or connector request to the exact native session
+// it was raised in, so a decision cannot be replayed against another session.
+function connectorSessionBinding(sessionRef, sessionProvenance) {
+  const stableProvenance = {
+    scope: String(sessionProvenance?.scope || 'none'),
+    originTaskId: String(sessionProvenance?.originTaskId || ''),
+    inheritedTaskIds: Array.isArray(sessionProvenance?.inheritedTaskIds)
+      ? [...sessionProvenance.inheritedTaskIds]
+      : [],
+    completeness: String(sessionProvenance?.completeness || 'complete'),
+  }
+  return {
+    sessionRefHash: sha256(sessionRef),
+    sessionProvenanceHash: sha256(canonicalJson(stableProvenance)),
+  }
+}
+
+// The native Agent session one invocation runs in. A conversation owns one
+// native session for its lifetime: it is resumed on every turn and rebuilt
+// only when the Agent reports that the stored session is no longer valid.
+class InvocationSession {
+  // `resolved` is what the workspace stored for this conversation; `deps`
+  // carries the state hooks so this class never touches workspace state itself.
+  constructor({ resolved, group, kind, taskId, deps }) {
+    this.group = group
+    this.kind = kind
+    this.taskId = taskId
+    this.deps = deps
+    this.key = resolved.key
+    this.storedRef = String(resolved.sessionRef || '')
+    this.ref = this.storedRef
+    this.meta = normalizeSessionMeta(resolved.sessionMeta)
+    this.provenance = resolved.provenance
+    this.rotated = resolved.sessionReset === true
+    this.transport = this.ref ? String(this.meta.transport || '') : ''
+  }
+
+  binding() {
+    return connectorSessionBinding(this.ref, this.provenance)
+  }
+
+  // Forget the native session so the next turn starts a fresh one. OpenClaw
+  // addresses its sessions by name, so it gets a new name straight away.
+  discard() {
+    this.meta = {}
+    this.provenance = createdSessionProvenance(this.taskId)
+    this.transport = ''
+    this.rotated = true
+    this.deps.commitSessionState((nextState) => {
+      delete nextState.sessions[this.key]
+      delete nextState.sessionMeta[this.key]
+      if (this.kind === 'openclaw') {
+        const generation = randomUUID().replace(/[^a-zA-Z0-9]/g, '').slice(0, 12) || 'session'
+        this.ref = this.deps.openClawSessionRef(
+          this.group, generation, this.group.conversationType === 'direct' ? '' : this.taskId,
+        )
+        nextState.sessions[this.key] = this.ref
+        nextState.sessionMeta[this.key] = normalizeSessionMeta(provenanceMeta(this.provenance))
+      } else {
+        this.ref = ''
+      }
+    })
+  }
+
+  // The Agent reported (or created) its native session id.
+  adopt(nextRef, metadata = {}) {
+    const transport = ['legacy', 'acp'].includes(metadata?.transport) ? metadata.transport : ''
+    if (transport) this.transport = transport
+    this.ref = String(nextRef || '')
+    this.deps.persistSessionState(this.key, this.ref, normalizeSessionMeta({
+      ...this.meta,
+      ...provenanceMeta(this.provenance),
+      ...(this.transport ? { transport: this.transport } : {}),
+    }))
+  }
+
+  // A turn finished: record what it cost and which message it had seen.
+  complete(resultRef, usage) {
+    this.deps.persistSessionState(
+      this.key,
+      resultRef || this.ref,
+      completedSessionMeta(this.meta, this.provenance, this.taskId, usage),
+    )
+  }
+}
+
+module.exports = {
+  InvocationSession,
+  completedSessionMeta,
+  connectorSessionBinding,
+  createdSessionProvenance,
+  provenanceMeta,
+  sha256,
+}

desktop/src/workspace/local-workspace-agent-catalog.cjs

@@ -1,9 +1,23 @@
 const {
   agentRuntimeCapabilities,
-  isReviewOnlyAgentKind,
 } = require('../agents/agent-runtime-contract.cjs')
 
 const RECENT_VERIFICATION_MS = 24 * 60 * 60 * 1000
+const AUTH_FAILURE_RETRY_MS = 30 * 1000
+// A readiness probe that times out or crashes says nothing about whether the
+// Agent works: it is not a "not signed in" answer. An Agent that was usable
+// stays usable through such results for this long; a definitive answer
+// (signed out, incompatible, a recorded auth failure) applies immediately.
+const INDETERMINATE_PROBE_GRACE_MS = 10 * 60 * 1000
+const INDETERMINATE_PROBE_SOURCES = new Set(['native-runtime-unavailable', 'native-probe-failed'])
+
+function expiredAuthFailure(runtime, now) {
+  if (runtime?.credentialState !== 'missing') return false
+  const checkedAt = Date.parse(String(runtime.checkedAt || ''))
+  const current = Date.parse(String(now || ''))
+  return !Number.isFinite(checkedAt) || (Number.isFinite(current)
+    && (current < checkedAt || current - checkedAt >= AUTH_FAILURE_RETRY_MS))
+}
 
 function agentVersionIdentified(agent) {
   if (agent?.custom === true) return true
@@ -35,37 +49,63 @@ class LocalWorkspaceAgentCatalog {
     this.setDetectedAgents = options.setDetectedAgents
     this.detectAgents = options.detectAgents
     this.credentialState = options.credentialState
-    this.sharedProviderReady = options.sharedProviderReady
     this.attachmentSupport = options.attachmentSupport || (() => ({}))
     this.save = options.save
     this.emitChanged = options.emitChanged
     this.snapshot = options.snapshot
     this.now = options.now
+    this.refreshTask = null
+    this.refreshAgain = false
+    this.indeterminateSince = new Map()
   }
 
   async refresh() {
+    if (this.refreshTask) {
+      this.refreshAgain = true
+      return this.refreshTask
+    }
+    const task = (async () => {
+      let snapshot
+      do {
+        this.refreshAgain = false
+        snapshot = await this.refreshOnce()
+      } while (this.refreshAgain)
+      return snapshot
+    })()
+    const pending = task.finally(() => {
+      if (this.refreshTask === pending) this.refreshTask = null
+    })
+    this.refreshTask = pending
+    return pending
+  }
+
+  async refreshOnce() {
     const runtimeAtRefreshStart = new Map(Object.entries(this.state().agentRuntime))
+    const previousAgents = new Map(this.detectedAgents().map(agent => [agent.kind, agent]))
     const detected = await this.detectAgents()
-    const nativeStates = await Promise.all(detected.map((agent) => {
-      const runtime = runtimeAtRefreshStart.get(agent.kind)
-      const sharedProviderReady = Boolean(this.sharedProviderReady(agent.kind))
-      if (sharedProviderReady && runtime?.credentialState === 'missing') {
-        return { state: 'missing', source: 'runtime-auth-failure' }
+    const nativeStates = await Promise.all(detected.map(async (agent) => {
+      try {
+        return await this.credentialState(agent.kind, agent)
+      } catch {
+        return { state: 'unknown', source: 'native-probe-failed' }
       }
-      if (sharedProviderReady) {
-        return { state: 'ready', source: 'shared-provider' }
-      }
-      return this.credentialState(agent.kind, agent)
     }))
     const state = this.state()
     let recoveredRuntimeCredential = false
     const agents = detected.map((agent, index) => {
       const native = nativeStates[index]
       let runtime = state.agentRuntime[agent.kind]
-      const sharedProviderReady = Boolean(this.sharedProviderReady(agent.kind))
       const nativeState = ['ready', 'missing'].includes(native?.state) ? native.state : 'unknown'
+      const workBuddyUnavailable = ['workbuddy-desktop-locked', 'workbuddy-model-unavailable'].includes(native?.source)
       const authoritativeNativeState = native?.source === 'native-auth-status'
-      const sharedProviderRequired = native?.source === 'shared-provider-required'
+      // Give corrected native credentials a retry after the cooldown, never erase a newer failure.
+      if (expiredAuthFailure(runtime, this.now())
+          && !(authoritativeNativeState && nativeState === 'ready')
+          && runtime === runtimeAtRefreshStart.get(agent.kind)) {
+        delete state.agentRuntime[agent.kind]
+        runtime = undefined
+        recoveredRuntimeCredential = true
+      }
       // A probe that started before a newer runtime failure cannot clear that failure.
       if (authoritativeNativeState && nativeState === 'ready'
           && ['missing', 'unknown'].includes(runtime?.credentialState)
@@ -85,28 +125,39 @@ class LocalWorkspaceAgentCatalog {
       const nativeReadySource = nativeState === 'ready'
         ? (native.source || 'native-credential')
         : ''
+      const retained = this.retainedAvailability({
+        agent, previous: previousAgents.get(agent.kind), native, runtimeMissing,
+      })
       let credentialState = 'unknown'
-      if (runtimeMissing || sharedProviderRequired || nativeState === 'missing') {
+      if (runtimeMissing || nativeState === 'missing') {
         credentialState = 'missing'
       }
-      if (!runtimeMissing && sharedProviderReady) credentialState = 'ready'
-      else if (!runtimeMissing && nativeState === 'ready') credentialState = 'ready'
+      if (!runtimeMissing && nativeState === 'ready') credentialState = 'ready'
       else if (!runtimeMissing && verifiedReady && nativeState !== 'missing') credentialState = 'ready'
+      if (retained && retained.credentialState === 'ready') credentialState = 'ready'
       const installed = true
       const versionIdentified = agentVersionIdentified(agent)
       const compatible = agentCompatible(agent)
-      const configured = sharedProviderReady
+      const nativeConfigurationUnknown = !runtimeMissing
+        && !workBuddyUnavailable
+        && nativeState === 'unknown'
+        && native?.source !== 'native-runtime-unavailable'
+        && native?.source !== 'native-probe-failed'
+      const configured = retained !== null
         || nativeState === 'ready'
         || native?.source === 'native-auth-status'
         || native?.source === 'native-runtime-unavailable'
         || verifiedReady
         || runtimeMissing
-      const authenticated = !runtimeMissing && nativeState !== 'missing' && (
-        sharedProviderReady || nativeState === 'ready' || verifiedReady
-      )
-      const runtimePrerequisitesReady = native?.source !== 'native-runtime-unavailable'
+        || nativeConfigurationUnknown
+      const authenticated = retained !== null || (!runtimeMissing && nativeState !== 'missing' && (
+        nativeState === 'ready' || verifiedReady || nativeConfigurationUnknown
+      ))
+      const runtimePrerequisitesReady = retained !== null
+        || (native?.source !== 'native-runtime-unavailable'
+          && (native?.source !== 'native-probe-failed' || recentlyVerified(runtime, this.now())))
       const invocable = installed && versionIdentified && compatible && configured
-        && authenticated && runtimePrerequisitesReady
+        && authenticated && runtimePrerequisitesReady && !workBuddyUnavailable
       const verifiedRecently = (authoritativeNativeState && nativeState === 'ready')
         || recentlyVerified(runtime, this.now())
       const available = invocable
@@ -118,10 +169,14 @@ class LocalWorkspaceAgentCatalog {
       let availabilitySource = 'unverified'
       if (!compatible) availabilitySource = 'incompatible'
       else if (runtimeMissing) availabilitySource = 'runtime-auth-failure'
-      else if (sharedProviderReady) availabilitySource = nativeReadySource || 'shared-provider'
       else if (nativeState === 'missing') availabilitySource = native.source || 'none'
+      else if (native?.source === 'native-probe-failed') availabilitySource = 'native-probe-failed'
+      else if (native?.source === 'native-runtime-unavailable') availabilitySource = 'native-runtime-unavailable'
       else if (nativeReadySource) availabilitySource = nativeReadySource
       else if (verifiedReady) availabilitySource = 'verified-run'
+      else if (nativeConfigurationUnknown) availabilitySource = 'local-cli'
+      if (retained) availabilitySource = retained.availabilitySource
+      if (workBuddyUnavailable) availabilitySource = native.source
       return {
         ...agent,
         installed,
@@ -137,9 +192,7 @@ class LocalWorkspaceAgentCatalog {
         task: capabilities.task,
         resumable: capabilities.resumable,
         capabilities,
-        showInSidebar: capabilities.task === 'general'
-          && available
-          && (typeof preferred === 'boolean' ? preferred : true),
+        showInSidebar: typeof preferred === 'boolean' ? preferred : true,
       }
     })
     this.setDetectedAgents(agents)
@@ -148,14 +201,33 @@ class LocalWorkspaceAgentCatalog {
     return this.snapshot()
   }
 
+  // The state an Agent keeps while a readiness probe is inconclusive, or null
+  // when the probe result must be taken at face value.
+  retainedAvailability({ agent, previous, native, runtimeMissing }) {
+    if (!INDETERMINATE_PROBE_SOURCES.has(native?.source)) {
+      this.indeterminateSince.delete(agent.kind)
+      return null
+    }
+    const nowMs = Date.parse(String(this.now()))
+    if (!this.indeterminateSince.has(agent.kind) && Number.isFinite(nowMs)) {
+      this.indeterminateSince.set(agent.kind, nowMs)
+    }
+    const since = this.indeterminateSince.get(agent.kind)
+    if (previous?.available !== true || runtimeMissing || !Number.isFinite(nowMs)
+        || !Number.isFinite(since) || nowMs - since >= INDETERMINATE_PROBE_GRACE_MS
+        || !agentVersionIdentified(agent) || !agentCompatible(agent)) return null
+    return {
+      credentialState: previous.credentialState,
+      availabilitySource: previous.availabilitySource || 'native-probe-failed',
+    }
+  }
+
   setSidebarVisibility(kind, visible) {
     const agent = this.detectedAgents().find(item => item.kind === kind)
     if (!agent) throw new Error('LOCAL_AGENT_NOT_INSTALLED')
-    if (isReviewOnlyAgentKind(agent.kind)) throw new Error('LOCAL_AGENT_REVIEW_ONLY')
-    if (visible && !agent.available) throw new Error('LOCAL_AGENT_UNAVAILABLE')
     const state = this.state()
-    state.agentPreferences[kind] = { showInSidebar: Boolean(visible) }
-    agent.showInSidebar = agent.available && Boolean(visible)
+    state.agentPreferences[kind] = { ...state.agentPreferences[kind], showInSidebar: Boolean(visible) }
+    agent.showInSidebar = Boolean(visible)
     this.save()
     this.emitChanged()
     return this.snapshot()
@@ -167,8 +239,9 @@ class LocalWorkspaceAgentCatalog {
       credentialState,
       checkedAt: this.now(),
     }
+    if (credentialState === 'ready') this.indeterminateSince.delete(kind)
     const agent = this.detectedAgents().find(item => item.kind === kind)
-    if (agent) {
+    if (agent && !(credentialState === 'unknown' && agent.authenticated === true)) {
       agent.credentialState = credentialState
       agent.versionIdentified = agentVersionIdentified(agent)
       agent.compatible = agentCompatible(agent)
@@ -186,9 +259,7 @@ class LocalWorkspaceAgentCatalog {
             ? 'runtime-auth-failure'
             : 'unverified'
       const preferred = state.agentPreferences[kind]?.showInSidebar
-      agent.showInSidebar = !isReviewOnlyAgentKind(agent.kind)
-        && agent.available
-        && (typeof preferred === 'boolean' ? preferred : true)
+      agent.showInSidebar = typeof preferred === 'boolean' ? preferred : true
     }
     this.save()
     this.emitChanged()

desktop/src/workspace/local-workspace-auto-runner-collaboration.cjs

@@ -0,0 +1,261 @@
+// Collaboration records written while an automatic run progresses (roles, objectives, results).
+const { createHash } = require('node:crypto')
+const {
+  appendBlackboardEntry,
+  appendHandoff,
+  collaborationPackageText,
+  emptyCollaborationState,
+  publicCollaborationText,
+  roleForIndex,
+  visibleBlackboardEntries,
+} = require('../collaboration/collaboration-records.cjs')
+const { createTaskGraphCursor } = require('../collaboration/task-graph-records.cjs')
+
+const collaborationMethods = {
+  orchestrationCursor(targetKinds, taskGraph = null) {
+    if (taskGraph) {
+      return {
+        version: 3,
+        workflow: 'auto',
+        template: 'task-graph',
+        currentKind: '',
+        pendingKinds: [...targetKinds],
+        activeKinds: [...targetKinds],
+        successfulKinds: [],
+        agreementKinds: [],
+        attachmentRecipients: [],
+        totalSuccesses: 0,
+        terminalFailureOccurred: false,
+        collaboration: emptyCollaborationState(),
+        taskGraph: createTaskGraphCursor(taskGraph),
+      }
+    }
+    return {
+      version: 2,
+      workflow: 'auto',
+      currentKind: '',
+      pendingKinds: [...targetKinds],
+      activeKinds: [...targetKinds],
+      successfulKinds: [],
+      agreementKinds: [],
+      attachmentRecipients: [],
+      totalSuccesses: 0,
+      terminalFailureOccurred: false,
+      collaboration: emptyCollaborationState(),
+    }
+  },
+
+  collaborationRole(activeKinds, kind) {
+    return roleForIndex(Math.max(0, activeKinds.indexOf(kind)))
+  },
+
+  collaborationAudience(role) {
+    return {
+      roles: role === 'primary'
+        ? ['reviewer', 'arbiter']
+        : (role === 'reviewer' ? ['primary', 'arbiter'] : ['primary', 'reviewer']),
+      agentKinds: [],
+    }
+  },
+
+  collaborationAcceptance(role) {
+    if (role === 'reviewer') {
+      return [
+        'Check the selected claims and outcome references.',
+        'Identify unsupported assumptions, conflicts, or missing evidence.',
+      ]
+    }
+    if (role === 'arbiter') {
+      return [
+        'Resolve visible conflicts using the selected evidence.',
+        'Return one bounded conclusion and state whether consensus is reached.',
+      ]
+    }
+    return [
+      'Produce one concrete conclusion for the current task.',
+      'Publish only claims and durable outcome references needed downstream.',
+    ]
+  },
+
+  collaborationExpectedOutput(role) {
+    if (role === 'reviewer') return 'A concise review with corrections or explicit acceptance.'
+    if (role === 'arbiter') return 'A final adjudication of the selected claims and conflicts.'
+    return 'A concise primary conclusion with any durable Artifact or Evidence references.'
+  },
+
+  collaborationObjective(group, controller, threadRootId) {
+    const root = this.state().messages.find(message => (
+      message.groupId === group.id && message.id === threadRootId && message.role === 'user'
+    ))
+    return publicCollaborationText(root?.content || 'Complete the current user task.', 3000)
+      || 'Complete the current user task.'
+  },
+
+  prepareCollaborationPackage(
+    group, controller, activeKinds, kind, threadRootId, options = {},
+  ) {
+    const collaboration = controller.orchestration?.collaboration || emptyCollaborationState()
+    const destination = {
+      agentKind: kind,
+      role: options.role || this.collaborationRole(activeKinds, kind),
+    }
+    const selectedEntryIds = Array.isArray(options.selectedEntryIds)
+      ? new Set(options.selectedEntryIds)
+      : null
+    const selectedEntries = selectedEntryIds
+      ? collaboration.entries.filter(entry => selectedEntryIds.has(entry.entryId))
+      : visibleBlackboardEntries(collaboration, destination)
+    const objective = this.collaborationObjective(group, controller, threadRootId)
+    const expectedOutput = options.expectedOutput
+      || this.collaborationExpectedOutput(destination.role)
+    const acceptanceCriteria = options.acceptanceCriteria
+      || this.collaborationAcceptance(destination.role)
+    const selectedIds = selectedEntries.map(entry => entry.entryId)
+    const reusable = [...collaboration.handoffs].reverse().find(handoff => (
+      handoff.destination.agentKind === destination.agentKind
+      && handoff.destination.role === destination.role
+      && handoff.objective === objective
+      && handoff.expectedOutput === expectedOutput
+      && handoff.selectedEntryIds.length === selectedIds.length
+      && handoff.selectedEntryIds.every((id, index) => id === selectedIds[index])
+      && handoff.acceptanceCriteria.length === acceptanceCriteria.length
+      && handoff.acceptanceCriteria.every((value, index) => value === acceptanceCriteria[index])
+    ))
+    if (reusable) {
+      return {
+        handoff: reusable,
+        entries: selectedEntries,
+        text: collaborationPackageText(reusable, selectedEntries),
+      }
+    }
+    const previousOwner = [...collaboration.entries].reverse().find(entry => (
+      entry.owner.type === 'agent'
+    ))?.owner
+    const createdAt = Date.now()
+    const next = appendHandoff(collaboration, {
+      source: previousOwner || { type: 'harness' },
+      destination,
+      objective,
+      selectedEntryIds: selectedIds,
+      expectedOutput,
+      acceptanceCriteria,
+      provenance: {
+        runId: controller.runId,
+        taskId: controller.taskId,
+        round: controller.currentRound,
+        agentRunId: null,
+        artifactIds: [],
+        evidenceIds: [],
+      },
+      createdAt,
+    })
+    const handoff = next.handoffs.at(-1)
+    this.checkpointOrchestration(group, controller, { collaboration: next })
+    return {
+      handoff,
+      entries: selectedEntries,
+      text: collaborationPackageText(handoff, selectedEntries),
+    }
+  },
+
+  recordCollaborationResult(group, controller, activeKinds, kind, result, options = {}) {
+    const role = options.role || this.collaborationRole(activeKinds, kind)
+    const conclusion = publicCollaborationText(result?.message?.content || '')
+    const trace = result?.message?.trace
+    const provenance = {
+      runId: controller.runId,
+      taskId: controller.taskId,
+      round: controller.currentRound,
+      agentRunId: trace?.agentRunId || null,
+      artifactIds: result?.outcomeRefs?.artifactIds || [],
+      evidenceIds: result?.outcomeRefs?.evidenceIds || [],
+    }
+    let collaboration = controller.orchestration?.collaboration || emptyCollaborationState()
+    const previousCollaboration = collaboration
+    const previousEntryIds = new Set(collaboration.entries.map(entry => entry.entryId))
+    let sequence = collaboration.entries.length + 1
+    const recordedAt = Date.now()
+    const conclusionValue = conclusion
+      ? createHash('sha256').update(conclusion).digest('hex')
+      : ''
+    const entryType = options.entryType || 'claim'
+    const subject = options.subject || `task:${controller.taskId}:conclusion`
+    const entryRefs = Array.isArray(options.refs) ? options.refs : []
+    const duplicateConclusion = conclusion && collaboration.entries.some(entry => (
+      entry.entryType === entryType
+      && entry.lifecycle.state === 'active'
+      && entry.subject === subject
+      && entry.value === conclusionValue
+      && entry.owner.type === 'agent'
+      && entry.owner.agentKind === kind
+    ))
+    if (conclusion && !duplicateConclusion) {
+      collaboration = appendBlackboardEntry(collaboration, {
+        entryType,
+        subject,
+        statement: conclusion,
+        value: entryType === 'claim' ? conclusionValue : '',
+        owner: { type: 'agent', agentKind: kind, role },
+        audience: this.collaborationAudience(role),
+        lifecycle: {
+          state: 'active', sequence, recordedAt, supersedesEntryId: null,
+        },
+        provenance,
+        refs: entryRefs,
+      })
+      sequence = collaboration.entries.length + 1
+    }
+    for (const artifactId of duplicateConclusion ? [] : provenance.artifactIds.slice(0, 1)) {
+      collaboration = appendBlackboardEntry(collaboration, {
+        entryType: 'artifact-ref',
+        subject: `task:${controller.taskId}:artifact`,
+        statement: 'Durable Artifact produced by the Agent.',
+        value: '',
+        owner: { type: 'agent', agentKind: kind, role },
+        audience: this.collaborationAudience(role),
+        lifecycle: {
+          state: 'active', sequence, recordedAt, supersedesEntryId: null,
+        },
+        provenance,
+        refs: [artifactId],
+      })
+      sequence = collaboration.entries.length + 1
+    }
+    for (const evidenceId of duplicateConclusion ? [] : provenance.evidenceIds.slice(0, 1)) {
+      collaboration = appendBlackboardEntry(collaboration, {
+        entryType: 'evidence-ref',
+        subject: `task:${controller.taskId}:evidence`,
+        statement: 'Durable Evidence recorded for the Agent conclusion.',
+        value: '',
+        owner: { type: 'agent', agentKind: kind, role },
+        audience: this.collaborationAudience(role),
+        lifecycle: {
+          state: 'active', sequence, recordedAt, supersedesEntryId: null,
+        },
+        provenance,
+        refs: [evidenceId],
+      })
+      sequence = collaboration.entries.length + 1
+    }
+    if (collaboration !== previousCollaboration) {
+      this.checkpointOrchestration(group, controller, { collaboration })
+    }
+    return collaboration.entries
+      .filter(entry => !previousEntryIds.has(entry.entryId))
+      .map(entry => entry.entryId)
+  },
+
+  checkpointOrchestration(group, controller, updates = {}) {
+    const previous = controller.orchestration
+    controller.orchestration = { ...previous, ...updates }
+    // A thrown callback has an unknown write outcome; only explicit failure is safe to roll back.
+    const persisted = this.checkpointRun?.(group.id, controller)
+    if (this.hasRunLedger() && persisted !== true) {
+      controller.orchestration = previous
+      if (previous?.version === 4) controller.currentRound = previous.round
+      throw new Error('LOCAL_RUN_PERSIST_FAILED')
+    }
+  },
+}
+
+module.exports = { collaborationMethods }

desktop/src/workspace/local-workspace-auto-runner-natural-consensus.cjs

@@ -0,0 +1,135 @@
+const { hashValue } = require('../collaboration/orchestration-v4-records.cjs')
+const { createHash } = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+// Rebuild consensus from committed, operation-bound messages. No in-memory vote
+// can survive a crash without its corresponding durable Agent response.
+const naturalConsensusMethods = {
+  v4NaturalConsensus(group, controller, threadRootId) {
+    const messages = this.state().messages.filter(message => (
+      message.groupId === group.id && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && this.v4NaturalMessageMatchesBinding(message, controller)
+    )).sort((a, b) => (a.turnSeq || 0) - (b.turnSeq || 0))
+    let candidate = null
+    const files = new Map()
+    for (const message of messages) {
+      const artifactIds = message.trace?.context?.outcomeRefs?.artifactIds || []
+      for (const artifactId of artifactIds) {
+        const { artifact, contentHash } = this.v4ArtifactIdentity(artifactId)
+        if (artifact.locationRef?.kind === 'workspace-relative') {
+          if (candidate?.files.some(file => file.path === artifact.locationRef.path
+              && file.contentHash !== contentHash)) candidate = null
+          files.set(artifact.locationRef.path, { path: artifact.locationRef.path,
+            artifactId, contentHash, size: artifact.contentRef.size })
+        }
+      }
+      if (message.trace?.phase !== 'discussion') continue
+      const decision = message.trace?.context?.taskDecision
+      if (!decision) continue
+      if (decision.status !== 'completed') {
+        candidate = null
+        continue
+      }
+      if (decision.reviewedVersion) {
+        if (candidate && decision.reviewedVersion === candidate.version) {
+          candidate.approvedKinds.add(message.agentKind)
+        }
+        continue
+      }
+      // An unbound confirmation cannot replace the version being reviewed.
+      // Revisions must first withdraw it with a non-completed decision.
+      if (candidate) continue
+      const contribution = this.v4NaturalMessageContent(message)
+      if (contribution.partial || !contribution.text.trim()) {
+        candidate = null
+        continue
+      }
+      const candidateFiles = [...files.values()]
+      candidate = {
+        version: hashValue({ messageId: message.id, text: contribution.text, artifactIds, files: candidateFiles }),
+        message,
+        text: contribution.text,
+        artifactIds,
+        files: candidateFiles,
+        approvedKinds: new Set([message.agentKind]),
+      }
+    }
+    // Votes refer to captured bytes, not just a filename. Workspace edits made
+    // outside the discussion must not inherit approval of the previous bytes.
+    if (candidate?.files.length) {
+      try {
+        const root = fs.realpathSync(group.workdir)
+        for (const file of candidate.files) {
+          const filename = fs.realpathSync(path.resolve(root, file.path))
+          const relative = path.relative(root, filename)
+          if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`)
+              || path.isAbsolute(relative) || fs.statSync(filename).size !== file.size
+              || createHash('sha256').update(fs.readFileSync(filename)).digest('hex') !== file.contentHash) return null
+        }
+      } catch { return null }
+    }
+    return candidate
+  },
+
+  v4NaturalConsensusPrompt(group, controller, threadRootId) {
+    const candidate = this.v4NaturalConsensus(group, controller, threadRootId)
+    if (!candidate) return ''
+    return [
+      `Candidate version: ${candidate.version}`,
+      `Proposed by @${candidate.message.agentKind}. Review this exact complete candidate, including its deliverable files, before accepting.`,
+      `Candidate deliverables: ${JSON.stringify(candidate.message.trace.context.taskDecision.deliverables)}`,
+      `Immutable artifact references: ${JSON.stringify(candidate.artifactIds)}`,
+      `Deliverable file versions (read each file and verify its contents): ${JSON.stringify(candidate.files)}`,
+      'Complete candidate answer (not a transcript excerpt):',
+      candidate.text,
+      `To accept this version, use status completed and reviewedVersion "${candidate.version}" in your receipt. Do not rewrite or replace the candidate while accepting it.`,
+      'If anything needs changing, use status continue, explain the defect and request the peer who should fix it. This withdraws the candidate and all its approvals; the revised result needs fresh approval from everyone.',
+      'Do not modify this candidate while accepting it. Missing, stale or implicit approval never counts as acceptance.',
+    ].join('\n\n')
+  },
+
+  async v4NaturalAgentLedOutcome(group, controller, threadRootId, round, activeKinds) {
+    const messages = this.v4NaturalDiscussionRoundMessages(group, controller, threadRootId, round)
+    const candidate = this.v4NaturalConsensus(group, controller, threadRootId)
+    if (candidate) {
+      const missing = controller.targetKinds.filter(kind => !candidate.approvedKinds.has(kind))
+      if (!missing.length) return { status: 'completed' }
+      const available = missing.filter(kind => activeKinds.includes(kind))
+      if (available.length) return { nextKinds: available }
+      return { status: 'partial' }
+    }
+    const decisionMessage = messages.at(-1)
+    const decision = decisionMessage?.trace?.context?.taskDecision
+    const route = this.v4NaturalRouteDecision(decision, activeKinds)
+    if (route.dropped.length) {
+      this.v4NaturalNotice(group, controller, threadRootId, 'system.autoRouteIgnored',
+        'Requests for unavailable participants were skipped.',
+        { agents: route.dropped.map(kind => this.agentLabel(kind)).join(', ') })
+    }
+    if (decision?.status === 'needs-human' && this.requestTaskDecision) {
+      const response = await this.requestTaskDecision(group, controller, decisionMessage)
+      if (response?.status === 'approved') return { nextKinds: [decisionMessage.agentKind] }
+      if (response?.status === 'rejected') {
+        controller.stopReason = 'human_gate_rejected'
+        return { status: 'stopped' }
+      }
+    }
+    if (['blocked', 'needs-human'].includes(decision?.status)) {
+      this.addMessage(group.id, 'system', decision.reason, '', threadRootId, {
+        key: decision.status === 'needs-human' ? 'system.autoTaskNeedsHuman' : 'system.autoTaskBlocked',
+        params: { reason: decision.reason },
+      })
+      return { status: 'partial' }
+    }
+    const nextKinds = this.v4NaturalNextKinds(group, controller, threadRootId, round, activeKinds)
+    if (nextKinds.length) return { nextKinds }
+    // A missing receipt is not approval. Ask the current speaker to finish
+    // their handoff or propose a concrete candidate instead of inventing votes.
+    return { nextKinds: [], fallbackKind: activeKinds.includes(decisionMessage?.agentKind)
+      ? decisionMessage.agentKind : activeKinds[0] }
+  },
+}
+
+module.exports = { naturalConsensusMethods }

desktop/src/workspace/local-workspace-auto-runner-natural-decisions.cjs

@@ -0,0 +1,239 @@
+const { parseLenientTaskDecision } = require('../collaboration/task-decision.cjs')
+
+const v4NaturalDecisionMethods = {
+  v4NaturalRouteDecision(decision, activeKinds) {
+    const participants = Array.isArray(activeKinds) ? activeKinds : []
+    if (decision == null) return { status: 'none', kinds: [], dropped: [] }
+    let parsed
+    try { parsed = parseLenientTaskDecision(decision) }
+    catch { return { status: 'none', kinds: [], dropped: [] } }
+    const requested = parsed.nextKinds || []
+    // A request for an absent or paused participant is dropped on its own;
+    // it used to stop the whole discussion with a misleading message.
+    const dropped = requested.filter(kind => !participants.includes(kind))
+    const kinds = requested.filter(kind => participants.includes(kind))
+    return { status: kinds.length ? 'valid' : 'none', kinds, dropped }
+  },
+
+  v4NaturalNotice(group, controller, threadRootId, key, text, params = {}) {
+    const runParams = { ...params, runId: controller.runId }
+    const duplicate = this.state().messages.some(message => (
+      message.threadRootId === threadRootId
+        && message.system?.key === key
+        && JSON.stringify(message.system?.params || {}) === JSON.stringify(runParams)
+    ))
+    if (!duplicate) {
+      this.addMessage(group.id, 'system', text, '', threadRootId, { key, params: runParams })
+    }
+  },
+
+  async v4NaturalRoundOutcome(group, controller, threadRootId, round, activeKinds) {
+    const messages = this.v4NaturalDiscussionRoundMessages(group, controller, threadRootId, round)
+    if (!activeKinds.length) return { status: 'partial' }
+    const nominalOwner = this.v4NaturalOwner(group, controller, threadRootId)
+    const owner = this.v4NaturalOwner(group, controller, threadRootId, activeKinds)
+    if (owner !== nominalOwner) {
+      // The owner failed or was paused: the next selected participant takes
+      // over instead of the discussion ending silently as partial.
+      this.v4NaturalNotice(group, controller, threadRootId, 'system.autoOwnerChanged',
+        `${this.agentLabel(owner)} took over as delivery owner because ${this.agentLabel(nominalOwner)} is no longer available.`,
+        { agent: this.agentLabel(owner), previous: this.agentLabel(nominalOwner) })
+    }
+    const routes = messages.map(message => this.v4NaturalRouteDecision(
+      message.trace?.context?.taskDecision, activeKinds,
+    ))
+    const dropped = [...new Set(routes.flatMap(route => route.dropped || []))]
+    if (dropped.length) {
+      this.v4NaturalNotice(group, controller, threadRootId, 'system.autoRouteIgnored',
+        `Requests for ${dropped.map(kind => this.agentLabel(kind)).join(', ')} were skipped because they are not active in this discussion.`,
+        { agents: dropped.map(kind => this.agentLabel(kind)).join(', ') })
+    }
+    const ownerMessage = messages.find(message => message.agentKind === owner)
+    // A peer's blocker is input for the delivery owner, who judges the whole
+    // task. It used to end the discussion as partial on the spot.
+    const peerBlocker = messages.find(message => {
+      if (message.agentKind === owner) return false
+      const status = message.trace?.context?.taskDecision?.status
+      return status === 'blocked' || status === 'needs-human'
+    })
+    const ownerSawBlocker = peerBlocker && ownerMessage
+      && controller.discussionStyle === 'sequential'
+      && messages.indexOf(ownerMessage) > messages.indexOf(peerBlocker)
+    if (peerBlocker && !ownerSawBlocker) {
+      const peerDecision = peerBlocker.trace?.context?.taskDecision
+      this.v4NaturalNotice(group, controller, threadRootId, 'system.autoPeerBlockerForwarded',
+        `${this.agentLabel(peerBlocker.agentKind)} reported a blocker; the delivery owner will decide how to proceed.`,
+        { agent: this.agentLabel(peerBlocker.agentKind), reason: peerDecision.reason })
+      return { nextKinds: [owner], ownerReview: true }
+    }
+    const nextKinds = this.v4NaturalNextKinds(group, controller, threadRootId, round, activeKinds)
+    if (nextKinds.length) return { nextKinds, ownerReview: false }
+    const decision = ownerMessage?.trace?.context?.taskDecision
+    if (decision?.handoffTo && !activeKinds.includes(decision.handoffTo)) {
+      this.v4NaturalNotice(group, controller, threadRootId, 'system.autoHandoffIgnored',
+        `The handoff to ${this.agentLabel(decision.handoffTo)} was ignored because that Agent is not active; ${this.agentLabel(owner)} remains the delivery owner.`,
+        { agent: this.agentLabel(decision.handoffTo), owner: this.agentLabel(owner) })
+    }
+    if (decision?.status === 'continue') return { nextKinds: [owner], ownerReview: false }
+    const sawAllContributions = messages.length === 1
+      || (controller.discussionStyle === 'sequential' && messages.at(-1)?.agentKind === owner)
+    if (!ownerMessage || !sawAllContributions) return { nextKinds: [owner], ownerReview: true }
+    if (!decision) {
+      // Ask the owner once more for a judgment before giving up: a missing
+      // or unreadable receipt is usually a formatting slip, not a verdict.
+      if (!this.v4NaturalOwnerMissedDecisionBefore(group, controller, threadRootId, round, owner)) {
+        this.v4NaturalNotice(group, controller, threadRootId, 'system.autoTaskDecisionRequested',
+          `${this.agentLabel(owner)} did not include a readable task decision; asking for one before continuing.`,
+          { agent: this.agentLabel(owner), round })
+        return { nextKinds: [owner], ownerReview: true }
+      }
+      this.addMessage(group.id, 'system', 'Discussion stopped without a valid task completion decision.',
+        '', threadRootId, { key: 'system.autoTaskDecisionMissing' })
+      return { status: 'partial' }
+    }
+    if (decision.status === 'completed') {
+      // The owner may not close the task before selected peers had one discussion
+      // round of their own; otherwise a single full round collapses into an
+      // owner-only review and peers never get to challenge the result.
+      if (activeKinds.some(kind => kind !== owner)
+          && !this.v4NaturalPriorPeerDiscussion(group, controller, threadRootId, round, owner)) {
+        this.addMessage(
+          group.id, 'system',
+          'The delivery owner signaled completion before peer discussion; running one cross-review round first.',
+          '', threadRootId, { key: 'system.autoCrossReview' },
+        )
+        return { nextKinds: [...activeKinds], ownerReview: false }
+      }
+      if (controller.failedKinds.length) {
+        this.v4NaturalNotice(group, controller, threadRootId, 'system.autoCompletedWithout',
+          `The delivery owner completed the task without ${controller.failedKinds.map(kind => this.agentLabel(kind)).join(', ')}, which stopped earlier in this discussion.`,
+          { agents: controller.failedKinds.map(kind => this.agentLabel(kind)).join(', ') })
+        return { status: 'partial' }
+      }
+      return { status: 'completed' }
+    }
+    if (decision.status === 'needs-human' && this.requestTaskDecision) {
+      const response = await this.requestTaskDecision(group, controller, ownerMessage)
+      if (response?.status === 'approved') return { nextKinds: [owner], ownerReview: true }
+      if (response?.status === 'rejected') {
+        controller.stopReason = 'human_gate_rejected'
+        return { status: 'stopped' }
+      }
+    }
+    this.addMessage(group.id, 'system', decision.reason, '', threadRootId, {
+      key: decision.status === 'needs-human' ? 'system.autoTaskNeedsHuman' : 'system.autoTaskBlocked',
+      params: { reason: decision.reason },
+    })
+    return { status: 'partial' }
+  },
+
+  v4NaturalNextKinds(group, controller, threadRootId, round, activeKinds) {
+    const current = this.v4NaturalDiscussionRoundMessages(group, controller, threadRootId, round)
+    const selected = new Set(current.flatMap(message => (
+      this.v4NaturalRouteDecision(message.trace?.context?.taskDecision, activeKinds).kinds
+        .filter(kind => kind !== message.agentKind)
+    )))
+    if (!selected.size) return []
+    return [...selected]
+  },
+
+  v4NaturalPriorPeerDiscussion(group, controller, threadRootId, round, owner) {
+    return this.state().messages.some(message => (
+      message.groupId === group.id
+      && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && message.agentKind !== owner
+      && message.trace?.runId === controller.runId
+      && message.trace?.phase === 'discussion'
+      && Number(message.trace?.round) < round
+      && this.v4NaturalMessageMatchesBinding(message, controller)
+    ))
+  },
+
+  v4NaturalOwnerMissedDecisionBefore(group, controller, threadRootId, round, owner) {
+    const earlier = this.state().messages.filter(message => (
+      message.groupId === group.id
+      && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && message.agentKind === owner
+      && message.trace?.runId === controller.runId
+      && message.trace?.phase === 'discussion'
+      && Number(message.trace?.round) < round
+      && this.v4NaturalMessageMatchesBinding(message, controller)
+    ))
+    const previous = earlier.at(-1)
+    return Boolean(previous && !previous.trace?.context?.taskDecision)
+  },
+
+  // With activeKinds, an owner who failed or was paused hands ownership to
+  // the first still-active selected participant.
+  v4NaturalOwner(group, controller, threadRootId, activeKinds = null) {
+    let owner = controller.targetKinds[0] || ''
+    for (const message of this.state().messages) {
+      if (message.groupId !== group.id || message.threadRootId !== threadRootId
+          || message.role !== 'agent' || message.agentKind !== owner
+          || message.trace?.phase !== 'discussion'
+          || !this.v4NaturalMessageMatchesBinding(message, controller)) continue
+      const decision = message.trace?.context?.taskDecision
+      if (decision?.status === 'continue' && decision.handoffTo
+          && controller.targetKinds.includes(decision.handoffTo)) owner = decision.handoffTo
+    }
+    if (Array.isArray(activeKinds) && activeKinds.length && !activeKinds.includes(owner)) {
+      return controller.targetKinds.find(kind => activeKinds.includes(kind)) || owner
+    }
+    return owner
+  },
+
+  v4NaturalDiscussionIsRepeating(group, controller, threadRootId, round, activeKinds) {
+    const window = Math.max(4, activeKinds.length * 2)
+    if (round < window + 2) return false
+    const firstRound = round - window + 1
+    const previous = new Map()
+    const observedRounds = new Set()
+    const messages = this.state().messages
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      const message = messages[index]
+      const messageRound = Number(message.trace?.round) || 0
+      if (message.groupId !== group.id || message.threadRootId !== threadRootId
+          || message.role !== 'agent' || message.trace?.phase !== 'discussion'
+          || message.trace?.runId !== controller.runId || messageRound < 2
+          || messageRound > round || !this.v4NaturalMessageMatchesBinding(message, controller)) continue
+      const contribution = this.v4NaturalMessageContent(message)
+      if (contribution.partial) return false
+      const text = contribution.text
+        .replace(/@[A-Za-z0-9][A-Za-z0-9_-]*/gu, '')
+        .replace(/\s+/gu, ' ').trim()
+      const files = []
+      for (const artifactId of message.trace?.context?.outcomeRefs?.artifactIds || []) {
+        try {
+          const { artifact, contentHash } = this.v4ArtifactIdentity(artifactId)
+          if (artifact.locationRef?.kind === 'workspace-relative') {
+            files.push([artifact.locationRef.path, contentHash])
+          }
+        } catch { return false }
+      }
+      const content = JSON.stringify([text, message.trace?.context?.taskDecision?.reviewedVersion || '', files.sort()])
+      if (previous.has(message.agentKind) && previous.get(message.agentKind) !== content) return false
+      if (messageRound >= firstRound) {
+        observedRounds.add(messageRound)
+        previous.set(message.agentKind, content)
+      } else {
+        previous.delete(message.agentKind)
+        if (observedRounds.size === window && previous.size === 0) return true
+      }
+    }
+    return false
+  },
+
+  v4NaturalStopRepeatingDiscussion(group, controller, threadRootId, round, activeKinds) {
+    if (!this.v4NaturalDiscussionIsRepeating(group, controller, threadRootId, round, activeKinds)) return false
+    this.addMessage(
+      group.id, 'system',
+      'Automatic discussion stopped because repeated handoffs produced no new contribution.',
+      '', threadRootId, { key: 'system.autoDiscussionStalled' },
+    )
+    return true
+  },
+}
+
+module.exports = { v4NaturalDecisionMethods }

desktop/src/workspace/local-workspace-auto-runner-natural-discussion.cjs

@@ -0,0 +1,557 @@
+// Natural discussion, the production path for automatic group runs: transcript, prompts and the sequential and agent-led loops.
+const path = require('node:path')
+const { MAX_MESSAGE_TEXT_CHARS } = require('./local-workspace-contracts.cjs')
+const { hashValue } = require('../collaboration/orchestration-v4-records.cjs')
+const { packNaturalDiscussionTranscript, v4Prompt } = require('./local-workspace-context.cjs')
+const { naturalDiscussionPrompt } = require('./prompts/natural-discussion-prompt.cjs')
+const { terminalRunStatusForReason } = require('./local-workspace-auto-runner-support.cjs')
+const { traceCapsuleFromAgentRun } = require('../runs/run-harness-normalization.cjs')
+
+const naturalDiscussionMethods = {
+  v4NaturalMessageMatchesBinding(message, controller) {
+    const phase = String(message?.trace?.phase || '')
+    const kind = String(message?.agentKind || '')
+    const round = Number(message?.trace?.round) || 0
+    if (!['proposal', 'discussion'].includes(phase) || !kind || round < 1) return false
+    if (message.trace?.runId !== controller.runId) return false
+    const slot = controller.orchestration?.slots?.find(candidate => candidate.agentKind === kind)
+    const snapshotHash = String(controller.orchestration?.snapshotHash || '')
+    if (!slot?.slotId || !snapshotHash) return false
+    const operationPhase = phase === 'discussion' ? `discussion:${round}` : phase
+    const expectedOperationId = this.v4OperationId(
+      controller, kind, operationPhase, slot.slotId, round,
+    )
+    return message.trace?.context?.operationId === expectedOperationId
+      && message.trace?.context?.snapshotHash === snapshotHash
+  },
+
+  v4NaturalMessageContent(message) {
+    const text = String(message.content || '')
+    if (text.length < MAX_MESSAGE_TEXT_CHARS && message.trace?.truncated !== true) {
+      return { text, partial: false }
+    }
+    for (const artifactId of message.trace?.context?.outcomeRefs?.artifactIds || []) {
+      try {
+        const { artifact, content } = this.v4ArtifactIdentity(artifactId)
+        if (artifact.name !== `${message.agentKind}-conclusion.txt`
+            || artifact.producedBy?.runId !== message.trace?.runId
+            || artifact.producedBy?.agentRunId !== message.trace?.agentRunId
+            || artifact.producedBy?.agentKind !== message.agentKind
+            || !content.startsWith(text)) continue
+        return { text: content, partial: false }
+      } catch { /* Historical blobs may be unavailable; identify the excerpt below. */ }
+    }
+    return { text, partial: true }
+  },
+
+  v4NaturalThreadEntries(group, threadRootId, options = {}) {
+    const rounds = Array.isArray(options.rounds) ? new Set(options.rounds) : null
+    const entries = this.state().messages.filter(message => (
+      message.groupId === group.id
+      && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && message.agentKind
+      && (!rounds || rounds.has(Number(message.trace?.round) || 0))
+      && (!options.controller || this.v4NaturalMessageMatchesBinding(
+        message, options.controller,
+      ))
+    )).map((message, index) => ({ message, index }))
+      // Peers read turns in dispatch order, the same order the user sees,
+      // instead of the order replies happened to be saved in.
+      .sort((left, right) => {
+        const leftTurn = Number.isSafeInteger(left.message.turnSeq) ? left.message.turnSeq : 0
+        const rightTurn = Number.isSafeInteger(right.message.turnSeq) ? right.message.turnSeq : 0
+        return (leftTurn ? 1 : 0) - (rightTurn ? 1 : 0)
+          || leftTurn - rightTurn
+          || left.index - right.index
+      })
+      .map(({ message }) => message)
+      .map(message => ({
+      ...this.v4NaturalMessageContent(message),
+      id: message.id,
+      agentKind: message.agentKind,
+      round: Number(message.trace?.round) || 0,
+      phase: message.trace?.phase || 'proposal',
+      operationId: message.trace?.context?.operationId || '',
+    })).map(entry => ({
+      // Peers collaborating on the same workspace must be able to name its
+      // files; keep workspace paths readable as relative paths.
+      ...entry, text: this.v4SanitizeDeliveryText(entry.text, Number.MAX_SAFE_INTEGER, {
+        workspaceRoot: group.workdir ? path.resolve(group.workdir) : '',
+      }),
+    }))
+    return entries.map(entry => ({ ...entry, hash: hashValue(entry) }))
+  },
+
+  v4NaturalThreadTranscript(group, threadRootId, options = {}) {
+    return packNaturalDiscussionTranscript(this.v4NaturalThreadEntries(group, threadRootId, options))
+  },
+
+  v4NaturalDeliveryPrompt(group, controller, threadRootId, kind, slot, binding, promptBuilder) {
+    const entries = this.v4NaturalThreadEntries(group, threadRootId, { controller })
+    const previousEntries = binding.hasSession && !binding.sessionRotated
+      ? (controller.orchestration?.deliveryState || []).filter(entry => (
+          entry.recipientKind === kind && entry.status === 'acknowledged'
+          && entry.sessionRefHash === binding.sessionRefHash
+          && entry.sessionProvenanceHash === binding.sessionProvenanceHash
+          && entry.snapshotHash === controller.orchestration.snapshotHash
+          && entry.sourceMessages
+        ))
+      : []
+    const seen = new Set(previousEntries.flatMap(entry => entry.sourceMessages.map(message => (
+      [entry.sourceAgentKind, entry.sourcePhase, message.id, message.hash].join('\u0000')
+    ))))
+    const unseen = entries.filter(entry => !seen.has([
+      entry.agentKind, entry.phase, entry.id, entry.hash,
+    ].join('\u0000')))
+    const fullOpening = controller.discussionStyle === 'agent-led' && controller.currentRound === 2
+      ? entries.filter(entry => entry.phase === 'proposal') : null
+    const packed = fullOpening ? {
+      text: fullOpening.map(entry => `Round 1 - @${entry.agentKind} [${entry.id}]\n${entry.text}`).join('\n\n'),
+      completeMessageIds: fullOpening.filter(entry => !entry.partial).map(entry => entry.id),
+    } : packNaturalDiscussionTranscript(unseen, {
+      withEntries: true,
+      prefix: unseen.length < entries.length
+        ? 'Previously delivered turns are not repeated here. They were supplied to this native session; ask peers to restate missing evidence if your current context is incomplete. Their omission does not imply agreement or task completion.'
+        : '',
+    })
+    const included = new Set(packed.completeMessageIds)
+    const sources = new Map()
+    for (const entry of unseen) {
+      if (!included.has(entry.id)) continue
+      const key = `${entry.agentKind}\u0000${entry.phase}`
+      const source = sources.get(key) || {
+        sourceAgentKind: entry.agentKind, sourcePhase: entry.phase,
+        watermark: 0, operationId: entry.operationId, sourceMessages: [],
+      }
+      source.watermark = Math.max(source.watermark, entry.round)
+      source.sourceMessages.push({ id: entry.id, hash: entry.hash })
+      sources.set(key, source)
+    }
+    const packageHash = hashValue(packed.text)
+    const deliveryId = `delivery-${hashValue({
+      runId: controller.runId, kind, operationId: slot.operationId,
+      packageHash, binding, now: Date.now(),
+    })}`
+    const delivery = sources.size ? {
+      natural: true, previousEntries, packageHash, deliveryId,
+      entries: [...sources.values()].map(source => ({
+        ...source, recipientKind: kind,
+        sessionRefHash: binding.sessionRefHash,
+        sessionProvenanceHash: binding.sessionProvenanceHash,
+        snapshotHash: controller.orchestration.snapshotHash,
+        packageHash, deliveryId, status: 'prepared', updatedAt: Date.now(),
+      })),
+    } : null
+    this.v4PrepareDelivery(group, controller, delivery)
+    return { prompt: promptBuilder(packed.text), delivery }
+  },
+
+  v4NaturalRecoveredPhaseResult(group, controller, threadRootId, phase, kind, slot) {
+    if (!this.naturalAgentResponses || !slot || controller.currentRound < 1) return null
+    if (!['proposal', 'discussion'].includes(phase)) return null
+    const operationId = String(slot.operationId || '')
+    const snapshotHash = String(slot.snapshotHash || '')
+    if (!operationId || !snapshotHash) return null
+    const matchesBinding = context => (
+      context?.operationId === operationId && context?.snapshotHash === snapshotHash
+    )
+    const scopedMessages = [...this.state().messages].reverse().filter(message => (
+      message.groupId === group.id
+      && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && message.agentKind === kind
+      && message.trace?.runId === controller.runId
+      && message.trace?.phase === phase
+      && Number(message.trace?.round) === controller.currentRound
+    ))
+    if (scopedMessages.some(message => !matchesBinding(message.trace?.context))) {
+      throw new Error('LOCAL_RUN_COLLABORATION_SCOPE_INVALID')
+    }
+    const existingMessage = scopedMessages.find(message => matchesBinding(message.trace?.context))
+    let content = String(existingMessage?.content || '')
+    let trace = existingMessage?.trace || null
+    let metadata = existingMessage ? {
+      ...(existingMessage.elapsedMs != null ? { elapsedMs: existingMessage.elapsedMs } : {}),
+      ...(Array.isArray(existingMessage.toolCalls) ? { toolCalls: existingMessage.toolCalls } : {}),
+      ...(Array.isArray(existingMessage.attachments)
+        ? { attachments: existingMessage.attachments } : {}),
+      ...(existingMessage.responseVersionRootId
+        ? { responseVersionRootId: existingMessage.responseVersionRootId } : {}),
+      trace,
+    } : null
+    if (!content || !trace?.agentRunId) {
+      const scopedRuns = [...(controller.harness?.snapshot?.() || [])].reverse().filter(run => (
+        run.kind === kind
+        && run.round === controller.currentRound
+        && run.status === 'completed'
+        && String(run.output || '')
+      ))
+      if (scopedRuns.some(run => !matchesBinding(run.context))) {
+        throw new Error('LOCAL_RUN_COLLABORATION_SCOPE_INVALID')
+      }
+      const recoveredRun = scopedRuns.find(run => matchesBinding(run.context))
+      if (!recoveredRun) return null
+      content = String(recoveredRun.output)
+      trace = traceCapsuleFromAgentRun(recoveredRun, {
+        runId: controller.runId,
+        status: recoveredRun.status,
+        phase,
+      })
+      if (!trace?.agentRunId) return null
+      metadata = { trace }
+    }
+    return {
+      text: content,
+      pendingMessage: {
+        groupId: group.id,
+        role: 'agent',
+        content,
+        agentKind: kind,
+        threadRootId,
+        system: null,
+        metadata,
+      },
+      collaboration: trace.context?.taskDecision
+        ? { summary: trace.context.taskDecision.reason, taskDecision: trace.context.taskDecision }
+        : null,
+      outcomeRefs: trace.context?.outcomeRefs || {},
+      operationId: slot.operationId,
+      consensus: false,
+    }
+  },
+
+  v4NaturalRecoveredDiscussionResult(group, controller, threadRootId, kind, slot) {
+    return this.v4NaturalRecoveredPhaseResult(
+      group, controller, threadRootId, 'discussion', kind, slot,
+    )
+  },
+
+  v4NaturalPhasePrompt(group, kind, phase, snapshot, receiptRecords, activeKinds, options = {}) {
+    const humanResponses = options.runId ? this.taskDecisionResponses(options.runId) : []
+    return naturalDiscussionPrompt({
+      brief: v4Prompt({
+        group, kind, phase, snapshot, role: 'participant',
+        skillHints: options.skillHints,
+        knowledgeBaseHints: options.knowledgeBaseHints,
+        naturalResponse: true,
+      }),
+      group,
+      kind,
+      phase,
+      activeKinds,
+      transcript: String(options.transcript || ''),
+      humanResponsesText: humanResponses.length ? packNaturalDiscussionTranscript(humanResponses) : '',
+      writerKind: group.allowWrite === true ? kind : '',
+      ownerKind: options.ownerKind,
+      allowRouting: options.allowRouting === true,
+      consensusText: options.consensusText || '',
+    })
+  },
+
+  v4NaturalDiscussionOperationIds(controller, slots, kinds, round) {
+    return new Map(kinds.map((kind) => {
+      const slot = slots.find(candidate => candidate.agentKind === kind)
+      return [kind, this.v4OperationId(
+        controller, kind, `discussion:${round}`, slot?.slotId || '', round,
+      )]
+    }))
+  },
+
+  v4NaturalDiscussionRoundMessages(group, controller, threadRootId, round) {
+    return this.state().messages.filter(message => (
+      message.groupId === group.id
+      && message.threadRootId === threadRootId
+      && message.role === 'agent'
+      && message.trace?.runId === controller.runId
+      && message.trace?.phase === 'discussion'
+      && Number(message.trace?.round) === round
+      && this.v4NaturalMessageMatchesBinding(message, controller)
+    ))
+  },
+
+  async runV4SequentialDiscussion(group, controller, threadRootId, context, input) {
+    const {
+      targetKinds, activeKinds: initialActiveKinds, writerKind, batchId,
+      snapshot, snapshotRecord, snapshotHash, slots: initialSlots, receiptRecords,
+      checkpointPhase, removePhaseFailures, addRoundLimitNotice,
+    } = input
+    let activeKinds = [...initialActiveKinds]
+    let slots = initialSlots
+    let round = Math.max(1, Number(controller.currentRound) || 1)
+    let pendingKinds = controller.orchestration?.discussionStyle === 'sequential'
+      && controller.orchestration?.phase === 'discussion'
+      && controller.orchestration?.round === round
+      ? (controller.orchestration.pendingKinds || []).filter(kind => activeKinds.includes(kind))
+      : [...activeKinds]
+    if (!pendingKinds.length && controller.orchestration?.phase === 'discussion') {
+      const outcome = await this.v4NaturalRoundOutcome(group, controller, threadRootId, round, activeKinds)
+      if (outcome.status) return outcome.status
+      if (!controller.unlimitedRounds && round >= (controller.maxRounds || 6)) {
+        addRoundLimitNotice()
+        return 'round-limit'
+      }
+      round += 1
+      pendingKinds = outcome.ownerReview ? outcome.nextKinds : [...activeKinds]
+    }
+    while (!controller.signal.aborted) {
+      controller.currentRound = round
+      while (pendingKinds.length && !controller.signal.aborted) {
+        const kind = pendingKinds[0]
+        const remainingKinds = pendingKinds.slice(1)
+        const dispatch = await this.runV4Phase(group, controller, threadRootId, context, {
+          phase: 'discussion',
+          activeKinds: [kind],
+          targetKinds,
+          participantKinds: activeKinds,
+          writerKind,
+          batchId,
+          snapshot,
+          snapshotRecord,
+          snapshotHash,
+          slots,
+          receiptRecords,
+          challengeBindings: null,
+          coordinationPlan: null,
+          workReceipts: [],
+          operationIds: this.v4NaturalDiscussionOperationIds(
+            controller, slots, [kind], round,
+          ),
+          pendingKinds,
+          remainingKinds,
+          sessionPolicy: null,
+          resumedGate: input.resumedGate,
+          disableDeliveryPrompt: true,
+          promptBuilder: ({ kind: promptKind, transcript }) => this.v4NaturalPhasePrompt(
+            group, promptKind, 'discussion', snapshot, receiptRecords, activeKinds, {
+              runId: controller.runId,
+              transcript: transcript ?? this.v4NaturalThreadTranscript(
+                group, threadRootId, { controller },
+              ),
+              skillHints: context.rootSkillsByKind.get(promptKind) || [],
+              knowledgeBaseHints: context.rootKnowledgeBasesByKind.get(promptKind) || [],
+              ownerKind: this.v4NaturalOwner(group, controller, threadRootId, activeKinds),
+              writerKind,
+              allowRouting: false,
+            },
+          ),
+        })
+        slots = dispatch.slots || slots
+        if (!dispatch.ok) {
+          if (controller.signal.aborted) return terminalRunStatusForReason(controller.stopReason)
+          const failedKinds = removePhaseFailures(dispatch)
+          activeKinds = activeKinds.filter(agentKind => !failedKinds.includes(agentKind))
+          if (!activeKinds.length) {
+            return dispatch.phasePendingMessages?.length ? 'partial' : 'failed'
+          }
+        }
+        pendingKinds = remainingKinds.filter(agentKind => activeKinds.includes(agentKind))
+      }
+      const outcome = await this.v4NaturalRoundOutcome(group, controller, threadRootId, round, activeKinds)
+      if (outcome.status) return outcome.status
+      if (!controller.unlimitedRounds && round >= (controller.maxRounds || 6)) {
+        addRoundLimitNotice()
+        return 'round-limit'
+      }
+      round += 1
+      controller.currentRound = round
+      pendingKinds = outcome.ownerReview ? outcome.nextKinds : [...activeKinds]
+    }
+    return terminalRunStatusForReason(controller.stopReason)
+  },
+
+  async runV4AgentLedDiscussion(group, controller, threadRootId, context, input) {
+    const {
+      targetKinds, activeKinds: initialActiveKinds, batchId,
+      snapshot, snapshotRecord, snapshotHash, slots: initialSlots, receiptRecords,
+      latestFor, runPhase, checkpointPhase, removePhaseFailures, addRoundLimitNotice,
+    } = input
+    let activeKinds = [...initialActiveKinds]
+    let slots = initialSlots
+    let round = Math.max(1, Number(controller.currentRound) || 1)
+    const proposalCompleteBeforeRun = activeKinds.every(kind => Boolean(latestFor('proposal', kind)))
+    if (!proposalCompleteBeforeRun) {
+      controller.currentRound = 1
+      const proposal = await runPhase('proposal', activeKinds)
+      slots = proposal.slots || slots
+      if (!proposal.ok) {
+        const failedKinds = removePhaseFailures(proposal)
+        activeKinds = activeKinds.filter(kind => !failedKinds.includes(kind))
+        checkpointPhase('proposal', [], slots, null)
+        if (!activeKinds.length) return proposal.phasePendingMessages?.length ? 'partial' : 'failed'
+      }
+    }
+    const proposalComplete = activeKinds.every(kind => Boolean(latestFor('proposal', kind)))
+    if (!proposalComplete) {
+      return activeKinds.some(kind => Boolean(latestFor('proposal', kind))) ? 'partial' : 'failed'
+    }
+    if (!controller.unlimitedRounds && (controller.maxRounds || 6) <= 1) {
+      addRoundLimitNotice()
+      return 'round-limit'
+    }
+
+    let nextKinds = []
+    if (controller.orchestration?.phase === 'discussion') {
+      round = Math.max(2, Number(controller.orchestration.round) || 2)
+      nextKinds = (controller.orchestration.pendingKinds || [])
+        .filter(kind => activeKinds.includes(kind))
+      if (!nextKinds.length) {
+        if (this.v4NaturalStopRepeatingDiscussion(
+          group, controller, threadRootId, round, activeKinds,
+        )) return 'partial'
+        const outcome = await this.v4NaturalAgentLedOutcome(group, controller, threadRootId, round, activeKinds)
+        if (outcome.status) return outcome.status
+        nextKinds = outcome.nextKinds.length ? outcome.nextKinds : [outcome.fallbackKind]
+        if (!controller.unlimitedRounds && round >= (controller.maxRounds || 6)) {
+          addRoundLimitNotice()
+          return 'round-limit'
+        }
+        round += 1
+      }
+    } else {
+      round = 2
+      nextKinds = [activeKinds[0]]
+    }
+
+    while (!controller.signal.aborted) {
+      controller.currentRound = round
+      const kind = nextKinds[0]
+      const remainingKinds = nextKinds.slice(1)
+      const candidate = this.v4NaturalConsensus(group, controller, threadRootId)
+      const turnWriterKind = !candidate && group.allowWrite === true && this.canWriteWorkspace(kind)
+        ? kind : ''
+      const dispatch = await this.runV4Phase(group, controller, threadRootId, context, {
+        phase: 'discussion',
+        activeKinds: [kind],
+        targetKinds,
+        participantKinds: activeKinds,
+        writerKind: turnWriterKind,
+        batchId,
+        snapshot,
+        snapshotRecord,
+        snapshotHash,
+        slots,
+        receiptRecords,
+        challengeBindings: null,
+        coordinationPlan: null,
+        workReceipts: [],
+        operationIds: this.v4NaturalDiscussionOperationIds(
+          controller, slots, [kind], round,
+        ),
+        pendingKinds: nextKinds,
+        remainingKinds,
+        sessionPolicy: null,
+        resumedGate: input.resumedGate,
+        disableDeliveryPrompt: true,
+        promptBuilder: ({ kind, transcript }) => this.v4NaturalPhasePrompt(
+          group, kind, 'discussion', snapshot, receiptRecords, activeKinds, {
+            runId: controller.runId,
+            transcript: transcript ?? this.v4NaturalThreadTranscript(group, threadRootId, { controller }),
+            skillHints: context.rootSkillsByKind.get(kind) || [],
+            knowledgeBaseHints: context.rootKnowledgeBasesByKind.get(kind) || [],
+            allowRouting: true,
+            writerKind: turnWriterKind,
+            consensusText: this.v4NaturalConsensusPrompt(group, controller, threadRootId),
+          },
+        ),
+      })
+      slots = dispatch.slots || slots
+      if (!dispatch.ok) {
+        if (controller.signal.aborted) return terminalRunStatusForReason(controller.stopReason)
+        const failedKinds = removePhaseFailures(dispatch)
+        activeKinds = activeKinds.filter(kind => !failedKinds.includes(kind))
+        if (!activeKinds.length) return dispatch.phasePendingMessages?.length ? 'partial' : 'failed'
+      }
+      if (this.v4NaturalStopRepeatingDiscussion(
+        group, controller, threadRootId, round, activeKinds,
+      )) return 'partial'
+      const outcome = await this.v4NaturalAgentLedOutcome(group, controller, threadRootId, round, activeKinds)
+      if (outcome.status) return outcome.status
+      // A new candidate starts its own confirmation queue. An objection
+      // cancels pending approvals; otherwise preserve outstanding invitations.
+      nextKinds = this.v4NaturalConsensus(group, controller, threadRootId) || candidate
+        ? outcome.nextKinds
+        : [...new Set([...outcome.nextKinds, ...remainingKinds])]
+      nextKinds = nextKinds.filter(agentKind => activeKinds.includes(agentKind))
+      if (!nextKinds.length) nextKinds = [outcome.fallbackKind || activeKinds[0]]
+      if (!controller.unlimitedRounds && round >= (controller.maxRounds || 6)) {
+        addRoundLimitNotice()
+        return 'round-limit'
+      }
+      round += 1
+      controller.currentRound = round
+    }
+    return terminalRunStatusForReason(controller.stopReason)
+  },
+
+  async runV4NaturalDiscussion(group, controller, threadRootId, context, input) {
+    if (input.resume && ['proposal', 'discussion'].includes(controller.orchestration?.phase)) {
+      for (const slot of input.slots) {
+        if (slot.permission !== 'workspace-write' || !slot.agentRunId
+            || slot.commitStatus === 'committed'
+            || !['running', 'waiting', 'stopped', 'failed'].includes(slot.status)) continue
+        if (this.v4NaturalRecoveredPhaseResult(group, controller, threadRootId,
+          controller.orchestration.phase, slot.agentKind, slot)) continue
+        if (input.resumedGate?.operationId === slot.operationId
+            && input.resumedGate.agentKind === slot.agentKind
+            && input.resumedGate.status === 'approved') continue
+        if (!this.requestHumanGate) throw new Error('LOCAL_RUN_RETRY_GATE_INVALID')
+        const binding = {
+          agentRunId: slot.agentRunId, agentKind: slot.agentKind,
+          round: controller.currentRound, phase: controller.orchestration.phase, slotId: slot.slotId,
+          operationId: slot.operationId, snapshotHash: input.snapshotHash,
+        }
+        const request = {
+          phase: 'discussion-writer-recovery', batchId: input.batchId,
+          slotId: slot.slotId, operationId: slot.operationId, attempt: slot.attempt,
+          outcomeCertainty: 'unknown_outcome', sideEffectsPossible: true,
+        }
+        const gate = await this.requestHumanGate({
+          type: 'retry', runId: controller.runId, agentRunId: slot.agentRunId,
+          agentKind: slot.agentKind,
+          summary: 'The interrupted Agent may already have changed the workspace.',
+          options: [
+            { optionId: 'retry-once', name: 'Retry once', kind: 'allow_once' },
+            { optionId: 'cancel-retry', name: 'Do not retry', kind: 'reject_once' },
+          ],
+          request,
+        }, {
+          signal: controller.signal,
+          preserveOnAbort: () => controller.stopReason === 'shutdown',
+          continuation: { resumeKind: 'agent_slot', ...binding },
+        })
+        if (gate.status !== 'approved') {
+          if (this.completeHumanGateContinuation?.(controller.runId, gate.gateId, 'cancelled') !== true
+              && this.hasRunLedger()) throw new Error('LOCAL_RUN_PERSIST_FAILED')
+          controller.stopReason = 'human_gate_rejected'
+          return 'stopped'
+        }
+        if (gate.optionId !== 'retry-once') throw new Error('LOCAL_RUN_CONTINUATION_INVALID')
+        if (this.completeHumanGateContinuation?.(controller.runId, gate.gateId, 'completed') !== true
+            && this.hasRunLedger()) throw new Error('LOCAL_RUN_PERSIST_FAILED')
+        input.resumedGate = { ...binding, gateId: gate.gateId, type: 'retry',
+          status: gate.status, optionId: gate.optionId, request, used: true }
+      }
+    }
+    if (input.resumedGate?.type === 'retry'
+        && input.resumedGate.request?.phase === 'discussion-writer-recovery') {
+      const gate = input.resumedGate
+      const slot = input.slots.find(item => item.slotId === gate.slotId)
+      if (gate.status !== 'approved' || gate.optionId !== 'retry-once'
+          || !slot || slot.agentKind !== gate.agentKind
+          || slot.operationId !== gate.operationId
+          || slot.snapshotHash !== gate.snapshotHash
+          || slot.attempt !== gate.request.attempt) throw new Error('LOCAL_RUN_CONTINUATION_INVALID')
+      if (!gate.used && this.completeHumanGateContinuation?.(controller.runId, gate.gateId, 'completed') !== true
+          && this.hasRunLedger()) throw new Error('LOCAL_RUN_PERSIST_FAILED')
+    }
+    const style = controller.orchestration?.discussionStyle
+      || controller.discussionStyle
+      || 'sequential'
+    return style === 'agent-led'
+      ? this.runV4AgentLedDiscussion(group, controller, threadRootId, context, input)
+      : this.runV4SequentialDiscussion(group, controller, threadRootId, context, input)
+  },
+}
+
+module.exports = { naturalDiscussionMethods }

desktop/src/workspace/local-workspace-auto-runner-recovery.cjs

@@ -0,0 +1,443 @@
+// Failed, interrupted and unauthorized invocations: retry policy, pausing an Agent for the run, and recovery prompts.
+const { createHash } = require('node:crypto')
+const {
+  MAX_RUN_AGENT_ATTEMPTS,
+  boundedBackoffDelay,
+  normalizeAttemptHistoryEntry,
+  normalizeFailure,
+  normalizeFailureOutcome,
+  retryDecision,
+} = require('../runs/failure-policy.cjs')
+const {
+  circuitBreakerError,
+  sanitizedAuthenticationError,
+  unauthorizedFailure,
+} = require('./local-workspace-auto-runner-support.cjs')
+
+const recoveryMethods = {
+  setCurrentAgent(controller, kind) {
+    controller.currentKind = kind
+    controller.progress = []
+    this.emitChanged()
+  },
+
+  pauseFailedAgentForRun(group, controller, kind, threadRootId, error = null) {
+    // Failures are scoped to the current run. Group membership is user
+    // configuration: editing it after a provider or login hiccup made the
+    // Agent disappear from every later conversation turn, and removing the
+    // last member made the whole group (and its history) unloadable.
+    if (group.conversationType === 'direct' || !group.agentKinds.includes(kind)) return false
+    if (!controller.failedKinds.includes(kind)) controller.failedKinds.push(kind)
+    const alreadyReported = this.state().messages.some(message => (
+      message.threadRootId === threadRootId
+        && message.agentKind === kind
+        && message.system?.key === 'system.agentPausedAfterFailure'
+        && message.system?.params?.runId === controller.runId
+    ))
+    if (!alreadyReported) {
+      const agent = this.agentLabel(kind)
+      const reason = normalizeFailure(error).code || 'LOCAL_AGENT_PROCESS_FAILED'
+      this.addMessage(
+        group.id,
+        'system',
+        `${agent} is paused for the rest of this discussion (${reason}). It stays in the group and will be tried again on the next message.`,
+        kind,
+        threadRootId,
+        {
+          key: 'system.agentPausedAfterFailure',
+          params: { agent, reason, runId: controller.runId },
+        },
+      )
+    }
+    return true
+  },
+
+  shouldPauseFailedAgent(error) {
+    const category = normalizeFailure(error).category
+    // Runtime, provider, rate-limit, protocol, and timeout failures stay
+    // silent run-scoped exclusions; their own failure message explains them.
+    // Authentication and compatibility failures get an explicit notice
+    // because the user usually has to act (sign in or update the CLI).
+    return ['authentication', 'compatibility'].includes(category)
+  },
+
+  replacementInstruction(failedKind) {
+    return [
+      `You are replacing ${this.agentLabel(failedKind)} for this turn.`,
+      'Complete the interrupted Agent slot using the shared task context, then return your own conclusion.',
+      'Do not claim that the interrupted Agent completed this work.',
+    ].join('\n')
+  },
+
+  retryDelay(failedAttempt) {
+    return boundedBackoffDelay(failedAttempt, {
+      baseDelayMs: this.retryBaseDelayMs,
+      maxDelayMs: this.retryMaxDelayMs,
+    })
+  },
+
+  operationIdFor(controller, kind, mode) {
+    const digest = createHash('sha256').update(JSON.stringify({
+      runId: controller.runId,
+      kind,
+      mode,
+      round: controller.currentRound || 0,
+    })).digest('hex')
+    return `agent-operation-${digest}`
+  },
+
+  recordAttempt(group, controller, input) {
+    const history = Array.isArray(controller.attemptHistory) ? controller.attemptHistory : []
+    const previousSequence = history.at(-1)?.sequence || 0
+    const entry = normalizeAttemptHistoryEntry({
+      sequence: previousSequence + 1,
+      agentKind: input.agentKind,
+      phase: input.phase,
+      attempt: input.attempt,
+      failureCategory: input.failureCategory ?? null,
+      policyAction: input.policyAction,
+      backoffMs: input.backoffMs || 0,
+      recoveryAgentKind: input.recoveryAgentKind || '',
+      finalOutcome: input.finalOutcome,
+      timestamp: Date.now(),
+      ...(input.outcomeCertainty ? { outcomeCertainty: input.outcomeCertainty } : {}),
+      ...(Object.hasOwn(input, 'sideEffectsPossible')
+        ? { sideEffectsPossible: input.sideEffectsPossible }
+        : {}),
+      ...(input.operationId ? { operationId: input.operationId } : {}),
+      ...(input.idempotencyMode ? { idempotencyMode: input.idempotencyMode } : {}),
+    })
+    if (!entry) throw new Error('LOCAL_RUN_ATTEMPT_INVALID')
+    controller.attemptHistory = [...history, entry].slice(-256)
+    const persisted = this.checkpointRun?.(group.id, controller)
+    if (this.hasRunLedger() && persisted !== true) {
+      throw new Error('LOCAL_RUN_PERSIST_FAILED')
+    }
+    return entry
+  },
+
+  async prepareRetry(group, kind, controller, failedAttempt, options = {}) {
+    if (options.resetSession === true) {
+      this.resetAgentSession(group, kind, true, controller.taskId)
+    }
+    this.markRuntimeCredential(kind, 'unknown')
+    try { await this.refreshAgents() } catch {
+      if (controller.signal.aborted) throw new Error('LOCAL_AGENT_EXECUTION_STOPPED')
+    }
+    const delayMs = Number.isFinite(options.delayMs)
+      ? Math.max(0, Math.floor(options.delayMs))
+      : this.retryDelay(failedAttempt)
+    await this.sleep(delayMs, controller.signal)
+    return delayMs
+  },
+
+  async invokeTransiently(invokeSource, group, kind, controller, options = {}) {
+    const operationId = options.operationId
+    const idempotencyMode = options.idempotencyMode === 'durable' ? 'durable' : 'none'
+    const sideEffectsPossible = options.sideEffectsPossible === true
+    for (let attempt = 1; ; attempt += 1) {
+      if (controller.attemptHistory.length >= MAX_RUN_AGENT_ATTEMPTS) {
+        throw circuitBreakerError()
+      }
+      const phase = attempt === 1 ? (options.phase || 'initial') : 'transient_retry'
+      const phaseAttempt = attempt === 1 ? (options.attempt || 1) : attempt - 1
+      try {
+        const result = await invokeSource()
+        this.recordAttempt(group, controller, {
+          agentKind: options.agentKind || kind,
+          phase,
+          attempt: phaseAttempt,
+          failureCategory: null,
+          policyAction: options.successAction || 'complete',
+          backoffMs: options.successBackoffMs || 0,
+          recoveryAgentKind: options.recoveryAgentKind || '',
+          finalOutcome: 'succeeded',
+          sideEffectsPossible,
+          operationId,
+          idempotencyMode,
+        })
+        return result
+      } catch (error) {
+        if (controller.signal.aborted) {
+          this.recordAttempt(group, controller, {
+            agentKind: options.agentKind || kind,
+            phase,
+            attempt: phaseAttempt,
+            failureCategory: 'cancellation',
+            policyAction: 'cancel',
+            recoveryAgentKind: options.recoveryAgentKind || '',
+            finalOutcome: 'cancelled',
+          })
+          throw error
+        }
+        if (unauthorizedFailure(error)) throw error
+        const failure = normalizeFailure(error)
+        const safety = normalizeFailureOutcome(error, {
+          category: failure.category,
+          sideEffectsPossible,
+          operationId,
+          idempotencyMode,
+        })
+        if (failure.category === 'cancellation') throw error
+        if (options.deferFailurePolicy === true) {
+          this.recordAttempt(group, controller, {
+            agentKind: options.agentKind || kind,
+            phase,
+            attempt: phaseAttempt,
+            failureCategory: failure.category,
+            policyAction: 'fail',
+            backoffMs: 0,
+            recoveryAgentKind: '',
+            finalOutcome: 'failed',
+            ...safety,
+          })
+          throw error
+        }
+        // Session recovery is owned by LocalWorkspaceAgentInvocation so a stale
+        // native Session gets exactly one fresh attempt across every run mode.
+        // An ambiguous refusal (HTTP 403, proxy or region block) gets exactly
+        // one more attempt: a transient gateway refusal recovers, while a real
+        // permission problem fails fast without signing the Agent out.
+        const maxAttempts = failure.category === 'timeout' && options.retryTimeouts !== true
+          ? 1
+          : failure.code === 'LOCAL_AGENT_ACCESS_DENIED' ? 2 : 4
+        const decision = retryDecision(failure, {
+          attempt,
+          maxAttempts,
+          baseDelayMs: this.retryBaseDelayMs,
+          maxDelayMs: this.retryMaxDelayMs,
+          rateLimitMinDelayMs: this.retryRateLimitMinDelayMs,
+          safety,
+        })
+        if (decision.action === 'human_gate') {
+          this.recordAttempt(group, controller, {
+            agentKind: options.agentKind || kind,
+            phase,
+            attempt: phaseAttempt,
+            failureCategory: failure.category,
+            policyAction: 'human_gate',
+            backoffMs: decision.delayMs,
+            recoveryAgentKind: options.recoveryAgentKind || '',
+            finalOutcome: 'failed',
+            ...safety,
+          })
+          if (!this.requestHumanGate || !error?.runTrace?.agentRunId) {
+            throw new Error('LOCAL_RUN_RETRY_GATE_INVALID')
+          }
+          const gate = await this.requestHumanGate({
+            type: 'retry',
+            runId: controller.runId,
+            agentRunId: error.runTrace.agentRunId,
+            agentKind: options.agentKind || kind,
+            summary: 'The previous write-capable Agent attempt may already have changed the workspace.',
+            options: [
+              { optionId: 'retry-once', name: 'Retry once', kind: 'allow_once' },
+              { optionId: 'cancel-retry', name: 'Do not retry', kind: 'reject_once' },
+            ],
+            request: {
+              failureCategory: failure.category,
+              outcomeCertainty: safety.outcomeCertainty,
+              sideEffectsPossible: safety.sideEffectsPossible,
+              operationId: safety.operationId,
+              idempotencyMode: safety.idempotencyMode,
+            },
+          }, {
+            signal: controller.signal,
+            preserveOnAbort: () => controller.stopReason === 'shutdown',
+            continuation: {
+              resumeKind: 'agent_slot',
+              agentRunId: error.runTrace.agentRunId,
+              agentKind: options.agentKind || kind,
+              round: controller.currentRound || 0,
+              ...(options.v4AgentSlotBinding || {}),
+            },
+          })
+          if (gate.status !== 'approved') {
+            this.completeHumanGateContinuation?.(controller.runId, gate.gateId, 'cancelled')
+            controller.stopReason = 'human_gate_rejected'
+            controller.abort()
+            throw new Error('LOCAL_AGENT_EXECUTION_STOPPED')
+          }
+          if (this.completeHumanGateContinuation?.(
+            controller.runId, gate.gateId, 'completed',
+          ) !== true && this.hasRunLedger()) {
+            throw new Error('LOCAL_RUN_PERSIST_FAILED')
+          }
+          this.markRuntimeCredential(kind, 'unknown')
+          try { await this.refreshAgents() } catch {
+            if (controller.signal.aborted) throw new Error('LOCAL_AGENT_EXECUTION_STOPPED')
+          }
+          await this.sleep(decision.delayMs, controller.signal)
+          continue
+        }
+        if (decision.action !== 'retry') {
+          this.recordAttempt(group, controller, {
+            agentKind: options.agentKind || kind,
+            phase,
+            attempt: phaseAttempt,
+            failureCategory: failure.category,
+            policyAction: options.failureAction
+              || (decision.action === 'refresh_session' ? 'refresh_session' : 'fail'),
+            backoffMs: options.failureBackoffMs || 0,
+            recoveryAgentKind: options.recoveryAgentKind || '',
+            finalOutcome: 'failed',
+            ...safety,
+          })
+          throw error
+        }
+        this.recordAttempt(group, controller, {
+          agentKind: options.agentKind || kind,
+          phase,
+          attempt: phaseAttempt,
+          failureCategory: failure.category,
+          policyAction: 'retry',
+          backoffMs: decision.delayMs,
+          recoveryAgentKind: options.recoveryAgentKind || '',
+          finalOutcome: 'failed',
+          ...safety,
+        })
+        // Transient retries keep the Agent's readiness untouched. Refreshing
+        // the whole catalog here re-ran discovery and credential probes while
+        // the Agent was busy and could flip a healthy Agent to unavailable.
+        await this.sleep(decision.delayMs, controller.signal)
+      }
+    }
+  },
+
+  async controlAfterFailure(group, kind, controller, error) {
+    const request = this.consumeAgentControl(controller, kind)
+    if (!request) return null
+    const failure = normalizeFailure(error)
+    const manualAttempt = (controller.manualRetryCounts.get(kind) || 0) + 1
+    if (request.action === 'retry') {
+      controller.manualRetryCounts.set(kind, manualAttempt)
+      const delayMs = this.retryDelay(manualAttempt)
+      this.recordAttempt(group, controller, {
+        agentKind: kind,
+        phase: 'manual_retry',
+        attempt: manualAttempt,
+        failureCategory: failure.category,
+        policyAction: 'retry',
+        backoffMs: delayMs,
+        finalOutcome: 'failed',
+      })
+      await this.prepareRetry(group, kind, controller, manualAttempt, {
+        resetSession: true,
+        delayMs,
+      })
+      return { action: 'retry' }
+    }
+    this.recordAttempt(group, controller, {
+      agentKind: kind,
+      phase: 'manual_retry',
+      attempt: manualAttempt,
+      failureCategory: failure.category,
+      policyAction: request.action === 'replace' ? 'replace_agent' : 'cancel',
+      recoveryAgentKind: request.replacementKind || '',
+      finalOutcome: request.action === 'replace' ? 'replaced' : 'cancelled',
+    })
+    return request
+  },
+
+  async invokeWithUnauthorizedRecovery(input) {
+    const { controller, kind } = input
+    if (controller.attemptHistory.length >= MAX_RUN_AGENT_ATTEMPTS) {
+      throw circuitBreakerError()
+    }
+    if (controller.agentSlotKinds.has(kind)) {
+      throw new Error('LOCAL_AGENT_ATTEMPT_RUNNING')
+    }
+    controller.agentSlotKinds.add(kind)
+    try {
+      return await this.invokeWithUnauthorizedRecoveryInSlot(input)
+    } finally {
+      controller.agentSlotKinds.delete(kind)
+    }
+  },
+
+  async invokeWithUnauthorizedRecoveryInSlot({
+    group,
+    kind,
+    controller,
+    threadRootId,
+    context,
+    mode = 'auto',
+  }) {
+    const requestedOperationId = String(context?.operationId || '')
+    const operationId = /^[A-Za-z0-9._:-]{1,120}$/.test(requestedOperationId)
+      ? requestedOperationId
+      : this.operationIdFor(controller, kind, mode)
+    const contract = this.retryContract(kind) || {}
+    const idempotencyMode = contract.idempotencyMode === 'durable' ? 'durable' : 'none'
+    const sideEffectsPossible = group.allowWrite === true
+      && context.permissionMode !== 'read-only'
+    const invokeSource = async () => {
+      if (context.parallelGraph !== true) this.setCurrentAgent(controller, kind)
+      return this.invokeAgent(group, kind, mode, controller.signal, threadRootId, {
+        ...context,
+        yolo: context.yolo ?? this.defaultYolo,
+        deferCredentialFailure: true,
+        operationId,
+      })
+    }
+    let phase = 'initial'
+    let phaseAttempt = 1
+    while (true) {
+      try {
+        return {
+          result: await this.invokeTransiently(invokeSource, group, kind, controller, {
+            phase,
+            attempt: phaseAttempt,
+            operationId,
+            idempotencyMode,
+            sideEffectsPossible,
+            deferFailurePolicy: context.v4SynthesisRecovery === true
+              || (context.v4 === true && context.resumedGate?.type === 'permission'),
+            // A timed-out automatic slot is a failed participant for this
+            // round. Retrying it serially delays every healthy peer and
+            // defeats failure isolation; manual/direct invocations retain
+            // their existing timeout retry policy.
+            retryTimeouts: mode !== 'auto',
+            v4AgentSlotBinding: mode === 'auto' && context.v4 === true ? {
+              phase: context.phase,
+              slotId: context.slotId,
+              operationId,
+              snapshotHash: context.snapshotHash,
+            } : null,
+          }),
+          removed: false,
+        }
+      } catch (error) {
+        if (controller.signal.aborted) throw error
+        const control = await this.controlAfterFailure(group, kind, controller, error)
+        if (control?.action === 'retry') {
+          phase = 'manual_retry'
+          phaseAttempt = controller.manualRetryCounts.get(kind) || 1
+          continue
+        }
+        if (control) return { result: null, removed: false, control, error }
+        if (!unauthorizedFailure(error)) throw error
+        // Only explicit sign-in failures reach this point. Mark the Agent as
+        // needing a fresh login; the catalog clears it on the next refresh
+        // after the retry window or as soon as native credentials verify.
+        this.markRuntimeCredential(kind, 'missing')
+        this.recordAttempt(group, controller, {
+          agentKind: kind,
+          phase,
+          attempt: phaseAttempt,
+          failureCategory: 'authentication',
+          policyAction: 'fail',
+          finalOutcome: 'failed',
+          ...normalizeFailureOutcome(error, {
+            sideEffectsPossible: group.allowWrite === true,
+            operationId,
+            idempotencyMode,
+          }),
+        })
+        throw sanitizedAuthenticationError(error)
+      }
+    }
+  },
+}
+
+module.exports = { recoveryMethods }

desktop/src/workspace/local-workspace-auto-runner-rounds.cjs

@@ -0,0 +1,313 @@
+// V2 round-based runs. Kept so older runs can be resumed; new runs do not use it.
+const { MAX_RUN_AGENT_ATTEMPTS } = require('../runs/failure-policy.cjs')
+const {
+  circuitBreakerError,
+  circuitBreakerFailure,
+  hardBudgetFailure,
+  terminalRunStatusForReason,
+} = require('./local-workspace-auto-runner-support.cjs')
+
+const roundsMethods = {
+  async runRounds(group, controller, threadRootId, maxRounds, context, resume = false) {
+    const {
+      rootAttachments,
+      rootSkillsByKind,
+      rootKnowledgeBasesByKind,
+    } = context
+    const cursor = resume ? controller.orchestration : null
+    const attachmentRecipients = new Set(cursor?.attachmentRecipients || [])
+    let terminalFailureOccurred = cursor?.terminalFailureOccurred === true
+    let activeKinds = cursor ? [...cursor.activeKinds] : [...controller.targetKinds]
+    let executionSequence = Number(cursor?.executionSequence) || 0
+    let totalSuccesses = cursor?.totalSuccesses || 0
+    let consensusReached = false
+    const reportedFailures = new Set()
+    const firstRound = resume ? Math.max(0, controller.currentRound - 1) : 0
+
+    for (
+      let round = firstRound;
+      (controller.unlimitedRounds || round < maxRounds) && !controller.signal.aborted;
+      round += 1
+    ) {
+      const resumedRound = resume && round === firstRound
+      const successfulKinds = new Set(resumedRound ? cursor.successfulKinds : [])
+      const agreementKinds = new Set(resumedRound ? cursor.agreementKinds : [])
+      const replacementInstructions = new Map()
+      const roundQueue = resumedRound ? [...cursor.pendingKinds] : [...activeKinds]
+      controller.currentRound = round + 1
+      controller.completedKinds = resumedRound
+        ? activeKinds.filter(kind => !roundQueue.includes(kind))
+        : []
+      controller.failedKinds = resumedRound
+        ? controller.completedKinds.filter(kind => !successfulKinds.has(kind))
+        : []
+      if (!resumedRound) {
+        this.checkpointOrchestration(group, controller, {
+          currentKind: '',
+          pendingKinds: [...roundQueue],
+          activeKinds: [...activeKinds],
+          successfulKinds: [],
+          agreementKinds: [],
+          attachmentRecipients: [...attachmentRecipients],
+          totalSuccesses,
+          terminalFailureOccurred,
+          executionSequence,
+        })
+      }
+      this.emitChanged()
+
+      while (roundQueue.length) {
+        const kind = roundQueue.shift()
+        if (!activeKinds.includes(kind)) {
+          this.checkpointOrchestration(group, controller, { pendingKinds: [...roundQueue] })
+          continue
+        }
+        if (controller.signal.aborted) break
+        const executionKind = kind
+        executionSequence += 1
+        this.setCurrentAgent(controller, executionKind)
+        this.checkpointOrchestration(group, controller, {
+          currentKind: executionKind,
+          pendingKinds: [...roundQueue],
+          activeKinds: [...activeKinds],
+          successfulKinds: [...successfulKinds],
+          agreementKinds: [...agreementKinds],
+          attachmentRecipients: [...attachmentRecipients],
+          totalSuccesses,
+          terminalFailureOccurred,
+          executionSequence,
+        })
+        try {
+          if (controller.attemptHistory.length >= MAX_RUN_AGENT_ATTEMPTS) {
+            throw circuitBreakerError()
+          }
+          const collaborationPackage = this.prepareCollaborationPackage(
+            group, controller, activeKinds, executionKind, threadRootId,
+          )
+          const attachments = attachmentRecipients.has(executionKind)
+            ? []
+            : rootAttachments.map(attachment => attachment.path)
+          const invocation = await this.invokeWithUnauthorizedRecovery({
+            group,
+            kind: executionKind,
+            controller,
+            activeKinds,
+            threadRootId,
+            context: {
+              attachments,
+              attachmentSnapshots: attachments.length ? rootAttachments : [],
+              skillHints: rootSkillsByKind.get(executionKind) || [],
+              knowledgeBaseHints: rootKnowledgeBasesByKind.get(executionKind) || [],
+              runtimeInstruction: replacementInstructions.get(executionKind) || '',
+              collaborationPackage,
+              contextOptions: {
+                focusUserMessageId: threadRootId,
+                omitAgentThreadRootId: threadRootId,
+              },
+              executionSequence,
+            },
+            reportedFailures,
+          })
+          replacementInstructions.delete(executionKind)
+          if (invocation.control?.action === 'replace') {
+            this.recordAgentInterruption(
+              group.id, executionKind, invocation.error, threadRootId, 'stopped', reportedFailures,
+            )
+            if (!controller.failedKinds.includes(executionKind)) {
+              controller.failedKinds.push(executionKind)
+            }
+            if (!controller.completedKinds.includes(executionKind)) {
+              controller.completedKinds.push(executionKind)
+            }
+            successfulKinds.delete(executionKind)
+            agreementKinds.delete(executionKind)
+            const replacementKind = invocation.control.replacementKind
+            activeKinds = activeKinds.filter(activeKind => activeKind !== executionKind)
+            replacementInstructions.set(
+              replacementKind,
+              this.replacementInstruction(executionKind),
+            )
+            if (!roundQueue.includes(replacementKind)) roundQueue.unshift(replacementKind)
+            controller.currentKind = ''
+            controller.progress = []
+            this.checkpointOrchestration(group, controller, {
+              currentKind: '',
+              pendingKinds: [...roundQueue],
+              activeKinds: [...activeKinds],
+              successfulKinds: [...successfulKinds],
+              agreementKinds: [...agreementKinds],
+            })
+            this.emitChanged()
+            continue
+          }
+          if (invocation.control?.action === 'cancel') {
+            this.recordAgentInterruption(
+              group.id, executionKind, invocation.error, threadRootId, 'stopped', reportedFailures,
+            )
+            if (!controller.failedKinds.includes(executionKind)) {
+              controller.failedKinds.push(executionKind)
+            }
+            if (!controller.completedKinds.includes(executionKind)) {
+              controller.completedKinds.push(executionKind)
+            }
+            successfulKinds.delete(executionKind)
+            agreementKinds.delete(executionKind)
+            controller.currentKind = ''
+            controller.progress = []
+            this.checkpointOrchestration(group, controller, {
+              currentKind: '',
+              pendingKinds: [...roundQueue],
+              successfulKinds: [...successfulKinds],
+              agreementKinds: [...agreementKinds],
+            })
+            this.emitChanged()
+            continue
+          }
+          const result = invocation.result
+          if (attachments.length) attachmentRecipients.add(executionKind)
+          successfulKinds.add(executionKind)
+          if (result.consensus) agreementKinds.add(executionKind)
+          else agreementKinds.delete(executionKind)
+          this.recordCollaborationResult(
+            group, controller, activeKinds, executionKind, result,
+          )
+        } catch (error) {
+          if (circuitBreakerFailure(error)) {
+            controller.stopReason = 'circuit_breaker'
+            controller.abort()
+            break
+          }
+          const hardBudget = hardBudgetFailure(error)
+          if (hardBudget) {
+            this.recordAgentFailure(
+              group.id, executionKind, error, threadRootId, reportedFailures,
+            )
+            successfulKinds.delete(executionKind)
+            agreementKinds.delete(executionKind)
+            if (!controller.failedKinds.includes(executionKind)) {
+              controller.failedKinds.push(executionKind)
+            }
+            if (!controller.completedKinds.includes(executionKind)) {
+              controller.completedKinds.push(executionKind)
+            }
+            terminalFailureOccurred = true
+            controller.stopReason = 'hard_budget'
+            controller.abort()
+            break
+          }
+          if (controller.signal.aborted) {
+            const interruptedKind = controller.currentKind || executionKind
+            if (error?.runTrace) {
+              this.recordAgentInterruption(
+                group.id,
+                interruptedKind,
+                error,
+                threadRootId,
+                controller.stopReason === 'shutdown' ? 'interrupted' : 'stopped',
+                reportedFailures,
+              )
+              if (!controller.completedKinds.includes(interruptedKind)) {
+                controller.completedKinds.push(interruptedKind)
+              }
+              controller.currentKind = ''
+              controller.progress = []
+              this.emitChanged()
+            }
+            break
+          }
+          this.recordAgentFailure(
+            group.id, executionKind, error, threadRootId, reportedFailures,
+          )
+          successfulKinds.delete(executionKind)
+          agreementKinds.delete(executionKind)
+          if (!controller.failedKinds.includes(executionKind)) {
+            controller.failedKinds.push(executionKind)
+          }
+          terminalFailureOccurred = true
+          // Failed CLIs leave only this run's active queue; the configured
+          // group keeps them so the next turn can retry.
+          if (this.shouldPauseFailedAgent(error)) {
+            this.pauseFailedAgentForRun(group, controller, executionKind, threadRootId, error)
+          }
+          activeKinds = activeKinds.filter(activeKind => activeKind !== executionKind)
+        }
+        if (controller.signal.aborted) break
+        if (!controller.completedKinds.includes(executionKind)) {
+          controller.completedKinds.push(executionKind)
+        }
+        controller.currentKind = ''
+        controller.progress = []
+        this.checkpointOrchestration(group, controller, {
+          currentKind: '',
+          pendingKinds: [...roundQueue],
+          activeKinds: [...activeKinds],
+          successfulKinds: [...successfulKinds],
+          agreementKinds: [...agreementKinds],
+          attachmentRecipients: [...attachmentRecipients],
+          totalSuccesses,
+          terminalFailureOccurred,
+          executionSequence,
+        })
+        this.emitChanged()
+      }
+
+      if (controller.signal.aborted) break
+      const successes = activeKinds.filter(kind => successfulKinds.has(kind)).length
+      const agreements = activeKinds.filter(kind => agreementKinds.has(kind)).length
+      totalSuccesses += successes
+      this.checkpointOrchestration(group, controller, {
+        currentKind: '',
+        pendingKinds: [],
+        activeKinds: [...activeKinds],
+        successfulKinds: [...successfulKinds],
+        agreementKinds: [...agreementKinds],
+        attachmentRecipients: [...attachmentRecipients],
+        totalSuccesses,
+        terminalFailureOccurred,
+        executionSequence,
+      })
+      if (activeKinds.length < 2) break
+      const crossReviewComplete = !controller.unlimitedRounds || controller.currentRound >= 2
+      if (crossReviewComplete
+          && successes === activeKinds.length
+          && agreements === activeKinds.length) {
+        consensusReached = true
+        break
+      }
+    }
+
+    let runStatus
+    if (controller.signal.aborted) {
+      runStatus = terminalRunStatusForReason(controller.stopReason)
+    } else if (terminalFailureOccurred) runStatus = totalSuccesses > 0 ? 'partial' : 'failed'
+    else if (consensusReached) runStatus = 'completed'
+    else runStatus = totalSuccesses > 0 ? 'round-limit' : 'failed'
+    if (!terminalFailureOccurred && !controller.unlimitedRounds
+        && (runStatus === 'round-limit' || runStatus === 'failed')) {
+      this.addMessage(
+        group.id,
+        'system',
+        `Automatic discussion reached its ${maxRounds}-round limit. The latest replies above are the current result.`,
+        '',
+        threadRootId,
+        { key: 'system.autoRoundLimit', params: { rounds: maxRounds } },
+      )
+    }
+    if (controller.stopReason === 'circuit_breaker') {
+      this.addMessage(
+        group.id,
+        'system',
+        `Automatic discussion stopped after ${MAX_RUN_AGENT_ATTEMPTS} Agent attempts.`,
+        '',
+        threadRootId,
+        {
+          key: 'system.runCircuitBreaker',
+          params: { maxAttempts: MAX_RUN_AGENT_ATTEMPTS },
+        },
+      )
+    }
+    return runStatus
+  },
+}
+
+module.exports = { roundsMethods }

desktop/src/workspace/local-workspace-auto-runner-support.cjs

@@ -0,0 +1,100 @@
+const { terminalRunStatusForReason } = require('./local-workspace-inputs.cjs')
+const {
+  normalizeFailure,
+} = require('../runs/failure-policy.cjs')
+
+function authenticationFailureText(error) {
+  return [
+    error?.diagnostic,
+    error?.message,
+    error?.cause?.diagnostic,
+    error?.cause?.message,
+  ].filter(Boolean).join('\n')
+}
+
+function unauthorizedFailure(error) {
+  return normalizeFailure(error).category === 'authentication'
+}
+
+function hardBudgetFailure(error) {
+  return error?.code === 'LOCAL_BUDGET_EXHAUSTED'
+    || error?.message === 'LOCAL_BUDGET_EXHAUSTED'
+}
+
+function circuitBreakerFailure(error) {
+  return error?.code === 'LOCAL_RUN_CIRCUIT_BREAKER'
+    || error?.message === 'LOCAL_RUN_CIRCUIT_BREAKER'
+}
+
+function circuitBreakerError() {
+  return Object.assign(new Error('LOCAL_RUN_CIRCUIT_BREAKER'), {
+    code: 'LOCAL_RUN_CIRCUIT_BREAKER',
+  })
+}
+
+function authenticationFailureStatus(error) {
+  const status = normalizeFailure(error).httpStatus
+  if ([401, 403].includes(status)) return status
+  const message = authenticationFailureText(error)
+  if (/(?:\bHTTP\s*)?\b403\b|forbidden/i.test(message)) return 403
+  return 401
+}
+
+function sanitizedAuthenticationError(error) {
+  const statusCode = authenticationFailureStatus(error)
+  const sanitized = Object.assign(
+    new Error(`HTTP ${statusCode}; authentication failed; Agent retained`),
+    {
+      code: 'LOCAL_AGENT_AUTH_REQUIRED',
+      statusCode,
+      failure: Object.freeze({
+        code: 'LOCAL_AGENT_AUTH_REQUIRED',
+        category: 'authentication',
+        retryable: false,
+      }),
+    },
+  )
+  if (error?.runTrace) {
+    Object.defineProperty(sanitized, 'runTrace', {
+      value: error.runTrace,
+      enumerable: false,
+      configurable: true,
+    })
+  }
+  return sanitized
+}
+
+function abortableDelay(delayMs, signal) {
+  if (!delayMs) return Promise.resolve()
+  if (signal?.aborted) return Promise.reject(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', abortHandler)
+      resolve()
+    }, delayMs)
+    const abortHandler = () => {
+      clearTimeout(timer)
+      reject(new Error('LOCAL_AGENT_EXECUTION_STOPPED'))
+    }
+    signal?.addEventListener('abort', abortHandler, { once: true })
+  })
+}
+
+function stalePermissionResumeFailure(error, resumedGate) {
+  const code = String(error?.code || error?.message || '')
+  return resumedGate?.type === 'permission'
+    && ['LOCAL_RUN_PERMISSION_RESUME_UNAVAILABLE', 'LOCAL_AGENT_SESSION_INVALID'].includes(code)
+}
+
+module.exports = {
+  abortableDelay,
+  authenticationFailureStatus,
+  authenticationFailureText,
+  circuitBreakerError,
+  circuitBreakerFailure,
+  hardBudgetFailure,
+  sanitizedAuthenticationError,
+  stalePermissionResumeFailure,
+  terminalRunStatusForReason,
+  unauthorizedFailure,
+}

desktop/src/workspace/local-workspace-auto-runner-task-graph.cjs

@@ -0,0 +1,419 @@
+// V3 task-graph runs. Kept so older runs can be resumed; new runs do not use it.
+const { createHash } = require('node:crypto')
+const {
+  appendBlackboardEntry,
+  emptyCollaborationState,
+  publicCollaborationText,
+} = require('../collaboration/collaboration-records.cjs')
+const { unlimitedReviewContract } = require('./local-workspace-context.cjs')
+const {
+  parseTaskGraphCursor,
+  readyTaskGraphNodes,
+  terminalTaskGraphState,
+  updateTaskGraphCursor,
+} = require('../collaboration/task-graph-records.cjs')
+const {
+  circuitBreakerFailure,
+  hardBudgetFailure,
+  terminalRunStatusForReason,
+} = require('./local-workspace-auto-runner-support.cjs')
+
+const taskGraphMethods = {
+  unresolvedTaskGraphConflicts(collaborationInput = null) {
+    const collaboration = collaborationInput || emptyCollaborationState()
+    const resolved = new Set(collaboration.entries
+      .filter(entry => entry.entryType === 'decision' && entry.lifecycle.state === 'active')
+      .flatMap(entry => entry.refs))
+    return collaboration.entries.filter(entry => (
+      entry.entryType === 'conflict'
+      && entry.lifecycle.state === 'active'
+      && !resolved.has(entry.entryId)
+    ))
+  },
+
+  taskGraphAcceptanceCriteria(node) {
+    const criteria = []
+    if (node.acceptance.requireConclusion) criteria.push('Return one concrete conclusion.')
+    if (node.acceptance.minArtifactRefs) {
+      criteria.push(`Produce at least ${node.acceptance.minArtifactRefs} durable Artifact reference(s).`)
+    }
+    if (node.acceptance.minEvidenceRefs) {
+      criteria.push(`Produce at least ${node.acceptance.minEvidenceRefs} durable Evidence reference(s).`)
+    }
+    return criteria.length ? criteria : ['Complete the explicit Human decision.']
+  },
+
+  taskGraphSelectedEntryIds(controller, node) {
+    const cursor = parseTaskGraphCursor(controller.orchestration.taskGraph)
+    const states = new Map(cursor.nodeStates.map(state => [state.nodeId, state]))
+    const selected = node.inputNodeIds.flatMap(nodeId => states.get(nodeId)?.entryIds || [])
+    if (['reviewer', 'arbiter'].includes(node.role)) {
+      selected.push(...this.unresolvedTaskGraphConflicts(
+        controller.orchestration.collaboration,
+      ).map(entry => entry.entryId))
+    }
+    return [...new Set(selected)]
+  },
+
+  taskGraphPrompt(node, objective, collaborationPackage, unlimitedRounds = false) {
+    return [
+      'MELDWORK_TASK_GRAPH_V1',
+      `Node: ${node.nodeId}`,
+      `Role: ${node.role}`,
+      `Objective: ${objective}`,
+      `Expected output: ${node.expectedOutput}`,
+      `Acceptance criteria: ${this.taskGraphAcceptanceCriteria(node).join(' | ')}`,
+      unlimitedReviewContract(unlimitedRounds),
+      collaborationPackage.text,
+      'Return the requested result directly. Completion is evaluated from durable typed records; do not emit a consensus marker.',
+    ].join('\n')
+  },
+
+  checkpointTaskGraph(group, controller, cursorInput, options = {}) {
+    let taskGraph = parseTaskGraphCursor(cursorInput)
+    taskGraph = parseTaskGraphCursor({
+      ...taskGraph,
+      terminalState: terminalTaskGraphState(taskGraph),
+    })
+    const states = new Map(taskGraph.nodeStates.map(state => [state.nodeId, state]))
+    const pendingKinds = taskGraph.graph.nodes
+      .filter(node => states.get(node.nodeId)?.status === 'pending' && node.agentKind)
+      .map(node => node.agentKind)
+    const successfulKinds = taskGraph.graph.nodes
+      .filter(node => states.get(node.nodeId)?.status === 'accepted' && node.agentKind)
+      .map(node => node.agentKind)
+    const uniquePendingKinds = [...new Set(pendingKinds)]
+    const uniqueSuccessfulKinds = [...new Set(successfulKinds)]
+    this.checkpointOrchestration(group, controller, {
+      taskGraph,
+      currentKind: options.currentKind || '',
+      pendingKinds: uniquePendingKinds,
+      successfulKinds: uniqueSuccessfulKinds,
+      agreementKinds: [],
+      totalSuccesses: taskGraph.nodeStates.filter(state => state.status === 'accepted').length,
+      terminalFailureOccurred: taskGraph.terminalState === 'failed',
+    })
+    return taskGraph
+  },
+
+  taskGraphResultAccepted(node, result) {
+    const conclusion = publicCollaborationText(result?.message?.content || '')
+    const artifactIds = result?.outcomeRefs?.artifactIds || []
+    const evidenceIds = result?.outcomeRefs?.evidenceIds || []
+    return (!node.acceptance.requireConclusion || Boolean(conclusion))
+      && artifactIds.length >= node.acceptance.minArtifactRefs
+      && evidenceIds.length >= node.acceptance.minEvidenceRefs
+  },
+
+  applyTaskGraphAgentResult(group, controller, node, result) {
+    const conflicts = this.unresolvedTaskGraphConflicts(controller.orchestration.collaboration)
+    const entryIds = this.recordCollaborationResult(
+      group,
+      controller,
+      controller.orchestration.activeKinds,
+      node.agentKind,
+      result,
+      {
+        role: node.role,
+        entryType: node.role === 'arbiter' ? 'decision' : 'claim',
+        subject: node.role === 'primary'
+          ? `task:${controller.taskId}:conclusion`
+          : `task:${controller.taskId}:node:${node.nodeId}`,
+        refs: node.role === 'arbiter' ? conflicts.map(entry => entry.entryId) : [],
+      },
+    )
+    const accepted = this.taskGraphResultAccepted(node, result)
+    const conclusion = publicCollaborationText(result?.message?.content || '')
+    const artifactIds = result?.outcomeRefs?.artifactIds || []
+    const evidenceIds = result?.outcomeRefs?.evidenceIds || []
+    let cursor = updateTaskGraphCursor(
+      controller.orchestration.taskGraph,
+      node.nodeId,
+      {
+        status: accepted ? 'accepted' : 'failed',
+        entryIds,
+        artifactIds,
+        evidenceIds,
+        conclusionHash: conclusion
+          ? createHash('sha256').update(conclusion).digest('hex')
+          : '',
+      },
+    )
+    if (accepted) {
+      if (!controller.completedKinds.includes(node.agentKind)) {
+        controller.completedKinds.push(node.agentKind)
+      }
+    } else if (!controller.failedKinds.includes(node.agentKind)) {
+      controller.failedKinds.push(node.agentKind)
+    }
+    cursor = this.checkpointTaskGraph(group, controller, cursor)
+    return accepted
+  },
+
+  taskGraphDecisionAgentRunId(graphId, nodeId) {
+    const digest = createHash('sha256').update(JSON.stringify([graphId, nodeId])).digest('hex')
+    return `graph-decision-${digest}`
+  },
+
+  taskGraphDecisionAnchor(controller, node) {
+    const graph = parseTaskGraphCursor(controller.orchestration.taskGraph)
+    const byId = new Map(graph.graph.nodes.map(candidate => [candidate.nodeId, candidate]))
+    return [...node.dependsOn].reverse()
+      .map(nodeId => byId.get(nodeId)?.agentKind)
+      .find(Boolean) || controller.targetKinds[0]
+  },
+
+  applyTaskGraphHumanDecision(group, controller, node, decision) {
+    const option = node.decisionOptions.find(candidate => candidate.optionId === decision.optionId)
+    if (!option) throw new Error('LOCAL_WORKFLOW_DECISION_INVALID')
+    const accepted = decision.status === 'approved'
+    const conflicts = this.unresolvedTaskGraphConflicts(controller.orchestration.collaboration)
+    let collaboration = controller.orchestration.collaboration
+    collaboration = appendBlackboardEntry(collaboration, {
+      entryType: 'decision',
+      subject: `task:${controller.taskId}:node:${node.nodeId}`,
+      statement: `Human selected: ${option.name}`,
+      value: '',
+      owner: { type: 'harness' },
+      audience: { roles: ['primary', 'reviewer', 'arbiter'], agentKinds: [] },
+      lifecycle: {
+        state: 'active',
+        sequence: collaboration.entries.length + 1,
+        recordedAt: Date.now(),
+        supersedesEntryId: null,
+      },
+      provenance: {
+        runId: controller.runId,
+        taskId: controller.taskId,
+        round: controller.currentRound,
+        agentRunId: this.taskGraphDecisionAgentRunId(
+          controller.orchestration.taskGraph.graph.graphId,
+          node.nodeId,
+        ),
+        artifactIds: [],
+        evidenceIds: [],
+      },
+      refs: conflicts.map(entry => entry.entryId),
+    })
+    const decisionEntryId = collaboration.entries.at(-1).entryId
+    this.checkpointOrchestration(group, controller, { collaboration })
+    let cursor = updateTaskGraphCursor(
+      controller.orchestration.taskGraph,
+      node.nodeId,
+      {
+        status: accepted ? 'accepted' : 'rejected',
+        entryIds: [decisionEntryId],
+        decisionOptionId: option.optionId,
+      },
+    )
+    cursor = this.checkpointTaskGraph(group, controller, cursor)
+    return accepted
+  },
+
+  async executeTaskGraphAgentNode(
+    group, controller, threadRootId, context, node, parallelGraph = false,
+  ) {
+    const selectedEntryIds = this.taskGraphSelectedEntryIds(controller, node)
+    const collaborationPackage = this.prepareCollaborationPackage(
+      group,
+      controller,
+      controller.orchestration.activeKinds,
+      node.agentKind,
+      threadRootId,
+      {
+        role: node.role,
+        selectedEntryIds,
+        expectedOutput: node.expectedOutput,
+        acceptanceCriteria: this.taskGraphAcceptanceCriteria(node),
+      },
+    )
+    const isolated = ['reviewer', 'arbiter'].includes(node.role)
+    const attachments = node.role === 'primary'
+      && !controller.orchestration.attachmentRecipients.includes(node.agentKind)
+      ? context.rootAttachments.map(attachment => attachment.path)
+      : []
+    const objective = this.collaborationObjective(group, controller, threadRootId)
+    return this.invokeWithUnauthorizedRecovery({
+      group,
+      kind: node.agentKind,
+      controller,
+      threadRootId,
+      context: {
+        attachments,
+        attachmentSnapshots: attachments.length ? context.rootAttachments : [],
+        skillHints: context.rootSkillsByKind.get(node.agentKind) || [],
+        knowledgeBaseHints: context.rootKnowledgeBasesByKind.get(node.agentKind) || [],
+        collaborationPackage,
+        completionPolicy: 'typed',
+        parallelGraph,
+        runtimeInstruction: isolated ? '' : [
+          `Execute task-graph node ${node.nodeId} as ${node.role}.`,
+          `Expected output: ${node.expectedOutput}`,
+          'Do not emit a consensus marker.',
+        ].join('\n'),
+        ...(isolated ? {
+          sessionPolicy: 'isolated',
+          promptOverride: this.taskGraphPrompt(
+            node, objective, collaborationPackage, controller.unlimitedRounds === true,
+          ),
+          contextPackId: controller.contextPackId,
+        } : {}),
+        contextOptions: {
+          focusUserMessageId: threadRootId,
+          omitAgentThreadRootId: threadRootId,
+        },
+      },
+      mode: 'auto',
+    })
+  },
+
+  async executeTaskGraphHumanNode(group, controller, node) {
+    if (!this.requestHumanGate) throw new Error('LOCAL_WORKFLOW_DECISION_UNAVAILABLE')
+    const anchorKind = this.taskGraphDecisionAnchor(controller, node)
+    const agentRunId = this.taskGraphDecisionAgentRunId(
+      controller.orchestration.taskGraph.graph.graphId,
+      node.nodeId,
+    )
+    let cursor = updateTaskGraphCursor(
+      controller.orchestration.taskGraph,
+      node.nodeId,
+      { status: 'waiting', attention: 'decision', attempts: 1 },
+    )
+    cursor = this.checkpointTaskGraph(group, controller, cursor, { currentKind: anchorKind })
+    const gate = await this.requestHumanGate({
+      type: 'decision',
+      runId: controller.runId,
+      agentRunId,
+      agentKind: anchorKind,
+      summary: node.expectedOutput,
+      options: node.decisionOptions,
+      request: {
+        graphId: cursor.graph.graphId,
+        nodeId: node.nodeId,
+        inputNodeIds: node.inputNodeIds,
+      },
+    }, {
+      signal: controller.signal,
+      preserveOnAbort: () => controller.stopReason === 'shutdown',
+      continuation: {
+        resumeKind: 'role_review_decision',
+        agentRunId,
+        agentKind: anchorKind,
+        round: controller.currentRound,
+      },
+    })
+    const accepted = this.applyTaskGraphHumanDecision(group, controller, node, gate)
+    if (this.completeHumanGateContinuation?.(
+      controller.runId,
+      gate.gateId,
+      accepted ? 'completed' : 'cancelled',
+    ) !== true && this.hasRunLedger()) {
+      throw new Error('LOCAL_RUN_PERSIST_FAILED')
+    }
+    return accepted
+  },
+
+  taskGraphBatch(group, readyNodes) {
+    const parallel = []
+    const kinds = new Set()
+    if (group.allowWrite !== true) {
+      for (const node of readyNodes) {
+        if (!node.parallel || node.role === 'human' || kinds.has(node.agentKind)) continue
+        parallel.push(node)
+        kinds.add(node.agentKind)
+      }
+    }
+    return parallel.length > 1 ? parallel : readyNodes.slice(0, 1)
+  },
+
+  async runTaskGraph(group, controller, threadRootId, context) {
+    while (!controller.signal.aborted) {
+      let cursor = parseTaskGraphCursor(controller.orchestration.taskGraph)
+      const terminalState = terminalTaskGraphState(cursor)
+      if (terminalState !== 'running') {
+        cursor = this.checkpointTaskGraph(group, controller, cursor)
+        break
+      }
+      if (!controller.unlimitedRounds && controller.currentRound >= controller.maxRounds) break
+      const readyNodes = readyTaskGraphNodes(cursor)
+      if (!readyNodes.length) {
+        cursor = parseTaskGraphCursor({ ...cursor, terminalState: 'failed' })
+        this.checkpointTaskGraph(group, controller, cursor)
+        break
+      }
+      const batch = this.taskGraphBatch(group, readyNodes)
+      controller.currentRound += 1
+      if (batch.length === 1 && batch[0].role === 'human') {
+        await this.executeTaskGraphHumanNode(group, controller, batch[0])
+        continue
+      }
+      const conflicts = this.unresolvedTaskGraphConflicts(controller.orchestration.collaboration)
+      for (const node of batch) {
+        cursor = updateTaskGraphCursor(cursor, node.nodeId, {
+          status: 'running',
+          attention: node.role === 'reviewer' && conflicts.length
+            ? 'review'
+            : (node.role === 'arbiter' && conflicts.length ? 'decision' : 'none'),
+          attempts: cursor.nodeStates.find(state => state.nodeId === node.nodeId).attempts + 1,
+        })
+      }
+      const currentKind = batch.length === 1 ? batch[0].agentKind : ''
+      cursor = this.checkpointTaskGraph(group, controller, cursor, { currentKind })
+      this.emitChanged()
+      const settled = await Promise.allSettled(batch.map(node => (
+        this.executeTaskGraphAgentNode(
+          group, controller, threadRootId, context, node, batch.length > 1,
+        )
+      )))
+      for (let index = 0; index < batch.length; index += 1) {
+        const node = batch[index]
+        const outcome = settled[index]
+        if (outcome.status === 'fulfilled' && outcome.value?.result) {
+          if (outcome.value.result.outcomeRefs?.artifactIds?.length
+              && !controller.orchestration.attachmentRecipients.includes(node.agentKind)) {
+            this.checkpointOrchestration(group, controller, {
+              attachmentRecipients: [...controller.orchestration.attachmentRecipients, node.agentKind],
+            })
+          }
+          this.applyTaskGraphAgentResult(group, controller, node, outcome.value.result)
+          continue
+        }
+        const error = outcome.status === 'rejected'
+          ? outcome.reason
+          : (outcome.value?.error || new Error('LOCAL_AGENT_UNKNOWN_FAILURE'))
+        if (controller.signal.aborted) continue
+        this.recordAgentFailure(group.id, node.agentKind, error, threadRootId, new Set())
+        cursor = updateTaskGraphCursor(
+          controller.orchestration.taskGraph,
+          node.nodeId,
+          { status: 'failed' },
+        )
+        this.checkpointTaskGraph(group, controller, cursor)
+        if (!controller.failedKinds.includes(node.agentKind)) {
+          controller.failedKinds.push(node.agentKind)
+        }
+        if (circuitBreakerFailure(error)) {
+          controller.stopReason = 'circuit_breaker'
+          controller.abort()
+        } else if (hardBudgetFailure(error)) {
+          controller.stopReason = 'hard_budget'
+          controller.abort()
+        }
+      }
+      controller.currentKind = ''
+      controller.progress = []
+      this.emitChanged()
+    }
+
+    if (controller.signal.aborted) return terminalRunStatusForReason(controller.stopReason)
+    const cursor = parseTaskGraphCursor(controller.orchestration.taskGraph)
+    if (cursor.terminalState === 'accepted') return 'completed'
+    if (cursor.terminalState === 'rejected') return 'stopped'
+    if (cursor.terminalState === 'failed') {
+      return cursor.nodeStates.some(state => state.status === 'accepted') ? 'partial' : 'failed'
+    }
+    return cursor.nodeStates.some(state => state.status === 'accepted') ? 'round-limit' : 'failed'
+  },
+}
+
+module.exports = { taskGraphMethods }

desktop/src/workspace/local-workspace-auto-runner-v4-context.cjs

@@ -0,0 +1,403 @@
+// What a V4 run freezes and shares: the task snapshot, stored receipts and the collaboration package.
+const { createHash } = require('node:crypto')
+const { peerCollaborationText, publicCollaborationText } = require('../collaboration/collaboration-records.cjs')
+const {
+  buildCollaborationPackage,
+  hashValue,
+  parseCollaborationControlBlock,
+  resolveCoordinationConsensus,
+} = require('../collaboration/orchestration-v4-records.cjs')
+const { canonicalJson } = require('../collaboration/context-pack-records.cjs')
+const {
+  restoreV4SnapshotSkills,
+  v4SnapshotBodyHash,
+  v4SnapshotSkillHints,
+  validateV4SnapshotBody,
+} = require('./local-workspace-context.cjs')
+
+const v4ContextMethods = {
+  v4OperationId(
+    controller, kind, phase, slotId = '', round = controller.currentRound || 0,
+  ) {
+    const digest = createHash('sha256').update(JSON.stringify([
+      controller.runId,
+      controller.taskId,
+      kind,
+      slotId,
+      phase,
+      round,
+    ])).digest('hex')
+    return `operation-${digest}`
+  },
+
+  v4SnapshotRecord(controller, snapshot, targetKinds) {
+    if (!this.contentBlobStore) throw new Error('LOCAL_RUN_SNAPSHOT_STORE_UNAVAILABLE')
+    const serialized = canonicalJson(snapshot)
+    const contentRef = this.contentBlobStore.put(serialized, { mediaType: 'application/json' })
+    const sourceIds = [snapshot?.messageId, ...(snapshot?.history || []).map(item => item.id)]
+      .filter(Boolean).slice(-64)
+    const taskId = snapshot?.taskId || controller.taskId || null
+    const record = {
+      contextPackId: controller.contextPackId || null,
+      taskId,
+      messageId: snapshot?.messageId || controller.threadRootId || null,
+      groupId: snapshot?.group?.id || controller.groupId || null,
+      round: Math.max(0, Number(controller.currentRound) || 0),
+      targetKinds: [...targetKinds],
+      sourceIds,
+      capturedAt: Date.now(),
+      charCount: Buffer.byteLength(serialized),
+      contentHash: contentRef.hash,
+      bodyHash: v4SnapshotBodyHash(snapshot),
+      contentRef,
+    }
+    return { record, snapshotHash: hashValue(record) }
+  },
+
+  v4SnapshotSkillHints(snapshot, targetKinds) {
+    return v4SnapshotSkillHints(snapshot, targetKinds)
+  },
+
+  async v4RestoreSnapshotSkills(snapshot, targetKinds, persisted = null) {
+    return restoreV4SnapshotSkills({
+      snapshot,
+      targetKinds,
+      validateSkillSelections: this.validateSkillSelections,
+      persisted,
+    })
+  },
+
+  v4LoadSnapshot(orchestration, { taskId, messageId, groupId, targetKinds }) {
+    const record = orchestration?.snapshot
+    if (!record?.contentRef || !this.contentBlobStore) {
+      throw new Error('LOCAL_RUN_SNAPSHOT_INVALID')
+    }
+    let bytes
+    try { bytes = this.contentBlobStore.read(record.contentRef) } catch {
+      throw new Error('LOCAL_RUN_SNAPSHOT_INVALID')
+    }
+    const serialized = bytes.toString('utf8')
+    let body
+    try { body = JSON.parse(serialized) } catch {
+      throw new Error('LOCAL_RUN_SNAPSHOT_INVALID')
+    }
+    return validateV4SnapshotBody({
+      body,
+      serialized,
+      byteLength: bytes.length,
+      record,
+      orchestrationSnapshotHash: orchestration.snapshotHash,
+      taskId,
+      messageId,
+      groupId,
+      targetKinds,
+    })
+  },
+
+  v4RestoreReceipts(controller) {
+    if (Array.isArray(controller.v4ReceiptRecords)) {
+      return controller.v4ReceiptRecords.map(item => ({
+        receipt: item.receipt,
+        verdict: item.verdict || '',
+        resolvedIssueIds: Array.isArray(item.resolvedIssueIds)
+          ? [...item.resolvedIssueIds]
+          : [],
+      }))
+    }
+    const restored = []
+    const slots = Array.isArray(controller.orchestration?.slots)
+      ? controller.orchestration.slots
+      : []
+    for (const slot of slots) {
+      const records = slot?.resultRefs?.workflowOutcomeRefs
+      if (!Array.isArray(records)) continue
+      for (const record of records) {
+        if (!record?.receipt) continue
+        try {
+          const receipt = parseCollaborationControlBlock(record.receipt)
+          restored.push({
+            receipt,
+            verdict: typeof record.verdict === 'string' ? record.verdict : '',
+            resolvedIssueIds: Array.isArray(record.resolvedIssueIds)
+              ? record.resolvedIssueIds.filter(value => typeof value === 'string')
+              : [],
+          })
+        } catch { /* malformed historical receipts are ignored and re-run */ }
+      }
+    }
+    controller.v4ReceiptRecords = restored
+    return restored
+  },
+
+  v4Package(receiptRecords, options = {}) {
+    const recipientKind = String(options.recipientKind || '')
+    const binding = options.sessionBinding || {}
+    const deliveryState = Array.isArray(options.deliveryState) ? options.deliveryState : []
+    const latest = new Map()
+    for (const item of receiptRecords) {
+      const receipt = item?.receipt
+      if (!receipt) continue
+      const key = receipt.agentKind || `${receipt.phase}\u0000${receipt.summary}`
+      const previous = latest.get(key)
+      if (!previous || (Number(receipt.deliveryWatermark) || 0)
+          > (Number(previous.receipt.deliveryWatermark) || 0)
+          || ((Number(receipt.deliveryWatermark) || 0)
+            === (Number(previous.receipt.deliveryWatermark) || 0)
+            && receipt.phase.localeCompare(previous.receipt.phase) > 0)) {
+        latest.set(key, item)
+      }
+    }
+    let selectedItems = [...latest.values()]
+    const snapshotHash = typeof options.snapshotHash === 'string' ? options.snapshotHash : ''
+    const targetKinds = new Set(Array.isArray(options.targetKinds) ? options.targetKinds : [])
+    const resolvedIssueIds = []
+    const resolved = new Set()
+    for (const item of receiptRecords) {
+      const receipt = item?.receipt
+      if (!snapshotHash || receipt?.snapshotHash !== snapshotHash
+          || (targetKinds.size && !targetKinds.has(receipt.agentKind))) continue
+      for (const value of Array.isArray(item.resolvedIssueIds) ? item.resolvedIssueIds : []) {
+        if (typeof value !== 'string' || !value || value.length > 120 || resolved.has(value)) continue
+        resolved.add(value)
+        resolvedIssueIds.push(value)
+        if (resolvedIssueIds.length >= 256) break
+      }
+      if (resolvedIssueIds.length >= 256) break
+    }
+    if (recipientKind && binding.sessionRefHash && !options.forceFull) {
+      const acknowledged = new Map(deliveryState
+        .filter(item => item.recipientKind === recipientKind
+          && item.sessionRefHash === binding.sessionRefHash
+          && item.sessionProvenanceHash === binding.sessionProvenanceHash
+          && item.status === 'acknowledged')
+        .map(item => [`${item.sourceAgentKind}\u0000${item.sourcePhase}`, item.watermark]))
+      selectedItems = selectedItems.filter(item => {
+        const receipt = item.receipt
+        const previous = acknowledged.get(`${receipt.agentKind}\u0000${receipt.phase}`) || 0
+        return (Number(receipt.deliveryWatermark) || 0) > previous
+      })
+    }
+    const selectedReceipts = selectedItems.map(item => item.receipt)
+    const totalLimit = Number.isSafeInteger(options.totalLimit) ? options.totalLimit : 6000
+    const packageRecord = buildCollaborationPackage(selectedReceipts, {
+      targetKinds: options.targetKinds || [],
+      totalLimit,
+      resolvedIssueIds,
+    })
+    const text = this.v4SanitizeDeliveryText(packageRecord.text, packageRecord.text.length)
+    return text === packageRecord.text
+      ? packageRecord
+      : { ...packageRecord, text, totalChars: text.length, packageHash: hashValue(text) }
+  },
+
+  v4CoordinationResult({
+    receiptRecords, targetKinds, snapshotHash, snapshot = null,
+    challengeBindings = [], requireSupport = true,
+  }) {
+    const candidateReceipts = receiptRecords
+      .filter(record => record?.receipt?.phase === 'challenge')
+    const supportReceipts = requireSupport
+      ? targetKinds.map((kind) => {
+          const operationId = challengeBindings.find(binding => (
+            binding.reviewerKind === kind
+          ))?.reviewerOperationId || ''
+          return this.v4ReceiptForOperation(
+            receiptRecords, 'challenge', kind, operationId,
+          ) || null
+        })
+      : []
+    if (supportReceipts.some(receipt => !receipt)) {
+      const result = resolveCoordinationConsensus({
+        targetKinds, snapshotHash, candidateReceipts, supportReceipts: [],
+      })
+      return this.v4SemanticCoordinationResult(result, snapshot)
+    }
+    const result = resolveCoordinationConsensus({
+      targetKinds, snapshotHash, candidateReceipts, supportReceipts,
+    })
+    return this.v4SemanticCoordinationResult(result, snapshot)
+  },
+
+  v4SemanticCoordinationResult(result, snapshot) {
+    const candidates = result.candidates.filter((candidate) => {
+      try {
+        for (const assignment of candidate.assignments) {
+          this.v4DirectAssignmentReferences(assignment, snapshot)
+        }
+        return true
+      } catch (error) {
+        if (error?.message === 'LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID') return false
+        throw error
+      }
+    })
+    const candidateHashes = new Set(candidates.map(candidate => candidate.planHash))
+    return {
+      ...result,
+      plan: result.plan && candidateHashes.has(result.plan.planHash) ? result.plan : null,
+      candidates,
+    }
+  },
+
+  v4SanitizeDeliveryText(value, limit = 6000, options = {}) {
+    const privateWrapper = '(?:private[ _-]?(?:reasoning|thoughts?)|analysis|chain[ _-]?of[ _-]?thought|cot)'
+    const privateHeading = '(?:private[ _-]?(?:reasoning|thoughts?)|chain[ _-]?of[ _-]?thought|cot)'
+    const stripped = this.v4StripMeldworkControls(
+      options.workspaceRoot
+        ? peerCollaborationText(value, { workspaceRoot: options.workspaceRoot })
+        : publicCollaborationText(value, Number.MAX_SAFE_INTEGER),
+    )
+    const maximum = Number.isSafeInteger(limit) && limit >= 0 ? limit : 6000
+    let privateSectionLevel = null
+    const withoutPrivateSections = stripped.split(/\r?\n/).filter((line) => {
+      const heading = line.match(/^\s*(#{1,6})\s+(.+)$/u)
+      const level = heading?.[1].length
+      if (heading && new RegExp(`^${privateHeading}\\b`, 'iu').test(heading[2].trim())) {
+        privateSectionLevel = Math.min(privateSectionLevel ?? level, level)
+        return false
+      }
+      if (privateSectionLevel !== null && heading && level <= privateSectionLevel) {
+        privateSectionLevel = null
+      }
+      return privateSectionLevel === null
+    }).join('\n')
+    return withoutPrivateSections
+      .replace(new RegExp(`<\\s*${privateWrapper}\\b[^>]*>[\\s\\S]*?<\\/\\s*${privateWrapper}\\s*>`, 'giu'), '')
+      .replace(/(?:^|\n)\s*(?:my\s+)?private[ _-]?reasoning\s*:\s*[^\n]*/giu, '\n')
+      .replace(/\b(?:session(?:[ _-]?(?:id|ref))?)\b\s*(?::|=)\s*[A-Za-z0-9][A-Za-z0-9._:-]*/giu, '[redacted]')
+      .replace(/\b(?:session(?:[ _-]?(?:id|ref))?)\b\s+[A-Za-z0-9][A-Za-z0-9._:-]*/giu, '[redacted]')
+      .replace(/\b(?:session[-_][A-Za-z0-9._:-]+|[A-Za-z0-9][A-Za-z0-9._:-]*-(?:native-)?session)\b/giu, '[redacted]')
+      .replace(/\n{3,}/g, '\n\n')
+      .trim()
+      .slice(0, maximum)
+  },
+
+  v4StripMeldworkControls(text) {
+    const marker = '[[MELDWORK_'
+    const source = String(text || '')
+    const upper = source.toUpperCase()
+    let cursor = 0
+    let output = ''
+    while (true) {
+      const start = upper.indexOf(marker, cursor)
+      if (start < 0) return output + source.slice(cursor)
+      output += source.slice(cursor, start)
+      let quote = ''
+      let escaped = false
+      let braces = 0
+      let brackets = 0
+      let end = -1
+      for (let index = start + 2; index < source.length - 1; index += 1) {
+        const character = source[index]
+        if (quote) {
+          if (escaped) escaped = false
+          else if (character === '\\') escaped = true
+          else if (character === quote) quote = ''
+          continue
+        }
+        if (character === '"' || character === "'") {
+          quote = character
+        } else if (character === '{') {
+          braces += 1
+        } else if (character === '}') {
+          braces = Math.max(0, braces - 1)
+        } else if (character === '[') {
+          brackets += 1
+        } else if (character === ']') {
+          if (braces === 0 && brackets === 0 && source[index + 1] === ']') {
+            end = index + 2
+            break
+          }
+          brackets = Math.max(0, brackets - 1)
+        }
+      }
+      if (end < 0) return output
+      const header = source.slice(start, end)
+      if (!header.includes(':')) {
+        const closing = `[[/${header.slice(2, -2)}]]`.toUpperCase()
+        const closingStart = upper.indexOf(closing, end)
+        cursor = closingStart < 0 ? end : closingStart + closing.length
+      } else {
+        cursor = end
+      }
+    }
+  },
+
+  v4CoordinationText(result, limit = 4800) {
+    const candidates = Array.isArray(result?.candidates) ? result.candidates : []
+    if (!candidates.length) return ''
+    const supportCounts = new Map()
+    for (const planHash of result.supportPlanHashes || []) {
+      if (planHash) supportCounts.set(planHash, (supportCounts.get(planHash) || 0) + 1)
+    }
+    const lines = [
+      'MELDWORK_V4_RESPONSIBILITY_CANDIDATES_V1',
+      'Fields: h=planHash;s=support;f=finalizer;v=verifiers;a=[t=taskId,o=owner,r=role,x=objective,y=expectedOutput,i=inputRefs,a=artifactRefs,d=dependencies]',
+    ]
+    const append = (line) => {
+      const next = [...lines, line].join('\n')
+      if (next.length > limit) return false
+      lines.push(line)
+      return true
+    }
+    for (const plan of candidates) {
+      let safe = true
+      const text = value => {
+        const raw = String(value || '')
+        const sanitized = this.v4SanitizeDeliveryText(raw, 2000)
+        if (/\[\[MELDWORK_/iu.test(raw) || sanitized !== raw) safe = false
+        return sanitized
+      }
+      const values = value => Array.isArray(value) ? value.map(text) : []
+      const graph = {
+        h: plan.planHash,
+        s: supportCounts.get(plan.planHash) || 0,
+        f: text(plan.finalizerKind),
+        v: values(plan.verifierKinds),
+        a: plan.assignments.map(assignment => ({
+          t: text(assignment.taskId),
+          o: text(assignment.ownerKind),
+          r: text(assignment.role),
+          x: text(assignment.objective),
+          y: text(assignment.expectedOutput),
+          i: values(assignment.inputRefs),
+          a: values(assignment.artifactIds),
+          d: values(assignment.dependsOn),
+        })),
+      }
+      if (!safe) continue
+      append(JSON.stringify(graph))
+    }
+    return lines.join('\n')
+  },
+
+  v4ChallengeProposalText(binding, reviewerKind, limit = 1600) {
+    const proposalKind = String(binding?.proposalKind || '')
+    if (!proposalKind || proposalKind === reviewerKind) {
+      throw new Error('LOCAL_RUN_V4_CHALLENGE_BINDING_INVALID')
+    }
+    for (const artifactId of binding.artifactIds || []) {
+      try {
+        const { artifact, content } = this.v4ArtifactIdentity(artifactId)
+        const body = this.v4SanitizeDeliveryText(content, limit)
+        if (artifact.producedBy?.agentKind !== proposalKind || !body) continue
+        return [
+          'MELDWORK_V4_ASSIGNED_PROPOSAL_V1',
+          `Proposal Agent: ${proposalKind}`,
+          `Proposal Artifact: ${artifactId}`,
+          'Proposal body excerpt:',
+          body,
+        ].join('\n')
+      } catch { /* skip non-text and unavailable outcome refs */ }
+    }
+    throw new Error('LOCAL_RUN_V4_CHALLENGE_BINDING_INVALID')
+  },
+
+  v4CoordinationAssignment(coordinationPlan, kind, options = {}) {
+    const owned = coordinationPlan?.assignments?.filter(item => item.ownerKind === kind) || []
+    if (options.taskId) return owned.find(item => item.taskId === options.taskId) || null
+    if (options.role) return owned.find(item => item.role === options.role) || null
+    return owned[0] || null
+  },
+}
+
+module.exports = { v4ContextMethods }

desktop/src/workspace/local-workspace-auto-runner-v4-delivery.cjs

@@ -0,0 +1,604 @@
+// How a V4 run hands context to each Agent: assignments, the blackboard owner, delivery prompts and delivery state.
+const { createHash } = require('node:crypto')
+const { collaborationPackageIndexText } = require('../collaboration/collaboration-records.cjs')
+const { hashValue } = require('../collaboration/orchestration-v4-records.cjs')
+const { v4Prompt } = require('./local-workspace-context.cjs')
+
+const v4DeliveryMethods = {
+  v4DirectAssignmentReferences(assignment, snapshot) {
+    const snapshotSources = new Map([
+      [snapshot?.messageId, snapshot?.taskText],
+      ...(Array.isArray(snapshot?.history) ? snapshot.history : []).map(item => [item?.id, item?.text]),
+    ].filter(([sourceId]) => typeof sourceId === 'string' && sourceId))
+    const safeReferenceText = (value) => {
+      const raw = String(value || '').trim()
+      const sanitized = this.v4SanitizeDeliveryText(raw, Number.MAX_SAFE_INTEGER)
+      if (!raw || sanitized !== raw || /\[\[MELDWORK_/iu.test(raw)) {
+        throw new Error('LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID')
+      }
+      return sanitized
+    }
+    const inputReferences = assignment.inputRefs.map((sourceId) => {
+      if (!snapshotSources.has(sourceId)) {
+        throw new Error('LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID')
+      }
+      return {
+        kind: 'input', id: sourceId, header: `Input ${sourceId}:`,
+        body: safeReferenceText(snapshotSources.get(sourceId)),
+      }
+    })
+    const directArtifacts = assignment.artifactIds.map((artifactId) => {
+      let identity
+      try { identity = this.v4ArtifactIdentity(artifactId) } catch {
+        throw new Error('LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID')
+      }
+      if (identity.artifact.contentRef?.mediaType !== 'text/plain') {
+        throw new Error('LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID')
+      }
+      return {
+        kind: 'artifact', id: artifactId, header: `Artifact ${artifactId}:`,
+        body: safeReferenceText(identity.content),
+      }
+    })
+    return { inputReferences, directArtifacts }
+  },
+
+  v4WorkAssignmentText(
+    coordinationPlan, kind, taskId, snapshot = null, limit = 6000, receiptRecords = [],
+  ) {
+    const assignment = this.v4CoordinationAssignment(coordinationPlan, kind, { taskId })
+    if (!assignment) throw new Error('LOCAL_RUN_V4_COORDINATION_PLAN_INVALID')
+    const { inputReferences, directArtifacts } = this.v4DirectAssignmentReferences(
+      assignment, snapshot,
+    )
+    const directReferences = [...inputReferences, ...directArtifacts]
+    const dependencies = new Set(assignment.dependsOn)
+    const latestDependencies = new Map()
+    for (const record of receiptRecords) {
+      const receipt = record?.receipt
+      if (receipt?.phase !== 'work' || !dependencies.has(receipt.workItemId)) continue
+      latestDependencies.set(receipt.workItemId, record)
+    }
+    const dependencyArtifacts = [...latestDependencies.values()]
+      .sort((left, right) => String(left.receipt.workItemId)
+        .localeCompare(String(right.receipt.workItemId)))
+      .flatMap(record => (record.receipt.artifactIds || []).map((artifactId, index) => ({
+        artifactId,
+        index,
+        receipt: record.receipt,
+      })))
+      .map(({ artifactId, index, receipt }) => {
+        let identity
+        try { identity = this.v4ArtifactIdentity(artifactId) } catch {
+          throw new Error('LOCAL_RUN_V4_REFERENCE_INVALID')
+        }
+        const mediaType = String(identity.artifact.contentRef?.mediaType || '')
+        const raw = String(identity.content || '').trim()
+        const body = mediaType === 'text/plain'
+          ? this.v4SanitizeDeliveryText(raw, Number.MAX_SAFE_INTEGER)
+          : ''
+        let omission = ''
+        if (mediaType !== 'text/plain') {
+          omission = `${artifactId} reason=non-text mediaType=${mediaType || 'unknown'}`
+        } else if (!raw) {
+          omission = `${artifactId} reason=empty`
+        } else if (body !== raw) {
+          omission = `${artifactId} reason=safety-filter`
+        }
+        return {
+          key: `${receipt.workItemId}:${index}`,
+          artifactId,
+          body,
+          omission,
+          header: `Artifact ${artifactId} from ${receipt.agentKind} work=${receipt.workItemId}`,
+        }
+      })
+    const render = (included) => {
+      const lines = [
+        'MELDWORK_V4_AGREED_WORK_PACKAGE_V1',
+        `Responsibility plan: ${coordinationPlan.planHash}`,
+        `Work item: ${assignment.taskId}`,
+        `Owner: ${assignment.ownerKind}`,
+        `Role: ${assignment.role}`,
+        `Input refs: ${assignment.inputRefs.length ? assignment.inputRefs.join(', ') : '(none)'}`,
+        `Artifact refs: ${assignment.artifactIds.length ? assignment.artifactIds.join(', ') : '(none)'}`,
+        `Dependencies: ${assignment.dependsOn.length ? assignment.dependsOn.join(', ') : '(none)'}`,
+      ]
+      if (inputReferences.length) {
+        lines.push('MELDWORK_V4_FROZEN_INPUT_REFS_V1')
+        for (const reference of inputReferences) {
+          lines.push(reference.header)
+          const body = included.get(`direct:${reference.kind}:${reference.id}`) || ''
+          if (body) lines.push(body)
+        }
+      }
+      if (directArtifacts.length) {
+        lines.push('MELDWORK_V4_DIRECT_ARTIFACT_REFS_V1')
+        for (const reference of directArtifacts) {
+          lines.push(reference.header)
+          const body = included.get(`direct:${reference.kind}:${reference.id}`) || ''
+          if (body) lines.push(body)
+        }
+      }
+      if (dependencyArtifacts.length) {
+        lines.push('MELDWORK_V4_REFERENCED_ARTIFACTS_V1')
+        for (const artifact of dependencyArtifacts) {
+          lines.push(artifact.header)
+          const body = included.get(`dependency:${artifact.key}`) || ''
+          if (body) lines.push(body)
+        }
+      }
+      const objective = included.get('objective') || ''
+      const expectedOutput = included.get('expectedOutput') || ''
+      lines.push(`Objective: ${objective}`, `Expected output: ${expectedOutput}`)
+      const freeTextOmissions = [
+        ...(objective.length < assignment.objective.length ? ['objective reason=budget'] : []),
+        ...(expectedOutput.length < assignment.expectedOutput.length
+          ? ['expectedOutput reason=budget'] : []),
+      ]
+      if (freeTextOmissions.length) {
+        lines.push('MELDWORK_V4_TRUNCATED_FREE_TEXT_V1', ...freeTextOmissions)
+      }
+      const directOmissions = directReferences.filter(reference => (
+        (included.get(`direct:${reference.kind}:${reference.id}`) || '').length
+          < reference.body.length
+      )).map(reference => `${reference.kind} ${reference.id} reason=budget`)
+      if (directOmissions.length) {
+        lines.push('MELDWORK_V4_OMITTED_DIRECT_REFERENCE_BODIES_V1', ...directOmissions)
+      }
+      const dependencyOmissions = dependencyArtifacts.flatMap((artifact) => {
+        if (artifact.omission) return [artifact.omission]
+        return (included.get(`dependency:${artifact.key}`) || '').length < artifact.body.length
+          ? [`${artifact.artifactId} reason=budget`]
+          : []
+      })
+      if (dependencyOmissions.length) {
+        lines.push('MELDWORK_V4_OMITTED_ARTIFACT_BODIES_V1', ...dependencyOmissions)
+      }
+      return lines.join('\n')
+    }
+    const maximum = Number.isSafeInteger(limit) && limit >= 0 ? limit : 6000
+    const fullIncluded = new Map([
+      ['objective', assignment.objective],
+      ['expectedOutput', assignment.expectedOutput],
+      ...directReferences.map(reference => [
+        `direct:${reference.kind}:${reference.id}`, reference.body,
+      ]),
+      ...dependencyArtifacts.filter(artifact => artifact.body).map(artifact => [
+        `dependency:${artifact.key}`, artifact.body,
+      ]),
+    ])
+    const full = render(fullIncluded)
+    if (full.length <= maximum) return full
+    const bodyFields = [...fullIncluded.entries()]
+    const bodyLineCount = directReferences.length
+      + dependencyArtifacts.filter(artifact => artifact.body).length
+    let remaining = maximum - render(new Map()).length - bodyLineCount
+    if (remaining < 0) throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+    const included = new Map()
+    let pendingFields = bodyFields.length
+    for (const [key, body] of bodyFields) {
+      const share = pendingFields > 0 ? Math.floor(remaining / pendingFields) : 0
+      const value = body.slice(0, Math.max(0, share))
+      included.set(key, value)
+      remaining -= value.length
+      pendingFields -= 1
+    }
+    const result = render(included)
+    if (result.length > maximum) throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+    return result
+  },
+
+  v4CheckpointRole(phase, slot, coordinationPlan, workAssignment = null) {
+    if (['proposal', 'discussion', 'challenge'].includes(phase)) return 'participant'
+    const assignment = phase === 'work'
+      ? (workAssignment || this.v4CoordinationAssignment(coordinationPlan, slot.agentKind))
+      : (phase === 'synthesis'
+        ? this.v4CoordinationAssignment(coordinationPlan, slot.agentKind, { role: 'integrator' })
+          || this.v4CoordinationAssignment(coordinationPlan, slot.agentKind)
+        : this.v4CoordinationAssignment(coordinationPlan, slot.agentKind))
+    if (phase === 'verification') {
+      if (coordinationPlan?.verifierKinds?.includes(slot.agentKind)) return 'verifier'
+      return assignment?.role || 'writer'
+    }
+    return assignment?.role || 'writer'
+  },
+
+  v4PromptRole(phase, kind, coordinationPlan, workAssignment = null) {
+    if (['proposal', 'discussion', 'challenge'].includes(phase)) return 'participant'
+    if (phase === 'verification') {
+      if (!coordinationPlan?.verifierKinds?.includes(kind)) {
+        throw new Error('LOCAL_RUN_V4_COORDINATION_PLAN_INVALID')
+      }
+      return 'verifier'
+    }
+    const assignment = phase === 'work'
+      ? workAssignment
+      : (phase === 'synthesis'
+        ? this.v4CoordinationAssignment(coordinationPlan, kind, { role: 'integrator' })
+          || this.v4CoordinationAssignment(coordinationPlan, kind)
+        : this.v4CoordinationAssignment(coordinationPlan, kind))
+    if (!assignment) throw new Error('LOCAL_RUN_V4_COORDINATION_PLAN_INVALID')
+    return assignment.role
+  },
+
+  v4BlackboardOwner(coordinationPlan, kind) {
+    const assignment = this.v4CoordinationAssignment(coordinationPlan, kind, { role: 'integrator' })
+      || this.v4CoordinationAssignment(coordinationPlan, kind)
+    if (!assignment) {
+      throw new Error('LOCAL_RUN_V4_COORDINATION_PLAN_INVALID')
+    }
+    return {
+      type: 'agent',
+      agentKind: kind,
+      role: assignment.role,
+    }
+  },
+
+  v4ArtifactContext(
+    receiptRecords, phase, coordinationPlan, kind, limit = 3600, workTaskId = '',
+  ) {
+    let selected = []
+    if (phase === 'work') {
+      const assignment = this.v4CoordinationAssignment(
+        coordinationPlan, kind, { taskId: workTaskId },
+      )
+      const dependencies = new Set(assignment?.dependsOn || [])
+      selected = receiptRecords.filter(record => (
+        record?.receipt?.phase === 'work' && dependencies.has(record.receipt.workItemId)
+      ))
+    } else if (phase === 'synthesis') {
+      const workItems = new Set(coordinationPlan?.assignments?.map(item => item.taskId) || [])
+      selected = receiptRecords.filter(record => (
+        record?.receipt?.phase === 'work' && workItems.has(record.receipt.workItemId)
+      ))
+    } else if (phase === 'verification') {
+      const latest = this.v4LatestReceipt(receiptRecords, 'synthesis')
+      selected = latest ? [latest] : []
+    }
+    const latestByKey = new Map()
+    for (const record of selected) {
+      const receipt = record.receipt
+      const key = receipt.workItemId || `${receipt.phase}:${receipt.agentKind}`
+      latestByKey.set(key, record)
+    }
+    const records = [...latestByKey.values()].sort((left, right) => (
+      String(left.receipt.workItemId || left.receipt.agentKind)
+        .localeCompare(String(right.receipt.workItemId || right.receipt.agentKind))
+    ))
+    if (!records.length) return ''
+    const artifacts = records.flatMap((record, recordIndex) => {
+      const receipt = record.receipt
+      return (receipt.artifactIds || []).map((artifactId, artifactIndex) => ({
+        key: `${recordIndex}:${artifactIndex}`,
+        artifactId,
+        receipt,
+      }))
+    }).map(({ key, artifactId, receipt }) => {
+      let identity
+      try { identity = this.v4ArtifactIdentity(artifactId) } catch {
+        throw new Error('LOCAL_RUN_V4_REFERENCE_INVALID')
+      }
+      const mediaType = String(identity.artifact.contentRef?.mediaType || '')
+      const raw = String(identity.content || '').trim()
+      const body = mediaType === 'text/plain'
+        ? this.v4SanitizeDeliveryText(raw, Number.MAX_SAFE_INTEGER)
+        : ''
+      return {
+        key,
+        artifactId,
+        receipt,
+        mediaType,
+        raw,
+        body,
+        header: `Artifact ${artifactId} from ${receipt.agentKind} work=${receipt.workItemId || receipt.phase}`,
+      }
+    })
+    if (!artifacts.length) return ''
+    const maximum = Number.isSafeInteger(limit) && limit >= 0 ? limit : 3600
+    const textArtifacts = artifacts.filter(artifact => artifact.mediaType === 'text/plain'
+      && artifact.body)
+    const fixedOmissions = artifacts.flatMap((artifact) => {
+      if (artifact.mediaType !== 'text/plain') {
+        return [`${artifact.artifactId} reason=non-text mediaType=${artifact.mediaType || 'unknown'}`]
+      }
+      if (!artifact.raw) return [`${artifact.artifactId} reason=empty`]
+      return artifact.body === artifact.raw
+        ? []
+        : [`${artifact.artifactId} reason=safety-filter`]
+    })
+    const potentialBudgetOmissions = textArtifacts.map(artifact => (
+      `${artifact.artifactId} reason=budget`
+    ))
+    const structuralLines = [
+      'MELDWORK_V4_REFERENCED_ARTIFACTS_V1',
+      ...artifacts.map(artifact => artifact.header),
+    ]
+    const reservedManifest = [...fixedOmissions, ...potentialBudgetOmissions]
+    const reservedLines = reservedManifest.length
+      ? [...structuralLines, 'MELDWORK_V4_OMITTED_ARTIFACT_BODIES_V1', ...reservedManifest]
+      : structuralLines
+    const bodySeparators = textArtifacts.length
+    const bodyBudget = maximum - reservedLines.join('\n').length - bodySeparators
+    if (bodyBudget < 0) throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+    let remaining = bodyBudget
+    let remainingArtifacts = textArtifacts.length
+    const includedByKey = new Map()
+    for (const artifact of textArtifacts) {
+      const share = remainingArtifacts > 0 ? Math.floor(remaining / remainingArtifacts) : 0
+      const included = artifact.body.slice(0, Math.max(0, share))
+      includedByKey.set(artifact.key, included)
+      remaining -= included.length
+      remainingArtifacts -= 1
+    }
+    const budgetOmissions = textArtifacts.filter(artifact => (
+      includedByKey.get(artifact.key).length < artifact.body.length
+    )).map(artifact => `${artifact.artifactId} reason=budget`)
+    const lines = ['MELDWORK_V4_REFERENCED_ARTIFACTS_V1']
+    for (const artifact of artifacts) {
+      lines.push(artifact.header)
+      const included = includedByKey.get(artifact.key) || ''
+      if (included) lines.push(included)
+    }
+    const omissions = [...fixedOmissions, ...budgetOmissions]
+    if (omissions.length) {
+      lines.push('MELDWORK_V4_OMITTED_ARTIFACT_BODIES_V1', ...omissions)
+    }
+    const result = lines.join('\n')
+    if (result.length > maximum) throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+    return result
+  },
+
+  v4DeliveryPrompt(group, controller, input) {
+    const {
+      kind, phase, snapshot, receiptRecords, role, targetKinds, slot, options,
+      sessionBinding, skillHints = [],
+    } = input
+    const full = sessionBinding.sessionRotated === true || sessionBinding.hasSession !== true
+    const packageFloor = phase === 'proposal' ? 0 : collaborationPackageIndexText(targetKinds).length
+    let remaining = 6000 - packageFloor
+    let assignedProposalText = phase === 'challenge'
+      ? this.v4SanitizeDeliveryText(options.assignedProposalText || '', 1600)
+      : ''
+    if (assignedProposalText) {
+      remaining = Math.max(0, remaining - 2)
+      assignedProposalText = assignedProposalText.slice(0, remaining)
+      remaining -= assignedProposalText.length
+    }
+    const rawExtraContext = String(options.extraContext || '').trim()
+    const requestedExtraContext = this.v4SanitizeDeliveryText(rawExtraContext, 6000)
+    const artifactContextPlan = options.artifactContext?.coordinationPlan || null
+    const structuredArtifactContext = ['synthesis', 'verification'].includes(phase)
+      && options.artifactContext && typeof options.artifactContext === 'object'
+      && !Array.isArray(options.artifactContext)
+    if ((phase === 'work' || structuredArtifactContext) && rawExtraContext.length > 6000) {
+      throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+    }
+    if ((phase === 'work' || structuredArtifactContext)
+        && requestedExtraContext !== rawExtraContext) {
+      throw new Error('LOCAL_RUN_V4_ASSIGNMENT_REFERENCE_INVALID')
+    }
+    const extraLimit = Math.max(0, remaining - 2)
+    let extraContext = requestedExtraContext
+    if (structuredArtifactContext) {
+      const artifactLimit = extraLimit - (extraContext ? extraContext.length + 2 : 0)
+      const artifactContext = this.v4ArtifactContext(
+        receiptRecords,
+        phase,
+        artifactContextPlan,
+        kind,
+        Math.max(0, artifactLimit),
+      )
+      extraContext = [extraContext, artifactContext].filter(Boolean).join('\n\n')
+      if (extraContext.length > extraLimit) {
+        throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+      }
+    } else if (extraContext.length > extraLimit) {
+      if (phase === 'work') throw new Error('LOCAL_RUN_V4_DELIVERY_BUDGET_EXCEEDED')
+      const marker = 'MELDWORK_V4_CONTEXT_TRUNCATED_V1'
+      if (extraLimit <= marker.length + 1) {
+        extraContext = ''
+      } else {
+        let prefix = extraContext.slice(0, extraLimit - marker.length - 1)
+        const boundary = prefix.lastIndexOf('\n')
+        if (boundary > 0) prefix = prefix.slice(0, boundary)
+        extraContext = `${prefix.trimEnd()}\n${marker}`
+      }
+    }
+    if (extraContext) remaining -= extraContext.length + 2
+    const packageRecord = phase === 'proposal'
+      ? null
+      : this.v4Package(receiptRecords, {
+          recipientKind: kind,
+          sessionBinding,
+          deliveryState: controller.orchestration?.deliveryState || [],
+          targetKinds,
+          snapshotHash: controller.orchestration?.snapshotHash,
+          forceFull: full,
+          totalLimit: packageFloor + remaining,
+        })
+    const deliveryId = `delivery-${hashValue({
+      runId: controller.runId, recipientKind: kind, slotId: slot.slotId,
+      operationId: slot.operationId, packageHash: packageRecord?.packageHash || '', now: Date.now(),
+    }).slice(0, 64)}`
+    const delivery = packageRecord?.receipts?.length ? {
+      deliveryId,
+      packageHash: packageRecord.packageHash,
+      entries: packageRecord.receipts.map(receipt => ({
+        recipientKind: kind,
+        sessionRefHash: sessionBinding.sessionRefHash,
+        sessionProvenanceHash: sessionBinding.sessionProvenanceHash,
+        sourceAgentKind: receipt.agentKind,
+        sourcePhase: receipt.phase,
+        watermark: receipt.deliveryWatermark,
+        snapshotHash: receipt.snapshotHash,
+        operationId: receipt.operationId,
+        packageHash: packageRecord.packageHash,
+        deliveryId,
+        status: 'prepared',
+        updatedAt: Date.now(),
+      })),
+    } : null
+    this.v4PrepareDelivery(group, controller, delivery)
+    return {
+      prompt: this.v4PhasePrompt(group, kind, phase, snapshot, receiptRecords, role, {
+        reviewTarget: options.reviewTarget,
+        assignedProposalText,
+        packageText: packageRecord?.text || '',
+        extraContext,
+        snapshotHash: controller.orchestration?.snapshotHash,
+        skillHints,
+      }),
+      delivery,
+    }
+  },
+
+  v4PrepareDelivery(group, controller, delivery) {
+    if (delivery) {
+      const replaced = new Set(delivery.entries.map(entry => [
+        entry.recipientKind, entry.sessionRefHash, entry.sessionProvenanceHash,
+        entry.sourceAgentKind, entry.sourcePhase,
+      ].join('\u0000')))
+      const deliveryState = [
+        ...(controller.orchestration?.deliveryState || []).filter(entry => (
+          (!delivery.natural || entry.recipientKind !== delivery.entries[0].recipientKind
+            || (entry.sessionRefHash === delivery.entries[0].sessionRefHash
+              && entry.sessionProvenanceHash === delivery.entries[0].sessionProvenanceHash))
+          && !replaced.has([
+          entry.recipientKind, entry.sessionRefHash, entry.sessionProvenanceHash,
+          entry.sourceAgentKind, entry.sourcePhase,
+        ].join('\u0000')))),
+        ...delivery.entries,
+      ].sort((left, right) => [
+        left.recipientKind, left.sessionRefHash, left.sessionProvenanceHash,
+        left.sourceAgentKind, left.sourcePhase,
+      ].join('\u0000').localeCompare([
+        right.recipientKind, right.sessionRefHash, right.sessionProvenanceHash,
+        right.sourceAgentKind, right.sourcePhase,
+      ].join('\u0000')))
+      this.checkpointOrchestration(group, controller, { deliveryState })
+    }
+  },
+
+  v4SetDeliveryStatus(group, controller, delivery, status, binding = null) {
+    if (!delivery?.entries?.length) return
+    const deliveryState = (controller.orchestration?.deliveryState || []).map(entry => {
+      const matched = delivery.entries.some(candidate => candidate.deliveryId === entry.deliveryId
+        && candidate.sourceAgentKind === entry.sourceAgentKind
+        && candidate.sourcePhase === entry.sourcePhase
+        && entry.status === 'prepared')
+      let sourceMessages = entry.sourceMessages
+      if (matched && sourceMessages && status === 'acknowledged'
+          && binding?.sessionRefHash === entry.sessionRefHash
+          && binding?.sessionProvenanceHash === entry.sessionProvenanceHash) {
+        const previous = delivery.previousEntries?.find(candidate => (
+          candidate.sourceAgentKind === entry.sourceAgentKind
+          && candidate.sourcePhase === entry.sourcePhase
+        ))
+        sourceMessages = [...new Map([
+          ...(previous?.sourceMessages || []), ...sourceMessages,
+        ].map(message => [message.id, message])).values()].slice(-100)
+      }
+      return matched ? {
+        ...entry,
+        ...(sourceMessages ? { sourceMessages } : {}),
+        ...(binding ? {
+          sessionRefHash: binding.sessionRefHash,
+          sessionProvenanceHash: binding.sessionProvenanceHash,
+        } : {}),
+        status,
+        updatedAt: Date.now(),
+      } : entry
+    }).sort((left, right) => [
+      left.recipientKind, left.sessionRefHash, left.sessionProvenanceHash,
+      left.sourceAgentKind, left.sourcePhase,
+    ].join('\u0000').localeCompare([
+      right.recipientKind, right.sessionRefHash, right.sessionProvenanceHash,
+      right.sourceAgentKind, right.sourcePhase,
+    ].join('\u0000')))
+    this.checkpointOrchestration(group, controller, { deliveryState })
+  },
+
+  v4ChallengeTarget(kind, targetKinds, round = 1, seed = '') {
+    const kinds = Array.isArray(targetKinds) ? targetKinds : []
+    const index = kinds.indexOf(kind)
+    if (index < 0 || kinds.length < 2) return ''
+    const digest = createHash('sha256').update(JSON.stringify([seed, round, kinds])).digest('hex')
+    const offset = 1 + (Number.parseInt(digest.slice(0, 8), 16) % (kinds.length - 1))
+    return kinds[(index + offset) % kinds.length] || ''
+  },
+
+  v4ChallengeBindings({ controller, targetKinds, round, snapshotRecord, slots, receiptRecords }) {
+    const kinds = [...new Set(Array.isArray(targetKinds) ? targetKinds : [])].sort()
+    if (kinds.length < 2 || !Number.isSafeInteger(round) || round < 2) {
+      throw new Error('LOCAL_RUN_V4_CHALLENGE_BINDING_INVALID')
+    }
+    const digest = createHash('sha256').update(JSON.stringify([
+      snapshotRecord?.bodyHash || '', kinds,
+    ])).digest('hex')
+    const initialOffset = 1 + (Number.parseInt(digest.slice(0, 8), 16) % (kinds.length - 1))
+    const offset = 1 + ((initialOffset - 1 + (round - 2)) % (kinds.length - 1))
+    const slotsByKind = new Map(slots.map(slot => [slot.agentKind, slot]))
+    const proposalsByKind = new Map()
+    for (const record of receiptRecords) {
+      const receipt = record?.receipt
+      if (receipt?.phase === 'proposal' && kinds.includes(receipt.agentKind)) {
+        proposalsByKind.set(receipt.agentKind, receipt)
+      }
+    }
+    return kinds.map((reviewerKind, index) => {
+      const proposalKind = kinds[(index + offset) % kinds.length]
+      const reviewerSlot = slotsByKind.get(reviewerKind)
+      const proposalSlot = slotsByKind.get(proposalKind)
+      const proposalReceipt = proposalsByKind.get(proposalKind)
+      if (!reviewerSlot || !proposalSlot || !proposalReceipt) {
+        throw new Error('LOCAL_RUN_V4_CHALLENGE_BINDING_INVALID')
+      }
+      return {
+        round,
+        reviewerKind,
+        reviewerSlotId: reviewerSlot.slotId,
+        reviewerOperationId: this.v4OperationId(
+          controller, reviewerKind, 'challenge', reviewerSlot.slotId,
+        ),
+        proposalKind,
+        proposalSlotId: proposalSlot.slotId,
+        proposalOperationId: proposalReceipt.operationId,
+        proposalReceiptId: proposalReceipt.receiptId,
+        artifactIds: [...(proposalReceipt.artifactIds || [])],
+        evidenceIds: [...(proposalReceipt.evidenceIds || [])],
+      }
+    })
+  },
+
+  v4PhasePrompt(group, kind, phase, snapshot, receiptRecords, role, options = {}) {
+    const collaborationPackage = phase === 'proposal'
+      ? ''
+      : String(options.packageText || this.v4Package(receiptRecords, {
+          recipientKind: kind,
+          forceFull: options.forceFullPackage === true,
+          snapshotHash: options.snapshotHash,
+        }).text)
+    const reviewTarget = phase === 'challenge' ? String(options.reviewTarget || '') : ''
+    const assignedProposalText = phase === 'challenge'
+      ? this.v4SanitizeDeliveryText(options.assignedProposalText || '', 1600) : ''
+    const extraContext = this.v4SanitizeDeliveryText(options.extraContext || '', 6000)
+    return [
+      v4Prompt({
+        group, kind, phase, snapshot, role, skillHints: options.skillHints,
+        knowledgeBaseHints: options.knowledgeBaseHints,
+        naturalResponse: this.naturalAgentResponses,
+      }),
+      reviewTarget
+        ? `Coverage responsibility: explicitly incorporate or challenge ${reviewTarget}'s proposal while negotiating with every peer. This coverage duty does not assign responsibilities or authorize you to allocate work for others.`
+        : '',
+      assignedProposalText,
+      collaborationPackage
+        ? `Selected records from completed phases:\n${collaborationPackage}`
+        : '',
+      extraContext,
+    ].filter(Boolean).join('\n\n')
+  },
+}
+
+module.exports = { v4DeliveryMethods }