@zhushanwen/subagent-engine-sdk 0.7.1 → 0.9.0

package/dist/index.cjs

@@ -6574,8 +6574,6 @@ var src_exports = {};
 __export(src_exports, {
   AGENT_EVENT_TYPE_NAMES: () => AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS: () => CANCEL_SETTLE_GRACE_MS,
-  CRASH_REBUILD_BACKOFF_MS: () => CRASH_REBUILD_BACKOFF_MS,
-  CRASH_REBUILD_MAX_ATTEMPTS: () => CRASH_REBUILD_MAX_ATTEMPTS,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS: () => DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS: () => DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS: () => DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -6617,6 +6615,7 @@ __export(src_exports, {
   SHARED_POOL_KEY: () => SHARED_POOL_KEY,
   STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_IDENTITY_ENV: () => SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE: () => SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV: () => TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX: () => ZCODE_HOST_DB_SUFFIX,
@@ -6704,15 +6703,6 @@ function isProtocolVersionCompatible(version) {
 var REVERSE_REQUEST_TIMEOUT_MS = 1e4;
 var HANDSHAKE_TIMEOUT_MS = 1e4;
 var CANCEL_SETTLE_GRACE_MS = 3e3;
-var CRASH_REBUILD_MAX_ATTEMPTS = 3;
-var CRASH_REBUILD_BACKOFF_STEP_1_MS = 1e3;
-var CRASH_REBUILD_BACKOFF_STEP_2_MS = 2e3;
-var CRASH_REBUILD_BACKOFF_STEP_3_MS = 4e3;
-var CRASH_REBUILD_BACKOFF_MS = [
-  CRASH_REBUILD_BACKOFF_STEP_1_MS,
-  CRASH_REBUILD_BACKOFF_STEP_2_MS,
-  CRASH_REBUILD_BACKOFF_STEP_3_MS
-];
 var STDERR_TAIL_CHARS = 400;
 
 // src/protocol/frames.ts
@@ -6988,7 +6978,7 @@ var runSessionParamsSchema = {
       properties: {
         // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
         sessionRef: { type: "object", additionalProperties: { type: "string" } },
-        journalPath: { type: "string" }
+        eventsPath: { type: "string" }
       }
     }
   }
@@ -7151,8 +7141,16 @@ var ExecutionNestingContext = class {
   }
 };
 
+// src/global-slots.ts
+var ENGINE_SDK_SLOT_KEYS = {
+  /** dataDir 缺省告警一次性标记（data-dir.ts）。 */
+  dataDirWarned: "@zhushanwen/subagent-engine-sdk.data-dir-warned",
+  /** logger sink 进程级单例（logger.ts）。 */
+  loggerSink: "@zhushanwen/subagent-engine-sdk.logger-sink"
+};
+
 // src/logger.ts
-var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+var SINK_SLOT_KEY = Symbol.for(ENGINE_SDK_SLOT_KEYS.loggerSink);
 function getSinkSlot() {
   let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
   if (!slot) {
@@ -7589,7 +7587,7 @@ function sessionIdFromHandle(handle) {
 // src/data-dir.ts
 var logger2 = getLogger("subagents");
 var TAIJI_DATA_DIR_ENV = "TAIJI_AGENT_DATA_DIR";
-var WARNED_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.data-dir-warned");
+var WARNED_SLOT_KEY = Symbol.for(ENGINE_SDK_SLOT_KEYS.dataDirWarned);
 function getWarnedSlot() {
   let slot = Reflect.get(globalThis, WARNED_SLOT_KEY);
   if (!slot) {
@@ -7863,6 +7861,34 @@ function buildOutboundChildEnv(opts) {
   return out;
 }
 
+// src/identity-env.ts
+var SUBAGENT_IDENTITY_ENV = {
+  /** 本次 run 的 record id（子进程自身身份；主/子进程判定的唯一标记）。 */
+  selfRecordId: "PI_SUBAGENT_SELF_RECORD_ID",
+  /** 真 ROOT 的 pi session id。 */
+  rootSessionId: "PI_SUBAGENT_ROOT_SESSION_ID",
+  /** 真 ROOT 的工作目录（worktree 场景下≠子进程 cwd）。 */
+  rootCwd: "PI_SUBAGENT_ROOT_CWD",
+  /** 执行嵌套深度（子进程 = 父进程 + 1）。 */
+  depth: "PI_SUBAGENT_DEPTH",
+  /** fork 链深度。 */
+  forkDepth: "PI_SUBAGENT_FORK_DEPTH",
+  /** 父 record id（嵌套时 = 父进程 selfRecordId）。 */
+  parentRecordId: "PI_SUBAGENT_PARENT_RECORD_ID",
+  /** agent 名。 */
+  agent: "PI_SUBAGENT_AGENT",
+  /** 任务文本。 */
+  task: "PI_SUBAGENT_TASK",
+  /** 执行形态（background / chat；壳读者非法值兜底 background）。 */
+  mode: "PI_SUBAGENT_MODE",
+  /** 短标签（可选）。 */
+  slug: "PI_SUBAGENT_SLUG",
+  /** 起始时刻（epoch ms；缺席回落 Date.now()）。 */
+  startedAt: "PI_SUBAGENT_STARTED_AT",
+  /** worktree 隔离标志（"true" = 是）。 */
+  worktree: "PI_SUBAGENT_WORKTREE"
+};
+
 // src/spawn.ts
 var import_node_child_process = require("child_process");
 var logger4 = getLogger("engine-sdk/spawn");
@@ -8367,8 +8393,6 @@ function runEngineCliEntry(opts) {
 0 && (module.exports = {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
-  CRASH_REBUILD_BACKOFF_MS,
-  CRASH_REBUILD_MAX_ATTEMPTS,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -8410,6 +8434,7 @@ function runEngineCliEntry(opts) {
   SHARED_POOL_KEY,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX,

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_ERROR_CODE_PREFIX, ENGINE_PROTOCOL_ERROR_CODES, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, ENGINE_TIMEOUT_RECOVERY, EngineProtocolErrorCode, EngineSdkError, ErrorResponseFrame, EventNotificationParams, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, NotificationFrame, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolError, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, RequestFrame, ResponseFrame, ReverseChannel, ReverseRequestFrame, ReverseRequestTimeoutClass, ReverseResponseResult, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, STDOUT_TAIL_ECHO_CHARS, SUPPORTED_PROTOCOL_RANGE, SuccessResponseFrame, ValidateModelParams, ValidateModelResult, assertChatConversationSupported, engineConversationUnsupportedError, engineProtocolMismatchError, engineTimeoutDetail, errorResponseFrameSchema, isEngineErrorPassthroughCode, isEngineProtocolErrorCode, isNotificationFrame, isProtocolVersionCompatible, isRequestFrame, isResponseFrame, isReverseRequestFrame, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, schemaEmulationFailedDetail, successResponseFrameSchema } from './protocol/index.cjs';
-export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, k as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, l as ResumeAnchor, S as SessionView, T as ToolCall, m as ToolCallEntry, n as ToolCallResult, o as Turn, W as WorktreeHandle } from './contract-types-DiWyGRXr.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, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.cjs';
+export { C as CancelParams, b as CancelResult, D as DisposeParams, c as DisposeResult, d as ENGINE_ERROR_CODE_PREFIX, e as ENGINE_PROTOCOL_ERROR_CODES, f as ENGINE_TIMEOUT_RECOVERY, g as EngineProtocolErrorCode, E as EngineSdkError, h as ErrorResponseFrame, i as EventNotificationParams, a as InitializeParams, I as InitializeResult, L as ListModelsParams, j as ListModelsResult, N as NotificationFrame, P as PROTOCOL_METHODS, k as PingParams, l as PingResult, m as ProbeParams, n as ProtocolError, o as ProtocolMethod, p as ProtocolParamsMap, q as ProtocolResultMap, r as ReadParams, s as RequestFrame, t as ResponseFrame, u as ReverseRequestFrame, v as ReverseResponseResult, R as RunContextParams, w as RunParams, x as RunResult, y as RunResumeParams, S as STDOUT_TAIL_ECHO_CHARS, z as SuccessResponseFrame, V as ValidateModelParams, A as ValidateModelResult, B as assertChatConversationSupported, F as engineConversationUnsupportedError, G as engineProtocolMismatchError, H as engineTimeoutDetail, J as isEngineErrorPassthroughCode, K as isEngineProtocolErrorCode, M as isNotificationFrame, O as isRequestFrame, Q as isResponseFrame, T as isReverseRequestFrame, U as schemaEmulationFailedDetail } from './error-codes-C3oVToMr.cjs';
+export { f as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, g as AgentEventTypeName, h as AgentFailureKind, c as AgentOutcome, i as AgentOutcomeUsage, j as AgentUsage, a as AgentUsageTotal, k as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, l as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, m as ToolCall, n as ToolCallEntry, o as ToolCallResult, T as Turn, W as WorktreeHandle } from './contract-types-DqOD58r-.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';
@@ -22,6 +23,33 @@ export { EngineAgentCallOpts, EngineCtxModel, EngineHandle, EnginePort, EngineRu
 export { CliProtocolServerSink, RunEngineCliEntryOptions, runEngineCliEntry } from './cli-entry.cjs';
 import 'node:child_process';
 
+declare const SUBAGENT_IDENTITY_ENV: {
+    /** 本次 run 的 record id（子进程自身身份；主/子进程判定的唯一标记）。 */
+    readonly selfRecordId: "PI_SUBAGENT_SELF_RECORD_ID";
+    /** 真 ROOT 的 pi session id。 */
+    readonly rootSessionId: "PI_SUBAGENT_ROOT_SESSION_ID";
+    /** 真 ROOT 的工作目录（worktree 场景下≠子进程 cwd）。 */
+    readonly rootCwd: "PI_SUBAGENT_ROOT_CWD";
+    /** 执行嵌套深度（子进程 = 父进程 + 1）。 */
+    readonly depth: "PI_SUBAGENT_DEPTH";
+    /** fork 链深度。 */
+    readonly forkDepth: "PI_SUBAGENT_FORK_DEPTH";
+    /** 父 record id（嵌套时 = 父进程 selfRecordId）。 */
+    readonly parentRecordId: "PI_SUBAGENT_PARENT_RECORD_ID";
+    /** agent 名。 */
+    readonly agent: "PI_SUBAGENT_AGENT";
+    /** 任务文本。 */
+    readonly task: "PI_SUBAGENT_TASK";
+    /** 执行形态（background / chat；壳读者非法值兜底 background）。 */
+    readonly mode: "PI_SUBAGENT_MODE";
+    /** 短标签（可选）。 */
+    readonly slug: "PI_SUBAGENT_SLUG";
+    /** 起始时刻（epoch ms；缺席回落 Date.now()）。 */
+    readonly startedAt: "PI_SUBAGENT_STARTED_AT";
+    /** worktree 隔离标志（"true" = 是）。 */
+    readonly worktree: "PI_SUBAGENT_WORKTREE";
+};
+
 /** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
 declare const RELAY_FRAME_KINDS: {
     readonly handshake: "handshake";
@@ -55,4 +83,4 @@ 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];
 
-export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason };
+export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason, SUBAGENT_IDENTITY_ENV };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_ERROR_CODE_PREFIX, ENGINE_PROTOCOL_ERROR_CODES, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, ENGINE_TIMEOUT_RECOVERY, EngineProtocolErrorCode, EngineSdkError, ErrorResponseFrame, EventNotificationParams, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, NotificationFrame, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolError, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, RequestFrame, ResponseFrame, ReverseChannel, ReverseRequestFrame, ReverseRequestTimeoutClass, ReverseResponseResult, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, STDOUT_TAIL_ECHO_CHARS, SUPPORTED_PROTOCOL_RANGE, SuccessResponseFrame, ValidateModelParams, ValidateModelResult, assertChatConversationSupported, engineConversationUnsupportedError, engineProtocolMismatchError, engineTimeoutDetail, errorResponseFrameSchema, isEngineErrorPassthroughCode, isEngineProtocolErrorCode, isNotificationFrame, isProtocolVersionCompatible, isRequestFrame, isResponseFrame, isReverseRequestFrame, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, schemaEmulationFailedDetail, successResponseFrameSchema } from './protocol/index.js';
-export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, k as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, l as ResumeAnchor, S as SessionView, T as ToolCall, m as ToolCallEntry, n as ToolCallResult, o as Turn, W as WorktreeHandle } from './contract-types-DiWyGRXr.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, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.js';
+export { C as CancelParams, b as CancelResult, D as DisposeParams, c as DisposeResult, d as ENGINE_ERROR_CODE_PREFIX, e as ENGINE_PROTOCOL_ERROR_CODES, f as ENGINE_TIMEOUT_RECOVERY, g as EngineProtocolErrorCode, E as EngineSdkError, h as ErrorResponseFrame, i as EventNotificationParams, a as InitializeParams, I as InitializeResult, L as ListModelsParams, j as ListModelsResult, N as NotificationFrame, P as PROTOCOL_METHODS, k as PingParams, l as PingResult, m as ProbeParams, n as ProtocolError, o as ProtocolMethod, p as ProtocolParamsMap, q as ProtocolResultMap, r as ReadParams, s as RequestFrame, t as ResponseFrame, u as ReverseRequestFrame, v as ReverseResponseResult, R as RunContextParams, w as RunParams, x as RunResult, y as RunResumeParams, S as STDOUT_TAIL_ECHO_CHARS, z as SuccessResponseFrame, V as ValidateModelParams, A as ValidateModelResult, B as assertChatConversationSupported, F as engineConversationUnsupportedError, G as engineProtocolMismatchError, H as engineTimeoutDetail, J as isEngineErrorPassthroughCode, K as isEngineProtocolErrorCode, M as isNotificationFrame, O as isRequestFrame, Q as isResponseFrame, T as isReverseRequestFrame, U as schemaEmulationFailedDetail } from './error-codes-CiDwaODz.js';
+export { f as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, g as AgentEventTypeName, h as AgentFailureKind, c as AgentOutcome, i as AgentOutcomeUsage, j as AgentUsage, a as AgentUsageTotal, k as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, l as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, m as ToolCall, n as ToolCallEntry, o as ToolCallResult, T as Turn, W as WorktreeHandle } from './contract-types-DqOD58r-.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';
@@ -22,6 +23,33 @@ export { EngineAgentCallOpts, EngineCtxModel, EngineHandle, EnginePort, EngineRu
 export { CliProtocolServerSink, RunEngineCliEntryOptions, runEngineCliEntry } from './cli-entry.js';
 import 'node:child_process';
 
+declare const SUBAGENT_IDENTITY_ENV: {
+    /** 本次 run 的 record id（子进程自身身份；主/子进程判定的唯一标记）。 */
+    readonly selfRecordId: "PI_SUBAGENT_SELF_RECORD_ID";
+    /** 真 ROOT 的 pi session id。 */
+    readonly rootSessionId: "PI_SUBAGENT_ROOT_SESSION_ID";
+    /** 真 ROOT 的工作目录（worktree 场景下≠子进程 cwd）。 */
+    readonly rootCwd: "PI_SUBAGENT_ROOT_CWD";
+    /** 执行嵌套深度（子进程 = 父进程 + 1）。 */
+    readonly depth: "PI_SUBAGENT_DEPTH";
+    /** fork 链深度。 */
+    readonly forkDepth: "PI_SUBAGENT_FORK_DEPTH";
+    /** 父 record id（嵌套时 = 父进程 selfRecordId）。 */
+    readonly parentRecordId: "PI_SUBAGENT_PARENT_RECORD_ID";
+    /** agent 名。 */
+    readonly agent: "PI_SUBAGENT_AGENT";
+    /** 任务文本。 */
+    readonly task: "PI_SUBAGENT_TASK";
+    /** 执行形态（background / chat；壳读者非法值兜底 background）。 */
+    readonly mode: "PI_SUBAGENT_MODE";
+    /** 短标签（可选）。 */
+    readonly slug: "PI_SUBAGENT_SLUG";
+    /** 起始时刻（epoch ms；缺席回落 Date.now()）。 */
+    readonly startedAt: "PI_SUBAGENT_STARTED_AT";
+    /** worktree 隔离标志（"true" = 是）。 */
+    readonly worktree: "PI_SUBAGENT_WORKTREE";
+};
+
 /** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
 declare const RELAY_FRAME_KINDS: {
     readonly handshake: "handshake";
@@ -55,4 +83,4 @@ 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];
 
-export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason };
+export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason, SUBAGENT_IDENTITY_ENV };

package/dist/index.js

@@ -1,6 +1,17 @@
+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-EJMF63R5.js";
+} from "./chunk-QMEHSKNR.js";
 import {
   replayJournal
 } from "./chunk-RDH3ZOV6.js";
@@ -10,11 +21,16 @@ import {
 } from "./chunk-LQR73V67.js";
 import {
   runEngineCliEntry
-} from "./chunk-J4G2MXDS.js";
+} from "./chunk-VE3NVT7K.js";
 import {
   ZCODE_HOST_DB_SUFFIX,
   ZCODE_ISOLATED_DB_SEGMENTS
 } from "./chunk-CT3FEBDO.js";
+import {
+  TAIJI_DATA_DIR_ENV,
+  resetDataDirWarnForTests,
+  resolveEngineDataDir
+} from "./chunk-3FVBDH3X.js";
 import {
   resolveEngineDir,
   resolveEnginesRoot,
@@ -35,7 +51,7 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-YL5W5EMV.js";
+} from "./chunk-AF2ETADP.js";
 import {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   ENGINE_ABORT_KILL_GRACE_MS,
@@ -43,14 +59,14 @@ import {
   armEngineSelfDestruct,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-HERD6RIR.js";
+} from "./chunk-6QE3OODO.js";
 import {
   ENGINE_NODE_ENV,
   hostKindOf,
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-3WC36CHI.js";
+} from "./chunk-KADRNFG2.js";
 import {
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
@@ -62,17 +78,6 @@ import {
   stderrLogPidOf,
   stderrRotationParams
 } from "./chunk-MSAJXIP4.js";
-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 {
   AGENT_EVENT_TYPE_NAMES,
   ENGINE_PROTOCOL_SCHEMAS,
@@ -81,17 +86,19 @@ import {
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   errorResponseFrameSchema,
-  isNotificationFrame,
-  isRequestFrame,
-  isResponseFrame,
-  isReverseRequestFrame,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "./chunk-W23PAAGX.js";
+} from "./chunk-DIIYVO4O.js";
+import {
+  isNotificationFrame,
+  isRequestFrame,
+  isResponseFrame,
+  isReverseRequestFrame
+} from "./chunk-D36ZIQQK.js";
 import {
   SCHEMA_EMULATION_TAIL_CHARS,
   buildSchemaEmulationSegment,
@@ -114,14 +121,12 @@ import {
   probePidAlive,
   safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-RCT7L777.js";
+} from "./chunk-EF2F5YOM.js";
 import {
   toErrorMessage
 } from "./chunk-PYO3YR7W.js";
 import {
   CANCEL_SETTLE_GRACE_MS,
-  CRASH_REBUILD_BACKOFF_MS,
-  CRASH_REBUILD_MAX_ATTEMPTS,
   ENGINE_ERROR_CODE_PREFIX,
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_VERSION,
@@ -140,7 +145,12 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "./chunk-SFNTX7Q3.js";
+} from "./chunk-VDKR7MLG.js";
+import {
+  configureLoggerSink,
+  getLogger,
+  resetLoggerSinkForTests
+} from "./chunk-NXNNXGTY.js";
 import {
   aggregateUsage,
   createReplayRecord,
@@ -149,18 +159,36 @@ import {
   toReplayedTurn,
   updateFromEvent
 } from "./chunk-SGAIDL63.js";
-import {
-  TAIJI_DATA_DIR_ENV,
-  resetDataDirWarnForTests,
-  resolveEngineDataDir
-} from "./chunk-X24IVQKJ.js";
-import {
-  configureLoggerSink,
-  getLogger,
-  resetLoggerSinkForTests
-} from "./chunk-75QEMUGV.js";
 import "./chunk-JSBRDJBE.js";
 
+// src/identity-env.ts
+var SUBAGENT_IDENTITY_ENV = {
+  /** 本次 run 的 record id（子进程自身身份；主/子进程判定的唯一标记）。 */
+  selfRecordId: "PI_SUBAGENT_SELF_RECORD_ID",
+  /** 真 ROOT 的 pi session id。 */
+  rootSessionId: "PI_SUBAGENT_ROOT_SESSION_ID",
+  /** 真 ROOT 的工作目录（worktree 场景下≠子进程 cwd）。 */
+  rootCwd: "PI_SUBAGENT_ROOT_CWD",
+  /** 执行嵌套深度（子进程 = 父进程 + 1）。 */
+  depth: "PI_SUBAGENT_DEPTH",
+  /** fork 链深度。 */
+  forkDepth: "PI_SUBAGENT_FORK_DEPTH",
+  /** 父 record id（嵌套时 = 父进程 selfRecordId）。 */
+  parentRecordId: "PI_SUBAGENT_PARENT_RECORD_ID",
+  /** agent 名。 */
+  agent: "PI_SUBAGENT_AGENT",
+  /** 任务文本。 */
+  task: "PI_SUBAGENT_TASK",
+  /** 执行形态（background / chat；壳读者非法值兜底 background）。 */
+  mode: "PI_SUBAGENT_MODE",
+  /** 短标签（可选）。 */
+  slug: "PI_SUBAGENT_SLUG",
+  /** 起始时刻（epoch ms；缺席回落 Date.now()）。 */
+  startedAt: "PI_SUBAGENT_STARTED_AT",
+  /** worktree 隔离标志（"true" = 是）。 */
+  worktree: "PI_SUBAGENT_WORKTREE"
+};
+
 // src/relay-frames.ts
 var RELAY_FRAME_KINDS = {
   handshake: "handshake",
@@ -191,8 +219,6 @@ var RELAY_REJECT_REASONS = {
 export {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
-  CRASH_REBUILD_BACKOFF_MS,
-  CRASH_REBUILD_MAX_ATTEMPTS,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -234,6 +260,7 @@ export {
   SHARED_POOL_KEY,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV,
   ZCODE_HOST_DB_SUFFIX,

package/dist/journal-io.d.cts

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

package/dist/journal-io.d.ts

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

package/dist/journal-replay.d.cts

@@ -1,4 +1,4 @@
-import { o as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DiWyGRXr.cjs';
+import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-DqOD58r-.cjs';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。

package/dist/journal-replay.d.ts

@@ -1,4 +1,4 @@
-import { o as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DiWyGRXr.js';
+import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-DqOD58r-.js';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。

package/dist/kill-chain.cjs

@@ -32,8 +32,16 @@ __export(kill_chain_exports, {
 });
 module.exports = __toCommonJS(kill_chain_exports);
 
+// src/global-slots.ts
+var ENGINE_SDK_SLOT_KEYS = {
+  /** dataDir 缺省告警一次性标记（data-dir.ts）。 */
+  dataDirWarned: "@zhushanwen/subagent-engine-sdk.data-dir-warned",
+  /** logger sink 进程级单例（logger.ts）。 */
+  loggerSink: "@zhushanwen/subagent-engine-sdk.logger-sink"
+};
+
 // src/logger.ts
-var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+var SINK_SLOT_KEY = Symbol.for(ENGINE_SDK_SLOT_KEYS.loggerSink);
 function getSinkSlot() {
   let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
   if (!slot) {

package/dist/kill-chain.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DiWyGRXr.cjs';
+import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-DqOD58r-.cjs';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。

package/dist/kill-chain.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DiWyGRXr.js';
+import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-DqOD58r-.js';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。

package/dist/kill-chain.js

@@ -8,10 +8,10 @@ import {
   probePidAlive,
   safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-RCT7L777.js";
+} from "./chunk-EF2F5YOM.js";
 import "./chunk-PYO3YR7W.js";
-import "./chunk-SFNTX7Q3.js";
-import "./chunk-75QEMUGV.js";
+import "./chunk-VDKR7MLG.js";
+import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {
   DEFAULT_KILL_GRACE_MS,

package/dist/logger.cjs

@@ -25,7 +25,17 @@ __export(logger_exports, {
   resetLoggerSinkForTests: () => resetLoggerSinkForTests
 });
 module.exports = __toCommonJS(logger_exports);
-var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+
+// src/global-slots.ts
+var ENGINE_SDK_SLOT_KEYS = {
+  /** dataDir 缺省告警一次性标记（data-dir.ts）。 */
+  dataDirWarned: "@zhushanwen/subagent-engine-sdk.data-dir-warned",
+  /** logger sink 进程级单例（logger.ts）。 */
+  loggerSink: "@zhushanwen/subagent-engine-sdk.logger-sink"
+};
+
+// src/logger.ts
+var SINK_SLOT_KEY = Symbol.for(ENGINE_SDK_SLOT_KEYS.loggerSink);
 function getSinkSlot() {
   let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
   if (!slot) {

package/dist/logger.js

@@ -2,7 +2,7 @@ import {
   configureLoggerSink,
   getLogger,
   resetLoggerSinkForTests
-} from "./chunk-75QEMUGV.js";
+} from "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {
   configureLoggerSink,

package/dist/node-executor.js

@@ -4,8 +4,8 @@ import {
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-3WC36CHI.js";
-import "./chunk-SFNTX7Q3.js";
+} from "./chunk-KADRNFG2.js";
+import "./chunk-VDKR7MLG.js";
 import "./chunk-JSBRDJBE.js";
 export {
   ENGINE_NODE_ENV,

package/dist/port-contract.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, l as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DiWyGRXr.cjs';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.cjs';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -31,7 +31,7 @@ interface EngineStream {
  * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
  * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
  * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
- * 三类消费：① journal 落盘路径构造（core journal-wiring）；② 存量 record 兼容
+ * 三类消费：① journal 落盘路径构造（core event-journal-wiring）；② 存量 record 兼容
  * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
  * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
  * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
@@ -44,10 +44,6 @@ interface RunContext {
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
     stream?: EngineStream;
-    engineFallback?: {
-        from: string;
-        reason: string;
-    };
     /**
      * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
      * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
@@ -67,6 +63,16 @@ interface RunContext {
      * 恒无扩展 flag）。additive 可选：宿主缺省不传。
      */
     extensionPaths?: string[];
+    /**
+     * [D4 record 身份信封] 协议 `run.params.ctx.identity` 的进程内还原——引擎把它整封
+     * 写进任务子进程的身份 env（`SUBAGENT_IDENTITY_ENV` 的 slug / startedAt / mode）。
+     * additive 可选：宿主缺省不传时引擎不写这三个键，读者按回落语义工作。
+     */
+    identity?: {
+        slug?: string;
+        startedAt?: number;
+        mode?: string;
+    };
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {

package/dist/port-contract.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, l as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DiWyGRXr.js';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-DqOD58r-.js';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
@@ -31,7 +31,7 @@ interface EngineStream {
  * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
  * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
  * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
- * 三类消费：① journal 落盘路径构造（core journal-wiring）；② 存量 record 兼容
+ * 三类消费：① journal 落盘路径构造（core event-journal-wiring）；② 存量 record 兼容
  * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
  * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
  * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
@@ -44,10 +44,6 @@ interface RunContext {
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
     stream?: EngineStream;
-    engineFallback?: {
-        from: string;
-        reason: string;
-    };
     /**
      * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
      * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
@@ -67,6 +63,16 @@ interface RunContext {
      * 恒无扩展 flag）。additive 可选：宿主缺省不传。
      */
     extensionPaths?: string[];
+    /**
+     * [D4 record 身份信封] 协议 `run.params.ctx.identity` 的进程内还原——引擎把它整封
+     * 写进任务子进程的身份 env（`SUBAGENT_IDENTITY_ENV` 的 slug / startedAt / mode）。
+     * additive 可选：宿主缺省不传时引擎不写这三个键，读者按回落语义工作。
+     */
+    identity?: {
+        slug?: string;
+        startedAt?: number;
+        mode?: string;
+    };
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {