Summary

• Problem: Hub sessions (WebChat, WeChat, and other main chat surfaces) need persistent external ACP harness workers without binding a Discord/Telegram thread. The existing ACP persistent path requires mode: "session" plus thread: true, which is unavailable or awkward on many hub channels.
• Why it matters now: Dogfooding hub → Codex/Claude Code delegation from a single visible chat requires a named worker that stays alive across turns, accepts follow-ups by label, and does not echo A2A ping-pong back into the hub.
• Intended outcome: A hub agent can sessions_spawn({ runtime: "acp", delegate: true, label?, task }), follow up with sessions_send(label=...), list owned workers via sessions_list({ delegated: true }), and operators inspect or close workers with /acp delegate list|status|close <label>. Persistent harness teardown for hub-delegated workers is operator-facing (/acp delegate close) plus maintenance idle/max-age sweeps — the same lifecycle model documented in docs/tools/acp-agents.md.
• Success looks like: Hub-delegated workers spawn without thread binding, survive after the first task, honor follow-ups without A2A echo loops, auto-close on idle/max-age policy, and remain discoverable by label for both agents and operators.
• Reviewers should focus on: Owner-boundary correctness for hubDelegated metadata and label follow-up, A2A skip conditions for parent-owned delegates, lifecycle maintenance/close ordering (acp.delegate.*), fail-closed ACP metadata/session-id/repair boundaries, owner-scoped label uniqueness (spawn pre-check and sessions.patch), and JSON-store vs sqlite discovery parity for operator /acp delegate vs maintenance.

ACP spawn shapes (scope boundary)

Three sessions_spawn({ runtime: "acp", ... }) paths — this PR delivers row 3 only:

This PR delivers: hub-delegated persistent workers (row 3) for WebChat/WeChat and other non-thread hub surfaces.

Does not change: row 1 (mode: "run") and row 2 (thread-bound persistent ACP). Broader decoupled-session / global session-management work stays out of scope — see Linked context.

Full product docs: docs/tools/acp-agents.md (Hub-delegated persistent workers).

Design rationale: why delegate instead of relaxing mode: "session"?

Short answer: persistence alone is under-specified. mode: "session" today means thread-visible persistent ACP (follow-up in the bound thread, close via /acp close). Hub orchestration needs a different contract: parent-owned background worker, label-routed follow-up via sessions_send, skip A2A for owner sends, and operator/maintenance close — not “same persistent session, minus thread.”

Why not { mode: "session" } without thread: true?

• Runtime would not know follow-up surface (thread message vs hub label), visibility (channel thread vs internal worker), close owner (/acp close vs /acp delegate close + acp.delegate.*), or label rules (global vs owner-scoped).
• That conflates at least three persistent shapes: thread-bound session, hub-delegated worker (this PR), and cron/hook affinity — each with different owner and lifecycle invariants.
• Today mode: "session" without thread fail-closes on purpose; silently allowing it would create persistent workers without an explicit product contract.

What delegate: true buys:

• Explicit opt-in to the hub worker bundle: hubDelegated ownership, owner-scoped labels, parent relay semantics, /acp delegate operator surface, and maintenance policy — without changing row 1 (run) or row 2 (thread session) behavior.

Relationship to #53548: this PR delivers the hub/orchestrator slice only; it does not generalize decoupled mode: "session" for all channels or requesters.

Architecture (hub → ACP worker)

Hub-delegated workers are parent-owned background ACP sessions. The hub session stays the only user-visible chat surface; the harness worker stays alive off-channel and is addressed by label, not by opening a Discord/Telegram thread.

Component map

flowchart LR
  subgraph Visible["User-visible hub surface"]
    U[User]
    CH["Channel adapter WebChat WeChat etc"]
    HUB["Hub session agent main webchat main"]
  end

  subgraph Worker["Parent-owned ACP worker background"]
    ACP["Persistent ACP session agent codex acp"]
    HX["External harness Codex Claude Code etc"]
  end

  subgraph Meta["Ownership and naming"]
    HD["hubDelegated ownerSessionKey plus label per owner"]
  end

  subgraph Lifecycle["Operator and maintenance"]
    OPS["acp delegate list status close"]
    SWP["Idle and max-age maintenance"]
  end

  U --> CH --> HUB
  HUB -->|sessions_spawn delegate true| ACP
  HUB -->|sessions_send by label| ACP
  ACP --> HX
  HUB --- HD
  ACP --- HD
  OPS --> HD
  SWP --> HD
  HUB -->|summarize or relay| CH --> U

Key invariant: the worker does not bind a channel thread/topic. Follow-ups reuse the same harness session via label; the hub agent decides what (if anything) to publish back to the visible channel.

1) Initial spawn (first task)

sequenceDiagram
  autonumber
  actor User
  participant Channel
  participant Hub as Hub session
  participant Spawn as sessions_spawn
  participant GW as Gateway
  participant Worker as ACP worker
  participant Harness as Harness runtime

  User->>Channel: task or message
  Channel->>Hub: inbound dispatch
  Hub->>Spawn: delegate true plus task and optional label
  Spawn->>GW: sessions patch hubDelegated label spawnedBy
  Spawn->>GW: initialize persistent ACP runtime
  GW->>Worker: create worker and store marker
  Worker->>Harness: run initial task
  Harness-->>Worker: progress and result
  Worker-->>Hub: optional progress stream silent notify
  Hub-->>Channel: hub agent reply
  Channel-->>User: response

Notes for reviewers:

• No thread: true and no channel binding record is required.
• delegate: true implies persistent mode: "session"; one-shot mode: "run" is rejected.
• Label is optional; when omitted OpenClaw assigns delegate-YYYYMMDD-HHMMSS (UTC) and returns it in the spawn result.

2) Follow-up turns (send by label)

sequenceDiagram
  autonumber
  actor User
  participant Channel
  participant Hub as Hub session
  participant Send as sessions_send
  participant GW as Gateway
  participant Worker as ACP worker
  participant Harness as Harness runtime

  User->>Channel: follow-up message
  Channel->>Hub: inbound dispatch
  Hub->>Send: label plus message and timeout
  Send->>GW: sessions resolve label owner scoped
  GW-->>Send: worker session key
  Send->>GW: agent run and agent wait
  Note over Send,Worker: Parent-owned delegate skips A2A loop
  Worker->>Harness: continue persistent session
  Harness-->>Worker: assistant reply
  Worker-->>Send: waited reply snapshot
  Send-->>Hub: tool result
  Hub-->>Channel: hub agent relays or summarizes
  Channel-->>User: response

Notes for reviewers:

• sessions.resolve uses owner-scoped label matching for hub-delegated workers (not global label uniqueness across owners).
• Parent sessions_send into its own hub-delegated worker skips the A2A announce loop because the hub already owns the visible reply channel.
• Waited sessions_send reads the worker reply from canonical chat.history; hub-delegated turns stay off visible delivery surfaces but still persist assistant/user turns to the session transcript.
• Hub-delegated worker teardown is via /acp delegate close <label> (operator commands) and maintenance idle/max-age policy; thread-bound ACP sessions continue to use /acp close.

3) How this differs from thread-bound persistent ACP

Also bundled from live dogfood on this branch:

• P0: Fail-closed ACP runtime handle reuse after idle; force re-ensure before turn when TTL exceeded.
• P1: When agent.wait race returns null, abort both waiters immediately so sessions_send honors timeoutSeconds (default 30s) instead of blocking for minutes.

Linked context

Which issues, PRs, or discussions are related?

• Related Decouple mode="session" from thread binding requirement #53548 — hub/orchestrator slice only (delegate: true + sessions_send(label=…)). Does not close or replace the full decoupled-session ask.

Does not address:

• Thread-bound persistent ACP (thread: true, /acp close) — unchanged.
• Generalized decoupled mode: "session" without delegate: true.
• Global session-management CLI/UI, cron/hook affinity reuse, channel spawn policy, and agent-tool sessions_close for hub-delegated workers (close is /acp delegate close + maintenance by design).

Was this requested by a maintainer or owner?

Local maintainer dogfood for hub → ACP delegation from WebChat/stable gateway (port 18789).

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Hub-delegated persistent ACP workers from a main chat surface; follow-up via label; no thread binding; no A2A echo loop; operator lifecycle via /acp delegate.
• Real environment tested: macOS local source-built OpenClaw gateway on port 18789 (~/.openclaw), WeChat hub session + WebChat delegated ACP worker session, Codex ACP harness via acpx. Close-path proof recorded against current head after the delegate label-routing close fix.
• Exact steps or command run after this patch:

1. From hub session: sessions_spawn({ runtime: "acp", delegate: true, agentId: "codex", task: "..." }) (with and without explicit label).
2. Follow up: sessions_send({ label: "<label>", message: "..." }).
3. List: sessions_list({ delegated: true }).
4. Operator: /acp delegate list, /acp delegate status <label>.
5. Close path (current head): /acp delegate close <label>, then /acp delegate list (expect empty), then sessions_send({ label: "<label>", message: "..." }) (expect rejected / no resolve).
6. Regression checks for idle reconnect (>10 min) and sessions_send timeout honoring (~30s default).

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Maintainer dogfood verified manually on stable gateway (port 18789). All proof uses screenshots (not video).

Screenshot 1 — hub-delegated ACP subagent spawn (sessions_spawn({ runtime: "acp", delegate: true, ... }); persistent mode: "session" worker created without thread: true):

Screenshot 2 — follow-up via sessions_send (hub session sends to the spawned worker by label):

Screenshot 3 — /acp delegate list empty after close (after /acp delegate close <label> on current head):

Screenshot 4 — sessions_send rejected after close (follow-up with the same closed delegate label):

• Observed result after fix:

• Hub-delegated spawn accepted without thread: true.

• Follow-ups by label work from the same hub session.

• sessions_list({ delegated: true }) returns owned workers.

• A2A follow-up skipped for parent-owned hub-delegated targets (delivery.status="skipped" path).

• Idle stale-handle reconnect and sessions_send timeout fixes verified after long-idle and short-wait scenarios.

• Spawn/follow-up (screenshots 1–2): hub-delegated spawn succeeds without thread: true; sessions_send({ label: "<label>", ... }) reaches the persistent worker and returns a reply.

• Close path (screenshots 3–4): /acp delegate close <label> succeeds; /acp delegate list and sessions_list({ delegated: true }) are empty afterward; follow-up sessions_send({ label: "<label>", ... }) is rejected and does not reopen the closed worker.

• What was not tested:

• timeoutSeconds: 0 fire-and-forget on hub-delegated follow-up.

• Remote Crabbox/Testbox or GitHub Actions CI (local CI only; see Tests section).

• Proof limitations or environment constraints: Proof is from a maintainer local environment, not Crabbox. Four screenshots above cover spawn, sessions_send follow-up, close, and post-close rejection; list/status and edge cases remain covered by unit tests. Duplicate-label conflict, owner-scoped label resolve, expired-delegate reactivation, and close-ordering edge cases remain covered by unit tests.

• Before evidence (optional but encouraged): Prior dogfood without P0/P1 fixes showed long idle turns hanging until ~900s and sessions_send waits exceeding configured timeout when race waiters stacked.

Tests and validation

Which commands did you run?

# Local changed CI (Crabbox unavailable on host; remote child disabled)
env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 pnpm check:changed

pnpm test:changed

# Targeted proof during development
pnpm test packages/acp-core/src/hub-delegated.test.ts
pnpm test src/acp/hub-delegated-lifecycle.test.ts
pnpm test src/agents/acp-spawn.test.ts -t "hub-delegated|auto-generates|duplicate hub-delegated"
pnpm test src/acp/control-plane/manager.runtime-handles.test.ts
pnpm test src/acp/control-plane/manager.repair-missing-metadata.test.ts
pnpm test src/acp/runtime/session-meta.test.ts
pnpm test src/tasks/task-registry.maintenance.hub-delegated.test.ts
pnpm test src/agents/openclaw-tools.sessions.test.ts -t "hub-delegated|label resolve"
pnpm test src/config/schema.test.ts -t "hub-delegated ACP lifecycle"
pnpm test src/gateway/server.chat.gateway-server-chat.test.ts

What regression coverage was added or updated?

• packages/acp-core/src/hub-delegated.test.ts — policy, ownership, expiry, auto-label generation/conflict suffix.
• packages/acp-core/src/session-interaction-mode.test.ts — hub-delegated parent-owned background classification.
• src/acp/hub-delegated-lifecycle.test.ts — JSON-store sweep without sqlite metadata, close ordering, expired-candidate resolution.
• src/commands/agent.acp.test.ts — hub-delegated ACP turns persist to canonical transcript for waited sessions_send.
• src/agents/acp-spawn.test.ts — delegate spawn, auto-label, delegate/thread conflict, duplicate label across ACP harness stores; concurrent auto-label suffix allocation under label lock.
• src/agents/openclaw-tools.sessions.test.ts — sessions_send skip-A2A for hub-delegated targets; owner-scoped label resolve via spawnedBy.
• src/acp/control-plane/manager.repair-missing-metadata.test.ts — hub-delegated persistent repair, one-shot repair, thread-bound binding-key repair, fail-closed with no evidence.
• src/acp/runtime/session-meta.test.ts — fail-closed session_id drift; explicit rebind only.
• src/tasks/task-registry.maintenance.hub-delegated.test.ts — expired delegate maintenance via JSON-store sweep and marker-first close.
• src/config/schema.test.ts — acp.delegate.* accepted by strict schema.
• Gateway/agent tests, ACP manager runtime-handle tests, sessions patch/resolve tests, command tests — hub-delegated metadata, list filter, delegate slash commands, idle reconnect, timeout race.
• User docs: docs/tools/acp-agents.md, docs/concepts/session-tool.md, docs/gateway/configuration-reference.md.

What failed before this fix, if known?

• check:changed initially failed on src/agents/tools/sessions-spawn-tool.ts TS5076 (??/|| mixing); fixed with parentheses before CI green.
• Pre-P0: reused stale ACP socket after idle caused turns to hang until long timeout.
• Pre-P1: sessions_send could block far longer than timeoutSeconds when agent.wait race returned null but left a waiter alive.

If no test was added, why not?

Targeted unit/integration coverage was added for the main contracts above. Full channel-matrix live proof remains manual dogfood.

Risk checklist

Did user-visible behavior change? (Yes)

Yes. New hub-delegated ACP worker shape, new /acp delegate operator commands, optional auto-generated delegate labels, owner-scoped label follow-up, and user-facing docs for the flow. Existing thread-bound and one-shot ACP paths are unchanged unless the caller opts into delegate: true.

Did config, environment, or migration behavior change? (Yes)

Yes, additive only: acp.delegate.idleHours (default 72) and acp.delegate.maxAgeHours (default 168). Keys are now schema-valid with label/help metadata. No doctor migration required; defaults apply to new hub-delegated workers.

Did security, auth, secrets, network, or tool execution behavior change? (No)

No new auth surfaces. Hub-delegated workers remain parent-owned with internal delivery/control-ui session effects and silent notify policy; waited sessions_send still reads canonical session transcript via chat.history. Visibility stays scoped to the owning requester for list/close/status and label-based follow-up.

What is the highest-risk area?

Parent/child session ownership and sessions_send delivery semantics (skipping A2A while still allowing intentional parent follow-up), plus ACP runtime handle reuse after idle (P0 touch) and lifecycle closure/repair boundaries for expired or partially lost delegates.

How is that risk mitigated?

• hubDelegated.ownerSessionKey stored in session metadata; list/close/status filter by owner.
• Label follow-up resolves within the requester owner scope (spawnedBy / hubDelegated.ownerSessionKey).
• A2A skip uses the same parent-owned-background classification as one-shot ACP children, extended for hub-delegated persistent workers.
• Explicit label uniqueness enforced per owner across ACP harness stores; auto-label uses UTC timestamp + suffix on collision under the shared hub-delegated label patch lock.
• Hub-delegated close clears hubDelegated before runtime teardown so missing-metadata repair cannot resurrect closed workers.
• Maintenance sweeps JSON-store hubDelegated rows even when sqlite metadata is absent or drifted.
• Missing-metadata repair requires explicit persistent evidence (hubDelegated, binding key shape, or active bindings); session_id drift is fail-closed until explicit metadata rebind.
• P0 fail-closed on empty/missing runtime status and force re-ensure after idle TTL.
• Tests cover spawn, send, list, delegate commands, idle handle reuse, wait timeout race, repair mode, session_id drift, label scan/ownership, maintenance expiry, close ordering, and config schema.