niceeval 0.11.4-canary.20 → 0.12.0

package/dist/report/slices/content.js

@@ -1,6 +1,46 @@
 // 指标视图 TableContent 投影:compute *Data → Table 原语可直接消费的形状。
-import { localizedMessage } from "../model/locale.js";
-export function deltaTableContent(data) {
+import { DEFAULT_REPORT_LOCALE, localizedMessage } from "../model/locale.js";
+import { formatMetricValue, formatPlainNumber, formatPoints, formatTimeDistance, verdictMark } from "../model/format.js";
+/**
+ * 带符号的美元/tokens 差值:复用 `formatMetricValue` 折终值(内建 unit 格式不分 locale,
+ * presentation.md「unit 决定格式」),只在外面补一个恒定的正负号——负值 `formatMetricValue`
+ * 已经自带 "-",这里只需要给非负值补 "+"。
+ */
+function signedMetricText(value, unit) {
+    const sign = value > 0 ? "+" : "";
+    return `${sign}${formatMetricValue(value, unit)}`;
+}
+/** 带符号的挣分差值("+4 pts" / "-4 pts");`formatPointsSuffix` 恒加 "+" 号,不适用于可能为负的差值。 */
+function signedPointsText(value) {
+    const sign = value > 0 ? "+" : value < 0 ? "-" : "";
+    const abs = Math.abs(value);
+    return `${sign}${formatPlainNumber(abs)} ${abs === 1 ? "pt" : "pts"}`;
+}
+/**
+ * 一格的判定读法(docs/feature/reports/show/compare.md):有数据时通过制只留判定符(`bare`,
+ * 历史执行再接相对时距)、计分制显示挣分;该条件缺席这道题时,记录里有过期结论参考才给
+ * `— <判定符> <时距>`(`—` 不被参考替换,它标记「这一格没有可聚合的结果」,参考只是附注),
+ * 没有参考就是纯 `notApplicable`。参考不进任何计数——它压根不出现在 `cells` 里,只在这一格
+ * 的显示上多一句附注。
+ */
+function conditionVerdictCell(cell, reference, locale) {
+    if (!cell) {
+        if (!reference)
+            return { kind: "notApplicable" };
+        const mark = verdictMark(reference.verdict === "skipped" ? "skipped" : reference.verdict);
+        return { kind: "text", text: `— ${mark} ${formatTimeDistance(reference.staleSinceMs, locale)}` };
+    }
+    if (cell.evaluationKind === "points") {
+        return { kind: "text", text: cell.totalScore !== undefined ? formatPoints(cell.totalScore) : "—" };
+    }
+    return {
+        kind: "verdict",
+        verdict: cell.verdict,
+        bare: true,
+        ...(cell.historical && cell.staleSinceMs !== undefined ? { staleSinceMs: cell.staleSinceMs } : {}),
+    };
+}
+export function deltaTableContent(data, locale = DEFAULT_REPORT_LOCALE) {
     const conditionColumns = data.conditions.flatMap((condition) => [
         { key: `${condition}:verdict` },
         { key: `${condition}:tokens` },
@@ -20,31 +60,24 @@ export function deltaTableContent(data) {
             };
             for (const condition of data.conditions) {
                 const cell = row.cells[condition];
-                cells[`${condition}:verdict`] = cell
-                    ? cell.evaluationKind === "points"
-                        ? {
-                            kind: "text",
-                            text: cell.totalScore !== undefined ? String(cell.totalScore) : "—",
-                        }
-                        : { kind: "verdict", verdict: cell.verdict }
-                    : { kind: "notApplicable" };
+                cells[`${condition}:verdict`] = conditionVerdictCell(cell, row.references?.[condition], locale);
                 cells[`${condition}:tokens`] =
                     cell?.totalTokens !== undefined
-                        ? { kind: "text", text: String(cell.totalTokens) }
+                        ? { kind: "metric", metric: { value: cell.totalTokens, unit: "tokens", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
                         : { kind: "notApplicable" };
                 cells[`${condition}:cost`] =
                     cell?.totalCostUSD !== undefined
-                        ? { kind: "text", text: String(cell.totalCostUSD) }
+                        ? { kind: "metric", metric: { value: cell.totalCostUSD, unit: "$", basis: "eval", samples: 1, total: 1, refs: cell.attempts } }
                         : { kind: "notApplicable" };
             }
             for (const condition of data.conditions.slice(1)) {
                 const delta = row.delta?.[condition];
                 cells[`${condition}:Δscore`] =
-                    delta?.score !== undefined ? { kind: "text", text: String(delta.score) } : { kind: "notApplicable" };
+                    delta?.score !== undefined ? { kind: "text", text: signedPointsText(delta.score) } : { kind: "notApplicable" };
                 cells[`${condition}:Δtokens`] =
-                    delta?.tokens !== undefined ? { kind: "text", text: String(delta.tokens) } : { kind: "notApplicable" };
+                    delta?.tokens !== undefined ? { kind: "text", text: signedMetricText(delta.tokens, "tokens") } : { kind: "notApplicable" };
                 cells[`${condition}:Δcost`] =
-                    delta?.costUSD !== undefined ? { kind: "text", text: String(delta.costUSD) } : { kind: "notApplicable" };
+                    delta?.costUSD !== undefined ? { kind: "text", text: signedMetricText(delta.costUSD, "$") } : { kind: "notApplicable" };
             }
             return { key: row.key, cells };
         }),

package/dist/report/slices/validate.js

@@ -129,6 +129,20 @@ function deltaCellProblem(value, path) {
         return `"${path}.totalCostUSD" must be a number`;
     if (typeof value.historical !== "boolean")
         return `"${path}.historical" must be a boolean`;
+    if (value.staleSinceMs !== undefined && typeof value.staleSinceMs !== "number")
+        return `"${path}.staleSinceMs" must be a number`;
+    return null;
+}
+/** 缺席格的过期结论参考(与 experiment-table 占位行同一份 StaleConclusionReference 形状)。 */
+function staleReferenceProblem(value, path) {
+    if (!isObject(value))
+        return `"${path}" must be an object { locator, verdict, staleSinceMs }`;
+    if (typeof value.locator !== "string")
+        return `"${path}.locator" must be a string`;
+    if (typeof value.verdict !== "string")
+        return `"${path}.verdict" must be a string`;
+    if (typeof value.staleSinceMs !== "number")
+        return `"${path}.staleSinceMs" must be a number`;
     return null;
 }
 function deltaTotalsProblem(value, path) {
@@ -206,6 +220,15 @@ export const validateDeltaData = (data) => {
                     return `"${path}.delta.${condition}.costUSD" must be a number`;
             }
         }
+        if (row.references !== undefined) {
+            if (!isObject(row.references))
+                return `"${path}.references" must be an object`;
+            for (const [condition, reference] of Object.entries(row.references)) {
+                const problem = staleReferenceProblem(reference, `${path}.references.${condition}`);
+                if (problem !== null)
+                    return problem;
+            }
+        }
         return null;
     });
     if (rowsProblem !== null)

package/dist/report/tasks.d.ts

@@ -6,7 +6,7 @@ import type { AttemptIdentity } from "../record/locator.ts";
 import { type SourceContent } from "../record/annotated-source.ts";
 import type { EvalResult, CommandExitEvidence, PhaseTiming, SandboxBuildRecord, TimingActivity, TraceSpan } from "../types.ts";
 import { type EvidenceRow, type MetricValue } from "./model/calculation.ts";
-import type { AttemptAssertionsData, AttemptConversationData, AttemptDiagnosticsData, AttemptDiffData, AttemptErrorData, AttemptFixPromptData, AttemptSummaryData, AttemptTraceData, DeltaData, ExperimentListItem, HeroData, SampleSummaryContent, StabilityMatrixData, UsageTableData } from "./model/types.ts";
+import type { AttemptAssertionsData, AttemptConversationData, AttemptDiagnosticsData, AttemptDiffData, AttemptErrorData, AttemptFactsData, AttemptFixPromptData, AttemptSummaryData, AttemptTraceData, DeltaData, ExperimentListItem, HeroData, SampleSummaryContent, StabilityMatrixData, UsageTableData } from "./model/types.ts";
 import type { CalloutGroup } from "./definition/primitives/callouts-logic.ts";
 import type { CopyBlockContent } from "./definition/primitives/copy-block.tsx";
 import { type DeltaTableOptions, type StabilityMatrixOptions } from "./slices/compute.ts";
@@ -32,6 +32,11 @@ export interface StandardOverviewResult {
     summary: SampleSummaryContent;
     charts: readonly StandardOverviewChartResult[];
     experiments: readonly ExperimentListItem[];
+    /**
+     * 「只看新执行」开关的另一态(experiment-table.md「只看新执行」);Sample 里既无历史执行
+     * 也无过期结论时为 null——一个永远不改变行集的控件只会让人怀疑自己看漏了什么。
+     */
+    freshExperiments: readonly ExperimentListItem[] | null;
 }
 export interface ComparisonCoverageResult {
     common: number;
@@ -122,6 +127,7 @@ export interface AttemptDetailsResult {
     conversation: ConversationResult;
     diagnostics: AttemptDiagnosticsData | null;
     usage: UsageResult;
+    facts: AttemptFactsData | null;
     trace: AttemptTraceData | null;
     diff: DiffResult;
 }

package/dist/report/tasks.js

@@ -7,8 +7,8 @@ import { compactAssertionSummary, primaryAssertionSummary, summaryText } from ".
 import { firstLine } from "../util.js";
 import { aggregate, agent, costUSD, experiment, passRate, totalScore, } from "./model/calculation.js";
 import { attemptCostUSD } from "./model/metrics.js";
-import { attemptAssertionsData, attemptConversationData, attemptDiagnosticsData, attemptDiffData, attemptErrorData, attemptFixPromptData, attemptSummaryData, attemptTraceData, usageTableData, } from "./components/attempt-detail/compute.js";
-import { experimentListData } from "./components/entity-lists/compute.js";
+import { attemptAssertionsData, attemptConversationData, attemptDiagnosticsData, attemptDiffData, attemptErrorData, attemptFactsData, attemptFixPromptData, attemptSummaryData, attemptTraceData, usageTableData, } from "./components/attempt-detail/compute.js";
+import { experimentListData, hasHistoricalOrStale } from "./components/entity-lists/compute.js";
 import { sampleSummary } from "./components/summaries/compute.js";
 import { evaluationKindComposition } from "./model/evaluation-kind.js";
 import { heroData, } from "./components/site-components/compute.js";
@@ -115,7 +115,8 @@ export async function standardOverviewResult(sample) {
         experimentListData(sample),
         Promise.all(chartPromises),
     ]);
-    return { hero, notices, diagnostics, fixPrompt, summary, charts, experiments };
+    const freshExperiments = hasHistoricalOrStale(experiments) ? await experimentListData(sample.freshOnly()) : null;
+    return { hero, notices, diagnostics, fixPrompt, summary, charts, experiments, freshExperiments };
 }
 export async function comparisonResult(sample, options) {
     const data = await deltaTableData(sample, options);
@@ -305,6 +306,7 @@ export async function attemptDetailsResult(attempt) {
         conversation,
         diagnostics: attemptDiagnosticsData(attempt),
         usage,
+        facts: attemptFactsData(attempt),
         trace: attemptTraceData(attempt),
         diff,
     };

package/dist/runner/types.d.ts

@@ -1,6 +1,6 @@
 import type { JsonValue, LocalizedText, ScopedFeedback, SourceArtifact, Verdict } from "../shared/types.ts";
 import type { AttemptFailureClassifier } from "../shared/failure-class.ts";
-import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan, Truncation, Usage } from "../o11y/types.ts";
 import type { Agent, AgentSetupManifest } from "../agents/types.ts";
 import type { SandboxLayer } from "../sandbox/layer.ts";
 import type { LinkedRunPlan } from "../sandbox/plan.ts";
@@ -161,10 +161,10 @@ export interface PhaseTiming {
 }
 /**
  * `commands.json` 的一条落盘记录(见 docs/feature/record/architecture.md「commandsjson」):
- * 四个公开 `Sandbox.run*()` 方法的最外层调用返回非零 `exitCode` 时,Runner 在
- * `CommandResult` 交还调用方**之前**登记的完整证据——Eval 后续即使只把 `.slice(-N)` 拼进
- * 异常消息,这份证据仍然完整。只记非零退出;成功命令的输出不进第二份 artifact,provider 内部
- * 实现步骤与 Agent 自己调用的 shell 不经过这层包装,不伪装成这里的命令。
+ * 四个公开 `Sandbox.run*()` 方法的最外层调用返回时,Runner 在 `CommandResult` 交还调用方
+ * **之前**登记的完整证据——Eval 后续即使只把 `.slice(-N)` 拼进异常消息,这份证据仍然完整。
+ * 成功与非零退出都记录;provider 内部实现步骤与 Agent 自己调用的 shell 不经过这层包装,
+ * 不伪装成这里的命令。
  */
 export interface CommandExitEvidence {
     /** 与 `PhaseTiming.children` 中 `key === "sandbox.command"` 的 `TimingActivity.id` 相同,唯一关联命令证据卡与 `--timing` 的 command 节点。 */
@@ -176,10 +176,14 @@ export interface CommandExitEvidence {
     exitCode: number;
     /** 是否由 checked run*OrThrow 公开调用产生;非零 + checked 才是失败展示语义。 */
     checked: boolean;
-    /** 不截断落盘；`CommandOptions.sensitiveValues` 命中的已知值已替换为 `<redacted>`。 */
+    /** `CommandOptions.sensitiveValues` 命中的已知值已替换为 `<redacted>`;超过每流 64 KiB 时
+     *  在落盘序列化时截断,见 `truncated`。 */
     stdout: string;
-    /** 不截断落盘，同 `stdout` 的已知敏感值边界。 */
+    /** 同 `stdout` 的已知敏感值边界与截断规则。 */
     stderr: string;
+    /** `stdout` / `stderr` 超过每流上限时的结构化截断标记(`path` 为 `"stdout"` 或 `"stderr"`);
+     *  只由 writer 在落盘时刻写入,运行时与调用方拿到的仍是完整值。 */
+    truncated?: Truncation[];
 }
 /** `commands.json` 的落盘形状。 */
 export type CommandsArtifact = CommandExitEvidence[];
@@ -252,7 +256,7 @@ export interface DiagnosticRecord {
 }
 /**
  * `--accept` 跨过的一条具名差异(`EvalResult.carriedAccepting` 的成员)。
- * `selector` 与 CLI 上写下的那个字面量同一个词表,`from` / `to` 是有界值摘要;
+ * `selector` 与 CLI 上写下的那个字面量同一个词表,`from` / `to` 是完整值的字符串投影;
  * 某一侧没有这个键(新增 / 删除)时该侧省略。
  */
 export interface CarriedAcceptance {
@@ -281,7 +285,7 @@ export interface AcceptedResult {
     fingerprint: string;
     /** 当前项目按本次配置重算出的指纹。 */
     acceptedFingerprint: string;
-    /** 新旧 manifest/config 的有界差异摘要。 */
+    /** 新旧 manifest/config 的完整差异清单。 */
     differences: AcceptedDifference[];
 }
 /** 自动重试吸收的一次物理 send 失败；不进入逻辑会话事件流。 */
@@ -397,7 +401,7 @@ export interface EvalResult {
     };
     /** agent 归因增量:逐 send 窗口的 delta 序列(落盘为 diff.json;文件级视图由读取面派生)。 */
     diff?: DiffArtifact;
-    /** 非零 Sandbox 命令的 stdout/stderr 证据(落盘为 commands.json);只记非零退出,见 `CommandExitEvidence`。 */
+    /** Sandbox 命令的 stdout/stderr 证据(落盘为 commands.json);成功与非零退出都记录,见 `CommandExitEvidence`。 */
     commands?: CommandExitEvidence[];
     rawTranscript?: string;
     /** 携带条目(--resume 合入)专用:artifact 目录(相对结果根目录),指向原快照里的落盘。 */
@@ -501,6 +505,15 @@ export interface InvocationShape {
      * 省略只出现在没有携带规划的直调场景。
      */
     manifests?: ReadonlyMap<string, RunManifests>;
+    /**
+     * 本次规划期按 experimentId 算好的 Run 级配置身份(见
+     * `config-identity.ts` 的 `configIdentityForRun` / `hashConfigHash`)。同一 experiment 内
+     * 全部 eval 共享一个值(configHash 只依赖 run 与 Experiment 作者 layer,不依赖逐 eval 的
+     * 物理 provider plan);落盘面据此在建 Run 目录时把它写进 `run.json.configHash`,不再只有
+     * `niceeval accept` 显式声明。与 `manifests` 同一条路径:runner 显式递给 reporter,
+     * 不由落盘面自己猜。省略只出现在没有携带规划的直调场景。
+     */
+    configHashes?: ReadonlyMap<string, string>;
 }
 export interface Reporter {
     onEvent?(event: ReporterEvent): void | Promise<void>;
@@ -1255,8 +1268,14 @@ export interface FailureDetail {
     assertion?: PrimaryAssertionSummary;
     /** 仅 errored 使用：结构化执行错误发生时所在的阶段。failed 是断言 outcome，不带 phase。 */
     phase?: LifecyclePhase;
+    /** 仅 errored 且没有结构化主断言摘要（真正的执行错误，而非 assertion-unavailable）时携带：
+     *  `AttemptError.code` 原样透出,human 单行事实行拼成 `errored · <phase> · <code>`。 */
+    code?: string;
     /** 完整时间归属；attempt 形态同时投影上面的 phase，run 形态保留共享 timing node。 */
     origin?: TimingOrigin;
+    /** 该 attempt 的 `AttemptRecord.facts` 键数；缺失或为空对象时省略。结束反馈的 FAILURES 面板
+     *  只据此给一条行内提示(有才提示),完整键值表留给 `niceeval show @<locator>`。 */
+    factsCount?: number;
 }
 /** 带发生时间的失败通知；复用失败以 FailureDetail 静态进入 plan，不伪装成刚发生的事件。 */
 export interface FailureNotice extends FailureDetail {
@@ -1479,6 +1498,7 @@ export type DurableFeedbackEvent = {
     reason: string;
     assertion?: PrimaryAssertionSummary;
     phase?: LifecyclePhase;
+    code?: string;
     origin?: TimingOrigin;
 } | {
     type: "diagnostic";

package/dist/sample/index.d.ts

@@ -100,12 +100,3 @@ export declare function isNewerSnapshotPlacement(a: Pick<Run, "startedAt" | "dir
  * 包内使用,不进公共 barrel。
  */
 export declare function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[];
-/**
- * 时效标注(`↩` + 人话时距)的粒度选择:选粒度最大的单位,四舍五入。结构化形态是单源——
- * entity-lists 渲染面的紧凑时距("3d")与曾经的 stale-run message 用同一套阈值,
- * 阈值不写两份(docs/feature/reports/library.md「时效标注」)。
- */
-export declare function gapParts(fromIso: string, toIso: string): {
-    n: number;
-    unit: "second" | "minute" | "hour" | "day";
-};

package/dist/sample/index.js

@@ -384,21 +384,3 @@ export function filterExperiments(experiments, filter) {
     const matched = new Set(prefixes.flatMap((p) => matchExperimentSelector(ids, p)));
     return experiments.filter((exp) => matched.has(exp.id));
 }
-/**
- * 时效标注(`↩` + 人话时距)的粒度选择:选粒度最大的单位,四舍五入。结构化形态是单源——
- * entity-lists 渲染面的紧凑时距("3d")与曾经的 stale-run message 用同一套阈值,
- * 阈值不写两份(docs/feature/reports/library.md「时效标注」)。
- */
-export function gapParts(fromIso, toIso) {
-    const ms = Math.max(0, Date.parse(toIso) - Date.parse(fromIso));
-    const seconds = Math.round(ms / 1000);
-    if (seconds < 90)
-        return { n: seconds, unit: "second" };
-    const minutes = Math.round(seconds / 60);
-    if (minutes < 90)
-        return { n: minutes, unit: "minute" };
-    const hours = Math.round(minutes / 60);
-    if (hours < 36)
-        return { n: hours, unit: "hour" };
-    return { n: Math.round(hours / 24), unit: "day" };
-}

package/dist/sandbox/backend.d.ts

@@ -7,7 +7,7 @@ export type SandboxBackendSupport<T> = {
     readonly _tag: "Unsupported";
 };
 export interface SandboxBackendCapabilities {
-    /** Provider 能否兑现 CommandOptions.root 的提权语义；runner 私有基础设施按这项能力选择身份。 */
+    /** Provider 能否兑现 CommandOptions.user 的 root 覆盖；runner 私有基础设施按这项能力选择身份。 */
     readonly rootCommands: SandboxBackendSupport<true>;
     readonly appendLog: SandboxBackendSupport<(line: string) => Promise<void>>;
     readonly suspend: SandboxBackendSupport<() => Promise<void>>;

package/dist/sandbox/commands.d.ts

@@ -5,7 +5,7 @@ export type MaybePromise<T> = T | Promise<T>;
 export interface SandboxCommandOptions {
     readonly cwd?: string;
     readonly env?: Readonly<globalThis.Record<string, string>>;
-    readonly root?: boolean;
+    readonly user?: string;
     readonly timeoutMs?: number;
     readonly stdin?: string;
 }

package/dist/sandbox/compose.d.ts

@@ -175,8 +175,9 @@ export interface DockerComposeProviderMaterializationPlan {
     readonly evalId: string;
     readonly profile: string;
     readonly mainService: string;
-    readonly executionUser?: string;
+    readonly user?: string;
     readonly env: Readonly<Record<string, string>>;
+    readonly pathPrepend?: readonly string[];
     readonly projectName?: string;
     readonly collection: ComposeBuildCollection;
     readonly caseKey: import("./identity.ts").CaseKey;

package/dist/sandbox/docker.d.ts

@@ -43,10 +43,15 @@ export interface DockerSandboxOptions {
      */
     workdir?: string;
     /**
-     * 默认执行身份。`"image"` = 容器镜像声明的 USER(空则 root)——Terminal-Bench 等
-     * 需要改系统文件的 Compose main 必须用它;省略 = 内置非 root `SANDBOX_USER`。
+     * 覆盖整个 Sandbox 的默认执行身份;省略时沿用镜像 `USER`(未声明按 Docker 语义是 root)、
+     * Compose service `user:` 或其镜像 `USER`。
      */
-    executionUser?: "image" | string;
+    user?: string;
+    /**
+     * 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md
+     * 「PATH:受管变量与 pathPrepend」)。
+     */
+    pathPrepend?: readonly string[];
 }
 /** `stop()` 时是否销毁容器。Compose 主容器由资源组 `compose down` 回收,附着句柄只松绑。 */
 export type DockerSandboxReleaseMode = "destroy" | "detach";
@@ -71,10 +76,16 @@ export declare class DockerSandbox implements SandboxProviderBackend, SandboxReu
     private provisionToken?;
     private runIdentity?;
     private releaseMode;
-    /** 默认 docker exec User;`opts.root` 仍可提到 root。 */
-    private defaultUser;
+    /** 起点覆盖(factory `user`);省略 = 沿用镜像/Compose 声明的默认身份。 */
+    private readonly userOverride?;
+    /** factory `pathPrepend`;按声明顺序前置到受管 PATH,省略 = 空数组。 */
+    private readonly pathPrepend;
+    /** 下面三项由 `resolveDefaultIdentity()` 探测得出,构造期先给出安全占位值。 */
     private defaultHome;
     private defaultUserName;
+    private defaultIsRoot;
+    private npmGlobalDir;
+    private sandboxPath;
     readonly capabilities: {
         rootCommands: import("./backend.ts").SandboxBackendSupport<true>;
         appendLog: import("./backend.ts").SandboxBackendSupport<(line: string) => Promise<void>>;
@@ -89,6 +100,8 @@ export declare class DockerSandbox implements SandboxProviderBackend, SandboxReu
         setCommandDeadline: import("./backend.ts").SandboxBackendSupport<(deadlineAt?: number) => void>;
     };
     constructor(options?: DockerSandboxOptions);
+    /** 受管 PATH:`pathPrepend` 按声明顺序前置到 npm 全局 bin + 系统默认路径。 */
+    private managedPath;
     /** 复用下由池在每次借出时换成承接者自己的 deadline(见 sandbox/deadline.ts)。 */
     setCommandDeadline(deadlineAt?: number): void;
     /**
@@ -113,6 +126,14 @@ export declare class DockerSandbox implements SandboxProviderBackend, SandboxReu
     static create(options?: DockerSandboxOptions): Promise<DockerSandbox>;
     /** 拉镜像、起容器、装基础工具、备好工作区与 npm 前缀。 */
     private initialize;
+    /**
+     * 探测 Sandbox 默认执行身份(`this.userOverride` 未设置时即容器/镜像的默认身份)的
+     * uid、用户名与家目录:省略 `User` 字段的 exec 沿用容器默认身份,`$HOME` 由容器内
+     * `/etc/passwd` 解析,不在 runner 侧维护一张 UID → 家目录的映射表。
+     */
+    private resolveDefaultIdentity;
+    /** chown 目标:factory 覆盖时原样复用(接受 name / uid[:gid]),否则用探测出的用户名。 */
+    private chownTarget;
     /** 确保镜像在本地,缺了就拉。 */
     private ensureImage;
     /**
@@ -126,8 +147,8 @@ export declare class DockerSandbox implements SandboxProviderBackend, SandboxReu
     /** 容器短 ID(像 Docker CLI 那样取前 12 位)。 */
     get sandboxId(): string;
     /**
-     * 在容器里跑一条命令。默认以非 root 的 node 用户跑;`opts.root` 为真则以 root 跑
-     * (setup 装系统依赖用)。
+     * 在容器里跑一条命令。默认沿用 Sandbox 的默认执行身份(factory `user` 覆盖后的身份,
+     * 否则镜像声明的 USER);`opts.user` 只覆盖这一条命令。
      */
     runCommand(cmd: string, args?: readonly string[], opts?: CommandOptions): Promise<CommandResult>;
     /** 以 root 跑命令(provider 内部用:容器初始化、属主收敛)。 */

package/dist/sandbox/e2b.d.ts

@@ -19,6 +19,13 @@ interface E2BSandboxCreateOptions {
     readonly deadlineAt?: number;
     readonly runtime?: "node20" | "node24";
     readonly template?: string;
+    /** 覆盖整个 Sandbox 的默认执行身份;省略时沿用 template 的默认用户。 */
+    readonly user?: string;
+    /**
+     * 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md
+     * 「PATH:受管变量与 pathPrepend」)。
+     */
+    readonly pathPrepend?: readonly string[];
     readonly provisionToken?: string;
     /** 运行时已解析的实例寿命；bounded attempt 不能退回 E2B 的 SDK 默认值。 */
     readonly lifetime: E2BSandboxLifetime;
@@ -44,6 +51,10 @@ export declare class E2BSandbox implements SandboxProviderBackend, SandboxReuseC
     private retired;
     /** 已实际请求的实例寿命;复用下续期一律续到这个值(滑动窗口)。 */
     private lifetime;
+    /** 起点覆盖(factory `user`);省略 = 沿用 template 的默认用户。 */
+    private readonly userOverride?;
+    /** factory `pathPrepend`;按声明顺序前置到受管 PATH,省略 = 空数组。 */
+    private readonly pathPrepend;
     readonly sandboxId: string;
     private deadlineAt?;
     readonly capabilities: {

package/dist/sandbox/identity.d.ts

@@ -30,7 +30,12 @@ export interface CaseKeyInput {
     readonly composeBytes?: string;
     readonly overlayBytes?: string;
     readonly buildKeys: readonly BuildKey[];
-    readonly serviceImageDigests?: Readonly<globalThis.Record<string, string>>;
+    /**
+     * 无 build 的 Compose service 的声明 image ref(已 pin 时含 digest,未 pin 时是原始 tag 文本)。
+     * 只收声明值——不得填入 `docker inspect` 等本地 daemon 解析出的实际 digest,否则并行 docker
+     * 活动会让身份在两次独立规划之间漂移(见 memory/compose-case-identity-digest-flap.md)。
+     */
+    readonly serviceImageRefs?: Readonly<globalThis.Record<string, string>>;
     readonly bindMountDigests?: Readonly<globalThis.Record<string, string>>;
     /** env_file / config / secret 的非敏感内容(或内容摘要)。 */
     readonly configContents?: Readonly<globalThis.Record<string, string>>;

package/dist/sandbox/layer.d.ts

@@ -22,7 +22,8 @@ export interface DockerComposeSandboxOptions {
     readonly file: string | URL;
     readonly workspaceService: string;
     readonly build?: "on-demand" | "prebuilt";
-    readonly executionUser?: string;
+    /** 覆盖整个 Sandbox 的默认执行身份;省略时沿用 Compose service `user:` 或其镜像 `USER`。 */
+    readonly user?: string;
     readonly env?: Readonly<globalThis.Record<string, string>>;
     /** Compose 插值所需凭据；value 只进私有 runtime binding，identity 只认变量名与 revision。 */
     readonly credentialEnv?: Readonly<globalThis.Record<string, {
@@ -30,27 +31,50 @@ export interface DockerComposeSandboxOptions {
         readonly revision?: string;
     }>>;
     readonly lifetimeMs?: number;
+    /**
+     * 按序前置到受管 `PATH` 的目录;作用于本 Sandbox 内全部受管命令(agent 进程、两层 prepare、
+     * ensure/install),hooks 与子进程自然继承。PATH 本身是受管变量,不接受经 `env` 覆盖——
+     * 需要扩展 PATH 用这个字段(见 docs/feature/sandbox/library.md「PATH:受管变量与
+     * pathPrepend」)。省略 = 不改 PATH。
+     */
+    readonly pathPrepend?: readonly string[];
 }
 export interface DockerfileSandboxOptions {
     readonly context: string | URL;
     readonly dockerfile?: string;
     readonly buildArgs?: Readonly<globalThis.Record<string, string>>;
+    /** 覆盖整个 Sandbox 的默认执行身份;省略时沿用构建出的镜像 `USER`。 */
+    readonly user?: string;
     readonly lifetimeMs?: number;
+    /** 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md)。 */
+    readonly pathPrepend?: readonly string[];
 }
 export interface DockerImageSandboxOptions {
     readonly image: string;
+    /** 覆盖整个 Sandbox 的默认执行身份;省略时沿用镜像 `USER`(未声明按 Docker 语义是 root)。 */
+    readonly user?: string;
     readonly lifetimeMs?: number;
+    /** 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md)。 */
+    readonly pathPrepend?: readonly string[];
 }
 export interface E2BSandboxOptions {
     readonly template: string;
+    /** 覆盖整个 Sandbox 的默认执行身份;省略时沿用 template 的默认用户。 */
+    readonly user?: string;
     readonly lifetimeMs?: number;
+    /** 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md)。 */
+    readonly pathPrepend?: readonly string[];
 }
 export interface VercelSandboxOptions {
     readonly snapshotId: string;
     readonly lifetimeMs?: number;
+    /** 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md)。 */
+    readonly pathPrepend?: readonly string[];
 }
 export interface LocalSandboxOptions {
     readonly dir?: string;
+    /** 按序前置到受管 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md)。 */
+    readonly pathPrepend?: readonly string[];
 }
 export interface CustomProviderSandboxOptions {
     readonly name: string;
@@ -309,7 +333,7 @@ export declare function sandboxLayer(): SandboxLayer<"command-only">;
 /** @internal Provider factory 用它一次性绑定纯数据声明与 Effect planner。 */
 export declare function defineSandboxTemplate(definition: SandboxTemplateDefinition): SandboxLayer<"template-bearing">;
 export type SandboxExecutionUser = {
-    readonly _tag: "ImageDefault";
+    readonly _tag: "EnvironmentDefault";
 } | {
     readonly _tag: "Configured";
     readonly value: string;
@@ -324,34 +348,43 @@ export interface DockerComposeProviderPlan {
     readonly file: SandboxLocation;
     readonly workspaceService: string;
     readonly build: "on-demand" | "prebuilt";
-    readonly executionUser: SandboxExecutionUser;
+    readonly user: SandboxExecutionUser;
     readonly env: Readonly<Record<string, string>>;
     readonly collection: ComposeBuildCollection;
     readonly lifetime: SandboxProviderLifetime;
+    readonly pathPrepend: readonly string[];
 }
 export interface DockerfileProviderPlan {
     readonly context: SandboxLocation;
     readonly dockerfile: string;
     readonly buildArgs: Readonly<Record<string, string>>;
+    readonly user: SandboxExecutionUser;
     readonly build: DockerfileBuildIdentity;
     readonly buildKey: BuildKey;
     readonly platform: string;
     readonly lifetime: SandboxProviderLifetime;
+    readonly pathPrepend: readonly string[];
 }
 export interface DockerImageProviderPlan {
     readonly image: string;
+    readonly user: SandboxExecutionUser;
     readonly lifetime: SandboxProviderLifetime;
+    readonly pathPrepend: readonly string[];
 }
 export interface E2BProviderPlan {
     readonly template: string;
+    readonly user: SandboxExecutionUser;
     readonly lifetime: SandboxProviderLifetime;
+    readonly pathPrepend: readonly string[];
 }
 export interface VercelProviderPlan {
     readonly snapshotId: string;
     readonly lifetime: SandboxProviderLifetime;
+    readonly pathPrepend: readonly string[];
 }
 export interface LocalProviderPlan {
     readonly directory: string;
+    readonly pathPrepend: readonly string[];
 }
 export interface CustomProviderPlan {
     readonly name: string;

package/dist/sandbox/local.d.ts

@@ -7,6 +7,11 @@ export interface LocalSandboxOptions {
     timeout?: number;
     /** attempt deadline 的截止时刻(epoch ms);单条命令按剩余量取上限(见 deadline.ts)。 */
     deadlineAt?: number;
+    /**
+     * 按序前置到宿主 `PATH` 的目录;省略 = 不改 PATH(见 docs/feature/sandbox/library.md
+     * 「PATH:受管变量与 pathPrepend」)。
+     */
+    pathPrepend?: readonly string[];
     /**
      * 内部测试用:覆盖「当前目录」的解析起点(省略 `dir` 时向上找 git 根、显式 `dir` 时的相对路径
      * 基准都从它算)。生产路径(runtime.ts 的 provider materializer)从不传这个字段,恒用
@@ -26,6 +31,8 @@ export declare class LocalSandbox implements SandboxProviderBackend {
     private readonly timeout?;
     private deadlineAt?;
     private readonly ledgerBase;
+    /** factory `pathPrepend`;按声明顺序前置到宿主 PATH,省略 = 空数组。 */
+    private readonly pathPrepend;
     readonly capabilities: {
         rootCommands: import("./backend.ts").SandboxBackendSupport<never>;
         appendLog: import("./backend.ts").SandboxBackendSupport<never>;
@@ -38,6 +45,8 @@ export declare class LocalSandbox implements SandboxProviderBackend {
     static create(options?: LocalSandboxOptions): Promise<LocalSandbox>;
     /** 复用下由池在每次借出时换成承接者自己的 deadline(见 sandbox/deadline.ts)。 */
     setCommandDeadline(deadlineAt?: number): void;
+    /** 宿主 env:`process.env` 叠加 `pathPrepend` 前置后的 PATH,`opts.env` 仍可覆盖任意键(含 PATH)。 */
+    private hostEnv;
     runCommand(cmd: string, args?: readonly string[], opts?: CommandOptions): Promise<CommandResult>;
     runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
     runCommandOrThrow(cmd: string, args?: readonly string[], opts?: CommandOptions): Promise<SuccessfulCommandResult>;