feat(agent): return an AgentHandle with an async per-agent disposer

The agent factory (`ctx.agents.create`/`resume`, the `AgentFactory` seam)
now returns `AgentHandle = { agent; dispose(): Promise<void> }` instead of a
bare `Agent`. The disposer is a capability: only the holder can tear down
exactly this agent — stop its loop, await the loop's exit (true quiescence,
not just the `disposed` status flip), unregister it, and remove its session
from the store.

The teardown ORDER is load-bearing for durability. The loop appends its
final `turn/end` + runs `session/flush` AFTER an abort, delivered through
`session.onAppend` → `session/event`; if the session-store effect (which
detaches `onAppend`) were torn down first, those closing events would never
reach persistence. So `dispose()`:
  1. runs the register+start effect disposer (sync: request loop stop),
  2. `await agent.done` (loop exits, final flush captured), THEN
  3. runs the session disposer (detach onAppend + delete store entry).

`SessionStore.createOwned()` exposes the session-create effect's disposer
(plain `create()` discards it — fiber-owned). `AgentLoop` funnels both
factory entrypoints (`createAgent`, `resumeWith`) through a shared
`startOwned` that composes the ordered teardown; the config path keeps a
fiber-owned agent by discarding the handle.

`ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for
the owner that created it.

packages/agent/src/index.ts

@@ -54,6 +54,23 @@ export interface ResumeAgentOptions {
   agentOptions?: AgentOptions
 }
 
+/**
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: only the holder
+ * can tear this agent down. `dispose()` unregisters the agent, stops its loop,
+ * awaits the loop's exit (quiescence — NOT just the `disposed` status flip), and
+ * removes the agent's session from the store, in an order that captures the
+ * loop's final `session/flush` before the session is detached.
+ *
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is only
+ * for the OWNER that created it. Config-created agents (the loop's own startup)
+ * are owned by the loop fiber and never need a handle.
+ */
+export interface AgentHandle {
+  agent: Agent
+  dispose(): Promise<void>
+}
+
 /**
  * The agent-creation factory the loop implementation provides to the registry
  * via {@link AgentRegistry.setFactory}. Kept on the `dsh-agent` interface so
@@ -61,14 +78,18 @@ export interface ResumeAgentOptions {
  * depending on the concrete `dsh-agent-loop` package.
  */
 export interface AgentFactory {
-  /** Create, start, and register a new agent on a caller-supplied session id. */
-  createAgent(options: CreateAgentOptions): Agent
+  /**
+   * Create, start, and register a new agent on a caller-supplied session id.
+   * Returns an {@link AgentHandle} — the owner disposes it to tear down exactly
+   * this agent (unregister + stop loop + await quiescence + remove session).
+   */
+  createAgent(options: CreateAgentOptions): AgentHandle
   /**
    * Load a persisted session and resume an agent on it. Async because it awaits
    * `ctx.sessionPersistence.load`; must be called after that service exists
-   * (consumers inject `sessionPersistence`).
+   * (consumers inject `sessionPersistence`). Returns an {@link AgentHandle}.
    */
-  resume(options: ResumeAgentOptions): Promise<Agent>
+  resume(options: ResumeAgentOptions): Promise<AgentHandle>
 }
 
 /** Thrown when create/resume is called before an agent factory is registered. */
@@ -107,9 +128,10 @@ export class AgentRegistry extends Service {
    * Create, start, and register a new agent through the registered factory.
    * Distinct from {@link register} (which records an already-constructed
    * agent): this constructs the agent and its session. Throws if no factory is
-   * registered.
+   * registered. Returns an {@link AgentHandle} — the owner disposes it to tear
+   * down exactly this agent.
    */
-  create(options: CreateAgentOptions): Agent {
+  create(options: CreateAgentOptions): AgentHandle {
     if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
     return this.factory.createAgent(options)
   }
@@ -117,9 +139,9 @@ export class AgentRegistry extends Service {
   /**
    * Load a persisted session and resume an agent on it through the registered
    * factory. Rejects if no factory is registered; the factory rejects if
-   * session persistence is not configured.
+   * session persistence is not configured. Returns an {@link AgentHandle}.
    */
-  async resume(options: ResumeAgentOptions): Promise<Agent> {
+  async resume(options: ResumeAgentOptions): Promise<AgentHandle> {
     if (this.factory === undefined) throw new Error(NO_FACTORY_MESSAGE)
     return this.factory.resume(options)
   }