@sema-agent/server 7.126.0 → 7.127.1

package/dist/runs.js

@@ -64,13 +64,6 @@ export function markChildrenStoppedByUserOnAbort(signal, taskId, principal) {
     }
     signal.addEventListener("abort", mark, { once: true });
 }
-export function isSessionConflictResult(result) {
-    if (result.terminal.kind !== "failed")
-        return false;
-    if (result.terminal.code)
-        return result.terminal.code === "conflict";
-    return /stale write|concurrent write|conflict/i.test(result.terminal.message ?? "");
-}
 const PREPARE_REFUSAL_HTTP_STATUS = {
     "resume.session_not_found": 404,
     "rewind_snapshot.unresolvable": 422,
@@ -170,12 +163,7 @@ export async function graftParkToolCallId(result, cs) {
     const id = await parkToolCallId(result, cs);
     return id === undefined ? result : { ...result, toolCallId: id };
 }
-export function evictIfConflict(runner, sessionId, result) {
-    if (sessionId && isSessionConflictResult(result)) {
-        runner.sessions.evict?.(sessionId);
-    }
-}
-export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, parkCheckpointReader, pendingEngineNotices, trustedInternals, userInputLedger) {
+export async function runInBackground(runner, spec, runStore, taskId, metrics, principal, verify, cascade, instrumentDegenerate, planCacheProbe, persistThinking = false, inflight, preemptable, steerable, modelUsage, elicitation, elicitOwner, captureTurnAnchor, fleetPublisher, captureUserMessageAnchor, question, workflowCompletionInbox, subagentSteer, completionDiagLog, sendUserFile, promptManifests, approval, parkCheckpointReader, pendingEngineNotices, trustedInternals, userInputLedger, acceptance) {
     const startedAt = Date.now();
     metrics?.addGauge("runs_active", 1);
     fleetPublisher?.onStart();
@@ -338,7 +326,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
             if (verify !== undefined) {
                 const result = await runWithVerification(runner, { ...spec, taskId, signal: cancelCtrl.signal }, verify, { ...fwdInternals, ...statusSeat });
                 await flush();
-                evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
                 const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
@@ -346,13 +333,13 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
+                acceptance?.settle(safe);
                 recordDone(safe, plane.status);
                 return;
             }
             if (cascade !== undefined) {
                 const result = await runCascade(runner, { ...spec, taskId, signal: cancelCtrl.signal }, cascade, { ...fwdInternals, ...statusSeat });
                 await flush();
-                evictIfConflict(runner, spec.sessionId, result);
                 await flushPromptManifest();
                 const safe = await withModelUsage(sealResultForExit(result));
                 await append("done", { result: safe });
@@ -360,6 +347,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 const plane = outwardPlane(safe.terminal);
                 await runStore.setTerminal(taskId, plane.status, safe, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, safe);
+                acceptance?.settle(safe);
                 recordDone(safe, plane.status);
                 return;
             }
@@ -373,6 +361,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 }
                 fleetPublisher?.onEvent(ev);
                 await userInputLedger?.observeLegEvent(stream, ev);
+                acceptance?.observe(ev);
                 await flushPromptManifest();
                 switch (ev.type) {
                     case "text_delta":
@@ -406,7 +395,6 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                         await parkNeedsReview(ev.result);
                         continue;
                     }
-                    evictIfConflict(runner, spec.sessionId, ev.result);
                     {
                         const settled = causeAtDone !== undefined ? cancelledResult(causeAtDone, ev.result) : ev.result;
                         settledAsCancel = failureCodeOf(settled.terminal) === CANCELLED_CODE;
@@ -491,6 +479,7 @@ export async function runInBackground(runner, spec, runStore, taskId, metrics, p
                 settledAsCancel = failureCodeOf(reached.result.terminal) === CANCELLED_CODE;
                 await runStore.setTerminal(taskId, plane.status, reached.result, plane.errorMessage ?? null);
                 await releaseKeyIfZeroWorkRefusal(runStore, taskId, reached.result);
+                acceptance?.settle(reached.result);
             }
             else if (reached?.kind === "suspended") {
                 await runStore.setSuspended(taskId, reached.result);

package/dist/sandbox-egress-policy.d.ts

@@ -0,0 +1,61 @@
+/** `K8S_SANDBOX_IPV6` 闭集:`enabled` = pod 保留平台给的 IPv6(pod spec 与未引入本旋钮时逐字同形);`disabled` = pod 级 sysctl 关掉 IPv6。 */
+export declare const SANDBOX_IPV6_WORDS: readonly ["enabled", "disabled"];
+export type SandboxIpv6 = (typeof SANDBOX_IPV6_WORDS)[number];
+/** 旋钮缺席时的姿态(缺省不动 pod:关 v6 要每个节点的 kubelet 放行这两只 sysctl,没放行的集群 pod 起不来)。 */
+export declare const SANDBOX_IPV6_DEFAULT: SandboxIpv6;
+/** 一只 pod 级 sysctl(k8s `PodSecurityContext.sysctls[]` 的形)。 */
+export interface PodSysctl {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * 沙箱 pod 的 sysctl 只有这一个属主:`disabled` ⇒ `all`(已有接口)与 `default`(之后建的接口)都关 IPv6;`enabled` ⇒ 不铸。
+ * 两只都不在 k8s 的 safe sysctl 表里 ⇒ 每个节点 kubelet 要 `--allowed-unsafe-sysctls` 点名它们,否则 pod 起不来(车道连沙箱失败,响亮)。
+ */
+export declare function sandboxPodSysctls(ipv6: SandboxIpv6): readonly PodSysctl[] | undefined;
+/** 自检读的两张表(车道侧各一只 GET)。 */
+export type EgressPolicyRead = "nodes" | "networkpolicies";
+/** 节点地址里自检判的两类(`Hostname` / `InternalDNS` / `ExternalDNS` 不是地址)。 */
+type NodeAddressType = "InternalIP" | "ExternalIP";
+export type SandboxEgressGap = {
+    readonly kind: "node_address_open";
+    readonly node: string;
+    readonly addressType: NodeAddressType;
+    readonly address: string;
+    readonly policy: string;
+    readonly ports: string;
+} | {
+    readonly kind: "policy_absent";
+} | {
+    readonly kind: "ipv6_enabled";
+} | {
+    readonly kind: "unreadable";
+    readonly what: EgressPolicyRead;
+    readonly detail: string;
+};
+/** 一只 GET 的读数:答了 2xx ⇒ 体;否则一句为什么读不到(HTTP 码 / 错误句)。 */
+export type ApiRead = {
+    readonly ok: true;
+    readonly json: unknown;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+export interface EgressPolicyInputs {
+    readonly nodes: ApiRead;
+    readonly policies: ApiRead;
+    /** 沙箱 pod 的标签(车道建 pod 时铸的那一份)。 */
+    readonly podLabels: Readonly<Record<string, string>>;
+    readonly ipv6: SandboxIpv6;
+}
+/**
+ * 读数 → 缺口(纯函数、全函数:不抛;顺序:读不到的表 → 策略缺席 → 逐节点逐地址 → IPv6)。一张表读不到,只跳过要它的那一判;另一张照判。
+ */
+export declare function sandboxEgressGaps(inputs: EgressPolicyInputs): SandboxEgressGap[];
+/** 读数的说法:每个缺口一行 warn `sandbox_egress_policy_gap` + 一次 `recordFailOpen`(P-DEBT);零缺口一行 info `sandbox_egress_policy_checked`。 */
+export declare function sayEgressPolicyReading(gaps: readonly SandboxEgressGap[], logger: {
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+} | undefined, namespace: string): void;
+export {};
+//# sourceMappingURL=sandbox-egress-policy.d.ts.map

package/dist/sandbox-egress-policy.js

@@ -0,0 +1,235 @@
+import { BlockList, isIP } from "node:net";
+import { recordFailOpen } from "./observability/fail-open.js";
+export const SANDBOX_IPV6_WORDS = ["enabled", "disabled"];
+export const SANDBOX_IPV6_DEFAULT = "enabled";
+export function sandboxPodSysctls(ipv6) {
+    switch (ipv6) {
+        case "enabled":
+            return undefined;
+        case "disabled":
+            return [
+                { name: "net.ipv6.conf.all.disable_ipv6", value: "1" },
+                { name: "net.ipv6.conf.default.disable_ipv6", value: "1" },
+            ];
+    }
+}
+class Unjudgeable extends Error {
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function recordAt(v, where) {
+    if (!isRecord(v))
+        throw new Unjudgeable(`${where} is not an object`);
+    return v;
+}
+function optRecordAt(v, where) {
+    return v === undefined || v === null ? undefined : recordAt(v, where);
+}
+function arrayAt(v, where) {
+    if (!Array.isArray(v))
+        throw new Unjudgeable(`${where} is not a list`);
+    return v;
+}
+function optArrayAt(v, where) {
+    return v === undefined || v === null ? undefined : arrayAt(v, where);
+}
+function stringAt(v, where) {
+    if (typeof v !== "string")
+        throw new Unjudgeable(`${where} is not a string`);
+    return v;
+}
+function listItems(json, what) {
+    const items = isRecord(json) ? json.items : undefined;
+    if (!Array.isArray(items))
+        throw new Unjudgeable(`${what} answer carries no items list`);
+    return items;
+}
+const SELECTOR_OPERATORS = ["In", "NotIn", "Exists", "DoesNotExist"];
+function readSelector(v, where) {
+    const sel = optRecordAt(v, where) ?? {};
+    const labels = optRecordAt(sel.matchLabels, `${where}.matchLabels`) ?? {};
+    const matchLabels = {};
+    for (const [k, val] of Object.entries(labels))
+        matchLabels[k] = stringAt(val, `${where}.matchLabels.${k}`);
+    const matchExpressions = (optArrayAt(sel.matchExpressions, `${where}.matchExpressions`) ?? []).map((e, i) => {
+        const x = recordAt(e, `${where}.matchExpressions[${i}]`);
+        const operator = stringAt(x.operator, `${where}.matchExpressions[${i}].operator`);
+        if (!SELECTOR_OPERATORS.includes(operator))
+            throw new Unjudgeable(`${where} operator ${JSON.stringify(operator)} is not one of ${SELECTOR_OPERATORS.join(" / ")}`);
+        return { key: stringAt(x.key, `${where}.matchExpressions[${i}].key`), operator, values: (optArrayAt(x.values, `${where}.matchExpressions[${i}].values`) ?? []).map((y, j) => stringAt(y, `${where}.matchExpressions[${i}].values[${j}]`)) };
+    });
+    return { matchLabels, matchExpressions };
+}
+function selects(sel, labels) {
+    for (const [k, v] of Object.entries(sel.matchLabels))
+        if (labels[k] !== v)
+            return false;
+    for (const e of sel.matchExpressions) {
+        const has = Object.prototype.hasOwnProperty.call(labels, e.key);
+        switch (e.operator) {
+            case "In":
+                if (!has || !e.values.includes(labels[e.key]))
+                    return false;
+                break;
+            case "NotIn":
+                if (has && e.values.includes(labels[e.key]))
+                    return false;
+                break;
+            case "Exists":
+                if (!has)
+                    return false;
+                break;
+            case "DoesNotExist":
+                if (has)
+                    return false;
+                break;
+            default:
+                throw new Unjudgeable(`podSelector operator ${JSON.stringify(e.operator)} is not one of ${SELECTOR_OPERATORS.join(" / ")}`);
+        }
+    }
+    return true;
+}
+function readCidr(v, where) {
+    const cidr = stringAt(v, where);
+    parseCidr(cidr);
+    return cidr;
+}
+function readRule(v, where) {
+    const r = recordAt(v, where);
+    const to = optArrayAt(r.to, `${where}.to`);
+    const blocks = [];
+    for (const [i, peer] of (to ?? []).entries()) {
+        const ip = optRecordAt(recordAt(peer, `${where}.to[${i}]`).ipBlock, `${where}.to[${i}].ipBlock`);
+        if (ip === undefined)
+            continue;
+        blocks.push({ cidr: readCidr(ip.cidr, `${where}.to[${i}].ipBlock.cidr`), except: (optArrayAt(ip.except, `${where}.to[${i}].ipBlock.except`) ?? []).map((x, j) => readCidr(x, `${where}.to[${i}].ipBlock.except[${j}]`)) });
+    }
+    const ports = optArrayAt(r.ports, `${where}.ports`);
+    const portText = ports === undefined || ports.length === 0
+        ? "all"
+        : ports
+            .map((p, i) => {
+            const x = recordAt(p, `${where}.ports[${i}]`);
+            return `${typeof x.protocol === "string" ? x.protocol : "TCP"}/${typeof x.port === "number" || typeof x.port === "string" ? x.port : "*"}${typeof x.endPort === "number" ? `-${x.endPort}` : ""}`;
+        })
+            .join(",");
+    return { to: to === undefined || to.length === 0 ? undefined : blocks, ports: portText };
+}
+function isolatesEgress(spec, where) {
+    const types = optArrayAt(spec.policyTypes, `${where}.policyTypes`);
+    return types !== undefined ? types.map((t, i) => stringAt(t, `${where}.policyTypes[${i}]`)).includes("Egress") : spec.egress !== undefined && spec.egress !== null;
+}
+function egressPolicies(json, podLabels) {
+    const out = [];
+    for (const [i, item] of listItems(json, "networkpolicies").entries()) {
+        const p = recordAt(item, `networkpolicies[${i}]`);
+        const name = stringAt(recordAt(p.metadata, `networkpolicies[${i}].metadata`).name, `networkpolicies[${i}].metadata.name`);
+        const spec = recordAt(p.spec, `networkpolicy ${name} spec`);
+        if (!isolatesEgress(spec, `networkpolicy ${name}`) || !selects(readSelector(spec.podSelector, `networkpolicy ${name} podSelector`), podLabels))
+            continue;
+        out.push({ name, rules: (optArrayAt(spec.egress, `networkpolicy ${name} egress`) ?? []).map((r, j) => readRule(r, `networkpolicy ${name} egress[${j}]`)) });
+    }
+    return out;
+}
+function nodeAddresses(json) {
+    const out = [];
+    for (const [i, item] of listItems(json, "nodes").entries()) {
+        const n = recordAt(item, `nodes[${i}]`);
+        const node = stringAt(recordAt(n.metadata, `nodes[${i}].metadata`).name, `nodes[${i}].metadata.name`);
+        const addresses = arrayAt(recordAt(n.status, `node ${node} status`).addresses, `node ${node} status.addresses`);
+        let seen = 0;
+        for (const [j, a] of addresses.entries()) {
+            const x = recordAt(a, `node ${node} status.addresses[${j}]`);
+            const type = stringAt(x.type, `node ${node} status.addresses[${j}].type`);
+            if (type !== "InternalIP" && type !== "ExternalIP")
+                continue;
+            const address = stringAt(x.address, `node ${node} status.addresses[${j}].address`);
+            if (isIP(address) === 0)
+                throw new Unjudgeable(`node ${node} ${type} ${JSON.stringify(address)} is not an IP address`);
+            out.push({ node, addressType: type, address });
+            seen++;
+        }
+        if (seen === 0)
+            throw new Unjudgeable(`node ${node} reports no InternalIP / ExternalIP`);
+    }
+    return out;
+}
+function parseCidr(cidr) {
+    const slash = cidr.indexOf("/");
+    const net = slash < 0 ? cidr : cidr.slice(0, slash);
+    const fam = isIP(net);
+    const max = fam === 6 ? 128 : 32;
+    const prefix = slash < 0 ? max : Number(cidr.slice(slash + 1));
+    if (fam === 0 || !/^\d+$/.test(slash < 0 ? String(max) : cidr.slice(slash + 1)) || prefix > max)
+        throw new Unjudgeable(`ipBlock cidr ${JSON.stringify(cidr)} does not parse`);
+    return { net, prefix, family: fam === 6 ? "ipv6" : "ipv4" };
+}
+function inCidr(address, cidr) {
+    const c = parseCidr(cidr);
+    if ((isIP(address) === 6 ? "ipv6" : "ipv4") !== c.family)
+        return false;
+    const list = new BlockList();
+    list.addSubnet(c.net, c.prefix, c.family);
+    return list.check(address, c.family);
+}
+function ruleAllows(rule, address) {
+    if (rule.to === undefined)
+        return true;
+    return rule.to.some((b) => inCidr(address, b.cidr) && !b.except.some((x) => inCidr(address, x)));
+}
+function readTable(read, what, parse, gaps) {
+    if (!read.ok) {
+        gaps.push({ kind: "unreadable", what, detail: read.detail });
+        return undefined;
+    }
+    try {
+        return parse(read.json);
+    }
+    catch (e) {
+        gaps.push({ kind: "unreadable", what, detail: e instanceof Unjudgeable ? e.message : `answer not understood: ${e instanceof Error ? e.message : String(e)}` });
+        return undefined;
+    }
+}
+export function sandboxEgressGaps(inputs) {
+    const gaps = [];
+    const policies = readTable(inputs.policies, "networkpolicies", (json) => egressPolicies(json, inputs.podLabels), gaps);
+    const addresses = readTable(inputs.nodes, "nodes", nodeAddresses, gaps);
+    if (policies !== undefined && policies.length === 0)
+        gaps.push({ kind: "policy_absent" });
+    if (policies !== undefined && policies.length > 0 && addresses !== undefined) {
+        for (const a of addresses) {
+            for (const p of policies) {
+                const rule = p.rules.find((r) => ruleAllows(r, a.address));
+                if (rule !== undefined) {
+                    gaps.push({ kind: "node_address_open", node: a.node, addressType: a.addressType, address: a.address, policy: p.name, ports: rule.ports });
+                    break;
+                }
+            }
+        }
+    }
+    if (inputs.ipv6 === "enabled")
+        gaps.push({ kind: "ipv6_enabled" });
+    return gaps;
+}
+function effectOf(gap) {
+    switch (gap.kind) {
+        case "node_address_open":
+            return "sandbox pods can reach this node address through the egress policy — add it to sandbox.networkPolicy.nodeCidrs (kube-up lists every node's addresses) or narrow the allowing rule";
+        case "policy_absent":
+            return "no NetworkPolicy selects the sandbox pods for egress — the policy layer does not restrict sandbox egress (chart sandbox.networkPolicy.enabled, or the CNI's own policy)";
+        case "ipv6_enabled":
+            return "sandbox pods keep IPv6 — an enforcement layer that filters only IPv4 leaves the pods' IPv6 (link-local included) unfiltered; K8S_SANDBOX_IPV6=disabled turns it off in the pod (needs the two sysctls allowed by every node's kubelet)";
+        case "unreadable":
+            return `the ${gap.what} could not be read — this part of the egress check did not run (the server's k8s account needs ${gap.what === "nodes" ? "get/list on nodes (cluster scope)" : "get/list on networkpolicies in the sandbox namespace"})`;
+    }
+}
+export function sayEgressPolicyReading(gaps, logger, namespace) {
+    if (gaps.length === 0) {
+        logger?.info("sandbox_egress_policy_checked", { namespace, gaps: 0 });
+        return;
+    }
+    for (const gap of gaps) {
+        recordFailOpen("server.sandbox-egress.policy-gap", `kind=${gap.kind}${gap.kind === "unreadable" ? ` what=${gap.what}` : ""}`);
+        logger?.warn("sandbox_egress_policy_gap", { namespace, ...gap, effect: effectOf(gap) });
+    }
+}
+//# sourceMappingURL=sandbox-egress-policy.js.map

package/dist/session-error-wire.d.ts

@@ -29,8 +29,8 @@
  *    列表里的缺席),码位各不相同,不由本表统一。
  *  · `invalid_entry` / `invalid_fork_target` / `placement_refused` —— 留白:本仓今天没有一条 wire 口把它们作为自己的
  *    应答(它们在 core 的追加 / 分叉 / 放置面上抛,落进各站点既有的处置或通用 500)。给它们起名是另一件事、另一张票。
- *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 由提交腿的 CAS 冲突臂按结果处置(`runs.ts`
- *    `isSessionConflictResult`),`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
+ *  · `storage` / `conflict` / `unknown` —— 留白:`conflict` 是 run 的写撞上真并发写,落成那条 run 的 `failed` 终局
+ *    (`terminal.code: "conflict"`),提交腿不另作处置;`storage` / `unknown` 是故障类,通用 500 就是它们今天的应答。
  *
  * core 给闭集加一个词 ⇒ 下面的 `switch` 编译红,由人裁定它在两面上的答复,而不是让它静默落进某个恰好存在的臂
  * ([ref] 词表纪律;同形先例 `session-policy-wire.ts` 的 `sessionPolicyErrorHttp`)。

package/dist/session-titler.d.ts

@@ -1,8 +1,10 @@
 /**
  * Auto-generated session titles.
  *
- * SHAPE: fire-and-forget at a task submit whose session has NO title (the objective is known then — no need to wait
- * for the run to finish, and the web Recents gets the title sooner). Fills a NULL title only (`setTitleIfNull`,
+ * SHAPE: fire-and-forget once the ENGINE ACCEPTS a submitted run whose session has NO title — the one caller is the
+ * submission's acceptance seat (`run-acceptance.ts`: the objective entered the conversation, or a result-only verify /
+ * cascade leg came back having done work). A run the engine refuses before acceptance never reaches the titler (no
+ * model call for a refused input). No need to wait for the run to finish, and the web Recents gets the title sooner. Fills a NULL title only (`setTitleIfNull`,
  * store-side `WHERE title IS NULL`) — the user writes the SAME column unconditionally (`PATCH /v1/sessions/:id` →
  * `patchSessionMeta`): a user-set title is never overwritten (the probe below reads "titled" and skips the model
  * call), and a title the user cleared (`title: null` ⇒ NULL) is filled again at the next submit (law: `session-row.ts`).
@@ -25,7 +27,7 @@ export interface SessionTitlerDeps {
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
     /** Cheap pre-LLM probe: "titled" = skip (a restart/evicted-seen/another replica
      *  already paid — don't re-spend an LLM call); "untitled" = generate; "none" = the session_meta row hasn't
-     *  been REGISTERED yet (createRun fires before the Runner's session acquire) — retry after a grace window,
+     *  been REGISTERED (or was deleted meanwhile) — retry after a grace window,
      *  and if still absent, release the seen slot so the NEXT submit retries (never a permanently-untitled
      *  session via a swallowed early UPDATE-0). Local lane has no row-existence dimension → never "none". */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;

package/dist/trace/core-keyset-guard.d.ts

@@ -50,7 +50,7 @@ type _GuardAskReverse = AssertAllKeysHandled<Exclude<AskProjected | AskExcluded,
 type AskFrameServerMinted = "type" | "approvalId" | "argsOmitted" | "outcome" | "governanceForced" | "expiresAtMs" | "expiresInMs" | "serverNowMs" | "parked" | "cause" | "inputHasBidi" | "rememberRefused";
 type _GuardAskFrame = AssertAllKeysHandled<Exclude<keyof ToolApprovalFrame, AskProjected | AskFrameServerMinted>>;
 type _GuardAskFrameReverse = AssertAllKeysHandled<Exclude<AskProjected | AskFrameServerMinted, keyof ToolApprovalFrame>>;
-type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest" | "text_end" | "tool_roster_delta" | "tool_progress" | "tool_disclosure";
+type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome" | "human_input" | "wiring_manifest" | "text_end" | "tool_roster_delta" | "tool_progress" | "tool_disclosure" | "task_started";
 type _GuardTaskEvent = AssertAllKeysHandled<Exclude<TaskEvent["type"], TaskEventHandled>>;
 type _GuardTaskEventReverse = AssertAllKeysHandled<Exclude<TaskEventHandled, TaskEvent["type"]>>;
 type MailboxProjected = "seq" | "from" | "content" | "sentAt" | "hopChain" | "peerMeta";
@@ -149,7 +149,8 @@ type _GuardParkArmQueue = AssertAllKeysHandled<Exclude<ParkArmKeys, ParkArmQueue
 type _GuardParkArmQueueReverse = AssertAllKeysHandled<Exclude<ParkArmQueueProjected | ParkArmQueueExcluded, ParkArmKeys>>;
 type _NoDoubleBookParkArmQueue = AssertAllKeysHandled<Extract<ParkArmQueueProjected, ParkArmQueueExcluded>>;
 type TaskSpecWired = "objective" | "principal" | "images" | "sessionId" | "requireExistingSession" | "oneShot" | "clientContext" | "resumeAt" | "resumeAtMode" | "model" | "compactionModel" | "thinking" | "systemPrompt" | "appendSystemPrompt" | "promptProvider" | "memory" | "suggestNextPrompts" | "restoreFiles" | "acceptPartialRestore" | "rewindFilesTo" | "tools" | "excludeTools" | "deferTools" | "toolMaterializeStrategy" | "promptProfile" | "toolPolicy" | "onAsk" | "onQuestion" | "hooks" | "durableApproval" | "resourceSuspend" | "resilience" | "finalVerification" | "checkpointStore" | "handsReadOnly" | "memoryPersistenceCapable" | "additionalDirectories" | "additionalReadDirectories" | "enablePlanMode" | "interactiveTools" | "enableFork" | "shellGate" | "approvalReach" | "writeFace" | "mcp" | "a2a" | "skills" | "backgroundScope" | "envFacts" | "limits" | "configOverrides" | "forwardSubagentEvents" | "retainSubagentSessions" | "retainBackgroundProcesses" | "outputSchema" | "outputRetries" | "compaction" | "attachments" | "selfOrchestration" | "getApiKeyAndHeaders" | "interactionPosture" | "agents" | "permissionMode" | "taskId" | "signal" | "preemptSignal" | "maxSuspends" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "excludeAllTools" | "fileHistory" | "userInvokedSkills" | "outputStyle" | "allowedTools" | "allowTools";
-type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars" | "peerPresence" | "writeProtectedAdditions" | "complianceAdditionalDenies" | "modelRole" | "enableBlockedReport";
+/** 导出:请求体键闭集门(`request-key-closure.ts`)据它锁「本仓记为未接线的引擎座,提交口不许受理」—— 两处分类只能同向。 */
+export type TaskSpecUnwired = "actor" | "roles" | "lspManager" | "tracer" | "readFace" | "readDenyPatterns" | "interactiveQuestionFallback" | "alwaysLoadTools" | "restoreGatedTools" | "deferSelfResolve" | "basePolicyForResumeEdit" | "lspDiagnostics" | "streamingToolExecution" | "toolResultThresholdChars" | "peerPresence" | "writeProtectedAdditions" | "complianceAdditionalDenies" | "modelRole" | "enableBlockedReport" | "userAttachments";
 type _GuardTaskSpec = AssertAllKeysHandled<Exclude<keyof TaskSpec, TaskSpecWired | TaskSpecUnwired>>;
 type _GuardTaskSpecReverse = AssertAllKeysHandled<Exclude<TaskSpecWired | TaskSpecUnwired, keyof TaskSpec>>;
 type TaskResultForwarded = "taskId" | "runId" | "sessionId" | "terminal" | "model" | "effectiveReasoning" | "result" | "salvagedOutput" | "remoteEnvFailures" | "apiFailure" | "retryAfterMs" | "degraded" | "structuredOutput" | "rewindNotes" | "haltedOnUserRejection" | "haltedByUser" | "strandedHumanAnswers" | "pendingApproval" | "approvalWaitedMs" | "effectiveReadFace" | "effectiveReadDenyPatterns" | "effectiveWriteFace" | "effectiveMemoryScopes" | "stats" | "editedFiles" | "responseModel" | "compaction";

package/dist/trace/ledger-events.d.ts

@@ -39,9 +39,15 @@ export type LedgerEventType = "reasoning" | "text" | "tool_start" | "tool_end" |
 /** [ref](core 7.18.0):本条腿的**延迟工具普查**快照(policy / thresholdPercent? / deferred[] / activated[])。
  *  与 `tool_roster_delta` 同判、同理由——**快照语义**(整只替换,回放零合并),而开腿那一份住在
  *  `wiring_manifest` 之后的首帧、**之后每一次激活**只活在本帧上。整帧缺席 = 这条腿什么都没延迟。
- *  🔴 `tool_progress`([ref])**刻意不在本表**:core 的 `tool_progress.ephemeral` 契约逐字「LIVE ONLY …
- *  core never persists this frame」,与 `task_progress` / `status` 同一处置(两条 durable 腿零 case)。 */
- | "tool_disclosure" | "human_input" | "task_progress" | "task_notification" | "turn_end"
+ *  🔴 `tool_progress`([ref])**刻意不在本表**,理由是它自己的、不是「core 标了 LIVE ONLY」:那一条只是**引擎**的义务
+ *  (不进会话树 / 检查点 / 续跑重放),本仓的账本是异步车道的活流与断线重连面,律是「EPHEMERAL 帧带着回放面没有第二来源的
+ *  事实 ⇒ 落账」(`status` / `task_progress` / `task_started` 都落)。`tool_progress` 的事实由同一只调用的 `tool_end` 推出
+ *  (真源在那里;帧的缺席也从不是证据 —— 一个周期内跑完的调用零帧),所以它不落。 */
+ | "tool_disclosure" | "human_input"
+/** core 7.50.0:委派子代**起跑**帧(每周期一只,先于子代的首个 `task_progress`)。按上面那一条律落账:
+ *  `agentType` / `rootSessionId` / `parentSessionId` / `startedAt` 只骑这一帧,`task_progress` 上没有 ⇒ 不落则异步车道
+ *  (`POST /v1/runs` 的活流就是 `GET /v1/runs/:id/events` 的账本 tail)永远读不到。两条 durable 腿主流 + forward 道各一处写口。 */
+ | "task_started" | "task_progress" | "task_notification" | "turn_end"
 /** park 行名**两个**(`appendParked(kind)` 逐字取自 `result.status`)—— 运行期闭集见
  *  {@link PARK_LEDGER_EVENT_TYPES}(本联合是它的类型面,两者由下方的双向断言锁步)。 */
  | "suspended" | "needs_review" | "done" | "failed" | "suggestions" | "model_usage" | "prompt_assembled" | "config_assembled" | "file_link"

package/dist/trace/ledger-sink.d.ts

@@ -97,6 +97,13 @@ export interface LedgerSink {
  * ⚠️ 用它的前提是**这条腿的全部写口都走它**(混用一个绕开链的写口 = 病灶原样保留)。
  */
 export declare function createSerialLedgerAppend(appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>, startSeq: number): (type: LedgerEventType, data: unknown) => Promise<void>;
+/**
+ * durable 腿 forward 道(fire-and-forget,同步回调里不能 await)的写失败出口 —— 一只,两处用:本汇的 `onForwardEvent`(bg 腿 +
+ * sync detach 车道 + 续跑腿的 verify 臂)与续跑腿自己的 forward 回调(`http/resume-legs.ts`,那里另有既有的逐次 warn 行)。
+ * F 类留痕 `server.ledger.forward-append-failed`:这一帧永远不在回放面(子代的起跑帧 / tick / 工具卡),run 照跑、不改任何裁决。
+ * 返回 `.catch` 用的处理器(产物是函数 ⇒ `create*`)。
+ */
+export declare function createForwardAppendFailedNote(type: string): (err: unknown) => void;
 export declare function createLedgerSink(opts: {
     /** The seq-stamped durable append — typically `(seq, type, data) => runStore.appendEvent(taskId, seq, type, data)`. */
     appendEvent: (seq: number, type: LedgerEventType, data: unknown) => Promise<void>;

package/dist/trace/ledger-sink.js

@@ -1,6 +1,7 @@
 import {} from "@sema-agent/core";
 import { outwardPlane } from "../terminal.js";
-import { modelTextEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, turnEndEventData, contextUsageEventData } from "./project.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { modelTextEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, turnEndEventData, contextUsageEventData } from "./project.js";
 import { NotifiedKeys, taskNotificationStreamKeyOf } from "../orchestration/workflow-completion-inbox.js";
 import { isParkLedgerEventType } from "./ledger-events.js";
 import { isModelSegmentBoundary, reasoningDeltaBytes, reasoningSegmentEventId } from "./model-segment.js";
@@ -13,6 +14,9 @@ export function createSerialLedgerAppend(appendEvent, startSeq) {
         return step;
     };
 }
+export function createForwardAppendFailedNote(type) {
+    return (err) => recordFailOpen("server.ledger.forward-append-failed", `type=${type} err=${err instanceof Error ? err.message : String(err)}`);
+}
 export function createLedgerSink(opts) {
     const keys = opts.notifiedKeys ?? new NotifiedKeys();
     let seq = 0;
@@ -114,6 +118,9 @@ export function createLedgerSink(opts) {
             case "human_input":
                 await append("human_input", humanInputEventData(ev));
                 break;
+            case "task_started":
+                await append("task_started", taskStartedEventData(ev));
+                break;
             case "task_progress":
                 await append("task_progress", taskProgressEventData(ev));
                 break;
@@ -140,13 +147,16 @@ export function createLedgerSink(opts) {
     const onForwardEvent = (e) => {
         const t = e.type;
         if (t === "task_progress") {
-            void append("task_progress", taskProgressEventData(e)).catch(() => undefined);
+            void append("task_progress", taskProgressEventData(e)).catch(createForwardAppendFailedNote(t));
+        }
+        else if (t === "task_started") {
+            void append("task_started", taskStartedEventData(e)).catch(createForwardAppendFailedNote(t));
         }
         else if (t === "tool_start") {
-            void append("tool_start", toolStartEventData(e)).catch(() => undefined);
+            void append("tool_start", toolStartEventData(e)).catch(createForwardAppendFailedNote(t));
         }
         else if (t === "tool_end") {
-            void append("tool_end", toolEndEventData(e)).catch(() => undefined);
+            void append("tool_end", toolEndEventData(e)).catch(createForwardAppendFailedNote(t));
         }
     };
     const appendStatus = (ev) => {

package/dist/trace/project.d.ts

@@ -290,14 +290,13 @@ export declare function toolEndEventData(ev: {
 /**
  * `tool_progress` 的白名单投影(core 7.18.0 [ref])—— 一只**仍在跑**的工具调用的存活 tick。
  *
- * ## 这一帧只上 live,不落账(判据是 core 的契约,不是本仓的偏好)
+ * ## 这一帧只上 live,不落账(判据是回放面有没有第二来源,不是「core 标了 LIVE ONLY」)
  * core `@contract tool_progress.ephemeral` 逐字:「LIVE ONLY, like `task_progress`/`status`: core never
- * persists this frame (no session-tree entry, no checkpoint state, no resume replay)」。本仓对
- * `task_progress` / `status` 正是同一处置(两条 durable 腿零 case),本帧照抄。
- * 另一条 core 契约把「不落账」从偏好抬成正确性:`@contract tool_progress.cadence` 逐字「A call that
- * finishes inside one interval emits NO frame at all」⇒ **帧的缺席从来不是证据**;落账会让回放面凭空
- * 多出一份「这只调用跑了多久」的账,而那件事的真源是 `tool_end`(core 明写 `elapsedTimeSeconds`
- * **不等于** `tool_end` 的 duration)。
+ * persists this frame (no session-tree entry, no checkpoint state, no resume replay)」—— 那是**引擎**的义务;
+ * 本仓的律是「EPHEMERAL 帧带着回放面没有第二来源的事实 ⇒ 落账」(`status` / `task_progress` / `task_started` 都落)。
+ * 本帧的事实**有**第二来源:`@contract tool_progress.cadence` 逐字「A call that finishes inside one interval emits
+ * NO frame at all」⇒ **帧的缺席从来不是证据**;落账会让回放面凭空多出一份「这只调用跑了多久」的账,而那件事的
+ * 真源是 `tool_end`(core 明写 `elapsedTimeSeconds` **不等于** `tool_end` 的 duration)。
  *
  * ## 信任划线
  *  · `toolCallId` / `toolName` —— 调用 id(🔴 S-283 订正:出身是**服务商**在 tool_use / tool_calls 里给的,引擎缺席时自铸兜底、越界时折叠 ——
@@ -309,7 +308,8 @@ export declare function toolEndEventData(ev: {
  *  · `elapsedTimeSeconds` —— 引擎铸的整秒,单调、一 call 一个原点 ⇒ 有限数才铸键。
  *  · `output` —— 🔴 **UNTRUSTED RAW**,core 逐字「exactly as `tool_end.output`: process output that may
  *    carry secrets, paths or PII; core bounds only its SIZE, and a consumer MUST redact before persisting
- *    or displaying it」⇒ 与 `tool_end.output` **同一只** `redactDeep`,一个字节的例外都不开。
+ *    or displaying it」⇒ 与 `tool_end.output` **同一只**投影 `projectToolOutput`(串形与文本块整只过 `redactDeep`;本帧只有串形,
+ *    媒体块那一臂在这里够不着),一个字节的例外都不开。
  *  · `totalLines` / `totalBytes` —— 引擎计数;core 的缺席律逐字:三者**同进同退**(在场=「观察到了输出」,
  *    缺席=「一个字节都没观察到」,**从不是**「与上一帧相比没变」)。所以本投影按 `output` 的在场判三者:
  *    `output` 读不出 ⇒ 三键一起缺席,不单独留下两个计数(那会把「没输出」谎报成「有输出但读不出」)。
@@ -373,6 +373,47 @@ export declare function taskProgressEventData(ev: {
     seq?: number;
     model?: string;
 }): Record<string, unknown>;
+/**
+ * The `task_started` payload(core 7.50.0):一只委派子代**起跑**的那一帧 —— 每周期一只(首派 / 复活;耐久续跑腿不铸),
+ * 序在子代的 `wiring_manifest` 之后、它的首个 `task_progress` 与首次模型请求之前。
+ *
+ * **活面投、账本落**(与 `task_progress` / `status` 同一条律)。core 契约逐字「Live and ephemeral like `task_progress`:
+ * never persisted, never replayed on resume, absent from checkpoints」—— 那是**引擎**的义务(不进会话树、检查点、续跑重放)。
+ * 本服务的账本是异步车道的活流(`POST /v1/runs` 的观看者读的就是 `GET /v1/runs/:id/events` 的账本 tail)与断线重连面,
+ * 律是「**EPHEMERAL 帧带着回放面没有第二来源的事实 ⇒ 落账**」:`agentType` / `rootSessionId` / `parentSessionId` / `startedAt`
+ * 只骑这一帧,`task_progress` 上没有。(`tool_progress` 不落是同一条律的反面:它的事实由同一只调用的 `tool_end` 推出。)
+ * 调用点:三条 live 腿(sync 主流、sync forward 道、子代 tail 总线)+ 两条 durable 腿(账本汇、resume 腿)各自的主流臂与
+ * forward 道 —— 即 `task_progress` 的全部投影点,同一只构造器。
+ *
+ * 键的信任判与 `task_progress` 孪生**逐键同**(core 原话「every member is a value the run already speaks
+ * elsewhere — this frame introduces no new reading of any of them」⇒ 本仓也不铸第二种读法):
+ *  · run / 会话 id、`seq`、`taskType`、`model`、`workflowRunId`、`agentType` —— 引擎值 verbatim(`agentType` 是解析过的子代类型名,
+ *    不是模型自由文本);`startedAt` 是有限数才上 wire;
+ *  · `name` / `workflowAgentLabel` —— UNTRUSTED 展示文本 ⇒ `redactSecrets`(同 `task_progress.name` / `.workflowAgentLabel`);
+ *  · `spawnName` —— 出生点校验过的队友**身份键** ⇒ verbatim(理由全文在 {@link taskProgressEventData} 的同名键注);
+ *  · 身份两键经 `identityFields`(信封上的 `sourceTaskId` / `bgAgentId` 不由本族构造器投,见 `FRAME_ENVELOPE_KEYS`)。
+ * 缺席即缺席:可选键缺席不铸键(`taskType` 缺席 = 前台子代,禁读作某个默认种类;`seq` 缺席 = 无 `a*` 行,禁读作 cycle 1)。
+ */
+export declare function taskStartedEventData(ev: {
+    /** 判别位(入参就是那一帧;本构造器不投它 —— 帧名由调用点的 `type` 键 / 账本行名给)。 */
+    type?: "task_started";
+    taskId: string;
+    sessionId: string;
+    taskType?: string;
+    seq?: number;
+    workflowRunId?: string;
+    workflowAgentLabel?: string;
+    parentTaskId?: string;
+    parentSessionId?: string;
+    rootSessionId?: string;
+    name?: string;
+    spawnName?: string;
+    agentType?: string;
+    model: string;
+    startedAt: number;
+    eventId?: string;
+    parentToolCallId?: string;
+}): Record<string, unknown>;
 /** The `task_notification` payload (core 1.202 [ref] P2: a background task finished — this event is the
  *  LEDGER/display projection of the OBSERVED terminal state, emitted the moment core observes it. It does NOT
  *  attest that the `<task-notification>` XML has entered the model context: core's steer targets the NEXT TURN