@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/api/sessions-router.js

@@ -10,7 +10,7 @@ import { platform } from 'node:os';
 import { spawn } from 'node:child_process';
 import { ifNoneMatchMatches } from '../http/context.js';
 import { SidecarError } from '../sidecar/client.js';
-import { HttpError, requireFields } from './router.js';
+import { HttpError, RawResponse, requireFields } from './router.js';
 import { GitWorkspaceError, WORKSPACE_BUSY_MESSAGE } from '../workspace/git.js';
 import { requestSessionIdGuard } from './session-visibility.js';
 import { HttpFailure, sanitizePaths } from '../sessions/service.js';
@@ -25,6 +25,8 @@ import { randomUUID } from 'node:crypto';
 import { pyOsError, pyRepr, str } from '../util.js';
 import { ensureTrustedAuthSession, sessionCanManageServer } from '../auth/gate.js';
 import { RelayPairingError } from '../sessions/relay.js';
+import { EscapeGrantExpired } from '../workspace/escape.js';
+import { ProfileError } from '../profiles/profiles.js';
 const os = implement({ ...sessionsContract, ...workspacesContract }).$context().use(requestSessionIdGuard);
 /** Map service failures to the Python-shaped error body. */
 export function failure(error) {
@@ -32,6 +34,8 @@ export function failure(error) {
         throw new HttpError(error.status, error.message, error.extra);
     if (error instanceof SessionNotFound)
         throw new HttpError(404, 'Session not found');
+    if (error instanceof ProfileError)
+        throw new HttpError(error.status, error.message);
     throw error;
 }
 /** Handler boundary: contract outputs are pinned loose objects (index signatures), so the concrete return type is erased here like the `as never` casts elsewhere. */
@@ -62,18 +66,37 @@ function queryPositiveInt(value, fallback, maximum) {
 }
 const sanitizeError = sanitizePaths;
 /** Python `_guard_request_session_visibility` for a body/query session id. */
-function guardVisibility(ctx, sid) {
-    if (!ctx.deps.sessions.sessionIdVisible(sid))
+async function guardVisibility(ctx, sid) {
+    if (!(await ctx.deps.sessions.sessionIdVisible(sid)))
         throw new HttpError(404, 'Session not found');
 }
+/** Python `float(body["since"])` for the handoff dock: a unix time or numeric string; absent is null. */
+function handoffSince(value) {
+    if (value === undefined || value === null)
+        return null;
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN;
+    if (Number.isNaN(n))
+        throw new HttpError(400, 'since must be a unix timestamp (number)');
+    return n;
+}
+/** The handoff dock's session id and `since`, validated in the predecessor's order. */
+async function handoffInput(ctx, input) {
+    requireFields(input, 'session_id');
+    const sid = str(input.session_id).trim();
+    if (!sid)
+        throw new HttpError(400, 'session_id is required');
+    const since = handoffSince(input.since);
+    await guardVisibility(ctx, sid);
+    return { sid, since };
+}
 function allProfilesEnabled(ctx, value) {
     return queryFlag(value) && !ctx.deps.isolatedProfileMode();
 }
 /** Search inputs that select the sidebar rows rather than every stored session (TAL-308). */
 const SIDEBAR_SEARCH_KEYS = ['project_id', 'sidebar_source', 'include_archived', 'exclude_hidden', 'show_cli_sessions', 'show_claude_code_sessions', 'show_cron_sessions', 'show_webhook_sessions', 'show_kanban_sessions'];
 /** The `/api/sessions` row selection for a list or sidebar-search query (TAL-308 shares it). */
-function sidebarListParams(ctx, input) {
-    const settings = ctx.deps.settings.load();
+async function sidebarListParams(ctx, input) {
+    const settings = (await ctx.deps.settings.load());
     const overrideKeys = ['show_cli_sessions', 'show_claude_code_sessions', 'show_cron_sessions', 'show_webhook_sessions', 'show_kanban_sessions'];
     const sidebarSourceRaw = (input.sidebar_source ?? '').trim().toLowerCase();
     return {
@@ -95,32 +118,33 @@ function sidebarListParams(ctx, input) {
 }
 export const sessionsRouter = os.router({
     sessions: {
-        list: os.sessions.list.handler(({ input, context: { ctx } }) => run(() => {
-            const { body, etag } = ctx.deps.sessions.list(sidebarListParams(ctx, input));
+        list: os.sessions.list.handler(({ input, context: { ctx } }) => run(async () => {
+            const { body, etag } = await ctx.deps.sessions.list((await sidebarListParams(ctx, input)));
             ctx.extraResponseHeaders = { etag };
             if (ifNoneMatchMatches(ctx.header('if-none-match') ?? '', etag))
                 ctx.notModified = true;
             return body;
         })),
-        search: os.sessions.search.handler(({ input, context: { ctx } }) => run(() => {
+        search: os.sessions.search.handler(({ input, context: { ctx } }) => run(async () => {
             // Python: `int(depth)` falls back to 5 when malformed.
             const depthRaw = (input.depth ?? '5').trim();
             const depth = /^[+-]?\d+$/.test(depthRaw) ? Math.max(0, Number.parseInt(depthRaw, 10)) : 5;
             const opts = { content: (input.content ?? '1') === '1', depth, allProfiles: allProfilesEnabled(ctx, input.all_profiles) };
             // TAL-308: any sidebar filter answers from the sidebar's own rows; without one the store-only search stays.
             if (SIDEBAR_SEARCH_KEYS.some((k) => input[k] !== undefined)) {
-                return ctx.deps.sessions.sidebarSearch(input.q ?? '', sidebarListParams(ctx, input), { ...opts, projectId: input.project_id?.trim() || null });
+                return await ctx.deps.sessions.sidebarSearch(input.q ?? '', (await sidebarListParams(ctx, input)), { ...opts, projectId: input.project_id?.trim() || null });
             }
-            return ctx.deps.sessions.search(input.q ?? '', opts);
+            return await ctx.deps.sessions.search(input.q ?? '', opts);
         })),
-        cleanupZeroMessage: os.sessions.cleanupZeroMessage.handler(({ context: { ctx } }) => run(() => ctx.deps.sessions.cleanup(true))),
+        cleanup: os.sessions.cleanup.handler(({ context: { ctx } }) => run(async () => (await ctx.deps.sessions.cleanup(false)))),
+        cleanupZeroMessage: os.sessions.cleanupZeroMessage.handler(({ context: { ctx } }) => run(async () => (await ctx.deps.sessions.cleanup(true)))),
         // TAL-627: each id runs the single-session route's own guards, lock and cleanup, one at a time; a failure becomes
         // that id's result and the rest still run.
         bulk: os.sessions.bulk.handler(async ({ input, context: { ctx } }) => {
             const results = [];
             for (const sid of input.session_ids) {
                 try {
-                    guardVisibility(ctx, sid);
+                    await guardVisibility(ctx, sid);
                     if (input.action === 'delete') {
                         const { state_db_cleanup_failed } = await ctx.deps.sessions.delete(sid);
                         results.push({ session_id: sid, ok: true, state_db_cleanup_failed: Boolean(state_db_cleanup_failed) });
@@ -135,7 +159,8 @@ export const sessionsRouter = os.router({
                         : error instanceof HttpFailure ? [error.status, error.message]
                             : error instanceof SessionNotFound ? [404, 'Session not found']
                                 : [500, sanitizeError(error)];
-                    results.push({ session_id: sid, ok: false, status, error: message });
+                    const refused = error instanceof HttpFailure ? error.extra.refused : undefined;
+                    results.push({ session_id: sid, ok: false, status, error: message, ...(refused ? { refused } : {}) });
                 }
             }
             return { results };
@@ -145,35 +170,39 @@ export const sessionsRouter = os.router({
         // No visibility guard here: `detail()` answers 409 `session_profile_mismatch` so the frontend can switch to the owning profile.
         get: os.session.get.handler(({ input, context: { ctx } }) => run(async () => {
             await ctx.deps.sessions.deps.warmModelOptions?.();
+            await ctx.deps.turns.loadGoal(input.session_id.trim());
             try {
-                return { session: ctx.deps.sessions.detail(input.session_id, input) };
+                return { session: (await ctx.deps.sessions.detail(input.session_id, input)) };
             }
             catch (error) {
                 // Runs left on the relay by a deletion that predates `clearRelayCompletions` clear when the id is next requested.
                 const sid = input.session_id.trim();
-                if (error instanceof HttpFailure && error.status === 404 && ctx.deps.sessionStore.wasDeleted(sid))
-                    ctx.deps.relay.clearDeleted(sid, ctx.deps.activeProfile());
+                if (error instanceof HttpFailure && error.status === 404 && (await ctx.deps.sessionStore.wasDeleted(sid)))
+                    (await ctx.deps.relay.clearDeleted(sid, ctx.deps.activeProfile()));
                 throw error;
             }
         })),
-        status: os.session.status.handler(({ input, context: { ctx } }) => run(() => {
+        status: os.session.status.handler(({ input, context: { ctx } }) => run(async () => {
             if (!input.session_id)
                 throw new HttpError(400, 'Missing session_id');
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.status(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.status(input.session_id));
         })),
-        usage: os.session.usage.handler(({ input, context: { ctx } }) => run(() => {
+        usage: os.session.usage.handler(({ input, context: { ctx } }) => run(async () => {
             if (!input.session_id)
                 throw new HttpError(400, 'Missing session_id');
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.usage(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.usage(input.session_id));
         })),
         new: os.session.new.handler(({ input, context: { ctx } }) => run(async () => {
             // Python: an invisible prev_session_id is ignored (the service drops it), never an error (#5420).
             const profile = input.profile || null;
             // The middleware warms only the cookie profile's config; new-session defaults read the target's synchronously.
-            if (profile)
-                await ctx.deps.agentConfig.read(ctx.deps.profileHome(profile)).catch(() => undefined);
+            // `profileHome` refuses a profile whose home escapes the profiles root (400) before any warm-up failure is swallowed.
+            if (profile) {
+                const home = ctx.deps.profileHome(profile);
+                await ctx.deps.agentConfig.read(home).catch(() => undefined);
+            }
             let worktree = null;
             let worktreeSkipped = null;
             const explicit = 'worktree' in input;
@@ -186,8 +215,8 @@ export const sessionsRouter = os.router({
             }
             if (requested) {
                 try {
-                    let base = input.workspace ? ctx.deps.sessions.resolveNewSessionWorkspace(input, null, profile) : null;
-                    base ??= ctx.deps.workspaces.resolveTrusted(ctx.deps.workspaces.lastWorkspace(profile), profile);
+                    let base = input.workspace ? (await ctx.deps.sessions.resolveNewSessionWorkspace(input, null, profile)) : null;
+                    base ??= (await ctx.deps.workspaces.resolveTrusted((await ctx.deps.workspaces.lastWorkspace(profile)), profile));
                     const repo = base;
                     worktree = await ctx.deps.git.holdWrite(repo, () => ctx.deps.worktrees.create(repo));
                 }
@@ -205,67 +234,69 @@ export const sessionsRouter = os.router({
                     worktreeSkipped = error.message;
                 }
             }
-            const s = ctx.deps.sessions.create(input, { worktree });
-            const payload = { session: ctx.deps.sessions.publicSession(s) };
+            const s = (await ctx.deps.sessions.create(input, { worktree }));
+            const payload = { session: (await ctx.deps.sessions.publicSession(s)) };
             if (worktreeSkipped)
                 payload.worktree_skipped = worktreeSkipped;
             return payload;
         })),
         rename: os.session.rename.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
+            await guardVisibility(ctx, input.session_id);
             if (!input.title)
                 throw new HttpError(400, 'Missing required field(s): title');
-            return ctx.deps.sessions.rename(input.session_id, input.title);
+            return (await ctx.deps.sessions.rename(input.session_id, input.title));
         })),
         delete: os.session.delete.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.delete(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.delete(input.session_id));
         })),
         pin: os.session.pin.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
+            await guardVisibility(ctx, input.session_id);
             return ctx.deps.sessions.pin(input.session_id, input.pinned ?? true);
         })),
         archive: os.session.archive.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.archive(input.session_id, input.archived ?? true);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.archive(input.session_id, input.archived ?? true));
         })),
         move: os.session.move.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.move(input.session_id, input.project_id || null);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.move(input.session_id, input.project_id || null));
         })),
-        duplicate: os.session.duplicate.handler(({ input, context: { ctx } }) => run(() => {
+        duplicate: os.session.duplicate.handler(({ input, context: { ctx } }) => run(async () => {
             if (!input.session_id)
                 throw new HttpError(400, 'session_id is required');
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.duplicate(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.duplicate(input.session_id));
         })),
-        branch: os.session.branch.handler(({ input, context: { ctx } }) => run(() => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.branch(input.session_id, input);
+        branch: os.session.branch.handler(({ input, context: { ctx } }) => run(async () => {
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.branch(input.session_id, input));
         })),
         truncate: os.session.truncate.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.truncate(input.session_id, input.keep_count);
+            await guardVisibility(ctx, input.session_id);
+            // A body without `confirm_deep_truncate` is a released App's, which asked on the device before sending it.
+            const hold = input.confirm_deep_truncate === undefined ? null : { confirmToken: input.confirm_deep_truncate ? input.confirm_token ?? null : null };
+            return (await ctx.deps.sessions.truncate(input.session_id, input.keep_count, hold));
         })),
         clear: os.session.clear.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.clear(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.clear(input.session_id));
         })),
         retry: os.session.retry.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.retry(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.retry(input.session_id));
         })),
         undo: os.session.undo.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.undo(input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.undo(input.session_id));
         })),
         update: os.session.update.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.update(input.session_id, input);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.update(input.session_id, input));
         })),
         toolsets: os.session.toolsets.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.setToolsets(input.session_id, input.toolsets);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.setToolsets(input.session_id, input.toolsets));
         })),
         yoloGet: os.session.yoloGet.handler(({ input, context: { ctx } }) => run(() => ctx.deps.sessions.yolo(input.session_id))),
         yoloSet: os.session.yoloSet.handler(({ input, context: { ctx } }) => run(async () => {
@@ -285,29 +316,52 @@ export const sessionsRouter = os.router({
             const released = await ctx.deps.turns.respondApproval(sid, 'once', '', true);
             return { ok: true, yolo_enabled: Boolean(released.yolo_enabled ?? ctx.deps.sessions.yolo(sid).yolo_enabled), ...(released.stale_cleared ? { stale_cleared: true } : {}) };
         })),
-        import: os.session.import.handler(({ input, context: { ctx } }) => run(() => ctx.deps.sessions.import(input))),
+        import: os.session.import.handler(({ input, context: { ctx } }) => run(async () => (await ctx.deps.sessions.import(input)))),
         regenerateTitle: os.session.regenerateTitle.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = input.session_id;
             let session;
             try {
-                session = ctx.deps.sessionStore.get(sid);
+                session = (await ctx.deps.sessionStore.get(sid));
             }
             catch {
                 throw new HttpError(404, 'Session not found');
             }
-            if (ctx.deps.sessions.isReadOnly(session) || ctx.deps.sessions.isSubagentViewOnly(sid))
+            if ((await ctx.deps.sessions.isReadOnly(session)) || (await ctx.deps.sessions.isSubagentViewOnly(sid)))
                 throw new HttpError(403, 'Read-only imported sessions cannot regenerate titles');
             const generated = await ctx.deps.turns.generateTitle(session, { preferLatest: Boolean(input.prefer_latest) });
             if (!generated.title)
                 throw new HttpError(422, `Could not generate a better title (${generated.status || 'empty'})`);
             const current = await ctx.deps.sessions.persistGeneratedTitle(sid, generated.title, 'session_title_regenerate');
-            return { session: ctx.deps.sessions.wireRow(current), title: current.title, status: generated.status, raw_preview: generated.rawPreview.slice(0, 240) };
+            return { session: (await ctx.deps.sessions.wireRow(current)), title: current.title, status: generated.status, raw_preview: generated.rawPreview.slice(0, 240) };
+        })),
+        recoveryAudit: os.session.recoveryAudit.handler(({ context: { ctx } }) => run(async () => (await ctx.deps.sessions.recoveryAudit()))),
+        recoveryRepairSafe: os.session.recoveryRepairSafe.handler(({ context: { ctx } }) => run(async () => {
+            const result = await ctx.deps.sessions.recoveryRepairSafe();
+            if (!result.clean)
+                throw new RawResponse(409, result);
+            return result;
+        })),
+        lineageReport: os.session.lineageReport.handler(({ input, context: { ctx } }) => run(() => {
+            const sid = input.session_id ?? '';
+            if (!sid)
+                throw new HttpError(400, 'session_id required');
+            const report = ctx.deps.sessions.lineageReport(sid);
+            if (!report.found)
+                throw new HttpError(404, 'Session not found');
+            return report;
+        })),
+        compressionRecoveryStart: os.session.compressionRecoveryStart.handler(({ input, context: { ctx } }) => run(async () => {
+            requireFields(input, 'session_id');
+            const sid = str(input.session_id).trim();
+            if (!sid)
+                throw new HttpError(400, 'session_id is required');
+            return (await ctx.deps.sessions.compressionRecoveryStart(sid));
         })),
         // TAL-255: the iOS `/compress` route joins or starts the session's compression job and answers with its result.
         compress: os.session.compress.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id');
             const sid = str(input.session_id).trim();
-            guardVisibility(ctx, sid);
+            await guardVisibility(ctx, sid);
             const job = await ctx.deps.sessions.startCompression(sid, input.focus_topic || input.topic);
             await job.done;
             if (job.status === 'error')
@@ -317,47 +371,56 @@ export const sessionsRouter = os.router({
         compressStart: os.session.compressStart.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id');
             const sid = str(input.session_id).trim();
-            guardVisibility(ctx, sid);
+            await guardVisibility(ctx, sid);
             return compressionStatusPayload(await ctx.deps.sessions.startCompression(sid, input.focus_topic || input.topic));
         })),
-        compressStatus: os.session.compressStatus.handler(({ input, context: { ctx } }) => run(() => {
+        // TAL-258: the handoff dock. Rounds decides when to offer it; the summary is generated and appended to the transcript.
+        conversationRounds: os.session.conversationRounds.handler(({ input, context: { ctx } }) => run(async () => {
+            const { sid, since } = (await handoffInput(ctx, input));
+            return (await ctx.deps.sessions.conversationRounds(sid, since));
+        })),
+        handoffSummary: os.session.handoffSummary.handler(({ input, context: { ctx } }) => run(async () => {
+            const { sid, since } = (await handoffInput(ctx, input));
+            return (await ctx.deps.sessions.handoffSummary(sid, since));
+        })),
+        compressStatus: os.session.compressStatus.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = input.session_id.trim();
             if (!sid)
                 throw new HttpError(400, 'session_id is required');
-            guardVisibility(ctx, sid);
-            const job = ctx.deps.sessions.compressionJob(sid);
+            await guardVisibility(ctx, sid);
+            const job = (await ctx.deps.sessions.compressionJob(sid));
             return (job ? compressionStatusPayload(job) : { ok: true, status: 'idle', session_id: sid });
         })),
-        draftGet: os.session.draftGet.handler(({ input, context: { ctx } }) => run(() => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.readDraft(input.session_id);
+        draftGet: os.session.draftGet.handler(({ input, context: { ctx } }) => run(async () => {
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.readDraft(input.session_id));
         })),
         draftSave: os.session.draftSave.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.writeDraft(input);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.writeDraft(input));
         })),
-        anchorSceneGet: os.session.anchorSceneGet.handler(({ input, context: { ctx } }) => run(() => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.readAnchorScene(input);
+        anchorSceneGet: os.session.anchorSceneGet.handler(({ input, context: { ctx } }) => run(async () => {
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.readAnchorScene(input));
         })),
-        toolResult: os.session.toolResult.handler(({ input, context: { ctx } }) => run(() => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.readToolResult(input);
+        toolResult: os.session.toolResult.handler(({ input, context: { ctx } }) => run(async () => {
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.readToolResult(input));
         })),
         anchorSceneSave: os.session.anchorSceneSave.handler(({ input, context: { ctx } }) => run(async () => {
-            guardVisibility(ctx, input.session_id);
-            return ctx.deps.sessions.saveAnchorScene(input);
+            await guardVisibility(ctx, input.session_id);
+            return (await ctx.deps.sessions.saveAnchorScene(input));
         })),
     },
     projects: {
-        list: os.projects.list.handler(({ input, context: { ctx } }) => run(() => {
+        list: os.projects.list.handler(({ input, context: { ctx } }) => run(async () => {
             const activeProfile = ctx.deps.activeProfile();
-            const all = ctx.deps.projects.load();
+            const all = (await ctx.deps.projects.load());
             const allProfiles = allProfilesEnabled(ctx, input.all_profiles);
             const scoped = allProfiles ? all : all.filter((p) => ctx.deps.profilesMatch(p.profile ?? null, activeProfile));
             return { projects: scoped, all_profiles: allProfiles, active_profile: activeProfile, other_profile_count: allProfiles || ctx.deps.isolatedProfileMode() ? 0 : all.length - scoped.length };
         })),
-        create: os.projects.create.handler(({ input, context: { ctx } }) => run(() => {
+        create: os.projects.create.handler(({ input, context: { ctx } }) => run(async () => {
             const name = input.name.trim().slice(0, 128);
             if (!name)
                 throw new HttpError(400, 'name required');
@@ -367,43 +430,43 @@ export const sessionsRouter = os.router({
             const requested = (input.profile ?? '').trim();
             if (requested && requested !== 'default' && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(requested))
                 throw new HttpError(400, 'invalid profile');
-            const projects = ctx.deps.projects.load();
             const proj = { project_id: randomUUID().replace(/-/g, '').slice(0, 12), name, color, profile: requested || ctx.deps.activeProfile() || 'default', created_at: ctx.deps.auth.now() };
-            projects.push(proj);
-            ctx.deps.projects.save(projects);
+            await ctx.deps.projects.mutate((projects) => { projects.push(proj); });
             ctx.deps.events.publish('project_create', { profile: proj.profile });
             return { ok: true, project: proj };
         })),
-        rename: os.projects.rename.handler(({ input, context: { ctx } }) => run(() => {
-            const projects = ctx.deps.projects.load();
-            const proj = projects.find((p) => p.project_id === input.project_id);
+        rename: os.projects.rename.handler(({ input, context: { ctx } }) => run(async () => {
             const activeProfile = ctx.deps.activeProfile();
-            if (!proj || !ctx.deps.profilesMatch(proj.profile ?? null, activeProfile))
-                throw new HttpError(404, 'Project not found');
-            requireFields(input, 'project_id', 'name');
-            proj.name = input.name.trim().slice(0, 128);
-            if ('color' in input) {
-                const color = input.color ?? null;
-                if (color && !/^#[0-9a-fA-F]{3,8}$/.test(color))
-                    throw new HttpError(400, 'Invalid color format');
-                proj.color = color;
-            }
-            ctx.deps.projects.save(projects);
+            const proj = await ctx.deps.projects.mutate((projects) => {
+                const proj = projects.find((p) => p.project_id === input.project_id);
+                if (!proj || !ctx.deps.profilesMatch(proj.profile ?? null, activeProfile))
+                    throw new HttpError(404, 'Project not found');
+                requireFields(input, 'project_id', 'name');
+                proj.name = input.name.trim().slice(0, 128);
+                if ('color' in input) {
+                    const color = input.color ?? null;
+                    if (color && !/^#[0-9a-fA-F]{3,8}$/.test(color))
+                        throw new HttpError(400, 'Invalid color format');
+                    proj.color = color;
+                }
+                return proj;
+            });
             ctx.deps.events.publish('project_rename', { profile: activeProfile });
             return { ok: true, project: proj };
         })),
-        delete: os.projects.delete.handler(({ input, context: { ctx } }) => run(() => {
-            let projects = ctx.deps.projects.load();
-            const proj = projects.find((p) => p.project_id === input.project_id);
+        delete: os.projects.delete.handler(({ input, context: { ctx } }) => run(async () => {
             const activeProfile = ctx.deps.activeProfile();
-            if (!proj || !ctx.deps.profilesMatch(proj.profile ?? null, activeProfile))
-                throw new HttpError(404, 'Project not found');
-            projects = projects.filter((p) => p.project_id !== input.project_id);
-            ctx.deps.projects.save(projects);
+            await ctx.deps.projects.mutate((projects) => {
+                const position = projects.findIndex((p) => p.project_id === input.project_id);
+                const proj = projects[position];
+                if (!proj || !ctx.deps.profilesMatch(proj.profile ?? null, activeProfile))
+                    throw new HttpError(404, 'Project not found');
+                projects.splice(position, 1);
+            });
             const store = ctx.deps.sessionStore;
             const activeIds = ctx.deps.sessions.deps.runtime.activeStreamIds;
             try {
-                for (const entry of store.readIndexEntries()) {
+                for (const entry of (await store.readIndexEntries())) {
                     if (entry.project_id !== input.project_id)
                         continue;
                     const sid = str(entry.session_id);
@@ -415,9 +478,9 @@ export const sessionsRouter = os.router({
                                 continue;
                             }
                         }
-                        const s = store.get(sid);
+                        const s = (await store.get(sid));
                         s.project_id = null;
-                        store.save(s);
+                        await store.save(s);
                     }
                     catch { /* one slow or failing session never aborts the request */ }
                 }
@@ -442,36 +505,36 @@ export const sessionsRouter = os.router({
             const bound = str(session?.bound_profile).trim() || null;
             return relayCall(() => Promise.resolve(ctx.deps.relay.presence.update(input, ctx.deps.isRootProfile(bound ?? ctx.deps.activeProfile()) ? 'default' : (bound ?? ctx.deps.activeProfile()))));
         }),
-        viewed: os.talaria.viewed.handler(({ input, context: { ctx } }) => run(() => {
-            ctx.deps.relay.markViewed(input.session_id.trim());
+        viewed: os.talaria.viewed.handler(({ input, context: { ctx } }) => run(async () => {
+            await ctx.deps.relay.markViewed(input.session_id.trim());
             return { ok: true };
         })),
     },
     share: {
-        create: os.share.create.handler(({ input, context: { ctx } }) => run(() => {
+        create: os.share.create.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = input.session_id.trim();
             if (!sid)
                 throw new HttpError(400, 'session_id is required');
-            return ctx.deps.sessions.createShare(sid);
+            return (await ctx.deps.sessions.createShare(sid));
         })),
-        revoke: os.share.revoke.handler(({ input, context: { ctx } }) => run(() => {
+        revoke: os.share.revoke.handler(({ input, context: { ctx } }) => run(async () => {
             const sid = input.session_id.trim();
             if (!sid)
                 throw new HttpError(400, 'session_id is required');
-            return ctx.deps.sessions.revokeShare(sid);
+            return (await ctx.deps.sessions.revokeShare(sid));
         })),
-        read: os.share.read.handler(({ input, context: { ctx } }) => run(() => {
+        read: os.share.read.handler(({ input, context: { ctx } }) => run(async () => {
             ctx.extraResponseHeaders = { 'x-robots-tag': 'noindex, nofollow' };
-            return ctx.deps.sessions.loadShare(input.token.trim());
+            return (await ctx.deps.sessions.loadShare(input.token.trim()));
         })),
     },
     workspaces: {
-        list: os.workspaces.list.handler(({ context: { ctx } }) => run(() => {
+        list: os.workspaces.list.handler(({ context: { ctx } }) => run(async () => {
             const profile = ctx.deps.activeProfile();
-            return { workspaces: ctx.deps.workspaces.load(profile), last: ctx.deps.workspaces.lastWorkspace(profile), terminal_remote_backend: ctx.deps.features().terminal_remote_backend };
+            return { workspaces: (await ctx.deps.workspaces.load(profile)), last: (await ctx.deps.workspaces.lastWorkspace(profile)), terminal_remote_backend: ctx.deps.features().terminal_remote_backend };
         })),
-        suggest: os.workspaces.suggest.handler(({ input, context: { ctx } }) => run(() => ({ suggestions: ctx.deps.workspaces.suggest(input.prefix ?? '', 12, ctx.deps.activeProfile()), prefix: input.prefix ?? '' }))),
-        add: os.workspaces.add.handler(({ input, context: { ctx } }) => run(() => {
+        suggest: os.workspaces.suggest.handler(({ input, context: { ctx } }) => run(async () => ({ suggestions: (await ctx.deps.workspaces.suggest(input.prefix ?? '', 12, ctx.deps.activeProfile())), prefix: input.prefix ?? '' }))),
+        add: os.workspaces.add.handler(({ input, context: { ctx } }) => run(async () => {
             const ws = ctx.deps.workspaces;
             const pathStr = stripSurroundingQuotes(input.path.trim());
             const name = (input.name ?? '').trim();
@@ -510,42 +573,42 @@ export const sessionsRouter = os.router({
             catch (error) {
                 throw new HttpError(400, error.message);
             }
-            const list = ws.load(profile);
+            const list = (await ws.load(profile));
             if (list.some((w) => w.path === p))
                 throw new HttpError(400, 'Workspace already in list');
             list.push({ path: p, name: name || basename(p) });
-            ws.save(list, profile);
+            await ws.save(list, profile);
             return { ok: true, workspaces: list };
         })),
-        remove: os.workspaces.remove.handler(({ input, context: { ctx } }) => run(() => {
+        remove: os.workspaces.remove.handler(({ input, context: { ctx } }) => run(async () => {
             const pathStr = input.path.trim();
             if (!pathStr)
                 throw new HttpError(400, 'path is required');
             const profile = ctx.deps.activeProfile();
-            const list = ctx.deps.workspaces.load(profile).filter((w) => w.path !== pathStr);
-            ctx.deps.workspaces.save(list, profile);
+            const list = (await ctx.deps.workspaces.load(profile)).filter((w) => w.path !== pathStr);
+            await ctx.deps.workspaces.save(list, profile);
             return { ok: true, workspaces: list };
         })),
-        rename: os.workspaces.rename.handler(({ input, context: { ctx } }) => run(() => {
+        rename: os.workspaces.rename.handler(({ input, context: { ctx } }) => run(async () => {
             const pathStr = input.path.trim();
             const name = input.name.trim();
             if (!pathStr || !name)
                 throw new HttpError(400, 'path and name are required');
             const profile = ctx.deps.activeProfile();
-            const list = ctx.deps.workspaces.load(profile);
+            const list = (await ctx.deps.workspaces.load(profile));
             const entry = list.find((w) => w.path === pathStr);
             if (!entry)
                 throw new HttpError(404, 'Workspace not found');
             entry.name = name;
-            ctx.deps.workspaces.save(list, profile);
+            await ctx.deps.workspaces.save(list, profile);
             return { ok: true, workspaces: list };
         })),
-        reorder: os.workspaces.reorder.handler(({ input, context: { ctx } }) => run(() => {
+        reorder: os.workspaces.reorder.handler(({ input, context: { ctx } }) => run(async () => {
             const paths = input.paths;
             if (!Array.isArray(paths) || !paths.length)
                 throw new HttpError(400, 'paths is required and must be a list');
             const profile = ctx.deps.activeProfile();
-            const list = ctx.deps.workspaces.load(profile);
+            const list = (await ctx.deps.workspaces.load(profile));
             const byPath = new Map(list.map((w) => [w.path, w]));
             const reordered = [];
             const seen = new Set();
@@ -560,18 +623,18 @@ export const sessionsRouter = os.router({
             for (const w of list)
                 if (!seen.has(w.path))
                     reordered.push(w);
-            ctx.deps.workspaces.save(reordered, profile);
+            await ctx.deps.workspaces.save(reordered, profile);
             return { ok: true, workspaces: reordered };
         })),
     },
     files: {
-        list: os.files.list.handler(({ input, context: { ctx } }) => run(() => {
+        list: os.files.list.handler(({ input, context: { ctx } }) => run(async () => {
             if (!input.session_id)
                 throw new HttpError(400, 'session_id is required');
-            guardVisibility(ctx, input.session_id);
+            await guardVisibility(ctx, input.session_id);
             // Python `_handle_list` resolved the workspace directly and answered 404 with the trust error; the POST file ops
             // keep `get_session_for_file_ops`' lenient fallback.
-            const s = fileOpsSession(ctx, input.session_id, { strictWorkspace: true });
+            const s = (await fileOpsSession(ctx, input.session_id, { strictWorkspace: true }));
             const rel = input.path ?? '.';
             try {
                 const entries = listDir(s.workspace, rel);
@@ -581,11 +644,11 @@ export const sessionsRouter = os.router({
                 throw fileError(error, 404);
             }
         })),
-        read: os.files.read.handler(({ input, context: { ctx } }) => run(() => {
+        read: os.files.read.handler(({ input, context: { ctx } }) => run(async () => {
             if (!input.session_id)
                 throw new HttpError(400, 'session_id is required');
-            guardVisibility(ctx, input.session_id);
-            const s = fileOpsSession(ctx, input.session_id);
+            await guardVisibility(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             if (!input.path)
                 throw new HttpError(400, 'path is required');
             try {
@@ -596,9 +659,9 @@ export const sessionsRouter = os.router({
                 throw fileError(error, 404);
             }
         })),
-        save: os.files.save.handler(({ input, context: { ctx } }) => run(() => {
+        save: os.files.save.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 if (['.docx', '.xlsx', '.pptx'].includes(extname(input.path).toLowerCase()))
                     throw new HttpError(400, 'Office documents cannot be saved from the Web UI');
@@ -625,9 +688,9 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
-        create: os.files.create.handler(({ input, context: { ctx } }) => run(() => {
+        create: os.files.create.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const root = s.workspace;
                 assertWorkspaceFree(ctx, root);
@@ -650,9 +713,9 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
-        createDir: os.files.createDir.handler(({ input, context: { ctx } }) => run(() => {
+        createDir: os.files.createDir.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const root = s.workspace;
                 assertWorkspaceFree(ctx, root);
@@ -666,9 +729,9 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
-        delete: os.files.delete.handler(({ input, context: { ctx } }) => run(() => {
+        delete: os.files.delete.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const root = s.workspace;
                 assertWorkspaceFree(ctx, root);
@@ -690,9 +753,9 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
-        rename: os.files.rename.handler(({ input, context: { ctx } }) => run(() => {
+        rename: os.files.rename.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path', 'new_name');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const root = s.workspace;
                 assertWorkspaceFree(ctx, root);
@@ -717,10 +780,10 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
-        move: os.files.move.handler(({ input, context: { ctx } }) => run(() => {
+        move: os.files.move.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields({ ...input, dest_dir: input.dest_dir ?? input.destination }, 'session_id', 'path', 'dest_dir');
             const destDirRaw = (input.dest_dir ?? input.destination ?? '.').trim() || '.';
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const root = s.workspace;
                 assertWorkspaceFree(ctx, root);
@@ -753,7 +816,7 @@ export const sessionsRouter = os.router({
         })),
         reveal: os.files.reveal.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const target = safeResolve(s.workspace, input.path);
                 if (!existsSync(target))
@@ -772,9 +835,19 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
+        path: os.files.path.handler(({ input, context: { ctx } }) => run(async () => {
+            requireFields(input, 'session_id', 'path');
+            const s = (await fileOpsSession(ctx, input.session_id));
+            try {
+                return { ok: true, path: safeResolve(s.workspace, input.path) };
+            }
+            catch (error) {
+                throw fileError(error);
+            }
+        })),
         openVsCode: os.files.openVsCode.handler(({ input, context: { ctx } }) => run(async () => {
             requireFields(input, 'session_id', 'path');
-            const s = fileOpsSession(ctx, input.session_id);
+            const s = (await fileOpsSession(ctx, input.session_id));
             try {
                 const target = safeResolve(s.workspace, input.path);
                 if (!existsSync(target))
@@ -790,8 +863,65 @@ export const sessionsRouter = os.router({
                 throw fileError(error);
             }
         })),
+        escapeAuthorize: os.files.escapeAuthorize.handler(({ input, context: { ctx } }) => run(async () => {
+            // A Referer alone is not a browser fetch: Python required `Origin`, which the global CSRF check has already matched.
+            if (!ctx.header('origin'))
+                throw new HttpError(403, 'browser origin required');
+            if (input.token?.trim())
+                throw new HttpError(400, 'token must not be provided');
+            const sid = (input.session_id ?? '').trim();
+            const rel = (input.path ?? '').trim();
+            if (!sid)
+                throw new HttpError(400, 'session_id is required');
+            if (!rel)
+                throw new HttpError(400, 'path is required');
+            const s = (await fileOpsSession(ctx, sid));
+            try {
+                return ctx.deps.escapeGrants.authorize(s.workspace, sid, s.profile, rel);
+            }
+            catch (error) {
+                throw fileError(error, 404);
+            }
+        })),
+        escapeList: os.files.escapeList.handler(({ input, context: { ctx } }) => run(async () => {
+            const req = (await escapeRequest(ctx, input.session_id, input.token, input.path ?? '.'));
+            try {
+                const listing = ctx.deps.escapeGrants.list(req);
+                return { ...listing, entries: serializeEntriesForBrowser(listing.entries) };
+            }
+            catch (error) {
+                throw fileError(error, 404);
+            }
+        })),
+        escapeRead: os.files.escapeRead.handler(({ input, context: { ctx } }) => run(async () => {
+            const req = (await escapeRequest(ctx, input.session_id, input.token, input.path ?? ''));
+            try {
+                const file = ctx.deps.escapeGrants.read(req);
+                // The frame loads the bytes through the same grant; the workspace preview grant would outlive and skip its re-checks.
+                return file.preview === 'html' ? { ...file, preview_url: `api/escape/file/raw?${new URLSearchParams({ session_id: String(input.session_id), token: String(input.token), path: req.requestPath, inline: '1' }).toString()}` } : file;
+            }
+            catch (error) {
+                throw fileError(error, 404);
+            }
+        })),
     },
 });
+/** The escape routes' shared front half: required ids, the session, and the grant re-check (403 when it fails). */
+export async function escapeRequest(ctx, sid, token, rel) {
+    if (!sid)
+        throw new HttpError(400, 'session_id is required');
+    if (!token)
+        throw new HttpError(400, 'token is required');
+    const s = (await fileOpsSession(ctx, sid));
+    try {
+        return ctx.deps.escapeGrants.resolve(s.workspace, sid, s.profile, token, rel);
+    }
+    catch (error) {
+        if (error instanceof EscapeGrantExpired)
+            throw new HttpError(403, error.message);
+        throw fileError(error, 404);
+    }
+}
 function isSymlinkAt(path) {
     try {
         return lstatSync(path).isSymbolicLink();
@@ -805,7 +935,7 @@ function assertWorkspaceFree(ctx, path) {
     if (ctx.deps.git.workspaceBusy(path))
         throw new HttpError(409, WORKSPACE_BUSY_MESSAGE);
 }
-function fileError(error, notFoundStatus = 400) {
+export function fileError(error, notFoundStatus = 400) {
     if (error instanceof HttpError)
         return error;
     if (error instanceof HttpFailure)
@@ -821,10 +951,10 @@ function fileError(error, notFoundStatus = 400) {
  * `state.db` but that has no `sessions/<sid>.json` (CLI, messaging) is served as an external view bound to the active
  * workspace, as the sidebar already lists it (issue #3280).
  */
-export function fileOpsSession(ctx, sid, opts = {}) {
+export async function fileOpsSession(ctx, sid, opts = {}) {
     let session;
     try {
-        session = ctx.deps.sessionStore.get(sid, { metadataOnly: true });
+        session = (await ctx.deps.sessionStore.get(sid, { metadataOnly: true }));
     }
     catch {
         const profile = ctx.deps.activeProfile();
@@ -832,7 +962,7 @@ export function fileOpsSession(ctx, sid, opts = {}) {
             throw new HttpError(404, 'Session not found');
         if (!ctx.deps.workspaces.profileSupportsLocalIo(profile))
             throw new HttpError(400, REMOTE_WORKSPACE_UNSUPPORTED_CODE, { message: REMOTE_WORKSPACE_UNSUPPORTED_MESSAGE });
-        return { workspace: ctx.deps.workspaces.lastWorkspace(profile), profile, recovered: false, session: null };
+        return { workspace: (await ctx.deps.workspaces.lastWorkspace(profile)), profile, recovered: false, session: null };
     }
     if (!ctx.deps.profilesMatch(session.profile, ctx.deps.activeProfile()))
         throw new HttpError(404, 'Session not found');
@@ -842,7 +972,7 @@ export function fileOpsSession(ctx, sid, opts = {}) {
     let recovered = false;
     try {
         ;
-        [workspace, recovered] = ctx.deps.workspaces.resolveImplicitWithRecovery(session.workspace, (p) => ctx.deps.workspaces.lastWorkspace(p), session.profile);
+        [workspace, recovered] = (await ctx.deps.workspaces.resolveImplicitWithRecovery(session.workspace, async (p) => (await ctx.deps.workspaces.lastWorkspace(p)), session.profile));
     }
     catch (error) {
         if (opts.strictWorkspace)
@@ -855,10 +985,10 @@ export function fileOpsSession(ctx, sid, opts = {}) {
         if (cached)
             cached.workspace = workspace;
         try {
-            const full = ctx.deps.sessionStore.load(sid);
+            const full = (await ctx.deps.sessionStore.load(sid));
             if (full) {
                 full.workspace = workspace;
-                ctx.deps.sessionStore.save(full, { touchUpdatedAt: false });
+                (await ctx.deps.sessionStore.save(full, { touchUpdatedAt: false }));
             }
         }
         catch { /* recovery persistence is best effort */ }