@sema-agent/server 1.290.0 → 1.292.0

package/README.md

@@ -134,7 +134,7 @@ The server is configured entirely through environment variables. The most import
 | `MODEL_ID` | `Qwen3.5-35B` | Default model id |
 | `MODEL_API_KEY` | — | Gateway API key (optional) |
 | `SERVICE_AUTH_TOKEN` | — | Callers must send `Authorization: Bearer <token>` |
-| `DB_BACKEND` | `mysql` | SQL engine: `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB; `tidb` is an alias) / `pg` (PostgreSQL) / `local` (file-backed, no DB). Setting `mysql`/`pg` explicitly also switches sessions to durable |
+| `DB_BACKEND` | `local`* | `mysql` (any MySQL-protocol DB: MySQL/TiDB/MariaDB; `tidb` alias) / `pg` (PostgreSQL) / `local` (file-backed, no DB) / `memory` (explicit in-memory: nothing survives a restart, durable-runs faces 501). *Bare boot (no DB env at all) defaults to `local` so a single-user machine keeps its runs across restarts; any SQL signal (`SESSION_BACKEND` or `TIDB_/MYSQL_/PG_HOST`) keeps the `mysql` engine default, and `REQUIRE_PRINCIPAL=true` bare boots stay `memory` (the local file store has no tenant isolation — a warning says so). A DEFAULT-derived `local` that cannot create its data root degrades to memory with a warning + the `store_backend_degraded` gauge; an EXPLICIT `DB_BACKEND=local` fails loud instead. Setting `mysql`/`pg` explicitly also switches sessions to durable |
 | `SESSION_BACKEND` | `memory`* | `memory` / `mysql` (durable session center; `tidb` alias) / `auto`. *Defaults to durable when `DB_BACKEND` is explicitly `mysql`/`pg` |
 | `REMOTE_EXEC` | unset | Sandbox execution lane: `host` / `local-docker` / `e2b` / `k8s` / `ssh` / `adb`; unset = in-process stub (with `CONFIG_PROVIDER=local` the default becomes `host`) |
 | `CONFIG_PROVIDER` | unset | Config source: `local` (file-backed `config.d/`, single machine) / `remote` (registry control plane) |

package/dist/config.d.ts

@@ -141,7 +141,8 @@ export interface ServiceConfig {
         database: string;
         connectionLimit?: number;
     };
-    dbBackend: "mysql" | "pg" | "local";
+    dbBackend: "mysql" | "pg" | "local" | "memory";
+    dbBackendExplicit: boolean;
     localDataRoot?: string;
     pg?: {
         host: string;

package/dist/config.js

@@ -168,9 +168,22 @@ export function loadConfig() {
     const modelId = env("MODEL_ID", "Qwen3.5-35B");
     const singleUserTurnkey = process.env.REQUIRE_PRINCIPAL !== "true";
     const postureOn = (envVal, infraReady = true) => envVal === "true" ? true : envVal === "false" ? false : singleUserTurnkey && infraReady;
-    const dbBackendRaw = enumEnv("DB_BACKEND", "mysql", ["mysql", "tidb", "pg", "local"]);
+    const dbBackendSet = !!process.env.DB_BACKEND;
+    const sqlSignal = (!!process.env.SESSION_BACKEND && process.env.SESSION_BACKEND !== "memory") ||
+        !!(process.env.TIDB_HOST || process.env.MYSQL_HOST || process.env.PG_HOST);
+    const bareBoot = !dbBackendSet && !sqlSignal;
+    const multiTenantBareBoot = bareBoot && process.env.REQUIRE_PRINCIPAL === "true";
+    const dbBackendRaw = enumEnv("DB_BACKEND", bareBoot ? (multiTenantBareBoot ? "memory" : "local") : "mysql", ["mysql", "tidb", "pg", "local", "memory"]);
     const dbBackend = dbBackendRaw === "tidb" ? "mysql" : dbBackendRaw;
-    const sqlEngineExplicit = !!process.env.DB_BACKEND && dbBackend !== "local";
+    if (multiTenantBareBoot) {
+        CONFIG_NOTICES.push({
+            event: "db_backend_default_memory_multi_tenant",
+            fields: {
+                note: "REQUIRE_PRINCIPAL=true with no DB_BACKEND — the single-user default (local file store) is incompatible with multi-tenant (no tenant isolation in the file owner map), so this deployment runs IN-MEMORY (runs/sessions lost on restart, durable runs 501). Configure DB_BACKEND=mysql|pg for a durable multi-tenant deployment.",
+            },
+        });
+    }
+    const sqlEngineExplicit = !!process.env.DB_BACKEND && dbBackend !== "local" && dbBackend !== "memory";
     const sessionBackendRaw = enumEnv("SESSION_BACKEND", sqlEngineExplicit ? "mysql" : "memory", ["memory", "mysql", "tidb", "auto"]);
     const sessionBackend = sessionBackendRaw === "mysql" ? "tidb" : sessionBackendRaw;
     const memoryEngineEnabled = process.env.MEMORY_ENGINE !== "off";
@@ -487,6 +500,7 @@ export function loadConfig() {
             }
             : undefined,
         dbBackend,
+        dbBackendExplicit: dbBackendSet,
         localDataRoot,
         tidb: needsDb && dbBackend === "mysql"
             ? {

package/dist/env-facts.d.ts

@@ -25,6 +25,11 @@ export declare function resumeFactsForLane(provider: "e2b" | "k8s" | "ssh" | "ad
 export declare function scratchpadSessionSegment(sessionId: string): string;
 export declare function scratchpadDirFor(localDataRoot: string, sessionId: string): string;
 export declare function ensureScratchpadDir(localDataRoot: string, sessionId: string): Promise<string | undefined>;
+export declare function acceptShellScratchpadDir(raw: unknown, opts: {
+    requirePrincipal: boolean;
+    hostSemanticsLane: boolean;
+    warn: (msg: string, meta?: object) => void;
+}): Promise<string | undefined>;
 export declare function purgeScratchpadDir(localDataRoot: string, sessionId: string): Promise<void>;
 export declare function sweepStaleScratchpads(localDataRoot: string, opts: {
     olderThanMs: number;

package/dist/env-facts.js

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 const MAX_STR = 64;
@@ -59,6 +59,40 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
         return undefined;
     }
 }
+export async function acceptShellScratchpadDir(raw, opts) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    if (opts.requirePrincipal) {
+        opts.warn("shell_scratchpad_ignored", { reason: "multi_tenant", note: "tenant-supplied exempt dir on a shared worker disk — server-computed scratchpad used instead" });
+        return undefined;
+    }
+    if (!opts.hostSemanticsLane) {
+        opts.warn("shell_scratchpad_ignored", { reason: "remote_lane", note: "worker-local path is not real to remote-sandbox hands — in-sandbox scratchpad used instead" });
+        return undefined;
+    }
+    if (!isAbsolute(raw)) {
+        opts.warn("shell_scratchpad_ignored", { reason: "not_absolute" });
+        return undefined;
+    }
+    if (raw.length > MAX_PATH) {
+        opts.warn("shell_scratchpad_ignored", { reason: "too_long", length: raw.length, max: MAX_PATH });
+        return undefined;
+    }
+    const canonical = resolve(raw);
+    const depth = canonical.split(sep).filter((s) => s.length > 0).length;
+    if (depth < 3) {
+        opts.warn("shell_scratchpad_ignored", { reason: "too_shallow", canonical });
+        return undefined;
+    }
+    try {
+        await mkdir(canonical, { recursive: true });
+        return canonical;
+    }
+    catch (err) {
+        opts.warn("shell_scratchpad_ignored", { reason: "mkdir_failed", error: err instanceof Error ? err.message : String(err) });
+        return undefined;
+    }
+}
 export async function purgeScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {

package/dist/fleet/fleet-bus.d.ts

@@ -23,6 +23,20 @@ export interface FleetTaskRow {
     };
     toolUses?: number;
     transcriptId?: string;
+    stoppedBy?: string;
+    usage?: {
+        totalTokens?: number;
+        toolUses?: number;
+        durationMs?: number;
+        tokens?: number;
+        turns?: number;
+        costMicroUsd?: number;
+    };
+    resumable?: boolean;
+    editedFiles?: Array<{
+        path: string;
+        edits: number;
+    }>;
 }
 export interface FleetWorkflowRow {
     id: string;
@@ -161,9 +175,27 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
         status?: string;
     }) => void;
     onChildTerminal: (taskId: string, status: string, altId?: string, toolUseId?: string) => boolean;
-    onTerminal: (status: string) => void;
+    onTerminal: (status: string, residuals?: {
+        usage?: FleetTaskRow["usage"];
+        stoppedBy?: string;
+        transcriptId?: string;
+    }) => void;
 };
 export type FleetRunPublisher = ReturnType<typeof fleetRunPublisher>;
+export declare function fleetRunResiduals(result: {
+    sessionId?: string;
+    errorCode?: string;
+    stats?: {
+        turns?: number;
+        tokens?: number;
+        toolCalls?: number;
+        costMicroUsd?: number;
+    };
+} | null | undefined): {
+    usage?: FleetTaskRow["usage"];
+    stoppedBy?: string;
+    transcriptId?: string;
+};
 export declare function fleetBackgroundChildPublisher(bus?: FleetEventBus, log?: (msg: string, fields: Record<string, unknown>) => void): (e: import("@sema-agent/core").BackgroundChildEvent) => void;
 export declare function fleetRunLabels(objective: string | undefined): {
     name: string;

package/dist/fleet/fleet-bus.js

@@ -136,21 +136,47 @@ export function fleetRunPublisher(bus, run) {
             }
             return hadRow;
         },
-        onTerminal(status) {
+        onTerminal(status, residuals) {
             settledLeg = true;
             const fleetStatus = runStatusToFleet(status);
-            bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt });
+            const terminal = fleetStatus === "completed" || fleetStatus === "failed" || fleetStatus === "killed";
+            const res = terminal && residuals
+                ? {
+                    ...(residuals.usage ? { usage: residuals.usage } : {}),
+                    ...(residuals.stoppedBy ? { stoppedBy: residuals.stoppedBy } : {}),
+                    ...(residuals.transcriptId ? { transcriptId: residuals.transcriptId } : {}),
+                }
+                : {};
+            bus.publishTask({ id: run.runId, status: fleetStatus, tokens, elapsedMs: Date.now() - startedAt, ...res });
             for (const cid of children)
                 bus.removeTask(cid);
             children.clear();
             childStartedAt.clear();
             childByToolCall.clear();
-            if (fleetStatus === "completed" || fleetStatus === "failed" || fleetStatus === "killed") {
+            if (terminal) {
                 bus.removeTask(run.runId);
             }
         },
     };
 }
+export function fleetRunResiduals(result) {
+    if (!result)
+        return {};
+    const s = result.stats;
+    const usage = s
+        ? {
+            ...(typeof s.tokens === "number" ? { totalTokens: s.tokens } : {}),
+            ...(typeof s.turns === "number" ? { turns: s.turns } : {}),
+            ...(typeof s.toolCalls === "number" ? { toolUses: s.toolCalls } : {}),
+            ...(typeof s.costMicroUsd === "number" ? { costMicroUsd: s.costMicroUsd } : {}),
+        }
+        : {};
+    return {
+        ...(Object.keys(usage).length > 0 ? { usage } : {}),
+        ...(result.errorCode === "cancelled" ? { stoppedBy: "user" } : {}),
+        ...(result.sessionId ? { transcriptId: result.sessionId } : {}),
+    };
+}
 export function fleetBackgroundChildPublisher(bus, log) {
     if (!bus)
         return () => undefined;
@@ -325,7 +351,25 @@ export function fleetBackgroundChildPublisher(bus, log) {
             return;
         }
         const status = e.status === "completed" ? "completed" : e.status === "killed" ? "killed" : "failed";
-        bus.publishTask({ id: e.taskId, ...rowTags(m), status });
+        bus.publishTask({
+            id: e.taskId, ...rowTags(m), status,
+            ...(e.stoppedBy ? { stoppedBy: e.stoppedBy } : {}),
+            ...(e.resumable !== undefined ? { resumable: e.resumable } : {}),
+            ...(e.transcriptId ? { transcriptId: e.transcriptId } : {}),
+            ...(e.editedFiles !== undefined ? { editedFiles: e.editedFiles.slice(0, 100).map((f) => ({ path: redactSecrets(f.path), edits: f.edits })) } : {}),
+            ...(e.usage
+                ? {
+                    usage: {
+                        ...(e.usage.totalTokens !== undefined ? { totalTokens: e.usage.totalTokens } : {}),
+                        ...(e.usage.toolUses !== undefined ? { toolUses: e.usage.toolUses } : {}),
+                        ...(e.usage.durationMs !== undefined ? { durationMs: e.usage.durationMs } : {}),
+                        ...(e.usage.tokens !== undefined ? { tokens: e.usage.tokens } : {}),
+                        ...(e.usage.turns !== undefined ? { turns: e.usage.turns } : {}),
+                        ...(e.usage.costMicroUsd !== undefined ? { costMicroUsd: e.usage.costMicroUsd } : {}),
+                    },
+                }
+                : {}),
+        });
         bus.removeTask(e.taskId);
         if (m.aliasUuid) {
             const tail = ` ${m.aliasUuid}`;

package/dist/http/server.d.ts

@@ -221,6 +221,7 @@ export interface TaskRequestBody {
         toolsDelta?: boolean;
     };
     forwardSubagentEvents?: boolean;
+    scratchpadDir?: string;
     retainSubagentSessions?: boolean | {
         ttlMs?: number;
         max?: number;

package/dist/http/server.js

@@ -21,7 +21,7 @@ import { runInBackground, evictIfConflict, stripCheckpointToken, resumeAtHttpSta
 import { looksLikeJwt } from "../auth-bridge.js";
 import { redactSteerIn, STEER_IN_MAX_CHARS, STEER_IN_MAX_REQUEST_CHARS } from "../orchestration/workflow-agent-steer.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationFoldKey, taskNotificationStreamKey, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
-import { fleetRunPublisher, fleetRunLabels } from "../fleet/fleet-bus.js";
+import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals } from "../fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "../fleet/subagent-tail-bus.js";
 import { RateLimiter } from "../observability/rate-limit.js";
 import { withPrincipal } from "../observability/principal-context.js";
@@ -679,6 +679,7 @@ export function createHttpServer(deps) {
                 toolOutput: true,
                 messageIdentity: true,
                 forwardSubagentEvents: true,
+                scratchpadDir: true,
                 subagentSteer: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
                 subagentResume: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
                 taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: false, hooks: deps.config.requirePrincipal !== true },
@@ -853,8 +854,12 @@ export function createHttpServer(deps) {
                     return;
                 }
                 streamTaskId = earlyDurableTid;
+                let usageKey;
                 streamDetached = detachOnDisconnect;
                 sseHeaders(res, earlyDurableTid ? { "x-task-id": earlyDurableTid } : undefined);
+                if (earlyDurableTid) {
+                    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", taskId: earlyDurableTid, ...(prepared.spec.sessionId ? { sessionId: prepared.spec.sessionId } : {}) })}\n\n`);
+                }
                 const ac = new AbortController();
                 if (prepared.spec.sessionId)
                     markChildrenStoppedByUserOnAbort(ac.signal, prepared.spec.sessionId, prepared.auth?.principal);
@@ -921,6 +926,9 @@ export function createHttpServer(deps) {
                             const rs = deps.runStore;
                             const tid = durableTaskId;
                             ledgerSink = createLedgerSink({ appendEvent: (seq, type, data) => rs.appendEvent(tid, seq, type, data), persistThinking: deps.config.traceThinking });
+                            usageKey = prepared.spec.sessionId;
+                            if (usageKey)
+                                deps.modelUsage?.register(usageKey);
                         }
                         if (deps.checkpointStore && prepared.spec.sessionId) {
                             await deps.checkpointStore.putCtx(prepared.spec.sessionId, { body: prepared.body, memoryScope: prepared.auth?.memoryScope });
@@ -961,11 +969,11 @@ export function createHttpServer(deps) {
                             throw e;
                         }
                         let fleetSettled = false;
-                        const settleFleet = (status) => {
+                        const settleFleet = (status, residuals) => {
                             if (fleetSettled)
                                 return;
                             fleetSettled = true;
-                            fleetPub?.onTerminal(status);
+                            fleetPub?.onTerminal(status, residuals);
                         };
                         let liveStreamRef;
                         const subagentHandleEvictions = [];
@@ -1069,16 +1077,25 @@ export function createHttpServer(deps) {
                                             }
                                             finalizeTaskResult(ev.result, principal, prepared.spec.objective, prepared.spec.sessionId);
                                             putRewindAnchor();
-                                            settleFleet(finalResult?.status ?? "completed");
+                                            settleFleet(finalResult?.status ?? "completed", fleetRunResiduals(finalResult));
                                             if (ledgerSink && finalResult) {
+                                                if (usageKey && deps.modelUsage && deps.runStore && durableTaskId) {
+                                                    const rs2 = deps.runStore;
+                                                    const tid2 = durableTaskId;
+                                                    const fr = finalResult;
+                                                    finalResult = await attachModelUsage(fr, { append: ledgerSink.append, getEvents: (_id, after) => rs2.getEvents(tid2, after), modelUsage: deps.modelUsage, taskId: usageKey }).catch(() => fr);
+                                                }
                                                 await ledgerSink.onDone(finalResult);
                                                 ledgerTerminal = true;
                                             }
                                             res.write(`data: ${JSON.stringify({ ...ev, result: finalResult })}\n\n`);
                                             continue;
                                         }
-                                        if (ledgerSink)
+                                        if (ledgerSink) {
                                             await ledgerSink.onEvent(ev);
+                                            if (ev.type === "turn_end" && usageKey)
+                                                await appendModelUsageDelta(ledgerSink.append, deps.modelUsage, usageKey);
+                                        }
                                         fleetPub?.onEvent(ev);
                                         if (ev.type === "status")
                                             deps.metrics?.inc("brain_retry_total", { phase: String(ev.phase) });
@@ -1164,7 +1181,16 @@ export function createHttpServer(deps) {
                             }
                             const withApproval = () => approvalCtx && deps.toolApproval ? deps.toolApproval.runWithContext(approvalCtx, withQuestion) : withQuestion();
                             await (deps.sendUserFile
-                                ? deps.sendUserFile.runWithContext({ taskId: askTaskId, emit: async (f) => void (await emitAsk(f)) }, withApproval)
+                                ? deps.sendUserFile.runWithContext({
+                                    taskId: askTaskId,
+                                    emit: async (f) => {
+                                        void (await emitAsk(f));
+                                        if (ledgerSink) {
+                                            const { type, ...rest } = f;
+                                            await ledgerSink.append(type, rest).catch(() => undefined);
+                                        }
+                                    },
+                                }, withApproval)
                                 : withApproval());
                             if (durableTaskId && deps.runStore) {
                                 if (finalResult?.status === "suspended" && deps.checkpointStore)
@@ -1232,7 +1258,7 @@ export function createHttpServer(deps) {
                                                 await ledgerSink.onDone(finalResult).catch(() => undefined);
                                             }
                                             await deps.runStore.setTerminal(durableTaskId, finalResult.status, finalResult, finalResult.errorMessage ?? null);
-                                            settleFleet(finalResult.status);
+                                            settleFleet(finalResult.status, fleetRunResiduals(finalResult));
                                         }
                                         else if (ac.signal.aborted) {
                                             const err = "stream aborted before completion (run cancelled)";
@@ -1271,6 +1297,8 @@ export function createHttpServer(deps) {
                 finally {
                     uncountedBillableInflight--;
                     clearInterval(hb);
+                    if (usageKey)
+                        deps.modelUsage?.clear(usageKey);
                 }
                 if (!ranLive && resp && !res.writableEnded) {
                     res.write(`data: ${JSON.stringify({ type: "done", result: resp.body, replay: true })}\n\n`);
@@ -2163,7 +2191,17 @@ export function createHttpServer(deps) {
                 });
                 return;
             }
-            sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details });
+            const g14 = (() => {
+                const d = out.details;
+                if (!d || d.error !== undefined || d.retrieval_status === "not_ready")
+                    return {};
+                if (d.type === "background_bash")
+                    return { cursorSemantics: d.details && "bytesDroppedBeforeCursor" in d.details ? "cursor" : "full" };
+                if (d.type === "monitor" || d.type === "background_agent")
+                    return { cursorSemantics: "full" };
+                return {};
+            })();
+            sendJson(res, 200, { taskId: runId, target, content: out.content, output: out.details, ...g14 });
             return;
         }
         const subVerbMatch = req.method === "POST" ? (RUN_SUBAGENT_STEER_RE.exec(url) ?? RUN_SUBAGENT_RESUME_RE.exec(url)) : null;
@@ -5078,11 +5116,11 @@ export function createHttpServer(deps) {
             ? fleetRunPublisher(deps.fleetBus, { runId: taskId, scope: fleetScope, rootTaskId: sessionId, ...fleetRunLabels(resumeObjective) })
             : undefined;
         let fleetSettled = false;
-        const settleFleet = (status) => {
+        const settleFleet = (status, residuals) => {
             if (fleetSettled)
                 return;
             fleetSettled = true;
-            fleetPub?.onTerminal(status);
+            fleetPub?.onTerminal(status, residuals);
         };
         let result;
         let reopenConfirmedPark = false;
@@ -5445,7 +5483,7 @@ export function createHttpServer(deps) {
             else
                 await deps.runStore.setTerminal(taskId, result.status, stripCheckpointToken(result), result.errorMessage ?? null);
         }
-        settleFleet(checkpointReopened ? "suspended" : result.status);
+        settleFleet(checkpointReopened ? "suspended" : result.status, fleetRunResiduals(result));
         return {
             status: 200,
             body: {

package/dist/main.js

@@ -21,7 +21,7 @@ import { createSendUserFileIssuer } from "./plugins/send-user-file.js";
 import { withLedgerRecording } from "./plugins/send-file-ledger.js";
 import { basename, resolve } from "node:path";
 import { stat as fsStat, readFile as fsReadFile } from "node:fs/promises";
-import { buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, purgeScratchpadDir, sweepStaleScratchpads, resumeFactsForLane } from "./env-facts.js";
+import { acceptShellScratchpadDir, buildEnvFacts, egressForRemoteExec, ensureScratchpadDir, purgeScratchpadDir, sweepStaleScratchpads, resumeFactsForLane } from "./env-facts.js";
 import { normalizeSuggestNextPrompts, normalizeResilience, normalizeAttachments, normalizeResumeAtMode, resolveTaskLimits, taskAgentsSpecFragment, retainBackgroundProcessesFromBody, toolNameListFromBody, promptProfileFromBody } from "./spec-fields.js";
 import { createBrain, brainSummary } from "./brain.js";
 import { loadConfig, logConfigDiagnostics } from "./config.js";
@@ -434,7 +434,7 @@ async function main() {
                 await backend.ensureSchema();
             }
             catch (err) {
-                if (config.sessionBackend === "auto") {
+                if (config.sessionBackend === "auto" || (config.dbBackend === "local" && !config.dbBackendExplicit)) {
                     logger.warn("store_db_unreachable_fallback_memory", { backend: backend.kind, error: err instanceof Error ? err.message : String(err) });
                     storeBackendDegraded = true;
                     await backend.close().catch(() => undefined);
@@ -499,6 +499,12 @@ async function main() {
     }
     else {
         memoryEngine = memoryEngineBackendFor(config);
+        if (memoryEngine && process.env.LOCAL_DATA_ROOT && !config.memoryEngineDir) {
+            logger.warn("memory_engine_dir_defaulted", {
+                root: memoryEngine.root,
+                hint: "LOCAL_DATA_ROOT is set but MEMORY_ENGINE_DIR is not — the memory engine is sharing the machine-wide default; set MEMORY_ENGINE_DIR to isolate it under your data root",
+            });
+        }
     }
     let rosterStore;
     {
@@ -2181,9 +2187,13 @@ async function main() {
                 effectiveSettings = Object.keys(rest2).length > 0 ? rest2 : undefined;
             }
             const hostSemanticsLane = config.remoteExec === undefined || config.remoteExec.provider === "host";
-            const scratchpadDir = hostSemanticsLane && auth?.sessionId
-                ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId)
-                : undefined;
+            const shellScratchpad = await acceptShellScratchpadDir(body.scratchpadDir, {
+                requirePrincipal: config.requirePrincipal,
+                hostSemanticsLane,
+                warn: (msg, meta) => logger.warn(msg, { ...(meta ?? {}), sessionId: auth?.sessionId ?? null }),
+            });
+            const scratchpadDir = shellScratchpad ??
+                (hostSemanticsLane && auth?.sessionId ? await ensureScratchpadDir(config.localDataRoot ?? localRoot, auth.sessionId) : undefined);
             if (effectiveSettings) {
                 const fsWriteGate = hostSemanticsLane
                     ? (() => {

package/dist/runs.d.ts

@@ -5,7 +5,7 @@ import type { Metrics } from "./observability/metrics.js";
 import type { ModelUsageTracker, PromptManifestTracker } from "./budget.js";
 import type { ElicitationCoordinator } from "./elicitation.js";
 import type { QuestionCoordinator } from "./question.js";
-import type { FleetRunPublisher } from "./fleet/fleet-bus.js";
+import { type FleetRunPublisher } from "./fleet/fleet-bus.js";
 import { type WorkflowCompletionInbox } from "./orchestration/workflow-completion-inbox.js";
 export declare function backgroundAgentOutput(registry: typeof defaultTaskRegistry, handle: string, access: {
     owner: string;

package/dist/runs.js

@@ -3,6 +3,7 @@ import { withPrincipal } from "./observability/principal-context.js";
 import { redactSecrets } from "./trace/redact.js";
 import { taskNotificationEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "./trace/project.js";
 import { createLedgerSink } from "./trace/ledger-sink.js";
+import { fleetRunResiduals } from "./fleet/fleet-bus.js";
 import { defaultSubagentTailBus, projectTailFrame } from "./fleet/subagent-tail-bus.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "./orchestration/workflow-completion-inbox.js";
 export async function backgroundAgentOutput(registry, handle, access, agentStore) {
@@ -365,13 +366,16 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
         legLive = false;
         if (fleetPublisher) {
             if (reached?.kind === "done")
-                fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status);
+                fleetPublisher.onTerminal(reached.result.errorCode === "cancelled" ? "cancelled" : reached.result.status, fleetRunResiduals(reached.result));
             else if (reached?.kind === "suspended")
                 fleetPublisher.onTerminal("suspended");
             else if (reached?.kind === "needs_review")
                 fleetPublisher.onTerminal("needs_review");
             else
-                fleetPublisher.onTerminal(cancelCtrl.signal.aborted ? "cancelled" : "failed");
+                fleetPublisher.onTerminal(cancelCtrl.signal.aborted ? "cancelled" : "failed", {
+                    ...(cancelCtrl.signal.aborted ? { stoppedBy: "user" } : {}),
+                    ...(spec.sessionId ? { transcriptId: spec.sessionId } : {}),
+                });
         }
         if (inflight?.get(taskId) === cancelCtrl)
             inflight.delete(taskId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.290.0",
+  "version": "1.292.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",