P0: cut over DevSpace local-agent lifecycle to HerdR production backend

[James3014]

Goal

Make HerdR the authoritative execution backend for normal DevSpace local-agent dispatch, without moving DevSpace authority into HerdR.

Current main at creation:
8436fa8ab50e807019a436eec7cf49430695d849

Current state:

• P0: qualify HerdR as the durable external coding-agent runtime substrate #235 qualified HerdR v0.9.1 as a durable external-agent runtime substrate.
• P0: implement thin DevSpace -> HerdR external-agent runtime gateway #236 merged the thin DevSpace -> HerdR gateway and post-merge verified it, including live OpenCode and Agy canaries.
• M5 runtime is converged on current main and the HerdR daemon is running.
• Production agent_start still enters the existing launchPrompt()/spawnWorker() provider-launch path; ordinary dispatch is therefore not yet HerdR-backed.

Authority boundary

DevSpace continues to own:

• workspace identity and isolation;
• attemptKey and DispatchIntent identity;
• execution contract and write scope;
• retry/replay admission;
• Candidate / physical Git evidence / reconciliation;
• acceptance / merge / release authority.

HerdR owns only:

• PTY / process / pane / agent launch;
• prompt delivery / wait / read;
• detach / reconnect;
• native agent/session metadata.

Hard invariants:

• no silent fallback from HerdR to the legacy provider launcher after an admitted HERDR attempt;
• OUTCOME_UNKNOWN != retry permission;
• daemon/socket identity is part of execution identity;
• provider/model observed truth must not be filled from expected configuration;
• AUTO_CHAIN=false;
• P1: bind authorized tool ceiling to durable agent execution and project selected tools at provider boundary #190 tool/effect enforcement ceiling remains truthful; this issue must not claim physical tool enforcement that has not been proven.

Wave 1 — Cutover spine

Wire the public DevSpace local-agent lifecycle to HerdrThinGateway for the HERDR backend:

• start / first prompt;
• continue / prompt;
• status / wait/read;
• reconcile;
• cancel/stop.

Required behavior:

• durable HERDR handle is persisted before consequential continuation;
• restart/reconnect reuses the exact external effect identity;
• HerdR unavailable / wrong socket / wrong agent / ambiguous ack fails closed;
• no automatic legacy fallback;
• legacy launcher remains available only as an explicit rollback backend, not an implicit recovery path.

Gate W1

• source tests cover all lifecycle entrypoints through HerdR;
• existing P0: implement thin DevSpace -> HerdR external-agent runtime gateway #236 lost-ack / forged-handle / cross-socket / restart controls remain green;
• store + sessions + HerdR suites green;
• typecheck/build/diff-check green;
• no provider-specific policy is moved into HerdR.

Stop claim: HERDR_PUBLIC_LIFECYCLE_CANDIDATE_READY.

Wave 2 — M5 production activation with OpenCode + Agy

Activate HerdR as the default backend on the M5 production-shaped DevSpace runtime for the two already-qualified heterogeneous providers:

• OpenCode;
• Agy.

Required live witnesses must enter through the real public DevSpace dispatch lifecycle, not by directly calling the gateway test seam:

• agent_start -> HerdR;
• prompt/continue -> same HerdR agent;
• status/read -> same pane/agent;
• reconcile -> physical Git evidence;
• cancel/stop -> exact durable handle;
• DevSpace restart -> same attempt reconciles without duplicate worker;
• HerdR daemon unavailable -> fail closed, no legacy fallback.

Also bind service readiness:

• HerdR daemon supervised/started on boot or equivalent managed service;
• exact socket identity/readiness checked before HERDR admission;
• daemon restart behavior truthfully classified.

Gate W2

• OpenCode real public-path canary PASS;
• Agy real public-path canary PASS;
• restart/reconcile PASS with zero duplicate worker;
• runtime receipt/readback identifies runtimeKind=HERDR and exact socket/agent identity;
• current M5 DevSpace build and HerdR daemon identities are recorded.

Stop claim: HERDR_DEFAULT_ACTIVE_OPENCODE_AGY.

Wave 3 — Provider breadth qualification

Qualify additional local agents through the same public HerdR path:

Codex

• current executable/auth state;
• valid account-supported model/default selection;
• start/prompt/read/reconcile/stop;
• restart/reconcile.

Cline

• establish a supported runtime/Node combination;
• prove CLI readiness/capability;
• start/prompt/read/reconcile/stop;
• restart/reconcile.

Grok

• establish M5 authentication;
• start/prompt/read/reconcile/stop;
• restart/reconcile.

Each provider is independently pass/fail; one provider must not block the others.

Gate W3

• per-provider live receipt bound to host/runtime/version;
• no provider-specific silent fallback;
• failed provider remains disabled/blocked rather than weakening the HERDR backend.

Stop claim: HERDR_PROVIDER_BREADTH_QUALIFIED for only the providers that physically pass.

Wave 4 — Soak and legacy-retirement decision

Do not remove the legacy provider launcher in the same cutover mutation.

After W2 (and optionally W3) is active:

• observe bounded real task usage;
• verify no duplicate process/session families;
• verify restart/reconciliation behavior under ordinary use;
• verify rollback procedure;
• decide whether legacy provider adapters can be retired or retained as an explicit non-default rollback path.

Legacy retirement, if desired, should be a separate follow-up Issue after soak evidence.

Gate W4

• bounded soak evidence exists;
• rollback path is documented and tested;
• Owner decision recorded: retain explicit rollback backend OR open separate retirement Issue.

Stop claim: HERDR_CUTOVER_STABLE.

Existing related Issues

• P0: qualify HerdR as the durable external coding-agent runtime substrate #235 — runtime qualification; should close as completed after this successor is bound.
• P0: implement thin DevSpace -> HerdR external-agent runtime gateway #236 — thin gateway; CLOSED / merged.
• P1: bind authorized tool ceiling to durable agent execution and project selected tools at provider boundary #190 — physical tool/effect enforcement; remains OPEN and continues to limit high-risk production mutation claims.
• P0: fix ChatGPT↔DevSpace caller continuity, live tool projection, and evidence-chain liveness #240 — ChatGPT↔DevSpace caller/tool-projection/evidence continuity; separate control-plane reliability work and must not block this cutover.

Non-goals

• solving P1: bind authorized tool ceiling to durable agent execution and project selected tools at provider boundary #190 physical tool enforcement;
• solving P0: fix ChatGPT↔DevSpace caller continuity, live tool projection, and evidence-chain liveness #240 caller/tool schema continuity;
• changing CapabilityPlanner authority;
• provider-specific model routing policy;
• deleting all legacy adapters during initial cutover;
• automatic failover to a different execution backend;
• automatic retry after ambiguous external effect;
• merge/release authority inside HerdR.

Execution order

W1 -> W2 -> W3

W4 follows W2 after bounded real use; W3 provider sub-lanes may proceed independently after W2.

Recommended implementation batching:

• one bounded implementation cycle may do W1 + W2 together because P0: implement thin DevSpace -> HerdR external-agent runtime gateway #236 already proves the gateway primitives and OpenCode/Agy live behavior;
• do not include W3 Cline/Codex/Grok repairs in that same mutation unless they require no source changes beyond configuration/auth;
• do not combine legacy-adapter deletion with W1/W2.

Priority: P0 production cutover.

---

Reconciliation — 2026-09-25 relationship to #256

Fresh DevSpace main: 80a238da61112cabf18bcb44a912e3f0daceba2d.

#256 is now the single umbrella for stale HerdR lifecycle/capacity reconciliation. Several bounded #256 variants have merged and are already helping W2 cutover work, so #256 does not block bounded provider canaries or ordinary W2 evidence collection by itself.

However, the final W4 claim HERDR_CUTOVER_STABLE requires that #256 reach a truthful terminal state (or that a fresh reconciliation proves no unresolved stale-capacity class is material to the W4 soak contract).

Therefore:

W2 provider canaries / activation evidence
    || #256 lifecycle-family reconciliation

W4 HERDR_CUTOVER_STABLE
    -> requires #256 terminal/reconciled stale-capacity invariant

Do not open additional HerdR stale-capacity Issues for variants that belong to #256 unless a newly observed mechanism has a different authority owner or independent completion state.

---

Reconciliation — 2026-09-26 #256 closure and current frontier

Fresh source/closure watermark:

• DevSpace main: 3d8f522b5bbe7723232967bb0811fdc5b66f1a2d
• main tree: 5003ee40fb984f2b144c10b5e5e544a559a43f52
• fix(herdr): reconcile stale lifecycle and capacity safely (#256) #278: merged
• P0: stale HerdR agent states can permanently exhaust local execution capacity #256: closed / completed

#256's stale HerdR lifecycle/capacity family is now source/test closed on current main. The merged path requires exact external absence plus attributable physical workspace evidence before reclaim, keeps unreachable/identity-mismatch/unknown states fail-closed, and distinguishes verified live HerdR capacity from unresolved stale capacity.

Post-merge current-main verification:

• npm run typecheck — PASS
• P0: stale HerdR agent states can permanently exhaust local execution capacity #256 lifecycle matrix — PASS
• observed-launch absence / identity-mismatch gateway witness — PASS
• merge tree exactly equals the independently verified Candidate tree 5003ee40fb984f2b144c10b5e5e544a559a43f52
• exact-head GitHub CI and Repository Intelligence — PASS

#242 effect

The #256 prerequisite is satisfied. It is no longer a blocker for W2/W3 execution or W4 stale-capacity safety.

This does not establish:

• W2 HERDR_DEFAULT_ACTIVE_OPENCODE_AGY;
• current serving M5 DevSpace build/runtime convergence;
• W3 provider breadth classifications on the current serving runtime;
• W4 bounded soak / rollback / HERDR_CUTOVER_STABLE.

The prior 2026-09-25 serving-runtime/carrier observations are historical watermarks and must not be assumed current.

Exact next gate

ISSUE242_REBIND_CURRENT_M5_RUNTIME_THEN_W2_PUBLIC_CANARIES

1. fresh-read the serving M5 DevSpace build/source and HerdR daemon/socket identity;
2. if serving runtime is behind main@3d8f522..., perform the already-governed typed cutover rather than reopening source repair;
3. run real public-path OpenCode + Agy agent_start -> continue/status/reconcile/cancel witnesses on that serving runtime;
4. prove restart/reconcile zero-duplicate behavior and HerdR-unavailable fail-closed/no-legacy-fallback;
5. then refresh the W3 free-first provider matrix for OpenCode/Cline/Agy/Codex/Grok under the existing contract delta.

#242 remains OPEN until those runtime gates are physically established.

[James3014]

Reconciliation — 2026-09-25

Current source watermark: 549cba9f965c64e7e7c494eba6df61863628ed5f.

Source-side #242 status:

• W1 public lifecycle cutover is merged via PR P0: cut over DevSpace local-agent lifecycle to HerdR backend (#242) #243; public start/continue/status/reconcile/cancel has a HERDR backend path.
• W2 follow-up fixes are merged, including PR fix: preserve direct read-only continuation admission (#242) #244 (read-only continuation), PR fix: scope HerdR handle authority by workspace (#242) #249 (workspace-scoped HerdR handle authority), PR fix: reclaim stale HerdR capacity slots on verified agent absence (#242) #250 (verified stale-slot reclaim), and PR fix: preserve OpenCode permission authority through HerdR (#242) #267 (OpenCode permission/tool projection through HerdR).
• PR test: align HerdR replay and close-effect expectations (#242) #265 already aligned the two stale HerdR test expectations that failed on older main; no duplicate test-only repair is needed.
• PR fix: preserve OpenCode permission authority through HerdR (#242) #267 records an M5 live OpenCode canary after the permission projection fix.

Current production-runtime gap:

• M5 serving DevSpace is still devspace-1.0.7-973b507a / source 973b507a157ddf16b8db2bc9349f691befee7c83, not current main.
• On that old runtime, agent_preflight remains blocked at 4/4 local slots by stale durable sessions. This is exactly the class addressed by fix: reclaim stale HerdR capacity slots on verified agent absence (#242) #250, but fix: reclaim stale HerdR capacity slots on verified agent absence (#242) #250 is not active until the runtime is upgraded.
• Because capacity admission fails before a new turn can start, a fresh public-path Agy agent_start -> HERDR witness cannot currently be produced on the serving build.

Therefore #242 must remain OPEN. Source convergence is ahead of runtime convergence.

Exact next gate for W2 closure:

1. Cut over the M5 DevSpace service from 973b507a to current accepted main/build.
2. Re-run public-path OpenCode and Agy canaries through agent_start, requiring returned durable runtime evidence runtimeKind=HERDR plus exact socket/workspace/pane/agent identity.
3. Verify agent_continue, agent_status, agent_reconcile, and agent_cancel on the same durable HerdR identity.
4. Verify restart/reconcile with zero duplicate worker and HerdR-unavailable fail-closed/no-legacy-fallback behavior.

Until those runtime witnesses exist, do not claim HERDR_DEFAULT_ACTIVE_OPENCODE_AGY or close W2. W3/W4 remain separate follow-on gates.

Marker: ISSUE242_SOURCE_AHEAD_RUNTIME_CUTOVER_REQUIRED_20260925_V1

[James3014]

Owner target: complete public HerdR cutover + provider breadth

Owner direction for the current execution is to complete the user-facing two-wave goal:

1. production M5 Dev MCP -> HerdR cutover and public-path OpenCode/Agy verification;
2. public HerdR breadth qualification for Codex/Cline/Grok.

Fresh source/runtime watermark:

• GitHub main: 549cba9f965c64e7e7c494eba6df61863628ed5f
• serving M5 DevSpace: 973b507a157ddf16b8db2bc9349f691befee7c83 / devspace-1.0.7-973b507a
• state: source ahead of runtime.

Prepared exact-main build workspace:

• durable clone operation: op_46dbd4efddf2e920
• root: /Users/james/.devspace/worktrees/issue242-w1-549cba9f
• workspace: ws_5c3eda9ae3
• HEAD: 549cba9f965c64e7e7c494eba6df61863628ed5f
• clean.

Fresh old-runtime host readiness before cutover:

• OpenCode: executable/runtime ready; catalog includes active mimo-v2.6-flash-free; admission blocked only by stale 4/4 local slots.
• Agy: /Users/james/.local/bin/agy, v1.2.10; runtime ready; admission blocked only by stale 4/4 local slots.
• Codex: runtime executable currently resolves to old packaged Codex 0.149.0 on serving build; admission blocked by stale 4/4 local slots; valid post-cutover model/default still requires live qualification.
• Cline: /Users/james/.local/bin/cline, v3.0.65; catalog is now healthy and exposes ready/free routes including cline-free/mimo-v2.6-flash; admission blocked only by stale 4/4 local slots.
• Grok: /Users/james/.grok/bin/grok, v1.0.41; runtime ready; auth/reachability require live post-cutover witness; admission blocked by stale 4/4 local slots.

The common NO_EXECUTION_CAPACITY blocker is the old-runtime stale-session class already addressed by merged #250; no stale-session cleanup/retry was attempted on the old build.

Current exact gate

The typed dependency_sync / cutover control plane requires a locally Owner-approved carrier. The current M5 Remote Desktop Commander endpoint is offline; M4 is online but M5 SSH/Remote Login is not enabled. DevSpace correctly refuses MCP self-approval. No carrier bypass, direct SQLite write, permission expansion, or blind stale-agent cancellation is authorized.

Therefore the next physical step is: restore an Owner-local command path on M5 (Remote Desktop Commander or direct terminal), approve one bounded carrier, then continue frozen dependency sync -> build -> typed cutover -> public HerdR canaries.

Do not reopen source repair work before that local approval gate is satisfied.