@maudecode/talaria-web 1.18.0 → 1.20.0

package/dist/api/chat-router.js

@@ -1,7 +1,8 @@
 /** Chat turn admission, control, approvals, clarify, goals, background tasks, and side questions. */
+import { timingOutcome } from '../startup-timing.js';
 import { GATEWAY_APPROVAL_RELAY_UNAVAILABLE, isGenericContinuationIntent } from '../sessions/turn.js';
 import { implement } from '@orpc/server';
-import { chatContract, MAX_CHAT_ATTACHMENTS } from '@maudecode/talaria-web-contracts';
+import { chatContract, MAX_CHAT_ATTACHMENTS, RPC_ERROR_CODES } from '@maudecode/talaria-web-contracts';
 import { randomUUID } from 'node:crypto';
 import { HttpError } from './router.js';
 import { requestSessionIdGuard, streamOwnerSessionId, streamVisibleToRequest } from './session-visibility.js';
@@ -10,6 +11,9 @@ import { SessionNotFound } from '../sessions/store.js';
 import { compressionRecoveryPayload, isSafeSessionId } from '../sessions/session.js';
 import { messageText } from '../sessions/merge.js';
 import { str } from '../util.js';
+import { activeProfileName } from '../auth/gate.js';
+import { SidecarError } from '../sidecar/client.js';
+import { unsupportedPromptMessage } from '../tools/commands.js';
 const os = implement(chatContract).$context().use(requestSessionIdGuard);
 const STEER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const PROFILE_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
@@ -27,14 +31,14 @@ async function run(fn) {
     }
 }
 /** A session this request's profile may see (TAL-372 background work never crosses owners). */
-function visibleSession(ctx, sid) {
-    if (!ctx.deps.sessions.sessionIdVisible(sid))
+async function visibleSession(ctx, sid) {
+    if (!(await ctx.deps.sessions.sessionIdVisible(sid)))
         throw new HttpError(404, 'Session not found');
-    return getSession(ctx, sid, true);
+    return (await getSession(ctx, sid, true));
 }
-function getSession(ctx, sid, metadataOnly = false) {
+async function getSession(ctx, sid, metadataOnly = false) {
     try {
-        return ctx.deps.sessionStore.get(sid, { metadataOnly });
+        return (await ctx.deps.sessionStore.get(sid, { metadataOnly }));
     }
     catch {
         throw new HttpError(404, 'Session not found');
@@ -88,9 +92,61 @@ function visibleOrRetag(ctx, s, requestedProfile) {
     }
     throw new HttpError(404, 'Session not found');
 }
+/**
+ * TAL-817: what the model gets for a typed Agent prompt built-in (`/plan`, `/initiate-setup`, …): the Agent's own expansion
+ * of it for this session's profile, workspace and toolsets, while the transcript keeps the typed text; null when `msg` is
+ * not one. One the Agent cannot expand is
+ * refused with the catalog's message instead of reaching the model raw. Without a sidecar the turn reports that itself.
+ */
+async function expandPromptBuiltin(ctx, s, msg, workspace) {
+    const sidecar = ctx.deps.sidecar();
+    if (!msg.startsWith('/') || !sidecar)
+        return null;
+    // Only `/init` reads the workspace, and the sidecar refuses it without one; the turn reports a bad workspace itself.
+    let cwd = '';
+    try {
+        cwd = (await ctx.deps.sessions.turnWorkspace(s, workspace));
+    }
+    catch {
+        cwd = '';
+    }
+    let expanded;
+    try {
+        expanded = await sidecar.call('commands.expand_prompt', {
+            profile_home: ctx.deps.profileHome(s.profile ?? activeProfileName(ctx)), command: msg, session_id: s.session_id, workspace: cwd,
+            enabled_toolsets: s.enabled_toolsets,
+        }, { timeoutMs: 120_000 });
+    }
+    catch (error) {
+        if (!(error instanceof SidecarError))
+            throw error;
+        const invalid = error.condition === 'invalid_params' || error.code === RPC_ERROR_CODES.invalidParams;
+        throw new HttpError(invalid ? 400 : error.condition === 'sidecar_unavailable' ? 503 : 502, error.message);
+    }
+    if (expanded.name !== null && expanded.message === null)
+        throw new HttpError(400, unsupportedPromptMessage(expanded.name));
+    return expanded.message;
+}
 /** `chat.start`; a `chat.steer` sent while a background turn runs starts the user's turn through it too (TAL-460). */
 async function startChat(ctx, body, settle = {}) {
+    ctx.enterChatStart();
+    const timing = ctx.startupTiming;
+    try {
+        const response = await startChatTimed(ctx, body, settle);
+        if (!response.stream_id)
+            timing?.finish('noop');
+        return response;
+    }
+    catch (error) {
+        timing?.finish(timingOutcome(error));
+        throw error;
+    }
+}
+async function startChatTimed(ctx, body, settle) {
+    const timing = ctx.startupTiming;
+    const measure = (name, fn) => timing ? timing.measure(name, fn) : Promise.resolve(fn());
     requireField(body, 'session_id');
+    timing?.identify(str(body.session_id));
     if (str(body.message).trim() === '[SILENT]')
         return { status: 'suppressed', reason: 'silent_control_message' };
     if (body.regenerate === true)
@@ -98,51 +154,66 @@ async function startChat(ctx, body, settle = {}) {
     const sid = str(body.session_id);
     // Python `_agent_runtime_barrier_response`: a stale local Agent checkout is refused with a typed 409 before any
     // session state is materialised, claimed, or mutated.
-    await ensureAgentRuntimeCurrent(ctx.deps.sidecar());
-    // TAL-542: the stale-model check reads this catalog; it is built before the session is read so no await follows that read.
-    await ctx.deps.sessions.deps.warmSessionModelRepair?.();
+    await measure('runtime_barrier', () => ensureAgentRuntimeCurrent(ctx.deps.sidecar()));
+    const owner = ctx.deps.sessions.owner;
+    if (owner && (await measure('owner_routing', () => owner.isOwned(sid)))) {
+        if (!(await ctx.deps.sessions.sessionIdVisible(sid)))
+            throw new HttpError(404, 'Session not found');
+        const response = (await owner.submit(sid, body, timing));
+        timing?.finish('ok');
+        return response;
+    }
+    // Admission reads the cached catalog snapshot; it never waits for a refresh.
+    timing?.begin('catalog_wait');
+    timing?.end('catalog_wait', 'noop');
+    const closeLoad = timing?.begin('session_load');
     let s;
     try {
-        s = ctx.deps.sessionStore.get(sid);
+        s = (await ctx.deps.sessionStore.get(sid));
     }
     catch {
         // Python `_claim_or_synthesize_cli_session` on the POST path: a claimable foreign (CLI/TUI/Desktop) session is
         // materialised as a WebUI sidecar before its first turn; an owned foreign store answers 403, nothing → 404.
-        const synth = ctx.deps.sessions.claimOrSynthesizeCliSession(sid);
+        const synth = (await ctx.deps.sessions.claimOrSynthesizeCliSession(sid));
         if (!synth.session)
             throw new HttpError(404, 'Session not found');
         if (synth.reason === 'not_claimable')
             throw new HttpError(403, 'session is read-only in its foreign store; cannot be claimed writeable in WebUI');
-        ctx.deps.sessionStore.save(synth.session);
-        s = ctx.deps.sessionStore.get(sid);
+        await ctx.deps.sessionStore.save(synth.session);
+        s = (await ctx.deps.sessionStore.get(sid));
     }
+    closeLoad?.();
+    const closeOwnership = timing?.begin('ownership_checks');
     // Python `_get_or_materialize_session` raised PermissionError for both: a read-only import and a delegated
     // subagent child (by sidecar tag or state.db row), which chat start answered with the same 403.
-    if (ctx.deps.sessions.isReadOnly(s) || s.branchSourceReadonly || ctx.deps.sessions.isSubagentViewOnly(sid))
+    if ((await ctx.deps.sessions.isReadOnly(s)) || s.branchSourceReadonly || (await ctx.deps.sessions.isSubagentViewOnly(sid)))
         throw new HttpError(403, 'Read-only imported sessions cannot be continued from WebUI');
     const requestedProfile = str(body.profile).trim();
     if (requestedProfile && requestedProfile !== 'default' && !PROFILE_ID_RE.test(requestedProfile))
         throw new HttpError(400, 'invalid profile');
     visibleOrRetag(ctx, s, requestedProfile);
+    closeOwnership?.();
     const msg = str(body.message).trim();
     const attachments = normalizeChatAttachments(body.attachments).slice(0, MAX_CHAT_ATTACHMENTS);
     // TAL-276: an attached file alone makes a turn; one with neither text nor a file path is refused.
     if (!msg && !attachments.some((att) => str(att.path)))
         throw new HttpError(400, 'message is required');
+    const prompt = await measure('prompt_preparation', () => expandPromptBuiltin(ctx, s, msg, body.workspace));
     // TAL-460: the user's message never joins a background turn; that turn stops quietly and this one takes its place.
-    if (await ctx.deps.turns.yieldBackgroundTurn(sid)) {
-        await ctx.deps.sessions.deps.warmSessionModelRepair?.();
-        s = ctx.deps.sessionStore.get(sid);
+    const yielded = await measure('background_yield', () => ctx.deps.turns.yieldBackgroundTurn(sid));
+    if (prompt !== null || yielded) {
+        s = (await ctx.deps.sessionStore.get(sid));
+        visibleOrRetag(ctx, s, requestedProfile);
     }
     // Python `compression_recovery_payload_for_session` + `is_generic_continuation_intent`.
     if (compressionRecoveryPayload(s) && !attachments.length && isGenericContinuationIntent(msg)) {
         throw new HttpError(409, 'This session exhausted context compression. Start a focused continuation, then describe the next narrow task.', { type: 'compression_recovery_required', compression_recovery: s.compression_recovery, session_id: s.session_id });
     }
-    const workspace = ctx.deps.sessions.turnWorkspace(s, body.workspace);
+    const workspace = await measure('workspace_preparation', () => ctx.deps.sessions.turnWorkspace(s, body.workspace));
     const [model, provider, normalized] = ctx.deps.sessions.turnModel(s, body);
     if (body.moa_config)
         throw new HttpError(503, 'MoA overrides need the Agent command registry (checkpoint 7).');
-    const response = ctx.deps.turns.start(s, { msg, attachments, workspace, model, modelProvider: provider, normalizedModel: normalized, source: 'webui', ...settle });
+    const response = (await ctx.deps.turns.start(s, { timing, msg, ...(prompt === null ? {} : { prompt }), attachments, workspace, model, modelProvider: provider, normalizedModel: normalized, source: 'webui', voiceTurn: body.voice_turn === true, connectCard: body.connect_card === true, skillSecret: body.skill_secret === true, ...settle }));
     if (response._status !== undefined && response._status >= 400)
         throw new HttpError(response._status, response.error ?? 'chat start failed', response.active_stream_id ? { active_stream_id: response.active_stream_id } : {});
     return startPayload(response);
@@ -152,7 +223,9 @@ async function startChat(ctx, body, settle = {}) {
  * failed after streaming text, answers `partial` with that text; any other failure answers with its error frame.
  */
 async function syncChat(ctx, body) {
-    if (ctx.deps.sessions.isSubagentViewOnly(str(body.session_id)))
+    if (await ctx.deps.sessions.owner?.isOwned(str(body.session_id)))
+        throw new HttpError(409, 'This owner requires the asynchronous chat stream', { code: 'owner_requires_streaming' });
+    if ((await ctx.deps.sessions.isSubagentViewOnly(str(body.session_id))))
         throw new HttpError(400, 'Subagent sessions are view-only and cannot be written from WebUI');
     if (!str(body.message).trim())
         throw new HttpError(400, 'empty message');
@@ -164,8 +237,8 @@ async function syncChat(ctx, body) {
     const streamId = str(started.stream_id);
     if (streamId)
         await ctx.deps.turns.finished(streamId);
-    const s = getSession(ctx, str(body.session_id));
-    const session = ctx.deps.turns.publicTerminalSession(s);
+    const s = (await getSession(ctx, str(body.session_id)));
+    const session = (await ctx.deps.turns.publicTerminalSession(s));
     const ended = outcome;
     // A `[SILENT]` control message starts no turn.
     if (!streamId || (ended && 'answer' in ended)) {
@@ -186,8 +259,24 @@ async function syncChat(ctx, body) {
 }
 export const chatRouter = os.router({
     chat: {
-        sync: os.chat.sync.handler(({ input, context: { ctx } }) => run(() => syncChat(ctx, input))),
-        start: os.chat.start.handler(({ input, context: { ctx } }) => run(() => startChat(ctx, input))),
+        ownerAction: os.chat.ownerAction.handler(({ input, context: { ctx } }) => run(async () => {
+            if (!(await ctx.deps.sessions.sessionIdVisible(input.session_id)))
+                throw new HttpError(404, 'Session not found');
+            const owner = ctx.deps.sessions.owner;
+            if (!owner)
+                throw new HttpError(503, 'Native session controls are unavailable');
+            let draft;
+            if (input.action === 'retry') {
+                draft = await owner.retry(input.session_id, input.admission_id, input.execution_generation);
+            }
+            else
+                await owner.action(input.session_id, input);
+            const session = await ctx.deps.sessions.detail(input.session_id, {});
+            const model_change = session.owner_attachment?.model_change;
+            return { ok: true, session: session, ...(draft === undefined ? {} : { draft }), ...(model_change ? { model_change } : {}) };
+        })),
+        sync: os.chat.sync.handler(({ input, context: { ctx } }) => run(async () => (await syncChat(ctx, input)))),
+        start: os.chat.start.handler(({ input, context: { ctx } }) => run(async () => (await startChat(ctx, input)))),
         steer: os.chat.steer.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = str(input.session_id).trim();
             const text = str(input.text).trim();
@@ -201,43 +290,52 @@ export const chatRouter = os.router({
                 throw new HttpError(400, 'steer_id must be 1-128 URL-safe characters');
             if (!steerId)
                 steerId = `steer-${randomUUID()}`;
-            if (!ctx.deps.sessions.sessionIdVisible(sid))
+            if (!(await ctx.deps.sessions.sessionIdVisible(sid)))
                 throw new HttpError(404, 'Session not found');
             const active = ctx.deps.registry.activeRunStreamForSession(sid);
             if (active && ctx.deps.registry.activeRuns.get(active)?.origin === 'background') {
                 const started = await startChat(ctx, { session_id: sid, message: text });
                 return { accepted: true, fallback: null, stream_id: started.stream_id ? str(started.stream_id) : null, steer_id: steerId, started_turn: started };
             }
-            return ctx.deps.turns.steer(sid, text, display, steerId);
+            // TAL-817: a prompt built-in steers with its expansion; the steer still shows as typed. A missing session is the steer's to report.
+            let target = null;
+            try {
+                target = (await ctx.deps.sessionStore.get(sid, { metadataOnly: true }));
+            }
+            catch {
+                target = null;
+            }
+            const prompt = target ? await expandPromptBuiltin(ctx, target, text, undefined) : null;
+            return (await ctx.deps.turns.steer(sid, prompt ?? text, display || (prompt === null ? '' : text), steerId));
         })),
         // TAL-424: Edit, Cancel and Send now on a pending steer; unknown or already-taken steers answer false.
         steerWithdraw: os.chat.steerWithdraw.handler(({ input, context: { ctx } }) => run(async () => {
-            if (!ctx.deps.sessions.sessionIdVisible(input.session_id))
+            if (!(await ctx.deps.sessions.sessionIdVisible(input.session_id)))
                 throw new HttpError(404, 'Session not found');
-            return ctx.deps.turns.withdrawSteer(input.session_id, input.steer_id, input.reason);
+            return (await ctx.deps.turns.withdrawSteer(input.session_id, input.steer_id, input.reason));
         })),
         steerSendNow: os.chat.steerSendNow.handler(({ input, context: { ctx } }) => run(async () => {
-            if (!ctx.deps.sessions.sessionIdVisible(input.session_id))
+            if (!(await ctx.deps.sessions.sessionIdVisible(input.session_id)))
                 throw new HttpError(404, 'Session not found');
-            return ctx.deps.turns.sendSteerNow(input.session_id, input.steer_id);
+            return (await ctx.deps.turns.sendSteerNow(input.session_id, input.steer_id));
         })),
         cancel: os.chat.cancel.handler(({ input, context: { ctx } }) => run(async () => {
             const streamId = str(input.stream_id);
             if (!streamId)
                 throw new HttpError(400, 'stream_id required');
-            if (!streamVisibleToRequest(ctx, streamId))
+            if (!(await streamVisibleToRequest(ctx, streamId)))
                 throw new HttpError(404, 'Session not found');
             const { cancelled, withdrawn } = await ctx.deps.turns.cancel(streamId);
             return { ok: true, cancelled, stream_id: streamId, withdrawn_steers: withdrawn };
         })),
-        streamStatus: os.chat.streamStatus.handler(({ input, context: { ctx } }) => run(() => {
+        streamStatus: os.chat.streamStatus.handler(({ input, context: { ctx } }) => run(async () => {
             const streamId = str(input.stream_id);
-            if (!streamVisibleToRequest(ctx, streamId))
+            if (!(await streamVisibleToRequest(ctx, streamId)))
                 throw new HttpError(404, 'Session not found');
             const active = ctx.deps.registry.liveIds.has(streamId);
-            const owner = streamOwnerSessionId(ctx, streamId);
-            const payload = { active, stream_id: streamId, replay_available: false, blocking_stream_id: owner ? ctx.deps.sessions.activeRunBlocking(owner) : null };
-            const summary = streamId ? ctx.deps.journal.findRunSummary(streamId) : null;
+            const owner = (await streamOwnerSessionId(ctx, streamId));
+            const payload = { active, stream_id: streamId, replay_available: false, blocking_stream_id: owner ? (await ctx.deps.sessions.activeRunBlocking(owner)) : null };
+            const summary = streamId ? (await ctx.deps.journal.findRunSummary(streamId)) : null;
             if (summary) {
                 payload.replay_available = true;
                 const terminal = summary.terminal;
@@ -247,7 +345,7 @@ export const chatRouter = os.router({
         })),
     },
     approval: {
-        pending: os.approval.pending.handler(({ input, context: { ctx } }) => run(() => ctx.deps.pending.approvalPending(str(input.session_id)))),
+        pending: os.approval.pending.handler(({ input, context: { ctx } }) => run(async () => (await ctx.deps.sessions.owner?.isOwned(str(input.session_id))) ? ctx.deps.sessions.owner.pending(str(input.session_id), 'approval') : ctx.deps.pending.approvalPending(str(input.session_id)))),
         respond: os.approval.respond.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = str(input.session_id);
             if (!sid)
@@ -268,14 +366,15 @@ export const chatRouter = os.router({
         })),
     },
     clarify: {
-        pending: os.clarify.pending.handler(({ input, context: { ctx } }) => run(() => ctx.deps.pending.clarifyPending(str(input.session_id)))),
+        pending: os.clarify.pending.handler(({ input, context: { ctx } }) => run(async () => (await ctx.deps.sessions.owner?.isOwned(str(input.session_id))) ? ctx.deps.sessions.owner.pending(str(input.session_id), 'clarify') : ctx.deps.pending.clarifyPending(str(input.session_id)))),
         respond: os.clarify.respond.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = str(input.session_id);
             if (!sid)
                 throw new HttpError(400, 'session_id is required');
-            // Keyed step answers are shaped by the server; a raw `response` is relayed as-is for older clients.
-            const reply = input.answers ?? str(input.response ?? input.answer ?? input.choice).trim();
-            if (!reply)
+            // Both keyed answers and older clients' raw replies are shaped against the pending prompt; only a vault prompt
+            // takes a decline (TAL-887).
+            const reply = input.decline === true ? null : input.answers ?? str(input.response ?? input.answer ?? input.choice).trim();
+            if (reply === '')
                 throw new HttpError(400, 'response is required');
             const result = await ctx.deps.turns.respondClarify(sid, str(input.clarify_id), reply);
             if (result.stale)
@@ -284,7 +383,8 @@ export const chatRouter = os.router({
                 throw new HttpError(400, 'answers must answer every question of the pending clarification', { ok: false });
             if (!result.ok)
                 throw new HttpError(503, result.error ?? 'clarify relay failed', { ok: false });
-            return { ok: true, response: str(result.response) };
+            // A vault answer is never echoed back.
+            return result.response === undefined ? { ok: true } : { ok: true, response: result.response };
         })),
     },
     goal: os.goal.handler(({ input, context: { ctx } }) => run(async () => {
@@ -295,10 +395,10 @@ export const chatRouter = os.router({
             return { status: 'suppressed', reason: 'silent_control_message' };
         const sid = str(body.session_id);
         // Python: a delegated subagent child is view-only; its goal state is never mutated and no turn starts on it.
-        if (ctx.deps.sessions.isSubagentViewOnly(sid))
+        if ((await ctx.deps.sessions.isSubagentViewOnly(sid)))
             throw new HttpError(400, 'Subagent sessions are view-only and cannot run /goal from WebUI');
-        const s = getSession(ctx, sid);
-        if (ctx.deps.sessions.isReadOnly(s) || s.branchSourceReadonly)
+        const s = (await getSession(ctx, sid));
+        if ((await ctx.deps.sessions.isReadOnly(s)) || s.branchSourceReadonly)
             throw new HttpError(403, 'Read-only imported sessions cannot be continued from WebUI');
         const requestedProfile = str(body.profile).trim();
         if (requestedProfile && requestedProfile !== 'default' && !PROFILE_ID_RE.test(requestedProfile))
@@ -309,7 +409,7 @@ export const chatRouter = os.router({
         if (s.active_stream_id) {
             streamRunning = ctx.deps.registry.liveIds.has(s.active_stream_id);
             if (!streamRunning)
-                ctx.deps.sessions.clearStaleStreamState(s);
+                (await ctx.deps.sessions.clearStaleStreamState(s));
         }
         const sidecar = ctx.deps.sidecar();
         if (!sidecar)
@@ -329,21 +429,27 @@ export const chatRouter = os.router({
             defaultMaxTurns = 20;
         }
         const snapshot = await sidecar.call('goals.snapshot', { session_id: sid, profile_home: profileHome, default_max_turns: defaultMaxTurns });
-        const payload = await sidecar.call('goals.command', { session_id: sid, profile_home: profileHome, args, stream_running: streamRunning, default_max_turns: defaultMaxTurns });
-        if (payload.ok === false)
-            throw new HttpError(payload.error === 'agent_running' ? 409 : 400, str(payload.message || payload.error || 'goal command failed'), payload);
+        await ctx.deps.sessions.assertWritable(s);
+        const payload = await sidecar.call('goals.command', { session_id: sid, profile_home: profileHome, args, stream_running: streamRunning, default_max_turns: defaultMaxTurns, workspace: str(s.workspace) || undefined });
+        // TAL-808: the session `goal` follows the command before the client reloads the session.
+        await ctx.deps.turns.refreshGoal(s);
+        if (payload.ok === false) {
+            // Clients show the body's `error`, so the Agent's reason replaces the sidecar's code there.
+            const reason = str(payload.message || payload.error || 'goal command failed');
+            throw new HttpError(payload.error === 'agent_running' ? 409 : 400, reason, { ...payload, error: reason });
+        }
         const kickoff = str(payload.kickoff_prompt).trim();
         if (kickoff) {
-            // TAL-542: after the goal RPCs, so the stale-model check reads a catalog for the profile the session now runs under.
-            await ctx.deps.sessions.deps.warmSessionModelRepair?.(s.profile);
-            const workspace = ctx.deps.sessions.turnWorkspace(s, body.workspace);
+            const workspace = (await ctx.deps.sessions.turnWorkspace(s, body.workspace));
             const [model, provider, normalized] = ctx.deps.sessions.turnModel(s, body);
-            const started = ctx.deps.turns.start(s, { msg: kickoff, attachments: [], workspace, model, modelProvider: provider, normalizedModel: normalized, source: 'webui', goalRelated: true });
+            const started = (await ctx.deps.turns.start(s, { msg: kickoff, attachments: [], workspace, model, modelProvider: provider, normalizedModel: normalized, source: 'webui', goalRelated: true }));
             if (started._status !== undefined && started._status >= 400) {
                 try {
+                    await ctx.deps.sessions.assertWritable(s);
                     await sidecar.call('goals.restore', { session_id: sid, profile_home: profileHome, snapshot: snapshot.snapshot });
                 }
                 catch { /* best effort */ }
+                await ctx.deps.turns.refreshGoal(s);
                 throw new HttpError(started._status, started.error ?? 'goal kickoff failed', { ...payload, ok: false });
             }
             Object.assign(payload, startPayload(started));
@@ -355,69 +461,79 @@ export const chatRouter = os.router({
             const body = input;
             requireField(body, 'session_id', 'prompt');
             // A subagent child's profile/workspace/context must never seed a runnable background session.
-            if (ctx.deps.sessions.isSubagentViewOnly(str(body.session_id)))
+            if ((await ctx.deps.sessions.isSubagentViewOnly(str(body.session_id))))
                 throw new HttpError(400, 'Subagent sessions are view-only and cannot run background tasks from WebUI');
-            // TAL-542: the background turn starts on the parent's repaired pair; the catalog is built before the parent is read.
-            await ctx.deps.sessions.deps.warmSessionModelRepair?.();
-            const parent = getSession(ctx, str(body.session_id));
-            if (ctx.deps.sessions.isReadOnly(parent) || parent.branchSourceReadonly)
+            const parent = (await getSession(ctx, str(body.session_id)));
+            if ((await ctx.deps.sessions.isReadOnly(parent)) || parent.branchSourceReadonly)
                 throw new HttpError(403, 'Read-only imported sessions cannot be continued from WebUI');
             const prompt = str(body.prompt).trim();
             if (!prompt)
                 throw new HttpError(400, 'prompt is required');
             const [model, modelProvider] = ctx.deps.sessions.turnModel(parent, {});
-            const bg = ctx.deps.sessionStore.newSession({ workspace: parent.workspace, model, modelProvider, profile: parent.profile });
+            const bg = (await ctx.deps.sessionStore.newSession({ workspace: parent.workspace, model, modelProvider, profile: parent.profile }));
             bg.title = `bg: ${prompt.slice(0, 60)}`;
-            ctx.deps.sessionStore.save(bg);
+            await ctx.deps.sessionStore.save(bg);
             // Python: `uuid.uuid4().hex[:8]`; a failed run still completes the task so `/api/background/tasks` reports it,
             // and the hidden bg session file is removed afterwards.
             const taskId = randomUUID().replace(/-/g, '').slice(0, 8);
             // TAL-372: the parent session keeps the task's record and result, so every client and a restart see it.
-            ctx.deps.background.trackCommand(parent.session_id, taskId, prompt);
-            const cleanup = () => { try {
-                ctx.deps.sessionStore.deleteFiles(bg.session_id, { tombstone: false });
+            await ctx.deps.background.trackCommand(parent.session_id, taskId, prompt);
+            const cleanup = async () => { try {
+                (await ctx.deps.sessionStore.delete(bg.session_id, { tombstone: false }));
             }
             catch { /* best effort */ } };
-            const started = ctx.deps.turns.start(bg, {
+            const started = (await ctx.deps.turns.start(bg, {
                 msg: prompt, attachments: [], workspace: parent.workspace, model, modelProvider, source: 'webui',
                 // Python: the last non-error assistant reply with content, else "(no answer produced)".
-                onDone: (answer) => { ctx.deps.background.settleCommand(parent.session_id, taskId, 'completed', answer || '(no answer produced)'); cleanup(); },
-                onFailed: () => { ctx.deps.background.settleCommand(parent.session_id, taskId, 'failed', '(background task failed)'); cleanup(); },
-            });
+                onDone: async (answer) => { (await ctx.deps.background.settleCommand(parent.session_id, taskId, 'completed', answer || '(no answer produced)')); (await cleanup()); },
+                onFailed: async () => { (await ctx.deps.background.settleCommand(parent.session_id, taskId, 'failed', '(background task failed)')); (await cleanup()); },
+            }));
             if (started._status !== undefined && started._status >= 400) {
                 // Admission refused (profile deleting, session busy…): nothing runs, so the tracked task and hidden
                 // session must not linger as "running".
-                ctx.deps.background.forgetCommand(parent.session_id, taskId);
-                cleanup();
+                await ctx.deps.background.forgetCommand(parent.session_id, taskId);
+                await cleanup();
                 throw new HttpError(started._status, started.error ?? 'background start failed');
             }
-            ctx.deps.background.setCommandStream(parent.session_id, taskId, str(started.stream_id));
+            await ctx.deps.background.setCommandStream(parent.session_id, taskId, str(started.stream_id));
             return { ok: true, task_id: taskId, stream_id: str(started.stream_id), session_id: bg.session_id };
         })),
         tasks: os.background.tasks.handler(({ input, context: { ctx } }) => run(async () => {
-            const s = visibleSession(ctx, input.session_id);
-            const snapshot = await ctx.deps.background.snapshot(s.session_id, s.profile);
+            const s = (await visibleSession(ctx, input.session_id));
+            const snapshot = await ctx.deps.background.snapshot(s.session_id, s.profile, { canStop: !(await ctx.deps.sessions.isReadOnly(s)) });
             return { session_id: s.session_id, ...snapshot, tasks: input.kind ? snapshot.tasks.filter((t) => t.kind === input.kind) : snapshot.tasks };
         })),
         result: os.background.result.handler(({ input, context: { ctx } }) => run(async () => {
-            const s = visibleSession(ctx, input.session_id);
+            const s = (await visibleSession(ctx, input.session_id));
             const text = await ctx.deps.background.result(s.session_id, s.profile, input.task_id);
             if (text === null)
                 throw new HttpError(404, 'No result for this background task');
             return { task_id: input.task_id, text };
         })),
-        dismiss: os.background.dismiss.handler(({ input, context: { ctx } }) => run(() => {
-            const s = visibleSession(ctx, input.session_id);
-            const task = ctx.deps.background.dismiss(s.session_id, input.task_id);
+        stop: os.background.stop.handler(({ input, context: { ctx } }) => run(async () => {
+            const s = await visibleSession(ctx, input.session_id);
+            await ctx.deps.sessions.assertWritable(s);
+            try {
+                return await ctx.deps.background.stop(s.session_id, s.profile, input.task_id);
+            }
+            catch (error) {
+                if (!(error instanceof SidecarError))
+                    throw error;
+                throw new HttpError(error.condition === 'sidecar_unavailable' ? 503 : 502, error.message);
+            }
+        })),
+        dismiss: os.background.dismiss.handler(({ input, context: { ctx } }) => run(async () => {
+            const s = (await visibleSession(ctx, input.session_id));
+            const task = (await ctx.deps.background.dismiss(s.session_id, input.task_id));
             if (!task)
                 throw new HttpError(404, 'Background task not found');
             return { ok: true, task };
         })),
-        ack: os.background.ack.handler(({ input, context: { ctx } }) => run(() => {
+        ack: os.background.ack.handler(({ input, context: { ctx } }) => run(async () => {
             const body = input;
             requireField(body, 'session_id');
             const sid = str(body.session_id).trim();
-            const s = getSession(ctx, sid, true);
+            const s = (await getSession(ctx, sid, true));
             const pid = str(body.task_id || body.process_id).trim();
             if (str(body.process_id).trim())
                 ctx.extraResponseHeaders = { deprecation: 'true' };
@@ -431,31 +547,30 @@ export const chatRouter = os.router({
         if (!isSafeSessionId(sid))
             throw new HttpError(404, 'Session not found');
         // Python: a subagent child's context must not be cloned into a runnable ephemeral session.
-        if (ctx.deps.sessions.isSubagentViewOnly(sid))
+        if ((await ctx.deps.sessions.isSubagentViewOnly(sid)))
             throw new HttpError(400, 'Subagent sessions are view-only and cannot be used for /btw from WebUI');
-        // TAL-542: the side question starts on the chat's repaired pair; the catalog is built before the chat is read.
-        await ctx.deps.sessions.deps.warmSessionModelRepair?.();
-        const s = getSession(ctx, sid);
-        if (ctx.deps.sessions.isReadOnly(s) || s.branchSourceReadonly)
+        const s = (await getSession(ctx, sid));
+        if ((await ctx.deps.sessions.isReadOnly(s)) || s.branchSourceReadonly)
             throw new HttpError(403, 'Read-only imported sessions cannot be continued from WebUI');
         const question = str(body.question).trim();
         if (!question)
             throw new HttpError(400, 'question is required');
         // TAL-518: a side question runs in its own hidden session, so the chat's running turn does not block it.
         const [model, modelProvider] = ctx.deps.sessions.turnModel(s, {});
-        const ephemeral = ctx.deps.sessionStore.newSession({ workspace: s.workspace, model, modelProvider, profile: s.profile });
+        const ephemeral = (await ctx.deps.sessionStore.newSession({ workspace: s.workspace, model, modelProvider, profile: s.profile }));
+        const context = await ctx.deps.sessions.sideQuestionContext(s);
         ephemeral.messages = structuredClone(s.messages);
-        ephemeral.context_messages = ctx.deps.sessions.sideQuestionContext(s);
+        ephemeral.context_messages = context;
         ephemeral.title = `btw: ${question.slice(0, 60)}`;
-        ctx.deps.sessionStore.save(ephemeral);
+        await ctx.deps.sessionStore.save(ephemeral);
         // TAL-512: a failed or refused btw turn must not leave its copy of the parent conversation behind.
-        const cleanup = () => { try {
-            ctx.deps.sessionStore.deleteFiles(ephemeral.session_id, { tombstone: false });
+        const cleanup = async () => { try {
+            (await ctx.deps.sessionStore.delete(ephemeral.session_id, { tombstone: false }));
         }
         catch { /* best effort */ } };
-        const started = ctx.deps.turns.start(ephemeral, { msg: question, attachments: [], workspace: s.workspace, model, modelProvider, source: 'webui', ephemeral: true, onFailed: cleanup });
+        const started = (await ctx.deps.turns.start(ephemeral, { msg: question, attachments: [], workspace: s.workspace, model, modelProvider, source: 'webui', ephemeral: true, onFailed: cleanup }));
         if (started._status !== undefined && started._status >= 400) {
-            cleanup();
+            await cleanup();
             throw new HttpError(started._status, started.error ?? 'btw start failed');
         }
         return { stream_id: str(started.stream_id), session_id: ephemeral.session_id, parent_session_id: sid };