@sema-agent/server 7.76.1 → 7.77.0

package/dist/http/routes/runs.js

@@ -23,7 +23,7 @@ import { sendJson, sendError, httpErrorCode, sseHeaders } from "../send.js";
 import { readTurnActivityMs } from "../../turn-activity.js";
 import { mintCancelledResult } from "../../run-cancel-context.js";
 import { buildCrossSliceUsage, readResourceWindow } from "../../resource-window.js";
-import { headerStr, gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { headerStr, gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 import { ActorAssertionWire } from "@sema-agent/settings-schema";
 import { mintAndDriveDurableRun } from "../durable-run-leg.js";
 import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
@@ -82,7 +82,7 @@ export const RUN_TASK_STOP_RE = /^\/v1\/runs\/([^/]+)\/tasks\/([^/]+)\/stop$/;
 async function subagentReadGate(req, res, deps, runId) {
     const principal = gatedPrincipal(req, deps.config);
     if (deps.config.requirePrincipal && principal === undefined) {
-        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        sendPrincipalRefusal(res, req, deps.config);
         return null;
     }
     const trusted = explicitOperatorOk(principal, deps.config.operatorPrincipals);
@@ -197,7 +197,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const taskId = runMatch[1];
         if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const run = await deps.runStore.getRun(taskId);
@@ -279,7 +279,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
             return;
         }
         if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const taskId = cancelMatch[1];
@@ -407,7 +407,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const taskId = steerMatch[1];
@@ -686,7 +686,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const taskId = interruptMatch[1];
@@ -832,7 +832,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const taskId = compactMatch[1];
@@ -899,7 +899,7 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const taskId = detachMatch[1];
@@ -1117,7 +1117,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const runId = safeDecode(subVerbMatch[1]);
@@ -1214,7 +1214,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const id = elicitMatch[1];
@@ -1240,7 +1240,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const id = questionMatch[1];
@@ -1266,7 +1266,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const id = approvalMatch[1];
@@ -1303,7 +1303,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         let rawBody;

package/dist/http/routes/sessions.js

@@ -3,14 +3,16 @@ import { a2aForScenario, mcpForScenario } from "../../config-center/facade.js";
 import { isUuidV7, isUuidShape, legacyUnownedSessionOk } from "../../security.js";
 import { windowMessages, truncateMessageBlobs } from "../../audit.js";
 import { redactSecrets } from "../../trace/redact.js";
+import { recordFailOpen } from "../../observability/fail-open.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../../task-settings.js";
 import { sendJson, sendError, sseHeaders } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefusal } from "../principal-gate.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
 const A2A_STATUS_TTL_MS = 5_000;
 const A2A_MATERIALIZE_TIMEOUT_MS = 10_000;
 const MEMORY_STATUS_TTL_MS = 5_000;
+const LAST_LEG_LEDGER_TIMEOUT_MS = 2_000;
 const A2A_PANEL_MAX_TOOL_NAMES = 200;
 export function createSessionsLocal() {
     return {
@@ -21,6 +23,44 @@ export function createSessionsLocal() {
         memoryStatusCache: new Map(),
     };
 }
+async function lastLegMcpFor(deps, sessionId, principal) {
+    let timer;
+    try {
+        return await Promise.race([
+            readLastLegMcp(deps, sessionId, principal),
+            new Promise((r) => { timer = setTimeout(() => { recordFailOpen("server.mcp-panel.last-leg-unreadable", `ledger read exceeded ${LAST_LEG_LEDGER_TIMEOUT_MS}ms`); r(undefined); }, LAST_LEG_LEDGER_TIMEOUT_MS); }),
+        ]);
+    }
+    catch (e) {
+        recordFailOpen("server.mcp-panel.last-leg-unreadable", e instanceof Error ? e.message : String(e ?? ""));
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function readLastLegMcp(deps, sessionId, principal) {
+    const runStore = deps.runStore;
+    if (!runStore || sessionId === null)
+        return undefined;
+    const latest = await runStore.latestRunForSession(sessionId);
+    if (latest === undefined)
+        return undefined;
+    if (!runOwnerReadable(principal, latest.owner, deps.config) && !explicitOperatorOk(principal, deps.config.operatorPrincipals))
+        return undefined;
+    const events = await runStore.getEvents(latest.taskId, 0);
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.type !== "wiring_manifest")
+            continue;
+        const mcp = ev.data?.mcp;
+        if (!Array.isArray(mcp))
+            return undefined;
+        return { runId: latest.taskId, at: ev.ts, mcp };
+    }
+    return undefined;
+}
 export async function handleSessions(req, res, url, ctx) {
     const miss = { fell: false };
     await handleSessionsBody(req, res, url, ctx, miss);
@@ -36,7 +76,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         if (im && req.method === "GET") {
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             sendJson(res, 200, {
@@ -52,7 +92,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         if (stm && req.method === "GET") {
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             sendJson(res, 200, {
@@ -71,17 +111,18 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
     {
         const mm = /^\/v1\/sessions\/([^/]+)\/mcp$/.exec(url);
         if (mm && req.method === "GET") {
-            if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
+            const lastLegMcp = await lastLegMcpFor(deps, safeDecode(mm[1]), principal);
             const specs = mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario);
+            const cacheKey = `${deps.config.defaultScenario}::${principal ?? ""}`;
             if (!specs || specs.length === 0) {
-                sendJson(res, 200, { servers: [], asOf: new Date().toISOString() });
+                sendJson(res, 200, { servers: [], asOf: new Date().toISOString(), ...(lastLegMcp === undefined ? {} : { lastLegMcp }) });
                 return;
             }
-            const principal = gatedPrincipal(req, deps.config);
-            const cacheKey = `${deps.config.defaultScenario}::${principal ?? ""}`;
             const cached = mcpStatusCache.get(cacheKey);
             if (!cached || Date.now() - cached.at > MCP_STATUS_TTL_MS) {
                 if (mcpStatusCache.size > 1024)
@@ -114,7 +155,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 })();
                 mcpStatusCache.set(cacheKey, { at: Date.now(), panel });
             }
-            sendJson(res, 200, await mcpStatusCache.get(cacheKey).panel);
+            sendJson(res, 200, { ...(await mcpStatusCache.get(cacheKey).panel), ...(lastLegMcp === undefined ? {} : { lastLegMcp }) });
             return;
         }
     }
@@ -122,7 +163,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
         const am = /^\/v1\/sessions\/([^/]+)\/a2a$/.exec(url);
         if (am && req.method === "GET") {
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             const specs = a2aForScenario(deps.config.a2aPeers, deps.config.defaultScenario);
@@ -420,7 +461,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             if (!deps.sessionAudit) {
@@ -480,7 +521,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             if (!deps.sessionAudit) {

package/dist/http/routes/side-query.js

@@ -3,7 +3,7 @@ import { HttpError } from "../../security.js";
 import { isModelAllowlisted } from "../../model-select.js";
 import { redactSecrets } from "../../trace/redact.js";
 import { sendJson, sendError, httpErrorCode, msg } from "../send.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 const CORE_PREFLIGHT_VALIDATION_PREFIXES = ["Unknown model ref ", "No model for role "];
 export function isCorePreflightValidationError(message) {
     return CORE_PREFLIGHT_VALIDATION_PREFIXES.some((prefix) => message.startsWith(prefix));
@@ -43,7 +43,7 @@ async function handleSideQueryBody(req, res, url, ctx, miss) {
                 return;
             const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
-                sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+                sendPrincipalRefusal(res, req, deps.config);
                 return;
             }
             let body;

package/dist/http/routes/tasks.js

@@ -4,7 +4,8 @@ import { graftParkToolCallId, markChildrenStoppedByUserOnAbort, resumeAtHttpStat
 import { stripResumeToken } from "../../terminal.js";
 import { withPrincipal } from "../../observability/principal-context.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../../fleet/fleet-bus.js";
-import { defaultSubagentTailBus, projectTailFrame } from "../../fleet/subagent-tail-bus.js";
+import { defaultSubagentTailBus } from "../../fleet/subagent-tail-bus.js";
+import { createReasoningSegments, reasoningStreamOfTask } from "../../trace/model-segment.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "../../orchestration/workflow-completion-inbox.js";
 import { createLedgerSink } from "../../trace/ledger-sink.js";
 import { registerEngineNoticeLeg } from "../../trace/engine-notice-wire.js";
@@ -313,23 +314,21 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                     const streamBody = async () => {
                         await withPrincipal(principal, async () => {
                             const tailContentMode = prepared.spec.forwardSubagentEvents === true ? "on" : "progress_only";
+                            const childReasoning = createReasoningSegments();
+                            const topReasoning = createReasoningSegments();
                             const fwdInternals = {
                                 onForwardEvent: (e) => {
                                     fleetPub?.onForwardEvent(e);
                                     ledgerSink?.onForwardEvent(e);
                                     {
                                         const bg = e.bgAgentId;
-                                        if (bg !== undefined) {
-                                            defaultSubagentTailBus.noteHandleContentMode(bg, tailContentMode);
-                                            if (defaultSubagentTailBus.hasSubscribers(bg)) {
-                                                const f = projectTailFrame(e);
-                                                if (f)
-                                                    defaultSubagentTailBus.publish(bg, f);
-                                            }
-                                        }
+                                        if (bg !== undefined)
+                                            defaultSubagentTailBus.onForwardFrame(bg, tailContentMode, e);
                                     }
                                     if (res.writableEnded)
                                         return;
+                                    for (const end of childReasoning.onEvent(e))
+                                        sseData(res, end);
                                     const t = e.type;
                                     if (t === "task_progress") {
                                         sseData(res, { type: "task_progress", ...taskProgressEventData(e) });
@@ -359,7 +358,10 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                                 onTaskNotification: (n, opts) => {
                                     if (n.task_type === "workflow")
                                         return;
-                                    defaultSubagentTailBus.forgetHandleContentMode(n.task_id);
+                                    if (!res.writableEnded)
+                                        for (const end of childReasoning.cut(reasoningStreamOfTask(n.task_id, n.sessionId)))
+                                            sseData(res, end);
+                                    defaultSubagentTailBus.forgetHandle(n.task_id);
                                     if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                                         defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                                     }
@@ -393,6 +395,8 @@ async function handleTasksBody(req, res, url, ctx, miss) {
                             for await (const ev of liveStream) {
                                 if (closed)
                                     break;
+                                for (const end of ev.type === "done" ? [...childReasoning.cut(), ...topReasoning.cut()] : topReasoning.onEvent(ev))
+                                    sseData(res, end);
                                 if (ev.type === "message_committed" && ev.role === "user")
                                     userMsgEntryId = ev.entryId;
                                 const cancelVerbAtDone = ev.type === "done" && durableTaskId !== undefined && cancelledViaVerb.has(durableTaskId);

package/dist/http/routes/workflows.js

@@ -9,7 +9,7 @@ import { redactErrorMessage, redactHead } from "../../observability/run-terminal
 const JOURNAL_PROJECTION_MEMO_CAP = 1024;
 const journalProjectionMemo = new Map();
 import { sendJson, sendError, sseHeaders } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sendPrincipalRefusal } from "../principal-gate.js";
 const WORKFLOWS_RE = /^\/v1\/workflows(?:\/([^/]+)(\/stream|\/journal)?)?$/;
 const WORKFLOW_AGENT_STEER_RE = /^\/v1\/workflows\/([^/]+)\/agents\/([^/]+)\/steer$/;
 export async function handleWorkflows(req, res, url, ctx) {
@@ -29,7 +29,7 @@ async function handleWorkflowsReadBody(req, res, url, ctx, miss) {
     if (wfMatch) {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         if (!deps.workflowRunStore) {
@@ -163,7 +163,7 @@ async function handleWorkflowAgentSteerBody(req, res, url, ctx, miss) {
         }
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && principal === undefined) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return;
         }
         const wfRunId = safeDecode(wfSteerMatch[1]);

package/dist/http/server.js

@@ -26,7 +26,7 @@ import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
 import {} from "../orchestration/workflow-agent-steer.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
 import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../fleet/fleet-bus.js";
-import { defaultSubagentTailBus, projectTailFrame } from "../fleet/subagent-tail-bus.js";
+import { defaultSubagentTailBus } from "../fleet/subagent-tail-bus.js";
 import { APPROVAL_GATE_KINDS, createApprovalCardEmitter, isApprovalGateKind, resolveApprovalLeg, resolveStreamApprovalGate } from "../tool-approval.js";
 import { buildCheckpointAnchorHash } from "../approval-ask-audit-store.js";
 import { TERMINAL_PARK_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
@@ -85,7 +85,7 @@ export { cascadeConfig };
 import { handleImages, createImagesLocal, coarseStatusForState, errorCodeForExit } from "./routes/images.js";
 export { coarseStatusForState, errorCodeForExit };
 import { sendJson, sendError, httpErrorCode, msg, isSseResponse } from "./send.js";
-import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, isOperator } from "./principal-gate.js";
+import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, isOperator, runOwnerReadable, sendPrincipalRefusal } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
 export { explicitOperatorOk, isOperator };
@@ -1453,14 +1453,8 @@ export function createHttpServer(rawDeps) {
                             fleetPub?.onForwardEvent(e);
                             {
                                 const bg = e.bgAgentId;
-                                if (bg !== undefined) {
-                                    defaultSubagentTailBus.noteHandleContentMode(bg, verifyTailContentMode);
-                                    if (defaultSubagentTailBus.hasSubscribers(bg)) {
-                                        const f = projectTailFrame(e);
-                                        if (f)
-                                            defaultSubagentTailBus.publish(bg, f);
-                                    }
-                                }
+                                if (bg !== undefined)
+                                    defaultSubagentTailBus.onForwardFrame(bg, verifyTailContentMode, e);
                             }
                             if (rsV && taskId)
                                 verifySink.onForwardEvent(e);
@@ -1474,7 +1468,7 @@ export function createHttpServer(rawDeps) {
                         onTaskNotification: (n, opts) => {
                             if (n.task_type === "workflow")
                                 return;
-                            defaultSubagentTailBus.forgetHandleContentMode(n.task_id);
+                            defaultSubagentTailBus.forgetHandle(n.task_id);
                             if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                                 defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                             }
@@ -1578,14 +1572,8 @@ export function createHttpServer(rawDeps) {
                             fleetPub?.onForwardEvent(e);
                             {
                                 const bg = e.bgAgentId;
-                                if (bg !== undefined) {
-                                    defaultSubagentTailBus.noteHandleContentMode(bg, tailContentMode);
-                                    if (defaultSubagentTailBus.hasSubscribers(bg)) {
-                                        const f = projectTailFrame(e);
-                                        if (f)
-                                            defaultSubagentTailBus.publish(bg, f);
-                                    }
-                                }
+                                if (bg !== undefined)
+                                    defaultSubagentTailBus.onForwardFrame(bg, tailContentMode, e);
                             }
                             if (!rs || !taskId)
                                 return;
@@ -1604,7 +1592,7 @@ export function createHttpServer(rawDeps) {
                         onTaskNotification: (n, opts) => {
                             if (n.task_type === "workflow")
                                 return;
-                            defaultSubagentTailBus.forgetHandleContentMode(n.task_id);
+                            defaultSubagentTailBus.forgetHandle(n.task_id);
                             if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
                                 defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
                             }
@@ -2331,11 +2319,10 @@ export function createHttpServer(rawDeps) {
     function runOwnerOk(req, res, owner, notFoundForm = "run") {
         const principal = gatedPrincipal(req, deps.config);
         if (deps.config.requirePrincipal && !principal) {
-            sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+            sendPrincipalRefusal(res, req, deps.config);
             return false;
         }
-        const legacyShellOwner = !deps.config.requirePrincipal && owner === "anon:shell-live" && (principal === undefined || principal === null);
-        if (!legacyShellOwner && owner !== null && principal !== owner) {
+        if (!runOwnerReadable(principal, owner, deps.config)) {
             if (notFoundForm === "session")
                 sendError(res, 404, "not_found.session", "session not found");
             else

package/dist/observability/fail-open.d.ts

@@ -13,6 +13,10 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-136 合并重扫确认项(`terminal.ts persistedPlaneOf`,持久 blob 的平面读面):盘上一条 `terminal` 因由形不合(`paused` 缺 gate / 词出闭集)让 core 的 `terminalProjection` 抛 ⇒ 本读面对这一行答**全格缺席**而不是整只 500。放行的最坏后果=一条坏行在列表/舰队读面上显示为无终局词;计数 + probe 带原句,便于按行回溯。";
     };
+    readonly "server.mcp-panel.last-leg-unreadable": {
+        readonly cls: "F";
+        readonly note: "S-297(`http/routes/sessions.ts lastLegMcpFor`,`/mcp` 面板的可选键 `lastLegMcp`):按会话取最近 run 的索引读 / 那条 run 的账本读**抛错或超期** ⇒ 该键缺席,面板本体照常 200。放行的最坏后果=这一屏少一格「上一次真挂上了什么」(壳退回翻账本),不是门、不是权限、不是凭证 —— 而反方向(让附加键的读失败打掉整张面板)会给一口此前零 MCP 配置下根本不碰账本的**既有**读面新加一条挂掉的理由。缺席本就是本键 wire 上的一等状态(消费端必须会读),所以这条兜底不产生任何新的消费端形态;计数让「某台部署的账本一直读不出来」显形。";
+    };
     readonly "server.workflow-park-index.sync-failed": {
         readonly cls: "P-DEBT";
         readonly note: "S-185 车CM(codex r1-F2 [high],验真后登记):workflow 出身 park 的 join 索引(`workflow_agent_session` / local 账本)在**一次成功的 run 写之后**同步失败 ⇒ 该次同步被吞,重试要等这条 run 的**下一次**写。而 park 恰好常常是这条 run 的**最后**一次写(park = run 终局 `failed`)⇒ 那条 park 可能永久 join 不到,`/decide` 结构性退回本批之前的行为(409 `conflict.resume_context_unavailable`)——**方向是 fail-closed**(不误配、不伪造、不放行任何东西),丢的是「人能不能把这条批准送出去」这个能力。归 P 类的理由是它决定**车道选择**(缺行 ⇒ 选中 legacy 腿),归 DEBT 的理由是真正的解要一条**按子代 checkpoint 键的耐久决议回执 + 重启期回填**(与 codex r1-F3 同一件欠账,另车)。计数非零 = 有 park 因此决不掉,运维要按 detail 里的 runId 去查。";

package/dist/observability/fail-open.js

@@ -4,6 +4,10 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-136 合并重扫确认项(`terminal.ts persistedPlaneOf`,持久 blob 的平面读面):盘上一条 `terminal` 因由形不合(`paused` 缺 gate / 词出闭集)让 core 的 `terminalProjection` 抛 ⇒ 本读面对这一行答**全格缺席**而不是整只 500。放行的最坏后果=一条坏行在列表/舰队读面上显示为无终局词;计数 + probe 带原句,便于按行回溯。",
     },
+    "server.mcp-panel.last-leg-unreadable": {
+        cls: "F",
+        note: "S-297(`http/routes/sessions.ts lastLegMcpFor`,`/mcp` 面板的可选键 `lastLegMcp`):按会话取最近 run 的索引读 / 那条 run 的账本读**抛错或超期** ⇒ 该键缺席,面板本体照常 200。放行的最坏后果=这一屏少一格「上一次真挂上了什么」(壳退回翻账本),不是门、不是权限、不是凭证 —— 而反方向(让附加键的读失败打掉整张面板)会给一口此前零 MCP 配置下根本不碰账本的**既有**读面新加一条挂掉的理由。缺席本就是本键 wire 上的一等状态(消费端必须会读),所以这条兜底不产生任何新的消费端形态;计数让「某台部署的账本一直读不出来」显形。",
+    },
     "server.workflow-park-index.sync-failed": {
         cls: "P-DEBT",
         note: "S-185 车CM(codex r1-F2 [high],验真后登记):workflow 出身 park 的 join 索引(`workflow_agent_session` / local 账本)在**一次成功的 run 写之后**同步失败 ⇒ 该次同步被吞,重试要等这条 run 的**下一次**写。而 park 恰好常常是这条 run 的**最后**一次写(park = run 终局 `failed`)⇒ 那条 park 可能永久 join 不到,`/decide` 结构性退回本批之前的行为(409 `conflict.resume_context_unavailable`)——**方向是 fail-closed**(不误配、不伪造、不放行任何东西),丢的是「人能不能把这条批准送出去」这个能力。归 P 类的理由是它决定**车道选择**(缺行 ⇒ 选中 legacy 腿),归 DEBT 的理由是真正的解要一条**按子代 checkpoint 键的耐久决议回执 + 重启期回填**(与 codex r1-F3 同一件欠账,另车)。计数非零 = 有 park 因此决不掉,运维要按 detail 里的 runId 去查。",

package/dist/parent-watch.d.ts

@@ -9,23 +9,31 @@
  * (core `FileStorageBackend` 的 pidfile,失效判定是 `process.kill(pid,0)` ⇒ **活孤儿是合法持锁人**),
  * 于是此后每一只新壳起自己的引擎都撞锁 fatal「another instance (pid N) owns this data dir」—— 用户看到
  * 的是「壳崩过一次以后就再也起不来了」。持锁 pid 不存在时 core 已自动剪陈旧锁,缺的只有「父死、子活」
- * 这一形。所以引擎给自己装一只**自查**腿:定期问一句"生我的那个还在吗",不在就**自己**走正常停机。
+ * 这一形。所以引擎给自己装一只**自查**腿:定期问一句"生我的那个还在吗"。
+ *
+ * ## 本腿**不**做什么(S-306,硬 breaking)
+ *
+ * 它**不判死、不 drain、不退进程**。父没了只说明这台引擎成了**孤儿**,而「孤儿该不该退」是**租约**
+ * 的问题:还有没有人附着、有没有在飞的 turn、静默够不够久 —— 那是 `boot/engine-lease.ts` 那一条腿,
+ * 孤儿态只是把它的窗从 `ENGINE_LINGER_MS` 换成 `ENGINE_ORPHAN_LINGER_MS`(默认 2s)。
+ * 旧出口(父死**即** drain,单拍、零附着感知)在「A 起引擎、B 按 engine.port 复用、A 正常退出」这一形
+ * 下会在 B 的 turn 中间把引擎拆掉 —— 自退律从此**只有一条**,本腿退化成它的一个输入。
  *
  * ## 机制(逐条都是契约)
  *
  *  1. **opt-in**:`SEMA_PARENT_PID` 缺席 ⇒ 整件不装配(`boot/shutdown.ts` 连 `createParentWatch` 都不调)。
  *     存量部署逐字零变化 —— systemd / launchd / 容器托管的引擎本来就 reparent 到 1,自退是事故。
  *     坏值(非正整数 / 超 int32)⇒ **启动期拒**,在 `config.ts` 的 `parentPidEnv()`。
- *  2. **判死 = 两支合取口一句,任一成立即判死**,每 {@link PARENT_WATCH_INTERVAL_MS} 一拍:
+ *  2. **判据 = 两支合取口一句,任一成立即标孤儿**,每 {@link PARENT_WATCH_INTERVAL_MS} 一拍:
  *
  *       · **强身份支 `reparented`**:`process.ppid` 不再是装配那一刻的那个值。生我的进程没了,内核就把
  *         我过继给 init(或容器里的 subreaper)—— 这是**内核对亲子关系的直答**,不依赖 pid 的身份。
  *         判据刻意**不写成 `ppid === 1`**:① 收养者未必是 1(PID 1 是 subreaper 的容器里不是);
  *         ② 壳本身就是 pid 1 的容器形里(`SEMA_PARENT_PID=1`),`=== 1` 会在**开机第一拍**把一台健康
- *         引擎判死。「不再是生我的那个」两种形都答得对,而且不需要任何特判。
+ *         引擎标成孤儿。「不再是生我的那个」两种形都答得对,而且不需要任何特判。
  *         🔴 **前提**(codex 复审 R1 [high],验真后修):这一支只有在「被监视的 pid 就是生我的那个」时
  *         才等价于「它没了」。壳经一层 wrapper spawn 引擎却仍传**自己**的 pid 时,引擎的直接父是
- *         wrapper —— wrapper 先退会让这一支把一台**壳还活着**的健康引擎连同 in-flight run 一起关掉。
+ *         wrapper —— wrapper 先退会让这一支把一台**壳还活着**的健康引擎标成孤儿(于是它的租约窗被无故收短)。
  *         前提在**装配那一刻**就能一次判完(`ppidAtArm === pid`),所以它是**装配期的开关**而不是每拍
  *         的特判:不成立 ⇒ 强身份支整条不装,只留弱身份支(它在那一形下语义仍然正确),并且 armed 那行
  *         改打 **warn** —— 覆盖面被降级了不许静默。
@@ -37,16 +45,16 @@
  *
  *     强身份支**先判**:它成立时这一拍连探活都不发 —— 弱判据没有资格给一个已经被过继走的进程改口
  *     (僵尸父那一形里 `kill(pid,0)` 恰恰恒成功)。
- *  3. **单拍即判,不去抖**。[ref] 定稿是「15s 一拍、连续两拍才判死」(上界 30s),S-292 整条退役:
- *     部署面的判据是「壳挂了 ≤5s 内数据根重新可用」,而 `ESRCH` / `ppid` 都不是会抖的读数(两者都是
- *     内核的直答,不是采样值)。去抖买不到确定性,只买到 15s 的延迟和一个 30s 长的 pid-复用窗口。
- *  4. **判死后走 `drain`**,即 `boot/shutdown.ts` 里 SIGTERM 用的那一条 `drainThenShutdown` —— in-flight
- *     run 的结算 / park 语义与人工停机**逐字一致**,而且收尾链里的 `backend.close()` 才是把 `LOCK`
- *     真正还回去的那一步。本模块自己**从不** `process.exit`。已有停机属主(`isStopped`)时站下不重入。
+ *  3. **单拍即判,不去抖**。[ref] 定稿是「15s 一拍、连续两拍才判定」(上界 30s),S-292 整条退役:
+ *     部署面的判据是「壳挂了以后数据根要在秒级重新可用」,而 `ESRCH` / `ppid` 都不是会抖的读数(两者
+ *     都是内核的直答,不是采样值)。去抖买不到确定性,只买到 15s 的延迟和一个 30s 长的 pid-复用窗口。
+ *  4. **命中一次即停探**(父不会复活),出口是 {@link ParentWatchDeps.onOrphaned} —— 装配层据此记下
+ *     「孤儿了 + 是哪一支判的」,租约腿下一拍读到它就换窗。本模块自己**从不** drain、**从不**
+ *     `process.exit`。已有停机属主(`isStopped`)时站下不重入(一次正在进行的优雅停机不必再被标孤儿)。
  *  5. **interval 必须 unref**:监视腿不得成为"进程本该退出却退不掉"的理由(与 drain tick 刻意不 unref
  *     的取向相反 —— 那一只 tick 就是停机驱动,这一只只是观察者)。
- *  6. **日志分档**([ref] 响亮律):装配 = `info`;判死与探活自坏 = `warn`(非计划内的停机、以及"这条腿
- *     此刻是失效的",都不许混在 info 流里)。档位是**闭集** {@link ParentWatchLogLevel},装配层用
+ *  6. **日志分档**([ref] 响亮律):装配 = `info`;标孤儿与探活自坏 = `warn`(非计划内的生命周期事件、
+ *     以及"这条腿此刻是失效的",都不许混在 info 流里)。档位是**闭集** {@link ParentWatchLogLevel},装配层用
  *     `Record<ParentWatchLogLevel, …>` 派发 ⇒ 新增一档是编译错,不会静默落进 info。
  *
  * ## 已知残余(成文,现版不收窄)
@@ -64,8 +72,9 @@
 export declare const PARENT_WATCH_INTERVAL_MS = 2000;
 /** 日志档位闭集。装配层按 `Record<ParentWatchLogLevel, …>` 派发 —— 新增一档必须在那里显式安置(编译错)。 */
 export type ParentWatchLogLevel = "info" | "warn";
-/** 判死缘由闭集(上 `parent_watch_exit` 的 `reason` 键,运维按它区分两支)。 */
-export type ParentDeathReason = "reparented" | "esrch";
+/** 成孤儿的缘由闭集(上 `parent_watch_orphaned` 的 `reason` 键,运维按它区分两支;也是租约自退留痕
+ *  `exit-last.json` 与 `engine_lease_auto_exit` 事件里 `reason` 的孤儿那两个词)。 */
+export type ParentOrphanReason = "reparented" | "esrch";
 export interface ParentWatchDeps {
     /** 被监视的父 pid(`config.parentPid`,已在 config 层校验为正整数)。 */
     pid: number;
@@ -75,11 +84,16 @@ export interface ParentWatchDeps {
     /** 亲子关系 seam:缺省 = `process.ppid`(**活读**,不是 boot 时的快照 —— 实测过继后当场变)。
      *  存在的理由与 `probe` 相同:reparent 在进程内测试里没有确定性的触发法。 */
     readPpid?: () => number;
-    /** 已有停机属主(`closing || draining`)时监视腿站下:一次正在进行的优雅 drain 不该被"父也没了"
-     *  升级成第二信号硬停(那会斩掉 in-flight leg —— 与本件"和人工停机逐字一致"的取向相反)。 */
+    /** 已有停机属主(`closing || draining`)时监视腿站下:停机已经在走了,再标一次孤儿改变不了任何事,
+     *  只会给一次计划内的停机添一条误导的 warn。 */
     isStopped: () => boolean;
-    /** 判死出口 = SIGTERM 那条 graceful drain。 */
-    drain: () => void;
+    /**
+     * **唯一出口**(S-306):父不在了 ⇒ 把这台引擎标成孤儿。**至多调用一次**(命中即停探)。
+     *
+     * 🔴 它**不是** drain:退不退由 `boot/engine-lease.ts` 的租约律按「无附着 ∧ 无在飞 ∧ 静默满
+     * `orphanLingerMs`」判。装配层拿到 reason 之后要做的只有一件事 —— 记下孤儿态(时刻 + 缘由)。
+     */
+    onOrphaned: (reason: ParentOrphanReason) => void;
     log: (level: ParentWatchLogLevel, event: string, fields: Record<string, unknown>) => void;
 }
 /** 装配并**立刻**起监视(装配即 `parent_watch_armed`)。返回停机链用的 `stop()`。 */

package/dist/parent-watch.js

@@ -12,11 +12,11 @@ export function createParentWatch(deps) {
         directParent,
         intervalMs: PARENT_WATCH_INTERVAL_MS,
         note: directParent
-            ? "engine watches this pid; it enters the same graceful drain as SIGTERM as soon as EITHER the engine is " +
-                "reparented away from it OR process.kill(pid,0) reports ESRCH (EPERM = alive). " +
-                "Unset SEMA_PARENT_PID to disable."
+            ? "engine watches this pid; it marks ITSELF an orphan as soon as EITHER the engine is reparented away from " +
+                "it OR process.kill(pid,0) reports ESRCH (EPERM = alive). Being orphaned does NOT shut the engine down — " +
+                "it only shortens the attachment-lease window to ENGINE_ORPHAN_LINGER_MS. Unset SEMA_PARENT_PID to disable."
             : "SEMA_PARENT_PID is NOT this engine's direct parent (ppid differs at arm time) — a wrapper process sits " +
-                "in between. The reparent arm is therefore NOT armed (it would stop a healthy engine when the wrapper " +
+                "in between. The reparent arm is therefore NOT armed (it would orphan a healthy engine when the wrapper " +
                 "exits while the watched process is still alive); only the process.kill(pid,0)/ESRCH arm is active, so a " +
                 "watched parent that exits WITHOUT being reaped (zombie) will not be detected. Spawn the engine directly " +
                 "from the process whose pid you pass.",
@@ -30,7 +30,7 @@ export function createParentWatch(deps) {
         }
         const ppid = readPpid();
         if (directParent && ppid !== ppidAtArm) {
-            fire("reparented", { ppidAtArm, ppid });
+            markOrphaned("reparented", { ppidAtArm, ppid });
             return;
         }
         try {
@@ -39,7 +39,7 @@ export function createParentWatch(deps) {
         catch (err) {
             const code = err?.code;
             if (code === "ESRCH") {
-                fire("esrch", { ppid });
+                markOrphaned("esrch", { ppid });
                 return;
             }
             if (code !== "EPERM" && !probeErrorReported) {
@@ -56,15 +56,17 @@ export function createParentWatch(deps) {
         }
     }, PARENT_WATCH_INTERVAL_MS);
     timer.unref?.();
-    function fire(reason, fields) {
+    function markOrphaned(reason, fields) {
         stop();
-        deps.log("warn", "parent_watch_exit", {
+        deps.log("warn", "parent_watch_orphaned", {
             pid: deps.pid,
             reason,
             ...fields,
-            note: "the parent that spawned this engine is gone — entering the SIGTERM graceful drain path",
+            note: "the parent that spawned this engine is gone — this engine is now an ORPHAN. It does NOT shut down here: " +
+                "it stays up while anything is attached or in flight, and self-exits via the SIGTERM graceful drain once " +
+                "the attachment lease has been idle for ENGINE_ORPHAN_LINGER_MS (see engine_lease_auto_exit).",
         });
-        deps.drain();
+        deps.onOrphaned(reason);
     }
     function stop() {
         if (stopped)