@zhushanwen/subagent-engine-sdk 0.10.1 → 0.12.0

package/dist/index.d.cts

@@ -1,22 +1,21 @@
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReverseChannel, ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.cjs';
-export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from './error-codes-f-UO4a8D.cjs';
-export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from './methods-BLxg4ZFr.cjs';
-export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from './contract-types-jSa1g28F.cjs';
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReverseChannel, ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUBAGENT_CONTROL_CLOSED_REASONS, SUBAGENT_CONTROL_FRAME_KINDS, SUBAGENT_CONTROL_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_RANGE, SubagentControlClosedReason, SubagentControlFrameKind, errorResponseFrameSchema, isProtocolVersionCompatible, isSubagentControlClosedReason, isSubagentControlFrameKind, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.cjs';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_SPAWN_DELIVERY_ERROR_CODES, d as ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY, e as ENGINE_TIMEOUT_RECOVERY, f as ENGINE_TRANSPORT_ERROR_CODES, g as ENGINE_TRANSPORT_ERROR_RECOVERY, h as EngineProtocolErrorCode, E as EngineSdkError, i as EngineSpawnDeliveryErrorCode, j as EngineTransportErrorCode, k as ErrorResponseFrame, l as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, m as ResponseFrame, n as ReverseRequestFrame, o as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, p as SET_MODEL_NOT_ACTIVE_CODE, q as STDOUT_TAIL_ECHO_CHARS, r as SetModelErrorCode, s as SuccessResponseFrame, t as assertChatConversationSupported, u as engineConversationUnsupportedError, v as engineProtocolMismatchError, w as engineSetModelUnsupportedError, x as engineTimeoutDetail, y as isEngineErrorPassthroughCode, z as isEngineProtocolErrorCode, A as isNotificationFrame, B as isRequestFrame, C as isResponseFrame, D as isReverseRequestFrame, F as schemaEmulationFailedDetail } from './error-codes-CgcjlmeD.cjs';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from './methods-BzvzcCrB.cjs';
+export { h as AGENT_EVENT_TYPE_NAMES, c as AgentCallOpts, A as AgentEvent, i as AgentEventTypeName, j as AgentFailureKind, d as AgentOutcome, k as AgentOutcomeUsage, a as AgentUsage, b as AgentUsageTotal, l as AssertMutuallyAssignable, e as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, n as EngineStopReason, F as FAILURE_CAUSE_CLOSED_KINDS, o as FAILURE_CAUSE_KINDS_BY_CLASS, p as FAILURE_CAUSE_KINDS_BY_CLASS_LOCK, q as FAILURE_CAUSE_KIND_VOCAB_LOCK, r as FailureCause, s as FailureCauseClass, t as FailureRetryability, I as InternalToolCall, g as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, f as ResumeAnchor, S as SessionView, u as ToolCall, v as ToolCallEntry, w as ToolCallResult, T as Turn, W as WorktreeHandle, _ as _EventVocabSyncLock } from './contract-types-C1scOS_M.cjs';
 export { SCHEMA_EMULATION_TAIL_CHARS, StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput } from './schema-emulation.cjs';
 export { ExecutionNestingContext, ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv } from './nesting-guard.cjs';
 export { CoreLogger, LogLevel, LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests } from './logger.cjs';
 export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome } from './kill-chain.cjs';
-export { ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.cjs';
+export { ErrorFact, ReplayRecordView, addUsage, aggregateUsage, appendErrorFact, createReplayRecord, emptyTurn, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.cjs';
 export { TAIJI_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir } from './data-dir.cjs';
 export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg } from './paths.cjs';
 export { UiMethod, UiRequest, UiRequestHandler, UiResponse, isUiResponse } from './ui-types.cjs';
 export { ChannelHandler, ExtensionUiRequestLike, ParsedChannel, UiChannelRegistry, createUiChannelRegistry, parseChannel } from './ui-channels.cjs';
-export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv } from './env.cjs';
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.cjs';
+export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv } from './env.cjs';
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, KillOwnProcessGroupDeps, KillOwnProcessGroupSpawnResult, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, killOwnProcessGroup, pumpNdjsonLines, spawnEngineChild } from './spawn.cjs';
 export { ENGINE_NODE_ENV, EngineNodeHostKind, EngineNodeLaunch, EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch } from './node-executor.cjs';
 export { CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams } from './logs/stderr-rotation.cjs';
 export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS, ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS } from './zcode-db-paths.cjs';
-export { RELAY_ENV_NODE, RELAY_ENV_RECORD_ID, RELAY_ENV_SCRIPT, RELAY_ENV_SESSION_ID, RELAY_ENV_SOCKET, RELAY_EXIT_CODES, RELAY_PROTOCOL_VERSION, isRelayActive, readRelayForwardEnv } from './relay-env.cjs';
 export { toErrorMessage } from './error-message.cjs';
 export { BestEffortLevel, bestEffort } from './best-effort.cjs';
 export { replayJournal } from './journal-io.cjs';
@@ -50,38 +49,27 @@ declare const SUBAGENT_IDENTITY_ENV: {
     /** worktree 隔离标志（"true" = 是）。 */
     readonly worktree: "PI_SUBAGENT_WORKTREE";
 };
+/**
+ * [M1 D2] 任务文本进 env 的截断上限（字符数）：写入点 = pi 引擎 spawn-runner 的
+ * applyContentIdentityKeys——写 `params.task` 前 2000 字符 + 截断标记
+ * `…[truncated N chars]`；env 读取点（appendSubagentIdentityEntry）零改动（读 env 值
+ * 即用）。全文以 pi session 文件首条 user 消息与父侧 manifest 为准（manifest 主路径
+ * 保留全文；截断只影响 manifest 缺席时的重建链/P-fallback 投影，降级面逐层判定登记
+ * 见设计 D2 消费方矩阵与 §3.7）。目的：控制面（握手帧）与 execve env 不再随任务正文
+ * 线性膨胀（ARG_MAX/E2BIG 族无界暴露的写入点根因修复）。
+ */
+declare const PI_SUBAGENT_TASK_MAX_CHARS = 2000;
 
-/** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
-declare const RELAY_FRAME_KINDS: {
-    readonly handshake: "handshake";
-    readonly accept: "accept";
-    readonly reject: "reject";
-    readonly data: "data";
-    readonly exit: "exit";
-    /**
-     * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
-     * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
-     * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
-     * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
-     * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
-     */
-    readonly goodbye: "goodbye";
-};
-/** 数据泵方向（data 帧 dir 字段词表）。 */
-declare const RELAY_FRAME_DIRS: {
-    readonly down: "down";
-    readonly up: "up";
-    readonly upStderr: "up-stderr";
-};
-/** reject 帧 reason 词表（runtime→代理的拒绝理由；代理对 version 以退出码 10 应答）。 */
-declare const RELAY_REJECT_REASONS: {
-    readonly version: "version";
-    readonly identity: "identity";
-    readonly duplicate: "duplicate";
-    readonly malformed: "malformed";
-};
-type RelayFrameKind = (typeof RELAY_FRAME_KINDS)[keyof typeof RELAY_FRAME_KINDS];
-type RelayFrameDir = (typeof RELAY_FRAME_DIRS)[keyof typeof RELAY_FRAME_DIRS];
-type RelayRejectReason = (typeof RELAY_REJECT_REASONS)[keyof typeof RELAY_REJECT_REASONS];
+/** control socket 路径（runtime 监听 `<dataDir>/run/subagent-<pid>.sock`；Windows 为 named pipe）。 */
+declare const CONTROL_ENV_SOCKET = "TAIJI_SUBAGENT_CONTROL_SOCKET";
+/** 主会话根 id（runtime 注入；嵌套链所有层同值——连接归属与 channel 树的归属键）。 */
+declare const CONTROL_ENV_ROOT_SESSION_ID = "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID";
+/**
+ * transport 选择谓词（D5 选择逻辑的单一实现）：SOCKET 非空 = 托管态 → runtime
+ * transport；空串/缺失 = standalone → local transport（调用方 warn）。消费方 =
+ * EngineClient transport 选择（u-m3-rt-transport）；缺失即 local，不存在
+ * 「注入了一半」的中间态。
+ */
+declare function isControlEnvActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
 
-export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason, SUBAGENT_IDENTITY_ENV };
+export { CONTROL_ENV_ROOT_SESSION_ID, CONTROL_ENV_SOCKET, PI_SUBAGENT_TASK_MAX_CHARS, SUBAGENT_IDENTITY_ENV, isControlEnvActive };

package/dist/index.d.ts

@@ -1,22 +1,21 @@
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReverseChannel, ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.js';
-export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from './error-codes-DnFru4L4.js';
-export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from './methods-C2zvZqhP.js';
-export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from './contract-types-jSa1g28F.js';
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReverseChannel, ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUBAGENT_CONTROL_CLOSED_REASONS, SUBAGENT_CONTROL_FRAME_KINDS, SUBAGENT_CONTROL_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_RANGE, SubagentControlClosedReason, SubagentControlFrameKind, errorResponseFrameSchema, isProtocolVersionCompatible, isSubagentControlClosedReason, isSubagentControlFrameKind, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.js';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_SPAWN_DELIVERY_ERROR_CODES, d as ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY, e as ENGINE_TIMEOUT_RECOVERY, f as ENGINE_TRANSPORT_ERROR_CODES, g as ENGINE_TRANSPORT_ERROR_RECOVERY, h as EngineProtocolErrorCode, E as EngineSdkError, i as EngineSpawnDeliveryErrorCode, j as EngineTransportErrorCode, k as ErrorResponseFrame, l as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, m as ResponseFrame, n as ReverseRequestFrame, o as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, p as SET_MODEL_NOT_ACTIVE_CODE, q as STDOUT_TAIL_ECHO_CHARS, r as SetModelErrorCode, s as SuccessResponseFrame, t as assertChatConversationSupported, u as engineConversationUnsupportedError, v as engineProtocolMismatchError, w as engineSetModelUnsupportedError, x as engineTimeoutDetail, y as isEngineErrorPassthroughCode, z as isEngineProtocolErrorCode, A as isNotificationFrame, B as isRequestFrame, C as isResponseFrame, D as isReverseRequestFrame, F as schemaEmulationFailedDetail } from './error-codes-o4rNd1Ee.js';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from './methods-CPMc4cvF.js';
+export { h as AGENT_EVENT_TYPE_NAMES, c as AgentCallOpts, A as AgentEvent, i as AgentEventTypeName, j as AgentFailureKind, d as AgentOutcome, k as AgentOutcomeUsage, a as AgentUsage, b as AgentUsageTotal, l as AssertMutuallyAssignable, e as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, n as EngineStopReason, F as FAILURE_CAUSE_CLOSED_KINDS, o as FAILURE_CAUSE_KINDS_BY_CLASS, p as FAILURE_CAUSE_KINDS_BY_CLASS_LOCK, q as FAILURE_CAUSE_KIND_VOCAB_LOCK, r as FailureCause, s as FailureCauseClass, t as FailureRetryability, I as InternalToolCall, g as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, f as ResumeAnchor, S as SessionView, u as ToolCall, v as ToolCallEntry, w as ToolCallResult, T as Turn, W as WorktreeHandle, _ as _EventVocabSyncLock } from './contract-types-C1scOS_M.js';
 export { SCHEMA_EMULATION_TAIL_CHARS, StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput } from './schema-emulation.js';
 export { ExecutionNestingContext, ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv } from './nesting-guard.js';
 export { CoreLogger, LogLevel, LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests } from './logger.js';
 export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome } from './kill-chain.js';
-export { ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.js';
+export { ErrorFact, ReplayRecordView, addUsage, aggregateUsage, appendErrorFact, createReplayRecord, emptyTurn, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.js';
 export { TAIJI_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir } from './data-dir.js';
 export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg } from './paths.js';
 export { UiMethod, UiRequest, UiRequestHandler, UiResponse, isUiResponse } from './ui-types.js';
 export { ChannelHandler, ExtensionUiRequestLike, ParsedChannel, UiChannelRegistry, createUiChannelRegistry, parseChannel } from './ui-channels.js';
-export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv } from './env.js';
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.js';
+export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv } from './env.js';
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, KillOwnProcessGroupDeps, KillOwnProcessGroupSpawnResult, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, killOwnProcessGroup, pumpNdjsonLines, spawnEngineChild } from './spawn.js';
 export { ENGINE_NODE_ENV, EngineNodeHostKind, EngineNodeLaunch, EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch } from './node-executor.js';
 export { CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams } from './logs/stderr-rotation.js';
 export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS, ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS } from './zcode-db-paths.js';
-export { RELAY_ENV_NODE, RELAY_ENV_RECORD_ID, RELAY_ENV_SCRIPT, RELAY_ENV_SESSION_ID, RELAY_ENV_SOCKET, RELAY_EXIT_CODES, RELAY_PROTOCOL_VERSION, isRelayActive, readRelayForwardEnv } from './relay-env.js';
 export { toErrorMessage } from './error-message.js';
 export { BestEffortLevel, bestEffort } from './best-effort.js';
 export { replayJournal } from './journal-io.js';
@@ -50,38 +49,27 @@ declare const SUBAGENT_IDENTITY_ENV: {
     /** worktree 隔离标志（"true" = 是）。 */
     readonly worktree: "PI_SUBAGENT_WORKTREE";
 };
+/**
+ * [M1 D2] 任务文本进 env 的截断上限（字符数）：写入点 = pi 引擎 spawn-runner 的
+ * applyContentIdentityKeys——写 `params.task` 前 2000 字符 + 截断标记
+ * `…[truncated N chars]`；env 读取点（appendSubagentIdentityEntry）零改动（读 env 值
+ * 即用）。全文以 pi session 文件首条 user 消息与父侧 manifest 为准（manifest 主路径
+ * 保留全文；截断只影响 manifest 缺席时的重建链/P-fallback 投影，降级面逐层判定登记
+ * 见设计 D2 消费方矩阵与 §3.7）。目的：控制面（握手帧）与 execve env 不再随任务正文
+ * 线性膨胀（ARG_MAX/E2BIG 族无界暴露的写入点根因修复）。
+ */
+declare const PI_SUBAGENT_TASK_MAX_CHARS = 2000;
 
-/** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
-declare const RELAY_FRAME_KINDS: {
-    readonly handshake: "handshake";
-    readonly accept: "accept";
-    readonly reject: "reject";
-    readonly data: "data";
-    readonly exit: "exit";
-    /**
-     * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
-     * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
-     * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
-     * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
-     * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
-     */
-    readonly goodbye: "goodbye";
-};
-/** 数据泵方向（data 帧 dir 字段词表）。 */
-declare const RELAY_FRAME_DIRS: {
-    readonly down: "down";
-    readonly up: "up";
-    readonly upStderr: "up-stderr";
-};
-/** reject 帧 reason 词表（runtime→代理的拒绝理由；代理对 version 以退出码 10 应答）。 */
-declare const RELAY_REJECT_REASONS: {
-    readonly version: "version";
-    readonly identity: "identity";
-    readonly duplicate: "duplicate";
-    readonly malformed: "malformed";
-};
-type RelayFrameKind = (typeof RELAY_FRAME_KINDS)[keyof typeof RELAY_FRAME_KINDS];
-type RelayFrameDir = (typeof RELAY_FRAME_DIRS)[keyof typeof RELAY_FRAME_DIRS];
-type RelayRejectReason = (typeof RELAY_REJECT_REASONS)[keyof typeof RELAY_REJECT_REASONS];
+/** control socket 路径（runtime 监听 `<dataDir>/run/subagent-<pid>.sock`；Windows 为 named pipe）。 */
+declare const CONTROL_ENV_SOCKET = "TAIJI_SUBAGENT_CONTROL_SOCKET";
+/** 主会话根 id（runtime 注入；嵌套链所有层同值——连接归属与 channel 树的归属键）。 */
+declare const CONTROL_ENV_ROOT_SESSION_ID = "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID";
+/**
+ * transport 选择谓词（D5 选择逻辑的单一实现）：SOCKET 非空 = 托管态 → runtime
+ * transport；空串/缺失 = standalone → local transport（调用方 warn）。消费方 =
+ * EngineClient transport 选择（u-m3-rt-transport）；缺失即 local，不存在
+ * 「注入了一半」的中间态。
+ */
+declare function isControlEnvActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
 
-export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason, SUBAGENT_IDENTITY_ENV };
+export { CONTROL_ENV_ROOT_SESSION_ID, CONTROL_ENV_SOCKET, PI_SUBAGENT_TASK_MAX_CHARS, SUBAGENT_IDENTITY_ENV, isControlEnvActive };

package/dist/index.js

@@ -1,14 +1,3 @@
-import {
-  RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES,
-  RELAY_PROTOCOL_VERSION,
-  isRelayActive,
-  readRelayForwardEnv
-} from "./chunk-GSW3DMN6.js";
 import {
   bestEffort
 } from "./chunk-QMEHSKNR.js";
@@ -52,22 +41,23 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-AF2ETADP.js";
+} from "./chunk-2L3I2TWJ.js";
 import {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
+  killOwnProcessGroup,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-HSNDUHFH.js";
+} from "./chunk-3MCOZY3Z.js";
 import {
   ENGINE_NODE_ENV,
   hostKindOf,
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-NTOLHLCL.js";
+} from "./chunk-QGXILDWB.js";
 import {
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
@@ -82,18 +72,28 @@ import {
 import {
   AGENT_EVENT_TYPE_NAMES,
   ENGINE_PROTOCOL_SCHEMAS,
+  FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
+  _EventVocabSyncLock,
   errorResponseFrameSchema,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "./chunk-LM7P7OTA.js";
+} from "./chunk-7R6HYT2A.js";
 import {
   isNotificationFrame,
   isRequestFrame,
@@ -122,7 +122,7 @@ import {
   probePidAlive,
   safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-CNCFMPEH.js";
+} from "./chunk-TJMS3YOR.js";
 import {
   toErrorMessage
 } from "./chunk-PYO3YR7W.js";
@@ -131,7 +131,11 @@ import {
   ENGINE_ERROR_CODE_PREFIX,
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   HANDSHAKE_TIMEOUT_MS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -151,20 +155,23 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "./chunk-JZN76I3S.js";
+} from "./chunk-NVF3PADP.js";
 import {
   configureLoggerSink,
   getLogger,
   resetLoggerSinkForTests
 } from "./chunk-NXNNXGTY.js";
 import {
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   createReplayRecord,
+  emptyTurn,
   eventsToSessionView,
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-SGAIDL63.js";
+} from "./chunk-U5MBAKS5.js";
 import "./chunk-JSBRDJBE.js";
 
 // src/identity-env.ts
@@ -194,37 +201,19 @@ var SUBAGENT_IDENTITY_ENV = {
   /** worktree 隔离标志（"true" = 是）。 */
   worktree: "PI_SUBAGENT_WORKTREE"
 };
+var PI_SUBAGENT_TASK_MAX_CHARS = 2e3;
 
-// src/relay-frames.ts
-var RELAY_FRAME_KINDS = {
-  handshake: "handshake",
-  accept: "accept",
-  reject: "reject",
-  data: "data",
-  exit: "exit",
-  /**
-   * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
-   * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
-   * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
-   * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
-   * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
-   */
-  goodbye: "goodbye"
-};
-var RELAY_FRAME_DIRS = {
-  down: "down",
-  up: "up",
-  upStderr: "up-stderr"
-};
-var RELAY_REJECT_REASONS = {
-  version: "version",
-  identity: "identity",
-  duplicate: "duplicate",
-  malformed: "malformed"
-};
+// src/control-env.ts
+var CONTROL_ENV_SOCKET = "TAIJI_SUBAGENT_CONTROL_SOCKET";
+var CONTROL_ENV_ROOT_SESSION_ID = "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID";
+function isControlEnvActive(env) {
+  return Boolean(env[CONTROL_ENV_SOCKET]);
+}
 export {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
+  CONTROL_ENV_ROOT_SESSION_ID,
+  CONTROL_ENV_SOCKET,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -240,25 +229,24 @@ export {
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   ExecutionNestingContext,
+  FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS,
   HOST_TIMEOUT_ABORT_REASON,
   NESTED_SPAWN_ENV,
   NestedSpawnRejectedError,
+  PI_SUBAGENT_TASK_MAX_CHARS,
   PROTOCOL_METHODS,
-  RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES,
-  RELAY_FRAME_DIRS,
-  RELAY_FRAME_KINDS,
-  RELAY_PROTOCOL_VERSION,
-  RELAY_REJECT_REASONS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -270,14 +258,20 @@ export {
   SHARED_POOL_KEY,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX,
   ZCODE_ISOLATED_DB_SEGMENTS,
   ZCODE_PI_SYNCED_PROVIDER_CONFIG_SEGMENTS,
+  _EventVocabSyncLock,
   abortWithFallback,
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   armEngineSelfDestruct,
   assertChatConversationSupported,
   assertNotNestedSpawn,
@@ -291,6 +285,7 @@ export {
   configureLoggerSink,
   createReplayRecord,
   createUiChannelRegistry,
+  emptyTurn,
   engineConversationUnsupportedError,
   engineProtocolMismatchError,
   engineSetModelUnsupportedError,
@@ -300,17 +295,20 @@ export {
   extractAndValidateStructuredOutput,
   getLogger,
   hostKindOf,
+  isControlEnvActive,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
   isNotificationFrame,
   isPidAlive,
   isProtocolVersionCompatible,
-  isRelayActive,
   isRequestFrame,
   isResponseFrame,
   isReverseRequestFrame,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   isUiResponse,
   killChain,
+  killOwnProcessGroup,
   killPidChain,
   notificationFrameSchema,
   parseChannel,
@@ -319,7 +317,6 @@ export {
   probePidAlive,
   protocolErrorSchema,
   pumpNdjsonLines,
-  readRelayForwardEnv,
   replayJournal,
   requestFrameSchema,
   resetDataDirWarnForTests,

package/dist/journal-io.d.cts

@@ -1,4 +1,4 @@
-import { A as AgentEvent } from './contract-types-jSa1g28F.cjs';
+import { A as AgentEvent } from './contract-types-C1scOS_M.cjs';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-io.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentEvent } from './contract-types-jSa1g28F.js';
+import { A as AgentEvent } from './contract-types-C1scOS_M.js';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-replay.cjs

@@ -20,8 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/journal-replay.ts
 var journal_replay_exports = {};
 __export(journal_replay_exports, {
+  addUsage: () => addUsage,
   aggregateUsage: () => aggregateUsage,
+  appendErrorFact: () => appendErrorFact,
   createReplayRecord: () => createReplayRecord,
+  emptyTurn: () => emptyTurn,
   eventsToSessionView: () => eventsToSessionView,
   sessionIdFromHandle: () => sessionIdFromHandle,
   toReplayedTurn: () => toReplayedTurn,
@@ -60,7 +63,8 @@ function createReplayRecord() {
     turns: [emptyTurn()],
     turnCount: 0,
     totalTokens: 0,
-    lastError: void 0
+    lastError: void 0,
+    errors: []
   };
 }
 function currentTurn(record) {
@@ -154,7 +158,11 @@ function applyTurnEnd(record) {
   turn.closed = true;
   turn.closedTs = Date.now();
   record.turnCount += 1;
-  record.lastError = void 0;
+}
+function appendErrorFact(record, message) {
+  if (!message) return;
+  (record.errors ??= []).push({ message, at: Date.now() });
+  record.lastError = message;
 }
 function applyMessageEnd(record, event) {
   if (event.usage) {
@@ -163,11 +171,11 @@ function applyMessageEnd(record, event) {
     record.totalTokens += (event.usage.input ?? 0) + (event.usage.output ?? 0) + (event.usage.cacheRead ?? 0) + (event.usage.cacheWrite ?? 0);
   }
   if (event.error) {
-    record.lastError = event.error;
+    appendErrorFact(record, event.error);
   }
 }
 function applyErrorEvent(record, event) {
-  record.lastError = event.message;
+  appendErrorFact(record, event.message);
 }
 function updateFromEvent(record, event) {
   switch (event.type) {
@@ -181,13 +189,13 @@ function updateFromEvent(record, event) {
       return applyToolStart(record, event);
     case "tool_end":
       return applyToolEnd(record, event);
-    // ── turn_end：闭合当前 turn ──
+    // ── turn_end：结束当前 turn ──
     case "turn_end":
       return applyTurnEnd(record);
     // ── message_end：usage 增量累加 + totalTokens 累加 ──
     case "message_end":
       return applyMessageEnd(record, event);
-    // ── error：存 record.lastError ──
+    // ── error：appendErrorFact 入账（errors 只追加 + lastError 派生）──
     case "error":
       return applyErrorEvent(record, event);
     // ── compaction：不产生数据（不变）──
@@ -197,10 +205,16 @@ function updateFromEvent(record, event) {
     case "activity":
       return;
     // ── armed：武装确认回执（[D3 协议版 P6]，协议语义见 contract-types）——监控
-    //    信号不进 record 投影，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
+    //    信号不进 record 派生视图，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
     //    双侧 reducer no-op 义务的 SDK 侧）
     case "armed":
       return;
+    // ── auto_retry：pi 原生重试边界帧（[subagent-observability §3.3.1 P5]）——
+    //    观测面（journal 留痕失败尝试轨迹），不进 record 派生视图：失败尝试的
+    //    turns/usage 切片与 retryAttempts 计数由引擎收尾快照一次产出（outcome
+    //    字段承载），reducer 写入会让失败尝试静默混进 turns 聚合，恰违背 P5 计账。
+    case "auto_retry":
+      return;
     default: {
       const _exhaustive = event;
       return _exhaustive;
@@ -255,8 +269,11 @@ function sessionIdFromHandle(handle) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   createReplayRecord,
+  emptyTurn,
   eventsToSessionView,
   sessionIdFromHandle,
   toReplayedTurn,

package/dist/journal-replay.d.cts

@@ -1,7 +1,18 @@
-import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-jSa1g28F.cjs';
+import { T as Turn, a as AgentUsage, b as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-C1scOS_M.cjs';
 
 /**
- * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
+ * 轮失败事实（subagent-observability §3.3.5：失败事实只追加进 errors 数组，
+ * lastError 由「最后一个非空轮失败」派生——数组只追加且空串不入账，
+ * 尾项即最后一个非空失败）。事实源记录，append-only，不因后续轮终清除。
+ */
+interface ErrorFact {
+    /** 错误消息原文（空串 / 缺席不入账——无信息失败事实不占位）。 */
+    message: string;
+    /** 事实落账墙钟（Date.now()，ms）。 */
+    at: number;
+}
+/**
+ * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这五个字段）。
  * core ExecutionRecord 满足本视图（W2 断言挂靠点）；SDK 内自持 createReplayRecord 产出。
  */
 interface ReplayRecordView {
@@ -9,19 +20,42 @@ interface ReplayRecordView {
     turnCount: number;
     totalTokens: number;
     lastError: string | undefined;
+    /**
+     * 轮失败事实只追加数组（§3.3.5）。缺省 undefined 视为空（磁盘重建的旧 record
+     * 兼容——reducer 以 `??=` 兜底初始化，不要求构造方预置）。
+     */
+    errors?: ErrorFact[];
 }
+/**
+ * 累加两个 AgentUsage（field-wise）。prev 为空时返回 next 的拷贝。
+ * 供 message_end 把 usage 增量并入 turn.usageDelta。
+ */
+declare function addUsage(prev: AgentUsage | undefined, next: AgentUsage): AgentUsage;
+/** 创建一个空 turn（text/thinking 空，无 toolCalls，未结束）。 */
+declare function emptyTurn(): Turn;
 /** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
 declare function createReplayRecord(): ReplayRecordView;
 /**
- * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ * [§3.3.5] 轮失败事实入账单点：append ErrorFact + lastError 派生刷新（唯一写点）。
+ * 空串 / 缺席不入账（无信息失败事实不占位）；`??=` 兜底磁盘重建的旧 record
+ * （无 errors 字段，缺省 undefined 视为空）。lastError = 最后追加的非空 message
+ * ——数组 append-only 且项非空，尾项即「最后一个非空轮失败」。
+ *
+ * [subagent-observability u3] 导出给 core 轮终写点（record-store-rounds 失败轮
+ * settlement）复用——u2 移交的「markRoundIdle 直写 rec.lastError 绕过 errors 数组」
+ * 收编：轮终失败事实与流内 error 事件走同一入账通道，写点单点（双写漂移防线）。
+ */
+declare function appendErrorFact(record: ReplayRecordView, message: string | undefined | null): void;
+/**
+ * 从 AgentEvent 更新 record。所有数据收敛进 record.turns[]。
  *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
  *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
  *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
- *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
- *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - turn_end：结束当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     不再清 lastError（§3.3.5——error → turn_end 序后 lastError 仍可读）
  *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
  *     totalTokens 累加
- *   - error：存 record.lastError（getEventLog 派生 error 条目用）
+ *   - error：经 appendErrorFact 入账（errors 只追加 + lastError 派生刷新）
  *
  * 唯一写点——replay 与 live 共用（重放等价性的实现体）。
  *
@@ -42,4 +76,4 @@ declare function eventsToSessionView(events: readonly AgentEvent[], engineId: st
 /** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
 declare function sessionIdFromHandle(handle: EngineHandleData): string | undefined;
 
-export { type ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };
+export { type ErrorFact, type ReplayRecordView, addUsage, aggregateUsage, appendErrorFact, createReplayRecord, emptyTurn, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };