docs: propose Effect-scoped turn execution and lifecycle migration roadmap

[zxch3n]

Related issue

Refs #429

Stack

1. docs: propose Effect-scoped turn execution and lifecycle migration roadmap #1057 — migration plan (docs), base main
2. feat(cli): terminate ACP process trees through an Effect process layer #1065 — L0 platform + L1 process-tree layer, ACP processes
3. refactor(cli): route every CLI process through the Effect process layer #1069 — every remaining CLI process caller + boundary guard
4. refactor: one Effect process layer for the CLI, Electron main and supervisor #1070 — one process layer for CLI, Electron main, supervisor and shared helpers

Merge in order; after each merge retarget the next PR to main.

Problem / pressure

Turn execution and ACP process shutdown produced the densest run of lifecycle defects in the last two months. Examples: #571, #618, #740, #817, #595 and #759, and the still-open #429. Each was fixed locally, but the shared root cause remains: resource and wait lifetimes are not bound to an owner. They are held together instead by ~15 boolean flags, a dozen per-session registries and five different kill implementations. The team plans to migrate lifecycle-fragile code onto Effect TS and needs an evidence-backed plan and a priority order first.

Summary

Documentation only: two proposed architecture notes, each in English and Chinese.

• 2026-09-27-effect-lifecycle-migration-roadmap sets the migration rule, the Loro stack decision, and the order:
  • Layers: seven layers, bottom-up: L0 platform → L1 OS leaf → L2 state and cloud → L3 ACP connection → L4 session resource → L5 turn → L6 entry adapters.
  • Definition of done: a layer counts as done only when every dependency below it is an Effect service. Our own Promise modules are rewritten, not wrapped. Only real third-party I/O boundaries are wrapped, once.
  • L2 design: SessionDocuments (RcMap), SessionHistory (interpreter of HistoryAction values), SessionPresence (lease), and CloudPort.
  • Loro stack decision: loro-repo and streams-crdt move to an Effect core with an Effect entry plus a Promise facade. This starts after the Flock persistence migration. Until then, Lody's L2 runs behind a temporary LoroRepo Layer.
  • Ranked units and fixes that need not wait for Effect ([Bug] CLI daemon exits on a full disk: uncaught log-transport ENOSPC drops unsaved local changes #1054, [Bug] race: Electron may exit during a Loro Renderer disposal race #448, [Bug] 打开已导入会话时自动刷新请求重叠，报 history sync is already running #553).
• 2026-09-27-effect-turn-execution-and-acp-process-ownership covers the turn and ACP process layers:
  • Design: a three-level ownership model (daemon → session resource → turn), typed stop reasons, and bounded drains.
  • Layered PRs: PR1 = L0 plus a complete L1 ProcessService covering every ACP-related process (directly targets [Bug] Windows ACP shutdown can leave descendants running or silently accept cleanup failure #429). PR2 = the remaining spawn callers. Then L3 AcpConnection → L4 AgentSession/Pool → L5 turn.
  • Also recorded: the invariants every PR must preserve, the risks, and the open decisions.

No code changes. Nothing has been implemented or measured, and both notes say so.

Visual explanation

flowchart TD
    D["DaemonRuntime (ManagedRuntime + root Scope)"] --> R["SessionResource scope: AgentProcess, ACP connection, terminals, sandbox"]
    R --> T["Turn scope: presence, replay suppression, update target, registration"]
    T --> W["rawWork: raw prompt / steer / set_config_option"]
    T --> A["ancillary: yielded-turn finalization"]
    R -.exited Deferred.-> T

Loading

Before / after

Before	After
The plan and ranking existed only in a chat	Two proposed notes, each in English and Chinese, under .agents/notes/proposed/architecture/

Test plan

• Ran pnpm run docs check. The new notes produce no errors. The remaining errors were already there: broken links into uninitialized ACP submodules, and older notes with no translation.
• Checked that every cited PR number resolves to the intended commit. Where the early PR numbers were ambiguous, commit hashes are cited instead.
• pnpm check / pnpm format were not run: no source changes, and this checkout has no node_modules.

Context handoff

The Lody team asked for an analysis of which modules most need an Effect-based lifecycle refactor, then for a detailed plan for turn execution and ACP shutdown plus a proposed note for the rest.

🤖 Generated with Claude Code