[bamboo] feat: unify SubAgent as a distributed persistent Actor runtime

[bigduu]

Summary

Create one authoritative, location-transparent SubAgent model for Bamboo.

A SubAgent is a durable logical ActorSession with its own transcript, parent/root/Project identity, inbox, lifecycle, policy, diagnostics, and stable ActorId. A local process, warm worker, Docker container, SSH host, remote resident worker, or scheduled pool slot is only a WorkerHost used by one ActorActivation. It is never the agent identity.

Every placement, including local execution, uses the broker transport. The LLM sees one compact SubAgent tool and never sees deploy_agent, ask_agent, broker mailbox ids, worker ids, container ids, endpoints, or scheduling mechanics.

This is an umbrella architecture and acceptance issue. It coordinates rather than replaces the scoped implementation issues listed under Related work.

Motivation and confirmed current split

Bamboo currently exposes two semantic models even though normal local SubAgent execution already uses the broker:

1. Session-backed SubAgent children:

   • create a durable child Session first;
   • preserve parent_session_id, root_session_id, Project, spawn_depth, transcript, and lifecycle;
   • execute by sending a Run to an actor worker over the broker;
   • write the final answer back to Session storage;
   • can be observed through Bamboo session history and agent.{SessionId} streams.

2. Broker-deployed workers:

   • deploy_agent returns a physical worker/mailbox id;
   • DeployedRegistry is scoped to server memory;
   • ask_agent addresses that mailbox directly;
   • accumulated context is worker-local rather than an authoritative Bamboo Session;
   • restart recovery, nested ownership, policy, history, diagnostics, and Lotus Next visibility are incomplete.

The target is not to add a second Session implementation inside broker workers. The target is to make every broker execution belong to the one control-plane ActorSession model.

Non-negotiable invariants

• Session is the durable actor truth; a worker is replaceable capacity.
• ActorId is stable across activation, restart, passivation, retry, migration, and placement changes.
• Every owned actor is persisted before activation or event publication.
• Local and remote execution use the same broker protocol and activation contract.
• The LLM sees exactly one SubAgent tool surface.
• Parent/root/Project/depth and effective policy come from the authoritative runtime, never from worker claims.
• All messages and parent requests are addressed by logical Session id.
• All undecided child permission requests and blocking questions are delegated to the direct parent Session.
• No permission, question, delivery, wakeup, or parent/child wait can block indefinitely.
• The browser uses Bamboo's authenticated gateway and never connects directly to the broker or a worker.
• High-frequency delivery events are not automatically admitted into LLM history.
• Capability authority only narrows down the actor tree; a child can never gain authority its ancestors do not possess.

Target architecture

Root/Parent ActorSession
        |
        | one SubAgent facade
        v
ActorRuntime / ActorDirectory ---------------- Session store + SessionInbox
        |                                               |
        | PlacementRequest                              | history/diagnostics
        v                                               |
PlacementScheduler ---- HostRegistry                    |
        |                                               |
        | ActorActivation + lease                       |
        v                                               |
Broker <--------------------> Host Agent / WorkerHost ---+
                               |
                               +-- local process
                               +-- Docker/container
                               +-- SSH/remote resident
                               +-- schedulable pool
                               +-- future orchestrator
                               |
                               +-- EnvironmentLease
                                   workspace/tools/secrets/network

ActorSession

The durable logical identity:

• actor_id equal to Session.id;
• parent_session_id, root_session_id, Project identity, and spawn_depth;
• transcript/history and durable inbox;
• role/profile and effective policy revision;
• lifecycle and current state;
• current activation attempt/version;
• placement intent, not physical endpoint;
• diagnostic and audit state.

All SubAgent Sessions remain inspectable after completion. Physical oneshot/resident differences become activation temperature: Active, Idle, Cold, Suspended, Retired.

ActorActivation

One bounded execution attempt:

• actor_id;
• activation_id, monotonically increasing attempt, and run_id;
• worker/placement lease and lease epoch;
• inbox generation/wakeup epoch;
• start/finish/heartbeat timestamps;
• status, checkpoint revision, error, retry reason;
• permission/question correlation scope;
• cancellation and stale-frame fencing.

Only one activation may mutate an ActorSession transcript at a time.

WorkerHost and HostRegistry

A WorkerHost advertises capacity rather than identity:

• trusted host id and health lease;
• OS/architecture/runtime/container support;
• GPU/CPU/memory and load;
• available workspace/capability labels;
• network/trust zone;
• supported executor/provider capabilities.

"Any host" means any registered and authorized WorkerHost. It must not mean an arbitrary unvalidated IP or shell command supplied by a model.

A host or warm worker may serve multiple ActorSessions sequentially, but must scrub transcript, events, approvals, cancellation state, workspace, and secrets between activations.

PlacementScheduler

Support two semantic modes without expanding the LLM schema:

• pinned: user/session policy requests a specific trusted host, pool, or locality;
• auto: the scheduler chooses from eligible capacity.

Scheduling first filters hard constraints, then scores soft preferences:

1. Project/data/security boundary;
2. required workspace, OS, GPU, tools, credentials, and network zone;
3. workspace/data affinity and transfer cost;
4. local/remote preference;
5. load, latency, cost, and stickiness.

A task requiring current uncommitted files, a local screen, or host-bound tools should remain local unless an explicit environment bridge exists. A portable Git snapshot, research task, build, or GPU task may run remotely.

Fallback behavior is explicit. A pinned or sensitive task must not silently cross a host/data boundary when its preferred placement is unavailable.

One LLM-facing SubAgent facade

Replace the current multi-tool/multi-parameter mental model with one compact tool:

{
  "intent": "chat | inspect | control",
  "target": "optional ActorId",
  "message": "natural-language request",
  "reply_to": "optional ParentRequest id"
}

intent defaults to chat.

Semantics

• chat with no target: create a durable child ActorSession and send its first task.
• chat with a target: continue the same child Session.
• inspect with no target: return the owned descendant tree and health summary.
• inspect with a target: return authoritative status, diagnostics, and requested history slices.
• control with a target: apply a bounded lifecycle command such as cancel current activation, retry, reassign, or retire.
• reply_to: resolve a pending permission or clarification request through the same chat facade.

Runtime behavior hidden from the model:

• create/update/run/send_message/ask_agent converge into chat;
• list/get/history/status converge into inspect;
• wait is owned by the runtime and completion coordinator;
• cancel/retry/stop converge into control;
• delete remains a user/admin operation by default;
• deploy_agent becomes internal capacity management or a compatibility adapter;
• model selection, lifecycle temperature, workspace, host, container, and scheduling parameters move to profile, policy, configuration, and runtime inference;
• list_models is not part of SubAgent orchestration.

The facade returns ActorId, logical state, response/observation, and actionable diagnostics. It never returns a broker token or physical mailbox address.

EnvironmentLease and local-environment access

Remote actors cannot magically read a path on the parent's host. Every activation receives an explicit EnvironmentLease using one or more modes:

1. Host-local workspace:

   • schedule onto the host that owns the workspace;
   • use an isolated worktree/branch lease for writes.

2. Scoped container mount:

   • mount only the selected workspace/artifact paths;
   • never mount all of ~/.bamboo or unrelated credentials by default.

3. Remote snapshot:

   • materialize a Git SHA plus optional uncommitted patch/content snapshot;
   • return changes as a patch, branch, or artifact.

4. Capability proxy:

   • execute explicitly allowlisted host-bound tools on the owning host;
   • existing MCP proxy behavior is a starting point;
   • default to read-only and audit every proxied action.

Large logs, patches, binaries, screenshots, and build outputs belong in a content-addressed Artifact Store. Broker and SessionInbox messages carry references and hashes, not unbounded file payloads.

Credentials use secret-free capability references and are resolved only on the selected trusted host. They never enter Session history, model-visible diagnostics, argv, broker ids, or browser state.

Nested delegation

Every ActorSession receives the same internal runtime capability to:

• spawn a child;
• assign/chat;
• inspect owned descendants;
• await/collect results;
• cancel/retry/retire;
• answer parent requests.

Nested creation must:

• register the durable child before activation;
• use an idempotent command_id;
• derive parent/root/Project/depth from ActorDirectory;
• enforce configurable depth, child concurrency, token/time/cost budgets;
• attenuate file/tool/credential/network/placement authority;
• deliver semantic ChildOutcome messages to the parent inbox;
• preserve recovery when a parent or child passivates or restarts.

Owned children, resident actors, and shared service actors use the same ActorSession identity contract. Shared service actors additionally require explicit caller ACLs and must not silently share one transcript among unrelated callers.

Parent-owned permission and question handling

All permission requests that still require a decision, and all blocking child questions, become typed durable ParentRequests delivered to the direct parent Session.

Already-allowed actions execute without a request. Explicit hard-deny, Guardian/Plan, authentication, OS, and sandbox boundaries reject immediately and cannot be overridden by a parent. Auto mode remains zero-prompt: it executes allowed actions and preserves hard denials rather than opening an approval loop.

ParentRequest

At minimum:

• request_id;
• origin child ActorId and activation attempt;
• direct parent ActorId;
• kind: permission or clarification;
• exact blocked operation/resource digest;
• rationale, options, and recommended safe default;
• deadline;
• escalation path/hop count;
• policy revision and maximum delegable authority.

ParentResolution

At minimum:

• request_id;
• decision: approve_once, deny, answer, or escalate;
• answer/reason;
• exact scope and expiry for a grant;
• decided_by ActorId/activation/policy;
• persisted resolution version.

The request enters the actual parent Session and its audit/history. It must not exist only as a hidden reviewer LLM call or an in-memory live bridge.

The parent may inspect the child's history and diagnostics before replying:

{
  "target": "child-123",
  "reply_to": "permission-7",
  "message": "approve_once"
}

A parent may approve only within its inherited delegation envelope. If it lacks authority, it may deny or escalate to its own parent. Every escalation records its path and is bounded against cycles.

Breaking parent/child wait cycles

The runtime must explicitly break this cycle:

Parent WaitingForChild
Child AwaitingParent(request)

When a child emits ParentRequest:

1. persist it in the parent SessionInbox;
2. mark the child Suspended/AwaitingParent, not terminal;
3. interrupt or temporarily release the parent's WaitingForChild state;
4. wake/activate the parent to process the request;
5. persist ParentResolution;
6. deliver and wake the child;
7. re-arm the parent's original wait if still applicable.

No Session lock, placement lock, activation reservation, or parent wait lease may be held while waiting for a model decision. A warm worker may be kept briefly for latency, then checkpointed and released after a grace period.

Permission deadlines fail closed with deny. Clarification deadlines use an explicit safe default or transition to a recoverable blocked_needs_input state. They never remain falsely Running.

Durable queue, retry, and wakeup semantics

Use one canonical SessionInbox per logical Session. Do not create a second in-memory source of truth.

Queue states

READY
  | claim
  v
IN_FLIGHT ----------------------------> ACKED
  | transient failure / lease timeout
  v
DELAYED -- next_visible_at -----------> READY

permanent failure / retry limit ------> DEAD_LETTER

Each delivery record needs:

• stable message_id and generation;
• delivery_attempt;
• next_visible_at;
• claim/lease owner;
• lease epoch and lease_expires_at;
• last error;
• activation eligibility and wakeup epoch.

Retry metadata is queue metadata and must not change the semantic message id or payload.

Claim/ack contract

• claim moves a ready item into an in-flight lease; it does not delete it;
• the active consumer renews the lease while making progress;
• ack is legal only after the exact message id is durably represented in the authoritative Session transcript/admission cursor;
• worker loss before durable admission causes lease expiry and requeue;
• crash after transcript checkpoint but before ack is reconciled from the admitted receipt and completes ack without duplicate admission;
• stale workers cannot ack or emit after their lease epoch is fenced;
• invalid, unauthorized, or malformed messages are quarantined/dead-lettered, not hot-looped.

Distinguish delivery failure from execution failure

• Activation/host launch failed before admission: keep/requeue the message and retry wakeup.
• Worker died after claim but before transcript checkpoint: requeue the same message after lease expiry.
• Input was already admitted and the LLM/tool execution later failed: retry ActorActivation against the existing transcript; do not append the same input again.
• Permission denied or a permanent domain error: produce a terminal semantic result; do not retry the original request.
• Delivery of that final result may itself use normal queue retry semantics.

WakeReconciler

Whenever eligible work exists:

• if the receiver is Active, notify its current activation;
• if it is Cold, reserve exactly one successor activation;
• coalesce multiple messages into one activation;
• if activation/placement fails, retain the queue item and schedule retry with exponential backoff plus jitter;
• when next_visible_at arrives, try again;
• reclaim expired claims;
• on process restart, scan eligible durable backlog;
• detect READY messages with no owner/heartbeat and repair the wakeup;
• stop poison-message hot loops with bounded attempts and dead-letter state.

A business deadline is different from a visibility lease. A delivery timeout requeues. A permission/question decision deadline produces a deterministic deny/default/blocked resolution rather than restarting an infinite approval conversation.

History, diagnostics, and authority

The root Session can inspect its full descendant tree. A direct parent can inspect its owned subtree. Siblings cannot read each other by default. Shared/service actors require ACLs.

Inspection is on demand: child histories remain isolated and are not automatically merged into the parent LLM context. The tool returns paginated or query-focused transcript slices/summaries and redacts credentials or protected tool output.

Chat self-report and runtime diagnosis remain distinct:

• chat asks the child what it believes;
• inspect reads authoritative control-plane state even when the child is dead, cold, disconnected, or stuck.

Diagnostics must include:

• logical lifecycle and current activation;
• placement class without sensitive endpoint/token details;
• Host/worker heartbeat and lease;
• last event, LLM round, tool name and tool phase;
• pending inbox, claimed/delayed/dead counts;
• claim owner/expiry, attempts, next retry, and last wake error;
• pending permission/question and its deadline;
• parent/child wait graph and cycle detection;
• latest error, retry history, and checkpoint;
• health classification: healthy, waiting, stalled, failed, orphaned, blocked_needs_input, or lost;
• evidence and suggested recovery action.

Event and Lotus Next projection

Every worker event is wrapped in an authoritative ActorEventEnvelope:

• actor_id;
• root/parent identity from ActorDirectory;
• activation attempt and run_id;
• per-attempt monotonic sequence;
• timestamp;
• typed event payload.

Bamboo validates the lease/attempt and projects:

• durable low-volume topology/lifecycle;
• agent.{ActorId} high-volume live content;
• authoritative transcript/runtime changes;
• metrics for duplicate, stale, missing, and rejected events.

Lotus Next consumes the same ActorDirectory/SessionDiagnostics projection as the model-facing inspect capability:

• recursive persistent ActorSession tree;
• history and activation inspector;
• local/remote/container placement badge;
• queue, permission/question, retry, and health state;
• one authenticated shared /v2/stream connection;
• lazy reference-counted subscriptions only for visible/expanded/previewed actors;
• transcript/snapshot recovery after sequence gaps.

Lotus Next never receives broker credentials, worker endpoints, PIDs, container ids, or secret values.

Reliability and security requirements

• At-least-once transport plus message-id deduplication; do not claim globally exactly-once side effects.
• Tool actions that may be retried use idempotency keys or transactional side-effect records.
• One transcript writer per ActorSession.
• Attempt/lease fencing rejects stale events, replies, approvals, cancellations, and acks.
• ParentRequest and ParentResolution are idempotent and exactly one terminal resolution wins.
• mTLS or equivalent authenticated host identity for remote workers.
• Short-lived, actor/activation-scoped broker credentials; no one shared token as an authorization boundary.
• Effective capability equals the intersection of root policy, parent delegation envelope, Project policy, EnvironmentLease, and Host capabilities.
• Every grant, denial, escalation, placement, retry, and recovery is auditable.
• Queue and history limits apply backpressure without silently dropping durable semantic messages.
• Retire preserves history; destructive deletion remains a user/admin operation.

Migration plan

Phase 0: contracts and invariants

• Define ActorSession, ActorActivation, WorkerHost lease, EnvironmentLease, ParentRequest/Resolution, queue lease, and diagnostics DTOs.
• Add state-machine and property tests before changing compatibility behavior.
• Re-evaluate stale blockers now that [bamboo] refactor: introduce a durable typed SessionInbox and activation router #681 is closed.

Phase 1: identity convergence

• Implement [bamboo-actor] epic: converge SubAgent and deployed workers on ActorSession identity #699.
• Make every legacy deploy_agent-created logical agent create a durable resident ActorSession.
• Return ActorId aliases while retaining bounded legacy worker-id compatibility.
• Route ask/query/steer through SessionMessenger and ActorActivation.

Phase 2: durable requests and queue recovery

• Extend SessionInbox with lease/renew/nack, delayed retry, retry wakeup epoch, dead-letter, and reconciliation.
• Converge child permissions and questions into ParentRequest/Resolution.
• Add wait-graph cycle breaking and parent wakeup.
• Preserve Auto/hard-deny semantics.

Phase 3: placement and environment

• Add authoritative HostRegistry and capability-aware PlacementScheduler.
• Move local, Docker, SSH, remote, and schedulable execution behind one WorkerHost lease interface.
• Add EnvironmentLease, isolated workspace/snapshot, artifact, and capability-proxy contracts.

Phase 4: one tool and nested delegation

• Replace the current model-facing action/parameter surface with the compact SubAgent facade.
• Hide deploy_agent/ask_agent and physical placement details from the model.
• Complete [bamboo-actor] epic: bidirectional messaging within one ActorSession tree #683 and [bamboo-actor] epic: nested depth, suspension, and resume correctness #685 against the same runtime.
• Keep compatibility adapters and migration tests until callers move.

Phase 5: lifecycle, diagnostics, and Lotus Next

• Implement [bamboo-actor] epic: project ActorSession lifecycle through the authenticated gateway #700 ActorEventRouter/gateway projection.
• Expose history, activation, queue, wait graph, parent-request, and health diagnostics.
• Implement lotus-next feat(engine): route Placement::Remote sub-agents through wss:// ConnectLauncher [#193] #194–test(server): live /v2/stream WS integration harness + per-channel outbound queues [#187] #196 topology, lazy streams, and recursive tree.
• Preserve bounded v1 compatibility until v2 parity is proven.

Phase 6: removal and documentation

• Remove raw mailbox identity from model/UI contracts.
• Remove the in-memory deployment registry as actor truth.
• Delete compatibility tools only after migration telemetry and tests prove no active callers.
• Update actor runtime, broker, remote placement, tool, permissions, queue, recovery, and Lotus Next documentation.

Acceptance criteria

Identity and placement

• Every owned local/remote/container/scheduled actor has a durable ActorSession before execution.
• ActorId never equals or depends on PID, worker id, mailbox id, endpoint, container id, or host id.
• Reassignment to a different WorkerHost preserves ActorId, history, inbox, parent/root/Project, and policy.
• Local and remote paths use the same broker-mediated activation contract.
• No warm worker leaks transcript, events, permissions, cancellation, workspace, or secrets between actors.
• Pinned and auto placement honor hard constraints and never silently cross a security/data boundary.
• Remote work receives an explicit EnvironmentLease; no remote actor assumes a parent-host absolute path exists.

Model-facing facade

• The LLM receives one SubAgent tool and no deploy_agent/ask_agent tool.
• Common delegation requires only a natural-language message; target is optional.
• Existing Session chat, inspect/history, lifecycle control, and ParentRequest replies use the same ActorId.
• Waiting, model selection, lifecycle temperature, workspace resolution, and placement mechanics are runtime-owned.
• Physical topology and credentials never appear in model-visible tool results.

Parent requests and deadlock freedom

• Every undecided child permission and blocking question is durably delivered to the direct parent.
• Parent can inspect child history/diagnostics before resolving.
• Parent decisions cannot widen inherited authority or override hard deny/Guardian/Plan/auth/OS/sandbox boundaries.
• Auto mode emits no ordinary approval wait.
• A Parent WaitingForChild is woken when that child needs a decision; the original wait is safely re-armed afterward.
• Parent/child/grandchild escalation is bounded, cycle-safe, restart-safe, and auditable.
• Every request has a deterministic timeout result; no actor remains falsely Running.

Queue and recovery

• Durable messages survive process, worker, host, and broker reconnect failures.
• Claim leases expire and safely requeue messages without allowing stale consumers to ack.
• Queue retry uses backoff/jitter and bounded poison-message handling.
• Transcript checkpoint before ack prevents duplicate provider admission.
• Same-generation failed wakeups can reserve a new activation attempt.
• Eligible queued work wakes an active receiver or reserves exactly one cold activation.
• Startup and periodic reconciliation repair stranded eligible backlog.
• Delivery failure, execution failure, permanent rejection, and business deadline have distinct outcomes.
• Dead-letter items are visible, diagnosable, and manually retryable without changing semantic ids.

History, diagnostics, and UI

• Root can inspect the authorized descendant tree and requested transcript slices without automatic history merging.
• Diagnostics work for Active, Cold, Suspended, Failed, Lost, and disconnected actors.
• Inspection exposes queue, activation, wait, permission/question, heartbeat, error, and retry evidence.
• Every observable actor publishes lifecycle before live content.
• Stale/duplicate/out-of-order ActorEventEnvelopes cannot regress state or pollute a newer activation.
• Lotus Next renders a recursive persistent tree and subscribes lazily through one authenticated Bamboo stream.
• Browser clients never connect to broker/worker endpoints or receive their credentials.

Deterministic test plan

• Create equivalent actors through SubAgent and legacy deploy_agent compatibility; compare durable identity and policy.
• Restart between Session persistence, queue delivery, placement reservation, activation start, transcript checkpoint, and ack.
• Lose a local process, container, SSH connection, remote resident worker, and schedulable host; recover on another host with the same ActorId.
• Reuse one warm worker across unrelated root/Project actors and prove complete isolation.
• Claim a message, crash before admission, expire lease, requeue, and admit once.
• Crash after transcript checkpoint but before ack; reconcile without duplicate history.
• Fail placement repeatedly; verify backoff, wake retry, attempt fencing, and dead-letter behavior.
• Deliver several messages while Cold; verify one activation drains a bounded ordered batch.
• Deliver while Active; verify notification without a second transcript writer.
• Parent waits for child while child requests permission; verify parent wake, resolution, child resume, and wait re-arm.
• Repeat the previous case at grandchild depth and across restart.
• Parent absent/retired and root unavailable; verify bounded escalation and deterministic deny/blocked outcome.
• Auto, Default, Plan, Guardian, hard-deny, and forced-ask policy matrices.
• Late permission reply, stale activation event, old cancellation, old ack, and broker redelivery.
• Local dirty workspace task stays local; portable snapshot task schedules remote; sensitive task refuses unsafe fallback.
• Container gets only scoped mounts; remote artifact/patch returns through references.
• Root inspect finds a deliberately stalled queue/activation and proposes a valid recovery.
• Recursive Lotus Next tree with 100+ actors proves bounded high-volume channel count and correct gap recovery.

Documentation

Update:

• docs/design/subagent-actor-runtime-design.md
• docs/design/remote-actor-plan.md
• docs/design/remote-mailbox-broker-design.md
• docs/design/architecture-overview.md
• SubAgent tool documentation
• permission/Auto/hard-deny documentation
• SessionInbox delivery/recovery documentation
• Lotus Next actor-tree and streaming documentation

Terminology must be consistent:

• ActorSession: durable logical agent;
• ActorActivation: one execution attempt;
• WorkerHost: physical capacity;
• EnvironmentLease: authorized environment/data/tool access;
• ParentRequest: permission or clarification delegated to an ancestor;
• broker: transport only;
• ActorDirectory/Runtime: identity, authority, activation, placement, and recovery control plane.

Non-goals

• No direct browser-to-broker or browser-to-worker protocol.
• No second worker-local Session source of truth.
• No magical remote access to a parent-host filesystem.
• No promise of lossless persistence for every token event.
• No global exactly-once guarantee for arbitrary external side effects.
• No unbounded actor recursion.
• No child authority escalation.
• No cross-root/cloud peer Handoff redesign; that remains [cloud] epic: peer Handoff and authoritative actor discovery #224.
• No replacement of existing placement launcher work where [bamboo] feat: remote actor execution (远程拉起 sub-agent) #9 already owns it.
• No immediate removal of compatibility surfaces before migration evidence.

Related work

Bamboo:

• [bamboo] refactor: introduce a durable typed SessionInbox and activation router #681 — durable typed SessionInbox and activation router (closed foundation).
• [bamboo-actor] epic: admit live user input into active Sessions #682 — safe live input admission.
• [bamboo-actor] epic: bidirectional messaging within one ActorSession tree #683 — bidirectional session messaging.
• [bamboo-actor] epic: incremental child outcomes with armed waits #684 — incremental parent wakeups and child outcomes.
• [bamboo-actor] epic: nested depth, suspension, and resume correctness #685 — nested resume and depth policy.
• [bamboo-actor] epic: converge SubAgent and deployed workers on ActorSession identity #699 — persistent ActorSession identity convergence.
• [bamboo-actor] epic: project ActorSession lifecycle through the authenticated gateway #700 — lifecycle/event projection through the authenticated gateway.
• [bamboo] feat: remote actor execution (远程拉起 sub-agent) #9 — remote placement/launcher work.
• [cloud] epic: peer Handoff and authoritative actor discovery #224 — cross-root/cloud peers (out of scope).
• [bamboo-tui] feat: add a persistent sub-agent tree and child-session inspector #645 — Bamboo/TUI child inspector.

Lotus Next:

• [lotus-next] feat: normalize recursive ActorSession topology and snapshots lotus-next#194 — normalized recursive ActorSession topology and snapshots.
• [lotus-next] feat: lazily subscribe to visible ActorSession streams over v2 lotus-next#195 — lazy visible ActorSession subscriptions over the shared v2 stream.
• [lotus-next] feat: render a virtualized recursive ActorSession tree lotus-next#196 — virtualized recursive ActorSession tree.

Delivery guidance

This Epic is not a single-agent implementation slice. Split work into scoped, dependency-ordered Issues and isolated branches with local review. Keep it agent:blocked until the first ready implementation slice has reconciled closed #681 and the authoritative contracts above are accepted.

[bigduu]

2026-08-23 Issue audit: this is the canonical ActorSession/placement umbrella and was missing from Zenith Roadmap while several of its implementation slices were present. Added to Roadmap as Triaged, P1, XL and removed the contradictory agent:ready label. Per its own delivery guidance it is not an implementation unit; only a reconciled child slice may move to Ready.

[bigduu]

2026-08-23 issue-governance audit

This remains the canonical architecture umbrella and is explicitly not an implementation unit. Its formerly oversized phase Issues have now been split into one-day-sized slices:

• [bamboo-actor] epic: admit live user input into active Sessions #682 live input → [bamboo-actor] refactor: route all live user ingress through SessionMessenger #914, [bamboo-actor] feat: admit durable user input at provider-valid loop boundaries #915, [bamboo-actor] feat: wake the exact active Session runner for durable inbox input #916.
• [bamboo-actor] epic: bidirectional messaging within one ActorSession tree #683 peer messaging → [bamboo-actor] feat: expose session_message and unify SubAgent send_message delivery #917, [bamboo-actor] feat: define authorized intra-tree Session peer messages #918, [bamboo-actor] feat: route peer messages across ActorSession worker hosts #919.
• [bamboo-actor] epic: incremental child outcomes with armed waits #684 incremental child outcomes → [bamboo-actor] feat: coalesce parent wakeups for incremental child outcomes #920, [bamboo-actor] feat: persist one ChildOutcome while keeping unfinished waits armed #921.
• [bamboo-actor] epic: nested depth, suspension, and resume correctness #685 nested depth/resume → [bamboo-actor] feat: coordinate nested resume, steering, approval, and cancellation #922, [bamboo-actor] refactor: centralize configurable SubAgent depth policy #923, [bamboo-actor] fix: represent nested suspension without false child completion #924.
• [bamboo-actor] epic: converge SubAgent and deployed workers on ActorSession identity #699 ActorSession identity convergence → [bamboo-actor] feat: persist ActorSession and ActorActivation authority #925, [bamboo-actor] refactor: create SubAgent and deploy_agent workers as ActorSessions #926, [bamboo-actor] refactor: converge ask, query, steer, and recovery on ActorId #927.
• [bamboo-actor] epic: project ActorSession lifecycle through the authenticated gateway #700 event/gateway projection → [bamboo-actor] feat: expose ActorSession snapshots through the authenticated gateway #928, [bamboo-actor] feat: fence and route ActorEventEnvelope lifecycle events #929, [bamboo-actor] refactor: migrate parent-wrapped and broker Ask observation to actor streams #930.

The six phase parents stay tracking-only/blocked. The first dependency-safe slice in each chain is Triaged, not Ready, while Bamboo module capacity is occupied. Lotus #26 is now closed as shipped transport foundation; actor UI remains bigduu/Lotus#140.

[bigduu]

Implementation slices added after the 2026-09-24 source audit:

• Lifecycle correctness: [bamboo] fix: arm parent wait before synchronous SubAgent launch #1267 (parent wait before launch; in progress), [bamboo] fix: fence queued child cancellation before activation #1268 (queued cancellation), [bamboo] fix: recover accepted background child launch after restart #1269 (restart launch recovery), [bamboo] fix: reject destructive SubAgent.update during active execution #1270 (active update safety).
• Root control: [bamboo] feat: apply orchestration prompt enhancement to root Sessions #1271 (root orchestration profile), [bamboo] feat: enforce root-tree child admission budget #1272 (root-tree child admission budget), [bamboo] feat: make child result and transcript retrieval truthful and bounded #1273 (bounded child result/history retrieval).
• Broker/remote correctness: [bamboo] fix: correlate concurrent ask_agent replies per caller #1274 (concurrent ask replies), [bamboo] fix: ACK remote actor frames after host checkpoint #1275 (Outcome checkpoint before ACK), [bamboo] security: protect System SSH actor deployment credentials #1276 (System SSH credential handling).

Reuse existing focused issues for incremental parent wakeups (#920/#921), named child profiles (#909), bounded versioned context packets (#1054), planner artifact (#1059), and adversarial reviewer/team templates (#935). Keep each implementation branch to one acceptance slice.

[bigduu]

Scope refinement: #1271 now covers the root prompt only; #1278 covers enforced orchestration-only tool authority. Remote completion was split into #1275 (host checkpoint before frame ACK), #1279 (critical worker uplink failure keeps Run retryable), and #1280 (terminal event watermark). The compaction/steering scope regression evidence and test requirement were added to existing #1054.

[bigduu]

Local-only implementation update (no GitHub PR review gate):

• [bamboo] feat: apply orchestration prompt enhancement to root Sessions #1271 root orchestration prompt is implemented and locally merged into Bamboo bamboo/integrate/791-local at e50dfd8c. It covers explicit root selection, persisted resume, bounded guidance and ordinary-root/child isolation. [bamboo] feat: enforce orchestration-only root tool authority #1278 still owns orchestration-only tool authority.
• Lotus [bamboo-engine] Dead/drift cleanup: unused strict_argument_tool_names config field, dead duplicate storage/v2.rs, never_loop clippy error breaks Lint #239 topology store and the independent memory recall 档0: CJK-aware tokenization + BM25(F) over lexical.json (bilingual recall, embedding-free) #240 visible-subscription manager are locally merged in lotus-next/integrate/239-actor-topology-local at 44b2ed4a. Canonical gateway wiring and UI remain dependent on [bamboo-actor] feat: expose ActorSession snapshots through the authenticated gateway #928–[bamboo-actor] refactor: migrate parent-wrapped and broker Ask observation to actor streams #930 and Lotus feat(bamboo-memory): CJK-aware tokenization + BM25(F) recall (#240) #241.
• [bamboo] fix: arm parent wait before synchronous SubAgent launch #1267 is under local implementation/review for durable wait-before-launch plus cancellation/failure convergence; do not count it complete yet.
• [bamboo-actor] feat: persist ActorSession and ActorActivation authority #925 ActorSession/ActorActivation authority has started in a separate local worktree. [bamboo-actor] refactor: create SubAgent and deploy_agent workers as ActorSessions #926/[bamboo-actor] refactor: converge ask, query, steer, and recovery on ActorId #927 remain dependent on it.
• New focused follow-ups found during review: [bamboo] refactor: route Remote actor activation through broker link #1311 Remote actor broker-path convergence; [bamboo] fix: reconcile explicit parent waits with child completion #1312 explicit parent-wait/completion interleavings already present in the baseline; [bamboo] fix: linearize cancelled child admission at durable delivery #1313 cancellation-aware durable child/Inbox admission at the actual commit boundary.

The umbrella acceptance checklist remains open until each location, queue, permission, facade, diagnostics, UI and recovery path is proven. Local branches and tests are being used for review and integration as requested.

[bigduu]

Correction to my earlier progress comment: the frontend source and issue tracking are bigduu/lotus-next, not the retired bigduu/Lotus repository. The active frontend Issues are bigduu/lotus-next#194 (normalized topology), bigduu/lotus-next#195 (lazy actor subscriptions), and bigduu/lotus-next#196 (recursive tree UI). Old Lotus #239–#241 are closed as transferred and removed from the roadmap. The first two local-only slices are in lotus-next/integrate/actor-runtime-local at 0cf9c59 and 5d5740a; no PR was opened. Backend DTO/channel bindings and the UI remain open.

[bigduu]

Local implementation checkpoint (2026-09-26): frontend delivery is exclusively Lotus Next. The Epic already links lotus-next#194/#195/#196; Root orchestration/recovery is lotus-next#197 and typed Workflow UI compatibility remains lotus-next#198. No work is being routed to the retired Lotus frontend.

This Epic remains open. The local Bamboo integration currently contains #925, #1267, #1271, #1273, #1313, #1316, #1317, #1319/#1323, #1320, #1321, #1322 and #1324. That is partial evidence, not completion of the full distributed-runtime acceptance checklist.

Existing Root mode terminal recovery (#1327) and its Lotus Next migration are under focused local tests/review. Newly split Root creation/replay and later chat authority binding are #1332/#1333. Inbox publication-to-wakeup recovery remains #1329; default named-role foundations begin with #1326 before #909/#1315.

The current source audit also confirmed two acceptance areas need explicit implementation units:

• [bamboo] track: fence durable SessionInbox claim leases #1334: durable Inbox claim lease expiry and stale ACK fencing, after [bamboo] fix: recover committed Inbox messages before activation watermark #1329. Current Inbox claims have no lease epoch/expiry and files in cur can be returned immediately.
• [bamboo] epic: deliver durable direct-parent decisions and break wait cycles #1335: tracker for durable direct-parent decisions and breaking parent/child wait cycles. Current source has no canonical typed ParentRequest/ParentResolution implementation. Each persistence, grant, wait-cycle and deadline slice will have its own Issue/worktree.

Queue backoff/dead-letter/periodic reconciliation, trusted placement/environment leases, remote convergence and actor event projection remain active #791 requirements. No corresponding checkbox is marked done from the current Root-mode work.

All delivery in this workstream continues through independent local review and local merge. GitHub PR review is not a gate; no feature push or Zenith pointer update is included.

[bigduu]

Local delivery update (Lotus Next only):

• Bamboo [bamboo] fix: recover ambiguous Root mode transitions with a durable fence #1327 is reviewed, tested and locally merged as 4529d0cfb2a6a335fd336b2fc16651dc8c8aeec6 (source b7439e1c78a3aa04e74b10bfb8212dfc30c2b624). Existing Root mode-only operations bind the original operation/birth/epoch and support terminal recovery or successor fencing. Full Domain/Storage/Engine suites and HTTP mode/chat/query suites passed; default Clippy passes with baseline warnings. Detailed evidence: [bamboo] fix: recover ambiguous Root mode transitions with a durable fence #1327 (comment).
• Lotus Next feat(server): v2-P3 MessagePack subprotocol for /v2/stream [#181] #197 recovery is locally merged at 68e2cd0b51a7ecdaeeb4a8511ee035867fc5265c; 1817 unit tests and built Root E2E (7 passed, 8 device-specific skips), plus desktop/phone screenshots. This is local fixture/API evidence, not a release or live-provider claim.
• Read-only production audit confirmed Lotus Next feat(engine): route Placement::Remote sub-agents through wss:// ConnectLauncher [#193] #194/feat(server): make /v2/stream hello an authoritative auth gate (browser device tokens) [#189] #195/test(server): live /v2/stream WS integration harness + per-channel outbound queues [#187] #196 currently provide normalized topology, lazy subscriptions and virtualized ActorTree foundations with tests. These new cores still have test-only callers, and Bamboo [bamboo-actor] feat: expose ActorSession snapshots through the authenticated gateway #928/[bamboo-actor] feat: fence and route ActorEventEnvelope lifecycle events #929/[bamboo-actor] refactor: migrate parent-wrapped and broker Ask observation to actor streams #930 have not supplied the public subtree/canonical ActorEventEnvelope binding. The real 100+ Actor tree and canonical event projection acceptance remain incomplete; no Epic checkbox is marked complete from foundation tests alone.
• [bamboo] feat: parse bounded global named-agent definitions #1326 bounded named-agent parser/catalog is undergoing local validation and fixes from independent review. [bamboo] fix: recover committed Inbox messages before activation watermark #1329 immediate Inbox activation-intent recovery has its own branch/worktree and is in progress; generic claim lease ([bamboo] track: fence durable SessionInbox claim leases #1334) and durable parent decisions ([bamboo] epic: deliver durable direct-parent decisions and break wait cycles #1335) remain distinct work.

All work continues through isolated local slices, local review and local merge. No push, PR-review gate or Zenith gitlink update. The Epic remains active; first-chat recovery (#1332), later-chat revision binding (#1333), remote placement/environment, leases/retries/dead-letter, ParentRequest decisions and production Actor projection are not claimed complete.

[bigduu]

Local implementation checkpoint

#791 remains active. This checkpoint records accepted slices and current bounded work; it does not close the Epic or its remaining architecture criteria.

Accepted local integration

• Bamboo [bamboo] fix: recover committed Inbox messages before activation watermark #1329 is reviewed, tested and merged as d267b11f3f48de383faecc6a47283335e27a18c6; source 86ad3aeb02b6943930a6b1db85bb61dbab1a0f07, identical tree 612d3d228e934ac9c3498342f24837a8d1c16ee9, clean. Exact acceptance and final-source gates.
• Immediate Inbox permission now belongs to its own message, while staged release remains a coordinator prefix. Respect/Interrupt policy is preserved through the actual claim consumer and restart/ACK path.
• Existing accepted Root mode/recovery, named-definition catalog and earlier slices remain in the local integration branch. This checkpoint adds no push, PR or Zenith gitlink change.

Current focused work

• [bamboo] feat: expose bounded authorized Actor subtree snapshots #1337 authorized read-only Actor subtree snapshot: final-source focused tests and full Domain/Storage passed; real server authentication/gates are underway. It is not yet merged.
• Lotus Next auth: Host-header-based local_bypass is spoofable (systemic, pre-existing) #199 snapshot inspector source 3b39cee6ef10790a0cfdab8d440d671ae5349687 is independently reviewed and tested (1876 tests; built desktop/phone fixture acceptance). It waits for [bamboo] feat: expose bounded authorized Actor subtree snapshots #1337 producer acceptance before integration; no live provider round trip is claimed.
• [bamboo] track: fence durable SessionInbox claim leases #1334 consumer claim leases: fresh branch from the current Bamboo integration, design/checkpoint-race audit first. Cargo is reserved for [bamboo] feat: expose bounded authorized Actor subtree snapshots #1337; no retry/DLQ or general lifecycle rewrite enters this slice.
• Lotus Next feat(auth): brute-force throttle on /v2/pair + /access/verify root password [#190] #198 typed Workflow selection: separate frontend slice using the actual authenticated instruction catalog and typed chat identity. Orchestration workflows continue to require their existing Workflow Run API.

Explicit remaining boundaries

• Actor runtime authority gap: durable ActorDirectory primitives currently have storage test callers, not production runner activation bindings. [bamboo-actor] refactor: create SubAgent and deploy_agent workers as ActorSessions #926/runtime writer integration and [bamboo-actor] feat: fence and route ActorEventEnvelope lifecycle events #929 canonical producer remain required. Successful validate_fence observation is not an atomic transcript/ACK fence.
• Lotus Next feat(server): remote-actor P2a — /v1/agents registry + RegistryFabric [#181] #200 splits the selected/previewed owned-Child canonical subscription consumer from full replay/recovery, depending on accepted producer/gateway contracts. No fake cursor, global revision or lease epoch is introduced.
• [bamboo] perf: read Actor snapshots without scanning transcripts #1339 separately tracks snapshot authority reads that avoid scanning transcript bodies. [bamboo] feat: expose bounded authorized Actor subtree snapshots #1337 retains its bounded, fail-closed first-slice behavior for long historical Session files.
• [bamboo] feat: read Actor subtree snapshots through Windows handles #1338 remains actual native Windows snapshot-reader coverage; macOS evidence is not Windows evidence.

All UI work is in Lotus Next. The retired Lotus frontend is not an implementation target.