Merge remote-tracking branch 'origin/master' into worktree/session-reference

# Conflicts:
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/module-graph.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/ui/acp/README.md
#	packages/ui/acp/package.json
#	packages/ui/acp/tsconfig.json
#	packages/ui/tui/package.json
#	packages/ui/tui/src/index.ts
#	packages/ui/tui/tests/tui.spec.ts
#	packages/ui/tui/tsconfig.json
#	pnpm-lock.yaml
#	python/sdk-runtime/package.json
#	scripts/gen-doc-graphs.ts
#	scripts/type-equiv.manifest.json

docs/cordis-catalog/events.md

@@ -535,11 +535,11 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
  * Waterfall around every streaming model call (retry, replay, routing).
  * Bound to the {@link LlmService}; call `next()` to reach the resolved
  * adapter's stream, or yield your own chunks to short-circuit.
- * @param options - the full request. A LOOP-built request arrives
- *   deep-frozen (mutation throws): its content is a pure function of the
- *   session log (the reconstructability Agent Note), so listeners read it, never
- *   rewrite it. A hand-built one-shot (compaction summarize) is the
- *   caller's own object and stays mutable here.
+ * @param options - the full request. A LOOP-built request carries the
+ *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+ *   (mutation throws): its content is a pure function of the session log (the
+ *   reconstructability Agent Note), so listeners read it, never rewrite it.
+ *   Hand-built calls own their mutability policy and do not carry that marker.
  * @mode waterfall
  */
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
@@ -572,7 +572,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:47`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:68`](../../packages/core/session/src/index.ts)
 
 ### `session/disposed` — emit
 
@@ -593,7 +593,7 @@ Emitted once when an announced session leaves the store, including publication r
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:78`](../../packages/core/session/src/index.ts)
 
 ### `session/event` — emit
 
@@ -616,7 +616,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:69`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:90`](../../packages/core/session/src/index.ts)
 
 ### `session/flush` — parallel
 
@@ -637,7 +637,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 
 Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:79`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:100`](../../packages/core/session/src/index.ts)
 
 ## `subagent/*`
 

docs/cordis-catalog/services.md

@@ -829,6 +829,13 @@ Live-preferred logical-corpus exact-read and relationship-tracing service.
  */
 listSessions(): Promise<SessionRecord[]>
 
+/**
+ * Fold the latest log-backed title from one live-preferred logical session.
+ * @param sessionId - live or persisted session id to read.
+ * @returns latest title snapshot, or `undefined` when the log has no title event.
+ */
+async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>
+
 /**
  * List lightweight raw-log event records for one logical session.
  * @param sessionId - live-preferred session id to read.
@@ -868,9 +875,9 @@ async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
 async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
 ```
 
-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md)
+Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
 
-Source: [`packages/session-query/session-query/src/index.ts:39`](../../packages/session-query/session-query/src/index.ts)
+Source: [`packages/session-query/session-query/src/index.ts:41`](../../packages/session-query/session-query/src/index.ts)
 
 ## `ctx.sessionReferences` — `SessionReferenceService`
 
@@ -878,12 +885,12 @@ Exact-read consumer that prepares immutable cross-session message context.
 
 ```ts cordis-catalog
 /**
- * List metadata-only reference candidates, ranked by working-directory affinity.
+ * List reference candidates, ranked by working-directory affinity.
  * @param agent - target agent; self is excluded and its cwd drives ranking.
  * @param query - optional case-insensitive session-id/cwd substring.
  * @param limit - optional positive result cap.
  * @param signal - optional cancellation boundary for host autocomplete teardown.
- * @returns candidate records in stable source creation order within each rank.
+ * @returns candidates labeled by latest title or, when absent, session id.
  */
 async listCandidates( agent: Agent, query = '', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
 
@@ -996,6 +1003,28 @@ announce(session: Session): void
  */
 async flush(session: Session): Promise<void>
 
+/**
+ * Append one plugin-declared log-only event without borrowing the agent
+ * loop's lifecycle. An open turn receives the event directly and remains
+ * responsible for its ordinary checkpoint. A closed log receives one
+ * zero-step turn around the event, followed by an awaited flush.
+ *
+ * Once the synthetic `turn/start` commits, this method always attempts its
+ * matching `turn/end` and flush, including when the target append fails.
+ * Detachment requested by an event or flush listener is deferred until that
+ * sequence settles, so publication cannot switch from a live scoped session
+ * to an unobserved bare `Session` halfway through the update.
+ *
+ * @param session - exact live session that owns the target log.
+ * @param type - event type opted into {@link OutOfBandSessionEventMap} by its owner.
+ * @param data - typed JSON payload for the target event.
+ * @param trigger - plugin-owned turn trigger used only when the log is closed.
+ * @returns the accepted target event with its assigned sequence and timestamp.
+ * @throws when the session is detached, another out-of-band append is active,
+ *   event acceptance fails, the synthetic turn cannot close, or flushing fails.
+ */
+async appendOutOfBand<T extends OutOfBandSessionEventType>( session: Session, type: T, data: SessionEventMap[T], trigger: TurnTrigger, ): Promise<SessionEvent<T>>
+
 /**
  * Look up a live session.
  * @param id - the session id to look up.
@@ -1025,9 +1054,43 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
+Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [OutOfBandSessionEventType](../core-data-structures/session.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md) · [SessionEventMap](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md) · [TurnTrigger](../core-data-structures/session.md)
 
-Source: [`packages/core/session/src/index.ts:570`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:592`](../../packages/core/session/src/index.ts)
+
+## `ctx.sessionTitle` — `SessionTitleService`
+
+Log-backed title fold plus asynchronous fallback generation.
+
+```ts cordis-catalog
+/**
+ * Read the latest folded title from one live or replayed session.
+ * @param session - session whose log is the title source of truth.
+ * @returns latest title snapshot, or `undefined` before eligible input.
+ */
+get(session: Session): SessionTitleSnapshot | undefined
+
+/**
+ * Explicitly retry the registered provider, or materialize the built-in
+ * fallback when no provider is registered.
+ * @param session - exact live session to refresh.
+ * @param signal - optional caller cancellation; an in-progress fallback append may finish durably before rejection.
+ * @returns latest accepted title, or `undefined` when no eligible text exists.
+ */
+async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Register the sole optional title provider. Disposal aborts its pending and
+ * active work before another provider may register.
+ * @param provider - provider identity, cadence, and generation function.
+ * @returns exact Cordis effect disposer, which settles after active calls quiesce.
+ */
+register(provider: SessionTitleProvider): () => Promise<void>
+```
+
+Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+
+Source: [`packages/session-title/session-title/src/index.ts:282`](../../packages/session-title/session-title/src/index.ts)
 
 ## `ctx.skills` — `SkillService`