@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/control-plane/routes/fleet.d.ts

@@ -0,0 +1,53 @@
+/**
+ * routes/fleet.ts
+ *
+ * W3-S2 — `fleet.snapshot` / `fleet.list` gateway-method handlers over the
+ * ALREADY daemon-resident `ProcessRegistry` (createProcessRegistry(),
+ * ../../runtime/fleet/registry.ts:204, constructed + exposed on
+ * RuntimeServices at ../../runtime/services.ts:712/:242). This is thin verb
+ * registration, not new machinery: every call is a direct pass-through to
+ * `registry.query()`, the registry's own cheap aggregate-on-read scan.
+ *
+ * Wired via `GatewayMethodCatalog.register(descriptor, handler)` — the SAME
+ * mechanism the plugin API already uses (../../plugins/api.ts
+ * `registerGatewayMethod`) — rather than a new REST path in the external
+ * `@pellux/goodvibes-daemon-sdk` package or a change to
+ * ../../daemon/http/router.ts (both out of this brief's file ownership).
+ * The registered handler is reached over real HTTP today via the existing
+ * generic invoke endpoint `POST /api/control-plane/methods/{methodId}/invoke`
+ * (daemon-sdk/src/control-routes.ts `invokeGatewayMethod`).
+ *
+ * Descriptors live in ../method-catalog-control-core.ts (so
+ * `buildOperatorContract` / api.md / contract-artifact generation see them
+ * whether or not a handler has been attached yet); `registerFleetGatewayMethods`
+ * below attaches the handler at RuntimeServices construction time
+ * (../../runtime/services.ts, right after `processRegistry` exists).
+ */
+import type { GatewayMethodCatalog } from '../method-catalog.js';
+import type { GatewayMethodHandler } from '../method-catalog-shared.js';
+import type { ProcessRegistry } from '../../runtime/fleet/types.js';
+/**
+ * `fleet.snapshot` payload cap (risk #1, W3-S2 brief): the registry's
+ * `query()` is a cheap O(n) in-memory scan, but the wire response must not
+ * grow unbounded with fleet size. Nodes beyond this cap are dropped (newest
+ * activity first is NOT guaranteed here — see `truncated`/`totalCount` so a
+ * caller that needs the full set knows to page via `fleet.list` instead).
+ */
+export declare const FLEET_SNAPSHOT_NODE_CAP = 2000;
+export declare const FLEET_LIST_DEFAULT_LIMIT = 100;
+export declare const FLEET_LIST_MAX_LIMIT = 500;
+/** Structural dep — only the read surface `fleet.*` needs. */
+export type FleetQueryOnlyRegistry = Pick<ProcessRegistry, 'query'>;
+export declare function createFleetSnapshotHandler(registry: FleetQueryOnlyRegistry): GatewayMethodHandler;
+export declare function createFleetListHandler(registry: FleetQueryOnlyRegistry): GatewayMethodHandler;
+/**
+ * Attach the `fleet.snapshot` / `fleet.list` handlers to the descriptors
+ * already registered (without a handler) from
+ * ../method-catalog-control-core.ts's static builtin array. Call once, at
+ * RuntimeServices construction time, after `processRegistry` exists.
+ * A missing descriptor (contract/registration drift) is a silent no-op
+ * rather than a throw — construction must never fail because a wire verb
+ * failed to register; the operator-contract gates catch a real drift.
+ */
+export declare function registerFleetGatewayMethods(catalog: GatewayMethodCatalog, registry: FleetQueryOnlyRegistry): void;
+//# sourceMappingURL=fleet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/fleet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAIV,eAAe,EAEhB,MAAM,8BAA8B,CAAC;AAKtC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAyExC,8DAA8D;AAC9D,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAEpE,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB,CAejG;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,oBAAoB,CAuC7F;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,sBAAsB,GAAG,IAAI,CASjH"}

package/dist/platform/control-plane/routes/fleet.js

@@ -0,0 +1,153 @@
+import { paginateItems } from '@pellux/goodvibes-daemon-sdk';
+import { GatewayVerbError } from './gateway-verb-error.js';
+import { readInvocationParams } from './invocation-params.js';
+/**
+ * `fleet.snapshot` payload cap (risk #1, W3-S2 brief): the registry's
+ * `query()` is a cheap O(n) in-memory scan, but the wire response must not
+ * grow unbounded with fleet size. Nodes beyond this cap are dropped (newest
+ * activity first is NOT guaranteed here — see `truncated`/`totalCount` so a
+ * caller that needs the full set knows to page via `fleet.list` instead).
+ */
+export const FLEET_SNAPSHOT_NODE_CAP = 2000;
+export const FLEET_LIST_DEFAULT_LIMIT = 100;
+export const FLEET_LIST_MAX_LIMIT = 500;
+const PROCESS_KINDS = [
+    'agent',
+    'wrfc-chain',
+    'wrfc-subtask',
+    'workflow',
+    'trigger',
+    'schedule',
+    'watcher',
+    'background-process',
+    'workstream',
+    'phase',
+    'work-item',
+    'code-index',
+];
+const PROCESS_STATES = [
+    'thinking',
+    'executing-tool',
+    'awaiting-approval',
+    'streaming',
+    'stalled',
+    'retrying',
+    'done',
+    'failed',
+    'killed',
+    'interrupted',
+    'idle',
+    'queued',
+    'paused',
+];
+function asStringArray(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (typeof value === 'string')
+        return value.split(',').map((v) => v.trim()).filter(Boolean);
+    return undefined;
+}
+function readFleetQueryFilter(query) {
+    if (!query)
+        return undefined;
+    const rawKinds = asStringArray(query.kinds);
+    const rawStates = asStringArray(query.states);
+    let kinds;
+    if (rawKinds) {
+        const invalid = rawKinds.filter((k) => !PROCESS_KINDS.includes(k));
+        if (invalid.length > 0) {
+            throw new GatewayVerbError(`Unknown fleet kind(s): ${invalid.join(', ')}`, 'INVALID_ARGUMENT', 400);
+        }
+        kinds = rawKinds;
+    }
+    let states;
+    if (rawStates) {
+        const invalid = rawStates.filter((s) => !PROCESS_STATES.includes(s));
+        if (invalid.length > 0) {
+            throw new GatewayVerbError(`Unknown fleet state(s): ${invalid.join(', ')}`, 'INVALID_ARGUMENT', 400);
+        }
+        states = rawStates;
+    }
+    if (!kinds && !states)
+        return undefined;
+    return { ...(kinds ? { kinds } : {}), ...(states ? { states } : {}) };
+}
+function clampLimit(raw, fallback, max) {
+    if (raw === undefined || raw === null)
+        return fallback;
+    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), max);
+}
+export function createFleetSnapshotHandler(registry) {
+    return (invocation) => {
+        const filter = readFleetQueryFilter(readInvocationParams(invocation));
+        const snapshot = registry.query(filter);
+        const truncated = snapshot.nodes.length > FLEET_SNAPSHOT_NODE_CAP;
+        const nodes = truncated
+            ? snapshot.nodes.slice(0, FLEET_SNAPSHOT_NODE_CAP)
+            : snapshot.nodes;
+        return {
+            capturedAt: snapshot.capturedAt,
+            nodes,
+            truncated,
+            totalCount: snapshot.nodes.length,
+        };
+    };
+}
+export function createFleetListHandler(registry) {
+    return (invocation) => {
+        const params = readInvocationParams(invocation);
+        const filter = readFleetQueryFilter(params);
+        const limit = clampLimit(params.limit, FLEET_LIST_DEFAULT_LIMIT, FLEET_LIST_MAX_LIMIT);
+        const rawCursor = typeof params.cursor === 'string' ? params.cursor : null;
+        const snapshot = registry.query(filter);
+        // Sort key and recovery key MUST agree (mirrors sessions.search's
+        // sortSessions-then-paginateItems pattern in session-search.ts): the array
+        // is sorted newest-first by startedAt (id tiebreak for determinism when
+        // two nodes share a timestamp, or neither has started), and paginateItems
+        // is handed that SAME startedAt extractor with { descending: true }. A
+        // node's `startedAt` is optional (not-yet-started processes), so absent
+        // values are normalized to 0 for both the sort and the recovery key —
+        // otherwise `paginateItems`' deleted-cursor recovery (which does a
+        // findIndex assuming the array is actually ordered by the field it is
+        // given) would search a startedAt-ordered predicate over an array that
+        // was really sorted by id, silently skipping or repeating nodes once a
+        // process is gc'd between pages.
+        const startedAtOf = (node) => node.startedAt ?? 0;
+        const sorted = [...snapshot.nodes].sort((a, b) => startedAtOf(b) - startedAtOf(a) || a.id.localeCompare(b.id));
+        const page = paginateItems(sorted, limit, rawCursor, (node) => node.id, startedAtOf, { descending: true });
+        if ('error' in page) {
+            throw new GatewayVerbError(page.error, 'INVALID_CURSOR', 400);
+        }
+        return {
+            items: page.items,
+            nextCursor: page.nextCursor,
+            hasMore: page.hasMore,
+            capturedAt: snapshot.capturedAt,
+        };
+    };
+}
+/**
+ * Attach the `fleet.snapshot` / `fleet.list` handlers to the descriptors
+ * already registered (without a handler) from
+ * ../method-catalog-control-core.ts's static builtin array. Call once, at
+ * RuntimeServices construction time, after `processRegistry` exists.
+ * A missing descriptor (contract/registration drift) is a silent no-op
+ * rather than a throw — construction must never fail because a wire verb
+ * failed to register; the operator-contract gates catch a real drift.
+ */
+export function registerFleetGatewayMethods(catalog, registry) {
+    const snapshotDescriptor = catalog.get('fleet.snapshot');
+    if (snapshotDescriptor) {
+        catalog.register(snapshotDescriptor, createFleetSnapshotHandler(registry), { replace: true });
+    }
+    const listDescriptor = catalog.get('fleet.list');
+    if (listDescriptor) {
+        catalog.register(listDescriptor, createFleetListHandler(registry), { replace: true });
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * gateway-verb-error.ts
+ *
+ * W3-S2 (fleet.*, checkpoints.*, sessions.search): a structured error for
+ * gateway methods registered with a direct handler via
+ * `GatewayMethodCatalog.register(descriptor, handler)`.
+ *
+ * WHY THIS EXISTS: `invokeGatewayMethodCall` (../../daemon/control-plane.ts)
+ * dispatches a handler-bearing method via `catalog.invoke()` and, on ANY
+ * thrown error, collapses it to a blanket `{ status: 500 }` — there was no
+ * prior handler-registered verb that needed an honest non-500 status (the
+ * only prior consumer of `register(descriptor, handler)` is the plugin API,
+ * whose tool-call errors are swallowed into a `{success:false}` payload, not
+ * an HTTP status). checkpoints.diff/restore need an honest 404 for an
+ * unknown/gc'd checkpoint id (see routes/checkpoints.ts), and invalid
+ * pagination cursors need an honest 400 (fleet.list, sessions.search) — a
+ * blanket 500 would misreport caller error as server error.
+ *
+ * This mirrors the existing `SDKErrorCodes.SESSION_CLOSED` convention used by
+ * the plain-REST session routes (`callOrSessionClosed`,
+ * ../../../daemon-sdk/src/runtime-session-routes.ts), generalized to any
+ * status/code pair instead of one hardcoded to 409/SESSION_CLOSED.
+ */
+export declare class GatewayVerbError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+export declare function isGatewayVerbError(error: unknown): error is GatewayVerbError;
+//# sourceMappingURL=gateway-verb-error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-verb-error.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/gateway-verb-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E"}

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

@@ -0,0 +1,36 @@
+/**
+ * gateway-verb-error.ts
+ *
+ * W3-S2 (fleet.*, checkpoints.*, sessions.search): a structured error for
+ * gateway methods registered with a direct handler via
+ * `GatewayMethodCatalog.register(descriptor, handler)`.
+ *
+ * WHY THIS EXISTS: `invokeGatewayMethodCall` (../../daemon/control-plane.ts)
+ * dispatches a handler-bearing method via `catalog.invoke()` and, on ANY
+ * thrown error, collapses it to a blanket `{ status: 500 }` — there was no
+ * prior handler-registered verb that needed an honest non-500 status (the
+ * only prior consumer of `register(descriptor, handler)` is the plugin API,
+ * whose tool-call errors are swallowed into a `{success:false}` payload, not
+ * an HTTP status). checkpoints.diff/restore need an honest 404 for an
+ * unknown/gc'd checkpoint id (see routes/checkpoints.ts), and invalid
+ * pagination cursors need an honest 400 (fleet.list, sessions.search) — a
+ * blanket 500 would misreport caller error as server error.
+ *
+ * This mirrors the existing `SDKErrorCodes.SESSION_CLOSED` convention used by
+ * the plain-REST session routes (`callOrSessionClosed`,
+ * ../../../daemon-sdk/src/runtime-session-routes.ts), generalized to any
+ * status/code pair instead of one hardcoded to 409/SESSION_CLOSED.
+ */
+export class GatewayVerbError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'GatewayVerbError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isGatewayVerbError(error) {
+    return error instanceof GatewayVerbError;
+}

package/dist/platform/control-plane/routes/index.d.ts

@@ -1,8 +1,2 @@
-export { dispatchAutomationRoutes } from './automation.js';
-export { dispatchSessionRoutes } from './sessions.js';
-export { dispatchTaskRoutes } from './tasks.js';
-export { dispatchOperatorRoutes } from './operator.js';
-export { dispatchRemoteRoutes } from './remote.js';
 export { dispatchDaemonApiRoutes } from './api-router.js';
-export type { DaemonApiRouteHandlers } from './context.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/platform/control-plane/routes/index.js

@@ -1,6 +1,6 @@
-export { dispatchAutomationRoutes } from './automation.js';
-export { dispatchSessionRoutes } from './sessions.js';
-export { dispatchTaskRoutes } from './tasks.js';
-export { dispatchOperatorRoutes } from './operator.js';
-export { dispatchRemoteRoutes } from './remote.js';
+// The live daemon route dispatch is daemon-sdk's; this barrel re-exports it.
+// The former sdk-local dispatcher copies (automation/tasks/operator/remote/
+// sessions + their context types) were a superseded, unreachable parallel —
+// deleted in the Wave-1 spine integration cleanup (0 callers, 0 api.md
+// presence; every test imports the daemon-sdk originals). Pay-its-way rule.
 export { dispatchDaemonApiRoutes } from './api-router.js';

package/dist/platform/control-plane/routes/invocation-params.d.ts

@@ -0,0 +1,23 @@
+/**
+ * routes/invocation-params.ts
+ *
+ * W3-S2 (post-S1 alignment) — one params view for the handler-registered
+ * verbs (fleet.*, checkpoints.*, sessions.search).
+ *
+ * S1's invoke-layer input gate (invoke-input-validation.ts, wired in
+ * daemon/control-plane.ts invokeGatewayMethodCall) validates the invoke BODY
+ * against a handler verb's typed inputSchema — a method with no http binding
+ * is body-carrying by that gate's definition. So the BODY is the canonical,
+ * schema-validated params channel for these verbs, and callers should put
+ * params there.
+ *
+ * The generic invoke envelope ({ query?, body }) still carries a `query`
+ * record, so this helper folds it in as a FALLBACK (body keys win). Query-
+ * supplied values bypass S1's schema gate, but every one of these handlers
+ * performs its own full validation with honest 400s (GatewayVerbError), so
+ * nothing unchecked reaches a manager either way.
+ */
+import type { GatewayMethodInvocation } from '../method-catalog-shared.js';
+/** Merged params for a handler-registered verb: query as fallback, body wins. */
+export declare function readInvocationParams(invocation: GatewayMethodInvocation): Record<string, unknown>;
+//# sourceMappingURL=invocation-params.d.ts.map

package/dist/platform/control-plane/routes/invocation-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-params.d.ts","sourceRoot":"","sources":["../../../../src/platform/control-plane/routes/invocation-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAQ3E,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjG"}

package/dist/platform/control-plane/routes/invocation-params.js

@@ -0,0 +1,9 @@
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Merged params for a handler-registered verb: query as fallback, body wins. */
+export function readInvocationParams(invocation) {
+    return { ...asRecord(invocation.query), ...asRecord(invocation.body) };
+}

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 W3-S2's three verb-registration calls
+ * (fleet.*, checkpoints.*, sessions.search), 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
+ *
+ * W3-S2 — `sessions.search`: a paginated/filtered query over the
+ * ALREADY-daemon-resident `SharedSessionBroker`'s home-scoped store,
+ * extending the Wave-1 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 (risk #3, W3-S2 brief): the store is
+ * single-user scale, so a full unbounded scan per call is intentional (no
+ * index) — see the brief's decision record for the documented ceiling.
+ */
+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;