agent-core-dev

Define an interface with a unique createDecorator name and _serviceBrand, implement it with constructor injection via @IX decorators, and register it with registerScopedService at the correct LifecycleScope. Follow the design stage to pick the scope from state identity first.

Use the align workflow: inventory the v1 class's state and dependencies, split it into semantic units by state identity, assign each unit a LifecycleScope, then re-register with registerScopedService and convert imports to the #/ alias. Never copy the v1 class shape directly.

Scope follows state identity: global state goes to App, per-sessionId state to Session, and per-agentId state to Agent. Stateless services default to App unless they inject a shorter-lived dependency. Never fake per-session state with a Map at App scope.

A cycle means knowledge was placed backwards between domains. Refactor by extracting a third service, inverting the notification into an event, or re-scoping; activation timing cannot break a dependency cycle.

Resolve the system under test by interface using ix.get(IX) with TestInstantiationService, or use createScopedTestHost for scope-layer behavior. Shared stubs live under test/, never src/, and teardown goes through one DisposableStore.

Use close() for async business shutdown like stopping in-flight work and flushing persistence, called before scope.dispose(). Use dispose() only for synchronous resource cleanup such as event subscriptions and timers, since dispose is never awaited.