@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/control-plane/session-broker-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationSurfaceKind } from '../automation/types.js';
+import type { SurfaceKind } from '../../events/surfaces.js';
 import type { SharedSessionMessage, SharedSessionRecord } from './session-types.js';
 import type { SharedSessionInputRecord } from './session-intents.js';
 export interface SharedSessionStoreSnapshot extends Record<string, unknown> {
@@ -20,6 +20,6 @@ export type SharedSessionMessageSender = {
 };
 export type SharedSessionEventPublisher = (event: string, payload: unknown) => void;
 export declare function dedupeSessionSurfaceKinds(participants: readonly {
-    readonly surfaceKind: AutomationSurfaceKind;
-}[]): AutomationSurfaceKind[];
+    readonly surfaceKind: SurfaceKind;
+}[]): SurfaceKind[];
 //# sourceMappingURL=session-broker-helpers.d.ts.map

package/dist/platform/control-plane/session-broker-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-broker-helpers.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,WAAW,0BAA2B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACtD;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC/E,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,GAAG,SAAS,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;CAChG,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEpF,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAA;CAAE,EAAE,GACvE,qBAAqB,EAAE,CAEzB"}
+{"version":3,"file":"session-broker-helpers.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,MAAM,WAAW,0BAA2B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACtD;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;CAC/E,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,GAAG,IAAI,GAAG,SAAS,CAAC;CACzE,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;CAChG,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEpF,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;CAAE,EAAE,GAC7D,WAAW,EAAE,CAEf"}

package/dist/platform/control-plane/session-broker-inputs.d.ts

@@ -17,5 +17,23 @@ export declare function recordSharedSessionInput(store: SharedSessionInputStore,
 }): SharedSessionInputRecord;
 export declare function updateSharedSessionInput(store: SharedSessionInputStore, sessionId: string, inputId: string, transform: (input: SharedSessionInputRecord) => SharedSessionInputRecord): SharedSessionInputRecord | null;
 export declare function claimNextQueuedSessionInput(store: SharedSessionInputStore, sessionId: string, agentId: string): SharedSessionInputRecord | null;
+/**
+ * Collection read for a live surface: filter a session's inputs by state and/or a
+ * `since` cursor (createdAt, exclusive), oldest-first, capped to `limit`. With
+ * `state: 'queued'` + the last-seen cursor this yields exactly the PENDING inputs
+ * a surface has not collected yet (see SharedSessionBroker.getInputsSince).
+ */
+export declare function filterSessionInputsSince(bucket: readonly SharedSessionInputRecord[], options: {
+    readonly state?: SharedSessionInputRecord['state'] | undefined;
+    readonly since?: number | undefined;
+    readonly limit?: number | undefined;
+}): SharedSessionInputRecord[];
+/**
+ * Surface delivery marking: advance a queued/delivered input as a live surface
+ * collects it (`consumed:false` → 'delivered') or finishes acting on it
+ * (`consumed:true` → 'completed'). Only queued/delivered inputs advance; anything
+ * else is returned unchanged. Returns null when the input is unknown.
+ */
+export declare function markSurfaceInputDelivered(store: SharedSessionInputStore, sessionId: string, inputId: string, consumed: boolean): SharedSessionInputRecord | null;
 export declare function finalizeAgentSessionInputs(store: SharedSessionInputStore, sessionId: string, agentId: string, nextState: Extract<SharedSessionInputRecord['state'], 'completed' | 'failed' | 'cancelled'>, error?: string): SharedSessionInputRecord[];
 //# sourceMappingURL=session-broker-inputs.d.ts.map

package/dist/platform/control-plane/session-broker-inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-broker-inputs.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-inputs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAK1F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAShG;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,KAAK,EAAE;IACL,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,GACA,wBAAwB,CAkC1B;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,wBAAwB,GACvE,wBAAwB,GAAG,IAAI,CAWjC;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,wBAAwB,GAAG,IAAI,CAYjC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,CAAC,wBAAwB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC,EAC3F,KAAK,CAAC,EAAE,MAAM,GACb,wBAAwB,EAAE,CAwB5B"}
+{"version":3,"file":"session-broker-inputs.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-inputs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAK1F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAShG;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,KAAK,EAAE;IACL,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,+BAA+B,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC,GACA,wBAAwB,CAkC1B;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,wBAAwB,GACvE,wBAAwB,GAAG,IAAI,CAWjC;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,wBAAwB,GAAG,IAAI,CAYjC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,wBAAwB,EAAE,EAC3C,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,wBAAwB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACpJ,wBAAwB,EAAE,CAO5B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,OAAO,GAChB,wBAAwB,GAAG,IAAI,CASjC;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,CAAC,wBAAwB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC,EAC3F,KAAK,CAAC,EAAE,MAAM,GACb,wBAAwB,EAAE,CAwB5B"}

package/dist/platform/control-plane/session-broker-inputs.js

@@ -81,6 +81,40 @@ export function claimNextQueuedSessionInput(store, sessionId, agentId) {
     touchSharedSession(store, sessionId);
     return result;
 }
+/**
+ * Collection read for a live surface: filter a session's inputs by state and/or a
+ * `since` cursor (createdAt, exclusive), oldest-first, capped to `limit`. With
+ * `state: 'queued'` + the last-seen cursor this yields exactly the PENDING inputs
+ * a surface has not collected yet (see SharedSessionBroker.getInputsSince).
+ */
+export function filterSessionInputsSince(bucket, options) {
+    const filtered = bucket.filter((entry) => {
+        if (options.state !== undefined && entry.state !== options.state)
+            return false;
+        if (options.since !== undefined && entry.createdAt <= options.since)
+            return false;
+        return true;
+    });
+    return filtered.slice(-Math.max(1, options.limit ?? 100));
+}
+/**
+ * Surface delivery marking: advance a queued/delivered input as a live surface
+ * collects it (`consumed:false` → 'delivered') or finishes acting on it
+ * (`consumed:true` → 'completed'). Only queued/delivered inputs advance; anything
+ * else is returned unchanged. Returns null when the input is unknown.
+ */
+export function markSurfaceInputDelivered(store, sessionId, inputId, consumed) {
+    return updateSharedSessionInput(store, sessionId, inputId, (entry) => {
+        if (consumed) {
+            if (entry.state !== 'queued' && entry.state !== 'delivered')
+                return entry;
+            return { ...entry, state: 'completed', updatedAt: Date.now() };
+        }
+        if (entry.state !== 'queued')
+            return entry;
+        return { ...entry, state: 'delivered', updatedAt: Date.now() };
+    });
+}
 export function finalizeAgentSessionInputs(store, sessionId, agentId, nextState, error) {
     const bucket = store.inputs.get(sessionId);
     if (!bucket)

package/dist/platform/control-plane/session-broker-sessions.d.ts

@@ -1,6 +1,47 @@
 import type { AutomationRouteBinding } from '../automation/routes.js';
-import type { SharedSessionParticipant, SharedSessionRecord, SubmitSharedSessionMessageInput } from './session-types.js';
+import type { CreateSharedSessionInput, ParticipantRouteAttachInput, RegisterSharedSessionInput, SharedSessionCloseReason, SharedSessionParticipant, SharedSessionRecord, SharedSessionRegisterResult } from './session-types.js';
 export declare const RESERVED_SHARED_SESSION_IDS: Set<string>;
+/**
+ * Metadata key under which a closed session records WHY it was closed. Kept in
+ * `metadata` (not a first-class field) so it rides the wire without a schema
+ * change and 0.38 readers ignore it. See {@link SharedSessionCloseReason}.
+ */
+export declare const SESSION_CLOSE_REASON_METADATA_KEY = "closeReason";
+/** Read the close reason off a record's metadata, or undefined when unset/unknown. */
+export declare function readSessionCloseReason(session: SharedSessionRecord): SharedSessionCloseReason | undefined;
+/** Stamp a close reason onto a metadata bag (returns a new object). */
+export declare function withSessionCloseReason(metadata: Record<string, unknown>, reason: SharedSessionCloseReason): Record<string, unknown>;
+/** Strip any close reason from a metadata bag (returns a new object only if needed). */
+export declare function withoutSessionCloseReason(metadata: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Metadata flag marking a session as SURFACE-MANAGED: a spine-registered surface
+ * (via `sessions.register`) owns turn execution and input collection for it. Set
+ * on every register/heartbeat. Steer/follow-up inputs to such a session (when no
+ * daemon agent is live) route to the surface as a queued input the surface
+ * collects — NOT a daemon executor spawn. Kept in metadata (open record) so it
+ * needs no schema change. Daemon-run origins (companion-task/automation, or a
+ * plain /task session) never call register and stay executor-routed.
+ */
+export declare const SESSION_SURFACE_MANAGED_METADATA_KEY = "surfaceManaged";
+/** How recently a participant must have been seen to count as a LIVE surface for
+ * steer/follow-up routing. A surface heartbeats via `sessions.register`; if the
+ * newest heartbeat is older than this, the surface is treated as gone and inputs
+ * fall back to the daemon executor path. */
+export declare const SURFACE_ROUTE_FRESHNESS_MS: number;
+export declare function isSurfaceManagedSession(session: SharedSessionRecord): boolean;
+/**
+ * True when a participant OTHER than `exclude` (the current input's own surface)
+ * was seen within `freshnessMs`. Excluding the sender prevents a steer's own
+ * just-attached participant from making a surfaceless session look live.
+ */
+export declare function hasFreshSurfaceParticipant(session: SharedSessionRecord, now: number, freshnessMs: number, exclude?: {
+    readonly surfaceId?: string | undefined;
+}): boolean;
+/** Steer/follow-up to this session should route to a live surface (queue-for-surface)
+ * rather than spawn a daemon executor. */
+export declare function shouldRouteInputToSurface(session: SharedSessionRecord, now: number, freshnessMs: number, exclude?: {
+    readonly surfaceId?: string | undefined;
+}): boolean;
 export interface CreateSharedSessionRecordInput {
     readonly id?: string | undefined;
     readonly title?: string | undefined;
@@ -8,15 +49,73 @@ export interface CreateSharedSessionRecordInput {
     readonly routeBinding?: AutomationRouteBinding | undefined;
     readonly participant?: SharedSessionParticipant | undefined;
     readonly kind?: SharedSessionRecord['kind'] | undefined;
+    readonly project?: string | undefined;
 }
 export declare function assertSharedSessionIdAllowed(id: string | undefined): void;
 export declare function createSharedSessionRecord(input: CreateSharedSessionRecordInput): SharedSessionRecord;
-export declare function closeSharedSessionRecord(session: SharedSessionRecord): SharedSessionRecord;
+/**
+ * Shape a participant triple into the attach-input the broker's
+ * participant/route merge expects. Used by `register` so a heartbeat re-attaches
+ * the participant (advancing `lastSeenAt`) without carrying a message body.
+ */
+/** The broker operations {@link registerSharedSession} needs, injected so the
+ * register control-flow lives here instead of bloating the broker class. */
+export interface RegisterBrokerOps {
+    getSession(id: string): SharedSessionRecord | null;
+    createSession(input: CreateSharedSessionInput): Promise<SharedSessionRecord>;
+    reopenSession(id: string): Promise<SharedSessionRecord | null>;
+    attachParticipant(session: SharedSessionRecord, attach: ParticipantRouteAttachInput): Promise<SharedSessionRecord>;
+}
+/**
+ * The idempotent register/heartbeat control-flow with HONEST closed semantics:
+ * a brand-new id is created; an existing OPEN id adopts the participant; an
+ * existing CLOSED id records the heartbeat but stays closed (returning a conflict
+ * marker) UNLESS `reopen: true` is passed. A titled session is never renamed by
+ * the heartbeat (that rule lives in {@link attachSharedSessionParticipantAndRoute}).
+ */
+export declare function registerSharedSession(ops: RegisterBrokerOps, input: RegisterSharedSessionInput): Promise<SharedSessionRegisterResult>;
+export declare function participantToAttachInput(participant: SharedSessionParticipant, title?: string): ParticipantRouteAttachInput;
+/** Close a session, recording WHY. Defaults to 'user' — the explicit close verb
+ * (daemon `sessions.close`) is a deliberate user/surface action, which does NOT
+ * auto-reopen on heartbeat. The reaper passes 'idle-reaped'. */
+export declare function closeSharedSessionRecord(session: SharedSessionRecord, reason?: SharedSessionCloseReason): SharedSessionRecord;
 export declare function reopenSharedSessionRecord(session: SharedSessionRecord): SharedSessionRecord;
 export declare function bindSharedSessionAgent(session: SharedSessionRecord, agentId: string): SharedSessionRecord;
+/**
+ * True when a session title is still the auto-generated placeholder (empty or
+ * `Session <id>`) and can be named by an incoming register/attach. A real,
+ * user-supplied title is never overwritten by this path.
+ */
+export declare function isPlaceholderSessionTitle(title: string, id: string): boolean;
+/**
+ * Merge a participant + optional route onto a session. This is the HEARTBEAT
+ * path — it records the participant and advances lastSeenAt, but it must NOT by
+ * itself change lifecycle status (a closed session stays closed; reopening is an
+ * explicit verb) and must NOT overwrite a real title (only names a placeholder).
+ */
 export declare function attachSharedSessionParticipantAndRoute(input: {
     readonly session: SharedSessionRecord;
-    readonly message: Omit<SubmitSharedSessionMessageInput, 'metadata'>;
+    readonly message: ParticipantRouteAttachInput;
     readonly binding?: AutomationRouteBinding | undefined;
 }): SharedSessionRecord;
+/**
+ * The inverse of {@link attachSharedSessionParticipantAndRoute}: remove EVERY
+ * participant bound to `surfaceId` and unbind the route bindings those
+ * participants alone held. This is "detach != close != kill" — the session and
+ * all other participants keep running; the detached surface simply stops being a
+ * routing target (and, filtered by domain, stops receiving session updates).
+ *
+ * Route pruning is conservative: a routeId is dropped from the session only when
+ * NO surviving participant still references it, so detaching one surface never
+ * severs another surface's live binding.
+ *
+ * Returns `{ session, changed }`. `changed` is false when no participant matched
+ * `surfaceId` (the caller can treat a no-match detach as an idempotent no-op and
+ * skip persistence/emit). Status, title, and closedAt are preserved untouched —
+ * detach is never a lifecycle transition.
+ */
+export declare function detachSharedSessionParticipant(session: SharedSessionRecord, surfaceId: string): {
+    readonly session: SharedSessionRecord;
+    readonly changed: boolean;
+};
 //# sourceMappingURL=session-broker-sessions.d.ts.map

package/dist/platform/control-plane/session-broker-sessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-broker-sessions.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-sessions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,+BAA+B,EAChC,MAAM,oBAAoB,CAAC;AAI5B,eAAO,MAAM,2BAA2B,aAA0B,CAAC;AAEnE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACzD;AAED,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMzE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,8BAA8B,GAAG,mBAAmB,CA6BpG;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAS1F;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAO3F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,CASzG;AAED,wBAAgB,sCAAsC,CAAC,KAAK,EAAE;IAC5D,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,+BAA+B,EAAE,UAAU,CAAC,CAAC;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CACvD,GAAG,mBAAmB,CA0BtB"}
+{"version":3,"file":"session-broker-sessions.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-sessions.ts"],"names":[],"mappings":"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"}

package/dist/platform/control-plane/session-broker-sessions.js

@@ -2,6 +2,64 @@ import { randomUUID } from 'node:crypto';
 import { dedupeSessionSurfaceKinds } from './session-broker-helpers.js';
 import { upsertSessionParticipant } from './session-broker-state.js';
 export const RESERVED_SHARED_SESSION_IDS = new Set(['', 'system']);
+/**
+ * Metadata key under which a closed session records WHY it was closed. Kept in
+ * `metadata` (not a first-class field) so it rides the wire without a schema
+ * change and 0.38 readers ignore it. See {@link SharedSessionCloseReason}.
+ */
+export const SESSION_CLOSE_REASON_METADATA_KEY = 'closeReason';
+/** Read the close reason off a record's metadata, or undefined when unset/unknown. */
+export function readSessionCloseReason(session) {
+    const raw = session.metadata?.[SESSION_CLOSE_REASON_METADATA_KEY];
+    return raw === 'idle-reaped' || raw === 'user' || raw === 'surface' ? raw : undefined;
+}
+/** Stamp a close reason onto a metadata bag (returns a new object). */
+export function withSessionCloseReason(metadata, reason) {
+    return { ...metadata, [SESSION_CLOSE_REASON_METADATA_KEY]: reason };
+}
+/** Strip any close reason from a metadata bag (returns a new object only if needed). */
+export function withoutSessionCloseReason(metadata) {
+    if (!(SESSION_CLOSE_REASON_METADATA_KEY in metadata))
+        return metadata;
+    const next = { ...metadata };
+    delete next[SESSION_CLOSE_REASON_METADATA_KEY];
+    return next;
+}
+/**
+ * Metadata flag marking a session as SURFACE-MANAGED: a spine-registered surface
+ * (via `sessions.register`) owns turn execution and input collection for it. Set
+ * on every register/heartbeat. Steer/follow-up inputs to such a session (when no
+ * daemon agent is live) route to the surface as a queued input the surface
+ * collects — NOT a daemon executor spawn. Kept in metadata (open record) so it
+ * needs no schema change. Daemon-run origins (companion-task/automation, or a
+ * plain /task session) never call register and stay executor-routed.
+ */
+export const SESSION_SURFACE_MANAGED_METADATA_KEY = 'surfaceManaged';
+/** How recently a participant must have been seen to count as a LIVE surface for
+ * steer/follow-up routing. A surface heartbeats via `sessions.register`; if the
+ * newest heartbeat is older than this, the surface is treated as gone and inputs
+ * fall back to the daemon executor path. */
+export const SURFACE_ROUTE_FRESHNESS_MS = 2 * 60 * 1000;
+export function isSurfaceManagedSession(session) {
+    return session.metadata?.[SESSION_SURFACE_MANAGED_METADATA_KEY] === true;
+}
+/**
+ * True when a participant OTHER than `exclude` (the current input's own surface)
+ * was seen within `freshnessMs`. Excluding the sender prevents a steer's own
+ * just-attached participant from making a surfaceless session look live.
+ */
+export function hasFreshSurfaceParticipant(session, now, freshnessMs, exclude) {
+    return session.participants.some((participant) => {
+        if (exclude?.surfaceId && participant.surfaceId === exclude.surfaceId)
+            return false;
+        return now - participant.lastSeenAt < freshnessMs;
+    });
+}
+/** Steer/follow-up to this session should route to a live surface (queue-for-surface)
+ * rather than spawn a daemon executor. */
+export function shouldRouteInputToSurface(session, now, freshnessMs, exclude) {
+    return isSurfaceManagedSession(session) && hasFreshSurfaceParticipant(session, now, freshnessMs, exclude);
+}
 export function assertSharedSessionIdAllowed(id) {
     if (id === undefined || !RESERVED_SHARED_SESSION_IDS.has(id))
         return;
@@ -17,6 +75,7 @@ export function createSharedSessionRecord(input) {
     return {
         id: sessionId,
         kind: input.kind ?? 'tui',
+        project: input.project?.trim() || 'unknown',
         title: input.title?.trim() || input.routeBinding?.title || `Session ${sessionId}`,
         status: 'active',
         createdAt: now,
@@ -37,7 +96,56 @@ export function createSharedSessionRecord(input) {
         },
     };
 }
-export function closeSharedSessionRecord(session) {
+/**
+ * The idempotent register/heartbeat control-flow with HONEST closed semantics:
+ * a brand-new id is created; an existing OPEN id adopts the participant; an
+ * existing CLOSED id records the heartbeat but stays closed (returning a conflict
+ * marker) UNLESS `reopen: true` is passed. A titled session is never renamed by
+ * the heartbeat (that rule lives in {@link attachSharedSessionParticipantAndRoute}).
+ */
+export async function registerSharedSession(ops, input) {
+    const existing = ops.getSession(input.sessionId);
+    if (!existing) {
+        const created = await ops.createSession({
+            id: input.sessionId,
+            ...(input.kind !== undefined ? { kind: input.kind } : {}),
+            ...(input.project !== undefined ? { project: input.project } : {}),
+            ...(input.title !== undefined ? { title: input.title } : {}),
+            participant: input.participant,
+        });
+        return { record: created, reopened: false };
+    }
+    const attach = participantToAttachInput(input.participant, input.title);
+    if (existing.status === 'closed') {
+        // Reopen honesty: a session the SYSTEM reaper closed ('idle-reaped') reopens
+        // automatically on the next participant heartbeat — the surface never
+        // deliberately closed it, so re-registering is not a conflict. An explicit
+        // 'user'/'surface' close stays closed (honest conflict) unless reopen:true.
+        const systemReaped = readSessionCloseReason(existing) === 'idle-reaped';
+        if (input.reopen === true || systemReaped) {
+            const reopened = (await ops.reopenSession(existing.id)) ?? existing;
+            return { record: await ops.attachParticipant(reopened, attach), reopened: true };
+        }
+        return { record: await ops.attachParticipant(existing, attach), reopened: false, conflict: { status: 'closed' } };
+    }
+    return { record: await ops.attachParticipant(existing, attach), reopened: false };
+}
+export function participantToAttachInput(participant, title) {
+    return {
+        surfaceKind: participant.surfaceKind,
+        surfaceId: participant.surfaceId,
+        externalId: participant.externalId,
+        userId: participant.userId,
+        displayName: participant.displayName,
+        routeId: participant.routeId,
+        ...(title ? { title } : {}),
+        body: '',
+    };
+}
+/** Close a session, recording WHY. Defaults to 'user' — the explicit close verb
+ * (daemon `sessions.close`) is a deliberate user/surface action, which does NOT
+ * auto-reopen on heartbeat. The reaper passes 'idle-reaped'. */
+export function closeSharedSessionRecord(session, reason = 'user') {
     const now = Date.now();
     return {
         ...session,
@@ -45,6 +153,7 @@ export function closeSharedSessionRecord(session) {
         activeAgentId: undefined,
         updatedAt: now,
         closedAt: now,
+        metadata: withSessionCloseReason(session.metadata, reason),
     };
 }
 export function reopenSharedSessionRecord(session) {
@@ -53,6 +162,9 @@ export function reopenSharedSessionRecord(session) {
         status: 'active',
         updatedAt: Date.now(),
         closedAt: undefined,
+        // A reopened session is no longer closed-for-any-reason; clear the marker so
+        // it never carries a stale close reason on the wire.
+        metadata: withoutSessionCloseReason(session.metadata),
     };
 }
 export function bindSharedSessionAgent(session, agentId) {
@@ -65,6 +177,21 @@ export function bindSharedSessionAgent(session, agentId) {
         lastActivityAt: now,
     };
 }
+/**
+ * True when a session title is still the auto-generated placeholder (empty or
+ * `Session <id>`) and can be named by an incoming register/attach. A real,
+ * user-supplied title is never overwritten by this path.
+ */
+export function isPlaceholderSessionTitle(title, id) {
+    const trimmed = title.trim();
+    return trimmed.length === 0 || trimmed === `Session ${id}`;
+}
+/**
+ * Merge a participant + optional route onto a session. This is the HEARTBEAT
+ * path — it records the participant and advances lastSeenAt, but it must NOT by
+ * itself change lifecycle status (a closed session stays closed; reopening is an
+ * explicit verb) and must NOT overwrite a real title (only names a placeholder).
+ */
 export function attachSharedSessionParticipantAndRoute(input) {
     const nextRouteIds = input.binding?.id
         ? [...new Set([...input.session.routeIds, input.binding.id])]
@@ -78,12 +205,23 @@ export function attachSharedSessionParticipantAndRoute(input) {
         routeId: input.binding?.id,
         lastSeenAt: Date.now(),
     });
+    const incomingTitle = input.message.title?.trim();
+    const title = incomingTitle && isPlaceholderSessionTitle(input.session.title, input.session.id)
+        ? incomingTitle
+        : input.session.title;
+    const now = Date.now();
     return {
         ...input.session,
-        title: input.message.title?.trim() || input.session.title,
-        status: input.session.status === 'closed' ? 'active' : input.session.status,
-        updatedAt: Date.now(),
-        closedAt: input.session.status === 'closed' ? undefined : input.session.closedAt,
+        title,
+        // Status is intentionally preserved: the participant merge is a heartbeat and
+        // cannot flip a closed session back to active. Reopening is an explicit verb.
+        status: input.session.status,
+        updatedAt: now,
+        // A register heartbeat IS session activity: advance lastActivityAt (not only
+        // the participant's lastSeenAt) so the idle-empty reaper does not close a
+        // live, message-less surface session out from under a heartbeating participant.
+        lastActivityAt: now,
+        closedAt: input.session.closedAt,
         routeIds: nextRouteIds,
         participants,
         surfaceKinds: dedupeSessionSurfaceKinds(participants),
@@ -92,3 +230,39 @@ export function attachSharedSessionParticipantAndRoute(input) {
         },
     };
 }
+/**
+ * The inverse of {@link attachSharedSessionParticipantAndRoute}: remove EVERY
+ * participant bound to `surfaceId` and unbind the route bindings those
+ * participants alone held. This is "detach != close != kill" — the session and
+ * all other participants keep running; the detached surface simply stops being a
+ * routing target (and, filtered by domain, stops receiving session updates).
+ *
+ * Route pruning is conservative: a routeId is dropped from the session only when
+ * NO surviving participant still references it, so detaching one surface never
+ * severs another surface's live binding.
+ *
+ * Returns `{ session, changed }`. `changed` is false when no participant matched
+ * `surfaceId` (the caller can treat a no-match detach as an idempotent no-op and
+ * skip persistence/emit). Status, title, and closedAt are preserved untouched —
+ * detach is never a lifecycle transition.
+ */
+export function detachSharedSessionParticipant(session, surfaceId) {
+    const remaining = session.participants.filter((participant) => participant.surfaceId !== surfaceId);
+    if (remaining.length === session.participants.length) {
+        return { session, changed: false };
+    }
+    const survivingRouteIds = new Set(remaining
+        .map((participant) => participant.routeId)
+        .filter((routeId) => typeof routeId === 'string'));
+    const routeIds = session.routeIds.filter((routeId) => survivingRouteIds.has(routeId));
+    return {
+        session: {
+            ...session,
+            updatedAt: Date.now(),
+            participants: remaining,
+            surfaceKinds: dedupeSessionSurfaceKinds(remaining),
+            routeIds,
+        },
+        changed: true,
+    };
+}

package/dist/platform/control-plane/session-broker-state.d.ts

@@ -9,11 +9,30 @@ export declare function loadSessionBrokerState(snapshot: SharedSessionStoreSnaps
     readonly messages: Map<string, SharedSessionMessage[]>;
     readonly inputs: Map<string, SharedSessionInputRecord[]>;
 };
+/**
+ * Build the durable snapshot with a PER-SESSION message cap.
+ *
+ * `maxPersistedMessagesPerSession` bounds each session's retained bodies
+ * independently — NOT the flattened total. The old global slice-after-flatten
+ * behaviour silently dropped whole sessions' transcripts (the oldest ones) once
+ * the combined message count crossed the cap, while `messageCount` stayed
+ * inflated. Capping per session keeps every session's most recent bodies and,
+ * when a session IS truncated, stamps `retainedMessageCount` so the loss is
+ * honest rather than silent (see {@link SharedSessionRecord.retainedMessageCount}).
+ */
 export declare function createSessionBrokerSnapshot(state: {
     readonly sessions: ReadonlyMap<string, SharedSessionRecord>;
     readonly messages: ReadonlyMap<string, readonly SharedSessionMessage[]>;
     readonly inputs: ReadonlyMap<string, readonly SharedSessionInputRecord[]>;
-}, maxPersistedMessages: number): SharedSessionStoreSnapshot;
+}, maxPersistedMessagesPerSession: number): SharedSessionStoreSnapshot;
 export declare function upsertSessionParticipant(participants: readonly SharedSessionParticipant[], participant: SharedSessionParticipant): SharedSessionParticipant[];
+/**
+ * Boot-time reconciliation of a freshly-loaded broker state (mutates in place):
+ * cancels inputs stuck in `spawned`/`delivered` from a prior run (agent state is
+ * unknown after a restart) and clears stale `activeAgentId` on every session.
+ * Returns the set of session ids whose input buckets changed so the caller can
+ * refresh their pending counts.
+ */
+export declare function reconcileSessionBrokerBoot(sessions: Map<string, SharedSessionRecord>, inputs: Map<string, SharedSessionInputRecord[]>): Set<string>;
 export declare function countPendingSessionInputs(records: readonly SharedSessionInputRecord[]): number;
 //# sourceMappingURL=session-broker-state.d.ts.map

package/dist/platform/control-plane/session-broker-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-broker-state.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAyQ9G,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,EAAE,CAE1F;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,EAAE,CAE5F;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,EAAE,CAElG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GAAG;IAC/F,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;CAC1D,CAsCA;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE;IACL,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC,CAAC;CAC3E,EACD,oBAAoB,EAAE,MAAM,GAC3B,0BAA0B,CAQ5B;AAED,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,SAAS,wBAAwB,EAAE,EACjD,WAAW,EAAE,wBAAwB,GACpC,wBAAwB,EAAE,CAM5B;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,GAAG,MAAM,CAI9F"}
+{"version":3,"file":"session-broker-state.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA8Q9G,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,EAAE,CAE1F;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,EAAE,CAE5F;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,EAAE,CAElG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,GAAG,SAAS,GAAG;IAC/F,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;CAC1D,CAsCA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE;IACL,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC,CAAC;IACxE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,wBAAwB,EAAE,CAAC,CAAC;CAC3E,EACD,8BAA8B,EAAE,MAAM,GACrC,0BAA0B,CA2B5B;AAED,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,SAAS,wBAAwB,EAAE,EACjD,WAAW,EAAE,wBAAwB,GACpC,wBAAwB,EAAE,CAM5B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC1C,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,GAC9C,GAAG,CAAC,MAAM,CAAC,CAkBb;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,GAAG,MAAM,CAI9F"}

package/dist/platform/control-plane/session-broker-state.js

@@ -1,6 +1,6 @@
 import { SHARED_SESSION_INPUT_INTENTS, SHARED_SESSION_INPUT_STATES, } from './session-intents.js';
 import { isRecord } from '../utils/record-coerce.js';
-const SESSION_KINDS = new Set(['tui', 'companion-task', 'companion-chat']);
+const SESSION_KINDS = new Set(['tui', 'agent', 'webui', 'companion-task', 'companion-chat', 'automation']);
 const SESSION_STATUSES = new Set(['active', 'closed']);
 const MESSAGE_ROLES = new Set(['user', 'assistant', 'system']);
 function isFiniteNumber(value) {
@@ -78,6 +78,7 @@ function normalizeSessionRecord(value, messages, inputs) {
     validateOptionalNumber(value['updatedAt']);
     validateOptionalNumber(value['lastActivityAt']);
     validateOptionalNumber(value['messageCount']);
+    validateOptionalNumber(value['retainedMessageCount']);
     validateOptionalNumber(value['pendingInputCount']);
     validateOptionalNumber(value['lastMessageAt']);
     validateOptionalNumber(value['closedAt']);
@@ -120,6 +121,7 @@ function normalizeSessionRecord(value, messages, inputs) {
         kind: typeof value['kind'] === 'string' && SESSION_KINDS.has(value['kind'])
             ? value['kind']
             : 'tui',
+        project: typeof value['project'] === 'string' && value['project'].length > 0 ? value['project'] : 'unknown',
         title: typeof value['title'] === 'string' && value['title'].trim().length > 0 ? value['title'] : `Session ${id}`,
         status: typeof value['status'] === 'string' && SESSION_STATUSES.has(value['status'])
             ? value['status']
@@ -130,6 +132,9 @@ function normalizeSessionRecord(value, messages, inputs) {
         ...(closedAt !== undefined ? { closedAt } : {}),
         lastActivityAt,
         messageCount: Math.max(isFiniteNumber(value['messageCount']) ? value['messageCount'] : 0, messages.length),
+        ...(isFiniteNumber(value['retainedMessageCount']) && value['retainedMessageCount'] < Math.max(isFiniteNumber(value['messageCount']) ? value['messageCount'] : 0, messages.length)
+            ? { retainedMessageCount: value['retainedMessageCount'] }
+            : {}),
         pendingInputCount: Math.max(isFiniteNumber(value['pendingInputCount']) ? value['pendingInputCount'] : 0, countPendingSessionInputs(inputs)),
         routeIds,
         surfaceKinds,
@@ -284,12 +289,43 @@ export function loadSessionBrokerState(snapshot) {
     }
     return { sessions, messages, inputs };
 }
-export function createSessionBrokerSnapshot(state, maxPersistedMessages) {
-    const messages = [...state.messages.values()].flatMap((bucket) => bucket);
+/**
+ * Build the durable snapshot with a PER-SESSION message cap.
+ *
+ * `maxPersistedMessagesPerSession` bounds each session's retained bodies
+ * independently — NOT the flattened total. The old global slice-after-flatten
+ * behaviour silently dropped whole sessions' transcripts (the oldest ones) once
+ * the combined message count crossed the cap, while `messageCount` stayed
+ * inflated. Capping per session keeps every session's most recent bodies and,
+ * when a session IS truncated, stamps `retainedMessageCount` so the loss is
+ * honest rather than silent (see {@link SharedSessionRecord.retainedMessageCount}).
+ */
+export function createSessionBrokerSnapshot(state, maxPersistedMessagesPerSession) {
+    const cap = Math.max(1, maxPersistedMessagesPerSession);
+    const cappedMessages = [];
+    const retainedBySession = new Map();
+    for (const [sessionId, bucket] of state.messages.entries()) {
+        const retained = sortMessages(bucket).slice(-cap);
+        for (const message of retained)
+            cappedMessages.push(message);
+        retainedBySession.set(sessionId, retained.length);
+    }
     const inputs = [...state.inputs.values()].flatMap((bucket) => bucket);
+    const sessions = sortSessions(state.sessions.values()).map((session) => {
+        const retained = retainedBySession.get(session.id) ?? 0;
+        if (retained < session.messageCount) {
+            return { ...session, retainedMessageCount: retained };
+        }
+        // Nothing pruned — drop any stale marker so the common case carries none.
+        if (session.retainedMessageCount !== undefined) {
+            const { retainedMessageCount: _drop, ...rest } = session;
+            return rest;
+        }
+        return session;
+    });
     return {
-        sessions: sortSessions(state.sessions.values()),
-        messages: sortMessages(messages).slice(-maxPersistedMessages),
+        sessions,
+        messages: sortMessages(cappedMessages),
         inputs: sortInputs(inputs),
     };
 }
@@ -300,6 +336,32 @@ export function upsertSessionParticipant(participants, participant) {
         participant,
     ];
 }
+/**
+ * Boot-time reconciliation of a freshly-loaded broker state (mutates in place):
+ * cancels inputs stuck in `spawned`/`delivered` from a prior run (agent state is
+ * unknown after a restart) and clears stale `activeAgentId` on every session.
+ * Returns the set of session ids whose input buckets changed so the caller can
+ * refresh their pending counts.
+ */
+export function reconcileSessionBrokerBoot(sessions, inputs) {
+    const restartReason = 'daemon restart — agent state unknown';
+    const changed = new Set();
+    for (const [sessionId, bucket] of inputs.entries()) {
+        for (let i = 0; i < bucket.length; i++) {
+            const entry = bucket[i];
+            if (entry.state === 'spawned' || entry.state === 'delivered') {
+                bucket[i] = { ...entry, state: 'cancelled', updatedAt: Date.now(), error: restartReason };
+                changed.add(sessionId);
+            }
+        }
+    }
+    for (const [sessionId, session] of sessions.entries()) {
+        if (session.activeAgentId) {
+            sessions.set(sessionId, { ...session, activeAgentId: undefined, updatedAt: Date.now() });
+        }
+    }
+    return changed;
+}
 export function countPendingSessionInputs(records) {
     return records.filter((entry) => entry.state === 'queued' || entry.state === 'delivered' || entry.state === 'spawned').length;
 }