@pellux/goodvibes-sdk 0.38.0 → 1.1.0

package/dist/platform/control-plane/routes/register-gateway-verb-groups.d.ts

@@ -0,0 +1,31 @@
+/**
+ * routes/register-gateway-verb-groups.ts
+ *
+ * One entry point the runtime-services composition root calls to attach every
+ * handler-registered gateway verb group, so services.ts needs a single import
+ * and a single call regardless of how many groups exist.
+ *
+ * It folds in the pre-existing fleet / checkpoints / sessions.search group
+ * (registerW3S2GatewayMethods, unchanged) and constructs + wires the browser-
+ * push group: a PushService over the subscription store and VAPID key custody,
+ * its verb handlers, and — the real event source — a subscription to the
+ * approval broker so an approval that needs a decision fans out as a push to the
+ * operator's registered devices.
+ */
+import type { GatewayMethodCatalog } from '../method-catalog.js';
+import { type W3S2GatewayDeps } from './register-w3-s2.js';
+import { type ApprovalSource, type VapidSecretStore } from '../../push/index.js';
+export interface GatewayVerbGroupDeps extends W3S2GatewayDeps {
+    /** SecretsManager (get/set) — VAPID keypair custody lives here, never in config. */
+    readonly secretsManager: VapidSecretStore;
+    /** The approval broker — the real event source push fans out from. */
+    readonly approvalBroker: ApprovalSource;
+    /** Home-scoped path service; the subscription store file resolves under it. */
+    readonly shellPaths: {
+        resolveUserPath(...segments: string[]): string;
+    };
+    /** Optional VAPID JWT `sub` contact. */
+    readonly vapidSubject?: string | undefined;
+}
+export declare function registerGatewayVerbGroups(catalog: GatewayMethodCatalog, deps: GatewayVerbGroupDeps): void;
+//# sourceMappingURL=register-gateway-verb-groups.d.ts.map

package/dist/platform/control-plane/routes/register-gateway-verb-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-gateway-verb-groups.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/register-gateway-verb-groups.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAA8B,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEvF,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,oFAAoF;IACpF,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE;QAAE,eAAe,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;KAAE,CAAC;IACxE,wCAAwC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAezG"}

package/dist/platform/control-plane/routes/register-gateway-verb-groups.js

@@ -0,0 +1,16 @@
+import { registerW3S2GatewayMethods } from './register-w3-s2.js';
+import { registerPushGatewayMethods } from './push.js';
+import { PushService, PushSubscriptionStore, VapidManager, } from '../../push/index.js';
+export function registerGatewayVerbGroups(catalog, deps) {
+    registerW3S2GatewayMethods(catalog, deps);
+    const pushService = new PushService({
+        vapid: new VapidManager(deps.secretsManager, { subject: deps.vapidSubject }),
+        store: new PushSubscriptionStore(deps.shellPaths.resolveUserPath('control-plane', 'push-subscriptions.json')),
+    });
+    registerPushGatewayMethods(catalog, pushService);
+    // Real event source: approvals-needed -> push to every registered device.
+    // The unsubscribe handle is intentionally not retained — the subscription
+    // lives for the daemon's lifetime, exactly like the fleet/checkpoint verb
+    // registrations above (there is no RuntimeServices-wide shutdown seam yet).
+    pushService.attachApprovalSource(deps.approvalBroker);
+}

package/dist/platform/control-plane/routes/register-w3-s2.d.ts

@@ -0,0 +1,26 @@
+/**
+ * routes/register-w3-s2.ts
+ *
+ * Single composite entry point for the fleet.*, checkpoints.*, sessions.search
+ * verb-registration calls (see CHANGELOG 1.0.0), so ../../runtime/services.ts —
+ * already at its line-cap ceiling — only needs one import and one call
+ * instead of three of each. See routes/fleet.ts, routes/checkpoints.ts, and
+ * routes/session-search.ts for what each registration actually does and why
+ * it's a catalog.register(descriptor, handler) call rather than a daemon-sdk
+ * REST route or a router.ts change.
+ *
+ * Call once, at RuntimeServices construction time, after processRegistry,
+ * workspaceCheckpointManager, and sessionBroker all exist (processRegistry
+ * is constructed last of the three, so the call site is right after it).
+ */
+import type { GatewayMethodCatalog } from '../method-catalog.js';
+import { type FleetQueryOnlyRegistry } from './fleet.js';
+import { type CheckpointsGatewayManager } from './checkpoints.js';
+import { type SessionSearchBroker } from './session-search.js';
+export interface W3S2GatewayDeps {
+    readonly processRegistry: FleetQueryOnlyRegistry;
+    readonly workspaceCheckpointManager: CheckpointsGatewayManager;
+    readonly sessionBroker: SessionSearchBroker;
+}
+export declare function registerW3S2GatewayMethods(catalog: GatewayMethodCatalog, deps: W3S2GatewayDeps): void;
+//# sourceMappingURL=register-w3-s2.d.ts.map

package/dist/platform/control-plane/routes/register-w3-s2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-w3-s2.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/register-w3-s2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAoC,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAsC,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEnG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,0BAA0B,EAAE,yBAAyB,CAAC;IAC/D,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;CAC7C;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,EAAE,eAAe,GAAG,IAAI,CAIrG"}

package/dist/platform/control-plane/routes/register-w3-s2.js

@@ -0,0 +1,8 @@
+import { registerFleetGatewayMethods } from './fleet.js';
+import { registerCheckpointGatewayMethods } from './checkpoints.js';
+import { registerSessionSearchGatewayMethod } from './session-search.js';
+export function registerW3S2GatewayMethods(catalog, deps) {
+    registerFleetGatewayMethods(catalog, deps.processRegistry);
+    registerCheckpointGatewayMethods(catalog, deps.workspaceCheckpointManager);
+    registerSessionSearchGatewayMethod(catalog, deps.sessionBroker);
+}

package/dist/platform/control-plane/routes/session-search.d.ts

@@ -0,0 +1,37 @@
+/**
+ * routes/session-search.ts
+ *
+ * `sessions.search` (see CHANGELOG 1.0.0): a paginated/filtered query over the
+ * ALREADY-daemon-resident `SharedSessionBroker`'s home-scoped store,
+ * extending the session-spine list-filter shape (`ListSharedSessionsOptions`:
+ * project/kind/includeClosed) with a free-text `query`, `surfaceKind`,
+ * `status`, and opaque cursor pagination (mirrors the
+ * daemon-sdk `paginateItems` convention already used by
+ * automation-jobs/runs and knowledge listings).
+ *
+ * DELIBERATELY a standalone read-only helper, NOT a `SharedSessionBroker`
+ * method: the brief's file_ownership marks session-broker.ts read-only for
+ * S2 ("add a search method only if unavoidable — prefer a read-only query
+ * helper; coordinate with S3 which also reads the broker"). Everything here
+ * is built from the broker's existing public `listSessions()` — no new
+ * broker state, no new broker method.
+ *
+ * Bounded in-memory filter+sort: the store is
+ * single-user scale, so a full unbounded scan per call is intentional (no
+ * index) — this ceiling is a deliberate, documented decision.
+ */
+import type { GatewayMethodCatalog } from '../method-catalog.js';
+import type { GatewayMethodHandler } from '../method-catalog-shared.js';
+import type { SharedSessionBroker } from '../session-broker.js';
+/** Structural dep — only the read surface `sessions.search` needs. */
+export type SessionSearchBroker = Pick<SharedSessionBroker, 'listSessions'>;
+export declare function createSessionsSearchHandler(broker: SessionSearchBroker): GatewayMethodHandler;
+/**
+ * Attach the `sessions.search` handler to the descriptor already registered
+ * (without a handler) from ../method-catalog-control-core.ts's static
+ * builtin array. Call once, at RuntimeServices construction time. A missing
+ * descriptor is a silent no-op — see routes/fleet.ts's
+ * `registerFleetGatewayMethods` for the same rationale.
+ */
+export declare function registerSessionSearchGatewayMethod(catalog: GatewayMethodCatalog, broker: SessionSearchBroker): void;
+//# sourceMappingURL=session-search.d.ts.map

package/dist/platform/control-plane/routes/session-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-search.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/session-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAkEhE,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAE5E,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CAuD7F;AAED;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAKnH"}

package/dist/platform/control-plane/routes/session-search.js

@@ -0,0 +1,113 @@
+import { SURFACE_KINDS } from '../../../events/surfaces.js';
+import { paginateItems } from '@pellux/goodvibes-daemon-sdk';
+import { GatewayVerbError } from './gateway-verb-error.js';
+import { readInvocationParams } from './invocation-params.js';
+const SHARED_SESSION_KINDS = [
+    'tui',
+    'agent',
+    'webui',
+    'companion-task',
+    'companion-chat',
+    'automation',
+];
+const SHARED_SESSION_STATUSES = ['active', 'closed'];
+const SESSIONS_SEARCH_DEFAULT_LIMIT = 50;
+const SESSIONS_SEARCH_MAX_LIMIT = 200;
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function validateKind(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !SHARED_SESSION_KINDS.includes(value)) {
+        throw new GatewayVerbError(`Invalid kind: ${String(value)} (expected one of ${SHARED_SESSION_KINDS.join(', ')})`, 'INVALID_ARGUMENT', 400);
+    }
+    return value;
+}
+function validateStatus(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !SHARED_SESSION_STATUSES.includes(value)) {
+        throw new GatewayVerbError(`Invalid status: ${String(value)} (expected one of ${SHARED_SESSION_STATUSES.join(', ')})`, 'INVALID_ARGUMENT', 400);
+    }
+    return value;
+}
+function validateSurfaceKind(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !SURFACE_KINDS.includes(value)) {
+        throw new GatewayVerbError(`Invalid surfaceKind: ${String(value)}`, 'INVALID_ARGUMENT', 400);
+    }
+    return value;
+}
+function clampLimit(raw) {
+    if (raw === undefined || raw === null)
+        return SESSIONS_SEARCH_DEFAULT_LIMIT;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new GatewayVerbError(`Invalid limit: ${String(raw)}`, 'INVALID_ARGUMENT', 400);
+    }
+    return Math.min(Math.floor(n), SESSIONS_SEARCH_MAX_LIMIT);
+}
+export function createSessionsSearchHandler(broker) {
+    return (invocation) => {
+        const params = readInvocationParams(invocation);
+        const textQuery = optionalString(params.query)?.toLowerCase();
+        const project = optionalString(params.project);
+        const kind = validateKind(params.kind);
+        const surfaceKind = validateSurfaceKind(params.surfaceKind);
+        const status = validateStatus(params.status);
+        const includeClosed = params.includeClosed === true || params.includeClosed === 'true';
+        const limit = clampLimit(params.limit);
+        const rawCursor = typeof params.cursor === 'string' ? params.cursor : null;
+        // Always fetch WITH closed sessions from the broker (its own default),
+        // then apply the wire-level closed policy ourselves below: sessions.search
+        // deliberately defaults to EXCLUDING closed sessions unless
+        // includeClosed:true is explicit — the opposite of
+        // SharedSessionBroker.listSessions' own default — because a "search"
+        // surface should not surface dead sessions by default.
+        const all = broker.listSessions(Number.MAX_SAFE_INTEGER, {
+            project,
+            kind,
+            includeClosed: true,
+        });
+        const filtered = all.filter((session) => {
+            if (!includeClosed && session.status === 'closed')
+                return false;
+            if (status !== undefined && session.status !== status)
+                return false;
+            if (surfaceKind !== undefined && !session.surfaceKinds.includes(surfaceKind))
+                return false;
+            if (textQuery !== undefined) {
+                const haystack = `${session.id} ${session.title}`.toLowerCase();
+                if (!haystack.includes(textQuery))
+                    return false;
+            }
+            return true;
+        });
+        // Mirrors sortSessions (session-broker-state.ts): updatedAt desc, id asc tiebreak.
+        const sorted = [...filtered].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+        const page = paginateItems(sorted, limit, rawCursor, (session) => session.id, (session) => session.updatedAt, { descending: true });
+        if ('error' in page) {
+            throw new GatewayVerbError(page.error, 'INVALID_CURSOR', 400);
+        }
+        return {
+            sessions: page.items,
+            nextCursor: page.nextCursor,
+            hasMore: page.hasMore,
+        };
+    };
+}
+/**
+ * Attach the `sessions.search` handler to the descriptor already registered
+ * (without a handler) from ../method-catalog-control-core.ts's static
+ * builtin array. Call once, at RuntimeServices construction time. A missing
+ * descriptor is a silent no-op — see routes/fleet.ts's
+ * `registerFleetGatewayMethods` for the same rationale.
+ */
+export function registerSessionSearchGatewayMethod(catalog, broker) {
+    const descriptor = catalog.get('sessions.search');
+    if (descriptor) {
+        catalog.register(descriptor, createSessionsSearchHandler(broker), { replace: true });
+    }
+}

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

@@ -8,6 +8,22 @@ export interface SharedSessionGcStore {
 export interface SharedSessionGcOptions {
     readonly idleEmptyMs: number;
     readonly idleLongMs: number;
+    /**
+     * Age (ms since closedAt) at which a CLOSED session's record + bodies are
+     * PERMANENTLY deleted from the store. Closed sessions are HISTORY: by default
+     * this is `Number.POSITIVE_INFINITY` (retain indefinitely — a closed session
+     * is never swept off disk), and deletion happens only when a caller opts into
+     * a finite retention window or invokes an explicit delete verb.
+     *
+     * NOTE ON MEMORY vs PERSISTENCE (divergence from the companion manager):
+     * the broker's durable store is a FULL SNAPSHOT of these in-memory maps
+     * (createSessionBrokerSnapshot), so there is no separate "memory handle" to
+     * evict independently of disk — dropping a closed session's bodies from these
+     * maps would also drop them from the next persisted snapshot. Retention is
+     * therefore all-or-nothing here: retained closed sessions stay both listable
+     * and on disk; memory stays bounded by the per-session message cap
+     * (MAX_PERSISTED_MESSAGES_PER_SESSION) rather than by body eviction.
+     */
     readonly deletionRetentionMs: number;
     readonly publishUpdate: (event: string, payload: unknown) => void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"session-broker-gc.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-gc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEpF,MAAM,WAAW,oBAAoB;IACnC,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;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACnE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CA8BzG"}
+{"version":3,"file":"session-broker-gc.d.ts","sourceRoot":"","sources":["../../../src/platform/control-plane/session-broker-gc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,MAAM,WAAW,oBAAoB;IACnC,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;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACnE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAmCzG"}

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

@@ -1,10 +1,14 @@
+import { withSessionCloseReason } from './session-broker-sessions.js';
 export function sweepSharedSessions(store, options) {
     const now = Date.now();
     let anyChanged = false;
     for (const [sessionId, session] of store.sessions.entries()) {
         if (session.status === 'closed') {
+            // History by default. Only an explicit FINITE retention window authorizes
+            // permanent deletion; the default POSITIVE_INFINITY never trips this and
+            // the closed record stays listable (includeClosed) and on disk forever.
             const closedAt = session.closedAt ?? session.updatedAt;
-            if (now - closedAt >= options.deletionRetentionMs) {
+            if (Number.isFinite(options.deletionRetentionMs) && now - closedAt >= options.deletionRetentionMs) {
                 store.sessions.delete(sessionId);
                 store.messages.delete(sessionId);
                 store.inputs.delete(sessionId);
@@ -12,8 +16,6 @@ export function sweepSharedSessions(store, options) {
             }
             continue;
         }
-        if (!shouldCloseIdleSession(session, now, options))
-            continue;
         const reason = idleCloseReason(session, now, options);
         if (!reason)
             continue;
@@ -23,6 +25,9 @@ export function sweepSharedSessions(store, options) {
             activeAgentId: undefined,
             updatedAt: now,
             closedAt: now,
+            // Record that the SYSTEM reaper closed this (not a user/surface action) so a
+            // subsequent register heartbeat auto-reopens it (honest reopen semantics).
+            metadata: withSessionCloseReason(session.metadata, 'idle-reaped'),
         };
         store.sessions.set(sessionId, closed);
         options.publishUpdate('session-closed', { ...closed, reason });
@@ -30,8 +35,15 @@ export function sweepSharedSessions(store, options) {
     }
     return anyChanged;
 }
-function shouldCloseIdleSession(session, now, options) {
-    return idleCloseReason(session, now, options) !== null;
+/**
+ * True when any participant was seen within the idle-empty window — i.e. a
+ * surface is actively holding this session open. A live participant IS activity,
+ * so an empty session with a fresh heartbeat must NOT be idle-empty reaped even
+ * if `lastActivityAt` has drifted (defense-in-depth alongside the register path
+ * advancing lastActivityAt).
+ */
+function hasFreshParticipant(session, now, idleEmptyMs) {
+    return session.participants.some((participant) => now - participant.lastSeenAt < idleEmptyMs);
 }
 function idleCloseReason(session, now, options) {
     if (session.status !== 'active')
@@ -41,8 +53,13 @@ function idleCloseReason(session, now, options) {
     if (session.pendingInputCount > 0)
         return null;
     const idle = now - session.lastActivityAt;
-    if (session.messageCount === 0 && idle >= options.idleEmptyMs)
+    if (session.messageCount === 0 && idle >= options.idleEmptyMs) {
+        // A surface holding the session open (fresh participant heartbeat) exempts it
+        // from idle-empty reaping — closing it would kill a LIVE, message-less session.
+        if (hasFreshParticipant(session, now, options.idleEmptyMs))
+            return null;
         return 'idle-empty';
+    }
     if (session.messageCount > 0 && idle >= options.idleLongMs)
         return 'idle-long';
     return null;

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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"}