@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/api/tools-router.js

@@ -1,4 +1,3 @@
-/** Skills, memory, prompts, commands, notes, insights, logs, health, MCP, plugins, updates, diagnostics (Python `api/routes.py` handlers of the same paths). */
 import { implement } from '@orpc/server';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
@@ -6,19 +5,32 @@ import { toolsContract } from '@maudecode/talaria-web-contracts';
 import { HttpError, requireFields } from './router.js';
 import { requestSessionIdGuard } from './session-visibility.js';
 import { activeProfileName, ensureTrustedAuthSession, sessionCanManageServer } from '../auth/gate.js';
-import { HttpFailure } from '../sessions/service.js';
+import { currentChatReadiness, HttpFailure } from '../sessions/service.js';
 import { SessionNotFound } from '../sessions/store.js';
 import { insightsSessionRows } from '../sessions/state-db.js';
 import { ConfigUnavailable } from '../config/agent-config.js';
 import { SidecarError } from '../sidecar/client.js';
 import { createPrompt, deletePrompt, externalNotesEnabled, loadPrompts, readMemory, writeMemory } from '../tools/memory.js';
-import { notesSources } from '../tools/mcp.js';
+import { JoplinError, joplinNote, joplinSearch, notesSources } from '../tools/mcp.js';
+import { catalogNames, connectorOperation, connectorsPage, connectorTools, rememberCatalogNames } from '../tools/connectors.js';
+import { resolveWikiLocation, wikiPages } from '../tools/wiki.js';
 import { buildInsights } from '../tools/insights.js';
-import { commandCatalog } from '../tools/commands.js';
-import { agentHealth, dashboardStatus, readLogTail, systemHealth } from '../tools/health.js';
+import { commandCatalog, SESSION_EXEC_COMMANDS } from '../tools/commands.js';
+import { spokenText } from './tools-raw.js';
+import { agentHealth, applyDashboardConfig, dashboardConfig, dashboardStatus, gatewayStatus, parseDashboardConfig, readLogTail, remoteGatewayBaseUrl, systemHealth } from '../tools/health.js';
+import { restartGateway } from '../tools/gateway-restart.js';
+import { projectOsDashboard } from '../tools/project-os.js';
+import { PluginSettingsInvalid, planPluginSettings, pluginSettingsView, serializePluginSettingsSave } from '../tools/plugin-settings.js';
+import { credentialShadowed, RuntimeCredentialError, writeRuntimeCredential } from '../providers/runtime-env.js';
+import { EnvWriteError, loadEnvFile } from '../providers/env-file.js';
+import { loadGatewaySessionIdentityMap } from '../sessions/list.js';
+import { gitBadge } from '../workspace/git.js';
+import { sanitizeError } from '../workspace/media.js';
 import { normalizeChannel, updatesCheckView } from '../tools/updates.js';
 import { pyBool } from '../settings.js';
 import { str } from '../util.js';
+import { redactString } from '../redact.js';
+import { GATEWAY_RESTART_NOW } from '../tools/update-notifications.js';
 const os = implement(toolsContract).$context().use(requestSessionIdGuard);
 function failure(error) {
     if (error instanceof HttpError)
@@ -43,6 +55,128 @@ async function run(fn) {
     }
 }
 const home = (ctx) => ctx.deps.profileHome(activeProfileName(ctx));
+/** Profile homes with an `stt.warm` in flight (TAL-916). */
+const warmingHomes = new Set();
+function runningSidecar(ctx) {
+    const sidecar = ctx.deps.sidecar();
+    if (!sidecar)
+        throw new HttpError(503, 'Hermes Agent sidecar is not running');
+    return sidecar;
+}
+/** A slash command's sidecar failure: `notFound` is 404, bad input 400, the rest as `failure` maps them. */
+function commandFailure(error, notFound, message) {
+    if (error instanceof SidecarError && error.condition === notFound)
+        throw new HttpError(404, message);
+    if (error instanceof SidecarError && (error.condition === 'invalid_params' || error.code === -32602))
+        throw new HttpError(400, error.message);
+    return failure(error);
+}
+/** TAL-820: several profiles have third-party plugins and one of them loads its plugins into the shared sidecar process. */
+async function pluginIsolationAdvisory(ctx) {
+    if (ctx.deps.isolatedProfileMode())
+        return false;
+    const { profiles } = await runningSidecar(ctx).call('plugins.isolation', { base_home: ctx.deps.profileHome('default') });
+    const withPlugins = profiles.filter((profile) => profile.third_party_plugins > 0);
+    return withPlugins.length > 1 && withPlugins.some((profile) => profile.isolation === 'in_process');
+}
+/** TAL-806: the active profile's plugins that declare settings; none on an Agent without the settings module. */
+async function pluginSettingsList(ctx) {
+    const result = await runningSidecar(ctx).call('plugins.settings', { profile_home: home(ctx) });
+    return result.plugins.map((entry) => ({ key: entry.key, fields: pluginSettingsFieldsView(ctx, entry.fields) }));
+}
+const pluginSettingsFieldsView = (ctx, fields) => {
+    const rootProfile = ctx.deps.isRootProfile(activeProfileName(ctx));
+    return pluginSettingsView(fields, (envVar) => credentialShadowed(ctx.deps.config.env, rootProfile, envVar));
+};
+/** A refusal that proves nothing was written; a timeout or a sidecar exit leaves the outcome unknown. */
+const definitiveRefusal = (error) => error instanceof SidecarError ? ['plugin_settings_managed', 'plugin_settings_changed', 'plugin_not_found'].includes(error.condition) || error.code === -32602
+    : error instanceof EnvWriteError ? error.condition !== 'sidecar_unavailable'
+        : error instanceof RuntimeCredentialError;
+/** TAL-818: a sidecar `connectors.*` condition as the HTTP status the contract names; the body's `code` is the condition. */
+const CONNECTOR_STATUS = {
+    connectors_unavailable: 404, connector_not_found: 404, connection_not_found: 404, operation_not_found: 404,
+    connectors_sign_in: 403, connectors_forbidden: 403, policy_invalid: 400, connectors_failed: 502,
+    policy_conflict: 409, connectors_org_required: 409, operation_settled: 409, operation_refused: 409,
+};
+async function connectorCall(ctx, method, params) {
+    try {
+        // A connect waits up to 31 s for its link; every portal request inside a call is bounded at 30 s.
+        return await runningSidecar(ctx).call(method, { ...params, profile_home: home(ctx) }, { timeoutMs: 90_000 });
+    }
+    catch (error) {
+        const status = error instanceof SidecarError ? CONNECTOR_STATUS[error.condition] : undefined;
+        if (status !== undefined)
+            throw new HttpError(status, error.message, { code: error.condition });
+        if (error instanceof SidecarError && error.code === -32602)
+            throw new HttpError(400, error.message);
+        throw error;
+    }
+}
+/** The catalog's app names for the active profile: the last page read's, else one catalog read; none when it fails. */
+async function connectorNames(ctx) {
+    return catalogNames(home(ctx)) ?? await connectorCall(ctx, 'connectors.catalog', {}).then((r) => rememberCatalogNames(home(ctx), r.connectors), () => ({}));
+}
+/** An operation as the contract shows it, with the apps' catalog names. */
+const operationView = async (ctx, snapshot) => connectorOperation(snapshot, await connectorNames(ctx));
+/** The rules, or why they cannot be read (a portal refusal or failure): the page then fails closed and says why. */
+const connectorPolicy = (ctx) => connectorCall(ctx, 'connectors.policy.get', {}).then((policy) => ({ policy, error: null }), (error) => { if (error instanceof HttpError)
+    return { policy: null, error: error.message }; throw error; });
+const health = (ctx) => agentHealth({ env: ctx.deps.config.env, hermesHome: ctx.deps.config.hermesHome, profileHome: () => home(ctx), fetch: () => ctx.deps.fetch, now: ctx.deps.nowSeconds });
+/**
+ * TAL-805: the active profile's gateway mode from sidecar `gateway.mode`; null for a remote gateway. A named profile never
+ * borrows the root's health: when the sidecar cannot answer, it reads `stopped`, while the root profile reads null and keeps
+ * its health. The root profile's gateway in another container (`health` alive from its fresh runtime status) is invisible
+ * to the sidecar's process checks, so it stays `own`.
+ */
+async function gatewayMode(ctx, health) {
+    if (remoteGatewayBaseUrl(ctx.deps.config.env) !== null)
+        return null;
+    const sidecar = ctx.deps.sidecar();
+    const name = activeProfileName(ctx);
+    const isDefault = ctx.deps.isRootProfile(name);
+    let mode = null;
+    try {
+        if (sidecar)
+            mode = (await sidecar.call('gateway.mode', { profile_home: home(ctx), name, is_default: isDefault }, { timeoutMs: 10_000 })).gateway_mode;
+    }
+    catch {
+        mode = null;
+    }
+    if (mode === null)
+        return isDefault ? null : 'stopped';
+    return mode === 'stopped' && isDefault && health.alive === true ? 'own' : mode;
+}
+/** Python `_gateway_status_payload` for the active profile. */
+async function currentGatewayStatus(ctx) {
+    const sessionsPath = join(home(ctx), 'sessions', 'sessions.json');
+    const probe = await health(ctx);
+    return gatewayStatus(probe, loadGatewaySessionIdentityMap(sessionsPath), sessionsPath, await gatewayMode(ctx, probe));
+}
+const GATEWAY_ACTION_TIMEOUT_S = 60;
+/** Python `_handle_gateway_lifecycle` through sidecar `gateway.control`: 409 busy, 504 timeout, 500 failure; only the Agent's first error line (`reason`) leaves the server, never its CLI output (TAL-884). */
+async function gatewayAction(ctx, action) {
+    const sidecar = ctx.deps.sidecar();
+    if (!sidecar)
+        throw new HttpError(500, 'Hermes Agent sidecar is not running', { ok: false, action });
+    let outcome;
+    try {
+        outcome = await sidecar.call('gateway.control', { profile_home: home(ctx), action, background_wait_seconds: GATEWAY_ACTION_TIMEOUT_S }, { timeoutMs: 300_000 });
+    }
+    catch (error) {
+        throw new HttpError(500, sanitizeError(error), { ok: false, action });
+    }
+    if (outcome.status === 'busy')
+        throw new HttpError(409, 'Another gateway action is already in progress; try again shortly.', { ok: false, action });
+    if (outcome.timed_out)
+        throw new HttpError(504, `Gateway ${action} timed out after ${String(GATEWAY_ACTION_TIMEOUT_S)} seconds`, { ok: false, action });
+    if (outcome.status === 'failed' && outcome.returncode !== undefined) {
+        const error = outcome.reason ? `Gateway ${action} failed: ${outcome.reason}` : `Gateway ${action} failed with exit code ${String(outcome.returncode)}`;
+        throw new HttpError(500, error, { ok: false, action, returncode: outcome.returncode });
+    }
+    if (outcome.status === 'failed')
+        throw new HttpError(500, outcome.message, { ok: false, action });
+    return { ok: true, action, message: `Gateway ${action} completed.`, status: await currentGatewayStatus(ctx) };
+}
 const principalHash = (...parts) => createHash('sha256').update(JSON.stringify(parts), 'utf8').digest('hex');
 export function updateNotificationOwner(session) {
     const authType = str(session?.auth_type).trim();
@@ -67,39 +201,54 @@ async function updateNotificationScope(ctx, tab) {
         tab: tab ?? null,
     };
 }
-async function applyWithNotification(ctx, target, apply, confirmed = false, tab) {
-    const scope = await updateNotificationScope(ctx, tab);
+async function applyWithNotification(ctx, input, action) {
+    const target = updateTarget(input.target);
+    const confirmed = input.confirmed_agent_revision !== undefined || input.agent_refresh_token !== undefined;
+    const scope = await updateNotificationScope(ctx, input.tab_id);
     const active = ctx.deps.updateNotifications.activeUpdate(scope, target);
     if (active)
-        ctx.deps.updateNotifications.watch(scope, active.id);
+        (await ctx.deps.updateNotifications.watch(scope, active.id));
     if (active && (active.phase === 'applying' || active.phase === 'restarting')) {
         return { ok: false, status: 'already_in_progress', message: 'Update already in progress', notification_id: active.id };
     }
-    const notification = active ?? ctx.deps.updateNotifications.begin(scope, target);
+    const notification = active ?? (await ctx.deps.updateNotifications.begin(scope, target));
     if (active?.phase === 'awaiting_confirmation' && confirmed)
-        ctx.deps.updateNotifications.transition(notification.id, 'applying');
+        (await ctx.deps.updateNotifications.transition(notification.id, 'applying'));
     try {
-        const result = await apply();
+        const options = { agentChannel: input.agent_channel, confirmedRevision: input.confirmed_agent_revision, version: input.version, refreshToken: input.agent_refresh_token, mutationIntent: principalHash(scope.owner, scope.profile, notification.id) };
+        const result = action === 'apply' ? await ctx.deps.updates.apply(target, bodyChannel(input.channel), () => true, options)
+            : action === 'force' ? await ctx.deps.updates.force(target, bodyChannel(input.channel), options)
+                : await ctx.deps.updates.clearLock(target, options);
         const verifiedIdentity = typeof result.verified_revision === 'string'
             ? { revision: result.verified_revision, version: typeof result.verified_version === 'string' ? result.verified_version : null }
             : undefined;
         if (result.confirmation_required === true)
-            ctx.deps.updateNotifications.transition(notification.id, 'awaiting_confirmation', null, verifiedIdentity);
+            (await ctx.deps.updateNotifications.transition(notification.id, 'awaiting_confirmation', null, verifiedIdentity, result.message));
         else if (result.restart_blocked === true)
-            ctx.deps.updateNotifications.transition(notification.id, 'blocked', null, verifiedIdentity, result.message);
+            (await ctx.deps.updateNotifications.transition(notification.id, 'blocked', null, verifiedIdentity, result.message));
         else if (result.ok !== true)
-            ctx.deps.updateNotifications.transition(notification.id, 'failed', null, verifiedIdentity, result.message || result.error);
+            (await ctx.deps.updateNotifications.transition(notification.id, 'failed', null, verifiedIdentity, result.message || result.error));
         else if (target === 'webui' && result.restart_scheduled === true) {
-            ctx.deps.updateNotifications.transition(notification.id, 'restarting', str(result.sourceRevision || result.candidate_revision), verifiedIdentity);
+            await ctx.deps.updateNotifications.transition(notification.id, 'restarting', str(result.sourceRevision || result.candidate_revision), verifiedIdentity);
+        }
+        else if (result.gateway_restart === 'waiting_for_idle' || (target === 'agent' && ctx.deps.gatewayRestarts.pendingId() !== null)) {
+            // TAL-953: the gateway restarts once its own work drains. A restart already waiting covers this update too, and a
+            // repeated request that found the Agent current follows that wait rather than reporting success before it.
+            const detail = result.stash_conflict === true ? str(result.message) : null;
+            await ctx.deps.updateNotifications.transition(notification.id, 'waiting_for_idle', null, verifiedIdentity, detail);
+            const pending = (await ctx.deps.gatewayRestarts.schedule(notification.id, scope.profile, detail));
+            if (pending !== notification.id)
+                (await ctx.deps.updateNotifications.watch(scope, pending));
+            return { ...result, notification_id: pending };
         }
         else {
             // A kept Agent stash needs the user's attention; its recovery commands ride on the success record.
-            ctx.deps.updateNotifications.transition(notification.id, 'succeeded', null, verifiedIdentity, result.stash_conflict === true ? result.message : undefined);
+            await ctx.deps.updateNotifications.transition(notification.id, 'succeeded', null, verifiedIdentity, result.stash_conflict === true ? result.message : undefined);
         }
         return { ...result, notification_id: notification.id };
     }
     catch (error) {
-        ctx.deps.updateNotifications.transition(notification.id, 'failed', null, undefined, error instanceof Error ? error.message : null);
+        await ctx.deps.updateNotifications.transition(notification.id, 'failed', null, undefined, error instanceof Error ? error.message : null);
         throw error;
     }
 }
@@ -177,10 +326,10 @@ export function sanitizeClientEvent(payload) {
         out.event = 'unknown';
     return out;
 }
-function memoryWorkspace(ctx, sessionId, workspace) {
+async function memoryWorkspace(ctx, sessionId, workspace) {
     if (sessionId) {
         try {
-            const session = ctx.deps.sessionStore.get(sessionId, { metadataOnly: true });
+            const session = (await ctx.deps.sessionStore.get(sessionId, { metadataOnly: true }));
             if (!ctx.deps.workspaces.profileSupportsLocalIo(session.profile))
                 return null;
             const ws = str(session.workspace).trim();
@@ -193,17 +342,49 @@ function memoryWorkspace(ctx, sessionId, workspace) {
     const profile = activeProfileName(ctx);
     if (!ctx.deps.workspaces.profileSupportsLocalIo(profile))
         return null;
-    const raw = workspace || (ctx.deps.config.env.TERMINAL_CWD ?? '') || ctx.deps.workspaces.lastWorkspace(profile);
+    const raw = workspace || (ctx.deps.config.env.TERMINAL_CWD ?? '') || (await ctx.deps.workspaces.lastWorkspace(profile));
     if (!raw)
         return null;
     try {
-        return ctx.deps.workspaces.resolveTrusted(raw, profile);
+        return (await ctx.deps.workspaces.resolveTrusted(raw, profile));
     }
     catch {
         return null;
     }
 }
+/** The external notes drawer's Joplin access; 404 while the drawer is disabled. */
+async function joplinDeps(ctx, disabled) {
+    const config = await ctx.deps.agentConfig.read(home(ctx));
+    if (!externalNotesEnabled(ctx.deps.config.env, config))
+        throw new HttpError(404, 'External notes sources are disabled.', { source: 'disabled', ...disabled });
+    return { config, env: ctx.deps.config.env, fetch: ctx.deps.fetch, redact: ctx.deps.sessions.deps.redactEnabled() };
+}
+/** A Joplin failure answers 502 with its fixed message. */
+async function joplin(extra, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof JoplinError)
+            throw new HttpError(502, error.message, { source: 'joplin', ...extra });
+        throw error;
+    }
+}
+/** Python `int(limit or 20)`, falling back to 20 for anything unparseable or zero. */
+const notesLimit = (raw) => (/^\s*[+-]?\d+\s*$/.test(raw ?? '') ? Number.parseInt(String(raw).trim(), 10) : 0) || 20;
+/** The wiki root for the active profile; an unreadable config.yaml falls through to the default. */
+async function wikiLocation(ctx) {
+    const profileHome = home(ctx);
+    const config = await ctx.deps.agentConfig.read(profileHome).catch(() => ({}));
+    return resolveWikiLocation(ctx.deps.config.env, profileHome, config, ctx.deps.config.homeDir);
+}
+/** TAL-819: the Agent's review handler per write; its message can quote the entry text an approval replaced or removed. */
+async function reviewPendingWrites(ctx, verb, input) {
+    const { results } = await runningSidecar(ctx).call(`write_approval.${verb}`, { profile_home: home(ctx), kind: input.kind, writes: input.writes });
+    return { results: results.map((r) => ({ ...r, message: redactString(r.message, ctx.deps.sessions.deps.redactEnabled()) })) };
+}
 export const toolsRouter = os.router({
+    toolsetsCatalog: os.toolsetsCatalog.handler(({ input, context: { ctx } }) => run(() => runningSidecar(ctx).call('toolsets.catalog', { profile_home: home(ctx), enabled_toolsets: input.toolsets }))),
     skills: {
         list: os.skills.list.handler(({ input, context: { ctx } }) => run(async () => ({ skills: await ctx.deps.skills.list(home(ctx), str(input.category).trim() || null) }))),
         usage: os.skills.usage.handler(({ context: { ctx } }) => run(() => ctx.deps.skills.usage(home(ctx)))),
@@ -234,14 +415,31 @@ export const toolsRouter = os.router({
     memory: {
         get: os.memory.get.handler(({ input, context: { ctx } }) => run(async () => {
             const config = await ctx.deps.agentConfig.read(home(ctx));
-            return readMemory(home(ctx), config, memoryWorkspace(ctx, str(input.session_id), str(input.workspace)), ctx.deps.config.env, ctx.deps.sessions.deps.redactEnabled());
+            return readMemory(home(ctx), config, (await memoryWorkspace(ctx, str(input.session_id), str(input.workspace))), ctx.deps.config.env, ctx.deps.sessions.deps.redactEnabled(), ctx.deps.auth.signingKey());
         })),
         write: os.memory.write.handler(({ input, context: { ctx } }) => run(async () => {
             const section = input.section ?? input.target;
             if (section === undefined || input.content === undefined)
                 throw new HttpError(400, 'Missing required field(s): section, content');
-            return writeMemory(home(ctx), await ctx.deps.agentConfig.read(home(ctx)), str(section), str(input.content));
+            const profileHome = home(ctx);
+            return writeMemory(profileHome, await ctx.deps.agentConfig.read(profileHome), str(section), str(input.content), input.revision, {
+                key: ctx.deps.auth.signingKey(),
+                check: (target, content) => runningSidecar(ctx).call('memory.check', { profile_home: profileHome, target, content }),
+                write: (target, base, content) => runningSidecar(ctx).call('memory.write', { profile_home: profileHome, section: target, base, content }),
+            });
+        })),
+    },
+    pendingWrites: {
+        list: os.pendingWrites.list.handler(({ input, context: { ctx } }) => run(async () => {
+            // Without the Agent nothing can be reviewed, so the page shows no panel (the Agent's own status reports it down).
+            const sidecar = ctx.deps.sidecar();
+            const { enabled, items } = sidecar ? await sidecar.call('write_approval.pending', { profile_home: home(ctx), kind: input.kind }) : { enabled: false, items: [] };
+            const redact = (text) => redactString(text, ctx.deps.sessions.deps.redactEnabled());
+            // Display text is redacted like the memory page; `revision` stays the sidecar's hash of the raw diff it rechecks.
+            return { kind: input.kind, visible: items.length > 0, enabled, items: items.map((item) => ({ ...item, summary: redact(item.summary), diff: redact(item.diff) })) };
         })),
+        approve: os.pendingWrites.approve.handler(({ input, context: { ctx } }) => run(() => reviewPendingWrites(ctx, 'approve', input))),
+        reject: os.pendingWrites.reject.handler(({ input, context: { ctx } }) => run(() => reviewPendingWrites(ctx, 'reject', input))),
     },
     prompts: {
         list: os.prompts.list.handler(({ context: { ctx } }) => run(() => ({ prompts: loadPrompts(home(ctx)) }))),
@@ -263,20 +461,51 @@ export const toolsRouter = os.router({
             const command = str(input.command).trim();
             if (!command)
                 throw new HttpError(400, 'command is required');
+            const [, name = '', args = ''] = /^\/?(\S*)\s*([\s\S]*)$/.exec(command) ?? [];
+            const sessionId = str(input.session_id).trim();
+            if (sessionId)
+                (await ctx.deps.sessions.assertWritable(sessionId));
+            // TAL-902: a session command runs on the chat's own agent (the request guard already checked the chat's profile).
+            if (SESSION_EXEC_COMMANDS.has(name.toLowerCase())) {
+                return { output: await ctx.deps.turns.refine(sessionId ? (await ctx.deps.sessionStore.get(sessionId)) : null, args.trim()) };
+            }
+            // TAL-904: a chat's command runs under that chat's session and the workspace its next turn would use. An unknown
+            // chat (404) or a workspace that turn would refuse (400) refuses the command rather than run it half-bound.
+            const chat = sessionId ? { session_id: sessionId, workspace: (await ctx.deps.sessions.turnWorkspace((await ctx.deps.sessionStore.get(sessionId, { metadataOnly: true })))) } : {};
+            try {
+                return { output: (await runningSidecar(ctx).call('commands.exec', { profile_home: home(ctx), command, ...chat }, { timeoutMs: 120_000 })).output };
+            }
+            catch (error) {
+                return commandFailure(error, 'command_not_found', 'Plugin command not found');
+            }
+        })),
+        bundles: os.commands.bundles.handler(({ context: { ctx } }) => run(async () => {
             const sidecar = ctx.deps.sidecar();
-            if (!sidecar)
-                throw new HttpError(503, 'Hermes Agent sidecar is not running');
             try {
-                return { output: (await sidecar.call('commands.exec', { profile_home: home(ctx), command }, { timeoutMs: 120_000 })).output };
+                return { bundles: sidecar ? (await sidecar.call('commands.bundles', { profile_home: home(ctx) })).bundles : [] };
+            }
+            catch {
+                return { bundles: [] };
+            }
+        })),
+        resolveBundle: os.commands.resolveBundle.handler(({ input, context: { ctx } }) => run(async () => {
+            const command = str(input.command).trim();
+            if (!command)
+                throw new HttpError(400, 'command is required');
+            try {
+                return await runningSidecar(ctx).call('commands.bundle_resolve', { profile_home: home(ctx), command }, { timeoutMs: 120_000 });
+            }
+            catch (error) {
+                return commandFailure(error, 'bundle_not_found', 'Bundle command not found');
+            }
+        })),
+        resolveMoa: os.commands.resolveMoa.handler(({ input, context: { ctx } }) => run(async () => {
+            try {
+                return (await runningSidecar(ctx).call('commands.moa_preset', { profile_home: home(ctx), preset: str(input.preset).trim() || null })).moa;
             }
             catch (error) {
-                if (error instanceof SidecarError) {
-                    if (error.condition === 'command_not_found')
-                        throw new HttpError(404, 'Plugin command not found');
-                    if (error.condition === 'invalid_params' || error.code === -32602)
-                        throw new HttpError(400, error.message);
-                    throw new HttpError(500, error.message);
-                }
+                if (error instanceof SidecarError && error.condition === 'moa_unavailable')
+                    throw new HttpError(503, error.message);
                 throw error;
             }
         })),
@@ -287,17 +516,30 @@ export const toolsRouter = os.router({
             return notesSources(config, externalNotesEnabled(ctx.deps.config.env, config));
         })),
         search: os.notes.search.handler(({ input, context: { ctx } }) => run(async () => {
-            const config = await ctx.deps.agentConfig.read(home(ctx));
-            if (!externalNotesEnabled(ctx.deps.config.env, config))
-                throw new HttpError(404, 'External notes sources are disabled.', { source: 'disabled', results: [] });
-            const source = str(input.source ?? 'joplin').trim().toLowerCase() || 'joplin';
-            throw new HttpError(source === 'joplin' ? 502 : 400, source === 'joplin' ? 'Joplin search is not available in this release.' : 'Search is currently implemented for Joplin sources only.', { source, results: [] });
+            const deps = await joplinDeps(ctx, { results: [] });
+            const source = str(input.source).trim().toLowerCase() || 'joplin';
+            const query = str(input.q).trim();
+            if (source !== 'joplin')
+                throw new HttpError(400, 'Search is currently implemented for Joplin sources only.', { source, results: [] });
+            return { source: 'joplin', query, results: await joplin({ query, results: [] }, () => joplinSearch(deps, query, notesLimit(input.limit))) };
+        })),
+        item: os.notes.item.handler(({ input, context: { ctx } }) => run(async () => {
+            const deps = await joplinDeps(ctx, {});
+            const source = str(input.source).trim().toLowerCase() || 'joplin';
+            if (source !== 'joplin')
+                throw new HttpError(400, 'Preview is currently implemented for Joplin sources only.', { source });
+            return { source: 'joplin', note: await joplin({}, () => joplinNote(deps, str(input.id))) };
         })),
     },
-    insights: os.insights.handler(({ input, context: { ctx } }) => run(() => {
+    wiki: {
+        status: os.wiki.status.handler(({ context: { ctx } }) => run(async () => wikiPages.status(await wikiLocation(ctx)))),
+        browse: os.wiki.browse.handler(({ context: { ctx } }) => run(async () => wikiPages.browse(await wikiLocation(ctx)))),
+        page: os.wiki.page.handler(({ input, context: { ctx } }) => run(async () => wikiPages.page(await wikiLocation(ctx), str(input.path)))),
+    },
+    insights: os.insights.handler(({ input, context: { ctx } }) => run(async () => {
         let entries = [];
         try {
-            entries = ctx.deps.sessionStore.readIndexEntries();
+            entries = (await ctx.deps.sessionStore.readIndexEntries());
         }
         catch {
             entries = [];
@@ -306,13 +548,13 @@ export const toolsRouter = os.router({
     })),
     logs: os.logs.handler(({ input, context: { ctx } }) => run(() => readLogTail(home(ctx), input.file, input.tail))),
     ops: {
-        agent: os.ops.agent.handler(({ context: { ctx } }) => run(() => agentHealth({ env: ctx.deps.config.env, hermesHome: ctx.deps.config.hermesHome, profileHome: () => ctx.deps.profileHome(ctx.deps.activeProfile()), fetch: () => ctx.deps.fetch, now: ctx.deps.nowSeconds }))),
+        agent: os.ops.agent.handler(({ context: { ctx } }) => run(async () => { const [gateway, chat] = await Promise.all([health(ctx), currentChatReadiness(ctx.deps.sidecar())]); return { ...gateway, chat }; })),
         system: os.ops.system.handler(({ context: { ctx } }) => run(() => systemHealth(ctx.deps.config.homeDir, ctx.deps.runtimeDiagnostics()))),
         restart: os.ops.restart.handler(({ context: { ctx } }) => run(async () => {
             const sidecar = ctx.deps.sidecar();
             if (!sidecar)
                 throw new HttpError(500, 'Hermes Agent sidecar is not running');
-            const outcome = await sidecar.call('gateway.restart', { profile_home: home(ctx) }, { timeoutMs: 300_000 });
+            const outcome = await restartGateway(sidecar, home(ctx));
             if (outcome.status === 'completed')
                 return { ok: true, message: 'Gateway service restarted successfully' };
             if (outcome.status === 'busy')
@@ -320,12 +562,34 @@ export const toolsRouter = os.router({
             throw new HttpError(500, outcome.message || 'Internal error running restart');
         })),
         dashboard: os.ops.dashboard.handler(({ context: { ctx } }) => run(async () => { const config = await ctx.deps.agentConfig.read(home(ctx)).catch(() => ({})); return dashboardStatus(config, ctx.deps.config.env, ctx.deps.fetch); })),
+        dashboardConfig: os.ops.dashboardConfig.handler(({ context: { ctx } }) => run(async () => dashboardConfig(await ctx.deps.agentConfig.read(home(ctx)).catch(() => ({}))))),
+        saveDashboardConfig: os.ops.saveDashboardConfig.handler(({ input, context: { ctx } }) => run(async () => {
+            const next = parseDashboardConfig(input);
+            await ctx.deps.agentConfig.update(home(ctx), (config) => { applyDashboardConfig(config, next); });
+            return next;
+        })),
+        projectOs: os.ops.projectOs.handler(({ input, context: { ctx } }) => run(async () => {
+            const profile = activeProfileName(ctx);
+            return projectOsDashboard(str(input.board), {
+                localIo: ctx.deps.workspaces.profileSupportsLocalIo(profile),
+                lastWorkspace: (await ctx.deps.workspaces.lastWorkspace(profile)),
+                boards: async () => (await runningSidecar(ctx).call('kanban.boards', { profile_home: home(ctx), include_archived: true })).boards,
+                git: async (repoRoot) => gitBadge(await ctx.deps.git.status(repoRoot, { useCache: true })),
+                cwd: process.cwd(),
+            });
+        })),
         shutdown: os.ops.shutdown.handler(({ context: { ctx } }) => run(() => {
             ctx.deps.log(`[shutdown-request] remote=${ctx.peer || 'unknown'} method=${ctx.method} path=${ctx.path.slice(0, 240)} ua=${(ctx.header('user-agent') ?? 'no-ua').replace(/[\x00-\x1f\x7f]+/g, '?').slice(0, 240)}`);
             ctx.deps.requestShutdown();
             return { status: 'shutting_down' };
         })),
     },
+    gateway: {
+        status: os.gateway.status.handler(({ context: { ctx } }) => run(() => currentGatewayStatus(ctx))),
+        start: os.gateway.start.handler(({ context: { ctx } }) => run(() => gatewayAction(ctx, 'start'))),
+        stop: os.gateway.stop.handler(({ context: { ctx } }) => run(() => gatewayAction(ctx, 'stop'))),
+        restart: os.gateway.restart.handler(({ context: { ctx } }) => run(() => gatewayAction(ctx, 'restart'))),
+    },
     mcp: {
         servers: os.mcp.servers.handler(({ context: { ctx } }) => run(() => ctx.deps.mcp.servers(home(ctx)))),
         tools: os.mcp.tools.handler(({ input, context: { ctx } }) => run(() => ctx.deps.mcp.tools(home(ctx), input.q))),
@@ -342,9 +606,48 @@ export const toolsRouter = os.router({
         update: os.mcp.update.handler(({ input, context: { ctx } }) => run(() => { const { name, ...body } = input; return ctx.deps.mcp.update(home(ctx), decodeURIComponent(name), body); })),
         delete: os.mcp.delete.handler(({ input, context: { ctx } }) => run(() => ctx.deps.mcp.delete(home(ctx), decodeURIComponent(input.name)))),
     },
+    connectors: {
+        // Fails closed: no sidecar, or one that cannot answer, hides the page.
+        available: os.connectors.available.handler(({ context: { ctx } }) => run(async () => ({ available: ctx.deps.sidecar() ? await connectorCall(ctx, 'connectors.available', {}).then((r) => r.available, () => false) : false }))),
+        page: os.connectors.page.handler(({ context: { ctx } }) => run(async () => {
+            if (!ctx.deps.sidecar() || !(await connectorCall(ctx, 'connectors.available', {})).available)
+                return { available: false, connectors: [], policy_revision: null, rules_error: null };
+            const [catalog, accounts, policy] = await Promise.all([connectorCall(ctx, 'connectors.catalog', {}), connectorCall(ctx, 'connectors.accounts', {}), connectorPolicy(ctx)]);
+            rememberCatalogNames(home(ctx), catalog.connectors);
+            return connectorsPage(catalog.connectors, accounts.accounts, policy.policy, policy.error);
+        })),
+        tools: os.connectors.tools.handler(({ input, context: { ctx } }) => run(async () => {
+            const [listing, policy] = await Promise.all([connectorCall(ctx, 'connectors.tools', { connector: input.connector }), connectorPolicy(ctx)]);
+            return connectorTools(listing, policy.policy);
+        })),
+        setPolicy: os.connectors.setPolicy.handler(({ input, context: { ctx } }) => run(async () => {
+            const change = input.tool === undefined ? (typeof input.enabled === 'boolean' ? { enabled: input.enabled } : null)
+                : typeof input.tool_enabled === 'boolean' && input.enabled === undefined ? { tool: input.tool, tool_enabled: input.tool_enabled } : null;
+            if (!change)
+                throw new HttpError(400, 'Send `enabled`, or `tool` with `tool_enabled`.', { code: 'policy_invalid' });
+            const { revision } = await connectorCall(ctx, 'connectors.policy.set', { connector: input.connector, expected_revision: input.revision, ...change });
+            return { ok: true, revision };
+        })),
+        connect: os.connectors.connect.handler(({ input, context: { ctx } }) => run(async () => operationView(ctx, await connectorCall(ctx, 'connectors.connect', { connector: input.connector })))),
+        removeAccount: os.connectors.removeAccount.handler(({ input, context: { ctx } }) => run(async () => {
+            await connectorCall(ctx, 'connectors.remove', { connection_id: input.connection_id });
+            return { ok: true };
+        })),
+        operation: os.connectors.operation.handler(({ input, context: { ctx } }) => run(async () => operationView(ctx, await connectorCall(ctx, 'connectors.operation', { op_id: input.op_id })))),
+        respond: os.connectors.respond.handler(({ input, context: { ctx } }) => run(async () => {
+            // Only a move the operation offers now reaches the Agent: the view decides, the sidecar applies.
+            const view = connectorOperation(await connectorCall(ctx, 'connectors.operation', { op_id: input.op_id }));
+            const { action } = input;
+            const offered = action === 'continue' ? view.can_continue : view.targets.some((t) => t.name === input.target && t.actions.includes(action));
+            if (!offered)
+                throw new HttpError(409, 'That move is not open on this connection.', { code: 'operation_refused' });
+            return operationView(ctx, await connectorCall(ctx, 'connectors.respond', { op_id: input.op_id, action, ...(input.target ? { target: input.target } : {}), ...(input.env ? { env: input.env } : {}) }));
+        })),
+    },
     plugins: os.plugins.handler(({ context: { ctx } }) => run(async () => {
         const sidecar = ctx.deps.sidecar();
         const hooks = ['pre_tool_call', 'post_tool_call', 'pre_llm_call', 'post_llm_call'];
+        const editable = await sessionCanManageServer(ctx, await ensureTrustedAuthSession(ctx));
         if (!sidecar)
             return { plugins: [], empty: true, supported_hooks: hooks, read_only: true, unavailable: true };
         try {
@@ -354,22 +657,80 @@ export const toolsRouter = os.router({
                 if (v && typeof v === 'object' && !Array.isArray(v) && typeof v.provider === 'string')
                     selected[k] = str(v.provider).trim().toLowerCase();
             const result = await sidecar.call('plugins.list', { profile_home: home(ctx), selected_providers: selected });
-            return { plugins: result.plugins, empty: result.plugins.length === 0, supported_hooks: result.supported_hooks, read_only: true };
+            // A settings failure leaves the list itself readable.
+            const declared = await pluginSettingsList(ctx).catch((error) => { ctx.deps.log(`[plugins] settings fields failed: ${str(error.message)}`); return []; });
+            const settings = new Map(declared.map((entry) => [entry.key, entry.fields]));
+            const plugins = result.plugins.map((plugin) => settings.has(plugin.key) ? { ...plugin, settings: settings.get(plugin.key) } : plugin);
+            // An advisory failure leaves the list itself readable.
+            const advisory = await pluginIsolationAdvisory(ctx).catch((error) => { ctx.deps.log(`[plugins] isolation advisory failed: ${str(error.message)}`); return false; });
+            return { plugins, empty: plugins.length === 0, supported_hooks: result.supported_hooks, read_only: !editable, plugin_isolation_advisory: advisory };
         }
         catch (error) {
             ctx.deps.log(`[plugins] visibility payload failed: ${str(error.message)}`);
             return { plugins: [], empty: true, supported_hooks: hooks, read_only: true, unavailable: true };
         }
     })),
+    pluginSettings: os.pluginSettings.handler(({ input, context: { ctx } }) => run(() => serializePluginSettingsSave(async () => {
+        const sidecar = runningSidecar(ctx);
+        const fields = (await pluginSettingsList(ctx)).find((entry) => entry.key === input.key)?.fields;
+        if (!fields)
+            throw new HttpError(404, `Plugin '${input.key}' declares no settings`);
+        let plan;
+        try {
+            plan = planPluginSettings(fields, input.values ?? {}, input.secrets ?? {});
+        }
+        catch (error) {
+            if (error instanceof PluginSettingsInvalid)
+                throw new HttpError(400, error.message);
+            throw error;
+        }
+        const secretFields = fields.filter((field) => field.env && field.env in plan.secrets);
+        // Secrets never reach config.yaml: each goes to the profile `.env` under the name the manifest field declares. They are
+        // written first and restored if a later write fails, so a refused save changes neither file. The save call always runs:
+        // it resolves the plugin again and refuses (before writing) when a secret's `.env` name no longer matches its manifest.
+        const credential = (envVar, value) => writeRuntimeCredential({ env: ctx.deps.config.env, sidecar: ctx.deps.sidecar, log: ctx.deps.log }, ctx.deps.isRootProfile(activeProfileName(ctx)), home(ctx), envVar, value);
+        const previous = loadEnvFile(join(home(ctx), '.env'));
+        const applied = [];
+        let result;
+        try {
+            for (const [envVar, value] of Object.entries(plan.secrets)) {
+                await credential(envVar, value);
+                applied.push(envVar);
+            }
+            result = await sidecar.call('plugins.settings_save', { profile_home: home(ctx), key: input.key, values: plan.values, secret_envs: Object.fromEntries(secretFields.map((field) => [field.key, field.env])) });
+        }
+        catch (error) {
+            if (!definitiveRefusal(error)) {
+                throw new HttpError(503, 'The Agent sidecar stopped before confirming the save, so it may be partly applied; reload Settings to see what was saved', { condition: 'plugin_settings_unconfirmed' });
+            }
+            for (const envVar of applied.reverse()) {
+                await credential(envVar, previous[envVar] ?? null).catch((restore) => { ctx.deps.log(`[plugins] could not restore ${envVar} after a failed settings save: ${str(restore.message)}`); });
+            }
+            if (error instanceof SidecarError && error.condition === 'plugin_settings_managed')
+                throw new HttpError(403, error.message, { condition: error.condition });
+            if (error instanceof SidecarError && error.condition === 'plugin_settings_changed')
+                throw new HttpError(409, `${error.message}; reload and try again`, { condition: error.condition });
+            if (error instanceof SidecarError && error.condition === 'plugin_not_found')
+                throw new HttpError(404, error.message);
+            if (error instanceof SidecarError && error.code === -32602)
+                throw new HttpError(400, error.message);
+            if (error instanceof RuntimeCredentialError)
+                throw new HttpError(503, error.message);
+            if (error instanceof EnvWriteError)
+                throw new HttpError(error.status, `Failed to save a secret: ${error.message}`, { condition: error.condition });
+            throw error;
+        }
+        return { ok: true, key: result.key, written: [...result.written, ...secretFields.map((field) => field.key)], settings: pluginSettingsFieldsView(ctx, result.fields) };
+    }))),
     updates: {
-        check: os.updates.check.handler(({ context: { ctx } }) => run(() => {
-            const settings = ctx.deps.settings.load();
+        check: os.updates.check.handler(({ context: { ctx } }) => run(async () => {
+            const settings = (await ctx.deps.settings.load());
             if (settings.check_for_updates === false)
                 return updatesCheckView({ disabled: true });
             return updatesCheckView(ctx.deps.updates.cachedStatus(!pyBool(settings.ignore_agent_updates)));
         })),
         checkNow: os.updates.checkNow.handler(({ input, context: { ctx } }) => run(async () => {
-            const settings = ctx.deps.settings.load();
+            const settings = (await ctx.deps.settings.load());
             const force = pyBool(input.force);
             if (settings.check_for_updates === false && !force)
                 return updatesCheckView({ disabled: true });
@@ -378,58 +739,83 @@ export const toolsRouter = os.router({
             ctx.deps.log(`[updates] checking for updates (force=${String(force)}, channel=${channel})`);
             return updatesCheckView(await ctx.deps.updates.check(force, !pyBool(settings.ignore_agent_updates), channel, input.agent_channel));
         })),
-        apply: os.updates.apply.handler(({ input, context: { ctx } }) => run(() => { const target = updateTarget(input.target); return applyWithNotification(ctx, target, () => ctx.deps.updates.apply(target, bodyChannel(input.channel), () => true, { agentChannel: input.agent_channel, confirmedRevision: input.confirmed_agent_revision }), input.confirmed_agent_revision !== undefined, input.tab_id); })),
-        force: os.updates.force.handler(({ input, context: { ctx } }) => run(() => { const target = updateTarget(input.target); return applyWithNotification(ctx, target, () => ctx.deps.updates.force(target, bodyChannel(input.channel), { agentChannel: input.agent_channel, confirmedRevision: input.confirmed_agent_revision }), input.confirmed_agent_revision !== undefined, input.tab_id); })),
-        clearLock: os.updates.clearLock.handler(({ input, context: { ctx } }) => run(() => { const target = updateTarget(input.target); return applyWithNotification(ctx, target, () => ctx.deps.updates.clearLock(target, { agentChannel: input.agent_channel, confirmedRevision: input.confirmed_agent_revision }), input.confirmed_agent_revision !== undefined, input.tab_id); })),
-        summary: os.updates.summary.handler(({ input, context: { ctx } }) => run(() => ctx.deps.updates.summarize(input.updates ?? {}, input.target))),
+        apply: os.updates.apply.handler(({ input, context: { ctx } }) => run(() => applyWithNotification(ctx, input, 'apply'))),
+        force: os.updates.force.handler(({ input, context: { ctx } }) => run(() => applyWithNotification(ctx, input, 'force'))),
+        clearLock: os.updates.clearLock.handler(({ input, context: { ctx } }) => run(() => applyWithNotification(ctx, input, 'clearLock'))),
+        summary: os.updates.summary.handler(({ input, context: { ctx } }) => run(async () => ctx.deps.updates.summarize(input.target, (await ctx.deps.settings.load()).check_for_updates === false))),
     },
     updateNotifications: {
         list: os.updateNotifications.list.handler(({ input, context: { ctx } }) => run(async () => {
             const scope = await updateNotificationScope(ctx, input.tab_id);
-            const frontendBuild = ctx.deps.updateNotifications.syncTabBuild(scope, input.loaded_build ?? null, ctx.deps.spa.buildId());
-            return { ...ctx.deps.updateNotifications.list(scope), frontend_build: frontendBuild };
+            const frontendBuild = (await ctx.deps.updateNotifications.syncTabBuild(scope, input.loaded_build ?? null, ctx.deps.spa.buildId()));
+            return { ...(await ctx.deps.updateNotifications.list(scope)), frontend_build: frontendBuild };
         })),
         read: os.updateNotifications.read.handler(({ input, context: { ctx } }) => run(async () => {
-            const notification = ctx.deps.updateNotifications.read(await updateNotificationScope(ctx, input.tab_id), input.id);
+            const notification = (await ctx.deps.updateNotifications.read(await updateNotificationScope(ctx, input.tab_id), input.id));
             if (!notification)
                 throw new HttpError(404, 'Update notification not found');
             return notification;
         })),
         dismiss: os.updateNotifications.dismiss.handler(({ input, context: { ctx } }) => run(async () => {
-            const result = ctx.deps.updateNotifications.dismiss(await updateNotificationScope(ctx, input.tab_id), input.id);
+            const result = (await ctx.deps.updateNotifications.dismiss(await updateNotificationScope(ctx, input.tab_id), input.id));
             if (result === 'acknowledgement_required')
                 throw new HttpError(409, 'This notification requires acknowledgement before it can be dismissed');
             return { ok: true };
         })),
         clear: os.updateNotifications.clear.handler(({ input, context: { ctx } }) => run(async () => {
             const scope = await updateNotificationScope(ctx, input.tab_id);
-            const frontendBuild = ctx.deps.updateNotifications.syncTabBuild(scope, input.loaded_build ?? null, ctx.deps.spa.buildId());
-            return { ...ctx.deps.updateNotifications.clear(scope), frontend_build: frontendBuild };
+            const frontendBuild = (await ctx.deps.updateNotifications.syncTabBuild(scope, input.loaded_build ?? null, ctx.deps.spa.buildId()));
+            return { ...(await ctx.deps.updateNotifications.clear(scope)), frontend_build: frontendBuild };
         })),
         cancel: os.updateNotifications.cancel.handler(({ input, context: { ctx } }) => run(async () => {
-            const notification = ctx.deps.updateNotifications.cancelUpdate(await updateNotificationScope(ctx), input.id);
+            const notification = (await ctx.deps.updateNotifications.cancelUpdate(await updateNotificationScope(ctx), input.id));
             if (!notification)
                 throw new HttpError(404, 'Awaiting update notification not found');
             return notification;
         })),
         action: os.updateNotifications.action.handler(({ input, context: { ctx } }) => run(async () => {
-            const notification = ctx.deps.updateNotifications.action(await updateNotificationScope(ctx, input.tab_id), input.id, input.action_id);
+            const notification = (await ctx.deps.updateNotifications.action(await updateNotificationScope(ctx, input.tab_id), input.id, input.action_id));
             if (!notification)
                 throw new HttpError(404, 'Notification action not found');
+            if (input.action_id === GATEWAY_RESTART_NOW)
+                ctx.deps.gatewayRestarts.restartNow(notification.id);
             return notification;
         })),
     },
     transcribeCapability: os.transcribeCapability.handler(({ context: { ctx } }) => run(async () => {
+        const unavailable = { ok: true, available: false, provider: 'none', streaming: false, warm_supported: false };
         const sidecar = ctx.deps.sidecar();
         if (!sidecar)
-            return { ok: true, available: false, provider: 'none' };
+            return unavailable;
         try {
             const cap = await sidecar.call('stt.capability', { profile_home: home(ctx) });
-            return { ok: true, available: cap.available, provider: cap.provider || 'none' };
+            return { ok: true, available: cap.available, provider: cap.provider || 'none', streaming: cap.available && cap.streaming, warm_supported: cap.available && cap.warm_supported };
         }
         catch {
-            return { ok: true, available: false, provider: 'none' };
+            return unavailable;
+        }
+    })),
+    speech: {
+        prepare: os.speech.prepare.handler(({ input, context: { ctx } }) => run(async () => ({ spoken_text: await spokenText(ctx, input.text.trim()) }))),
+    },
+    transcribeWarm: os.transcribeWarm.handler(({ context: { ctx } }) => run(() => {
+        const sidecar = ctx.deps.sidecar();
+        const profileHome = home(ctx);
+        // One load per profile at a time: a record start during a running load joins it rather than holding another sidecar slot.
+        if (sidecar && !warmingHomes.has(profileHome)) {
+            warmingHomes.add(profileHome);
+            // The load outlives this request's write lease: it is the profile's activity until it settles, so the profile
+            // cannot be deleted under it. Taken while the request's lease still refuses a deletion in progress.
+            const release = ctx.deps.profileActivity(activeProfileName(ctx));
+            // A first use downloads the model, and the Agent's load cannot be cancelled, so the call has no deadline: the entry
+            // lives exactly as long as the sidecar worker (a sidecar exit rejects it). Nobody waits on it.
+            void sidecar.call('stt.warm', { profile_home: profileHome }, { timeoutMs: 0 })
+                .then((result) => { if (result.action === 'error')
+                ctx.deps.log(`[stt] warm-up failed (${result.provider}): ${str(result.error)}`); })
+                .catch((error) => { ctx.deps.log(`[stt] warm-up failed: ${str(error.message)}`); })
+                .finally(() => { warmingHomes.delete(profileHome); release(); });
         }
+        return { ok: true };
     })),
     clientEvents: os.clientEvents.handler(({ input, context: { ctx } }) => run(() => {
         if (ctx.deps.clientEventLimiter.limited(ctx.peer || 'unknown'))