@prismshadow/penguin-server 0.2.13 → 0.2.16

package/dist/plugin/index.d.ts

@@ -1,29 +1,50 @@
-import { SpawnConfiner, ThinkingLevelName, OmniMessage, ToolCallPayload, ProjectConfig, ModelRef, ListEndpointModelsOptions, ProxyEnvPolicy, ControlEnvContext, ApproveFn, CompactAvailability, SessionTitleResult, BackgroundCommandInfo, ToolDetachResult, BackgroundSubagentInfo, SubagentMessageOptions, SubagentMessageOutcome } from '@prismshadow/penguin-core';
-import { SandboxProviderSource, SandboxSettings, SandboxDimension } from '@prismshadow/penguin-core/plugin';
+import { SpawnConfiner, OmniMessage, ThinkingLevelName, ToolCallPayload, ApprovalDecision, ProjectConfig, ModelRef, PluginTables, ListEndpointModelsOptions, ModelRequestContext, ProxyEnvPolicy, ControlEnvContext, AgentAssembly, ApproveFn, StopReason, CompactAvailability, SessionTitleResult, BackgroundCommandInfo, ToolDetachResult, BackgroundSubagentInfo, SubagentMessageOptions, SubagentMessageOutcome } from '@prismshadow/penguin-core';
+import { SandboxProviderSource, SandboxSettings, SandboxDimension, SandboxLimit } from '@prismshadow/penguin-core/plugin';
 import { Slot, Opaque } from '@prismshadow/penguin-core/kernel';
-import { ApprovalMode, SessionSource, ModelRefDto, ChatDefaultsDto, CommandPolicyDto, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelTestRequest, ModelTestResponse, ModelProtocolDetectRequest, ModelProtocolDetectResponse, EndpointModelListRequest, EndpointModelListResponse, ModelsResponse, ModelsUpdateRequest, MessagingChannel as MessagingChannel$1, SessionInfo, SessionCategory, SessionCategoryCounts, ServerEvent, SessionStatus, SessionBackgroundTasks, PendingSteeringInfo, PendingFollowUpInfo, AgentConfigDto, AgentConfigUpdateRequest, AgentKernelUpdateResponse, VaultResponse, VaultUpdateRequest, PluginUpdateRef, MessagingRuntimeStatus, ContributionsResponse, RendererRef } from '../api/types.js';
+import { ApprovalMode, ModelRefDto, ChatDefaultsDto, CommandPolicyDto, ModelVisionDetectRequest, ModelVisionDetectResponse, ModelTestRequest, ModelTestResponse, ModelProtocolDetectRequest, ModelProtocolDetectResponse, EndpointModelListRequest, EndpointModelListResponse, ModelsResponse, ModelsUpdateRequest, ProviderConnectionUpdate, PresetSyncMode, PresetSyncResponse, ServerEvent, MessagingChannel, UnavailableSandboxBackend, SessionSandboxPreset, SessionSandbox, SessionInfo, SessionCategory, SessionCategoryCounts, ModelScopeAuthFlowStatusResponse, SessionStatus, PendingSteeringInfo, SessionBackgroundTasks, PendingFollowUpInfo, AgentConfigDto, AgentConfigUpdateRequest, AgentKernelUpdateResponse, VaultResponse, VaultUpdateRequest, PluginUpdateRef, MessagingRuntimeStatus, PluginConfiguration, ContributionsResponse, RendererRef } from '../api/types.js';
+export { PluginConfigField } from '../api/types.js';
 import { ThinkingLevelName as ThinkingLevelName$1 } from '@prismshadow/penguin-core/interfaces';
+import { SessionSource } from '@prismshadow/penguin-core/omnimessage';
 import { Hono } from 'hono';
-import '@prismshadow/penguin-core/omnimessage';
+import '@prismshadow/penguin-hmr';
+
+interface UserRow {
+    userId: string;
+    passwordHash: string;
+    isAdmin: boolean;
+    /** Still using the initial password (seeded / set by an admin); cleared to 0 once the user changes it. */
+    passwordIsInitial: boolean;
+    /** Nickname shown in place of the id; null = never set. */
+    displayName: string | null;
+    /** Avatar as a data URL; null = never set. */
+    avatar: string | null;
+    createdAt: string;
+}
 
 /**
- * The sandbox service: owns the registered backends, routes each spawn's policy to a
- * backend that implements the dimensions it requires, and produces the SpawnConfiner
- * closure the runtime transports into core's command-session seam.
- *
- * Routing is by CAPABILITY, not by registration order alone: a policy requiring only
- * `fs-write` goes to the first backend that covers it (the DSH adaptor, which works on
- * Linux/macOS/Windows alike), while a policy also requiring `network` or `mask-paths`
- * goes to the first backend implementing those (penguin-bwrap). Registration order
- * only breaks ties between backends that both cover the request. A request nothing
- * covers fails closed — never a silent unconfined run, and never a silently dropped
- * dimension.
+ * "desktop" and "setup" may set a password without the old one (theirs is random and was never
+ * shown); desktop-only routes open to "desktop" alone. "token" is the local API token's
+ * authority, whether presented as a Bearer header or exchanged for a Remote cookie.
+ * Exchanging the credential must not grant the person's privileges. Anything else reads as
+ * "password".
  */
+type SessionVia = "password" | "desktop" | "setup" | "token";
 
 declare class SandboxService {
-    private readonly mounted;
-    /** name → why it failed to load; surfaced in the fail-closed message. */
-    private readonly loadErrors;
+    private mounted;
+    /**
+     * name → why it FAILED: it could not load, or failed its check on a host it is meant for —
+     * never silently absent. Surfaced in the fail-closed message and on the settings card.
+     */
+    private loadErrors;
+    /**
+     * The backends that declined: this host is not theirs (a Linux backend on Windows). Nothing
+     * is wrong with a deployment that installs one backend per platform, so a decline is not a
+     * failure — it is listed only when NO backend serves, where it is the explanation.
+     */
+    private declinedNames;
+    /** Every registration in routing order, with how its latest load settled. */
+    private readonly registrations;
     /**
      * Ships with confinement OFF (`danger-full-access`): the default flips to
      * workspace-write together with the deployment-facing config surface, so a
@@ -40,6 +61,14 @@ declare class SandboxService {
      *   exists for deployments flipping the mode in the first milliseconds after boot.
      */
     constructor(registrations?: Iterable<[string, SandboxProviderSource]>);
+    /** Rebuilds the mounted / failed / declined views from the registrations, in routing order. */
+    private record;
+    /**
+     * Loads again every backend whose load failed and that registered a loader (a bare promise
+     * cannot be re-run). Called after the sandbox's settings are saved: a backend whose check
+     * failed on its own setting mounts once that setting is fixed. Resolves when those settle.
+     */
+    retryFailed(): Promise<void>;
     /** Resolves when every registered backend has loaded (or failed to). */
     whenReady(): Promise<void>;
     /** Replaces the active settings (the config surface's write path). */
@@ -55,10 +84,22 @@ declare class SandboxService {
      * refusing the swap beats a swap that silently un-confines the deployment.
      */
     parkedSettings(): SandboxSettings | undefined;
-    /** The mounted backends and what each implements (diagnostics / the config surface). */
+    /** The backends that failed to load, each with why (diagnostics / the config surface). */
+    failures(): Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** The backends that declined because this host is not theirs (the config surface). */
+    declined(): string[];
+    /**
+     * The mounted backends and what each implements, in routing preference: the one a policy
+     * goes to first (diagnostics / the config surface).
+     */
     backends(): Array<{
         name: string;
         dimensions: readonly SandboxDimension[];
+        mechanism?: string;
+        limits?: readonly SandboxLimit[];
     }>;
     /**
      * The closure handed to the runtime: rewrites each spawn's argv under the active
@@ -66,11 +107,19 @@ declare class SandboxService {
      * serving during a hot-swap freeze window.
      */
     confiner(): SpawnConfiner;
-    /** The first mounted backend implementing every required dimension, or a fail-closed throw. */
+    /**
+     * The same closure under a policy the caller keeps — a Session's own snapshot. The
+     * backends are still this service's, so a backend change reaches every Session.
+     */
+    confinerFor(policyOf: () => SandboxSettings): SpawnConfiner;
+    /**
+     * The preferred mounted backend implementing every required dimension (byPreference), or a
+     * fail-closed throw.
+     */
     private pick;
     private failedSuffix;
 }
-declare const Sandbox_base: (abstract new () => Pick<SandboxService, "configure" | "currentSettings" | "parkedSettings" | "backends" | "confiner" | "whenReady">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare const Sandbox_base: (abstract new () => Pick<SandboxService, "failures" | "configure" | "currentSettings" | "parkedSettings" | "backends" | "declined" | "retryFailed" | "confiner" | "confinerFor" | "whenReady">) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** Confinement: settings, the active confiner, and which backends are mounted. */
 declare abstract class Sandbox extends Sandbox_base {
 }
@@ -85,6 +134,29 @@ interface SandboxSlots {
     }, SandboxProviderSource>;
 }
 
+/** What a terminal puts first on PATH, where the startup files that do it live, and its first line. */
+interface TerminalPathFirst {
+    /** The directories that must lead PATH once the shell is ready, in order: the CLI shim dir. */
+    dirs: readonly string[];
+    /** The directory holding the startup files, see {@link shellStartupDir}. */
+    startupDir: string;
+    /** A development instance's first line, for the shell to print at its first prompt. Absent or null: none. */
+    notice?: ShellNotice | null;
+}
+/**
+ * The first line of a development instance's terminal, printed by the shell itself at its first
+ * prompt, after its own startup files: `text` while `penguin` there still targets this instance,
+ * else `elsewhere`'s two halves around `VAR=value` — when those files set PENGUIN_API_URL, which
+ * names a server outright, or a PENGUIN_HOME that is not `root` (a trailing `/` aside), which the
+ * shim then leaves to the CLI.
+ */
+interface ShellNotice {
+    text: string;
+    /** This instance's data root. */
+    root: string;
+    elsewhere: readonly [before: string, after: string];
+}
+
 /**
  * Screen snapshot -> ANSI restore stream, plus plain-text capture.
  *
@@ -141,6 +213,42 @@ interface CreateTerminalSessionOptions {
      * absent falls back to the packaged require (see pty-module.ts).
      */
     assets?: () => string | null;
+    /**
+     * What leads PATH once the shell's own startup files have run: the server's CLI shim
+     * directory, so `penguin` here is the one the Agent's commands get (see shell-startup.ts).
+     * Absent or null, the shell starts with the inherited PATH as it is.
+     */
+    pathFirst?: TerminalPathFirst | null;
+    /**
+     * One line shown above everything the shell prints — on a development instance, which
+     * `penguin` this terminal runs, or why it is not this instance's (cli-notice.ts). Written to
+     * the screen, never to the shell: nothing runs, and the user's prompt follows it. A line with
+     * a `target` the shell prints itself instead, at its first prompt, where it can
+     * (shell-startup.ts ShellNotice): only then is it known what the user's own startup files left
+     * `penguin` pointing at.
+     */
+    notice?: TerminalNotice | null;
+    /**
+     * Whether the shell keeps the server process's `PENGUIN_HOME` and `PENGUIN_WEB_DB`. Only
+     * where no shim names this server's data root for `penguin` — a server with no CLI to offer,
+     * or a runtime older than the shim's root default — so that `penguin` there still finds this
+     * server the way it did before. Default false: every `PENGUIN_*` stays out.
+     */
+    inheritDataRoot?: boolean;
+}
+/** A line the server shows at the top of a new terminal; `warning` when something is wrong. */
+interface TerminalNotice {
+    text: string;
+    tone: "info" | "warning";
+    /**
+     * What `text` takes for granted: that `penguin` here targets this data root. On a development
+     * instance's line, which then says otherwise — `elsewhere`'s two halves around `VAR=value` —
+     * when the shell's own startup files set PENGUIN_API_URL, or a PENGUIN_HOME that is not `root`.
+     */
+    target?: {
+        root: string;
+        elsewhere: readonly [before: string, after: string];
+    };
 }
 interface TerminalSessionInfo {
     id: string;
@@ -223,20 +331,18 @@ interface CreateTerminalRequest {
 }
 /** A live pty: a host-like object (it owns a process), compared by name. */
 type Terminal = Opaque<"TerminalSession", TerminalSession>;
-declare const Terminals_base: (abstract new () => {
-    create(request: CreateTerminalRequest): Promise<Terminal>;
-    adopt(ids: readonly string[]): void;
-    quiesce(): void;
-    handleIds(): string[];
-    require(id: string, userId: string): Terminal;
-    get(id: string): Terminal | undefined;
-    list(userId: string): Terminal[];
-    listInfo(userId: string): TerminalSessionInfo[];
-    kill(id: string, userId: string): void;
-    disposeAll(): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** Live ptys: the spawn primitive behind /api/terminals and the terminal WebSocket. */
-declare abstract class Terminals extends Terminals_base {
+declare abstract class Terminals {
+    abstract create(request: CreateTerminalRequest): Promise<Terminal>;
+    abstract adopt(ids: readonly string[]): void;
+    abstract quiesce(): void;
+    abstract handleIds(): string[];
+    abstract require(id: string, userId: string): Terminal;
+    abstract get(id: string): Terminal | undefined;
+    abstract list(userId: string): Terminal[];
+    abstract listInfo(userId: string): TerminalSessionInfo[];
+    abstract kill(id: string, userId: string): void;
+    abstract disposeAll(): void;
 }
 
 /**
@@ -264,37 +370,67 @@ interface RecallableFile {
     mime: string;
 }
 
-declare const SessionIndex_base: (abstract new () => {
-    insert(row: SessionRow): void;
-    insertOrIgnore(row: SessionRow): void;
-    insertFork(sourceSessionId: string, row: SessionRow): SessionRow;
-    markOrgClient(sessionIds: readonly string[]): void;
-    markHasTrace(sessionId: string): void;
-    markDriven(sessionId: string, at: string): void;
-    touchLastActive(sessionId: string, at: string): void;
-    findById(sessionId: string): SessionRow | null;
-    listByAgent(projectId: string, agentId: string): SessionRow[];
-    listByProject(projectId: string): SessionRow[];
-    updateApprovalMode(sessionId: string, mode: ApprovalMode): void;
-    updateThinkingLevel(sessionId: string, level: ThinkingLevelName): void;
-    updateTitle(sessionId: string, title: string): void;
-    updateTitleIfNull(sessionId: string, title: string): void;
-    setArchived(sessionId: string, archivedAt: string | null): void;
-    replaceId(oldSessionId: string, newSessionId: string): void;
-    deleteByAgent(projectId: string, agentId: string): void;
-    deleteByProject(projectId: string): void;
-    deleteById(sessionId: string): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** The open streaming fragments of running sessions, as their holder uses them — what {@link LiveTailTracker} implements. */
+interface LiveTail {
+    observe(sessionId: string, msg: OmniMessage): void;
+    fragments(sessionId: string): OmniMessage[];
+    clear(sessionId: string): void;
+}
+
 /** SessionIndex: the mechanism SessionsRepo implements. */
-declare abstract class SessionIndex extends SessionIndex_base {
+declare abstract class SessionIndex {
+    abstract insert(row: SessionRow): void;
+    abstract insertOrIgnore(row: SessionRow): void;
+    abstract insertFork(sourceSessionId: string, row: SessionRow): SessionRow;
+    abstract markOrgClient(sessionIds: readonly string[]): void;
+    abstract markHasTrace(sessionId: string): void;
+    abstract markDriven(sessionId: string, at: string): void;
+    abstract touchLastActive(sessionId: string, at: string): void;
+    abstract findById(sessionId: string): SessionRow | null;
+    abstract listByAgent(projectId: string, agentId: string): SessionRow[];
+    abstract listByProject(projectId: string): SessionRow[];
+    abstract updateApprovalMode(sessionId: string, mode: ApprovalMode): void;
+    abstract updateSandbox(sessionId: string, sandbox: SandboxSettings): void;
+    abstract updateThinkingLevel(sessionId: string, level: ThinkingLevelName): void;
+    abstract updateTitle(sessionId: string, title: string): void;
+    abstract updateTitleIfNull(sessionId: string, title: string): void;
+    abstract updateModel(sessionId: string, provider: string, modelId: string): void;
+    abstract setListing(sessionIds: readonly string[], listing: "archived" | "kept", at: string): void;
+    abstract replaceId(oldSessionId: string, newSessionId: string): void;
+    abstract deleteByAgent(projectId: string, agentId: string): void;
+    abstract deleteByProject(projectId: string): void;
+    abstract deleteById(sessionId: string): void;
 }
-declare const SessionOrigins_base: (abstract new () => {
-    set(sessionId: string, source: SessionSource | null): void;
-    get(sessionId: string): SessionSource | null | undefined;
-    delete(sessionId: string): void;
+/**
+ * What a run that has just ended asks of the CURRENT generation: start the next queued
+ * follow-up, or deliver background notices that raced the run's exit. A run outlives the
+ * generation that launched it (see AgentState.current), and what it starts next is the
+ * current logic's to start.
+ */
+interface RunStarter {
+    startQueuedFollowUp(sessionId: string): Promise<void>;
+    startBackgroundNoticeTask(sessionId: string): Promise<void>;
+}
+declare const AgentState_base: (abstract new () => {
+    readonly entries: Map<string, RuntimeEntry>;
+    readonly childRoots: Map<string, string>;
+    readonly locks: Map<string, Promise<unknown>>;
+    readonly deletingAgents: Set<string>;
+    readonly deletingSessions: Set<string>;
+    readonly agentGenerations: Map<string, number>;
+    readonly liveTail: LiveTail;
+    /** The generation working on this state right now; every generation points it at itself when it takes the state over. */
+    current: RunStarter | null;
 }) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** AgentState: the mechanism AgentStateStore implements — the Session runtime's in-memory state, data only. */
+declare abstract class AgentState extends AgentState_base {
+}
 /** SessionOrigins: the mechanism SessionSources implements. */
-declare abstract class SessionOrigins extends SessionOrigins_base {
+declare abstract class SessionOrigins {
+    /** `null`: the Session's Trace head records no source (written before it was required). */
+    abstract set(sessionId: string, source: SessionSource | null): void;
+    abstract get(sessionId: string): SessionSource | null | undefined;
+    abstract delete(sessionId: string): void;
 }
 
 /**
@@ -306,9 +442,13 @@ interface SessionRow {
     sessionId: string;
     projectId: string;
     agentId: string;
-    /** Provider group of the session's model (pairs with `modelId` to form the model reference). */
+    /**
+     * Provider group of the session's **current** model (pairs with `modelId` to form the model
+     * reference). Moves with each in-session switch (`updateModel`); the Trace's latest
+     * `session_meta` is the durable truth, and the runtime reconciles a row it disagrees with.
+     */
     provider: string;
-    /** Upstream model_id of the session's model (sent as-is to AgentHub; never concatenated). */
+    /** Upstream model_id of the session's current model (sent as-is to MMSP; never concatenated). */
     modelId: string;
     workspace: string;
     approvalMode: ApprovalMode;
@@ -320,21 +460,33 @@ interface SessionRow {
     thinkingLevel?: ThinkingLevelName$1 | null;
     /** Auto-generated session title; NULL = not yet generated (frontend shows "New Conversation"). */
     title: string | null;
-    /** Archive timestamp, ISO; NULL = not archived (omitting on insert defaults to NULL). */
+    /**
+     * When the user archived it, ISO; NULL = not archived by hand (omitting on insert defaults to
+     * NULL). Archived or not is the listing rule's answer (runtime/session-sources.ts listCategory):
+     * a background Session without `keptAt` is filed away too.
+     */
     archivedAt?: string | null;
+    /**
+     * The "keep in sidebar" mark, ISO: written when the user unarchives the Session, cleared when
+     * they archive it, never written by a run. It is what keeps a background Session (api /
+     * schedule / cli) listed among the conversations; NULL = the listing rule decides.
+     */
+    keptAt?: string | null;
     /**
      * Creating client: "web" (created via the Web App), "cli" (created through the API by
      * the CLI, or adopted from a Trace a legacy CLI-direct run left behind), "org" (opened by
-     * the organization runtime — a desk or a ticket session); NULL = legacy row from before
-     * the column existed, treated as web. Free text in SQLite, so a new value needs no
-     * migration. Provenance that outlives its organization: development mode's list is the
-     * one reader that filters on it, and it hides "org" rows whether or not the organization
-     * still exists. The schedule/subagent SOURCE is deliberately NOT a row field — core
+     * the organization runtime — a desk or a ticket session — or spawned as a sub-session of
+     * one, which inherits the stamp at registration), "api" (created by an Agent API run — the
+     * only rows the API may continue), "workbench" (created by the Workbench host); NULL = legacy row from before the column existed,
+     * treated as web. Free text in SQLite, so a new value needs no migration.
+     * Provenance that outlives its organization: development mode's list is the one reader
+     * that filters on it (through the list's `excludeOrg`), and it hides "org" rows whether or
+     * not the organization still exists. The schedule/subagent SOURCE is deliberately NOT a row field — core
      * session_meta in the Trace stays the single source of truth for it
      * (runtime/session-sources.ts); `client` is a separate, DB-only axis that meta never
      * records.
      */
-    client?: "web" | "cli" | "org" | null;
+    client?: "web" | "cli" | "org" | "api" | "workbench" | null;
     /** Cache: a Trace record exists (set at task start / adoption / subagent registration; backfilled by list hydration). */
     hasTrace?: boolean;
     /**
@@ -347,6 +499,11 @@ interface SessionRow {
      */
     lastActiveAt: string;
     createdAt: string;
+    /**
+     * The Session's own sandbox policy, snapshotted from the server's settings at creation.
+     * NULL = a row from before the column: it takes the settings at its next command.
+     */
+    sandbox?: SandboxSettings | null;
 }
 
 /**
@@ -361,6 +518,9 @@ interface SessionRow {
  *   `POST /approvals/:toolCallId`; no timeout — pending approvals are resolved to deny
  *   when the Task is interrupted (then proceeds through the abort flow).
  *
+ * An unattended Session takes that one route differently: there is no frontend to ask, so
+ * the call is denied on the spot instead of suspending forever (see `unattended` below).
+ *
  * Every approval decision re-reads the current approval_mode (`getMode` reads the DB),
  * so mode changes take effect immediately.
  * Docs: /docs/tools § "Approval".
@@ -370,6 +530,15 @@ interface PendingApproval {
     toolCall: OmniMessage<ToolCallPayload>;
     origin?: string[];
 }
+/** A Session runtime's pending approvals, as its holder uses them — what {@link ApprovalRegistry} implements. */
+interface Approvals {
+    readonly size: number;
+    list(): PendingApproval[];
+    wait(toolCall: OmniMessage<ToolCallPayload>): Promise<ApprovalDecision>;
+    decide(toolCallId: string, decision: ApprovalDecision): boolean;
+    denyAll(): void;
+    denyMain(): void;
+}
 
 /** A numbered channel event; `id` is `<epoch>-<seq>`, `data` is serialized single-line JSON. */
 interface ChannelEvent {
@@ -518,15 +687,13 @@ interface TieredRates {
     offPeak: PricingRates;
 }
 
-declare const Errors_base: (abstract new () => {
-    record(args: ErrorRecordArgs): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** Errors: the mechanism ErrorRecorder implements. */
-declare abstract class Errors extends Errors_base {
+declare abstract class Errors {
+    abstract record(args: ErrorRecordArgs): void;
 }
 
 /** Capture-site source (maps one-to-one to error_records.source). */
-type ErrorSource = "http" | "organization" | "session" | "llm" | "environment" | "compaction" | "usage" | "title" | "subagent" | "process" | "schedule" | "messaging";
+type ErrorSource = "http" | "organization" | "session" | "llm" | "environment" | "compaction" | "usage" | "title" | "subagent" | "process" | "schedule" | "messaging" | "id_suggest" | "plugin";
 /** Error classification: see file header — the criterion is "does a human need to step in". */
 type ErrorKind = "expected" | "unexpected";
 /** Attribution context (all optional: the login endpoint has no Project, and process-level fallback has no request at all). */
@@ -582,10 +749,25 @@ interface TitleNotifier {
 }
 
 /**
- * trace_files / trace_sessions repo: the Trace-tree derived cache (see schema.ts and
- * services/trace-index.ts for the cache rules). Pure row access — reconciliation
- * policy (mtime gates, head-reads) lives in the service.
+ * In-process registry of Session sources, derived from core `session_meta` — the single
+ * source of truth for what kind of conversation a Session is (the DB stores no `source`
+ * column).
+ *
+ * Populated wherever the server actually has the meta in hand: Session creation
+ * (SessionService reads the just-created core Session's meta), subagent registration
+ * (SessionManager reads the forwarded child meta), forks (always `user`), and Trace adoption /
+ * lazy list resolution (the trace index's head read). A value read back from a Trace is
+ * narrowed through core's `normalizeSessionSource` (the retired `benchmark` reads as `cli`),
+ * except that a head recording no source is kept as `null`: what it reads as depends on the
+ * Session's index row (`readRecordedSource`), which a head read does not have. An absent entry
+ * means "unknown": the list path resolves it from the Trace once per process lifetime.
+ */
+
+/**
+ * What a Session's Trace head records as its source: one of the sources, or `null` for a head
+ * written before the source was required, which records none.
  */
+type RecordedSource = SessionSource | null;
 
 /** One indexed Trace shard. */
 interface TraceFileRow {
@@ -601,7 +783,12 @@ interface TraceSessionRow {
     sessionId: string;
     projectId: string;
     agentId: string;
-    source: SessionSource | null;
+    /**
+     * The head's session_meta source, narrowed; `null` when the head records none (written before
+     * the source was required; read it with the row's client, `readRecordedSource`). Meaningful
+     * only once `metaRead`.
+     */
+    source: RecordedSource;
     workspace: string;
     title: string | null;
     provider: string | null;
@@ -610,38 +797,37 @@ interface TraceSessionRow {
     metaRead: boolean;
 }
 
-declare const TraceIndexStore_base: (abstract new () => {
-    upsertFile(row: TraceFileRow): void;
-    updateFileSize(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number): void;
-    getPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number): string | null;
-    setPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number, pageStats: string): void;
-    deleteFile(projectId: string, agentId: string, sessionId: string, fileIndex: number): void;
-    listFilesByAgent(projectId: string, agentId: string): TraceFileRow[];
-    listFilesBySession(projectId: string, agentId: string, sessionId: string): TraceFileRow[];
-    findAgentBySession(projectId: string, sessionId: string): string | null;
-    upsertSession(row: TraceSessionRow): void;
-    getSession(sessionId: string): TraceSessionRow | null;
-    listSessionsByAgent(projectId: string, agentId: string): TraceSessionRow[];
-    deleteBySession(sessionId: string): void;
-    deleteByAgent(projectId: string, agentId: string): void;
-    deleteByProject(projectId: string): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** TraceIndexStore: the mechanism TraceIndexRepo implements. */
-declare abstract class TraceIndexStore extends TraceIndexStore_base {
+declare abstract class TraceIndexStore {
+    abstract upsertFile(row: TraceFileRow): void;
+    abstract updateFileSize(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number): void;
+    abstract getPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number): string | null;
+    abstract setPageStats(projectId: string, agentId: string, sessionId: string, fileIndex: number, sizeBytes: number, pageStats: string): void;
+    abstract deleteFile(projectId: string, agentId: string, sessionId: string, fileIndex: number): void;
+    abstract listFilesByAgent(projectId: string, agentId: string): TraceFileRow[];
+    abstract listFilesBySession(projectId: string, agentId: string, sessionId: string): TraceFileRow[];
+    abstract findAgentBySession(projectId: string, sessionId: string): string | null;
+    abstract upsertSession(row: TraceSessionRow): void;
+    abstract getSession(sessionId: string): TraceSessionRow | null;
+    abstract listSessionsByAgent(projectId: string, agentId: string): TraceSessionRow[];
+    abstract deleteBySession(sessionId: string): void;
+    abstract deleteByAgent(projectId: string, agentId: string): void;
+    abstract deleteByProject(projectId: string): void;
 }
-declare const TraceIndex_base: (abstract new () => {
-    readonly counters: {
+/** TraceIndex: the mechanism TraceIndexService implements. */
+declare abstract class TraceIndex {
+    abstract readonly counters: {
         gateStats: number;
         dirScans: number;
         headReads: number;
     };
-    reconcileAgent(projectId: string, agentId: string, opts?: {
+    abstract reconcileAgent(projectId: string, agentId: string, opts?: {
         force?: boolean;
     }): Promise<void>;
-    reconcileProject(projectId: string, opts?: {
+    abstract reconcileProject(projectId: string, opts?: {
         force?: boolean;
     }): Promise<void>;
-    registerImportedFile(args: {
+    abstract registerImportedFile(args: {
         projectId: string;
         agentId: string;
         sessionId: string;
@@ -650,32 +836,44 @@ declare const TraceIndex_base: (abstract new () => {
         sizeBytes: number;
         records: OmniMessage[];
     }): void;
-    removeSession(projectId: string, agentId: string, sessionId: string): void;
-    removeAgent(projectId: string, agentId: string): void;
-    removeProject(projectId: string): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
-/** TraceIndex: the mechanism TraceIndexService implements. */
-declare abstract class TraceIndex extends TraceIndex_base {
+    abstract removeSession(projectId: string, agentId: string, sessionId: string): void;
+    abstract removeAgent(projectId: string, agentId: string): void;
+    abstract removeProject(projectId: string): void;
 }
 
+interface PlatformCatalogPricing {
+    unit: "usd_per_mtok";
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+/** A platform model normalized into the fields Penguin persists for a newly discovered row. */
+interface PlatformCatalogModel {
+    modelId: string;
+    displayName: string;
+    contextWindow: number;
+    supportsVision: boolean;
+    /**
+     * List price, which is what a Project stores: the platform's `listPricing` when it runs a
+     * promotion on the model, its billed `pricing` otherwise.
+     */
+    pricing: PlatformCatalogPricing;
+    /** Fraction off `pricing` the platform is running (0.5 = half price); absent when none. */
+    discount?: number;
+    baseUrl: string;
+    clientType: "mmsp";
+}
+/** Validated snapshot returned by Penguin Go's client-model catalog. */
+interface PlatformModelCatalog {
+    models: PlatformCatalogModel[];
+}
 /**
- * "desktop" and "setup" may set a password without the old one (theirs is random and was never
- * shown); desktop-only routes open to "desktop" alone. "token" is the local API token's Bearer
- * header — per request, never a stored row. Anything else reads as "password".
+ * Catalog merge result. `updated` counts route migrations; existing metadata is preserved.
  */
-type SessionVia = "password" | "desktop" | "setup" | "token";
-
-interface UserRow {
-    userId: string;
-    passwordHash: string;
-    isAdmin: boolean;
-    /** Still using the initial password (seeded / set by an admin); cleared to 0 once the user changes it. */
-    passwordIsInitial: boolean;
-    /** Nickname shown in place of the id; null = never set. */
-    displayName: string | null;
-    /** Avatar as a data URL; null = never set. */
-    avatar: string | null;
-    createdAt: string;
+interface PlatformModelApplyResult {
+    added: number;
+    updated: number;
+    applied: number;
 }
 
 type RawTable = Record<string, unknown>;
@@ -695,20 +893,26 @@ type UtilityCompletion = {
     error: string;
 };
 
-declare const ProjectConfigStore_base: (abstract new () => {
-    readRaw(projectId: string): Promise<RawTable>;
-    loadConfig(projectId: string): Promise<ProjectConfig>;
-    writeRaw(projectId: string, data: RawTable): Promise<void>;
-    writeInitialConfig(projectId: string, name: string): Promise<void>;
-    ensurePresetModels(projectId: string): Promise<void>;
-    getName(projectId: string): Promise<string | undefined>;
-    setName(projectId: string, name: string): Promise<void>;
-    getDefaultModelRef(projectId: string): Promise<ModelRef | undefined>;
-    setDefaultModelRef(projectId: string, ref: ModelRefDto): Promise<ModelRefDto>;
-    getChatDefaults(projectId: string): Promise<ChatDefaultsDto>;
-    setChatDefaults(projectId: string, req: ChatDefaultsDto): Promise<ChatDefaultsDto>;
-    getCommandPolicy(projectId: string): Promise<CommandPolicyDto>;
-    setCommandPolicy(projectId: string, req: {
+/** ProjectConfigStore: the mechanism ProjectConfigService implements. */
+declare abstract class ProjectConfigStore {
+    abstract readRaw(projectId: string): Promise<RawTable>;
+    abstract loadConfig(projectId: string): Promise<ProjectConfig>;
+    abstract writeRaw(projectId: string, data: RawTable): Promise<void>;
+    abstract writeInitialConfig(projectId: string, name: string): Promise<void>;
+    abstract ensurePresetModels(projectId: string): Promise<boolean>;
+    abstract seedPresetPromotions(projectId: string): Promise<void>;
+    abstract getName(projectId: string): Promise<string | undefined>;
+    abstract setName(projectId: string, name: string): Promise<void>;
+    abstract getDefaultModelRef(projectId: string): Promise<ModelRef | undefined>;
+    abstract setDefaultModelRef(projectId: string, ref: ModelRefDto): Promise<ModelRefDto>;
+    abstract getChatDefaults(projectId: string): Promise<ChatDefaultsDto>;
+    abstract setChatDefaults(projectId: string, req: ChatDefaultsDto): Promise<ChatDefaultsDto>;
+    /** The `[plugins]` key: the shared table and each machine's own, package name → requirement, in the file's order. */
+    abstract getPluginTables(projectId: string): Promise<PluginTables>;
+    /** Replaces the tables (a declarative PUT); answers what was written. */
+    abstract setPluginTables(projectId: string, tables: PluginTables): Promise<PluginTables>;
+    abstract getCommandPolicy(projectId: string): Promise<CommandPolicyDto>;
+    abstract setCommandPolicy(projectId: string, req: {
         enabled?: boolean;
         rules: {
             name: string;
@@ -717,20 +921,74 @@ declare const ProjectConfigStore_base: (abstract new () => {
             enabled?: boolean;
         }[];
     }): Promise<CommandPolicyDto>;
-    getPricing(projectId: string, provider: string, modelId: string): Promise<TieredRates | undefined>;
-    detectVision(projectId: string, req: ModelVisionDetectRequest): Promise<ModelVisionDetectResponse>;
-    testModel(projectId: string, req: ModelTestRequest): Promise<ModelTestResponse>;
-    detectProtocol(projectId: string, req: ModelProtocolDetectRequest): Promise<ModelProtocolDetectResponse>;
-    listEndpointModels(req: EndpointModelListRequest, listImpl?: (options: ListEndpointModelsOptions) => Promise<string[]>, timeoutMs?: number): Promise<EndpointModelListResponse>;
-    getModels(projectId: string): Promise<ModelsResponse>;
-    updateModels(projectId: string, req: ModelsUpdateRequest): Promise<ModelsResponse>;
-    setGroupApiKey(projectId: string, provider: string, apiKey: string): Promise<number>;
-    completeOnce(projectId: string, prompt: string): Promise<UtilityCompletion>;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
-/** ProjectConfigStore: the mechanism ProjectConfigService implements. */
-declare abstract class ProjectConfigStore extends ProjectConfigStore_base {
+    abstract getPricing(projectId: string, provider: string, modelId: string): Promise<TieredRates | undefined>;
+    abstract detectVision(projectId: string, req: ModelVisionDetectRequest): Promise<ModelVisionDetectResponse>;
+    abstract testModel(projectId: string, req: ModelTestRequest): Promise<ModelTestResponse>;
+    abstract detectProtocol(projectId: string, req: ModelProtocolDetectRequest): Promise<ModelProtocolDetectResponse>;
+    abstract listEndpointModels(req: EndpointModelListRequest, listImpl?: (options: ListEndpointModelsOptions) => Promise<string[]>, timeoutMs?: number): Promise<EndpointModelListResponse>;
+    abstract getModels(projectId: string): Promise<ModelsResponse>;
+    abstract updateModels(projectId: string, req: ModelsUpdateRequest): Promise<ModelsResponse>;
+    /** One group's `[providers.<id>]` connection, merged per field; rows are never touched. */
+    abstract setProviderConnection(projectId: string, provider: string, patch: ProviderConnectionUpdate): Promise<ModelsResponse>;
+    /** "Add new models" (`add`) or "Restore defaults" (`restore`) against the built-in catalog. */
+    abstract syncPresets(projectId: string, mode: PresetSyncMode): Promise<PresetSyncResponse>;
+    /** Writes the group key; resolves to how many of the group's rows use it (none of their own). */
+    abstract setGroupApiKey(projectId: string, provider: string, apiKey: string): Promise<number>;
+    abstract setGroupApiKeyWithProviderAuthToken(projectId: string, provider: string, apiKey: string, token: Omit<ModelProviderAuthToken, "provider" | "updatedAt">, options?: {
+        expectedRefreshToken?: string;
+    }): Promise<number>;
+    /** The group key (`[providers.<id>].api_key`), never a row's own. Server-side only. */
+    abstract getGroupApiKey(projectId: string, provider: string): Promise<string | undefined>;
+    /** One row's own key (its override of the group's), or undefined. Server-side only. */
+    abstract getModelApiKey(projectId: string, provider: string, modelId: string): Promise<string | undefined>;
+    /**
+     * The key a group's account balance is read with: the group key (never a row's own), or
+     * else the environment key a Session on one of the group's rows would use on its effective
+     * endpoint, when that variable's official endpoint is the balance endpoint's own host.
+     * Server-side only.
+     */
+    abstract getGroupBalanceKey(projectId: string, provider: string): Promise<string | undefined>;
+    abstract setModelApiKeyResolver(resolver: (context: ModelRequestContext) => Promise<string | undefined>): void;
+    abstract mergePlatformModels(projectId: string, provider: string, catalog: PlatformModelCatalog, apiKey: string, applyKeyToExisting: boolean): Promise<PlatformModelApplyResult>;
+    abstract completeOnce(projectId: string, prompt: string): Promise<UtilityCompletion>;
+}
+interface ModelProviderAuthToken {
+    provider: string;
+    refreshToken: string;
+    accessTokenExpiresAt?: string;
+    updatedAt: string;
 }
 
+/**
+ * The order a Session list is served in: `created` (the default) is newest creation first;
+ * `activity` is most recent `lastActiveAt` first — the order the sidebar displays, and the only
+ * one an {@link ActivityCursor} pages.
+ */
+type SessionListOrder = "created" | "activity";
+/** A row's place in the activity order; as a `before` cursor, the last row the client holds. */
+interface ActivityCursor {
+    lastActiveAt: string;
+    sessionId: string;
+}
+/** One row the listing rule files as archived (SessionService.archivedRows). */
+interface ArchivedRow {
+    row: SessionRow;
+    /** The source the row was classified by; absent while its Trace head is unread. */
+    source?: SessionSource;
+    /** Whether a Trace record exists: what toInfo takes for this row. */
+    hasTrace: boolean;
+}
+/**
+ * A slice of a Session list: `offset` rows skipped (the `created` contract, also accepted under
+ * `activity`), or every row strictly below `before` in the activity order.
+ */
+type SessionListPaging = {
+    offset: number;
+    limit: number;
+} | {
+    before: ActivityCursor;
+    limit: number;
+};
 interface SessionServiceDeps {
     root: string;
     sessions: SessionIndex;
@@ -759,6 +1017,14 @@ interface SessionServiceDeps {
      * this harness's own `penguin`, put in front of every command an Agent runs.
      */
     pathPrepend?: () => string[];
+    /**
+     * Tells every user of a Project that a Session now exists. The list only ever learns
+     * about rows it did not create itself from this: a Session started by the CLI, by
+     * another tab, by a schedule, or by an agent spawning a child sat invisible until the
+     * next full reload without it. Optional so the service keeps unit-testing without a
+     * channel registry; absent means nobody is told.
+     */
+    notifyProjectUsers?: (projectId: string, event: ServerEvent) => void;
     /**
      * The channel of the Session's ENABLED messaging binding, or null when none is enabled
      * (SessionInfo.messagingChannel, the sidebar row's per-channel indicator — saved-but-
@@ -766,7 +1032,7 @@ interface SessionServiceDeps {
      * service stays decoupled from the bindings table; absent (older assemblies/tests)
      * means the field is never set.
      */
-    messagingChannel?: (sessionId: string) => MessagingChannel$1 | null;
+    messagingChannel?: (sessionId: string) => MessagingChannel | null;
     /**
      * Company mode: the organization owning a Session (a desk session, or a session
      * contributing to a ticket), for `SessionInfo.orgId` — development mode's list hides
@@ -779,44 +1045,99 @@ interface SessionServiceDeps {
     orgIdOfSession?: (sessionId: string) => string | undefined;
     orgIdsOfProject?: (projectId: string) => ReadonlyMap<string, string>;
     /** Spawn-confinement getter (the sandbox module's), forwarded into core beside proxyEnv. */
-    confineSpawn?: () => SpawnConfiner | null;
+    confineSpawn?: (ctx: ControlEnvContext) => SpawnConfiner | null;
+    /** The server's Sandbox settings: what a new Session's policy is snapshotted from. */
+    sandboxDefaults?: () => SandboxSettings;
+    /** Host-owned model-request hooks, forwarded to core for every Session LLM. */
+    assembly?: AgentAssembly;
+    /** The dimensions the mounted sandbox backends implement between them (none when absent). */
+    sandboxDimensions?: () => readonly SandboxDimension[];
+    /** The enabled sandbox backends that failed to load or failed their check, with why. */
+    sandboxUnavailable?: () => readonly UnavailableSandboxBackend[];
+    /** The names of the sandbox backends in use, in routing preference (none when absent). */
+    sandboxBackends?: () => readonly string[];
+    /** The Sandbox card's presets table, in table order (absent: the view carries none). */
+    sandboxPresets?: () => readonly SessionSandboxPreset[];
+    /** The Sandbox card's switch: whether new Sessions start confined (absent: not reported). */
+    sandboxSwitchOn?: () => boolean;
+    /** The approval mode a new Session starts with when its request names none (the default preset's). */
+    sandboxDefaultApproval?: () => ApprovalMode | undefined;
 }
 declare class SessionService {
     private readonly deps;
     constructor(deps: SessionServiceDeps);
+    /** The policy a new Session starts with: the server's Sandbox settings. */
+    defaultSandbox(): SandboxSettings;
+    /** Whether this server can enforce the `local` network level right now. */
+    localNetworkSupported(): boolean;
+    private sandboxDimensions;
+    /** A policy as the composer sees it, with which of its levels this server can enforce. */
+    sandboxView(policy: SandboxSettings): SessionSandbox;
+    /**
+     * What a new Session starts from, as the composer's draft reads it (the chat defaults): the
+     * settings' policy, plus the approval mode the default preset gives a request naming none.
+     */
+    defaultsView(): SessionSandbox;
+    /**
+     * The approval mode a Session created without one starts with. An organization's Session
+     * keeps `allow-all`: its runtime names the mode it wants, and nobody is there to answer an
+     * ask a preset might bring. The other unattended creators — a scheduled run, a workbench —
+     * pass `allow-all` themselves (scheduler.ts, workbenches/service.ts).
+     */
+    private startApproval;
+    /** A Session's policy: its snapshot, or — for a row from before snapshots — the settings. */
+    sandboxOf(row: SessionRow): SandboxSettings;
+    /**
+     * The policy a pick would give one Session, checked — the non-admin ceiling and what this
+     * server can enforce — and not written: a PATCH checks every field before it writes any.
+     */
+    pickSandbox(row: SessionRow, pick: Partial<SessionSandbox>, isAdmin: boolean): SandboxSettings;
+    /** Stores one Session's policy (`pickSandbox`'s): its next command runs under it. */
+    updateSandbox(sessionId: string, policy: SandboxSettings): void;
     /**
      * DB row -> SessionInfo (run status and pending approval count come from session-manager).
      * Async because `source` is derived from session_meta: a registry miss (Session predating
      * this process) falls back to reading the Trace head once (see sourceOf). `traces` is the
      * list flow's one-walk discovery result; without it a miss locates the shard itself.
+     * `archived` is the listing rule's answer (listCategory), not the bare mark: a background
+     * Session the user never kept reads archived, and a subagent with a stray mark does not.
      *
      * `orgIds` is the list flow's one-query organization map (see listSessions); without it the
      * organization is a point lookup, which is what the single-Session paths want.
      */
     toInfo(row: SessionRow, hasTrace: boolean, orgIds?: ReadonlyMap<string, string>): Promise<SessionInfo>;
     /**
-     * A Session's origin, with session_meta as the single source of truth: the in-process
-     * registry answers first (populated at creation / subagent registration / adoption /
+     * A Session's source, with session_meta as the single source of truth: the in-process
+     * registry answers first (populated at creation / subagent registration / forks / adoption /
      * index registration); on a miss (a Session created before this process started) the
      * trace index's registration-time facts answer — the reconciler head-read the earliest
-     * shard once when the file first appeared, so no file is touched here. A Session with
-     * no Trace yet stays unknown and is NOT cached negatively — its meta may appear with
-     * the first run.
+     * shard once when the file first appeared, so no file is touched here. A head that records
+     * no source is read with the row's client (readRecordedSource). A Session with no Trace yet
+     * is NOT cached — its meta appears with the first run — and reads as its row says
+     * (unrunSource): the organization runtime's as `company`, the Agent API's as `api`, any other
+     * as unknown.
      */
     private sourceOf;
     /** Whether this Session already has a Trace record (a Task has been run): answered by the index (reconciled first). */
     hasTrace(row: SessionRow): Promise<boolean>;
     /**
-     * The list category of a row: archived wins (an explicit user action), then the
-     * origin's bucket, and no/unknown source is `active` — the same precedence the
-     * sidebar's partition applies to loaded rows, so server filtering and client
-     * rendering can never disagree.
+     * The list category of a row (see listCategory): none for a `subagent` or `company` Session,
+     * whatever its marks, which the list never serves; otherwise archived when the user archived
+     * it or when a program opened it and the user has not kept it, else active.
      */
     private categoryOf;
     /**
-     * List, sorted by createdAt descending. Every row is served **straight from the DB**,
-     * whichever client created it, with no Trace directory scanning — the answer to
-     * many-session sidebar reloads re-walking the filesystem on every request (#139).
+     * Where one row is listed, for a caller holding just the row (a PATCH, the archive page's
+     * batches). A row the registry already classified costs nothing; any other is looked up
+     * through the trace index once (hasTrace reconciles the Agent), so a subagent Session is
+     * known for one even before any list has walked it.
+     */
+    listingOf(row: SessionRow): Promise<SessionCategory | null>;
+    /**
+     * List, sorted by createdAt descending — or, with `order: "activity"`, by lastActiveAt
+     * descending (ties by sessionId, see {@link compareActivityDesc}). Every row is served
+     * **straight from the DB**, whichever client created it, with no Trace directory scanning —
+     * the answer to many-session sidebar reloads re-walking the filesystem on every request (#139).
      * Sessions living only in the Trace directory were adopted into the index by the
      * boot-time sweep (`adoptUnmanagedTraceSessions`), so listing never discovers. One
      * lazy discovery walk still runs for a list call that contains rows this process has
@@ -828,36 +1149,78 @@ declare class SessionService {
      * "has more"); slicing happens before toInfo, so per-request source derivation (lazy
      * Trace-head reads) stays bounded by the page size.
      *
-     * `category` filters to one sidebar bucket **before** paging, so offset/limit page
-     * within the category. Filtering needs each walked row's category (a possible
-     * Trace-head read per row, cached in the sources registry); without `withCounts`
-     * the walk stops as soon as the requested page is complete. `withCounts` classifies
-     * every row and returns per-category totals over the whole list — plus the same
-     * totals broken down by Workspace path, and each path's newest Session's `createdAt` —
-     * so the sidebar can label the collapsed folders, list every Workspace that holds
-     * Sessions (not only the ones its loaded pages happen to touch) and place the groups
-     * by recency, all without loading them.
+     * The `before` form pages the activity order by cursor: only rows strictly below it are
+     * walked and served. An offset cannot page that order, because a row below the offset that
+     * becomes active moves above it and the next page would skip a row; a cursor stays put — the
+     * moved row is simply not served again (the client learns of it from `session_state`). The
+     * offset form keeps serving the `created` order exactly as before.
+     *
+     * `category` filters to one list (the sidebar's `active`, the archive page's `archived`)
+     * **before** paging, so offset/limit page within the category. Filtering needs each walked
+     * row's category (a possible Trace-head read per row, cached in the sources registry);
+     * without `withCounts` the walk stops as soon as the requested page is complete.
+     * `withCounts` classifies every row, a cursor or not, and returns per-category totals over
+     * the whole list — plus the same totals broken down by Workspace path, and each path's
+     * newest Session's `createdAt`, once over every category (`workspaceLatest`, the Workspace
+     * picker's "recently used") and once over the active ones (`workspaceLatestActive`) — so the
+     * sidebar can list every Workspace that holds active Sessions (not only the ones its loaded
+     * pages happen to touch) and place the groups by the recency of what they show, all without
+     * loading them.
      *
      * `workspaceGroup` filters the same way, to one Workspace group (see workspace-group.ts),
      * so a sidebar grouped by Workspace pages each group down its OWN stream instead of
      * sharing one per-Agent cursor — without it, one group's "load more" consumes the page
      * its siblings were about to read, and their rows move on screen untouched. The two
      * filters compose; the returned counts stay whole-Agent either way.
+     *
+     * A `subagent` or `company` Session — a child its parent's Agent panel opens, company mode's
+     * desk and ticket Sessions — belongs to no category (listCategory), whatever its marks: every
+     * classified form of the list (`category`, `workspaceGroup` or `withCounts`) leaves it out of
+     * the page, the totals, the Workspace breakdown and its stamps alike. The plain form, which
+     * classifies nothing, still serves every row.
+     *
+     * `excludeOrg` drops the rows an organization owns (its desk and ticket sessions, and the
+     * sub-sessions they spawned) from the stream BEFORE anything else looks at it — the page,
+     * `counts`, `workspaceCounts`, both Workspace stamps and the limit+1 "has more" all describe the
+     * same own-rows stream. It is what development mode's list asks for: that list draws the
+     * user's own conversations, and a total or a stamp that still counted a desk or a ticket
+     * session would make its Workspace appear as a group the list can never fill. The rule above
+     * does not replace it: a person's conversation attached to a ticket is stamped `org` but
+     * stays `user`, and a row the organization caches name before the reconcile pass stamps it
+     * reads as `user`. Without the flag every row is served, whichever client created it, but
+     * for that rule.
      */
     listSessions(projectId: string, agentId: string, opts?: {
-        paging?: {
-            offset: number;
-            limit: number;
-        };
+        paging?: SessionListPaging;
+        order?: SessionListOrder;
         category?: SessionCategory;
         workspaceGroup?: string;
         withCounts?: boolean;
+        excludeOrg?: boolean;
     }): Promise<{
         sessions: SessionInfo[];
         counts?: SessionCategoryCounts;
         workspaceCounts?: Record<string, SessionCategoryCounts>;
         workspaceLatest?: Record<string, string>;
+        workspaceLatestActive?: Record<string, string>;
     }>;
+    /**
+     * The archive page's walk (services/archived-sessions-service.ts): every row of the Agent the
+     * listing rule files as archived — the rows `listSessions` serves with `category: "archived"`
+     * and `excludeOrg`, classified the same way — with the source each was classified by and
+     * whether it has a Trace. It builds no SessionInfo: the page makes one (toInfo) only for the
+     * rows a response carries, so a request costs a classification per archived row, not a full
+     * row view per archived row.
+     */
+    archivedRows(projectId: string, agentId: string): Promise<ArchivedRow[]>;
+    /**
+     * The rows a list walk starts from: the Agent's index rows, an organization's left out when
+     * `excludeOrg` asks (see listSessions), with the Project's organization map; and when any row
+     * predates this process, the one reconciled Trace discovery (`traces`) that lets every row be
+     * classified without per-row work and backfills the `has_trace` cache. Steady state —
+     * every row classified — skips the discovery and leaves `traces` absent.
+     */
+    private walkRows;
     /**
      * Session stats (Agents list card): total count = size of the union of DB index
      * ∪ Trace directory discovery; activity = number of active Sessions per day over
@@ -886,21 +1249,30 @@ declare class SessionService {
         /** The provider group for `modelId`; always paired with modelId, never inferred. */
         provider?: string;
         workspace?: string;
+        thinkingLevel?: ThinkingLevelName;
         approvalMode?: ApprovalMode;
+        /** The composer's sandbox picks; omitted halves take the server's settings. */
+        sandbox?: Partial<SessionSandbox>;
+        /** Whether the creator is an administrator (may loosen past the settings). Default false. */
+        isAdmin?: boolean;
         /**
-         * Session source marker: `schedule` when triggered by a scheduled task, `benchmark` when
-         * created by a Benchmark evaluation or optimization (the only value a client may send);
-         * defaults to user-created.
+         * What kind of conversation this is, recorded in the Session's session_meta: `schedule`
+         * from the scheduler, `company` from the organization runtime, `cli` from `penguin run`
+         * (the only source a request may name), `api` from an Agent API run; absent means `user`,
+         * a person's conversation.
          */
-        source?: "schedule" | "benchmark";
+        source?: SessionSource;
         /**
          * Creating-client hint stored on the index row (`POST .../sessions` body `client`):
-         * "cli" from the CLI, defaulting to "web". "org" is not accepted over HTTP — the
-         * organization runtime calls this method directly and is the only caller that passes
-         * it, so no request can claim an organization's provenance for itself.
+         * "cli" from the CLI, defaulting to "web". "org" and "api" are not accepted over HTTP —
+         * the organization runtime and the Agent API's run handler call this method directly and
+         * are the only callers that pass them, so no request can claim either provenance for
+         * itself ("api" is what lets the Agent API continue a Session).
          */
-        client?: "web" | "cli" | "org";
+        client?: "web" | "cli" | "org" | "api" | "workbench";
     }): Promise<SessionInfo>;
+    /** A new Session's snapshot: the settings, with the creator's picks (checked) on top. */
+    private snapshotSandbox;
     /**
      * Absolute path of a Session's **latest** Trace file (the current context shard);
      * undefined when no Trace exists. Costs a directory walk, so only the single-session
@@ -936,16 +1308,118 @@ declare class SessionService {
     private adoptTraceSession;
 }
 
+type ModelScopeAuthStatusResult = ModelScopeAuthFlowStatusResponse & {
+    changed?: true;
+};
+interface ModelScopeCredential {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: string;
+}
+interface ModelScopeRefreshResult {
+    changed: boolean;
+}
+interface ModelScopeAuthDeps {
+    /** Base URL of the bridge, without a trailing slash (config.modelscopeBridgeUrl). */
+    bridgeUrl: string;
+    /**
+     * Writes the delivered credential as the group key; resolves to how many of the group's rows
+     * use the access token (0 also when a refresh lost to a newer authorization and wrote nothing).
+     */
+    applyCredential: (projectId: string, credential: ModelScopeCredential, options?: {
+        expectedRefreshToken?: string;
+    }) => Promise<number>;
+    /** Reads the server-side refresh metadata for the group. */
+    readStoredCredential?: (projectId: string) => ModelProviderAuthToken | undefined;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+declare class ModelScopeAuthService {
+    private readonly deps;
+    private readonly flows;
+    private readonly refreshes;
+    private readonly refreshFailures;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(deps: ModelScopeAuthDeps);
+    private url;
+    private isPending;
+    private request;
+    ensureFresh(input: {
+        projectId: string;
+        provider: string;
+    }): Promise<ModelScopeRefreshResult>;
+    start(input: {
+        projectId: string;
+        userId: string;
+    }): Promise<{
+        flowId: string;
+        authorizeUrl: string;
+        expiresAt: string;
+    }>;
+    status(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): Promise<ModelScopeAuthStatusResult>;
+    retryApply(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): Promise<ModelScopeAuthStatusResult>;
+    cancel(input: {
+        flowId: string;
+        projectId: string;
+        userId: string;
+    }): void;
+    private refreshState;
+    private refreshNow;
+    private reauthorizationRequired;
+    private pollBridge;
+    private apply;
+    private publicFlow;
+    private requireFlow;
+    private sweep;
+    private evictOldest;
+}
+declare const ModelScopeAuth_base: (abstract new () => Pick<ModelScopeAuthService, "status" | "start" | "retryApply" | "cancel" | "ensureFresh">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** The per-App ModelScope key authorization capability consumed by Project model routes. */
+declare abstract class ModelScopeAuth extends ModelScopeAuth_base {
+}
+
 /** Minimal interface for a runtime Session (satisfied by core Session; tests may inject a fake implementation). */
+/** What one run is started with: the approval callback and the interrupt signal. */
+type RunOpts = {
+    approve: ApproveFn;
+    signal: AbortSignal;
+};
 interface RuntimeSession {
     readonly sessionId: string;
-    run(newMessages: OmniMessage[], opts: {
-        approve: ApproveFn;
-        signal: AbortSignal;
-    }): AsyncGenerator<OmniMessage>;
+    run(newMessages: OmniMessage[], opts: RunOpts): AsyncGenerator<OmniMessage>;
     compact(opts: {
         signal: AbortSignal;
     }): AsyncGenerator<OmniMessage>;
+    /**
+     * The running context's model (core `Session.provider` / `Session.modelId`, getters over
+     * the context's session_meta): the row's pair at creation, moved by each in-session switch
+     * — and, after a restart, whatever the Trace resumed on. Optional: test fakes may omit them,
+     * in which case the entry keeps the row's pair.
+     */
+    readonly provider?: string;
+    readonly modelId?: string;
+    /**
+     * Switches the Session's model in place (core `Session.switchModel`): closes the running
+     * context on the model it ran on, then opens the next one on the target. A completed switch
+     * streams the new context's main-session `session_meta` last, and the getters above answer
+     * the target by then; a refusal is thrown before the first event; a Session that never ran
+     * switches without streaming anything. Optional: test fakes may omit it, reading as
+     * "switching is not available".
+     */
+    switchModel?(opts: {
+        provider: string;
+        modelId: string;
+        signal: AbortSignal;
+    }): AsyncGenerator<OmniMessage, StopReason>;
     /**
      * The Session's thinking level (core `Session.thinkingLevel`, plain state): soft-limited —
      * an assignment applies from the Session's very next LLM request. Optional: test fakes may
@@ -965,6 +1439,13 @@ interface RuntimeSession {
     unsteer?(input: OmniMessage[]): boolean;
     /** Skips the in-progress reconnect backoff, firing the next retry immediately (core `Session.skipReconnectWait`); false when no wait is in progress. */
     skipReconnectWait(): boolean;
+    /**
+     * Whether a run with empty input would send anything (core `Session.hasPendingInput`): the
+     * input of a turn that failed or was stopped, held as carry-over — in process, or rebuilt
+     * from the Trace after a restart — or a compaction summary waiting for the next run.
+     * Optional: test fakes may omit it, reading as nothing held.
+     */
+    hasPendingInput?(): boolean;
     /**
      * Runs the named package's `user_prompt` hook (core `Session.runUserPromptHook` — hooks
      * run in core and nowhere else); null = the package is not installed or names no such
@@ -1041,6 +1522,8 @@ interface UsageRecorderLike {
     record(ctx: UsageContext, msg: OmniMessage): Promise<void>;
 }
 interface SessionManagerDeps {
+    /** The in-memory state this manager works on (see agent-state.ts). Optional: a manager built without one — unit tests — gets an empty state of its own. */
+    state?: AgentState;
     sessions: SessionIndex;
     channels: ChannelHub;
     loader: SessionLoader;
@@ -1051,6 +1534,8 @@ interface SessionManagerDeps {
     titles?: TitleNotifier;
     /** Error persistence (optional: without it, only logs — same as before this was wired up). */
     errors?: ErrorSink;
+    /** Provider auth refresh (optional for tests that do not exercise external model credentials). */
+    modelScopeAuth?: ModelScopeAuth;
     log?: (line: string) => void;
     /** Goal run-state persistence (optional like `titles`: without it, goals run but leave no restorable record). */
     /**
@@ -1087,9 +1572,120 @@ interface RecallStore {
     images: string[];
     files: RecallableFile[];
 }
+/** One queued follow-up task (`queueIfBusy`): the task input, held until the session is idle. */
+interface QueuedFollowUp {
+    /** Recall handle (PendingFollowUpInfo.id), assigned at queue time. */
+    id: string;
+    input: OmniMessage[];
+    /**
+     * Original content for recall, and the content `task_state` shows on the queued line.
+     * Always present: a caller that knows more than the input carries (the HTTP route, which
+     * also knows where the file attachments landed on disk) supplies it, and every other
+     * queueing path gets it derived from the input — what can be recalled must not depend on
+     * which door the message came through.
+     */
+    recall: RecallStore;
+}
+/** One undelivered steering entry: the display info broadcast on task_state, plus what a recall needs — the exact input list core queued (its unsteer handle) and the original content. */
+interface PendingSteeringEntry {
+    info: PendingSteeringInfo;
+    input: OmniMessage[];
+    recall: RecallStore;
+}
+/** Active-table entry: a loaded runtime Session plus its running state. */
+interface RuntimeEntry {
+    sessionId: string;
+    projectId: string;
+    agentId: string;
+    /**
+     * The Session's current model (provider group paired with modelId): what the next drive
+     * attributes usage to. The row's pair, kept in step with the runtime's own answer (see
+     * `syncEntryModel`) — at load, and whenever a model switch moves it.
+     */
+    provider: string;
+    modelId: string;
+    session: RuntimeSession;
+    status: SessionStatus;
+    approvals: Approvals;
+    abort: AbortController | null;
+    /** The in-flight drive Promise (awaited during graceful shutdown). */
+    running: Promise<void> | null;
+    /**
+     * Agent config generation this runtime was built under (see
+     * invalidateAgentRuntimes): once it falls behind the Agent's current generation,
+     * the entry is discarded on its next idle access and re-resumed via the loader.
+     */
+    generation: number;
+    /**
+     * Queued follow-up tasks (`queueIfBusy`): task inputs accepted while a Task/compaction was
+     * in progress, auto-started one at a time (in order) once the session returns to idle —
+     * ordinary tasks with normal semantics, unlike the mid-run steering queue.
+     * Deliberately NOT discarded on abort: they are future tasks the user explicitly queued.
+     */
+    followUps: QueuedFollowUp[];
+    /**
+     * The running Task's input messages, held from launch until the run ends. The engine
+     * writes these exact envelopes to the Trace only after the session bootstrap (MCP
+     * connect + discovery on the first run), so a history read during that window would
+     * miss the user's own message — and the draft flow subscribes to the stream only after
+     * the input publish, so the live channel cannot backfill it either. GET /messages
+     * appends the ones the Trace has not caught up to yet (exact-envelope dedup).
+     */
+    pendingInputs: OmniMessage[];
+    /**
+     * The running Task's streamed bootstrap records (mcp_connect begin/end,
+     * tool_list_ready), held until the run ends. Their Trace writes are deferred by the
+     * engine until after the input lands (turn attribution), and the draft flow subscribes
+     * only after they were published — so a history rebuild during the MCP connect would
+     * otherwise show nothing at all (a silent blank while a slow server times out).
+     * GET /messages appends whichever of them the Trace has not caught up to.
+     */
+    pendingBootstrap: OmniMessage[];
+    /**
+     * Steering messages queued on core but not yet delivered to the model — a display mirror
+     * of core's steering queue (same FIFO order), so the composer's "steering queued" hint and
+     * its content survive reloads: pushed on `steer`, shifted as each `[user_steering]`
+     * message appears on the drive stream, dropped wholesale when the run exits (core
+     * discards undelivered steering on abort/completion). The `info` halves are broadcast on
+     * every `task_state`; the rest is the recall handle (see recallSteering).
+     */
+    pendingSteering: PendingSteeringEntry[];
+    /**
+     * Steering the run ended without ever delivering — handed back to the user instead of
+     * discarded (#287 follow-up). An interrupt mid-tool-call is the ordinary way to get here:
+     * core drops its queue when the run exits, so the message would otherwise vanish with the
+     * text the user had already typed.
+     *
+     * Entries move here from `pendingSteering` when the run exits and stay recallable by the
+     * same handle, so the composer pulls them back into its draft (auto-recall on observing
+     * them, a reload included). They are deliberately NOT cleared when the next run starts:
+     * the message was never delivered whatever happens later, and dropping it there would
+     * reintroduce exactly the loss this list exists to prevent. Only a recall — or the entry's
+     * idle eviction — removes one.
+     */
+    returnedSteering: PendingSteeringEntry[];
+    /** Timestamp of last activity (refreshed on load / status flip / drive completion / background-task change), used for idle-eviction checks. */
+    lastActivityMs: number;
+    /**
+     * Background-task counts as last read from the runtime — at entry creation, then on every
+     * background-state ping. The baseline `session_background` is published against: a ping
+     * that leaves the counts where they were (a foreground-window child settling, an exited
+     * process being removed from the list) publishes nothing.
+     */
+    backgroundTasks: SessionBackgroundTasks;
+}
 declare class SessionManager {
     private readonly deps;
+    private readonly state;
     private readonly entries;
+    /**
+     * Each registered subagent Session's ROOT Session: a subagent runs under its root's
+     * sandbox policy, as it runs under its root's approval mode, so a change the person makes
+     * in the composer reaches the children already running.
+     */
+    private readonly childRoots;
+    /** The Session whose policy governs `sessionId`: its root for a subagent, else itself. */
+    rootSessionOf(sessionId: string): string;
     /** Per-Session mutex (serializes get-or-load and status flips); auto-cleaned once the chain drains. */
     private readonly locks;
     private readonly log;
@@ -1099,6 +1695,8 @@ declare class SessionManager {
     private readonly deletingAgents;
     /** Sessions currently being deleted (guards against the entry/Trace file being rebuilt and reviving it inside the deletion race window). */
     private readonly deletingSessions;
+    /** Sessions whose runtime entry idle eviction leaves alone (see keepLoaded). */
+    private readonly keptLoaded;
     /** Per-Agent config generation (key = agentKey), bumped by invalidateAgentRuntimes when a Project's credentials change. */
     private readonly agentGenerations;
     /** Open streaming fragments of running sessions (fed by drive, served to GET /messages; see live-tail.ts). */
@@ -1193,6 +1791,14 @@ declare class SessionManager {
      * The entry-lifetime approval callback: the registry, the per-decision approval-mode
      * re-read, and the SSE escalation are all entry-scoped, so one instance serves every run
      * of the entry and the children's session-lifetime fallback sink alike.
+     *
+     * This is also where the one cross-cutting approval override lives — wrapping the callback
+     * handed to `Session.run` rather than teaching the engine anything: an organization's
+     * sessions run with nobody watching, so a call their approval mode would hand to a person
+     * is denied here instead of waiting for an answer that is never coming (see `unattended`
+     * in approvals.ts). The marker is the row's durable `client = "org"` stamp — desk, ticket
+     * and the sub-sessions that inherit it — read per decision, so a row the reconcile pass
+     * stamps later is covered from its next decision on.
      */
     private entryApprove;
     /** Publishes one live background-subagent message and records its usage (fire-and-forget; the child's own Trace is the durable record). */
@@ -1256,6 +1862,21 @@ declare class SessionManager {
         sessionId: string;
         queued: boolean;
     }>;
+    /**
+     * Retry a failed or stopped run (`POST /retry`): a Task started with EMPTY input, so core
+     * sends the input of the turn that did not finish — held as carry-over since the run ended
+     * `fatal`, gave up reconnecting or was stopped by the user, with whatever the model had
+     * already written — and nothing else. No user message is published or recorded, and with no
+     * Prompt there is no user_prompt consult. Gated like startTask (busy is the same 409) but
+     * never queued, and refused with 409 `nothing_to_retry` when nothing is held — the user's
+     * next message already resent that input, or no run was cut short — since the run would end
+     * at once and the client would watch a Task start and stop with nothing sent. Not a person's
+     * input for company mode's hop accounting: the turn it resends was counted, or not, when
+     * it was first sent.
+     */
+    retryTask(sessionId: string): Promise<{
+        sessionId: string;
+    }>;
     /**
      * Start a goal run: like startTask, but the goal plugin composes the input and its stop
      * hook drives every later round inside this one `session.run` call — so the Session
@@ -1281,7 +1902,9 @@ declare class SessionManager {
      * Taps a goal run's stream for `drive`: round boundaries become goal_round events —
      * round 1 from the seeded input (core never yields a run's initial input, so it is
      * counted here, where startGoal published it), later rounds from the stop-hook continues
-     * core yields — and the goal hook's `stop` event becomes the
+     * core yields, each announced by the hook's `continue` event; a harness-stamped input
+     * nothing announced is another package's user_prompt context riding behind the
+     * objective, not a round — and the goal hook's `stop` event becomes the
      * goal_finished server event. `used` is what the hook last recorded in its event's
      * `output` — the same number its budget check used — so the UI never shows a different
      * figure. A stream that ends without the hook's terminal event (a cut-off run, an
@@ -1290,7 +1913,12 @@ declare class SessionManager {
     private goalStream;
     /** Closes a goal as aborted for the UI (stream cut off / infrastructure failure). */
     private finishAborted;
-    /** Shared task launch (fresh tasks and auto-started follow-ups): flips to running, publishes the input, and drives the run. Caller holds the session lock and has verified idle. */
+    /**
+     * Shared task launch (fresh tasks, auto-started follow-ups and retries): flips to running,
+     * publishes the input, and drives the run. Caller holds the session lock and has verified
+     * idle. A retry's input is empty: nothing is published or held, and drive gets no title
+     * material — the turn it resends already offered its text when it was first sent.
+     */
     private launchTask;
     /**
      * Auto-start of queued follow-ups: called from drive's finally whenever a Task or
@@ -1305,6 +1933,53 @@ declare class SessionManager {
     startCompact(sessionId: string): Promise<{
         sessionId: string;
     }>;
+    /**
+     * Switches the Session's model in place (`POST /switch-model`) — core `Session.switchModel`,
+     * gated like a compaction (open, not deleting, idle). Core decides everything before its
+     * first event, so the head of its stream is pulled here, under the lock, and tells the three
+     * outcomes apart:
+     *
+     * - it throws — a refusal, answered 409 with the code of its reason (see `switchRefusal`);
+     * - it is already done — a Session that never ran has no context to close: core re-assembled
+     *   its first context on the target, nothing streams, and the row carries the new pair by
+     *   the time this returns (`switched: true`; the route answers with the fresh DTO);
+     * - it yields — a driven run like a compaction (`switched: false`): status `compacting`,
+     *   idle when it ends. The head is a compaction's begin, the first record of a bootstrap (a
+     *   Session loaded from its Trace opens its context first), or — for a context with no
+     *   completed turn, which streams no pair — the opener's first record.
+     *
+     * The switch is the entry's run from that pull on — it can be stopped, and a deletion or a
+     * shutdown waits for it — while the entry only reads `compacting` once there is something
+     * to stream, so a refusal never flickers a state.
+     *
+     * The entry and the row follow the runtime as the new context's `session_meta` passes
+     * through the drive (see `drive`); a switch that does not complete streams no meta and
+     * leaves them where they were. Usage: a drive bills to the model it started on, so the
+     * switch's compaction request goes to the model that served it and the next run to the new
+     * one.
+     */
+    startSwitch(sessionId: string, ref: ModelRefDto): Promise<{
+        sessionId: string;
+        switched: boolean;
+    }>;
+    /** Who is told when a Session's model moves (see `onModelChanged`). */
+    private readonly modelListeners;
+    /**
+     * Subscribes to a Session's model moving: an in-session switch completing, or a row brought
+     * back in step with its Trace when the Session loads. The listener runs once the entry and
+     * the row carry the new pair. Returns the unsubscribe. Company mode listens: an employee's
+     * model is its desk Session's.
+     */
+    onModelChanged(listener: (sessionId: string, model: ModelRefDto) => void): () => void;
+    /**
+     * Moves the entry — and the row it caches into — to the model the runtime reports itself on,
+     * when that differs: the pair the next drive attributes usage to, and the one
+     * `GET /sessions/:id` describes. A runtime that reports none (test fakes) leaves the entry
+     * alone. The row write is guarded like the other bookkeeping writes (see `touchRow`): a
+     * switch must not be stranded mid-drive by a closed DB handle, and the entry is right either
+     * way. The same holds for whoever listens: a listener that throws is recorded, not rethrown.
+     */
+    private syncEntryModel;
     /** Submit an approval decision; returns false if the pending approval doesn't exist (already decided/unknown). */
     decideApproval(sessionId: string, toolCallId: string, decision: "allow" | "deny"): boolean;
     /**
@@ -1436,6 +2111,15 @@ declare class SessionManager {
      */
     beginSessionDeletion(sessionId: string): Promise<void>[];
     endSessionDeletion(sessionId: string): void;
+    /**
+     * The hand-over's half of a swap: this generation stops working on the state and leaves
+     * everything in it as it is — running Tasks keep running, pending approvals keep waiting —
+     * for the next generation to take over (PRFC-0015). Only what is this instance's own stops:
+     * the idle sweep. `shutdown` is the other ending, for a state nobody takes over.
+     */
+    detach(): void;
+    /** The Sessions with a Task in flight right now — what a swap parks, so that a successor that cannot take the state over knows which ones to start again. */
+    runningSessionIds(): string[];
     /** Graceful shutdown: reject new tasks (503), interrupt all active runs, and wait for them to finish (default ≤5s). */
     shutdown(timeoutMs?: number): Promise<void>;
     /**
@@ -1448,6 +2132,34 @@ declare class SessionManager {
      * tests and timers.
      */
     sweepIdle(now?: number, idleMs?: number): void;
+    /**
+     * Pins (`on`) or releases a Session's runtime entry against idle eviction (see sweepIdle).
+     * The messaging bridge holds the pin for as long as a binding's connection is enabled: that
+     * Session is where the bot lives on this server, and evicting it after half an hour of quiet
+     * makes the next chat message wait for a resume from the Trace before anything else happens.
+     *
+     * It pins only what is loaded and loads nothing itself (preload does). A stale id pins
+     * nothing: an entry a delete removed is gone from the table whatever this set says, and the
+     * bridge releases the id when its connection goes.
+     */
+    keepLoaded(sessionId: string, on: boolean): void;
+    /**
+     * Loads a Session's runtime into the active table ahead of its first Task, through the same
+     * get-or-resume path that Task would take, so the first message after a messaging connection
+     * comes up — an enable, a server restart — does not pay for a resume from the Trace on top of
+     * everything else. Only the load: no run starts, and the core bootstrap (session metadata,
+     * MCP connections) still happens on the first run. Under the Session lock, like startTask, so
+     * a Task arriving mid-load waits for this load instead of starting a second one.
+     *
+     * A Session that is gone or being deleted, alone or with its Agent, resolves quietly: there is
+     * nothing to warm and the caller has nothing to do about it. So does one with no Trace yet,
+     * because loading it is a self-heal REBUILD under a new session id — that would move the
+     * Session out from under the binding that asked, and earlier than any Task would. The row's
+     * `hasTrace` is a cache, so a row that has not caught up only misses the warm-up. Any other
+     * load failure rejects; the first Task meets the same failure and reports it where a person
+     * will see it.
+     */
+    preload(sessionId: string): Promise<void>;
     private assertOpen;
     /** The Agent owning this Session is being deleted → 409 (guards against directory recreation inside the deletion race window). */
     private assertAgentNotDeleting;
@@ -1455,6 +2167,7 @@ declare class SessionManager {
     private assertSessionNotDeleting;
     private assertIdle;
     private generationOf;
+    private refreshProviderCredentialIfNeeded;
     /** get-or-resume-or-heal: use directly on an active-table hit; otherwise load via the loader, updating the index's primary key on self-heal. */
     private ensureEntry;
     /**
@@ -1504,14 +2217,21 @@ declare class SessionManager {
      * row is gone as well.
      */
     private publishBackgroundTasks;
+    /**
+     * Publishes `session_approvals` on the user channel: how many tool calls of this Session wait
+     * for a person now. The Session's own stream carries the calls; this is what lets a list, or
+     * a host watching every Session of a Project, see which one waits without subscribing to each.
+     * Sent for an entry that is being disposed too, so a mark it had is cleared.
+     */
+    private publishApprovals;
     /** Serialize (mutually exclude) execution by sessionId; cleans up the lock-table entry once its chain drains (avoids unbounded growth). */
     private withLock;
 }
-declare const Sessions_base: (abstract new () => Pick<SessionManager, "steer" | "pendingApprovalCount" | "pendingFollowUpCount" | "statusOf" | "pendingApprovals" | "pendingSteeringOf" | "subagentsOf" | "sendToSubagent" | "abortSubagentRun" | "pendingFollowUpsOf" | "liveFragments" | "pendingInputs" | "pendingBootstrap" | "activeCountForAgent" | "invalidateAgentRuntimes" | "invalidateProjectRuntimes" | "assertCanAcceptTask" | "startTask" | "startGoal" | "startCompact" | "decideApproval" | "recallSteering" | "recallFollowUp" | "retryNow" | "abortTask" | "listProcesses" | "probeProcessServices" | "killProcess" | "removeProcess" | "abortProject" | "beginAgentDeletion" | "endAgentDeletion" | "beginSessionDeletion" | "endSessionDeletion" | "atIdleBoundary" | "shutdown" | "sweepIdle">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare const Sessions_base: (abstract new () => Pick<SessionManager, "steer" | "pendingApprovalCount" | "pendingFollowUpCount" | "statusOf" | "pendingApprovals" | "pendingSteeringOf" | "subagentsOf" | "sendToSubagent" | "abortSubagentRun" | "pendingFollowUpsOf" | "liveFragments" | "pendingInputs" | "pendingBootstrap" | "activeCountForAgent" | "invalidateAgentRuntimes" | "invalidateProjectRuntimes" | "assertCanAcceptTask" | "startTask" | "retryTask" | "startGoal" | "startCompact" | "startSwitch" | "onModelChanged" | "decideApproval" | "recallSteering" | "recallFollowUp" | "retryNow" | "abortTask" | "listProcesses" | "probeProcessServices" | "killProcess" | "removeProcess" | "abortProject" | "beginAgentDeletion" | "endAgentDeletion" | "beginSessionDeletion" | "endSessionDeletion" | "atIdleBoundary" | "shutdown" | "detach" | "runningSessionIds" | "sweepIdle" | "keepLoaded" | "preload">) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** The session runtime: one entry per live Session, task mutex, approvals, streaming. */
 declare abstract class Sessions extends Sessions_base {
 }
-declare const SessionServiceIface_base: (abstract new () => Pick<SessionService, "hasTrace" | "toInfo" | "listSessions" | "sessionStats" | "createSession" | "latestTracePath" | "adoptUnmanagedTraceSessions">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare const SessionServiceIface_base: (abstract new () => Pick<SessionService, "hasTrace" | "toInfo" | "listingOf" | "listSessions" | "archivedRows" | "sessionStats" | "createSession" | "defaultSandbox" | "pickSandbox" | "updateSandbox" | "latestTracePath" | "adoptUnmanagedTraceSessions">) & (<C>(target: C, context: ClassDecoratorContext) => C);
 declare abstract class SessionServiceIface extends SessionServiceIface_base {
 }
 
@@ -1586,42 +2306,40 @@ declare class AgentConfigService implements AgentConfig {
     updateVault(projectId: string, agentId: string, req: VaultUpdateRequest): Promise<VaultResponse>;
 }
 
-declare const AgentConfig_base: (abstract new () => {
-    exists(projectId: string, agentId: string): Promise<boolean>;
-    requireExists(projectId: string, agentId: string): Promise<void>;
-    readCardMeta(projectId: string, agentId: string): Promise<{
+/** AgentConfig: the mechanism AgentConfigService implements. */
+declare abstract class AgentConfig {
+    abstract exists(projectId: string, agentId: string): Promise<boolean>;
+    abstract requireExists(projectId: string, agentId: string): Promise<void>;
+    abstract readCardMeta(projectId: string, agentId: string): Promise<{
         name?: string;
         description?: string;
         toolCount: number;
         version: number;
         kernelOutdated: boolean;
     }>;
-    getConfig(projectId: string, agentId: string): Promise<AgentConfigView>;
-    updateConfig(projectId: string, agentId: string, req: AgentConfigUpdateRequest): Promise<void>;
-    resetConfig(projectId: string, agentId: string): Promise<void>;
-    kernelUpdate(projectId: string, agentId: string): Promise<AgentKernelUpdateResponse>;
-    insertTemplatePlaceholder(projectId: string, agentId: string, feature: "vault" | "skills" | "schedules"): Promise<AgentConfigView>;
-    getVault(projectId: string, agentId: string): Promise<VaultResponse>;
-    updateVault(projectId: string, agentId: string, req: VaultUpdateRequest): Promise<VaultResponse>;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
-/** AgentConfig: the mechanism AgentConfigService implements. */
-declare abstract class AgentConfig extends AgentConfig_base {
+    abstract getConfig(projectId: string, agentId: string): Promise<AgentConfigView>;
+    abstract updateConfig(projectId: string, agentId: string, req: AgentConfigUpdateRequest): Promise<void>;
+    abstract resetConfig(projectId: string, agentId: string): Promise<void>;
+    abstract kernelUpdate(projectId: string, agentId: string): Promise<AgentKernelUpdateResponse>;
+    abstract insertTemplatePlaceholder(projectId: string, agentId: string, feature: "vault" | "skills" | "schedules"): Promise<AgentConfigView>;
+    abstract getVault(projectId: string, agentId: string): Promise<VaultResponse>;
+    abstract updateVault(projectId: string, agentId: string, req: VaultUpdateRequest): Promise<VaultResponse>;
 }
-declare const AgentLifecycle_base: (abstract new () => {
-    listAgents(projectId: string): Promise<AgentListItem[]>;
-    deleteAgent(projectId: string, agentId: string): Promise<void>;
-    createAgent(projectId: string, agentId: string, name?: string, description?: string, skillNames?: readonly string[], directory?: {
+/** AgentLifecycle: the mechanism AgentService implements. */
+declare abstract class AgentLifecycle {
+    abstract listAgents(projectId: string): Promise<AgentListItem[]>;
+    /** Every id `createAgent` refuses as taken, as names only, including a folder that does not list. */
+    abstract takenAgentIds(projectId: string): Promise<string[]>;
+    abstract deleteAgent(projectId: string, agentId: string): Promise<void>;
+    abstract createAgent(projectId: string, agentId: string, name?: string, description?: string, skillNames?: readonly string[], directory?: {
         path: string;
         names: readonly string[];
     }, archive?: Buffer<ArrayBufferLike>): Promise<AgentListItem>;
-    pluginVersion(projectId: string, agentId: string, pluginName: string): Promise<{
+    abstract pluginVersion(projectId: string, agentId: string, pluginName: string): Promise<{
         installed: string | null;
         library: string | null;
     }>;
-    updatePlugin(projectId: string, agentId: string, pluginName: string): Promise<void>;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
-/** AgentLifecycle: the mechanism AgentService implements. */
-declare abstract class AgentLifecycle extends AgentLifecycle_base {
+    abstract updatePlugin(projectId: string, agentId: string, pluginName: string): Promise<void>;
 }
 
 interface AgentListItem {
@@ -1641,6 +2359,8 @@ interface AgentListItem {
     vaultKeyCount: number;
     /** Number of scheduled tasks (count of .toml files under schedule/, including invalid ones). */
     scheduleCount: number;
+    /** Workbench folders with a manifest, including ones with a load error. */
+    workbenchCount: number;
     /** Number of installed Skills (count of skills/<name>/ directories that contain a SKILL.md). */
     skillCount: number;
     /** Number of installed hook packages (hooks/<name>/ directories with a hooks.json). */
@@ -1658,6 +2378,14 @@ declare class AgentService implements AgentLifecycle {
     private readonly snapshots;
     /** Union of DB index ∪ directory scan; unmanaged directory Agents are backfilled into the DB. */
     listAgents(projectId: string): Promise<AgentListItem[]>;
+    /** Count installed folders without compiling or walking their UI/runtime assets. */
+    private workbenchCount;
+    /**
+     * Every id `createAgent` refuses as taken, as names only: the index rows and every entry under
+     * `agents/`. Unlike `listAgents`, this includes a folder with no `system_config.yaml`, and it
+     * opens no Agent.
+     */
+    takenAgentIds(projectId: string): Promise<string[]>;
     /** Number of vault keys (falls back to 0 on read failure). */
     private vaultKeyCount;
     /** Number of scheduled tasks: count of .toml files under schedule/ (0 if the directory doesn't exist). */
@@ -1665,7 +2393,9 @@ declare class AgentService implements AgentLifecycle {
     /**
      * One pass over `skills/` and one over `hooks/`, answering the card's questions: how many
      * skills and hook packages are installed, and which of them the plugin library has moved
-     * past — by plugin, since a plugin is what gets reinstalled to catch up.
+     * past — each part against the library's same part (a skill's dated version against that
+     * skill's, a hook package's against the plugin's `hooks.version`), reported by plugin, since
+     * a plugin is what gets reinstalled to catch up.
      *
      * Only the HEAD of each SKILL.md is read, and that bound is load-bearing rather than a
      * micro-optimization: a preinstalled library is ~180 KB of SKILL.md across seventeen files
@@ -1686,18 +2416,20 @@ declare class AgentService implements AgentLifecycle {
      */
     private installedPlugins;
     /**
-     * Where one library plugin stands on one Agent: `installed` is the OLDEST version among the
-     * plugin's installed skills and its installed hook package — the same "any component behind
-     * the library is an update" rule {@link installedPlugins} draws the list cards' hints from —
-     * and null when the Agent carries none of them; `library` is the version the library offers
-     * now, null when the library has no such plugin. Only the head of each SKILL.md is read
-     * (see SKILL_HEAD_BYTES), so the answer costs one small read per skill the plugin ships.
+     * Where one library plugin stands on one Agent, as one pair of dated versions of the same
+     * part — so `library` newer than `installed` is exactly "some part is behind", the rule
+     * {@link installedPlugins} draws the list cards' hints from. Each part the Agent carries (a
+     * skill, the hook package) is paired with the library's same part; among the parts that are
+     * behind — or, when none is, among all of them — the one with the OLDEST installed version
+     * answers. `installed` is null when the Agent carries none of the plugin's parts, with
+     * `library` then the plugin's content version; both are null when the library has no such
+     * plugin. Only the head of each SKILL.md is read (see SKILL_HEAD_BYTES), so the answer costs
+     * one small read per skill the plugin ships.
      *
      * The organization runtime asks this per employee per pass to keep company plugins current.
      * A skill the Agent does not carry — never installed, or removed by hand — counts for
-     * nothing: what is compared is the oldest version the Agent actually has, so a plugin whose
-     * skills are all current reads as current even where one of them is missing. Restoring a
-     * deleted skill is the Agents page's business, not a pass's.
+     * nothing: a plugin whose carried skills are all current reads as current even where one of
+     * them is missing. Restoring a deleted skill is the Agents page's business, not a pass's.
      */
     pluginVersion(projectId: string, agentId: string, pluginName: string): Promise<{
         installed: string | null;
@@ -1748,13 +2480,14 @@ declare class AgentService implements AgentLifecycle {
     }, archive?: Buffer): Promise<AgentListItem>;
 }
 
-declare const MessagingBindings_base: (abstract new () => {
-    find(sessionId: string, channel: string): MessagingBindingRow | null;
-    findEnabled(sessionId: string): MessagingBindingRow | null;
-    listForSession(sessionId: string): MessagingBindingRow[];
-    findEnabledByAccount(channel: string, accountId: string): MessagingBindingRow | null;
-    listAll(): MessagingBindingRow[];
-    upsert(args: {
+/** MessagingBindings: the mechanism MessagingBindingsRepo implements. */
+declare abstract class MessagingBindings {
+    abstract find(sessionId: string, channel: string): MessagingBindingRow | null;
+    abstract findEnabled(sessionId: string): MessagingBindingRow | null;
+    abstract listForSession(sessionId: string): MessagingBindingRow[];
+    abstract findEnabledByAccount(channel: string, accountId: string): MessagingBindingRow | null;
+    abstract listAll(): MessagingBindingRow[];
+    abstract upsert(args: {
         sessionId: string;
         channel: string;
         accountId: string;
@@ -1763,14 +2496,11 @@ declare const MessagingBindings_base: (abstract new () => {
         finalReplyOnly?: boolean;
         renderMarkdown?: boolean;
     }): MessagingBindingRow;
-    setEnabled(sessionId: string, channel: string, enabled: boolean): void;
-    recordChat(sessionId: string, channel: string, chatId: string, isDirect: boolean): void;
-    recordInboundWatermark(sessionId: string, channel: string, messageId: string | null): void;
-    delete(sessionId: string, channel: string): void;
-    deleteSession(sessionId: string): void;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
-/** MessagingBindings: the mechanism MessagingBindingsRepo implements. */
-declare abstract class MessagingBindings extends MessagingBindings_base {
+    abstract setEnabled(sessionId: string, channel: string, enabled: boolean): void;
+    abstract recordChat(sessionId: string, channel: string, chatId: string, isDirect: boolean): void;
+    abstract recordInboundWatermark(sessionId: string, channel: string, messageId: string | null): void;
+    abstract delete(sessionId: string, channel: string): void;
+    abstract deleteSession(sessionId: string): void;
 }
 
 interface MessagingBindingRow {
@@ -1846,8 +2576,7 @@ interface MessagingBindingRow {
  * every connector method validates its own shape and throws a readable error on a
  * malformed one — the bridge treats that like any other channel failure.
  */
-/** Known messaging channels (the DB stores the discriminator as text; unknown values are skipped defensively). */
-type MessagingChannel = "feishu" | "telegram" | "qq" | "wechat";
+
 /** One inbound image's bytes, once fetched, with the MIME type the bridge needs for its data URL. */
 interface MessagingInboundImageData {
     data: Buffer;
@@ -1957,8 +2686,25 @@ interface MessagingConnectorHandlers {
     onMessage(msg: MessagingInboundMessage): void | Promise<void>;
     /** The connection completed a handshake (may fire again after an automatic reconnect). */
     onReady?(): void;
-    /** The connection failed and the channel gave up (or the initial connect failed). */
+    /**
+     * The connection failed and the channel gave up (or the initial connect failed). A
+     * {@link MessagingChannelError} says whether the outage clears without anyone acting.
+     */
     onError?(err: unknown): void;
+    /**
+     * The connection's account started or stopped holding replies it could not deliver yet
+     * (see {@link MessagingReplyHeldError}): the ISO time since which it holds some, or null once
+     * it holds none. Fired on every change, and once at connect for a backlog held from before.
+     * Only a channel that holds replies (WeChat) ever calls it.
+     */
+    onHeldChange?(since: string | null): void;
+    /**
+     * A send the connector made on its OWN — a withheld tail flushed after the quiet period, held
+     * replies delivered on the next inbound message — failed for good. No caller is waiting on
+     * those sends, so this is the only way their failure reaches the binding's status and the
+     * error table.
+     */
+    onSendFailed?(err: unknown): void;
 }
 /** A live inbound event stream; `close` ends it (idempotent). */
 interface MessagingConnection {
@@ -2020,6 +2766,13 @@ interface MessagingSendOptions {
      * reach the one message a user sends to check whether the binding works at all.
      */
     markdown?: boolean;
+    /**
+     * This send is a probe of the outbound leg ("send test message"), not a reply. A connector
+     * that would HOLD a refused message for later delivery must throw
+     * {@link MessagingNeedsRecentMessageError} instead: a held probe that arrives an hour later
+     * proves nothing, and the person pressing the button needs to hear why it did not arrive now.
+     */
+    probe?: boolean;
 }
 /** Outbound half of one bound account. Every method throws on failure with a readable reason. */
 interface MessagingClient {
@@ -2071,7 +2824,8 @@ interface MessagingChannelConnector {
  * applies to every route behind this middleware, SSE endpoints included (the CLI
  * consumes SSE via fetch with headers). A Bearer header that does not match fails the
  * request rather than falling back to the cookie: silently downgrading a wrong explicit
- * credential would mask misconfiguration.
+ * credential would mask misconfiguration. A few writes refuse the token all the same and take a
+ * person's sign-in (requireHuman).
  *
  * Accessing a protected API while logged out -> 401 `{error:{code:"unauthorized"}}`.
  * CSRF: SameSite=Lax plus a Content-Type an HTML form cannot forge (see jsonOnlyWrites).
@@ -2104,6 +2858,16 @@ interface MessagingTaskRunnerShape {
         sessionId: string;
         queued: boolean;
     }>;
+    /**
+     * Pins the Session's runtime against idle eviction while a connection is enabled (`on`), or
+     * releases the pin.
+     */
+    keepLoaded(sessionId: string, on: boolean): void;
+    /**
+     * Loads the Session's runtime ahead of its first message, starting nothing; resolves quietly
+     * for a Session that is gone or being deleted.
+     */
+    preload(sessionId: string): Promise<void>;
 }
 /**
  * Minimal dependency on the sessions index: existence checks for reconcile/cascade, the
@@ -2293,6 +3057,14 @@ declare class MessagingBridge {
      * the log, which is where "the replies moved to General a while ago" is answerable at all.
      */
     private noteSend;
+    /** The connector's `onHeldChange`, behind the stale-entry guard every connector callback has. */
+    private setHeldReplySince;
+    /**
+     * Whether a send's failure is the connector HOLDING the reply rather than losing it (see
+     * MessagingReplyHeldError). Such a send is not a delivery failure — no error record, no
+     * `lastDeliveryError` — and is logged once per holding episode, not once per message.
+     */
+    private wasHeld;
     private clientFor;
     /**
      * Has this binding already processed this message? A duplicate is a complete no-op —
@@ -2470,9 +3242,12 @@ declare class MessagingBridge {
      * A file the run did not write is dropped SILENTLY, and so is a name matching no file at
      * all: the rule reads prose, so a reply that mentions the config it read — or describes a
      * `hello-world.md` it never wrote — is the ordinary case, and announcing those puts an
-     * error-shaped line under correct answers. Both are logged instead. What IS named in the
-     * chat is a file that exists and whose upload failed: there the reply promised something
-     * that then did not arrive, which is the one case where silence reads as broken.
+     * error-shaped line under correct answers. Both are logged instead. What IS recorded is a
+     * file that exists and still did not go out — over a ceiling, past the count cap, or
+     * refused on the way: the reply promised something that then did not arrive, so it is filed
+     * under the Session's Project, once the batch is done, in one record per cause naming every
+     * file it held back (see messagingFilesNotSentRecords). None of it is posted into the chat,
+     * which carries the reply and its files and nothing about the ones that stayed behind.
      *
      * Always plain sends, never a threaded reply: a run that mentions a file has by
      * definition already sent the text that mentions it, and that message took the group's
@@ -2481,19 +3256,11 @@ declare class MessagingBridge {
      */
     private deliverFiles;
     /**
-     * Names one file that did not make it, in the chat.
-     *
-     * Every other way a file does not arrive is already visible there — over the byte cap,
-     * past the count cap, an inbound refusal. A failed upload reached `error_records` alone,
-     * which the person in the chat cannot open, so the feature just looked broken. A missing
-     * permission gets its own wording: it is the one failure they can fix themselves, in
-     * about ten seconds, given the scope name and the console link.
-     *
-     * Its own try/catch: a chat that will not take the notice must not take the rest of the
-     * batch down with it, and the upload failure behind it is already recorded.
+     * One mirrored file: read under the outer ceiling, then sent as a picture or an attachment.
+     * Resolves null once the file went out. A file over the ceiling for its kind is not sent and
+     * resolves to that ceiling instead; a read or a send the channel refused throws. The caller
+     * records both (see messagingFilesNotSentRecords).
      */
-    private noteFileFailure;
-    /** One mirrored file: read under the outer ceiling, then sent as a picture or an attachment. */
     private deliverOneFile;
     /** One-line notice (approval waiting) to the last known chat; silent before one exists. */
     private deliverNotice;
@@ -2521,7 +3288,7 @@ declare const MessagingTaskRunner_base: (abstract new () => MessagingTaskRunnerS
 /** What the bridge needs of the session runtime — declared at the consumer. */
 declare abstract class MessagingTaskRunner extends MessagingTaskRunner_base {
 }
-declare const Messaging_base: (abstract new () => Pick<MessagingBridge, "start" | "stop" | "statusOf" | "sync" | "unbind" | "unbindSession" | "testCredentials" | "sendTestMessage">) & (<C>(target: C, context: ClassDecoratorContext) => C);
+declare const Messaging_base: (abstract new () => Pick<MessagingBridge, "stop" | "sync" | "start" | "statusOf" | "unbind" | "unbindSession" | "testCredentials" | "sendTestMessage">) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /** The chat-channel bridge: bindings, delivery, status. */
 declare abstract class Messaging extends Messaging_base {
 }
@@ -2532,21 +3299,42 @@ interface MessagingSlots {
     }, MessagingChannelConnector>;
 }
 
-declare const Http_base: (abstract new () => {
-    fetch(request: Opaque<"Request", Request>): Promise<Opaque<"Response", Response>>;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
+/** A settings group as a module declares it: a configuration, and where the page draws it. */
+interface SettingsGroupDecl extends PluginConfiguration {
+    /** Another group's name (its contribution id): this one is drawn inside that card and saved with it. */
+    parent?: string;
+    /** Position among the groups: lower first (absent = 100), then declaration order. */
+    order?: number;
+}
+/** What a module reads: the group it declared, and a watch on it. */
+declare abstract class PluginConfig {
+    /** The stored values merged onto the declared defaults; `{}` for a name no group answers to. */
+    abstract get(name: string): Record<string, unknown>;
+    /** Fires with the new document after every save of `name`; returns the unsubscribe. */
+    abstract watch(name: string, cb: (values: Record<string, unknown>) => void): () => void;
+    /** Whether anything was ever saved under `name` — what tells a default from a choice. */
+    abstract saved(name: string): boolean;
+    /** The configuration `name` was declared with (what `resolveTable` reads a table by); undefined for none. */
+    abstract schema(name: string): PluginConfiguration | undefined;
+}
+interface PluginConfigSlots {
+    /** A settings group, as data: its id is its name, the data its configuration. */
+    groups: Slot<SettingsGroupDecl>;
+}
+
 /** The assembled business surface: one request in, one response (or a decline) out. */
-declare abstract class Http extends Http_base {
+declare abstract class Http {
+    abstract fetch(request: Opaque<"Request", Request>): Promise<Opaque<"Response", Response>>;
 }
 interface HttpSlots {
     /**
-     * A route group. `auth: "user"` mounts it behind the cookie gate, `"none"` in front of
-     * it; `order` is the mount position (a stable number, since Hono matches in order). The
-     * code half is the group's Hono app.
+     * A route group. `auth: "user"` accepts a cookie or the local API token; `"token"` accepts
+     * only the local API token, without renewing cookies; `"none"` is public. `order` is the
+     * mount position (a stable number, since Hono matches in order). The code half is the Hono app.
      */
     routes: Slot<{
         prefix: string;
-        auth: "user" | "none";
+        auth: "user" | "token" | "none";
         order: number;
     }, Opaque<"Hono", Hono<AppEnv>>>;
 }
@@ -2557,10 +3345,6 @@ interface HttpSlots {
  * own module.json and renders what it has a renderer for.
  */
 
-declare const WebShell_base: (abstract new () => {
-    /** Every contribution to the web slots, by slot, in module order. */
-    contributions(): ContributionsResponse;
-}) & (<C>(target: C, context: ClassDecoratorContext) => C);
 /**
  * The frontend's slots, declared on the SERVER so a server module (or a plugin) can
  * contribute a page, an Agent settings tab or a Session tab as manifest data. The web
@@ -2568,7 +3352,9 @@ declare const WebShell_base: (abstract new () => {
  * renderer it knows: a `builtin` name from its own registry, or an `iframe`. No code
  * crosses this boundary — only data.
  */
-declare abstract class WebShell extends WebShell_base {
+declare abstract class WebShell {
+    /** Every contribution to the web slots, by slot, in module order. */
+    abstract contributions(): ContributionsResponse;
 }
 interface WebShellSlots {
     /** A page: its route, whether it sits in the main nav, whether it is admin-only. */
@@ -2585,11 +3371,22 @@ interface WebShellSlots {
         order: number;
         renderer: RendererRef;
     };
-    /** A tab beside a Session's chat (a workflow UI lives here). */
+    /**
+     * A tab beside a Session's chat. A workbench contributes here too, from its own tree, where
+     * the host publishes this slot under this module's name and scopes the tab to its Agent.
+     */
     sessionTabs: {
         key: string;
-        renderer: RendererRef;
+        title: string;
+        titleZh?: string;
+        renderer: {
+            builtin: string;
+        } | {
+            iframe: {
+                src: string;
+            };
+        };
     };
 }
 
-export { AgentConfigService, AgentService, Http, type HttpSlots, Messaging, type MessagingSlots, Sandbox, type SandboxSlots, SessionServiceIface, Sessions, Terminals, WebShell, type WebShellSlots };
+export { AgentConfigService, AgentService, Http, type HttpSlots, Messaging, type MessagingSlots, PluginConfig, type PluginConfigSlots, PluginConfiguration, Sandbox, type SandboxSlots, SessionServiceIface, Sessions, type SettingsGroupDecl, Terminals, WebShell, type WebShellSlots };